Version 6.0 of @lipemat/js-boilerplate is now available and ready for use. This is a major version update with several structural changes. Read on for migration instructions.
This release added support for the following systems:
- Node version 14.
- Yarn PNP.
- Webpack version 5.
Many of the previously included configurations and systems have been moved to their own package to support PNP and universal reuse.
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 are 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 configurations 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.
Add the following to the generated .yarnrc.yml to support our special structure.
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.
- react-router
- react-router-dom
- reactn
Direct Dependencies
Some dependencies are now required in your local package.json for PHPStorm and TypeScript to function.
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.
If using @lipemat/postcss-boilerplate it must also be added there.
Configuration Updates
Many of the configurations 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
.eslintrc
tsconfig.json
Gitignore
Add the following to prevent install-state.gz and node_modules from appearing.
Remove the following which will break the Yarn cache due to internal linking.
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).
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, Stylelint cannot be enabled in PHPStorm because of the following caveats:
- PNP requires a
package.jsonto live above the level of the file being linted. - PNP cannot exist at multiple levels in the same project.
- The
package.jsonmust include the@lipemat/stylelint-configpackage.
This creates multiple issues with clutter, as well as requiring duplicate packages. Technically, it may be made to work by moving the package.json file to the theme root and overriding all directories with configurations, but this adds a large amount of clutter for something with relatively low value.