README.adoc

Client Dependencies Gradle Plugin

This Gradle plugin allows you to declare client side dependencies in build.gradle from bower, npm or git and with a much clearer dependencies resolution model. This plugin queries the registries directly so it doesn’t require or install node, npm or bower.

Getting Started

Gradle 2.0

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'com.craigburke.gradle:client-dependencies:1.2.0'
    }
}

apply plugin: 'com.craigburke.client-dependencies'

Gradle 2.1 and higher

plugins {
    id 'com.craigburke.client-dependencies' version '1.2.0'
}

Tasks

The plugin adds the following tasks to your build:

Task	Description
clientInstall	Installs all the client dependencies you have set in your build.gradle
clientRefresh	Refreshes client dependencies (if you add or modify your configuration)
clientClean	Removes client dependencies and clears the cache
clientReport	Prints a report of all dependencies and the resolved versions

Declaring dependencies

You can specify dependencies from different sources (npm, bower or git) and control which files are included in your project by using the DSL shown below.

clientDependencies {
    bower {
        'jquery'('2.0.0') // <1>
    }
    npm {
        'bootstrap'('3.3.6', exclude: 'jquery') // <2>
        'restangular'('1.5.0', transitive: false) // <3>
        'angular-animate'('1.5.0', into: 'angular/modules') // <4>
        'animate.css'('1.0.0', url:'daneden/animate.css') // <5>
        'angular-ui-bootstrap'('1.3.x', from:'dist') { // <6>
            include 'ui-bootstrap-tpls.js'
        }
    }
}

1. Installs jquery from bower and into the location (src/assets/vendor/jquery) using the default copy settings

2. Installs bootstrap from npm and excludes the dependency jquery

3. Installs restangular from npm but doesn’t include any child dependencies

4. Changing the destination path using the into property. This is relative ot the install path meaning this would install to the location src/assets/vendor/angular/modules.

5. Use the url property to use a github repo as a dependency source (expands to https://www.github.com/danedan/animate.css.git). A full URL reference any git repository will also work here.

6. The from property allows you to copy code only from a certain subfolder

Tip	If you update your config and it doesn’t seem to be taking effect, try running the clientRefresh task.

The copy task

The files are copied using the DSL of Gradle’s copy task. See: Gradle Copy.

Default copy task

When the files for a dependency are copied to the install directory, the plugin uses reasonable defaults for what to include and exclude. This default behavior can be controlled with the following properties:

clientDependencies {
    fileExtensions 'ts' // <1>
    releaseFolders 'lib' // <2>
    copyIncludes '**' // <3>
    copyExcludes '**' // <4>
}

1. Add additional file extension to default include

2. Adds a release folders to look for. If a folder by this name is found then the file extension includes are relative to this folder. (ex dist/**/*.js instead of **/*.js)

3. Additional includes to append to the end of the copy task

4. Additional excludes to append to the end of the copy task

You can also completely override the default values for each of the properties above:

clientDependencies {
    fileExtensions = ['js', 'css', 'ts'] // <1>
    releaseFolders = ['release', 'dist', 'lib'] // <2>
    copyIncludes = ['**'] // <3>
    copyExcludes = ['**/*.txt'] // <4>
}

1. Sets default file extensions to include

2. Sets release folders to look for

3. Sets includes to append to the end of the copy task

4. Sets excludes to append to the end of the copy task

You can also completely override the default copy task (which also ignores the settings above)

clientDependencies {
    defaultCopy = {
        include '**'
        exclude '**/*.less', '**/*.sass'
    }
}

Overriding the copy task for an individual dependency

By passing a closure as the last argument of a dependency declaration you have full control of what files get copied and where they get copied to.

For example:

clientDependencies {
    npm {
        'bootstrap'('3.3.6') {
            include 'dist/**'
            exclude '**/*.min.*', '**/*.map', '**/npm.js'
            eachFile { it.path -= 'dist/' }
        }
    }
}

Registering custom registry

By default two registries named npm and bower are installed. You can either override these or register new custom registries. This allows you to also use it to separate out dependencies (production versus devevelopment dependencies for example).

clientDependencies {
    registry 'npmLocal', type:'npm', url:'http://www.example.com/npm/'
    registry 'npmDev', type: 'npm', url:'http://www.example.com/npm/'
    registry 'bowerLocal', type:'bower', url:'http://www.example.com/bower/'

    npmLocal {
        'bootstrap'('3.3.6')
        'myJSLib'('1.0.0')
    }

    npmDev {
        'lodash'('2.4.1')
        'grunt'('1.0.0')
        'grunt-contrib-clean'('~0.6.0')
        'colors'('^0.6.2')
    }

    bowerLocal {
        'jquery'('2.0.0')
        'myBowerJSLib'('1.0.0')
     }
}

Additional Properties

What follows are additional configuration options. With the possible exception of installDir you typically won’t need to set any of these options.

clientDependencies {
    installDir = 'src/assets/vendor' // <1>
    cacheDir = 'build/client-cache/' // <2>
    useGlobalCache = true // <3>
    checkDownloads = true // <4>
    threadPoolSize = 10 // <5>
}

1. Location that dependencies are installed to

2. Location of the local project cache

3. Whether the global caches for bower and npm are searched when resolving dependencies

4. Whether downloads are checked and verified

5. Size of thread pool used when downloading and installing dependencies

Contributors

Thank you to the following people who have made significant contributions to this project:

• Janne Ruuttunen - @jruuttun