@wordpress/build 0.2.0 → 0.3.0

package/src/build.mjs

@@ -3,19 +3,15 @@
 /**
  * External dependencies
  */
-import { readFile, writeFile, copyFile, mkdir } from 'fs/promises';
-import { readdirSync } from 'fs';
+import { readFile, writeFile, copyFile, mkdir, unlink } from 'fs/promises';
 import path from 'path';
 import { parseArgs } from 'node:util';
 import esbuild from 'esbuild';
 import glob from 'fast-glob';
 import chokidar from 'chokidar';
-// See https://github.com/WordPress/gutenberg/issues/72136
-// eslint-disable-next-line import/no-unresolved
 import browserslistToEsbuild from 'browserslist-to-esbuild';
-import { sassPlugin } from 'esbuild-sass-plugin';
+import { sassPlugin, postcssModules } from 'esbuild-sass-plugin';
 import postcss from 'postcss';
-import postcssModulesPlugin from 'postcss-modules';
 import autoprefixer from 'autoprefixer';
 import rtlcss from 'rtlcss';
 import cssnano from 'cssnano';
@@ -25,28 +21,42 @@ import { camelCase } from 'change-case';
 /**
  * Internal dependencies
  */
-import { groupByDepth, findScriptsToRebundle } from './dependency-graph.mjs';
+import {
+	groupByDepth,
+	findScriptsToRebundle,
+	findRoutesToRebuild,
+} from './dependency-graph.mjs';
 import {
 	generatePhpFromTemplate,
 	getPhpReplacements,
 } from './php-generator.mjs';
 import { getPackageInfo, getPackageInfoFromFile } from './package-utils.mjs';
 import { createWordpressExternalsPlugin } from './wordpress-externals-plugin.mjs';
+import {
+	getAllRoutes,
+	getRouteFiles,
+	getRouteMetadata,
+	generateContentEntryPoint,
+} from './route-utils.mjs';
 
 const ROOT_DIR = process.cwd();
 const PACKAGES_DIR = path.join( ROOT_DIR, 'packages' );
 const BUILD_DIR = path.join( ROOT_DIR, 'build' );
 
 const SOURCE_EXTENSIONS = '{js,ts,tsx}';
+const ASSET_EXTENSIONS = 'json';
 const IGNORE_PATTERNS = [
 	'**/benchmark/**',
 	'**/{__mocks__,__tests__,test}/**',
 	'**/{storybook,stories}/**',
 	'**/*.native.*',
+	'**/*.ios.*',
+	'**/*.android.*',
 ];
 const TEST_FILE_PATTERNS = [
 	/\/(benchmark|__mocks__|__tests__|test|storybook|stories)\/.+/,
 	/\.(spec|test)\.(js|ts|tsx)$/,
+	/\.(native|ios|android)\.(js|ts|tsx)$/,
 ];
 
 /**
@@ -55,19 +65,23 @@ const TEST_FILE_PATTERNS = [
  * @return {string[]} Array of package names.
  */
 function getAllPackages() {
-	return readdirSync( PACKAGES_DIR, { withFileTypes: true } )
-		.filter( ( dirent ) => dirent.isDirectory() )
-		.map( ( dirent ) => dirent.name );
+	return glob
+		.sync( normalizePath( path.join( PACKAGES_DIR, '*', 'package.json' ) ) )
+		.map( ( packageJsonPath ) =>
+			path.basename( path.dirname( packageJsonPath ) )
+		);
 }
 
 const PACKAGES = getAllPackages();
-const ROOT_PACKAGE_JSON = getPackageInfoFromFile( path.join( ROOT_DIR, 'package.json' ) );
+const ROOT_PACKAGE_JSON = getPackageInfoFromFile(
+	path.join( ROOT_DIR, 'package.json' )
+);
 const WP_PLUGIN_CONFIG = ROOT_PACKAGE_JSON.wpPlugin || {};
 const SCRIPT_GLOBAL = WP_PLUGIN_CONFIG.scriptGlobal;
 const PACKAGE_NAMESPACE = WP_PLUGIN_CONFIG.packageNamespace;
 const HANDLE_PREFIX = WP_PLUGIN_CONFIG.handlePrefix || PACKAGE_NAMESPACE;
 const EXTERNAL_NAMESPACES = WP_PLUGIN_CONFIG.externalNamespaces || {};
-
+const PAGES = WP_PLUGIN_CONFIG.pages || [];
 
 const baseDefine = {
 	'globalThis.IS_GUTENBERG_PLUGIN': JSON.stringify(
@@ -92,20 +106,26 @@ const wordpressExternalsPlugin = createWordpressExternalsPlugin(
 	HANDLE_PREFIX
 );
 
-/**
- * Create emotion babel plugin for esbuild.
- * This plugin enables emotion's babel transformations for proper CSS-in-JS handling.
- *
- * @return {Object} esbuild plugin.
- */
-function emotionBabelPlugin() {
-	return babel( {
-		filter: /\.[jt]sx?$/,
-		config: {
-			plugins: [ '@emotion/babel-plugin' ],
-		},
-	} );
-}
+const styleBundlingPlugins = [
+	// Handle CSS modules (.module.css and .module.scss)
+	sassPlugin( {
+		embedded: true,
+		filter: /\.module\.(css|scss)$/,
+		transform: postcssModules( {
+			generateScopedName: '[name]__[local]__[hash:base64:5]',
+		} ),
+		type: 'style',
+		loadPaths: [ 'node_modules', path.join( PACKAGES_DIR, 'base-styles' ) ],
+	} ),
+	// Handle regular CSS/SCSS files
+	// Note: .module.css and .module.scss already handled by plugin above
+	sassPlugin( {
+		embedded: true,
+		filter: /\.(css|scss)$/,
+		type: 'style',
+		loadPaths: [ 'node_modules', path.join( PACKAGES_DIR, 'base-styles' ) ],
+	} ),
+];
 
 /**
  * Normalize path separators for cross-platform compatibility.
@@ -278,7 +298,9 @@ async function bundlePackage( packageName ) {
 
 		// Check if package matches the namespace and should expose a global
 		const packageFullName = packageJson.name;
-		const matchesNamespace = packageFullName.startsWith( `@${ PACKAGE_NAMESPACE }/` );
+		const matchesNamespace = packageFullName.startsWith(
+			`@${ PACKAGE_NAMESPACE }/`
+		);
 		const shouldExposeGlobal = matchesNamespace && SCRIPT_GLOBAL !== false;
 
 		const globalName = shouldExposeGlobal
@@ -761,6 +783,132 @@ async function generateMainIndexPhp( replacements ) {
 	);
 }
 
+/**
+ * Generate global route registry file.
+ * Creates a single registry with all routes including page metadata.
+ *
+ * @param {Array}                  routes       Array of route objects.
+ * @param {Record<string, string>} replacements PHP template replacements.
+ */
+async function generateRoutesRegistry( routes, replacements ) {
+	if ( routes.length === 0 ) {
+		// No routes to register, skip generating routes registry
+		return;
+	}
+
+	// Generate PHP array entries with page metadata
+	const routeEntries = routes
+		.map( ( route ) => {
+			const hasRouteStr = route.hasRoute ? 'true' : 'false';
+			const hasContentStr = route.hasContent ? 'true' : 'false';
+			return `\tarray(
+		'name'        => '${ route.name }',
+		'path'        => '${ route.path }',
+		'page'        => '${ route.page }',
+		'has_route'   => ${ hasRouteStr },
+		'has_content' => ${ hasContentStr },
+	)`;
+		} )
+		.join( ',\n' );
+
+	// Generate single global registry at build/routes/index.php
+	await generatePhpFromTemplate(
+		'route-registry.php.template',
+		path.join( BUILD_DIR, 'routes', 'index.php' ),
+		{ ...replacements, '{{ROUTES}}': routeEntries }
+	);
+}
+
+/**
+ * Generate routes.php file with route registration logic.
+ * Uses registry pattern with loop-based registration on page init hooks.
+ *
+ * @param {Array}                  routes       Array of route objects.
+ * @param {Record<string, string>} replacements PHP template replacements.
+ */
+async function generateRoutesPhp( routes, replacements ) {
+	if ( routes.length === 0 ) {
+		// No routes to register, skip generating routes.php
+		return;
+	}
+
+	// Generate routes.php from template
+	await generatePhpFromTemplate(
+		'routes-registration.php.template',
+		path.join( BUILD_DIR, 'routes.php' ),
+		{ ...replacements, '{{HANDLE_PREFIX}}': HANDLE_PREFIX }
+	);
+}
+
+/**
+ * Generate page-specific PHP files for all pages.
+ *
+ * @param {Array}                  pageData     Array of page objects with routes.
+ * @param {Record<string, string>} replacements PHP template replacements.
+ */
+async function generatePagesPhp( pageData, replacements ) {
+	if ( pageData.length === 0 ) {
+		// No pages to generate
+		return;
+	}
+
+	// Generate files for each page
+	const pageGenerationPromises = pageData.map( async ( page ) => {
+		// Skip pages with no routes
+		if ( page.routes.length === 0 ) {
+			return;
+		}
+
+		const pageSlugUnderscore = page.slug.replace( /-/g, '_' );
+		const prefixUnderscore = replacements[ '{{PREFIX}}' ].replace(
+			/-/g,
+			'_'
+		);
+
+		const templateReplacements = {
+			...replacements,
+			'{{PAGE_SLUG}}': page.slug,
+			'{{PAGE_SLUG_UNDERSCORE}}': pageSlugUnderscore,
+			'{{PREFIX}}': prefixUnderscore,
+		};
+
+		// Generate both page.php and page-wp-admin.php
+		await Promise.all( [
+			generatePhpFromTemplate(
+				'page.php.template',
+				path.join( BUILD_DIR, 'pages', page.slug, 'page.php' ),
+				templateReplacements
+			),
+			generatePhpFromTemplate(
+				'page-wp-admin.php.template',
+				path.join( BUILD_DIR, 'pages', page.slug, 'page-wp-admin.php' ),
+				templateReplacements
+			),
+		] );
+
+		// Generate empty loader.js (dummy module for dependencies)
+		await writeFile(
+			path.join( BUILD_DIR, 'pages', page.slug, 'loader.js' ),
+			'// Empty module loader for page dependencies\n'
+		);
+	} );
+
+	await Promise.all( pageGenerationPromises );
+
+	// Generate pages.php loader
+	const pageIncludes = pageData
+		.map( ( page ) => {
+			return `require_once __DIR__ . '/pages/${ page.slug }/page.php';\nrequire_once __DIR__ . '/pages/${ page.slug }/page-wp-admin.php';`;
+		} )
+		.join( '\n' );
+
+	await generatePhpFromTemplate(
+		'pages.php.template',
+		path.join( BUILD_DIR, 'pages.php' ),
+		{ ...replacements, '{{PAGE_INCLUDES}}': pageIncludes }
+	);
+}
+
 /**
  * Transpile a single package's source files and copy JSON files.
  *
@@ -789,8 +937,10 @@ async function transpilePackage( packageName ) {
 		}
 	);
 
-	const jsonFiles = await glob(
-		normalizePath( path.join( packageDir, 'src/**/*.json' ) ),
+	const assetFiles = await glob(
+		normalizePath(
+			path.join( packageDir, `src/**/*.${ ASSET_EXTENSIONS }` )
+		),
 		{
 			ignore: IGNORE_PATTERNS,
 		}
@@ -806,7 +956,37 @@ async function transpilePackage( packageName ) {
 	// Check if this is the components package that needs emotion babel plugin.
 	// Ideally we should remove this exception and move away from emotion.
 	const needsEmotionPlugin = packageName === 'components';
-	const plugins = needsEmotionPlugin ? [ emotionBabelPlugin() ] : [];
+	const emotionPlugin = babel( {
+		filter: /\.[jt]sx?$/,
+		config: {
+			plugins: [ '@emotion/babel-plugin' ],
+		},
+	} );
+	const externalizeAllExceptCssPlugin = {
+		name: 'externalize-except-css',
+		setup( build ) {
+			// Externalize all non-CSS imports
+			build.onResolve( { filter: /.*/ }, ( args ) => {
+				// Skip entry points
+				if ( args.kind === 'entry-point' ) {
+					return null;
+				}
+
+				// Let CSS/SCSS files be processed by sassPlugin
+				if ( args.path.match( /\.(css|scss)$/ ) ) {
+					return null;
+				}
+
+				// Externalize everything else (keep imports as-is)
+				return { path: args.path, external: true };
+			} );
+		},
+	};
+	const plugins = [
+		needsEmotionPlugin && emotionPlugin,
+		externalizeAllExceptCssPlugin,
+		...styleBundlingPlugins,
+	].filter( Boolean );
 
 	if ( packageJson.main ) {
 		builds.push(
@@ -814,7 +994,7 @@ async function transpilePackage( packageName ) {
 				entryPoints: srcFiles,
 				outdir: buildDir,
 				outbase: srcDir,
-				bundle: false,
+				bundle: true,
 				platform: 'node',
 				format: 'cjs',
 				sourcemap: true,
@@ -828,13 +1008,13 @@ async function transpilePackage( packageName ) {
 			} )
 		);
 
-		for ( const jsonFile of jsonFiles ) {
-			const relativePath = path.relative( srcDir, jsonFile );
+		for ( const assetFile of assetFiles ) {
+			const relativePath = path.relative( srcDir, assetFile );
 			const destPath = path.join( buildDir, relativePath );
 			const destDir = path.dirname( destPath );
 			builds.push(
 				mkdir( destDir, { recursive: true } ).then( () =>
-					copyFile( jsonFile, destPath )
+					copyFile( assetFile, destPath )
 				)
 			);
 		}
@@ -846,7 +1026,7 @@ async function transpilePackage( packageName ) {
 				entryPoints: srcFiles,
 				outdir: buildModuleDir,
 				outbase: srcDir,
-				bundle: false,
+				bundle: true,
 				platform: 'neutral',
 				format: 'esm',
 				sourcemap: true,
@@ -860,7 +1040,7 @@ async function transpilePackage( packageName ) {
 			} )
 		);
 
-		for ( const jsonFile of jsonFiles ) {
+		for ( const jsonFile of assetFiles ) {
 			const relativePath = path.relative( srcDir, jsonFile );
 			const destPath = path.join( buildModuleDir, relativePath );
 			const destDir = path.dirname( destPath );
@@ -882,9 +1062,9 @@ async function transpilePackage( packageName ) {
 /**
  * Compile styles for a single package.
  *
- * Discovers and compiles SCSS entry points based on package configuration
- * (supporting wpStyleEntryPoints in package.json for custom entry point patterns),
- * and all .module.css files in src/ directory.
+ * Discovers and compiles SCSS entry points based on package configuration,
+ * supporting wpStyleEntryPoints in package.json for custom entry point
+ * patterns.
  *
  * @param {string} packageName Package name.
  * @return {Promise<number|null>} Build time in milliseconds, or null if no styles.
@@ -907,13 +1087,7 @@ async function compileStyles( packageName ) {
 		)
 	);
 
-	// Get CSS modules from anywhere in src/
-	const cssModuleEntries = await glob(
-		normalizePath( path.join( packageDir, 'src/**/*.module.css' ) ),
-		{ ignore: IGNORE_PATTERNS }
-	);
-
-	if ( scssEntries.length === 0 && cssModuleEntries.length === 0 ) {
+	if ( scssEntries.length === 0 ) {
 		return null;
 	}
 
@@ -921,64 +1095,6 @@ async function compileStyles( packageName ) {
 	const buildStyleDir = path.join( packageDir, 'build-style' );
 	const srcDir = path.join( packageDir, 'src' );
 
-	// Process .module.css files and generate JS modules
-	const cssResults = await Promise.all(
-		cssModuleEntries.map( async ( styleEntryPath ) => {
-			const buildDir = path.join( packageDir, 'build' );
-			const buildModuleDir = path.join( packageDir, 'build-module' );
-
-			const cssContent = await readFile( styleEntryPath, 'utf8' );
-			const relativePath = path.relative( srcDir, styleEntryPath );
-
-			let mappings = {};
-			const result = await postcss( [
-				postcssModulesPlugin( {
-					getJSON: ( _, json ) => ( mappings = json ),
-				} ),
-			] ).process( cssContent, { from: styleEntryPath } );
-
-			// Write processed CSS to build-style (preserving directory structure)
-			const cssOutPath = path.join(
-				buildStyleDir,
-				relativePath.replace( '.module.css', '.css' )
-			);
-			await mkdir( path.dirname( cssOutPath ), { recursive: true } );
-			await writeFile( cssOutPath, result.css );
-
-			// Generate JS modules with class name mappings (preserving directory structure)
-			const jsExport = JSON.stringify( mappings );
-			const jsPath = `${ relativePath }.js`;
-			await Promise.all( [
-				mkdir( path.dirname( path.join( buildDir, jsPath ) ), {
-					recursive: true,
-				} ),
-				mkdir( path.dirname( path.join( buildModuleDir, jsPath ) ), {
-					recursive: true,
-				} ),
-			] );
-			await Promise.all( [
-				writeFile(
-					path.join( buildDir, jsPath ),
-					`"use strict";\nmodule.exports = ${ jsExport };\n`
-				),
-				writeFile(
-					path.join( buildModuleDir, jsPath ),
-					`export default ${ jsExport };\n`
-				),
-			] );
-
-			// Return the processed CSS for combining
-			return result.css;
-		} )
-	);
-
-	// Generate combined stylesheet from all CSS modules
-	if ( cssResults.length > 0 ) {
-		const combinedCss = cssResults.join( '\n' );
-		await mkdir( buildStyleDir, { recursive: true } );
-		await writeFile( path.join( buildStyleDir, 'style.css' ), combinedCss );
-	}
-
 	// Process SCSS files
 	await Promise.all(
 		scssEntries.map( async ( styleEntryPath ) => {
@@ -1097,6 +1213,135 @@ function getPackageName( filename ) {
 	return null;
 }
 
+/**
+ * Build a single route's files.
+ *
+ * @param {string} routeName Route name.
+ * @return {Promise<number>} Build time in milliseconds.
+ */
+async function buildRoute( routeName ) {
+	const startTime = Date.now();
+	const routeDir = path.join( ROOT_DIR, 'routes', routeName );
+	const outputDir = path.join( BUILD_DIR, 'routes', routeName );
+
+	// Ensure output directory exists
+	await mkdir( outputDir, { recursive: true } );
+
+	// Copy package.json
+	await copyFile(
+		path.join( routeDir, 'package.json' ),
+		path.join( outputDir, 'package.json' )
+	);
+
+	const files = getRouteFiles( routeDir );
+
+	// Build route.js if it exists
+	if ( files.hasRoute ) {
+		const routeEntryPoints = await glob( `route.${ SOURCE_EXTENSIONS }`, {
+			cwd: routeDir,
+			absolute: true,
+		} );
+
+		if ( routeEntryPoints.length > 0 ) {
+			const routePlugins = [
+				wordpressExternalsPlugin( 'route.min', 'esm' ),
+			];
+
+			// Build both minified and non-minified versions in parallel
+			await Promise.all( [
+				esbuild.build( {
+					entryPoints: routeEntryPoints,
+					outfile: path.join( outputDir, 'route.min.js' ),
+					bundle: true,
+					format: 'esm',
+					target: browserslistToEsbuild(),
+					minify: true,
+					define: getDefine( false ),
+					plugins: routePlugins,
+				} ),
+				esbuild.build( {
+					entryPoints: routeEntryPoints,
+					outfile: path.join( outputDir, 'route.js' ),
+					bundle: true,
+					format: 'esm',
+					target: browserslistToEsbuild(),
+					minify: false,
+					define: getDefine( true ),
+					plugins: routePlugins,
+				} ),
+			] );
+		}
+	}
+
+	// Build content.js if stage or inspector exists
+	if ( files.hasStage || files.hasInspector ) {
+		// Create synthetic entry point
+		const syntheticEntry = generateContentEntryPoint( files );
+		const tempEntryPath = path.join( routeDir, '.content-entry.js' );
+
+		// Write temporary entry file
+		await writeFile( tempEntryPath, syntheticEntry );
+
+		const contentPlugins = [
+			wordpressExternalsPlugin( 'content.min', 'esm' ),
+			...styleBundlingPlugins,
+		];
+
+		// Build both minified and non-minified versions in parallel
+		await Promise.all( [
+			esbuild.build( {
+				entryPoints: [ tempEntryPath ],
+				outfile: path.join( outputDir, 'content.min.js' ),
+				bundle: true,
+				format: 'esm',
+				target: browserslistToEsbuild(),
+				minify: true,
+				define: getDefine( false ),
+				plugins: contentPlugins,
+			} ),
+			esbuild.build( {
+				entryPoints: [ tempEntryPath ],
+				outfile: path.join( outputDir, 'content.js' ),
+				bundle: true,
+				format: 'esm',
+				target: browserslistToEsbuild(),
+				minify: false,
+				define: getDefine( true ),
+				plugins: contentPlugins,
+			} ),
+		] );
+
+		await unlink( tempEntryPath );
+	}
+
+	return Date.now() - startTime;
+}
+
+/**
+ * Build all discovered routes.
+ *
+ * @return {Promise<void>}
+ */
+async function buildAllRoutes() {
+	console.log( '\n🚦 Phase 3: Building routes...\n' );
+
+	const routes = getAllRoutes( ROOT_DIR );
+
+	if ( routes.length === 0 ) {
+		console.log( '   No routes found, skipping.\n' );
+		return;
+	}
+
+	await Promise.all(
+		routes.map( async ( routeName ) => {
+			const buildTime = await buildRoute( routeName );
+			console.log(
+				`   ✔ Built route ${ routeName } (${ buildTime }ms)`
+			);
+		} )
+	);
+}
+
 /**
  * Main build function.
  */
@@ -1159,6 +1404,32 @@ async function buildAll() {
 		} )
 	);
 
+	// Build routes
+	await buildAllRoutes();
+
+	// Collect route and page data for PHP generation
+	const routes = getAllRoutes( ROOT_DIR ).map( ( routeName ) => {
+		const metadata = getRouteMetadata( ROOT_DIR, routeName );
+		const routeFiles = getRouteFiles(
+			path.join( ROOT_DIR, 'routes', routeName )
+		);
+		return {
+			name: routeName,
+			path: metadata?.path,
+			page: metadata?.page,
+			hasRoute: routeFiles.hasRoute,
+			hasContent: routeFiles.hasStage || routeFiles.hasInspector,
+		};
+	} );
+
+	const pageData = PAGES.map( ( pageSlug ) => {
+		const pageRoutes = routes.filter( ( r ) => r.page === pageSlug );
+		return {
+			slug: pageSlug,
+			routes: pageRoutes,
+		};
+	} );
+
 	console.log( '\n📄 Generating PHP registration files...\n' );
 	const phpReplacements = await getPhpReplacements( ROOT_DIR );
 	await Promise.all( [
@@ -1167,6 +1438,9 @@ async function buildAll() {
 		generateScriptRegistrationPhp( scripts, phpReplacements ),
 		generateStyleRegistrationPhp( styles, phpReplacements ),
 		generateVersionPhp( phpReplacements ),
+		generateRoutesRegistry( routes, phpReplacements ),
+		generateRoutesPhp( routes, phpReplacements ),
+		generatePagesPhp( pageData, phpReplacements ),
 	] );
 	console.log( '   ✔ Generated build/modules.php' );
 	console.log( '   ✔ Generated build/modules/index.php' );
@@ -1175,6 +1449,16 @@ async function buildAll() {
 	console.log( '   ✔ Generated build/styles.php' );
 	console.log( '   ✔ Generated build/styles/index.php' );
 	console.log( '   ✔ Generated build/version.php' );
+	console.log( '   ✔ Generated build/routes.php' );
+	if ( PAGES.length > 0 ) {
+		console.log( '   ✔ Generated build/pages.php' );
+		for ( const page of PAGES ) {
+			console.log( `   ✔ Generated build/pages/${ page }/page.php` );
+			console.log(
+				`   ✔ Generated build/pages/${ page }/page-wp-admin.php`
+			);
+		}
+	}
 	console.log( '   ✔ Generated build/index.php' );
 
 	const totalTime = Date.now() - startTime;
@@ -1202,6 +1486,9 @@ async function watchMode() {
 	}
 	const allFullNames = Array.from( shortToFull.values() );
 
+	// Get all routes for dependency tracking
+	const allRoutes = getAllRoutes( ROOT_DIR );
+
 	/**
 	 * Rebuild a package and any affected scripts/modules.
 	 *
@@ -1238,22 +1525,69 @@ async function watchMode() {
 					);
 				}
 			}
+
+			// Find and rebuild affected routes
+			const affectedRoutes = findRoutesToRebuild(
+				fullName,
+				allFullNames,
+				ROOT_DIR,
+				allRoutes
+			);
+
+			for ( const route of affectedRoutes ) {
+				try {
+					const rebuildStartTime = Date.now();
+					await buildRoute( route );
+					const rebuildTime = Date.now() - rebuildStartTime;
+					console.log(
+						`✅ routes/${ route } (rebuilt) (${ rebuildTime }ms)`
+					);
+				} catch ( error ) {
+					console.log(
+						`❌ routes/${ route } - Rebuild error: ${ error.message }`
+					);
+				}
+			}
 		} catch ( error ) {
 			console.log( `❌ ${ packageName } - Error: ${ error.message }` );
 		}
 	}
 
+	/**
+	 * Rebuild a route.
+	 *
+	 * @param {string} routeName Route to rebuild.
+	 */
+	async function rebuildRoute( routeName ) {
+		try {
+			const startTime = Date.now();
+			await buildRoute( routeName );
+			const buildTime = Date.now() - startTime;
+			console.log( `✅ routes/${ routeName } (${ buildTime }ms)` );
+		} catch ( error ) {
+			console.log(
+				`❌ routes/${ routeName } - Error: ${ error.message }`
+			);
+		}
+	}
+
 	async function processNextRebuild() {
 		if ( needsRebuild.size === 0 ) {
 			isRebuilding = false;
 			return;
 		}
 
-		const packagesToRebuild = Array.from( needsRebuild );
+		const itemsToRebuild = Array.from( needsRebuild );
 		needsRebuild.clear();
 
-		for ( const packageName of packagesToRebuild ) {
-			await rebuildPackage( packageName );
+		for ( const item of itemsToRebuild ) {
+			// Check if it's a route (prefixed with 'route:')
+			if ( item.startsWith( 'route:' ) ) {
+				const routeName = item.slice( 6 ); // Remove 'route:' prefix
+				await rebuildRoute( routeName );
+			} else {
+				await rebuildPackage( item );
+			}
 		}
 
 		await processNextRebuild();
@@ -1315,6 +1649,66 @@ async function watchMode() {
 	watcher.on( 'change', handleFileChange );
 	watcher.on( 'add', handleFileChange );
 	watcher.on( 'unlink', handleFileChange );
+
+	// Watch route files if routes exist
+	if ( allRoutes.length > 0 ) {
+		const routeWatchPaths = allRoutes.map( ( routeName ) =>
+			path.join( ROOT_DIR, 'routes', routeName )
+		);
+
+		const routeWatcher = chokidar.watch( routeWatchPaths, {
+			persistent: true,
+			ignoreInitial: true,
+			ignored: ( filepath ) => {
+				const basename = path.basename( filepath );
+				// Ignore .content-entry.js temporary build files
+				if ( basename === '.content-entry.js' ) {
+					return true;
+				}
+				// Ignore node_modules directories and contents
+				if ( filepath.includes( 'node_modules' ) ) {
+					return true;
+				}
+				return false;
+			},
+			useFsEvents: true,
+			depth: 10,
+			awaitWriteFinish: {
+				stabilityThreshold: 100,
+				pollInterval: 50,
+			},
+		} );
+
+		routeWatcher.on( 'error', ( error ) => {
+			console.error( '❌ Route watcher error:', error );
+		} );
+
+		const handleRouteFileChange = async ( filename ) => {
+			// Extract route name from path: routes/{routeName}/...
+			const routeMatch = filename.match( /routes[/\\]([^/\\]+)[/\\]/ );
+			if ( ! routeMatch ) {
+				return;
+			}
+
+			const routeName = routeMatch[ 1 ];
+			if ( ! allRoutes.includes( routeName ) ) {
+				return;
+			}
+
+			if ( isRebuilding ) {
+				needsRebuild.add( `route:${ routeName }` );
+				return;
+			}
+
+			isRebuilding = true;
+			await rebuildRoute( routeName );
+			await processNextRebuild();
+		};
+
+		routeWatcher.on( 'change', handleRouteFileChange );
+		routeWatcher.on( 'add', handleRouteFileChange );
+		routeWatcher.on( 'unlink', handleRouteFileChange );
+	}
 }
 
 /**