Documentation: Update documentation about build process changes

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

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;