@wordpress/build 0.2.0

package/src/wordpress-externals-plugin.mjs

@@ -0,0 +1,327 @@
+/**
+ * External dependencies
+ */
+import { writeFile, mkdir } from 'fs/promises';
+import path from 'path';
+import { camelCase } from 'change-case';
+
+/**
+ * Internal dependencies
+ */
+import { getPackageInfo } from './package-utils.mjs';
+
+/**
+ * Create WordPress externals plugin for esbuild.
+ * This plugin handles WordPress package externals and vendor libraries,
+ * treating them as external dependencies available via global variables.
+ *
+ * @param {string} packageNamespace Custom package namespace (e.g., 'wordpress', 'my-plugin').
+ * @param {string|false} scriptGlobal Global variable name (e.g., 'wp', 'myPlugin') or false to disable globals.
+ * @param {Object} externalNamespaces Additional namespaces to externalize (e.g., { 'woo': { global: 'woo', handlePrefix: 'woocommerce' } }).
+ * @param {string} handlePrefix Handle prefix for main package (e.g., 'wp', 'mp'). Defaults to packageNamespace.
+ * @return {Function} Function that creates the esbuild plugin instance.
+ */
+export function createWordpressExternalsPlugin(
+	packageNamespace,
+	scriptGlobal,
+	externalNamespaces = {},
+	handlePrefix
+) {
+	/**
+	 * WordPress externals plugin for esbuild.
+	 *
+	 * @param {string}        assetName         Base name for the asset file (e.g., 'index.min').
+	 * @param {string}        buildFormat       Build format: 'iife' for classic scripts, 'esm' for modules.
+	 * @param {Array<string>} extraDependencies Additional dependencies to include in the asset file.
+	 * @return {Object} esbuild plugin object.
+	 */
+	return function wordpressExternalsPlugin(
+		assetName = 'index.min',
+		buildFormat = 'iife',
+		extraDependencies = []
+	) {
+		return {
+			name: 'wordpress-externals',
+			/** @param {import('esbuild').PluginBuild} build */
+			setup( build ) {
+				const dependencies = new Set();
+				const moduleDependencies = new Map();
+
+				/**
+				 * Check if a package import is a script module.
+				 * A package is considered a script module if it has wpScriptModuleExports
+				 * and the specific import path (root or subpath) is declared in wpScriptModuleExports.
+				 *
+				 * @param {import('./package-utils.mjs').PackageJson} packageJson Package.json object.
+				 * @param {string|null}                               subpath     Subpath after package name, or null for root import.
+				 * @return {boolean} True if the import is a script module.
+				 */
+				function isScriptModuleImport( packageJson, subpath ) {
+					const { wpScriptModuleExports } = packageJson;
+
+					if ( ! wpScriptModuleExports ) {
+						return false;
+					}
+
+					// Root import: @wordpress/package-name
+					if ( ! subpath ) {
+						if ( typeof wpScriptModuleExports === 'string' ) {
+							return true;
+						}
+						if (
+							typeof wpScriptModuleExports === 'object' &&
+							wpScriptModuleExports[ '.' ]
+						) {
+							return true;
+						}
+						return false;
+					}
+
+					// Subpath import: @wordpress/package-name/subpath
+					if (
+						typeof wpScriptModuleExports === 'object' &&
+						wpScriptModuleExports[ `./${ subpath }` ]
+					) {
+						return true;
+					}
+
+					return false;
+				}
+
+				// Map of vendor packages to their global variables and handles
+				const vendorExternals = {
+					react: { global: 'React', handle: 'react' },
+					'react-dom': { global: 'ReactDOM', handle: 'react-dom' },
+					'react/jsx-runtime': {
+						global: 'ReactJSXRuntime',
+						handle: 'react-jsx-runtime',
+					},
+					'react/jsx-dev-runtime': {
+						global: 'ReactJSXRuntime',
+						handle: 'react-jsx-runtime',
+					},
+					moment: { global: 'moment', handle: 'moment' },
+					lodash: { global: 'lodash', handle: 'lodash' },
+					'lodash-es': { global: 'lodash', handle: 'lodash' },
+					jquery: { global: 'jQuery', handle: 'jquery' },
+				};
+
+				// Build list of package namespace configurations
+				const packageExternals = [
+					{
+						namespace: 'wordpress',
+						pattern: /^@wordpress\//,
+						globalName: 'wp',
+						handlePrefix: 'wp',
+					},
+				];
+
+				// Add custom namespace if different from wordpress and scriptGlobal is not false
+				if ( packageNamespace && packageNamespace !== 'wordpress' && scriptGlobal !== false ) {
+					packageExternals.push( {
+						namespace: packageNamespace,
+						pattern: new RegExp( `^@${ packageNamespace }/` ),
+						globalName: scriptGlobal,
+						handlePrefix: handlePrefix || packageNamespace,
+					} );
+				}
+
+				// Add additional external namespaces from configuration
+				for ( const [ namespace, config ] of Object.entries( externalNamespaces ) ) {
+					packageExternals.push( {
+						namespace,
+						pattern: new RegExp( `^@${ namespace }/` ),
+						globalName: config.global,
+						handlePrefix: config.handlePrefix || namespace,
+					} );
+				}
+
+				for ( const [ packageName, config ] of Object.entries(
+					vendorExternals
+				) ) {
+					build.onResolve(
+						{
+							filter: new RegExp( `^${ packageName }$` ),
+						},
+						/** @param {import('esbuild').OnResolveArgs} args */
+						( args ) => {
+							dependencies.add( config.handle );
+
+							return {
+								path: args.path,
+								namespace: 'vendor-external',
+								pluginData: { global: config.global },
+							};
+						}
+					);
+				}
+
+				// Handle package namespace externals (wordpress and custom)
+				for ( const externalConfig of packageExternals ) {
+					build.onResolve(
+						{ filter: externalConfig.pattern },
+						/** @param {import('esbuild').OnResolveArgs} args */
+						( args ) => {
+							// Extract package name and subpath from import
+							// e.g., '@wordpress/blocks/sub/path' → packageName='@wordpress/blocks', subpath='sub/path'
+							const parts = args.path.split( '/' );
+							let packageName = args.path;
+							let subpath = null;
+							if ( parts.length > 2 ) {
+								packageName = parts.slice( 0, 2 ).join( '/' );
+								subpath = parts.slice( 2 ).join( '/' );
+							}
+							const shortName = parts[ 1 ];
+							const handle = `${ externalConfig.handlePrefix }-${ shortName }`;
+
+							const packageJson = getPackageInfo( packageName );
+
+							if ( ! packageJson ) {
+								return undefined;
+							}
+
+							let isScriptModule = isScriptModuleImport(
+								packageJson,
+								subpath
+							);
+							let isScript = !! packageJson.wpScript;
+							if ( isScriptModule && isScript ) {
+								// If the package is both a script and a script module, rely on the format being built
+								isScript = buildFormat === 'iife';
+								isScriptModule = buildFormat === 'esm';
+							}
+
+							const kind =
+								args.kind === 'dynamic-import'
+									? 'dynamic'
+									: 'static';
+
+							if ( isScriptModule ) {
+								if ( kind === 'static' ) {
+									moduleDependencies.set( args.path, 'static' );
+								} else if (
+									! moduleDependencies.has( args.path )
+								) {
+									moduleDependencies.set( args.path, 'dynamic' );
+								}
+
+								return {
+									path: args.path,
+									external: true,
+								};
+							}
+
+							if ( isScript ) {
+								dependencies.add( handle );
+
+								return {
+									path: args.path,
+									namespace: 'package-external',
+									pluginData: { globalName: externalConfig.globalName },
+								};
+							}
+
+							return undefined;
+						}
+					);
+				}
+
+				build.onLoad(
+					{ filter: /.*/, namespace: 'vendor-external' },
+					/** @param {import('esbuild').OnLoadArgs} args */
+					( args ) => {
+						const global = args.pluginData.global;
+
+						return {
+							contents: `module.exports = window.${ global };`,
+							loader: 'js',
+						};
+					}
+				);
+
+				build.onLoad(
+					{ filter: /.*/, namespace: 'package-external' },
+					/** @param {import('esbuild').OnLoadArgs} args */
+					( args ) => {
+						const globalName = args.pluginData.globalName;
+						// Extract package name after '@namespace/' prefix
+						// e.g., '@wordpress/blocks' or '@my-plugin/data'
+						const packagePath = args.path.split( '/' ).slice( 1 ).join( '/' );
+						const camelCasedName = camelCase( packagePath );
+
+						return {
+							contents: `module.exports = window.${ globalName }.${ camelCasedName };`,
+							loader: 'js',
+						};
+					}
+				);
+
+				build.onEnd(
+					/** @param {import('esbuild').BuildResult} result */
+					async ( result ) => {
+						if ( result.errors.length > 0 ) {
+							return;
+						}
+
+						// Merge discovered dependencies with extra dependencies
+						const allDependencies = new Set( [
+							...dependencies,
+							...extraDependencies,
+						] );
+
+						const dependenciesString = Array.from( allDependencies )
+							.sort()
+							.map( ( dep ) => `'${ dep }'` )
+							.join( ', ' );
+
+						// Format module dependencies as array of arrays with 'id' and 'import' keys
+						const moduleDependenciesArray = Array.from(
+							moduleDependencies.entries()
+						)
+							.sort( ( [ a ], [ b ] ) => a.localeCompare( b ) )
+							.map(
+								( [ dep, kind ] ) =>
+									`array('id' => '${ dep }', 'import' => '${ kind }')`
+							);
+
+						const moduleDependenciesString =
+							moduleDependenciesArray.length > 0
+								? moduleDependenciesArray.join( ', ' )
+								: '';
+
+						const version = Date.now();
+
+						const parts = [
+							`'dependencies' => array(${ dependenciesString })`,
+						];
+						if ( moduleDependenciesString ) {
+							parts.push(
+								`'module_dependencies' => array(${ moduleDependenciesString })`
+							);
+						}
+						parts.push( `'version' => '${ version }'` );
+						const assetContent = `<?php return array(${ parts.join(
+							', '
+						) });`;
+
+						const outputDir =
+							build.initialOptions.outdir ||
+							path.dirname(
+								build.initialOptions.outfile || 'build'
+							);
+
+						const assetFilePath = path.join(
+							outputDir,
+							`${ assetName }.asset.php`
+						);
+
+						await mkdir( path.dirname( assetFilePath ), {
+							recursive: true,
+						} );
+						await writeFile( assetFilePath, assetContent );
+					}
+				);
+			},
+		};
+	};
+}

package/templates/index.php.template

@@ -0,0 +1,31 @@
+<?php
+/**
+ * Main entry point for auto-generated asset registration.
+ * Do not edit this file manually.
+ *
+ * @package {{PREFIX}}
+ */
+
+// Load version constant.
+$version_file = __DIR__ . '/version.php';
+if ( file_exists( $version_file ) ) {
+	require_once $version_file;
+}
+
+// Load script module registration.
+$modules_file = __DIR__ . '/modules.php';
+if ( file_exists( $modules_file ) ) {
+	require_once $modules_file;
+}
+
+// Load script registration.
+$scripts_file = __DIR__ . '/scripts.php';
+if ( file_exists( $scripts_file ) ) {
+	require_once $scripts_file;
+}
+
+// Load style registration.
+$styles_file = __DIR__ . '/styles.php';
+if ( file_exists( $styles_file ) ) {
+	require_once $styles_file;
+}

package/templates/module-registration.php.template

@@ -0,0 +1,44 @@
+<?php
+/**
+ * Script module registration - Auto-generated by build process.
+ * Do not edit this file manually.
+ *
+ * @package {{PREFIX}}
+ */
+
+if ( ! function_exists( '{{PREFIX}}_register_script_modules' ) ) {
+	/**
+	 * Register all script modules.
+	 */
+	function {{PREFIX}}_register_script_modules() {
+		$modules_dir = __DIR__ . '/modules';
+		$modules_file = $modules_dir . '/index.php';
+
+		if ( ! file_exists( $modules_file ) ) {
+			return;
+		}
+
+		$modules = require $modules_file;
+		$base_url = plugins_url( 'build/modules/', dirname( __FILE__ ) );
+		$extension = defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ? '.js' : '.min.js';
+
+		foreach ( $modules as $module ) {
+			$asset_path = $modules_dir . '/' . $module['asset'];
+			$asset = file_exists( $asset_path ) ? require $asset_path : array();
+
+			wp_register_script_module(
+				$module['id'],
+				$base_url . $module['path'] . $extension,
+				$asset['module_dependencies'] ?? array(),
+				$asset['version'] ?? false,
+				array(
+					'fetchpriority' => 'low',
+					'in_footer'     => true,
+				)
+			);
+		}
+	}
+
+	add_action( 'wp_default_scripts', '{{PREFIX}}_register_script_modules' );
+	remove_action( 'wp_default_scripts', 'wp_default_script_modules' );
+}

package/templates/module-registry.php.template

@@ -0,0 +1,11 @@
+<?php
+/**
+ * Script module registry - Auto-generated by build process.
+ * Do not edit this file manually.
+ *
+ * @package {{PREFIX}}
+ */
+
+return array(
+{{MODULES}}
+);

package/templates/script-registration.php.template

@@ -0,0 +1,87 @@
+<?php
+/**
+ * Script registration - Auto-generated by build process.
+ * Do not edit this file manually.
+ *
+ * @package {{PREFIX}}
+ */
+
+if ( ! function_exists( '{{PREFIX}}_override_script' ) ) {
+	/**
+	 * Registers a script according to `wp_register_script`. Honors this request by
+	 * reassigning internal dependency properties of any script handle already
+	 * registered by that name. It does not deregister the original script, to
+	 * avoid losing inline scripts which may have been attached.
+	 *
+	 * @param WP_Scripts       $scripts   WP_Scripts instance.
+	 * @param string           $handle    Name of the script. Should be unique.
+	 * @param string           $src       Full URL of the script, or path of the script relative to the WordPress root directory.
+	 * @param array            $deps      Optional. An array of registered script handles this script depends on. Default empty array.
+	 * @param string|bool|null $ver       Optional. String specifying script version number, if it has one, which is added to the URL
+	 *                                    as a query string for cache busting purposes. If version is set to false, a version
+	 *                                    number is automatically added equal to current installed WordPress version.
+	 *                                    If set to null, no version is added.
+	 * @param bool             $in_footer Optional. Whether to enqueue the script before </body> instead of in the <head>.
+	 *                                    Default 'false'.
+	 */
+	function {{PREFIX}}_override_script( $scripts, $handle, $src, $deps = array(), $ver = false, $in_footer = false ) {
+		$script = $scripts->query( $handle, 'registered' );
+		if ( $script ) {
+			/*
+			 * In many ways, this is a reimplementation of `wp_register_script` but
+			 * bypassing consideration of whether a script by the given handle had
+			 * already been registered.
+			 */
+
+			// See: `_WP_Dependency::__construct` .
+			$script->src  = $src;
+			$script->deps = $deps;
+			$script->ver  = $ver;
+			$script->args = $in_footer ? 1 : null;
+		} else {
+			$scripts->add( $handle, $src, $deps, $ver, ( $in_footer ? 1 : null ) );
+		}
+
+		if ( in_array( 'wp-i18n', $deps, true ) ) {
+			$scripts->set_translations( $handle );
+		}
+	}
+}
+
+if ( ! function_exists( '{{PREFIX}}_register_package_scripts' ) ) {
+	/**
+	 * Register all package scripts.
+	 */
+	function {{PREFIX}}_register_package_scripts( $scripts ) {
+		$default_version = defined( '{{VERSION_CONSTANT}}' ) && ! SCRIPT_DEBUG ? {{VERSION_CONSTANT}} : time();
+		$extension       = defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ? '.js' : '.min.js';
+
+		$scripts_dir  = __DIR__ . '/scripts';
+		$scripts_file = $scripts_dir . '/index.php';
+
+		if ( ! file_exists( $scripts_file ) ) {
+			return;
+		}
+
+		$scripts_data = require $scripts_file;
+		$plugin_dir   = dirname( __FILE__ );
+
+		foreach ( $scripts_data as $script_data ) {
+			$asset_file   = $scripts_dir . '/' . $script_data['asset'];
+			$asset        = file_exists( $asset_file ) ? require $asset_file : array();
+			$dependencies = $asset['dependencies'] ?? array();
+			$version      = $asset['version'] ?? $default_version;
+
+			{{PREFIX}}_override_script(
+				$scripts,
+				$script_data['handle'],
+				plugins_url( 'build/scripts/' . $script_data['path'] . $extension, $plugin_dir ),
+				$dependencies,
+				$version,
+				true
+			);
+		}
+	}
+
+	add_action( 'wp_default_scripts', '{{PREFIX}}_register_package_scripts' );
+}

package/templates/script-registry.php.template

@@ -0,0 +1,11 @@
+<?php
+/**
+ * Script registry - Auto-generated by build process.
+ * Do not edit this file manually.
+ *
+ * @package {{PREFIX}}
+ */
+
+return array(
+{{SCRIPTS}}
+);

package/templates/style-registration.php.template

@@ -0,0 +1,73 @@
+<?php
+/**
+ * Style registration - Auto-generated by build process.
+ * Do not edit this file manually.
+ *
+ * Note: These styles can be overridden by calling {{PREFIX}}_override_style()
+ * in lib/client-assets.php for complex cases (multiple files, conditional deps, etc.)
+ *
+ * @package {{PREFIX}}
+ */
+
+if ( ! function_exists( '{{PREFIX}}_override_style' ) ) {
+	/**
+	 * Registers a style according to `wp_register_style`. Honors this request by
+	 * deregistering any style by the same handler before registration.
+	 *
+	 * @param WP_Styles        $styles WP_Styles instance.
+	 * @param string           $handle Name of the stylesheet. Should be unique.
+	 * @param string           $src    Full URL of the stylesheet, or path of the stylesheet relative to the WordPress root directory.
+	 * @param array            $deps   Optional. An array of registered stylesheet handles this stylesheet depends on. Default empty array.
+	 * @param string|bool|null $ver    Optional. String specifying stylesheet version number, if it has one, which is added to the URL
+	 *                                 as a query string for cache busting purposes. If version is set to false, a version
+	 *                                 number is automatically added equal to current installed WordPress version.
+	 *                                 If set to null, no version is added.
+	 * @param string           $media  Optional. The media for which this stylesheet has been defined.
+	 *                                 Default 'all'. Accepts media types like 'all', 'print' and 'screen', or media queries like
+	 *                                 '(orientation: portrait)' and '(max-width: 640px)'.
+	 */
+	function {{PREFIX}}_override_style( $styles, $handle, $src, $deps = array(), $ver = false, $media = 'all' ) {
+		$style = $styles->query( $handle, 'registered' );
+		if ( $style ) {
+			$styles->remove( $handle );
+		}
+		$styles->add( $handle, $src, $deps, $ver, $media );
+	}
+}
+
+if ( ! function_exists( '{{PREFIX}}_register_package_styles' ) ) {
+	/**
+	 * Register all package styles (simple cases only).
+	 * Complex cases should be manually registered in lib/client-assets.php.
+	 *
+	 * @param WP_Styles $styles WP_Styles instance.
+	 */
+	function {{PREFIX}}_register_package_styles( $styles ) {
+		$default_version = defined( '{{VERSION_CONSTANT}}' ) && ! SCRIPT_DEBUG ? {{VERSION_CONSTANT}} : time();
+
+		$styles_dir  = __DIR__ . '/styles';
+		$styles_file = $styles_dir . '/index.php';
+
+		if ( ! file_exists( $styles_file ) ) {
+			return;
+		}
+
+		$styles_data = require $styles_file;
+		$plugin_dir  = dirname( __FILE__ );
+
+		foreach ( $styles_data as $style_data ) {
+			{{PREFIX}}_override_style(
+				$styles,
+				$style_data['handle'],
+				plugins_url( 'build/styles/' . $style_data['path'] . '.css', $plugin_dir ),
+				$style_data['dependencies'],
+				$default_version
+			);
+
+			// Enable RTL support (WordPress automatically loads -rtl.css variant)
+			$styles->add_data( $style_data['handle'], 'rtl', 'replace' );
+		}
+	}
+
+	add_action( 'wp_default_styles', '{{PREFIX}}_register_package_styles' );
+}

package/templates/style-registry.php.template

@@ -0,0 +1,11 @@
+<?php
+/**
+ * Style registry - Auto-generated by build process.
+ * Do not edit this file manually.
+ *
+ * @package {{PREFIX}}
+ */
+
+return array(
+{{STYLES}}
+);

package/templates/version.php.template

@@ -0,0 +1,11 @@
+<?php
+/**
+ * Plugin version constant - Auto-generated by build process.
+ * Do not edit this file manually.
+ *
+ * @package {{PREFIX}}
+ */
+
+if ( ! defined( '{{VERSION_CONSTANT}}' ) ) {
+	define( '{{VERSION_CONSTANT}}', '{{VERSION}}' );
+}

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig.json",
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"module": "node16",
+		"moduleResolution": "node16",
+		"esModuleInterop": true,
+		"target": "es2021",
+		"lib": [ "es2021", "ES2020.string" ],
+		"rootDir": ".",
+		"types": [ "node" ],
+
+		// This package isn't published with types.
+		// Don't generate types, this is strictly for validation.
+		"incremental": true,
+		"declarationMap": false,
+		"emitDeclarationOnly": false,
+		"noEmit": true,
+		"outDir": ".cache"
+	},
+	"include": [ "." ],
+	"exclude": [
+		// Excluded to maintain consistency with bin/tsconfig.json
+		// where packages/build.mjs was also excluded
+		"src/build.mjs"
+	]
+}