Migrate From Version 5 to Version 6

Version 6 was designed to support Yarn PNP using loose mode as well as Webpack 5 and node 14.

The majority of migrations will only be required if you are using PNP because various configuration files a not available to extend via the typical node_modules folder.

If you are not using Yarn PNP nor any configuration overrides, this guide is optional as it does not necessarily pertain to you, but should be followed anyway.

Webpack 5

All configuration use and rely on Webpack 5 being available. If you are using any configuration overrides, be sure to check the Webpack migration guide for any changes required for your configurations.

Node 14

This library no longer supports version 13 of node. While it will probably work to use earlier or later versions of node, we are no longer testing against non LTS (14) versions so it's best to simply use your NVM to change to the latest LTS 14 version.

Switching to Yarn PNP

The first step is to point your project to Yarn V2 like so

yarn set version berry
yarn set version latest

Add the following to the generated .yarnrc.yml to support our special structure.

nodeLinker: pnp
pnpMode: loose
pnpFallbackMode: all
enableScripts: false

logFilters:
  # Disable the warnings when peer dependencies are not provided due to boilerplate.
  - code: YN0002
    level: discard
  # Disable warning of third party build scripts we don't let run.
  - code: YN0004
    level: discard

Adjust your .gitignore (see below), then run yarn install.

No Longer Available Dependencies

If you are using any dependency on this list, you must add it to your local package.json.

1. react-router
2. react-router-dom
3. reactn

Direct Dependencies

Some dependencies are now required in your local package.json for PHPStorm and TypeScript to function.

{
"devDependencies": {
    "@types/jquery": "^3",
    "@types/lipemat__js-boilerplate": "lipemat/types-js-boilerplate#semver:^1",
    "eslint": "^7",
    "jest": "^26",
    "typescript": "^4",
  }
}

New Script

Because Yarn PNP will flood the console with warnings, we have a custom script which adjusts the .pnp.js file to remove these warnings. This script must be added as a postinstall event to package.json.

{
  "scripts": {
    "dist": "lipemat-js-boilerplate dist",
    "lint": "lipemat-js-boilerplate lint",
    "postinstall": "lipemat-js-boilerplate fix-pnp",
    "start": "lipemat-js-boilerplate start",
    "test": "lipemat-js-boilerplate test"
  },
}

If using @lipemat/postcss-boilerplate it must also be added there.

{
   "scripts": {
    "dist": "lipemat-postcss-boilerplate dist",
    "lint": "lipemat-postcss-boilerplate lint",
    "postinstall": "bash ./bin/npm-post-install && lipemat-postcss-boilerplate fix-pnp",
    "start": "lipemat-postcss-boilerplate start"
  },
}

Configuration Updates

Many of the configuration for various services must be updated to directly access the libraries instead of files within the node_modules directory. The majority may be found in the /templates directory.

ts

This directory may be deleted entirely as we no longer need to manually add jquery.d.ts and package.json to a /ts directory.

.nvmrc

14.15.3

.stylelintrc

{
	"extends": "@lipemat/stylelint-config"
}

.eslintrc

{
	"extends": [
		"@lipemat"
	]
}

tsconfig.json

{
  "extends": "@lipemat/js-boilerplate/config/tsconfig.json",
  "include": [
    "src/**/*"
  ]
}

Older Browsers Support

Custom properties

To allow custom properties to work with older browsers:

1. Rename the src/globals/pcss/variable.pcss file to src/globals/pcss/variables.css (notice the "s" at the end).
2. Rename the ../pcss/globals/variable.pcss file to ../pcss/globals/variables.css (notice the "s" at the end).
3. Add an @import for the ../pcss/globals/variables.css file to the default.pcss file instead of the previous src/globals/pcss/variables.pcss file.

ES6 Modules

The app will automatically detect any packages in your package.json which do not support ES5 and add them to the list of files that Babel will transform into ES5 code.

If you have a package which has a dependency which does not support ES5, you will need to add it to a es6Modules key in your package.json to have it transformed.

Example

{
 "es6Modules": [
    "buffer"
  ]
}

Gitignore

Add the following to prevent install-state.gz and node_modules from appearing.

# Yarn berry files
install-state.gz
dev/node_modules
wp-content/themes/core/js/node_modules

Remove the following which will break the Yarn cache due to internal linking.

node_modules

Deployment script

You NEVER want to run yarn install during a deployment script as packages will be include in Git. Simply remove all references of this within your deploy.sh.

post-merge Git hook

Git hooks must not run yarn install any longer. Remove the yarn_install function and any calls to it. No longer need to detect when package.json changes.

Cleanup

Cleanup any dangling node_modules on the server(s).

rm -Rf node_modules

PHPStorm Settings

TypeScript

Typescript must be pointed at the yarn link like so yarn:wp-content\themes\core\js\package.json:typescript

Jest

Jest (JS Test) must be pointed to yarn link like so yarn:wp-content\themes\core\js\package.json:jest

Stylelint

If using Yarn PNP with Stylelint can't be enabled in PHPStorm because of the following caveats:

1. PNP requires a package.json to live above the level of the file being linted.
2. PNP cannot exist at multiple levels in the same project.
3. The package.json must include the @lipemat/stylelint-config package.

Alternative Stylelint Configurations

If you want to use it just for the JS App you may do the following:

1. Move the .stylelintrc file to the js directory.
2. Add the following to your package.json and you will be able to enable the inspection in PHPStorm and run CSS lint via yarn css-lint.
3. In PHPStorm go to 'Inspections -> CSS -> Code quality tools -> Stylelint' and enable it just for scopes which target your JS app.

{
  "scripts": {
    "css-lint": "stylelint src/**/*.pcss --fix",
  },
  "devDependencies": {
    "@lipemat/stylelint-config": "^1.1.2",
    "stylelint": "^13"
  }
}