From 9dd8116acb5d5e5632947d3ee106ab4ce944dacb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Ka=CC=88gy?= Date: Mon, 6 May 2024 08:45:04 +0200 Subject: [PATCH 1/7] fix rename `useBlockModules` mode to `useScriptModules` --- packages/toolkit/config/webpack.config.js | 4 ++-- packages/toolkit/config/webpack/output.js | 4 ++-- packages/toolkit/utils/config.js | 4 ++-- projects/10up-theme/package.json | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/toolkit/config/webpack.config.js b/packages/toolkit/config/webpack.config.js index 8b52d948..ffb66ee5 100644 --- a/packages/toolkit/config/webpack.config.js +++ b/packages/toolkit/config/webpack.config.js @@ -32,7 +32,7 @@ const moduleBuildFiles = getModuleBuildFiles(); const isPackage = typeof source !== 'undefined' && typeof main !== 'undefined'; const isProduction = process.env.NODE_ENV === 'production'; const mode = isProduction ? 'production' : 'development'; -const useBlockModules = projectConfig.useBlockModules || false; +const useScriptModules = projectConfig.useScriptModules || false; const defaultTargets = [ '> 1%', @@ -107,4 +107,4 @@ const moduleConfig = { }, }; -module.exports = useBlockModules ? [scriptsConfig, moduleConfig] : scriptsConfig; +module.exports = useScriptModules ? [scriptsConfig, moduleConfig] : scriptsConfig; diff --git a/packages/toolkit/config/webpack/output.js b/packages/toolkit/config/webpack/output.js index 74fbf2e1..60a51f9a 100644 --- a/packages/toolkit/config/webpack/output.js +++ b/packages/toolkit/config/webpack/output.js @@ -3,7 +3,7 @@ const path = require('path'); module.exports = ({ isPackage, packageConfig: { packageType, main }, - projectConfig: { filenames, useBlockModules, hot, publicPath }, + projectConfig: { filenames, useScriptModules, hot, publicPath }, buildFiles, }) => { if (isPackage) { @@ -23,7 +23,7 @@ module.exports = ({ return { // when in block module mode or when hot reloading is active we should not clear dist folder between builds - clean: !useBlockModules && !hot, + clean: !useScriptModules && !hot, path: path.resolve(process.cwd(), 'dist'), chunkFilename: filenames.jsChunk, publicPath, diff --git a/packages/toolkit/utils/config.js b/packages/toolkit/utils/config.js index c9b72637..7d44b0fa 100644 --- a/packages/toolkit/utils/config.js +++ b/packages/toolkit/utils/config.js @@ -109,7 +109,7 @@ const getDefaultConfig = () => { const analyze = hasArgInCLI('--analyze'); const include = hasArgInCLI('--include') ? getArgFromCLI('--include').split(',') : []; const sourcemap = hasArgInCLI('--sourcemap'); - const useBlockModules = hasArgInCLI('--block-modules') || false; + const useScriptModules = hasArgInCLI('--block-modules') || false; const buildFilesPath = hasProjectFile('buildfiles.config.js') ? fromProjectRoot('buildfiles.config.js') @@ -140,7 +140,7 @@ const getDefaultConfig = () => { !process.env.TENUP_NO_EXTERNALS, publicPath: process.env.ASSET_PATH || undefined, useBlockAssets: true, - useBlockModules, + useScriptModules, include, }; }; diff --git a/projects/10up-theme/package.json b/projects/10up-theme/package.json index 4b12eb3c..9b9ccf5b 100644 --- a/projects/10up-theme/package.json +++ b/projects/10up-theme/package.json @@ -34,7 +34,7 @@ }, "10up-toolkit": { "useBlockAssets": true, - "useBlockModules": true, + "useScriptModules": true, "entry": { "admin": "./assets/js/admin/admin.js", "frontend": "./assets/js/frontend/frontend.js", From 53ee5c34eca3bf380bf1b76a757070bc424b1e45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Ka=CC=88gy?= Date: Mon, 6 May 2024 08:45:36 +0200 Subject: [PATCH 2/7] add documentation for `useScriptModules` mode --- packages/toolkit/README.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/packages/toolkit/README.md b/packages/toolkit/README.md index 8d66c234..24728ecb 100644 --- a/packages/toolkit/README.md +++ b/packages/toolkit/README.md @@ -219,7 +219,7 @@ Alternatively, you can set up `process.env.ASSET_PATH` to whatever path (or CDN) _NOTE: Since 10up-toolkit@6 this `useBlockAssets` is on by default_ -If your project includes blocks there are quite a few assets that need to be added to the list of entry points for Webpack to transpile. This can get quite cumbersome and repetitive. To make this easier toolkit has a special mode where it scans the source path for any `block.json` files and automatically adds any assets that are defined in there via the `script`, `editorScript`, `viewScript`, `style`, `editorStyle` keys with webpack. +If your project includes blocks there are quite a few assets that need to be added to the list of entry points for Webpack to transpile. This can get quite cumbersome and repetitive. To make this easier toolkit has a special mode where it scans the source path for any `block.json` files and automatically adds any assets that are defined in there via the `script`, `editorScript`, `viewScript`, `style`, `editorStyle` keys with webpack. In order to handle `scriptModule` ans `viewScriptModule` the `useScriptModules` mode needs to be enabled. It also automatically moves all files including the `block.json` and PHP files to the `dist/blocks/` folder. @@ -234,6 +234,12 @@ Since 10up-toolkit@6 this mode is on by default. To opt out of this mode you nee By default, the source directory for blocks is `./includes/blocks/`. This can be customized via the `blocksDir` key in the paths' config. +### WordPress Script Module Handling + +Since WordPress 6.5 ESM scripts are now officially supported. In fact, they are required in order to use some new features such as the Interactivity API. In WordPress these script modules need to coexist with commonJs scripts though. So it's not as easy as just switching the entire toolkit mode to output ESM instead of commonJS. + +Since Toolkit 6.1 it is possible to enable `useScriptModules` in the toolkit config. This mode allows you to have both commonJS and ESM scripts at the same time. Any existing entrypoints will continue to work as before. But a new `moduleEntry` key now allows for adding any additional ESM entrypoints to the toolkit config. Additionally any `scriptModule` & `viewScriptModule` files references inside `block.json` files will also get picked up and built as ESM scripts. + ### WordPress Editor Styles By default, 10up-toolkit will scope any css file named `editor-style.css` files with the @@ -568,6 +574,9 @@ config.plugins.push( module.exports = config; ``` +> [!NOTE] +> When `useScriptModules` mode is enabled the config returned from webpack here changes from an object to an array of two objects. The first one is the scripts config which matches the traditional structure. And the second object is the config for the ESM instance. + ### Customizing eslint and styling To customize eslint, create a supported eslint config file at the root of your project. Make sure to extend the `@10up/eslint-config` package. @@ -816,6 +825,11 @@ To override, use the `-f` or `--format` option 10up-toolkit build -f=commonjs ``` +There also is a special mode for outputting both CommonJS and ESM assets at the same time. It can be enabled via the `useScriptModules` flag in the toolkit settings and enables you to define any module entrypoints via the `moduleEntry` key in the settings. At the same time enabling this flag also means that the `scriptModule` & `viewScriptModule` keys in `block.json` files automatically get built as modules. + +> [!NOTE] +> Enabling has the side-effect that toolkit now needs to run two separate webpack instances. So the webpack config changes from an object to an array of objects. This is important to watch out for if you have a custom `webpack.config.js` file in your project and are customizing webpack yourself. + ### Externals This option is only useful in package mode and is used to override the webpack externals definitions. In package mode, the From 74b5522453bb15cddfc641689b13270d933923a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Ka=CC=88gy?= Date: Mon, 6 May 2024 09:15:32 +0200 Subject: [PATCH 3/7] add documentation for css global data config --- packages/toolkit/README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/packages/toolkit/README.md b/packages/toolkit/README.md index 24728ecb..7055caa2 100644 --- a/packages/toolkit/README.md +++ b/packages/toolkit/README.md @@ -245,6 +245,30 @@ Since Toolkit 6.1 it is possible to enable `useScriptModules` in the toolkit con By default, 10up-toolkit will scope any css file named `editor-style.css` files with the `.editor-styles-wrapper` class. Take a look at the default [postcss config](https://github.com/10up/10up-toolkit/blob/develop/packages/toolkit/config/postcss.config.js#L21) for more information. +## Handling of Global postCSS settings + +With the introduction of block-specific stylesheets, we've started to break out our CSS from one bog monolithic `frontend.css` file into smaller individual files that only get loaded when the specific block is used on the page. + +One downside to this approach however was that any postcss globals such as custom media queries, custom selectors, variables, and mixins defined in the main css file are not available to all the other block-specific stylesheets. + +To fix this Toolkit 6.1 introduces a new way to handle these global settings. There are now two special folders that toolkit watches for. `./assets/css/globals/` and `./assets/css/mixins/`. Any CSS files within these folders or nested within these folders get automatically loaded for all CSS files handled by Webpack. So if you define your custom breakpoints in a `./assets/css/globals/breakpoints.css` file that breakpoint will be available everywhere. + +> [!WARNING] +> Please note that [PostCSS Global Data](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-global-data) does not add anything to the output of your CSS. It only injects data into PostCSS so that other plugins can actually use it. + +If you need to customize the path of these global folders you can do so by modifying the `paths` in the tookit config. + +```json +{ + "10up-toolkit": { + "paths": { + "globalStylesDir": "./assets/css/globals/", + "globalMixinsDir": "./assets/css/mixins/" + } + } +} +``` + ## HMR and Fast Refresh ![react-fast-refresh-toolkit](https://user-images.githubusercontent.com/6104632/155181035-b77a53f8-6a45-454d-934c-5667bbb0f06a.gif) From 3eed064cf11a03d12b96485d100128f9d8688320 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20K=C3=A4gy?= Date: Mon, 6 May 2024 14:16:10 +0200 Subject: [PATCH 4/7] Update packages/toolkit/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Nícholas André --- packages/toolkit/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/toolkit/README.md b/packages/toolkit/README.md index 7055caa2..02f11551 100644 --- a/packages/toolkit/README.md +++ b/packages/toolkit/README.md @@ -219,7 +219,7 @@ Alternatively, you can set up `process.env.ASSET_PATH` to whatever path (or CDN) _NOTE: Since 10up-toolkit@6 this `useBlockAssets` is on by default_ -If your project includes blocks there are quite a few assets that need to be added to the list of entry points for Webpack to transpile. This can get quite cumbersome and repetitive. To make this easier toolkit has a special mode where it scans the source path for any `block.json` files and automatically adds any assets that are defined in there via the `script`, `editorScript`, `viewScript`, `style`, `editorStyle` keys with webpack. In order to handle `scriptModule` ans `viewScriptModule` the `useScriptModules` mode needs to be enabled. +If your project includes blocks there are quite a few assets that need to be added to the list of entry points for Webpack to transpile. This can get quite cumbersome and repetitive. To make this easier toolkit has a special mode where it scans the source path for any `block.json` files and automatically adds any assets that are defined in there via the `script`, `editorScript`, `viewScript`, `style`, `editorStyle` keys with webpack. In order to handle `scriptModule` and `viewScriptModule` the `useScriptModules` mode needs to be enabled. It also automatically moves all files including the `block.json` and PHP files to the `dist/blocks/` folder. From da4b54d49ad890f3acd40d118f7e021ff842d7ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20K=C3=A4gy?= Date: Mon, 6 May 2024 14:16:19 +0200 Subject: [PATCH 5/7] Update packages/toolkit/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Nícholas André --- packages/toolkit/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/toolkit/README.md b/packages/toolkit/README.md index 02f11551..097a7892 100644 --- a/packages/toolkit/README.md +++ b/packages/toolkit/README.md @@ -251,7 +251,7 @@ With the introduction of block-specific stylesheets, we've started to break out One downside to this approach however was that any postcss globals such as custom media queries, custom selectors, variables, and mixins defined in the main css file are not available to all the other block-specific stylesheets. -To fix this Toolkit 6.1 introduces a new way to handle these global settings. There are now two special folders that toolkit watches for. `./assets/css/globals/` and `./assets/css/mixins/`. Any CSS files within these folders or nested within these folders get automatically loaded for all CSS files handled by Webpack. So if you define your custom breakpoints in a `./assets/css/globals/breakpoints.css` file that breakpoint will be available everywhere. +To fix this 10up-toolkit 6.1 introduces a new way to handle these global settings. There are now two special folders that toolkit watches for. `./assets/css/globals/` and `./assets/css/mixins/`. Any CSS files within these folders or nested within these folders get automatically loaded for all CSS files handled by Webpack. So if you define your custom breakpoints in a `./assets/css/globals/breakpoints.css` file that breakpoint will be available everywhere. > [!WARNING] > Please note that [PostCSS Global Data](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-global-data) does not add anything to the output of your CSS. It only injects data into PostCSS so that other plugins can actually use it. From 0e1087be39e966a328f4d3c67be96fd0e04ab9ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20K=C3=A4gy?= Date: Mon, 6 May 2024 14:16:24 +0200 Subject: [PATCH 6/7] Update packages/toolkit/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Nícholas André --- packages/toolkit/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/toolkit/README.md b/packages/toolkit/README.md index 097a7892..7a613f8a 100644 --- a/packages/toolkit/README.md +++ b/packages/toolkit/README.md @@ -238,7 +238,7 @@ By default, the source directory for blocks is `./includes/blocks/`. This can be Since WordPress 6.5 ESM scripts are now officially supported. In fact, they are required in order to use some new features such as the Interactivity API. In WordPress these script modules need to coexist with commonJs scripts though. So it's not as easy as just switching the entire toolkit mode to output ESM instead of commonJS. -Since Toolkit 6.1 it is possible to enable `useScriptModules` in the toolkit config. This mode allows you to have both commonJS and ESM scripts at the same time. Any existing entrypoints will continue to work as before. But a new `moduleEntry` key now allows for adding any additional ESM entrypoints to the toolkit config. Additionally any `scriptModule` & `viewScriptModule` files references inside `block.json` files will also get picked up and built as ESM scripts. +Since Toolkit 6.1 it is possible to enable `useScriptModules` in the toolkit config. This mode allows you to have both CommonJS and ESM scripts at the same time. Any existing entrypoints will continue to work as before. But a new `moduleEntry` key now allows for adding any additional ESM entrypoints to the toolkit config. Additionally any `scriptModule` & `viewScriptModule` files references inside `block.json` files will also get picked up and built as ESM scripts. ### WordPress Editor Styles From 1f2c329ed75d00f115934ada7cb31cf54a10661f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Ka=CC=88gy?= Date: Mon, 6 May 2024 16:35:15 +0200 Subject: [PATCH 7/7] add code example --- packages/toolkit/README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/packages/toolkit/README.md b/packages/toolkit/README.md index 7a613f8a..54b566e1 100644 --- a/packages/toolkit/README.md +++ b/packages/toolkit/README.md @@ -600,6 +600,25 @@ module.exports = config; > [!NOTE] > When `useScriptModules` mode is enabled the config returned from webpack here changes from an object to an array of two objects. The first one is the scripts config which matches the traditional structure. And the second object is the config for the ESM instance. +> ```js +> // webpack.config.js +> const config = require("10up-toolkit/config/webpack.config.js"); +> const ProjectSpecificPlugin = require("project-specific-plugin"); +> +> // We can now either add it to the first standard config +> config[0].plugins.push( +> // Append project specific plugin config. +> new ProjectSpecificPlugin() +> ); +> +> // or to the second module specific config +> config[1].plugins.push( +> // Append project specific plugin config. +> new ProjectSpecificPlugin() +> ); +> +> module.exports = config; +>``` ### Customizing eslint and styling