:version: 1.4.1

ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[]

= Client Dependencies Gradle Plugin

This Gradle plugin allows you to declare client side dependencies in build.gradle from bower, npm, yarn 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.

The original plugin was not compatible with Gradle versions 3 or higher due to a breaking change in the String wrapping packages. It has been updated and pushed to the Gradle Plugin repository for usage.

== Getting Started

=== Gradle 3 and higher

[source,gradle,subs='attributes']

plugins { id "com.magnetichq.client-dependencies" version "2.0.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.

WARNING: The following example shows the use of several different types of registries, this works but it's best to stick to a single registry (NPM is recommended).

[source,gradle,subs='attributes']

clientDependencies { bower { 'jquery'('2.0.0') // <1> } npm { 'bootstrap'('3.3.6', exclude: 'jquery') // <2> 'restangular'('1.5.1', 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' } } yarn { 'angular'('1.5.8') // <7> } }

<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 to 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 <7> Installs angular from Yarn's registry 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: https://docs.gradle.org/current/dsl/org.gradle.api.tasks.Copy.html[Gradle Copy]. === Default copy task The default settings for the copy task are as follows: [source,gradle,subs='attributes'] ---- clientDependencies { fileExtensions = ['css', 'js', 'eot', 'svg', 'ttf', 'woff', 'woff2', 'ts', 'jpg', 'jpeg', 'png', 'gif'] // <1> releaseFolders = ['dist', 'release'] // <2> copyIncludes = [] // <3> copyExcludes = ['**/*.min.js', '**/*.min.css', '**/*.map', '**/Gruntfile.js', 'gulpfile.js', 'source/**'] // <4> } ---- <1> Default included file extensions <2> Default 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/{asterisk}{asterisk}/{asterisk}.js` instead of `{asterisk}{asterisk}/{asterisk}.js`) <3> Default includes to append to the end of the copy task <4> Default excludes to append to the end of the copy task You can add to the default values listed above by using the following methods: [source,gradle,subs='attributes'] ---- clientDependencies { fileExtensions 'ts' // <1> releaseFolders 'lib' // <2> copyIncludes '**' // <3> copyExcludes 'index.js' // <4> } ---- <1> Adds the file extension (`ts`) to default fileExtensions <2> Adds a release folders (`lib`) to the default release folder list <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 copy task (this will then completely ignores the settings above) [source,gradle,subs='attributes'] ---- 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: [source,gradle,subs='attributes'] ---- 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). [source,gradle,subs='attributes'] ---- 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. [source,gradle,subs='attributes'] ---- clientDependencies { installDir = 'src/assets/vendor' // <1> cacheDir = 'build/client-cache/' // <2> userAgent = 'client-dependencies-gradle' // <3> useGlobalCache = true // <4> checkDownloads = true // <5> threadPoolSize = 10 // <6> } ---- <1> Location that dependencies are installed to <2> Location of the local project cache <3> User agent used when making web requests <4> Whether the global caches for bower and npm are searched when resolving dependencies <5> Whether downloads are checked and verified <6> Size of thread pool used when downloading and installing dependencies == Special for Bower repositories Github credentials can be set in the `clientDependencies` block: [source,gradle,subs='attributes'] ---- clientDependencies { githubUsername = project.hasProperty('githubUsername') ? project.githubUsername : '' // <1> githubPassword = project.hasProperty('githubPassword') ? project.githubPassword : '' // <2> } ---- <1> Your Github Username <2> Your Github password or if you use two factor login (and you really should), your personal access token (see: https://github.com/settings/tokens) If you don't want to use your username and password you can obtain Github token here https://github.com/settings/tokens/new and use it this way: [source,gradle,subs='attributes'] ---- clientDependencies { githubToken = project.hasProperty('githubToken') ? project.githubToken : '' } ---- CAUTION: that it is important never to store your Github credentials in your `build.gradle` file. Instead you can set the values in `~/.gradle/gradle.properties` where they are for your eyes only. == Contributors Thank you to the following people who have made significant contributions to this project: * Janne Ruuttunen - link:https://github.com/jruuttun[@jruuttun] * Søren Berg Glasius - link:https://github.com/sbglasius[@sbglasius] * Eric Helgeson - link:https://github.com/erichelgeson[@erichelgeson] * Martin Grześlowski - link:https://github.com/magx2[@magx2]