Configuration

Plugin DSL

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

frontend {
    nodeDistributionProvided = false
    nodeVersion = '14.16.1'
    nodeDistributionUrlRoot = 'https://nodejs.org/dist/'
    nodeDistributionUrlPathPattern = 'vVERSION/node-vVERSION-ARCH.TYPE'
    nodeDistributionServerUsername = 'username'
    nodeDistributionServerPassword = 'password'
    nodeInstallDirectory = file("${projectDir}/node")

    yarnEnabled = false
    yarnDistributionProvided = false
    yarnVersion = '1.22.10'
    yarnDistributionUrlRoot = 'https://github.com/yarnpkg/yarn/releases/download/'
    yarnDistributionUrlPathPattern = 'vVERSION/yarn-vVERSION.tar.gz'
    yarnDistributionServerUsername = 'username'
    yarnDistributionServerPassword = 'password'
    yarnInstallDirectory = file("${projectDir}/yarn")

    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'
    verboseModeEnabled = false
}
frontend {
    nodeDistributionProvided.set(false)
    nodeVersion.set("14.16.1")
    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"))

    yarnEnabled.set(false)
    yarnDistributionProvided.set(false)
    yarnVersion.set("1.22.10")
    yarnDistributionUrlRoot.set("https://github.com/yarnpkg/yarn/releases/download/")
    yarnDistributionUrlPathPattern.set("vVERSION/yarn-vVERSION.tar.gz")
    yarnDistributionServerUsername.set("username")
    yarnDistributionServerPassword.set("password")
    yarnInstallDirectory.set(project.layout.projectDirectory.dir("yarn"))

    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")
    verboseModeEnabled.set(false)
}

Properties

Node.js settings

# Property nodeDistributionProvided

  • Related tasks: installNode
  • Type: boolean
  • Required: true
  • Default value: false

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

  1. When false, at least the nodeVersion property must be set.
  2. When true, the plugin relies on the following locations in this exact order to find node/npm/npx executables:
    1. The directory pointed by the nodeInstallDirectory property, if set.
    2. The directory pointed by the NODEJS_HOME environment variable, if set.
    3. Any directory in the PATH environment variable.
    Other node* properties should not be used for clarity.

# 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-v14.16.1-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 nodeInstallDirectory

Directory where the downloaded distribution shall be installed, or where a provided distribution is located if the nodeDistributionProvided property is true.

Yarn settings

# Property yarnDistributionProvided

  • Related tasks: installYarn
  • Type: boolean
  • Required: true
  • Default value: false

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

  1. When false, at least the yarnVersion property must be set.
  2. When true, the plugin relies on the following locations in this exact order to find yarn executable:
    1. The directory pointed by the yarnInstallDirectory property, if set.
    2. The directory pointed by the YARN_HOME environment variable, if set.
    3. Any directory in the PATH environment variable.
    Other yarn* properties should not be used for clarity.

# Property yarnDistributionUrlRoot

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

# Property yarnDistributionUrlPathPattern

This property is used to build the exact URL to download the distribution, by appending its value to the value of the yarnDistributionUrlRoot property. This property may be set with a fixed trailing path part (e.g. dist/yarn-v1.22.10.tar.gz), or take advantage of the automatic distribution resolution in the plugin, using specific token in the pattern such as VERSION (see the installYarn task).

Then, the exact URL used by default to download the distribution is https://github.com/yarnpkg/yarn/releases/download/vVERSION/yarn-vVERSION.tar.gz.

About URL pattern token

The yarnDistributionUrlRoot property and this property offer a convenient way to download distributions from a custom website - e.g. a website mirroring the official Yarn website, and still take advantage of the automatic resolution of the exact URL. The property may contain the following token:

  • VERSION: automatically replaced with the version number set in the yarnVersion property.

# Property yarnDistributionServerUsername

This property may be used to download the distribution with a given identity (BASIC scheme server-side). When not null, the yarnDistributionServerPassword 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 yarnDistributionServerPassword

Set this property to authenticate the distribution download (BASIC scheme server-side). The property is ignored unless the yarnDistributionServerUsername property is defined.

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 yarnInstallDirectory

Directory where the downloaded distribution shall be installed, or where a provided distribution is located if the yarnDistributionProvided property is true.

Script settings

Depending on the value of the yarnEnabled property, the value for each property hereafter is provided as argument either of the npm executable or the yarn 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/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 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.

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.