diff --git a/packages/README.md b/packages/README.md index 27efdf2d43ad5..cc2f34e38ac05 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 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 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 + { + "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 be included if the package exposes both a script and a script module. + 1. `README.md` file containing at least: - Package name - Package description diff --git a/packages/block-library/README.md b/packages/block-library/README.md index 28cf7471ed1f1..a6d1984cda98c 100644 --- a/packages/block-library/README.md +++ b/packages/block-library/README.md @@ -98,21 +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: +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 { - "viewScript": "file:./view.min.js" + "name": "@wordpress/block-library", + "wpScriptModuleExports": { + "./blinking-paragraph/view": "./build-module/blinking-paragraph/view.js", + "./image/view": "./build-module/image/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;