Skip to content

6.0.0
Compare
Choose a tag to compare
@v1nc3n4 v1nc3n4 released this 07 Nov 17:51
v6.0.0
8627c87

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 unrelevant.
  • 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.
Assets 2
Loading