Frequently asked questions

How to use `node`/`corepack`/`npm`/`pnpm`/`yarn` executables apart from Gradle when the Node.js distribution is downloaded by the plugin? ↑

Create a NODEJS_HOME environment variable (or a name of your choice) containing the real path set in the nodeInstallDirectory property.
Add the directory containing executables to the PATH environment variable:
- On Unix-like O/S, add the $NODEJS_HOME/bin path.
- On Windows O/S, add %NODEJS_HOME% path.

What should I do when error `UnsupportedPlatformException` occurs? ↑

By default, the plugin uses an automatic resolution process to "guess" the most relevant Node.js distribution applicable for your O/S and CPU architecture. Technically speaking, the plugin relies on JVM system properties named os.name and os.arch. If the plugin gets values it does not expect from these system properties, the following error shall occur during the build:

Execution failed for task ':installNode'. > org.siouan.frontendgradleplugin.domain.UnsupportedPlatformException: This platform is not supported yet: Platform(jvmArch=<os.arch>, osName=<os.name>)

In this case, please open an issue in the project's issue tracker, and provide the entire error message above. If possible, provide also output of command java -XshowSettings:properties -version and output of command uname for Unix-like O/S (beware of hiding sensitive data in both cases). As a workaround, consider using property nodeDistributionUrlPathPattern and specify a hard-coded path to download the relevant distribution from the Node.js distribution server.

How to configure the plugin so as it can download a Node.js distribution from a custom server? ↑

Properties nodeDistributionUrlRoot and nodeDistributionUrlPathPattern exist specially for this use case.

What's the purpose of the `.frontend-gradle-plugin` directory generated in each project? ↑

The plugin uses this directory to store some task outputs as files, so as Gradle can perform up-to-date checks. It allows to skip some task execution and optimize build time when inputs did not change, by reusing the already computed outputs. Generally, the build directory of the project is used for such goal, but the plugin cannot rely on this directory because it is removed when Gradle clean task is executed. This would remove mandatory outputs for plugin task cleanFrontend.

How can I set the install directory of the Node.js distribution using an environment variable? ↑

The best way to set the install directory using the value of an environment variable is to rely on Gradle API rather than on Java API:

frontend {
    nodeInstallDirectory = providers.environmentVariable('NODEJS_HOME')
}

frontend {
    nodeInstallDirectory.set(providers.environmentVariable("NODEJS_HOME"))
}

How can I provide additional environment variables to `node`/`corepack`/`npm`/`pnpm`/`yarn` processes? ↑

See this section.