@wordpress/dependency-extraction-webpack-plugin 4.30.0 → 5.0.0

package/LICENSE.md

@@ -1,6 +1,6 @@
 ## Gutenberg
 
-    Copyright 2016-2023 by the contributors
+    Copyright 2016-2024 by the contributors
 
 **License for Contributions (on and after April 15, 2021)**
 

package/README.md

@@ -2,11 +2,15 @@
 
 This webpack plugin serves two purposes:
 
--   Externalize dependencies that are available as script dependencies on modern WordPress sites.
--   Add an asset file for each entry point that declares an object with the list of WordPress script dependencies for the entry point. The asset file also contains the current version calculated for the current source code.
+-   Externalize dependencies that are available as shared scripts or modules on WordPress sites.
+-   Add an asset file for each entry point that declares an object with the list of WordPress script or module dependencies for the entry point. The asset file also contains the current version calculated for the current source code.
 
 This allows JavaScript bundles produced by webpack to leverage WordPress style dependency sharing without an error-prone process of manually maintaining a dependency list.
 
+Version 5 of this plugin adds support for module bundling. [Webpack's `output.module` option](https://webpack.js.org/configuration/output/#outputmodule) should
+be used to opt-in to this behavior. This plugin will adapt it's behavior based on the
+`output.module` option, producing an asset file suitable for use with the WordPress Module API.
+
 Consult the [webpack website](https://webpack.js.org) for additional information on webpack concepts.
 
 ## Installation
@@ -17,7 +21,7 @@ Install the module
 npm install @wordpress/dependency-extraction-webpack-plugin --save-dev
 ```
 
-**Note**: This package requires Node.js 14.0.0 or later. It also requires webpack 4.8.3 and newer. It is not compatible with older versions.
+**Note**: This package requires Node.js 18.0.0 or later. It also requires webpack 5.0.0 or newer. It is not compatible with older versions.
 
 ## Usage
 
@@ -39,7 +43,7 @@ module.exports = {
 
 ```js
 const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );
-const config = {
+const webpackConfig = {
 	...defaultConfig,
 	plugins: [
 		...defaultConfig.plugins.filter(
@@ -56,7 +60,9 @@ const config = {
 };
 ```
 
-Each entry point in the webpack bundle will include an asset file that declares the WordPress script dependencies that should be enqueued. Such file also contains the unique version hash calculated based on the file content.
+### Behavior with scripts
+
+Each entry point in the webpack bundle will include an asset file that declares the WordPress script dependencies that should be enqueued. This file also contains the unique version hash calculated based on the file content.
 
 For example:
 
@@ -88,6 +94,68 @@ By default, the following module requests are handled:
 
 This plugin is compatible with `externals`, but they may conflict. For example, adding `{ externals: { '@wordpress/blob': 'wp.blob' } }` to webpack configuration will effectively hide the `@wordpress/blob` module from the plugin and it will not be included in dependency lists.
 
+### Behavior with modules
+
+**Warning:** Modules support is considered experimental at this time.
+
+This section describes the behavior of this package to bundle ECMAScript modules and generate asset
+files suitable for use with the WordPress Modules API.
+
+Some of this plugin's options change, and webpack requires configuration to output modules. Refer to
+[webpack's documentation](https://webpack.js.org/configuration/output/#outputmodule) for up-to-date details.
+
+```js
+const webpackConfig = {
+	...defaultConfig,
+
+	// These lines are necessary to enable module compilation at time-of-writing:
+	output: { module: true },
+	experiments: { outputModule: true },
+
+	plugins: [
+		...defaultConfig.plugins.filter(
+			( plugin ) =>
+				plugin.constructor.name !== 'DependencyExtractionWebpackPlugin'
+		),
+		new DependencyExtractionWebpackPlugin( {
+			// With modules, we use `requestToExternalModule`:
+			requestToExternalModule( request ) {
+				if ( request === 'my-registered-module' ) {
+					return request;
+				}
+			},
+		} ),
+	],
+};
+```
+
+Each entry point in the webpack bundle will include an asset file that declares the WordPress module dependencies that should be enqueued. This file also contains the unique version hash calculated based on the file content.
+
+For example:
+
+```
+// Source file entrypoint.js
+import { store, getContext } from '@wordpress/interactivity';
+
+// Webpack will produce the output output/entrypoint.js
+/* bundled JavaScript output */
+
+// Webpack will also produce output/entrypoint.asset.php declaring script dependencies
+<?php return array('dependencies' => array('@wordpress/interactivity'), 'version' => 'dd4c2dc50d046ed9d4c063a7ca95702f');
+```
+
+By default, the following module requests are handled:
+
+| Request                      |
+| ---------------------------- |
+| `@wordpress/interactivity  ` |
+
+(`@wordpress/interactivity` is currently the only available WordPress module.)
+
+**Note:** This plugin overlaps with the functionality provided by [webpack `externals`](https://webpack.js.org/configuration/externals). This plugin is intended to extract module handles from bundle compilation so that a list of module dependencies does not need to be manually maintained. If you don't need to extract a list of module dependencies, use the `externals` option directly.
+
+This plugin is compatible with `externals`, but they may conflict. For example, adding `{ externals: { '@wordpress/blob': 'wp.blob' } }` to webpack configuration will effectively hide the `@wordpress/blob` module from the plugin and it will not be included in dependency lists.
+
 #### Options
 
 An object can be passed to the constructor to customize the behavior, for example:
@@ -142,6 +210,8 @@ Pass `useDefaults: false` to disable the default request handling.
 
 Force `wp-polyfill` to be included in each entry point's dependency list. This would be the same as adding `import '@wordpress/polyfill';` to each entry point.
 
+**Note**: This option is not available with modules.
+
 ##### `externalizedReport`
 
 -   Type: boolean | string
@@ -152,6 +222,8 @@ You can provide a filename, or set it to `true` to report to a default `external
 
 ##### `requestToExternal`
 
+**Note**: This option is not available with modules. See [`requestToExternalModule`](#requestToExternalModule) for module usage.
+
 -   Type: function
 
 `requestToExternal` allows the module handling to be customized. The function should accept a module request string and may return a string representing the global variable to use. An array of strings may be used to access globals via an object path, e.g. `wp.i18n` may be represented as `[ 'wp', 'i18n' ]`.
@@ -179,8 +251,46 @@ module.exports = {
 };
 ```
 
+##### `requestToExternalModule`
+
+**Note**: This option is only available with modules. See [`requestToExternal`](#requestToExternal) for script usage.
+
+-   Type: function
+
+`requestToExternalModule` allows the module handling to be customized. The function should accept a module request string and may return a string representing the module to use. Often, the module will have the same name.
+
+`requestToExternalModule` provided via configuration has precedence over default external handling. Unhandled requests will be handled by the default unless `useDefaults` is set to `false`.
+
+```js
+/**
+ * Externalize 'my-module'
+ *
+ * @param {string} request Requested module
+ *
+ * @return {(string|boolean|undefined)} Module ID
+ */
+function requestToExternalModule( request ) {
+	// Handle imports like `import myModule from 'my-module'`
+	if ( request === 'my-module' ) {
+		// Import should be of the form `import { something } from "myModule";` in the final bundle.
+		return 'myModule';
+	}
+
+	// If the Module ID in source is the same as the external module, we can return `true`.
+	return request === 'external-module-id-no-change-required';
+}
+
+module.exports = {
+	plugins: [
+		new DependencyExtractionWebpackPlugin( { requestToExternalModule } ),
+	],
+};
+```
+
 ##### `requestToHandle`
 
+**Note**: This option is not available with modules. It has no corresponding module configuration.
+
 -   Type: function
 
 All of the external modules handled by the plugin are expected to be WordPress script dependencies
@@ -233,6 +343,19 @@ $script_url = plugins_url( $script_path, __FILE__ );
 wp_enqueue_script( 'script', $script_url, $script_asset['dependencies'], $script_asset['version'] );
 ```
 
+Or with modules (the Module API is not yet stable):
+
+```php
+$module_path       = 'path/to/module.js';
+$module_asset_path = 'path/to/module.asset.php';
+$module_asset      = file_exists( $module_asset_path )
+	? require( $module_asset_path )
+	: array( 'dependencies' => array(), 'version' => filemtime( $module_path ) );
+$module_url = plugins_url( $module_path, __FILE__ );
+wp_register_module( 'my-module', $module_url, $module_asset['dependencies'], $module_asset['version'] );
+wp_enqueue_module( 'my-module' );
+```
+
 ## Contributing to this package
 
 This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.

package/lib/.eslintrc.json

@@ -1,6 +1,4 @@
 {
-	// Use the default eslint parser. Prevent babel transforms.
-	"parser": "espree",
 	"env": {
 		"node": true
 	}

package/lib/index.js

@@ -3,10 +3,7 @@
  */
 const path = require( 'path' );
 const webpack = require( 'webpack' );
-// In webpack 5 there is a `webpack.sources` field but for webpack 4 we have to fallback to the `webpack-sources` package.
-const { RawSource } = webpack.sources || require( 'webpack-sources' );
 const json2php = require( 'json2php' );
-const isWebpack4 = webpack.version.startsWith( '4.' );
 const { createHash } = webpack.util;
 
 /**
@@ -14,9 +11,13 @@ const { createHash } = webpack.util;
  */
 const {
 	defaultRequestToExternal,
+	defaultRequestToExternalModule,
 	defaultRequestToHandle,
 } = require( './util' );
 
+const { RawSource } = webpack.sources;
+const { AsyncDependenciesBlock } = webpack;
+
 const defaultExternalizedReportFileName = 'externalized-dependencies.json';
 
 class DependencyExtractionWebpackPlugin {
@@ -34,38 +35,65 @@ class DependencyExtractionWebpackPlugin {
 			options
 		);
 
-		/*
+		/**
 		 * Track requests that are externalized.
 		 *
 		 * Because we don't have a closed set of dependencies, we need to track what has
 		 * been externalized so we can recognize them in a later phase when the dependency
 		 * lists are generated.
+		 *
+		 * @type {Set<string>}
 		 */
 		this.externalizedDeps = new Set();
 
-		// Offload externalization work to the ExternalsPlugin.
-		this.externalsPlugin = new webpack.ExternalsPlugin(
-			'window',
-			isWebpack4
-				? this.externalizeWpDeps.bind( this )
-				: this.externalizeWpDepsV5.bind( this )
-		);
+		/**
+		 * Should we use modules. This will be set later to match webpack's
+		 * output.module option.
+		 *
+		 * @type {boolean}
+		 */
+		this.useModules = false;
 	}
 
-	externalizeWpDeps( _context, request, callback ) {
+	/**
+	 * @param {webpack.ExternalItemFunctionData}                             data
+	 * @param { ( err?: null | Error, result?: string | string[] ) => void } callback
+	 */
+	externalizeWpDeps( { request }, callback ) {
 		let externalRequest;
 
-		// Handle via options.requestToExternal first.
-		if ( typeof this.options.requestToExternal === 'function' ) {
-			externalRequest = this.options.requestToExternal( request );
-		}
+		try {
+			// Handle via options.requestToExternal(Module)  first.
+			if ( this.useModules ) {
+				if (
+					typeof this.options.requestToExternalModule === 'function'
+				) {
+					externalRequest =
+						this.options.requestToExternalModule( request );
+
+					// requestToExternalModule allows a boolean shorthand
+					if ( externalRequest === false ) {
+						externalRequest = undefined;
+					}
+					if ( externalRequest === true ) {
+						externalRequest = request;
+					}
+				}
+			} else if ( typeof this.options.requestToExternal === 'function' ) {
+				externalRequest = this.options.requestToExternal( request );
+			}
 
-		// Cascade to default if unhandled and enabled.
-		if (
-			typeof externalRequest === 'undefined' &&
-			this.options.useDefaults
-		) {
-			externalRequest = defaultRequestToExternal( request );
+			// Cascade to default if unhandled and enabled.
+			if (
+				typeof externalRequest === 'undefined' &&
+				this.options.useDefaults
+			) {
+				externalRequest = this.useModules
+					? defaultRequestToExternalModule( request )
+					: defaultRequestToExternal( request );
+			}
+		} catch ( err ) {
+			return callback( err );
 		}
 
 		if ( externalRequest ) {
@@ -77,10 +105,10 @@ class DependencyExtractionWebpackPlugin {
 		return callback();
 	}
 
-	externalizeWpDepsV5( { context, request }, callback ) {
-		return this.externalizeWpDeps( context, request, callback );
-	}
-
+	/**
+	 * @param {string} request
+	 * @return {string} Mapped dependency name
+	 */
 	mapRequestToDependency( request ) {
 		// Handle via options.requestToHandle first.
 		if ( typeof this.options.requestToHandle === 'function' ) {
@@ -102,6 +130,10 @@ class DependencyExtractionWebpackPlugin {
 		return request;
 	}
 
+	/**
+	 * @param {any} asset Asset Data
+	 * @return {string} Stringified asset data suitable for output
+	 */
 	stringify( asset ) {
 		if ( this.options.outputFormat === 'php' ) {
 			return `<?php return ${ json2php(
@@ -112,30 +144,37 @@ class DependencyExtractionWebpackPlugin {
 		return JSON.stringify( asset );
 	}
 
+	/** @type {webpack.WebpackPluginInstance['apply']} */
 	apply( compiler ) {
+		this.useModules = Boolean( compiler.options.output?.module );
+
+		/**
+		 * Offload externalization work to the ExternalsPlugin.
+		 * @type {webpack.ExternalsPlugin}
+		 */
+		this.externalsPlugin = new webpack.ExternalsPlugin(
+			this.useModules ? 'import' : 'window',
+			this.externalizeWpDeps.bind( this )
+		);
+
 		this.externalsPlugin.apply( compiler );
 
-		if ( isWebpack4 ) {
-			compiler.hooks.emit.tap( this.constructor.name, ( compilation ) =>
-				this.addAssets( compilation )
-			);
-		} else {
-			compiler.hooks.thisCompilation.tap(
-				this.constructor.name,
-				( compilation ) => {
-					compilation.hooks.processAssets.tap(
-						{
-							name: this.constructor.name,
-							stage: compiler.webpack.Compilation
-								.PROCESS_ASSETS_STAGE_ANALYSE,
-						},
-						() => this.addAssets( compilation )
-					);
-				}
-			);
-		}
+		compiler.hooks.thisCompilation.tap(
+			this.constructor.name,
+			( compilation ) => {
+				compilation.hooks.processAssets.tap(
+					{
+						name: this.constructor.name,
+						stage: compiler.webpack.Compilation
+							.PROCESS_ASSETS_STAGE_ANALYSE,
+					},
+					() => this.addAssets( compilation )
+				);
+			}
+		);
 	}
 
+	/** @param {webpack.Compilation} compilation */
 	addAssets( compilation ) {
 		const {
 			combineAssets,
@@ -174,28 +213,53 @@ class DependencyExtractionWebpackPlugin {
 		for ( const chunk of entrypointChunks ) {
 			const chunkFiles = Array.from( chunk.files );
 
-			const chunkJSFile = chunkFiles.find( ( f ) => /\.js$/i.test( f ) );
+			const jsExtensionRegExp = this.useModules ? /\.m?js$/i : /\.js$/i;
+
+			const chunkJSFile = chunkFiles.find( ( f ) =>
+				jsExtensionRegExp.test( f )
+			);
 			if ( ! chunkJSFile ) {
 				// There's no JS file in this chunk, no work for us. Typically a `style.css` from cache group.
 				continue;
 			}
 
-			const chunkDeps = new Set();
+			/** @type {Set<string>} */
+			const chunkStaticDeps = new Set();
+			/** @type {Set<string>} */
+			const chunkDynamicDeps = new Set();
+
 			if ( injectPolyfill ) {
-				chunkDeps.add( 'wp-polyfill' );
+				chunkStaticDeps.add( 'wp-polyfill' );
 			}
 
-			const processModule = ( { userRequest } ) => {
+			/**
+			 * @param {webpack.Module} m
+			 */
+			const processModule = ( m ) => {
+				const { userRequest } = m;
 				if ( this.externalizedDeps.has( userRequest ) ) {
-					chunkDeps.add( this.mapRequestToDependency( userRequest ) );
+					if ( this.useModules ) {
+						const isStatic =
+							DependencyExtractionWebpackPlugin.hasStaticDependencyPathToRoot(
+								compilation,
+								m
+							);
+
+						( isStatic ? chunkStaticDeps : chunkDynamicDeps ).add(
+							m.request
+						);
+					} else {
+						chunkStaticDeps.add(
+							this.mapRequestToDependency( userRequest )
+						);
+					}
 				}
 			};
 
 			// Search for externalized modules in all chunks.
-			const modulesIterable = isWebpack4
-				? chunk.modulesIterable
-				: compilation.chunkGraph.getChunkModules( chunk );
-			for ( const chunkModule of modulesIterable ) {
+			for ( const chunkModule of compilation.chunkGraph.getChunkModulesIterable(
+				chunk
+			) ) {
 				processModule( chunkModule );
 				// Loop through submodules of ConcatenatedModule.
 				if ( chunkModule.modules ) {
@@ -224,11 +288,20 @@ class DependencyExtractionWebpackPlugin {
 				.slice( 0, hashDigestLength );
 
 			const assetData = {
-				// Get a sorted array so we can produce a stable, stringified representation.
-				dependencies: Array.from( chunkDeps ).sort(),
+				dependencies: [
+					// Sort these so we can produce a stable, stringified representation.
+					...Array.from( chunkStaticDeps ).sort(),
+					...Array.from( chunkDynamicDeps )
+						.sort()
+						.map( ( id ) => ( { id, type: 'dynamic' } ) ),
+				],
 				version: contentHash,
 			};
 
+			if ( this.useModules ) {
+				assetData.type = 'module';
+			}
+
 			if ( combineAssets ) {
 				combinedAssetsData[ chunkJSFile ] = assetData;
 				continue;
@@ -246,14 +319,14 @@ class DependencyExtractionWebpackPlugin {
 					'.asset.' + ( outputFormat === 'php' ? 'php' : 'json' );
 				assetFilename = compilation
 					.getPath( '[file]', { filename: chunkJSFile } )
-					.replace( /\.js$/i, suffix );
+					.replace( /\.m?js$/i, suffix );
 			}
 
 			// Add source and file into compilation for webpack to output.
 			compilation.assets[ assetFilename ] = new RawSource(
 				this.stringify( assetData )
 			);
-			chunk.files[ isWebpack4 ? 'push' : 'add' ]( assetFilename );
+			chunk.files.add( assetFilename );
 		}
 
 		if ( combineAssets ) {
@@ -275,6 +348,58 @@ class DependencyExtractionWebpackPlugin {
 			);
 		}
 	}
+
+	/**
+	 * Can we trace a line of static dependencies from an entry to a module
+	 *
+	 * @param {webpack.Compilation}       compilation
+	 * @param {webpack.DependenciesBlock} block
+	 *
+	 * @return {boolean} True if there is a static import path to the root
+	 */
+	static hasStaticDependencyPathToRoot( compilation, block ) {
+		const incomingConnections = [
+			...compilation.moduleGraph.getIncomingConnections( block ),
+		].filter(
+			( connection ) =>
+				// Library connections don't have a dependency, this is a root
+				connection.dependency &&
+				// Entry dependencies are another root
+				connection.dependency.constructor.name !== 'EntryDependency'
+		);
+
+		// If we don't have non-entry, non-library incoming connections,
+		// we've reached a root of
+		if ( ! incomingConnections.length ) {
+			return true;
+		}
+
+		const staticDependentModules = incomingConnections.flatMap(
+			( connection ) => {
+				const { dependency } = connection;
+				const parentBlock =
+					compilation.moduleGraph.getParentBlock( dependency );
+
+				return parentBlock.constructor.name !==
+					AsyncDependenciesBlock.name
+					? [ compilation.moduleGraph.getParentModule( dependency ) ]
+					: [];
+			}
+		);
+
+		// All the dependencies were Async, the module was reached via a dynamic import
+		if ( ! staticDependentModules.length ) {
+			return false;
+		}
+
+		// Continue to explore any static dependencies
+		return staticDependentModules.some( ( parentStaticDependentModule ) =>
+			DependencyExtractionWebpackPlugin.hasStaticDependencyPathToRoot(
+				compilation,
+				parentStaticDependentModule
+			)
+		);
+	}
 }
 
 module.exports = DependencyExtractionWebpackPlugin;

package/lib/types.d.ts

@@ -13,6 +13,9 @@ declare interface DependencyExtractionWebpackPluginOptions {
 	outputFormat?: 'php' | 'json';
 	outputFilename?: string | Function;
 	requestToExternal?: ( request: string ) => string | string[] | undefined;
+	requestToExternalModule?: (
+		request: string
+	) => string | boolean | undefined;
 	requestToHandle?: ( request: string ) => string | undefined;
 	combinedOutputFile?: string | null;
 	combineAssets?: boolean;

package/lib/util.js

@@ -1,9 +1,10 @@
 const WORDPRESS_NAMESPACE = '@wordpress/';
 const BUNDLED_PACKAGES = [
+	'@wordpress/dataviews',
 	'@wordpress/icons',
 	'@wordpress/interface',
-	'@wordpress/undo-manager',
 	'@wordpress/sync',
+	'@wordpress/undo-manager',
 ];
 
 /**
@@ -55,6 +56,37 @@ function defaultRequestToExternal( request ) {
 	}
 }
 
+/**
+ * Default request to external module transformation
+ *
+ * Currently only @wordpress/interactivity
+ *
+ * Do not use the boolean shorthand here, it's only handled for the `requestToExternalModule` option.
+ *
+ * @param {string} request Module request (the module name in `import from`) to be transformed
+ * @return {string|Error|undefined} The resulting external definition.
+ *   - Return `undefined` to ignore the request (do not externalize).
+ *   - Return `string` to map the request to an external.
+ *   - Return `Error` to emit an error.
+ */
+function defaultRequestToExternalModule( request ) {
+	if ( request === '@wordpress/interactivity' ) {
+		// This is a special case. Interactivity does not support dynamic imports at this
+		// time. We add the external "module" type to indicate that webpack should
+		// externalize this as a module (instead of our default `import()` external type)
+		// which forces @wordpress/interactivity imports to be hoisted to static imports.
+		return `module ${ request }`;
+	}
+
+	const isWordPressScript = Boolean( defaultRequestToExternal( request ) );
+
+	if ( isWordPressScript ) {
+		throw new Error(
+			`Attempted to use WordPress script in a module: ${ request }, which is not supported yet.`
+		);
+	}
+}
+
 /**
  * Default request to WordPress script handle transformation
  *
@@ -100,5 +132,6 @@ function camelCaseDash( string ) {
 module.exports = {
 	camelCaseDash,
 	defaultRequestToExternal,
+	defaultRequestToExternalModule,
 	defaultRequestToHandle,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/dependency-extraction-webpack-plugin",
-	"version": "4.30.0",
+	"version": "5.0.0",
 	"description": "Extract WordPress script dependencies from webpack bundles.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -20,7 +20,7 @@
 		"url": "https://github.com/WordPress/gutenberg/issues"
 	},
 	"engines": {
-		"node": ">=14"
+		"node": ">=18"
 	},
 	"files": [
 		"lib",
@@ -29,14 +29,13 @@
 	"main": "lib/index.js",
 	"types": "lib/types.d.ts",
 	"dependencies": {
-		"json2php": "^0.0.7",
-		"webpack-sources": "^3.2.2"
+		"json2php": "^0.0.7"
 	},
 	"peerDependencies": {
-		"webpack": "^4.8.3 || ^5.0.0"
+		"webpack": "^5.0.0"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "d98dff8ea96f29cfea045bf964269f46f040d539"
+	"gitHead": "5e6f9caa205d3bfdbac131952b7bf9c6ec60569b"
 }