From ba8423364b7b797434df3f0faf0ef3ca29ac80b2 Mon Sep 17 00:00:00 2001 From: Jon Surrell Date: Thu, 24 Oct 2024 17:58:07 +0200 Subject: [PATCH 1/5] Document package requirements for bundling Document the wpScript and wpScriptModuleExports fields and their purposes. --- packages/README.md | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/packages/README.md b/packages/README.md index 27efdf2d43ad5..c81923786dcf5 100644 --- a/packages/README.md +++ b/packages/README.md @@ -4,10 +4,11 @@ This repository uses [npm workspaces](https://docs.npmjs.com/cli/v10/using-npm/w ## Creating a New Package -When creating a new package, you need to provide at least the following: +When creating a new package, you need to provide at least the following. Packages bundled in Gutenberg or WordPress must include a `wpScript` and or `wpScriptModuleExports` field in their `package.json` file. See the details below. 1. `package.json` based on the template: - ```json + + ```jsonc { "name": "@wordpress/package-name", "version": "1.0.0-prerelease", @@ -32,10 +33,39 @@ When creating a new package, you need to provide at least the following: }, "publishConfig": { "access": "public" - } + }, + // Include this line to include the package as a WordPress script. + "wpScript": true, + // Include this line to include the package as a WordPress script module. + "wpScriptModuleExports": "./build-module/index.js" } ``` + This assumes that your code is located in the `src` folder and will be transpiled with `Babel`. + + For packages that should ship as a WordPress script, include `wpScript: true` in the `package.json` file. This tells the build system to bundle the for use as a WordPress script. + + For packages that should ship as a WordPress script module, include a `wpScriptModuleExports` field the `package.json` file. The value of this field can be a string to use as a single export, or an object with a [shape like the standard `exports` object](https://nodejs.org/docs/latest-v20.x/api/packages.html#subpath-exports): + + ```jsonc + { + "name": "@wordpress/example", + + // The string form exposes the `@wordpress/example` script module. + "wpScriptModuleExports": "./build-module/index.js", + + // Multiple sub-modules can be exposed by providing an object: + "wpScriptModuleExports": { + // Exposed as `@wordpress/example` script module. + ".": "./build-module/index.js", + // Exposed as `@wordpress/example/demo-block/view` script module. + "./demo-block/view": "./build-module/index.js" + } + } + ``` + + Both `wpScript` and `wpScriptModuleExports` may set if the package exposes both a script and a script module. + 1. `README.md` file containing at least: - Package name - Package description From 4d91975137e38329479a8619c46a70adaceb2844 Mon Sep 17 00:00:00 2001 From: Jon Surrell Date: Thu, 24 Oct 2024 18:07:28 +0200 Subject: [PATCH 2/5] Document script-module process for block-library The block-library includes instructions for setting up a new block, document special steps necessary for script modules. --- packages/block-library/README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/packages/block-library/README.md b/packages/block-library/README.md index 28cf7471ed1f1..57be6985c8014 100644 --- a/packages/block-library/README.md +++ b/packages/block-library/README.md @@ -106,6 +106,24 @@ To find out more about contributing to this package or Gutenberg as a whole, ple } ``` + If the block exposes a script module, it must be included in the package's `package.json` file + in the `wpScriptModules` object. This will include the script module when it's bundled for use + in WordPress. See [the packages README for more details.](../README.md): + + ```json + { + "name": "@wordpress/block-library", + "wpScriptModuleExports": { + "./file/view": "./build-module/file/view.js", + "./image/view": "./build-module/image/view.js", + "./navigation/view": "./build-module/navigation/view.js", + "./query/view": "./build-module/query/view.js", + "./search/view": "./build-module/search/view.js" + // Add any new script modules here. + } + } + ``` + This file will get automatically loaded when the static block is present on the front end. For dynamic block, you need to manually enqueue the view script in `render_callback` of the block, example: ```php From 111085e65d55d8adfcd7dd8e0614d35d731dfe3f Mon Sep 17 00:00:00 2001 From: Jon Surrell Date: Thu, 24 Oct 2024 18:16:15 +0200 Subject: [PATCH 3/5] Fix typos and errors --- packages/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/README.md b/packages/README.md index c81923786dcf5..cc2f34e38ac05 100644 --- a/packages/README.md +++ b/packages/README.md @@ -43,9 +43,9 @@ When creating a new package, you need to provide at least the following. Package This assumes that your code is located in the `src` folder and will be transpiled with `Babel`. - For packages that should ship as a WordPress script, include `wpScript: true` in the `package.json` file. This tells the build system to bundle the for use as a WordPress script. + For packages that should ship as a WordPress script, include `wpScript: true` in the `package.json` file. This tells the build system to bundle the package for use as a WordPress script. - For packages that should ship as a WordPress script module, include a `wpScriptModuleExports` field the `package.json` file. The value of this field can be a string to use as a single export, or an object with a [shape like the standard `exports` object](https://nodejs.org/docs/latest-v20.x/api/packages.html#subpath-exports): + For packages that should ship as a WordPress script module, include a `wpScriptModuleExports` field the `package.json` file. The value of this field can be a string to expose a single script module, or an object with a [shape like the standard `exports` object](https://nodejs.org/docs/latest-v20.x/api/packages.html#subpath-exports) to expose multiple script modules from a single package: ```jsonc { @@ -64,7 +64,7 @@ When creating a new package, you need to provide at least the following. Package } ``` - Both `wpScript` and `wpScriptModuleExports` may set if the package exposes both a script and a script module. + Both `wpScript` and `wpScriptModuleExports` may be included if the package exposes both a script and a script module. 1. `README.md` file containing at least: - Package name From 03fb0aa8f063dcca064747c1e08a8d3a8ba5866a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Greg=20Zi=C3=B3=C5=82kowski?= Date: Fri, 25 Oct 2024 10:02:09 +0200 Subject: [PATCH 4/5] Update the steps for exposing a view script module --- packages/block-library/README.md | 23 +++++------------------ 1 file changed, 5 insertions(+), 18 deletions(-) diff --git a/packages/block-library/README.md b/packages/block-library/README.md index 57be6985c8014..a271daf8cc75a 100644 --- a/packages/block-library/README.md +++ b/packages/block-library/README.md @@ -98,39 +98,26 @@ To find out more about contributing to this package or Gutenberg as a whole, ple This file is used when using the option to register individual block from the `@wordpress/block-library` package. -4. If a `view.js` file (or a file prefixed with `view`, e.g. `view-example.js`) is present in the block's directory, this file will be built along other assets, making it available to load from the browser. You only need to reference a `view.min.js` (notice the different file extension) file in the `block.json` file as follows: - - ```json - { - "viewScript": "file:./view.min.js" - } - ``` - - If the block exposes a script module, it must be included in the package's `package.json` file - in the `wpScriptModules` object. This will include the script module when it's bundled for use - in WordPress. See [the packages README for more details.](../README.md): +4. If the block exposes a script module on the front end, it must be included in the package's `package.json` file in the `wpScriptModules` object. This will include the script module when it's bundled for use in WordPress. See [the packages README for more details.](../README.md): ```json { "name": "@wordpress/block-library", "wpScriptModuleExports": { - "./file/view": "./build-module/file/view.js", + "./blinking-paragraph/view": "./build-module/blinking-paragraph/view.js", "./image/view": "./build-module/image/view.js", - "./navigation/view": "./build-module/navigation/view.js", - "./query/view": "./build-module/query/view.js", - "./search/view": "./build-module/search/view.js" // Add any new script modules here. } } ``` - This file will get automatically loaded when the static block is present on the front end. For dynamic block, you need to manually enqueue the view script in `render_callback` of the block, example: + For every dynamic block, you need to manually enqueue the view script module in `render_callback` of the block, example: ```php function render_block_core_blinking_paragraph( $attributes, $content ) { - $should_load_view_script = ! empty( $attributes['isInteractive'] ) && ! wp_script_is( 'wp-block-blinking-paragraph-view' ); + $should_load_view_script = ! empty( $attributes['isInteractive'] ); if ( $should_load_view_script ) { - wp_enqueue_script( 'wp-block-blinking-paragraph-view' ); + wp_enqueue_script_module( '@wordpress/block-library/blinking-paragraph' ); } return $content; From 34e5eb5d3faafdea5eb2137e03f2313471f01869 Mon Sep 17 00:00:00 2001 From: Jon Surrell Date: Fri, 25 Oct 2024 10:35:11 +0200 Subject: [PATCH 5/5] Run docs:build --- packages/block-library/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/block-library/README.md b/packages/block-library/README.md index a271daf8cc75a..a6d1984cda98c 100644 --- a/packages/block-library/README.md +++ b/packages/block-library/README.md @@ -105,7 +105,7 @@ To find out more about contributing to this package or Gutenberg as a whole, ple "name": "@wordpress/block-library", "wpScriptModuleExports": { "./blinking-paragraph/view": "./build-module/blinking-paragraph/view.js", - "./image/view": "./build-module/image/view.js", + "./image/view": "./build-module/image/view.js" // Add any new script modules here. } }