Scripts: Recommend passing JS entry points with paths

packages/scripts/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Enhancements
+
+-   Recommend listing JavaScript entry points as paths passed to the `start` and `build` commands ([#68251](https://github.com/WordPress/gutenberg/pull/68251)).
+-   Introduce a new option `--source-path` to customize the source directory used with the `start` and `build` commands ([#68251](https://github.com/WordPress/gutenberg/pull/68251)).
+
 ## 30.7.0 (2024-12-11)
 
 ### Internal

packages/scripts/config/webpack.config.js

@@ -29,7 +29,7 @@ const {
 	hasArgInCLI,
 	hasCssnanoConfig,
 	hasPostCSSConfig,
-	getWordPressSrcDirectory,
+	getProjectSourcePath,
 	getWebpackEntryPoints,
 	getAsBooleanFromENV,
 	getBlockJsonModuleFields,
@@ -302,14 +302,14 @@ const scriptConfig = {
 			} ),
 
 		new PhpFilePathsPlugin( {
-			context: getWordPressSrcDirectory(),
+			context: getProjectSourcePath(),
 			props: [ 'render', 'variations' ],
 		} ),
 		new CopyWebpackPlugin( {
 			patterns: [
 				{
 					from: '**/block.json',
-					context: getWordPressSrcDirectory(),
+					context: getProjectSourcePath(),
 					noErrorOnMissing: true,
 					transform( content, absoluteFrom ) {
 						const convertExtension = ( path ) => {
@@ -346,7 +346,7 @@ const scriptConfig = {
 								const runtimePath = relative(
 									dirname( absoluteFrom ),
 									fromProjectRoot(
-										getWordPressSrcDirectory() +
+										getProjectSourcePath() +
 											sep +
 											'runtime.js'
 									)
@@ -375,7 +375,7 @@ const scriptConfig = {
 				},
 				{
 					from: '**/*.php',
-					context: getWordPressSrcDirectory(),
+					context: getProjectSourcePath(),
 					noErrorOnMissing: true,
 					filter: ( filepath ) => {
 						return (
@@ -417,7 +417,7 @@ if ( hasExperimentalModulesFlag ) {
 			/** @type {ReadonlyArray<string>} */
 			this.blockJsonFiles = glob( '**/block.json', {
 				absolute: true,
-				cwd: fromProjectRoot( getWordPressSrcDirectory() ),
+				cwd: fromProjectRoot( getProjectSourcePath() ),
 			} );
 		}
 

packages/scripts/scripts/build.js

@@ -7,31 +7,11 @@ const { sync: resolveBin } = require( 'resolve-bin' );
 /**
  * Internal dependencies
  */
-const { getWebpackArgs, hasArgInCLI, getArgFromCLI } = require( '../utils' );
+const { getWebpackArgs } = require( '../utils' );
 const EXIT_ERROR_CODE = 1;
 
 process.env.NODE_ENV = process.env.NODE_ENV || 'production';
 
-if ( hasArgInCLI( '--experimental-modules' ) ) {
-	process.env.WP_EXPERIMENTAL_MODULES = true;
-}
-
-if ( hasArgInCLI( '--webpack-no-externals' ) ) {
-	process.env.WP_NO_EXTERNALS = true;
-}
-
-if ( hasArgInCLI( '--webpack-bundle-analyzer' ) ) {
-	process.env.WP_BUNDLE_ANALYZER = true;
-}
-
-if ( hasArgInCLI( '--webpack-copy-php' ) ) {
-	process.env.WP_COPY_PHP_FILES_TO_DIST = true;
-}
-
-process.env.WP_SRC_DIRECTORY = hasArgInCLI( '--webpack-src-dir' )
-	? getArgFromCLI( '--webpack-src-dir' )
-	: 'src';
-
 const { status } = spawn( resolveBin( 'webpack' ), getWebpackArgs(), {
 	stdio: 'inherit',
 } );

packages/scripts/scripts/start.js

@@ -7,33 +7,9 @@ const { sync: resolveBin } = require( 'resolve-bin' );
 /**
  * Internal dependencies
  */
-const { getArgFromCLI, getWebpackArgs, hasArgInCLI } = require( '../utils' );
+const { getWebpackArgs, hasArgInCLI } = require( '../utils' );
 const EXIT_ERROR_CODE = 1;
 
-if ( hasArgInCLI( '--experimental-modules' ) ) {
-	process.env.WP_EXPERIMENTAL_MODULES = true;
-}
-
-if ( hasArgInCLI( '--webpack-no-externals' ) ) {
-	process.env.WP_NO_EXTERNALS = true;
-}
-
-if ( hasArgInCLI( '--webpack-bundle-analyzer' ) ) {
-	process.env.WP_BUNDLE_ANALYZER = true;
-}
-
-if ( hasArgInCLI( '--webpack--devtool' ) ) {
-	process.env.WP_DEVTOOL = getArgFromCLI( '--webpack--devtool' );
-}
-
-if ( hasArgInCLI( '--webpack-copy-php' ) ) {
-	process.env.WP_COPY_PHP_FILES_TO_DIST = true;
-}
-
-process.env.WP_SRC_DIRECTORY = hasArgInCLI( '--webpack-src-dir' )
-	? getArgFromCLI( '--webpack-src-dir' )
-	: 'src';
-
 const webpackArgs = getWebpackArgs();
 if ( hasArgInCLI( '--hot' ) ) {
 	webpackArgs.unshift( 'serve' );

packages/scripts/utils/config.js

@@ -9,6 +9,7 @@ const { sync: glob } = require( 'fast-glob' );
  * Internal dependencies
  */
 const {
+	getArgFromCLI,
 	getArgsFromCLI,
 	getFileArgsFromCLI,
 	hasArgInCLI,
@@ -114,9 +115,37 @@ const getWebpackArgs = () => {
 	// Gets all args from CLI without those prefixed with `--webpack`.
 	let webpackArgs = getArgsFromCLI( [
 		'--experimental-modules',
+		'--source-path',
 		'--webpack',
 	] );
 
+	if ( hasArgInCLI( '--experimental-modules' ) ) {
+		process.env.WP_EXPERIMENTAL_MODULES = true;
+	}
+
+	if ( hasArgInCLI( '--source-path' ) ) {
+		process.env.WP_SOURCE_PATH = getArgFromCLI( '--source-path' );
+	} else if ( hasArgInCLI( '--webpack-src-dir' ) ) {
+		// Backwards compatibility.
+		process.env.WP_SOURCE_PATH = getArgFromCLI( '--webpack-src-dir' );
+	}
+
+	if ( hasArgInCLI( '--webpack-bundle-analyzer' ) ) {
+		process.env.WP_BUNDLE_ANALYZER = true;
+	}
+
+	if ( hasArgInCLI( '--webpack-copy-php' ) ) {
+		process.env.WP_COPY_PHP_FILES_TO_DIST = true;
+	}
+
+	if ( hasArgInCLI( '--webpack--devtool' ) ) {
+		process.env.WP_DEVTOOL = getArgFromCLI( '--webpack--devtool' );
+	}
+
+	if ( hasArgInCLI( '--webpack-no-externals' ) ) {
+		process.env.WP_NO_EXTERNALS = true;
+	}
+
 	const hasWebpackOutputOption =
 		hasArgInCLI( '-o' ) || hasArgInCLI( '--output' );
 	if (
@@ -136,10 +165,6 @@ const getWebpackArgs = () => {
 		const pathToEntry = ( path ) => {
 			const entryName = basename( path, '.js' );
 
-			if ( ! path.startsWith( './' ) ) {
-				path = './' + path;
-			}
-
 			return [ entryName, path ];
 		};
 
@@ -162,7 +187,11 @@ const getWebpackArgs = () => {
 				const [ entryName, path ] = fileArg.includes( '=' )
 					? fileArg.split( '=' )
 					: pathToEntry( fileArg );
-				entry[ entryName ] = path;
+				entry[ entryName ] = fromProjectRoot(
+					process.env.WP_SOURCE_PATH
+						? join( process.env.WP_SOURCE_PATH, path )
+						: path
+				);
 			} );
 			process.env.WP_ENTRY = JSON.stringify( entry );
 		}
@@ -176,20 +205,20 @@ const getWebpackArgs = () => {
 };
 
 /**
- * Returns the WordPress source directory. It defaults to 'src' if the
- * `process.env.WP_SRC_DIRECTORY` variable is not set.
+ * Returns the project source path. It defaults to 'src' if the
+ * `process.env.WP_SOURCE_PATH` variable is not set.
  *
  * @return {string} The WordPress source directory.
  */
-function getWordPressSrcDirectory() {
-	return process.env.WP_SRC_DIRECTORY || 'src';
+function getProjectSourcePath() {
+	return process.env.WP_SOURCE_PATH || 'src';
 }
 
 /**
- * Detects the list of entry points to use with webpack. There are three ways to do this:
- *  1. Use the legacy webpack 4 format passed as CLI arguments.
- *  2. Scan `block.json` files for scripts.
- *  3. Fallback to `src/index.*` file.
+ * Detects the list of entry points to use with webpack. There are three alternative ways to do this:
+ *  1. Use the recommended command format that lists the paths to JavaScript files.
+ *  2. Scan `block.json` files to detect referenced JavaScript and PHP files automatically.
+ *  3. Fallback to the `src/index.*` file.
  *
  * @see https://webpack.js.org/concepts/entry-points/
  *
@@ -200,31 +229,32 @@ function getWebpackEntryPoints( buildType ) {
 	 * @return {Object<string,string>} The list of entry points.
 	 */
 	return () => {
-		// 1. Handles the legacy format for entry points when explicitly provided with the `process.env.WP_ENTRY`.
+		// 1. Uses the recommended command format that lists entry points as paths to JavaScript files.
+		//    Example: `wp-scripts build one.js two.js`.
 		if ( process.env.WP_ENTRY ) {
 			return buildType === 'script'
 				? JSON.parse( process.env.WP_ENTRY )
 				: {};
 		}
 
-		// Continue only if the source directory exists.
-		if ( ! hasProjectFile( getWordPressSrcDirectory() ) ) {
+		// Continues only if the source directory exists. Defaults to "src" if not explicitly set in the command.
+		if ( ! hasProjectFile( getProjectSourcePath() ) ) {
 			warn(
-				`Source directory "${ getWordPressSrcDirectory() }" was not found. Please confirm there is a "src" directory in the root or the value passed to --webpack-src-dir is correct.`
+				`Source directory "${ getProjectSourcePath() }" was not found. Please confirm there is a "src" directory in the root or the value passed with "--output-path" is correct.`
 			);
 			return {};
 		}
 
 		// 2. Checks whether any block metadata files can be detected in the defined source directory.
-		//    It scans all discovered files looking for JavaScript assets and converts them to entry points.
+		//    It scans all discovered files, looks for JavaScript assets, and converts them to entry points.
 		const blockMetadataFiles = glob( '**/block.json', {
 			absolute: true,
-			cwd: fromProjectRoot( getWordPressSrcDirectory() ),
+			cwd: fromProjectRoot( getProjectSourcePath() ),
 		} );
 
 		if ( blockMetadataFiles.length > 0 ) {
 			const srcDirectory = fromProjectRoot(
-				getWordPressSrcDirectory() + sep
+				getProjectSourcePath() + sep
 			);
 
 			const entryPoints = {};
@@ -276,7 +306,7 @@ function getWebpackEntryPoints( buildType ) {
 							) }" listed in "${ blockMetadataFile.replace(
 								fromProjectRoot( sep ),
 								''
-							) }". File is located outside of the "${ getWordPressSrcDirectory() }" directory.`
+							) }". File is located outside of the "${ getProjectSourcePath() }" directory.`
 						);
 						continue;
 					}
@@ -290,7 +320,7 @@ function getWebpackEntryPoints( buildType ) {
 						`${ entryName }.?(m)[jt]s?(x)`,
 						{
 							absolute: true,
-							cwd: fromProjectRoot( getWordPressSrcDirectory() ),
+							cwd: fromProjectRoot( getProjectSourcePath() ),
 						}
 					);
 
@@ -302,7 +332,7 @@ function getWebpackEntryPoints( buildType ) {
 							) }" listed in "${ blockMetadataFile.replace(
 								fromProjectRoot( sep ),
 								''
-							) }". File does not exist in the "${ getWordPressSrcDirectory() }" directory.`
+							) }". File does not exist in the "${ getProjectSourcePath() }" directory.`
 						);
 						continue;
 					}
@@ -322,15 +352,15 @@ function getWebpackEntryPoints( buildType ) {
 		}
 
 		// 3. Checks whether a standard file name can be detected in the defined source directory,
-		//  and converts the discovered file to entry point.
+		//    and converts the discovered file to entry point.
 		const [ entryFile ] = glob( 'index.[jt]s?(x)', {
 			absolute: true,
-			cwd: fromProjectRoot( getWordPressSrcDirectory() ),
+			cwd: fromProjectRoot( getProjectSourcePath() ),
 		} );
 
 		if ( ! entryFile ) {
 			warn(
-				`No entry file discovered in the "${ getWordPressSrcDirectory() }" directory.`
+				`No entry file discovered in the "${ getProjectSourcePath() }" directory.`
 			);
 			return {};
 		}
@@ -412,10 +442,10 @@ function getPhpFilePaths( context, props ) {
 
 module.exports = {
 	getJestOverrideConfigFile,
+	getPhpFilePaths,
+	getProjectSourcePath,
 	getWebpackArgs,
-	getWordPressSrcDirectory,
 	getWebpackEntryPoints,
-	getPhpFilePaths,
 	hasBabelConfig,
 	hasCssnanoConfig,
 	hasJestConfig,

packages/scripts/utils/index.js

@@ -13,10 +13,10 @@ const {
 } = require( './cli' );
 const {
 	getJestOverrideConfigFile,
+	getPhpFilePaths,
+	getProjectSourcePath,
 	getWebpackArgs,
-	getWordPressSrcDirectory,
 	getWebpackEntryPoints,
-	getPhpFilePaths,
 	hasBabelConfig,
 	hasCssnanoConfig,
 	hasJestConfig,
@@ -41,10 +41,10 @@ module.exports = {
 	getJestOverrideConfigFile,
 	getNodeArgsFromCLI,
 	getPackageProp,
+	getPhpFilePaths,
+	getProjectSourcePath,
 	getWebpackArgs,
-	getWordPressSrcDirectory,
 	getWebpackEntryPoints,
-	getPhpFilePaths,
 	getBlockJsonModuleFields,
 	getBlockJsonScriptFields,
 	hasArgInCLI,