10up-toolkit/UPGRADING.md

Collection of reusable scripts for 10up development.

# Upgrade Guide

## Upgrading from 5 to 6

There are a few major changes in this release. While it probably won't break your build, it's worth noting everything that's changed.

### Node version
Minimum Node version is now 18 to follow [Node LTS](https://nodejs.org/en/about/previous-releases).

### useBlockAssets on by default.

`useBlockAssets` is now `true` by default. If you are not ready for it yet. Set `useBlockAssets` to `false` in your 10up-toolkit package.json config.

```json
{
  "name": "your-project",
  "10up-toolkit": {
    "useBlockAssets": false
  }
}
```

### Stylelint
Stylelint has been updated to 15. When upgrading toolkit ensure you also update `@10up/stylelint-config` to 3, in case you are specifying it in your package.json. If you're not, npm should resolve the peer dependency automatically.

Please note that we have updated the Stylelint Rules to account for the new version of PostCSS Nesting which, according to the spec, no longer supports `@nest`. If you are using `@nest` in your CSS, you will need to update your code to use `@at-root` instead. You can read more about this change in the [Upcoming changes to CSS Nesting](https://preset-env.cssdb.org/blog/upcoming-changes-css-nesting/).

### PostCSS
Swapping `postcss-editor-styles` with `postcss-editor-styles-wrapper` which is compatible with PostCSS 8. This should be a seamless change as this is a fork of the original package that was updated to be compatible with PostCSS 8 and fixes wrong behaviour in some circumstances.

For those referencing `postcss-editor-styles` in `postcss.config.js` should update the plugin name to `postcss-editor-styles-wrapper`.

`postcss-preset-env` has been updated to `^9.0.0` from `^7.0.0`. This is a major version bump and there are some breaking changes. It's hard to know every single build that could be affected by this change, so here is a quick list of the things that could be breaking:

* If you were relying on any of the following plugins, you will need to set the option `enableClientSidePolyfills` to true now. Also, those plugins themselves are breaking.
	* `:blank pseudo-class` polyfill.
	* `:focus-visible pseudo-class` polyfill.
	* `:focus-within pseudo-class` polyfill.
	* `:has pseudo-class` polyfill.
	* `@media (prefers-color-scheme)` polyfill.
* If you were relying on `importFrom` and/or `exportTo` you're in trouble since those options have been removed. There's a new plugin that could help with `importFrom` especially if any Modular CSS was the reason. See [PostCSS Global Data](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-global-data#readme). We’re also considering bundling this plugin into toolkit eventually, if you’re interested please chime in on [the issue](https://github.com/10up/10up-toolkit/issues/340)!
* If you were relying on `postcss-env-function`, you will need to add the plugin manually. The plugin has been deprecated and removed from [PostCSS Preset Env](https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env#readme).
* If you were using complex logic in custom media queries, you might want to revisit the output is still the same. Also, if you were using custom media queries without parenthesis, you will need to add them.
* If you were leveraging `::before` or `::after` in custom selectors, you will need to rewrite your custom selectors to remove these. Similarly, if you use complex selectors (e.g. `.foo + .bar`) you will need to verify your project. The matched elements can be different.
* If you were relying on the `:dir` generated by [PostCSS Logical](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical#readme) to handle `margin-inline` and such, then you need to refactor your code.

See the [postcss-preset-env changelog](https://github.com/csstools/postcss-plugins/wiki/PostCSS-Preset-Env-8) for version 8 if you run into issues related to this change.

### Eslint
The rule `jsdoc/newline-after-description` has been removed in the latest `eslint-plugin-jsdoc` and thus has been removed in the latest version of toolkit. If you have this rule in your own eslint config file you will need to remove it.

When upgrading toolkit, ensure you also update `@10up/eslint-config` to 4, in case you are specifying it in your package.json. If you're not npm should resolve the peer dependency automatically.

### Prettier

Prettier have been upgraded to v3. We also recommend that you specify a [prettier exact version](https://prettier.io/docs/en/install#summary) in your own package.json going forward. If you haven't, add prettier v3 to your package.json and if you already have prettier listed as a dependency, update it to v3. Updating prettier will now be responsibility of the project since updating prettier often requires other code changes to adhere to new formatting rules.

### Jest

The jest packages have been updated, if you're using `10up-toolkit test-unit-jest` and using `testEnvironment: jsdom`, add `jest-environment-jsdom` as a dependency to your project.

## Upgrading from 3 to 4

If you're on version 3 and followed below to be on (at least) NPM version `7`, you should be in the clears for this upgrade. In the case you're not, you'll need to install all of these dependencies manually into the project where toolkit is used given that it's only from NPM 7 that `peerDependency` are handled automatically.

* `@10up/babel-preset-default`
* `@10up/eslint-config`
* `@10up/stylelint-config`
* `eslint`
* `eslint-config-airbnb`
* `eslint-config-airbnb-base`
* `eslint-config-prettier`
* `eslint-plugin-import`
* `eslint-plugin-jest`
* `eslint-plugin-jsdoc`
* `eslint-plugin-jsx-a11y`
* `eslint-plugin-prettier`
* `eslint-plugin-react`
* `eslint-plugin-react-hooks`
* `eslint-webpack-plugin`
* `prettier`
* `stylelint`

We're aiming to reduce major version releases with this change, decoupling Stylelint, Eslint and Prettier cycle's from Toolkit's cycles as we move forward. With this change it's possible to stay on Stylelint 13 if you depend on `@10up/stylelint-config` version `^1.0.0` or upgrade to Stylelint 14 if you use version `^2.0.0`.

## Upgrading from 2 to 3

### Minimum Node.js version

The minimum Node.js version is 12.x, however Node.js 16 is strongly recommended.

### Minimum NPM version

In theory 10up-toolkit can be installed with any npm version >= 6, however we don't recommend npm < 7.

~~If you're getting an install error due to conflicting prettier dependencies, we recommend updating to npm 8.  There's an [known issue](https://github.com/WordPress/gutenberg/issues/39208) with `@wordpress/eslint-plugin` that can break installations of 10up-toolkit when using npm < 8. Alternatively if you're not on npm 8, you can try pinning `prettier` to `2.4.1` in your package.json to force npm install the version toolkit uses.~~ Fixed in [#166](https://github.com/10up/10up-toolkit/pull/166)

### BrowserSync packages have been removed by default.

With the introduction of Hot Module Reload and React Fast Refresh, browser-sync has been deprecated in 10up-toolkit. However, if you wish to continue using browser sync while migrating to HMR & Fast Refresh, you can do so by installing `browser-sync` and `browser-sync-webpack-plugin`.

```
npm install --save-dev browser-sync browser-sync-webpack-plugin
```

If you're using NPM workspaces, make sure to specify the desired workspace.

```
npm install --save-dev browser-sync browser-sync-webpack-plugin -w=workspace-name
```

Browser sync will be automatically enabled if a `devURL` is specified and those packages are installed when you run `10up-toolkit watch` and `10up-tooking start`.

### The post css plugin `postcss-object-fit-image` has been removed

The post css plugin `postcss-object-fit-image` is no longer needed since we stopped supporting IE 11. If you are extending the `postcss.config.js` file and including that plugin you will need to remove from the list of plugins.

Note that the recommended way of extending `postcss.config.js` is as follows:

```javascript
const baseConfig = require('10up-toolkit/config/postcss.config.js');

module.exports = (props) => {
    const config = baseConfig(props);

    // do what you want with the config object

    return config;
};
```

So if you are just adding new things to the config you might not need to do anything as the removed plugin would come from the default config.

## `imagemin-webpack-plugin` and `imagemin` have been replaced

`imagemin-webpack-plugin` and `imagemin` have been replaced with `image-minimizer-webpack-plugin` and `squoosh`.

If you are extending the webpack config and making use of `imagemin-webpack-plugin` and `imagemin` you will need to change your webpack config.

If you want to extend your webpack config to optimize additional files you can do so the following way:

```javascript
const config = require('10up-toolkit/config/webpack.config.js');

config.optimization.minimizer.push(
    new ImageMinimizerPlugin({
        test: 'regex',
        minimizer: [
            {
                implementation: /* add a custom minimizer implementation */,
            },
        ],
    })
);
return config;
```

**IMPORTANT**: If you were extending the webpack config to change how svgs are optimized (such as prevent removing viewBox), 10up-toolkit no longer strips viewbox from svgs.

## HMR & Fast Refresh

Check out the [docs](./README.md#fast-refresh) for guidance on how to enable HMR and Fast Refresh.

Additionally, check out this [PR](https://github.com/10up/wp-scaffold/pull/87) that enables HMR & Fast Refresh in 10up's wp-scaffold.