Version 7 Migration - lipemat/js-boilerplate GitHub Wiki

Migration From Version 6 to Version 7

The following are breaking changes which must be considered when updating.

theme_path in package.json

The theme_path has been renamed to themeUrlPath. This must be updated in the package.json file.

Old

{
"theme_path": "/wp-content/themes/core/",
}

New

{
"themeUrlPath": "/wp-content/themes/core/",
}

Classnames

The classnames package is no longer included in the boilerplate. It was removed the boilerplate because it must be installed locally to support it's new TypeScript definitions. The global @types/classnames library is no longer maintained.

If you are using classnames, add it locally.

yarn add classnames

Node

Due to a critical security release, this package now requires node 14.17.6. While this package was in no way affected by the security issues, we take security seriously and are now requiring our users to have a secure version of node.

CSS Loader and Style Loader

The major versions of the css-loader and style-loader have been updated to the latest version.

  1. css-loader V6
  2. style-loader V3

If you are using configuration overrides for the css-loader portion of the Webpack configurations, you'll want to:

  1. Merge in changes from the boilerplate versions.
  2. Update your configurations changes to support the new versions of the loaders.

PostCSS Global Modules

Previously all modules were treated as local first and required wrapping a global CSS class with :global. Now any postcss file within either a 'global' or 'globals' directory will automatically be treated a global module. Technically, nothing will break with the change but best to update:

  1. Remove :global from all CSS classes within a 'global(s)' directory.
  2. Add :local to any CSS classes within a 'global(s)' directory which are intended to be :local.

PHPStorm can do a simple replace of all:

  1. Replace (enable Regex '.*') -> :global\((.*)\)
  2. With -> $1

Combined Packages

If you are migrating to a combined package as part of version 7 the following applies to you. If you don't know what I'm talking about, you may ignore this section entirely.

Combined Scripts

Some should be run in sequence, some in parallel. Pay attention to & vs && in the following examples.

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

Theme path

The postcss-boilerplate requires the theme_path to be available. Since we renamed it for js-boilerplate, we need to add it back for postcss-boilerplate

{
  "theme_path": "./",
}

Root path

Since the package.json lives one level above where it was, the root must be adjusted to be one level up.

{
  "root": "../../../"
}

JS path

Since the package.json lives one level above the js directory, a jsPath is required.

{
  "jsPath": "./js"
}

PHPStorm NPM run configurations

Remove all existing CSS and JS versions in favor of recreating all from the new package.json.

JEST

Jest tests will continue to run via the scripts, but require some reconfigurations for PHPStorm.

  1. Working directory -> Set to root of theme instead of JS directory.
  2. Jest Options: -> --config=js/jest.config.js
    1. Alternatively, you may point to the jest.config.js file via the "Configuration file" field.

Gitignore

  1. Remove -> dev/node_modules
  2. Move -> wp-content/themes/core/js/node_modules to wp-content/themes/core/node_modules

Git Hooks

  1. Adjust Git hooks to only include the single package.
  2. Run dist on either .pcss or .js changes.

Deployments

Deployment scripts must be updated.

  1. Run the compiling of resources from the package.json directory.
  2. Only run once, instead of separate for JS and PostCSS.

Stylelint

PHPStorm will now support running Stylelint.

  1. Enable stylelint using new package location.
  2. Enable the stylelint inspection.
    1. Theme Files only.
  3. Move .stylelintrc to new package location.

Configuration overrides

If you are using configuration overrides, you'll need to move the config directory to the same directory as the new package.json.