10.0.0

Features

• Task resolvePackageManager supports a packageManager property whose value ends with a hash to allow an integrity check after download by Corepack (#271).
• Task cleanFrontend was removed because it triggered tasks installNode and installFrontend, which was not intuitive and created latency when cleaning a project (#273).

Additional notes

• JDK 11 build will be abandoned in the next major release (11.0.0).

Upgrading from 9.0.0+

Breaking changes

After task cleanFrontend and DSL property frontend.cleanScript were removed, projects that were configuring this property to run a node-based command during Gradle clean task must now register a custom task.

Steps

In build scripts, register a custom task:

// Before upgrade

frontend {
    cleanScript.set(<clean-script>)
}

// After upgrade

// Solution 1 (recommended)
tasks.register<Delete>("cleanFrontend") {
    delete(<file>, ...)
}

tasks.named("clean") {
    dependsOn("cleanFrontend")
}

// Solution 2
import org.siouan.frontendgradleplugin.infrastructure.gradle.Run[Npm|Pnpm|Yarn]TaskType

tasks.register<Run[Npm|Pnpm|Yarn]TaskType>("cleanFrontend") {
    args.set(<clean-script>)
    dependsOn("installFrontend")
}

tasks.named("clean") {
    dependsOn("cleanFrontend")
}

9.1.0

Features

• Support of Node.js distribution compatible with Linux S390X systems (#260).
• Support of Node.js distribution compatible with Linux PPC64LE systems (#258).
• Support of Node.js distribution compatible with AIX PPC64 systems (#257).

Bug fixes

• installNode task does not delete temporary Node.js distribution file used for download after a 404 HTTP response (#254)

Latest upgrade notes available in release 9.0.0

9.0.0

Features

• Arguments of all task types are configurable on the command line (#239).
• New tasks runNode, runCorepack, runNpm, runPnpm, runYarn allow to execute an instant command from a Gradle command line without registering a custom task (#242).
• Support of Node.js distribution compatible with Windows ARM architecture (Node.js ≥ 19.9.0) (#249).

Upgrading from 8.0.0+

Breaking changes

New tasks run[Node|Corepack|Npm|Pnpm|Yarn] have a name that is conflicting with the name of implementation classes for task types Run[Node|Corepack|Npm|Pnpm|Yarn]. The script input property of these task types also suffer from a confusing name as it contains arguments to be appended after the name of the executable rather than a script identifier from the scripts section of the package.json file. To keep a consistent and comprehensive naming convention, name of classes for task types has been modified, as well as the name of the script input property.

Steps

In build scripts:

• Rename imports and uses of class RunCorepack to RunCorepackTaskType. Rename the script input property to args.
• Rename imports and uses of class RunNode to RunNodeTaskType. Rename the script input property to args.
• Rename imports and uses of class RunNpm to RunNpmTaskType. Rename the script input property to args.
• Rename imports and uses of class RunPnpm to RunPnpmTaskType. Rename the script input property to args.
• Rename imports and uses of class RunYarn to RunYarnTaskType. Rename the script input property to args.
• Verify and eventually rename any custom task previously named runNode, runCorepack, runNpm, runPnpm, runYarn. These names are now reserved by some plugin tasks.

Example:

// Before upgrade
import org.siouan.frontendgradleplugin.infrastructure.gradle.RunNode
tasks.register<RunNode>("runNode") {
    script.set("-v")
}

// After upgrade
import org.siouan.frontendgradleplugin.infrastructure.gradle.RunNodeTaskType
tasks.register<RunNodeTaskType>("getNodeVersion") {
    args.set("-v")
}

Contributions

• @t-h-e

8.1.0

Requirements

• Gradle: ≥8.5 for JDK 21 build, JDK 17 build, JDK 11 build

Features

• Corepack version management with new task installCorepack (#212)
• Support of environment variables for each Node.js-based task (#220)
• Release of JDK 21 build.

Bug fixes

• Serialization issues and compatibility with Gradle configuration cache (#217).

Latest upgrade notes available in release 8.0.0

Contributions

• @marcospereira

8.0.0

Requirements

• Gradle: ≥7.3 for JDK 17 build
• Gradle: ≥6.2 for JDK 11 build

Features

• Support of Node.js Linux ARM64 distributions (#190).
• Retry capability when downloading the Node.js distribution (#201).

Bug fixes

• Task installPackageManager and depending tasks could be executed unexpectedly with corrupted inputs when task resolvePackageManager was skipped (#206).

Upgrading from 7.0.0+

Breaking changes

Due to issue #206, support of FGP_NODEJS_HOME environment variable for the Node.js install directory is abandoned as it was impacting significantly implementation of new tasks resolvePackageManager and installPackageManager. However, the same behaviour may be obtained using an explicity configuration of property nodeInstallDirectory.

Steps

If the build was relying on FGP_NODEJS_HOME environment variable, see this FAQ for an alternative implementation.

Contributions

• @thebignet (#201)

7.0.0

Support of package managers through corepack

Requirements

• Gradle: ≥7.3 for JDK 17 build
• Gradle: ≥6.1 for JDK 11 build
• Node.js: ^14.19.0, ≥16.9.0
• JDK: ≥11

Features

• Initial support of PNPM (#183)
• Release of JDK 17 built.

Upgrading from 6.0.0+

Breaking changes

• Tasks NodeInstallTask and InstallDependenciesTask were renamed to match naming convention of other tasks.
• Tasks installGlobalYarn, enableYarnBerry, installYarn were removed since installation is now managed by corepack.
• Task type RunNpx was removed after command npx became deprecated. Command npm exec should be used instead.

Steps

• Define property packageManager in your package.json file (e.g. [email protected], [email protected], [email protected], etc.).
• Add .frontend-gradle-plugin/ directory to .gitignore file(s) (see cacheDirectory property).
• Rename task classes NodeInstallTask and InstallDependenciesTask into InstallNodeTask and InstallFrontendTask in build scripts.
• Remove yarnEnabled and yarnVersion properties from build scripts, if any (already known with property packageManager).
• Update any custom task based on type RunNpx: use type RunNpm instead and prepend exec -- to the script property value. See official documentation here for detailed usage and examples.
• JDK 8 is not supported anymore. Projects must upgrade to JDK 11+.

6.0.0

Yarn Berry initial support (Yarn 1, Yarn 2+)

Introduction

Yarn 2+ (Berry codename) is a massive rewrite of the package manager. Contrary to former Classic Yarn 1.x for which distribution archives are published, Yarn 2+ cannot be installed with a distribution archive anymore. Download and installation are entirely handled by Yarn itself, thanks to a preliminary global install with NPM.

This release brings an initial support of new Yarn package manager (often referred to as Yarn Berry, Yarn 2, or Yarn PnP), which provides access to Yarn releases 1.x and above in a different way than previous release of the package manager. This initial support means that we focused mainly on migration of projects based on Classic Yarn, to ensure they can go on using the plugin and a Yarn 1.x distribution through Yarn Berry "mode". There may be many use cases specific to Yarn 2 that the plugin is not aware of.

Impacts

The plugin components formerly in charge of downloading Classic Yarn 1.x distributions had to be refactored to handle Yarn installation in a different way, the way enforced by Yarn Berry:

• The plugin does not download and explode a Yarn distribution anymore.
• Using a proxy to download Yarn distributions must be configured at Yarn's level.
• Basic authentication settings for Yarn become irrelevant.
• Installing Yarn now requires the Node.js distribution to be present (i.e. the installNode task becomes an indirect dependency of the installYarn task). Indirect because before the appropriate Yarn distribution is installed in the (sub-)project, the plugin executes new tasks installGlobalYarn and enableYarnBerry. These 2 "technical" tasks allow to prepare the per-project installation, as explained in Yarn's install guide. The dependency chain now becomes installNode <- installGlobalYarn <- enableYarnBerry <- installYarn, and is executed left to right. The installYarn task still means the same thing: get a ready-to-use Yarn distribution for the project.

Features

• Added support of Yarn 2 (#139)

Tasks

• Task type RunNpmYarn was split in 2 distinct types RunNpm and RunYarn.

Upgrading from 5.0.0+

A definitive migration guide is very difficult to achieve, as there are many different configurations to take into account. Feel free to report any issue/improvement in the suggested steps below:

• Ensure you are able to rollback to a previous version of your project in case of problem (VCS, backup, etc).
• NODEJS_HOME environment variable is not used anymore by the plugin to resolve the location of the node executable. Now the plugin relies on the FGP_NODEJS_HOME environment variable. Update your environment variables accordingly if your build was explicitly relying on this variable (see documentation of the nodeDistributionProvided property).
• The project relies on NPM (i.e. yarnEnabled property is false):
  • Update any custom task using the former RunNpmYarn type with RunNpm type.
• The project relies on Yarn (i.e. yarnEnabled property is true):
  • If the yarnDistributionProvided property is false, the plugin will not use a previously downloaded distribution (i.e. the one pointed by the yarnInstallDirectory property). You may remove it.
  • Any YARN_HOME environment variable may have to be renamed, because YARN_* environment variables are now used automatically by Yarn to resolve some of its settings (see this section). Note that the YARN_HOME environment variable is not used anymore by the plugin to resolve a Yarn distribution on the system.
  • Remove properties yarnDistributionProvided, yarnDistributionUrlRoot, yarnDistributionUrlPathPattern, yarnDistributionServerUsername, yarnDistributionServerPassword, yarnInstallDirectory.
  • Update any custom task using the former RunNpmYarn type with RunYarn type.
  • Proxy settings don't apply to Yarn anymore. Refer to Yarn's documentation of httpsProxy property or httpProxy property) as a replacement.
  • If the nodeDistributionProvided property is false, and the Node.js distribution is not shared with other projects outside the root project, upgrade shall be completed.
  • Otherwise, ensure installing a Classic Yarn 1.x distribution globally (i.e. in the Node.js distribution) does not break other projects (the yarn executable located now in the Node.js distribution might take precedence over another executable).

We don't recommend upgrading simultaneously the plugin and Yarn (i.e. updating yarnVersion property to 2.x), to ease troubleshooting in case of problems. If you do so, keep in mind the plugin won't perform the migration of your project files (for this particular point, you should follow Yarn's migration guide). Instead:

1. First upgrade the plugin, and migrate project by following Yarn's migration guide. Ensure everything is working fine without changing the yarnVersion property (i.e. keep a Yarn 1.x distribution). At this point, keep in mind Yarn Berry deals with these distributions, and will take over from the plugin to download and install the relevant distribution.
2. Then update Yarn's version.

5.3.0

Features

• Added support of Node.js Linux ARMv7 distribution (#165)

Latest upgrade notes available in release 5.0.0

5.2.0

This release brings support of Gradle 7.0 and its configuration cache.

Requirements

• Gradle: ≥6.1 for JDK 11 build, JDK 8 build

Features

• Added support of Gradle 7.0 and compliance with configuration cache (#161)

Latest upgrade notes available in release 5.0.0

5.1.0

Features

• Added support of Node.js Apple Silicon distribution (ARM64), which requires Node.js 16.0.0 (#148)

Latest upgrade notes available in release 5.0.0