Configuration

Plugin DSL

The frontend extension is the implementation of the plugin DSL, and holds all settings. 

frontend {
    nodeDistributionProvided = false
    nodeVersion = '20.18.0'
    nodeDistributionUrlRoot = 'https://nodejs.org/dist/'
    nodeDistributionUrlPathPattern = 'vVERSION/node-vVERSION-ARCH.TYPE'
    nodeDistributionServerUsername = 'username'
    nodeDistributionServerPassword = 'password'
    nodeInstallDirectory = project.layout.projectDirectory.dir("node")
    corepackVersion = 'latest'

    installScript = 'install'
    cleanScript = 'run clean'
    assembleScript = 'run assemble'
    checkScript = 'run check'
    publishScript = 'run publish'

    packageJsonDirectory = projectDir
    httpsProxyHost = '127.0.0.1'
    httpsProxyPort = 443
    httpsProxyUsername = 'username'
    httpsProxyPassword = 'password'
    httpProxyHost = '127.0.0.1'
    httpProxyPort = 80
    httpProxyUsername = 'username'
    httpProxyPassword = 'password'
    maxDownloadAttempts = 1
    retryHttpStatuses = [408, 429, 500, 502, 503, 504]
    retryInitialIntervalMs = 1000
    retryIntervalMultiplier = 2.0
    retryMaxIntervalMs = 30000
    verboseModeEnabled = false
    cacheDirectory = project.layout.projectDirectory.dir(".frontend-gradle-plugin")
}
frontend {
    nodeDistributionProvided.set(false)
    nodeVersion.set("20.18.0")
    nodeDistributionUrlRoot.set("https://nodejs.org/dist/")
    nodeDistributionUrlPathPattern.set("vVERSION/node-vVERSION-ARCH.TYPE")
    nodeDistributionServerUsername.set("username")
    nodeDistributionServerPassword.set("password")
    nodeInstallDirectory.set(project.layout.projectDirectory.dir("node"))
    corepackVersion.set("latest")

    installScript.set("install")
    cleanScript.set("run clean")
    assembleScript.set("run assemble")
    checkScript.set("run check")
    publishScript.set("run publish")

    packageJsonDirectory.set(project.layout.projectDirectory)
    httpsProxyHost.set("127.0.0.1")
    httpsProxyPort.set(443)
    httpsProxyUsername.set("username")
    httpsProxyPassword.set("password")
    httpProxyHost.set("127.0.0.1")
    httpProxyPort.set(80)
    httpProxyUsername.set("username")
    httpProxyPassword.set("password")
    maxDownloadAttempts.set(1)
    retryHttpStatuses.set(setOf(408, 429, 500, 502, 503, 504))
    retryInitialIntervalMs.set(1000)
    retryIntervalMultiplier.set(2.0)
    retryMaxIntervalMs.set(30000)
    verboseModeEnabled.set(false)
    cacheDirectory.set(project.layout.projectDirectory.dir(".frontend-gradle-plugin"))
}

Properties

Node.js settings

# Property nodeDistributionProvided ↑

Whether the Node.js distribution is already provided, and shall not be downloaded.

  1. When false, task installNode downloads a Node.js distribution using properties nodeVersion, nodeDistributionUrlRoot, nodeDistributionUrlPathPattern, and installs it in the directory pointed by the nodeInstallDirectory property.

  2. When true, the plugin relies on the directory pointed by the nodeInstallDirectory property to locate the Node.js distribution. Other node* properties should not be used for clarity.

    CAUTION: globally installed distribution is modified when using the plugin and Corepack. Executables npm, pnpm, yarn that may already exists within Node.js install directory are overwritten when task installPackageManager is run.

# Property nodeDistributionUrlRoot ↑

This property is used to build the exact URL to download the distribution, by appending the value of the nodeDistributionUrlPathPattern property to its value. By default, the plugin attempts to download the distribution from the Node.js website.

# Property nodeDistributionUrlPathPattern ↑

This property is used to build the exact URL to download the distribution, by appending its value to the value of the nodeDistributionUrlRoot property. This property may be set with a fixed trailing path part (e.g. dist/node-v20.18.0-win-x64.zip), or take advantage of the automatic distribution resolution in the plugin, using specific tokens in the pattern such as VERSION, ARCH, TYPE. Then, the exact URL used by default to download the distribution is https://nodejs.org/dist/vVERSION/node-vVERSION-ARCH.TYPE.

About URL pattern tokens

The nodeDistributionUrlRoot property and this property offer a convenient way to download distributions from a custom website - e.g. a website mirroring the official Node.js website, and still take advantage of the automatic resolution of the exact URL, based on the current platform's architecture. The property may contain the following tokens:

  • VERSION: automatically replaced with the version number set in the nodeVersion property.
  • ARCH: automatically replaced with the architecture ID matching the current platform. For example, if the current O/S is MacOS 64 bits, the plugin replaces the token with darwin-x64.
  • TYPE: automatically replaced with the type of the distribution file expected for the current platform. For example, if the current O/S is Windows, the plugin replaces the token with zip.

# Property nodeDistributionServerUsername ↑

This property may be used to download the distribution with a given identity (BASIC scheme server-side). When not null, the nodeDistributionServerPassword property is also required.

SECURITY: do not to store a plain text username in the build script. Store it in an environment variable or an external user property, and use one or the other as the value of this property.

# Property nodeDistributionServerPassword ↑

Set this property to authenticate the distribution download (BASIC scheme server-side). The property is ignored if the nodeDistributionServerUsername property is null.

SECURITY: do not to store a plain text password in the build script. Store it in an environment variable or an external user property, and use one or the other as the value of this property.

# Property corepackVersion ↑

When null, the Node.js distribution is not touched and the plugin relies on the default version of Corepack embedded in the distribution. Setting this property to a non-null value should not be necessary most of the time, since Corepack is expected to be more and more stable. But situations may exist where Corepack is not able to download the package manager correctly, and upgrading the default version embedded is the only way-out. There are 2 options when setting this property:

  • Set a specific version with a value such as X.Y.Z.
  • Set the latest version with the latest value. Note that this will not update Corepack automatically if a newer version is released after the installCorepack task has run.

Script settings

The value for each property hereafter is provided as arguments of the package manager executable.

Under Unix-like O/S, white space characters ' ' in an argument value must be escaped with a backslash character '\'. Under Windows O/S, the whole argument must be enclosed between double-quotes.

  • Example on Unix-like O/S: assembleScript = 'run assemble single\ argument'
  • Example on Windows O/S: assembleScript = 'run assemble "single argument"'

Design of the plugin's tasks running a npm/pnpm/yarn executable (e.g. assembleFrontend task) rely on the assumption the package.json file contains all script definitions, and is the single resource defining how to build the frontend application, execute unit tests, lint source code, run a development server, publish artifacts... We recommend to keep these definitions in this file, in the scripts section, and avoid as much as possible using the properties below to run complex commands. Keeping these scripts in one place should also ease finding out where they are located. In an ideal situation, the properties below shall all have a value such as run <script-name>, and nothing more. Example: 

// Instead of:
assembleScript = 'run webpack -- --config webpack.config.js --profile'

// Prefer:
assembleScript = 'run build'
// with a package.json file containing:
// "scripts": {
//   "build": "webpack --config webpack/webpack.prod.js --profile"
// }
// Instead of:
assembleScript.set("run webpack -- --config webpack.config.js --profile")

// Prefer:
assembleScript.set("run build")
// with a package.json file containing:
// "scripts": {
//   "build": "webpack --config webpack/webpack.prod.js --profile"
// }

# Property installScript ↑

This property may be used to customize the command line to install frontend dependencies.

Take a look at this guide about script settings.

# Property cleanScript ↑

This property may be used to clean frontend's compiled artifacts, when they are generated out of the ${project.buildDir} directory.

Take a look at this guide about script settings.

# Property checkScript ↑

Script called to check the frontend application.

Take a look at this guide about script settings.

# Property publishScript ↑

Script called to publish the frontend artifacts.

Take a look at this guide about script settings.

Other settings

# Property packageJsonDirectory ↑

Location of the directory containing the package.json file. By default, this file is considered to be located in the project's directory, at the same level than this build.gradle[.kts] file. If the package.json file is located in another directory, it is recommended either to set up a Gradle multi-project build, or to set this property with the appropriate directory. This directory being used as the working directory when running JS scripts, consequently, the node_modules directory would be created at this location after the installFrontend task is executed.

# Property httpsProxyPort ↑

Port of the proxy server used for secure HTTP requests. This property is ignored unless the httpsProxyHost property is defined.

# Property httpsProxyUsername ↑

This property may be used to download distributions through the proxy server with a given identity (BASIC scheme server-side). This property is ignored when no proxy server is used (see the httpsProxyHost property). Otherwise, the httpsProxyPassword property is also required.

SECURITY: do not to store a plain text username in the build script. Store it in an environment variable or an external user property, and use one or the other as the value of this property.

# Property httpsProxyPassword ↑

Set this property to download distributions through the proxy server with an authenticated identity (BASIC scheme server-side). The property is ignored unless the httpsProxyUsername property is not null.

SECURITY: do not to store a plain text password in the build script. Store it in an environment variable or an external user property, and use one or the other as the value of this property.

# Property httpProxyPort ↑

Port of the proxy server used for secure HTTP requests. This property is ignored unless the httpProxyHost property is defined.

# Property httpProxyUsername ↑

This property may be used to download distributions through the proxy server with a given identity (BASIC scheme server-side). This property is ignored when no proxy server is used (see the httpProxyHost property). Otherwise, the httpProxyPassword property is also required.

SECURITY: do not to store a plain text username in the build script. Store it in an environment variable or an external user property, and use one or the other as the value of this property.

# Property httpProxyPassword ↑

Set this property to download distributions through the proxy server with an authenticated identity (BASIC scheme server-side). The property is ignored unless the httpProxyUsername property is not null.

SECURITY: do not to store a plain text password in the build script. Store it in an environment variable or an external user property, and use one or the other as the value of this property.

# Property maxDownloadAttempts ↑

Based on this property, the plugin may retry to download the Node.js distribution in case of error. A value of 1 indicates the plugin will not retry download (one attempt only). This property applies to the distribution file download as well as its shasum file download (see task installNode) used to validate the distribution file's integrity. Connectivity errors (distribution server reachability, network failures) and some HTTP errors trigger a retry of the download if more attempts are permitted thanks to this property. The retry strategy is based on the exponential backoff algorithm to determine the waiting time before the next download attempt:

waiting time (ms)=min(retryInitialIntervalMs×retryIntervalMultiplier(attempted downloads−1),retryMaxIntervalMs)

# Property retryHttpStatuses ↑

This property identifies HTTP error responses that may trigger a new download attempt based on their status code.

# Property retryIntervalMultiplier ↑

Multiplier used to compute exponential intervals between download attempts.

# Property verboseModeEnabled ↑

  • Type: boolean
  • Required: true
  • Default value: false

Whether the plugin shall log additional messages whatever Gradle's logging level is. Technically speaking, messages logged by the plugin with the INFO level are made visible. This property allows to track the plugin execution without activating Gradle's INFO or DEBUG levels, that may be too much verbose on a global point of view.

# Property cacheDirectory ↑

Directory where the plugin writes some task outputs as files. This is the only way to get Gradle perform up-to-date checks, and reuse outputs without re-executing the related task (see also this FAQ).

About proxy resolution ↑

As a prerequisite, the distribution server's IP address or domain name must not match an entry specified in the VM http.nonProxyHosts network property, otherwise the plugin uses a direct connection. Then, the plugin relies on its own settings in priority, and finally on the VM network properties. The exact behaviour at runtime is introduced below:

  • The distribution download URL uses the https protocol:
    1. If the httpsProxyHost property is not null, the plugin uses the IP address or domain name defined with this property and the port defined with the httpsProxyPort property.
    2. If the VM https.proxyHost network property is not null, the plugin uses the IP address or domain name defined with this property and the port defined with the VM https.proxyPort network property.
  • The distribution download URL uses the http protocol:
    1. If the httpProxyHost property is not null, the plugin uses the IP address or domain name defined with this property and the port defined with the httpProxyPort property.
    2. If the VM http.proxyHost network property is not null, the plugin uses the IP address or domain name defined with this property and the port defined with the VM http.proxyPort network property.