Node Gradle Plugin

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 NameTypeDefault ValueDescription
downloadbooleantrueWhether to download and use a local and isolated Node.js distribution instead of the one installed in the system.
globalbooleanfalseWhether 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.
nodeDirFile

If global is true: "${rootProject.buildDir}/node"

Otherwise: "${project.buildDir}/node"

The directory where the Node.js distribution is unpacked. If download is false, this property has no effect.
nodeUrlString"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.
nodeVersionString"5.5.0"The version of the Node.js distribution to use. If download is false, this property has no effect.
npmArgsList<String>[]The arguments added automatically to every task of type ExecuteNpmTask.
npmUrlString"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.
npmVersionStringnullThe 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:

MethodDescription
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:

NameDepends OnTypeDescription
cleanNPM-DeleteDeletes the node_modules directory, the npm-shrinkwrap.json file and the package-lock.json files from the project, if present.
downloadNode-DownloadNodeTaskDownloads and unpacks the local Node.js distribution for the project. If node.download is false, this task is disabled.
npmInstalldownloadNodeNpmInstallTaskRuns 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}npmInstallExecuteNpmTaskRuns the ${script} NPM script.
npmPackageLockcleanNPM, npmInstallDefaultTaskDeletes the NPM files and runs npm install to install the dependencies declared in the project’s package.json file, if present.
npmShrinkwrapcleanNPM, npmInstallNpmShrinkwrapTaskLocks 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 NameTypeDefault ValueDescription
nodeDirFilenullThe directory where the Node.js distribution is unpacked.
nodeExeUrlStringnullThe URL of node.exe to download when on Windows.
nodeUrlStringnullThe URL of the Node.js distribution to download.
npmUrlStringnullThe 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 NameTypeDefault ValueDescription
argsList<Object>[]The arguments for the Node.js invocation.
commandString"node"The file name of the executable to invoke.
environmentMap<Object, Object>[]The environment variables for the Node.js invocation.
inheritProxybooleantrueWhether 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.
nodeDirFile

If node.download is true: node.nodeDir

Otherwise: null

The directory that contains the executable to invoke. If null, the executable must be available in the system PATH.
npmInstallRetriesint0The 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.
workingDirFileproject.projectDirThe 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

MethodDescription
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 NameTypeDefault ValueDescription
scriptFileFilenullThe 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 NameDefault Value
command

If nodeDir is null: "npm"

Otherwise: "node"

scriptFile

If nodeDir is null: null

Otherwise: "${nodeDir}/lib/node_modules/npm/bin/npm-cli.js" or "${nodeDir}/node_modules/npm/bin/npm-cli.js" on Windows.

Task Properties

Property NameTypeDefault ValueDescription
cacheConcurrentboolean

If node.npmVersion is greater than or equal to 5.0.0, or node.nodeVersion is greater than or equal to 8.0.0: true

Otherwise: false

Whether to run this task concurrently, in case the version of NPM in use supports multiple concurrent accesses to the same cache directory.
cacheDirFile

If nodeDir is null, or node.npmVersion is greater than or equal to 5.0.0, or node.nodeVersion is greater than or equal to 8.0.0: null

Otherwise: "${nodeDir}/.cache"

The location of NPM’s cache directory. It sets the --cache argument. Leave the property null to keep the default value.
logLevelStringValue to mirror the log level set in the task’s logger object.The NPM log level. It sets the –loglevel argument.
productionbooleanfalseWhether to run in production mode during the NPM invocation. It sets the --production argument.
progressbooleantrueWhether to show a progress bar during the NPM invocation. It sets the --progress argument.
registryStringnullThe 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 NameTypeDefault ValueDescription
moduleNameStringnullThe name of the Node.js package to download.
moduleVersionStringnullThe 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 NameTypeDefault ValueDescription
nodeModulesCacheDirFilenull

The directory where node_modules directories are cached. By setting this property, it is possible to cache the node_modules directory of a project and avoid unnecessary invocations of npm install, useful especially in Continuous Integration environments.

The node_modules directory is cached based on the content of the project’s package-lock.json (or npm-shrinkwrap.json, or package.json if absent). Therefore, if NpmInstallTask tasks in multiple projects are configured with the same nodeModulesCacheDir, and their package-lock.json, npm-shrinkwrap.json or package.json declare the same dependencies, their node_modules caches will be shared.

This feature is not available if the com.liferay.cache plugin is applied.

nodeModulesCacheNativeSyncbooleantrueWhether 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.
nodeModulesDigestFileFilenull

If this property is set, the content of the project’s package-lock.json (or npm-shrinkwrap.json, or package.json if absent) is checked with the digest from the node_modules directory. If the digests match, do nothing. If the digests don’t match, the node_modules directory is deleted before running npm install.

This feature is not available if the com.liferay.cache plugin is applied or if the property nodeModulesCacheDir is set.

removeShrinkwrappedUrlsbooleantrue 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.
useNpmCIbooleanfalseWhether 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 NameTypeDefault ValueDescription
excludedDependenciesList<String>[]The package names to exclude from the generated npm-shrinkwrap.json file.
includeDevDependenciesbooleantrueWhether 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

MethodDescription
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 NameTypeDefault ValueDescription
moduleAuthorStringnullThe value of the author field in the generated package.json file.
moduleBugsUrlStringnullThe value of the bugs.url field in the generated package.json file.
moduleDescriptionStringproject.descriptionThe value of the description field in the generated package.json file.
moduleKeywordsList<String>[]The value of the keywords field in the generated package.json file.
moduleLicenseStringnullThe value of the license field in the generated package.json file.
moduleMainStringnullThe value of the main field in the generated package.json file.
moduleNameStringName 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.
moduleRepositoryStringnullThe value of the repository field in the generated package.json file.
moduleVersionStringproject.versionThe value of the version field in the generated package.json file.
npmEmailAddressStringnullThe email address of the npmjs.com user that publishes the package.
npmPasswordStringnullThe password of the npmjs.com user that publishes the package.
npmUserNameStringnullThe name of the npmjs.com user that publishes the package.
overriddenPackageJsonKeysSet<String>[]The field values to override in the generated package.json file.

Task Methods

MethodDescription
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 NameDefault 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.

« Maven Plugin Builder Gradle PluginREST Builder Gradle Plugin »
Was this article helpful?
0 out of 0 found this helpful