The Node Gradle plugin lets you run Node.js and NPM as part of your build.
The plugin has been successfully tested with Gradle 4.10.2.
Usage
To use the plugin, include it in your build script:
buildscript {
dependencies {
classpath group: "com.liferay", name: "com.liferay.gradle.plugins.node", version: "4.6.18"
}
repositories {
maven {
url "https://repository-cdn.liferay.com/nexus/content/groups/public"
}
}
}
apply plugin: "com.liferay.node"
Project Extension
The Node Gradle plugin exposes the following properties through the extension
named node:
| Property Name | Type | Default Value | Description |
|---|---|---|---|
download | boolean | true | Whether to download and use a local and isolated Node.js distribution instead of the one installed in the system. |
global | boolean | false | Whether to use a single Node.js installation for the whole multi-project build. This reduces the time required to unpack the Node.js distribution and the time required to download NPM packages thanks to a shared packages cache. If download is false, this property has no effect. |
nodeDir | File | If Otherwise: | The directory where the Node.js distribution is unpacked. If download is false, this property has no effect. |
nodeUrl | String | "http://nodejs.org/dist/v${node.nodeVersion}/node-v${node.nodeVersion}-${platform}-x${bitMode}.${extension}" | The URL of the Node.js distribution to download. If download is false, this property has no effect. |
nodeVersion | String | "5.5.0" | The version of the Node.js distribution to use. If download is false, this property has no effect. |
npmArgs | List<String> | [] | The arguments added automatically to every task of type ExecuteNpmTask. |
npmUrl | String | "https://registry.npmjs.org/npm/-/npm-${node.npmVersion}.tgz" | The URL of the NPM version to download. If download is false, this property has no effect. |
npmVersion | String | null | The version of NPM to use. If null, the version of NPM embedded inside the Node.js distribution is used. If download is false, this property has no effect. |
It is possible to override the default value of the download property by
setting the nodeDownload project property. For example, this can be done via
command line argument:
./gradlew -PnodeDownload=false npmInstall
The same extension exposes the following methods:
| Method | Description |
|---|---|
NodeExtension npmArgs(Iterable<?> npmArgs) | Adds arguments to automatically add to every task of type ExecuteNpmTask. |
NodeExtension npmArgs(Object... npmArgs) | Adds arguments to automatically add to every task of type ExecuteNpmTask. |
The properties of type File support any type that can be resolved by
project.file.
Moreover, it is possible to use Closures and Callables as values for String,
to defer evaluation until execution.
Please note that setting the global property of the node extension via the
command line is not supported. It can only be set via Gradle script, which can
be done by adding the following code to the build.gradle file in the root of
a project (e.g., Liferay Workspace):
allprojects {
plugins.withId("com.liferay.node") {
node.global = true
}
}
Tasks
The plugin adds a series of tasks to your project:
| Name | Depends On | Type | Description |
|---|---|---|---|
cleanNPM | - | Delete | Deletes the node_modules directory, the npm-shrinkwrap.json file and the package-lock.json files from the project, if present. |
downloadNode | - | DownloadNodeTask | Downloads and unpacks the local Node.js distribution for the project. If node.download is false, this task is disabled. |
npmInstall | downloadNode | NpmInstallTask | Runs npm install to install the dependencies declared in the project’s package.json file, if present. By default, the task is configured to run npm install two more times if it fails. |
npmRun${script} | npmInstall | ExecuteNpmTask | Runs the ${script} NPM script. |
npmPackageLock | cleanNPM, npmInstall | DefaultTask | Deletes the NPM files and runs npm install to install the dependencies declared in the project’s package.json file, if present. |
npmShrinkwrap | cleanNPM, npmInstall | NpmShrinkwrapTask | Locks down the versions of a package’s dependencies in order to control which dependency versions are used. |
DownloadNodeTask
The purpose of this task is to download and unpack a Node.js distribution.
Task Properties
| Property Name | Type | Default Value | Description |
|---|---|---|---|
nodeDir | File | null | The directory where the Node.js distribution is unpacked. |
nodeExeUrl | String | null | The URL of node.exe to download when on Windows. |
nodeUrl | String | null | The URL of the Node.js distribution to download. |
npmUrl | String | null | The URL of the NPM version to download. |
The properties of type File support any type that can be resolved by project.file.
Moreover, it is possible to use Closures and Callables as values for the
String properties, to defer evaluation until task execution.
ExecuteNodeTask
This is the base task to run Node.js in a Gradle build. All tasks of type
ExecuteNodeTask automatically depend on downloadNode.
Task Properties
| Property Name | Type | Default Value | Description |
|---|---|---|---|
args | List<Object> | [] | The arguments for the Node.js invocation. |
command | String | "node" | The file name of the executable to invoke. |
environment | Map<Object, Object> | [] | The environment variables for the Node.js invocation. |
inheritProxy | boolean | true | Whether to set the http_proxy, https_proxy, and no_proxy environment variables in the Node.js invocation based on the values of the system properties https.proxyHost, https.proxyPort, https.proxyUser, https.proxyPassword, https.nonProxyHosts, https.proxyHost, https.proxyPort, https.proxyUser, https.proxyPassword, and https.nonProxyHosts. If these environment variables are already set, their values will not be overwritten. |
nodeDir | File | If Otherwise: | The directory that contains the executable to invoke. If null, the executable must be available in the system PATH. |
npmInstallRetries | int | 0 | The number of times the node_modules is deleted, the NPM cached data is verified (npm cache verify), and npm install is retried in case the Node.js invocation defined by this task fails. This can help solving corrupted node_modules directories by re-downloading the project’s dependencies. |
workingDir | File | project.projectDir | The working directory to use in the Node.js invocation. |
The properties of type File support any type that can be resolved by
project.file.
Moreover, it is possible to use Closures and Callables as values for the
String properties to defer evaluation until task execution.
Task Methods
| Method | Description |
|---|---|
ExecuteNodeTask args(Iterable<?> args) | Adds arguments for the Node.js invocation. |
ExecuteNodeTask args(Object... args) | Adds arguments for the Node.js invocation. |
ExecuteNodeTask environment(Map<?, ?> environment) | Adds environment variables for the Node.js invocation. |
ExecuteNodeTask environment(Object key, Object value) | Adds an environment variable for the Node.js invocation. |
ExecuteNodeScriptTask
The purpose of this task is to execute a Node.js script. Tasks of type
ExecuteNodeScriptTask extend ExecuteNodeTask.
Task Properties
| Property Name | Type | Default Value | Description |
|---|---|---|---|
scriptFile | File | null | The Node.js script to execute. |
The properties of type File support any type that can be resolved by
project.file.
ExecuteNpmTask
The purpose of this task is to execute an NPM command. Tasks of type
ExecuteNpmTask extend ExecuteNodeScriptTask with
the following properties set by default:
| Property Name | Default Value |
|---|---|
command | If Otherwise: |
scriptFile | If Otherwise: |
Task Properties
| Property Name | Type | Default Value | Description |
|---|---|---|---|
cacheConcurrent | boolean | If Otherwise: | Whether to run this task concurrently, in case the version of NPM in use supports multiple concurrent accesses to the same cache directory. |
cacheDir | File | If Otherwise: | The location of NPM’s cache directory. It sets the --cache argument. Leave the property null to keep the default value. |
logLevel | String | Value to mirror the log level set in the task’s logger object. | The NPM log level. It sets the –loglevel argument. |
production | boolean | false | Whether to run in production mode during the NPM invocation. It sets the --production argument. |
progress | boolean | true | Whether to show a progress bar during the NPM invocation. It sets the --progress argument. |
registry | String | null | The base URL of the NPM package registry. It sets the --registry argument. Leave the property null or empty to keep the default value. |
The properties of type File support any type that can be resolved by project.file.
Moreover, it is possible to use Closures and Callables as values for the
String properties, to defer evaluation until task execution.
DownloadNodeModuleTask
The purpose of this task is to download a Node.js package. The packages are
downloaded in the ${workingDir}/node_modules directory, which is equal, by
default, to the node_modules directory of the project. Tasks of type
DownloadNodeModuleTask extend ExecuteNpmTask in order to
execute the command npm install ${moduleName}@${moduleVersion}.
DownloadNodeModuleTask instances are automatically disabled if the project’s
package.json file already lists a module with the same name in its
dependencies or devDependencies object.
Task Properties
| Property Name | Type | Default Value | Description |
|---|---|---|---|
moduleName | String | null | The name of the Node.js package to download. |
moduleVersion | String | null | The version of the Node.js package to download. |
It is possible to use Closures and Callables as values for the String
properties, to defer evaluation until task execution.
NpmInstallTask
Purpose of these tasks is to install the dependencies declared in a
package.json file. Tasks of type NpmInstallTask extend
ExecuteNpmTask in order to run the command npm install.
NpmInstallTask instances are automatically disabled if the package.json file
does not declare any dependency in the dependency or devDependencies object.
Task Properties
| Property Name | Type | Default Value | Description |
|---|---|---|---|
nodeModulesCacheDir | File | null | The directory where The This feature is not available if the |
nodeModulesCacheNativeSync | boolean | true | Whether to use rsync (on Linux/macOS) or robocopy (on Windows) to cache and restore the node_modules directory. If nodeModulesCacheDir is not set, this property has no effect. |
nodeModulesDigestFile | File | null | If this property is set, the content of the project’s This feature is not available if the |
removeShrinkwrappedUrls | boolean | true if the registry property has a value, false otherwise. | Whether to temporarily remove all the hard-coded URLs in the from and resolved fields of the npm-shinkwrap.json file before invoking npm install. This way, it is possible to force NPM to download all dependencies from a custom registry declared in the registry property. |
useNpmCI | boolean | false | Whether to run npm ci instead of npm install. If the package-lock.json file does not exist, this property has no effect. |
The properties of type File support any type that can be resolved by project.file.
NpmShrinkwrapTask
The purpose of this task is to lock down the versions of a package’s
dependencies so that you can control exactly which dependency versions are used
when your package is installed. Tasks of type NpmShrinkwrapTask extend
ExecuteNpmTask to execute the command
npm shrinkwrap.
The generated npm-shrinkwrap.json file is automatically sorted and formatted,
so it’s easier to see the changes with the previous version.
NpmShrinkwrapTask instances are automatically disabled if the package.json
file does not exist.
Task Properties
| Property Name | Type | Default Value | Description |
|---|---|---|---|
excludedDependencies | List<String> | [] | The package names to exclude from the generated npm-shrinkwrap.json file. |
includeDevDependencies | boolean | true | Whether to include the package’s devDependencies. It sets the --dev argument. |
It is possible to use Closures and Callables as values for the String
properties to defer evaluation until task execution.
Task Methods
| Method | Description |
|---|---|
NpmShrinkwrapTask excludeDependencies(Iterable<?> excludedDependencies) | Adds package names to exclude from the generated npm-shrinkwrap.json file. |
NpmShrinkwrapTask excludeDependencies(Object... excludedDependencies) | Adds package names to exclude from the generated npm-shrinkwrap.json file. |
PublishNodeModuleTask
The purpose of this task is to publish a package to the
NPM registry. Tasks of type PublishNodeModuleTask
extend ExecuteNpmTask in order to execute the command
npm publish.
These tasks generate a new temporary package.json file in the directory
assigned to the workingDir property; then the npm publish
command is executed. If the package.json file in that location does not exist,
the one in the root of the project directory (if found) is copied; otherwise, a
new file is created.
The package.json is then processed by adding the values provided by the task
properties, if not already present in the file itself. It is still possible to
override one or more fields of the package.json file with the values provided
by the task properties by adding one or more keys (e.g., "version") to the
overriddenPackageJsonKeys property.
Task Properties
| Property Name | Type | Default Value | Description |
|---|---|---|---|
moduleAuthor | String | null | The value of the author field in the generated package.json file. |
moduleBugsUrl | String | null | The value of the bugs.url field in the generated package.json file. |
moduleDescription | String | project.description | The value of the description field in the generated package.json file. |
moduleKeywords | List<String> | [] | The value of the keywords field in the generated package.json file. |
moduleLicense | String | null | The value of the license field in the generated package.json file. |
moduleMain | String | null | The value of the main field in the generated package.json file. |
moduleName | String | Name based on osgiHelper.bundleSymbolicName: for example, if osgiHelper.bundleSymbolicName is "com.liferay.gradle.plugins.node", the default value for the moduleName property is "liferay-gradle-plugins-node". | The value of the name field in the generated package.json file. |
moduleRepository | String | null | The value of the repository field in the generated package.json file. |
moduleVersion | String | project.version | The value of the version field in the generated package.json file. |
npmEmailAddress | String | null | The email address of the npmjs.com user that publishes the package. |
npmPassword | String | null | The password of the npmjs.com user that publishes the package. |
npmUserName | String | null | The name of the npmjs.com user that publishes the package. |
overriddenPackageJsonKeys | Set<String> | [] | The field values to override in the generated package.json file. |
Task Methods
| Method | Description |
|---|---|
PublishNodeModuleTask overriddenPackageJsonKeys(Iterable<String> overriddenPackageJsonKeys) | Adds field values to override in the generated package.json file. |
PublishNodeModuleTask overriddenPackageJsonKeys(String... overriddenPackageJsonKeys) | Adds field values to override in the generated package.json file. |
npmRun$ Task
For each script declared in the
package.json file of the project, one task npmRun${script} of type
ExecuteNpmTask is added. Each of these tasks is
automatically configured with sensible defaults:
| Property Name | Default Value |
|---|---|
args | ["run-script", "${script}"] |
If the java
plugin is applied and the package.json file declares a script named "build",
the script is executed before the classes task but after the
processResources
task.
If the lifecycle-base
plugin is applied and the package.json file declares a script named test,
the script is executed when running the check task.