@cloudcatch/wp-esbuild 1.1.0

package/lib/handlers/scss.mjs

@@ -0,0 +1,113 @@
+/**
+ * SCSS/CSS handler.
+ */
+
+import esbuild from 'esbuild';
+import { sassPlugin } from 'esbuild-sass-plugin';
+import glob from 'fast-glob';
+import path from 'path';
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { fileExists } from '../utils.mjs';
+import { generateRtlCss, loadPostcssPlugins, postprocessCss } from '../postcss.mjs';
+import { resolveScssOutfile } from '../resolve-scss-outfile.mjs';
+import { writeAssetPhp } from '../write-asset-php.mjs';
+
+/**
+ * @param {object} options
+ * @param {string} options.entry
+ * @param {string} options.outfile
+ * @param {object} options.buildContext
+ * @param {object} options.entryConfig
+ * @return {Promise<void>}
+ */
+export async function buildScssFile( { entry, outfile, buildContext, entryConfig } ) {
+	const { minify, sourcemap, projectRoot, postcss: postcssSetting, rtl } = buildContext;
+	const postcssPlugins = await loadPostcssPlugins( projectRoot, postcssSetting );
+	const shouldRtl = entryConfig.rtl ?? rtl;
+
+	await mkdir( path.dirname( outfile ), { recursive: true } );
+
+	const result = await esbuild.build( {
+		entryPoints: [ entry ],
+		outfile,
+		bundle: true,
+		minify,
+		sourcemap,
+		logLevel: 'silent',
+		plugins: [
+			sassPlugin( {
+				type: 'css',
+				sourceMap: sourcemap,
+			} ),
+		],
+	} );
+
+	if ( result.errors.length > 0 ) {
+		throw new Error( result.errors.map( ( e ) => e.text ).join( '\n' ) );
+	}
+
+	const css = await readFile( outfile, 'utf8' );
+	const processed = await postprocessCss( css, postcssPlugins );
+	await writeFile( outfile, processed );
+
+	if ( shouldRtl ) {
+		const rtlCss = await generateRtlCss( processed );
+		const rtlOutfile = outfile.replace( /\.css$/, '-rtl.css' );
+		await writeFile( rtlOutfile, rtlCss );
+
+		if ( entryConfig.assetPhp ) {
+			await writeAssetPhp( rtlOutfile );
+		}
+	}
+
+	if ( entryConfig.assetPhp ) {
+		await writeAssetPhp( outfile, {
+			dependencies: entryConfig.assetDependencies || [],
+		} );
+	}
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {object} entryConfig
+ * @param {object} buildContext
+ * @return {Promise<void>}
+ */
+export async function runScssHandler( projectRoot, entryConfig, buildContext ) {
+	const srcDir = path.join( projectRoot, entryConfig.src );
+	const outDir = path.join( projectRoot, entryConfig.out );
+
+	if ( ! ( await fileExists( srcDir ) ) ) {
+		return;
+	}
+
+	const globPattern = entryConfig.glob || '*.{scss,sass}';
+	const ignore = entryConfig.ignore || [ '**/_*' ];
+
+	const entries = await glob( globPattern, {
+		cwd: srcDir,
+		absolute: true,
+		ignore,
+	} );
+
+	for ( const entry of entries ) {
+		const outfile = resolveScssOutfile( {
+			srcDir,
+			outDir,
+			entry,
+			entryConfig,
+		} );
+
+		await buildScssFile( {
+			entry,
+			outfile,
+			buildContext,
+			entryConfig,
+		} );
+	}
+}
+
+export const scssHandler = {
+	type: 'scss',
+	run: runScssHandler,
+};

package/lib/load-config.mjs

@@ -0,0 +1,103 @@
+/**
+ * Load and merge project wp-esbuild.config.mjs.
+ */
+
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { defaultProjectConfig } from './config.mjs';
+import { normalizeConfig } from './normalize-config.mjs';
+
+const CONFIG_FILENAME = 'wp-esbuild.config.mjs';
+
+/**
+ * @param {string} projectRoot
+ * @return {Promise<object>}
+ */
+export async function loadProjectConfig( projectRoot ) {
+	const configPath = path.join( projectRoot, CONFIG_FILENAME );
+
+	try {
+		const module = await import( pathToFileURL( configPath ).href );
+		const userConfig =
+			typeof module.default === 'function'
+				? module.default( { env: process.env } )
+				: module.default;
+
+		return normalizeConfig( mergeConfig( defaultProjectConfig, userConfig || {} ) );
+	} catch ( error ) {
+		if (
+			error &&
+			typeof error === 'object' &&
+			'code' in error &&
+			error.code === 'ERR_MODULE_NOT_FOUND'
+		) {
+			return normalizeConfig( { ...defaultProjectConfig } );
+		}
+		throw error;
+	}
+}
+
+/**
+ * @param {object} base
+ * @param {object} override
+ * @return {object}
+ */
+function mergeConfig( base, override ) {
+	const merged = {
+		...base,
+		...override,
+	};
+
+	if ( override.blocks !== undefined ) {
+		merged.blocks = Array.isArray( override.blocks )
+			? override.blocks
+			: { ...base.blocks, ...override.blocks };
+	}
+
+	if ( override.js !== undefined ) {
+		merged.js = Array.isArray( override.js )
+			? override.js
+			: { ...base.js, ...override.js };
+	}
+
+	if ( override.modules !== undefined ) {
+		merged.modules = Array.isArray( override.modules )
+			? override.modules
+			: { ...base.modules, ...override.modules };
+	}
+
+	if ( override.scss !== undefined ) {
+		merged.scss = Array.isArray( override.scss )
+			? override.scss
+			: { ...base.scss, ...override.scss };
+	}
+
+	if ( override.copy !== undefined ) {
+		merged.copy = Array.isArray( override.copy ) ? override.copy : override.copy;
+	}
+
+	if ( override.blocksManifest ) {
+		merged.blocksManifest = { ...base.blocksManifest, ...override.blocksManifest };
+	}
+
+	if ( override.wordpressExternals ) {
+		merged.wordpressExternals = {
+			...base.wordpressExternals,
+			...override.wordpressExternals,
+		};
+	}
+
+	if ( override.esbuild ) {
+		merged.esbuild = { ...base.esbuild, ...override.esbuild };
+	}
+
+	if ( override.plugins ) {
+		merged.plugins = override.plugins;
+	}
+
+	if ( override.entries ) {
+		merged.entries = override.entries;
+	}
+
+	return merged;
+}

package/lib/merge-esbuild-options.mjs

@@ -0,0 +1,51 @@
+/**
+ * Merge default, global, and per-entry esbuild options.
+ */
+
+import path from 'path';
+import { getDefaultEsbuildOptions } from './config.mjs';
+
+/**
+ * @param {object} params
+ * @param {boolean} params.minify
+ * @param {boolean} params.sourcemap
+ * @param {object} [params.globalEsbuild]
+ * @param {object} [params.entryEsbuild]
+ * @param {string} [params.projectRoot]
+ * @return {import('esbuild').BuildOptions}
+ */
+export function mergeEsbuildOptions( {
+	minify,
+	sourcemap,
+	globalEsbuild = {},
+	entryEsbuild = {},
+	projectRoot,
+} ) {
+	const defaults = getDefaultEsbuildOptions( { minify, sourcemap } );
+	const merged = {
+		...defaults,
+		...globalEsbuild,
+		...entryEsbuild,
+		loader: {
+			...defaults.loader,
+			...globalEsbuild.loader,
+			...entryEsbuild.loader,
+		},
+		define: {
+			...defaults.define,
+			...globalEsbuild.define,
+			...entryEsbuild.define,
+		},
+	};
+
+	if ( merged.alias && projectRoot ) {
+		merged.alias = Object.fromEntries(
+			Object.entries( merged.alias ).map( ( [ key, value ] ) => [
+				key,
+				path.isAbsolute( value ) ? value : path.join( projectRoot, value ),
+			] )
+		);
+	}
+
+	return merged;
+}

package/lib/normalize-config.mjs

@@ -0,0 +1,267 @@
+/**
+ * Normalize raw merged config into executable entries + watch metadata.
+ */
+
+import path from 'path';
+import { defaultProjectConfig } from './config.mjs';
+
+const SCRIPT_GLOB = '*.{js,jsx,mjs,ts,tsx}';
+const MODULE_GLOB = '**/*.{js,jsx,mjs,ts,tsx}';
+const SCSS_GLOB = '*.{scss,sass}';
+
+/**
+ * @param {object|object[]|undefined} value
+ * @param {object} defaults
+ * @return {object[]}
+ */
+function toEntryArray( value, defaults ) {
+	if ( ! value ) {
+		return [];
+	}
+
+	if ( Array.isArray( value ) ) {
+		return value.map( ( entry, index ) => ( {
+			...defaults,
+			...entry,
+			name: entry.name || `${ defaults.type }-${ index }`,
+		} ) );
+	}
+
+	return [
+		{
+			...defaults,
+			...value,
+			name: value.name || defaults.type,
+		},
+	];
+}
+
+/**
+ * @param {object} raw
+ * @param {string} srcDir
+ * @param {string} outDir
+ * @return {object}
+ */
+function applyRootDirs( raw, srcDir, outDir ) {
+	const mapSection = ( section, defaults, relativeSrc, relativeOut ) => {
+		if ( Array.isArray( section ) ) {
+			return section.map( ( entry ) => ( {
+				...entry,
+				src: entry.src ?? `${ srcDir }/${ relativeSrc }`,
+				out: entry.out ?? `${ outDir }/${ relativeOut }`,
+			} ) );
+		}
+
+		const merged = {
+			...defaults,
+			...section,
+		};
+
+		const userProvidedSrc = section && typeof section === 'object' && 'src' in section;
+		const userProvidedOut = section && typeof section === 'object' && 'out' in section;
+
+		if ( ! userProvidedSrc && ( ! merged.src || merged.src === defaults.src ) ) {
+			merged.src = `${ srcDir }/${ relativeSrc }`;
+		}
+
+		if ( ! userProvidedOut && ( ! merged.out || merged.out === defaults.out ) ) {
+			merged.out = `${ outDir }/${ relativeOut }`;
+		}
+
+		return merged;
+	};
+
+	return {
+		...raw,
+		srcDir,
+		outDir,
+		blocks: mapSection( raw.blocks, defaultProjectConfig.blocks, 'blocks', 'blocks' ),
+		js: mapSection( raw.js, defaultProjectConfig.js, 'js', 'js' ),
+		modules: mapSection(
+			raw.modules,
+			defaultProjectConfig.modules,
+			'js/modules',
+			'js/modules'
+		),
+		scss: mapSection( raw.scss, defaultProjectConfig.scss, 'scss', 'css' ),
+		blocksManifest: {
+			...defaultProjectConfig.blocksManifest,
+			...raw.blocksManifest,
+			input:
+				raw.blocksManifest?.input === defaultProjectConfig.blocksManifest.input
+					? `${ outDir }/blocks`
+					: raw.blocksManifest?.input ?? `${ outDir }/blocks`,
+			output:
+				raw.blocksManifest?.output === defaultProjectConfig.blocksManifest.output
+					? `${ outDir }/blocks/blocks-manifest.php`
+					: raw.blocksManifest?.output ??
+					  `${ outDir }/blocks/blocks-manifest.php`,
+		},
+	};
+}
+
+/**
+ * @param {object} raw
+ * @return {object}
+ */
+export function normalizeConfig( raw ) {
+	const srcDir = raw.srcDir ?? defaultProjectConfig.srcDir;
+	const outDir = raw.outDir ?? defaultProjectConfig.outDir;
+	const rooted = applyRootDirs( raw, srcDir, outDir );
+
+	const withDefaults = {
+		...defaultProjectConfig,
+		...rooted,
+		blocksManifest: {
+			...defaultProjectConfig.blocksManifest,
+			...rooted.blocksManifest,
+		},
+		wordpressExternals: {
+			bundle: [],
+			external: [],
+			vendors: {},
+			...( raw.wordpressExternals || {} ),
+		},
+		esbuild: raw.esbuild || {},
+		postcss: raw.postcss ?? true,
+		rtl: raw.rtl ?? false,
+		plugins: raw.plugins || [],
+	};
+
+	let entries = [];
+
+	if ( Array.isArray( withDefaults.entries ) && withDefaults.entries.length > 0 ) {
+		entries = withDefaults.entries.map( ( entry, index ) => ( {
+			enabled: true,
+			...entry,
+			name: entry.name || `entry-${ index }`,
+		} ) );
+	} else {
+		entries = [
+			...toEntryArray( withDefaults.blocks, {
+				type: 'blocks',
+				src: `${ srcDir }/blocks`,
+				out: `${ outDir }/blocks`,
+				discover: '*/block.json',
+				copy: [ 'block.json', 'render.php' ],
+			} ),
+			...toEntryArray( withDefaults.js, {
+				type: 'script',
+				src: `${ srcDir }/js`,
+				out: `${ outDir }/js`,
+				glob: SCRIPT_GLOB,
+				format: 'iife',
+				wordpressExternals: true,
+				assetPhp: true,
+				extractCss: false,
+			} ),
+			...toEntryArray( withDefaults.modules, {
+				type: 'script',
+				src: `${ srcDir }/js/modules`,
+				out: `${ outDir }/js/modules`,
+				glob: MODULE_GLOB,
+				format: 'esm',
+				wordpressExternals: true,
+				assetPhp: true,
+				extractCss: false,
+			} ),
+			...toEntryArray( withDefaults.scss, {
+				type: 'scss',
+				src: `${ srcDir }/scss`,
+				out: `${ outDir }/css`,
+				glob: SCSS_GLOB,
+				ignore: [ '**/_*' ],
+			} ),
+			...toEntryArray( withDefaults.copy, {
+				type: 'copy',
+				from: '',
+				to: '',
+				flatten: false,
+			} ),
+		];
+	}
+
+	entries = entries.filter( ( entry ) => entry.enabled !== false );
+
+	const watchPaths = [];
+	const entryWatchMap = new Map();
+
+	for ( const entry of entries ) {
+		const paths = getEntryWatchPaths( entry );
+		entryWatchMap.set( entry.name, paths );
+		for ( const watchPath of paths ) {
+			if ( ! watchPaths.includes( watchPath ) ) {
+				watchPaths.push( watchPath );
+			}
+		}
+	}
+
+	for ( const plugin of withDefaults.plugins ) {
+		if ( Array.isArray( plugin.watch ) ) {
+			for ( const watchPath of plugin.watch ) {
+				if ( ! watchPaths.includes( watchPath ) ) {
+					watchPaths.push( watchPath );
+				}
+			}
+		}
+	}
+
+	return {
+		...withDefaults,
+		entries,
+		watchPaths,
+		entryWatchMap,
+	};
+}
+
+/**
+ * @param {object} entry
+ * @return {string[]}
+ */
+function getEntryWatchPaths( entry ) {
+	switch ( entry.type ) {
+		case 'blocks':
+			return [ entry.src ];
+		case 'script':
+		case 'scss':
+			return [ entry.src ];
+		case 'copy': {
+			const from = entry.from || '';
+			if ( /[*?[\]]/.test( from ) ) {
+				const globRoot = from.split( /[*?[\]]/ )[ 0 ].replace( /\/$/, '' );
+				return [ globRoot || '.' ];
+			}
+			return [ from ];
+		}
+		default:
+			return entry.src ? [ entry.src ] : [];
+	}
+}
+
+/**
+ * @param {string} changedPath
+ * @param {string} projectRoot
+ * @param {object} normalizedConfig
+ * @return {object[]}
+ */
+export function getEntriesForChangedPath( changedPath, projectRoot, normalizedConfig ) {
+	const relativePath = path.relative( projectRoot, changedPath ).replace( /\\/g, '/' );
+	const affected = [];
+
+	for ( const entry of normalizedConfig.entries ) {
+		const watchPaths = normalizedConfig.entryWatchMap.get( entry.name ) || [];
+		const matches = watchPaths.some( ( watchPath ) => {
+			const normalizedWatch = watchPath.replace( /\\/g, '/' ).replace( /\/$/, '' );
+			return (
+				relativePath === normalizedWatch ||
+				relativePath.startsWith( `${ normalizedWatch }/` )
+			);
+		} );
+
+		if ( matches ) {
+			affected.push( entry );
+		}
+	}
+
+	return affected.length > 0 ? affected : normalizedConfig.entries;
+}

package/lib/php-export.mjs

@@ -0,0 +1,62 @@
+/**
+ * Export JSON-serializable values as PHP array literals.
+ *
+ * @param {unknown} value
+ * @param {string} indent
+ * @return {string}
+ */
+export function exportToPhp( value, indent = '\t' ) {
+	if ( value === null ) {
+		return 'null';
+	}
+
+	if ( typeof value === 'boolean' ) {
+		return value ? 'true' : 'false';
+	}
+
+	if ( typeof value === 'number' ) {
+		return Number.isFinite( value ) ? String( value ) : 'null';
+	}
+
+	if ( typeof value === 'string' ) {
+		return `'${ value
+			.replace( /\\/g, '\\\\' )
+			.replace( /'/g, "\\'" ) }'`;
+	}
+
+	if ( Array.isArray( value ) ) {
+		if ( value.length === 0 ) {
+			return 'array()';
+		}
+
+		const childIndent = indent + '\t';
+		const items = value
+			.map( ( item ) => `${ childIndent }${ exportToPhp( item, childIndent ) }` )
+			.join( ',\n' );
+
+		return `array(\n${ items }\n${ indent })`;
+	}
+
+	if ( typeof value === 'object' ) {
+		const entries = Object.entries( value );
+
+		if ( entries.length === 0 ) {
+			return 'array()';
+		}
+
+		const childIndent = indent + '\t';
+		const items = entries
+			.map(
+				( [ key, item ] ) =>
+					`${ childIndent }'${ String( key ).replace( /'/g, "\\'" ) }' => ${ exportToPhp(
+						item,
+						childIndent
+					) }`
+			)
+			.join( ',\n' );
+
+		return `array(\n${ items }\n${ indent })`;
+	}
+
+	return 'null';
+}

package/lib/postcss.mjs

@@ -0,0 +1,82 @@
+/**
+ * Load PostCSS plugins from project config or postcss.config.*.
+ */
+
+import path from 'path';
+import { pathToFileURL } from 'url';
+import autoprefixer from 'autoprefixer';
+import { fileExists } from './utils.mjs';
+
+/** @type {Map<string, import('postcss').AcceptedPlugin[]|false>} */
+const cache = new Map();
+
+/**
+ * @param {string} projectRoot
+ * @param {boolean|import('postcss').AcceptedPlugin[]|object} postcssConfig
+ * @return {Promise<import('postcss').AcceptedPlugin[]|false>}
+ */
+export async function loadPostcssPlugins( projectRoot, postcssConfig = true ) {
+	const cacheKey = `${ projectRoot }:${ JSON.stringify( postcssConfig ) }`;
+	if ( cache.has( cacheKey ) ) {
+		return cache.get( cacheKey );
+	}
+
+	if ( postcssConfig === false ) {
+		cache.set( cacheKey, false );
+		return false;
+	}
+
+	if ( Array.isArray( postcssConfig ) ) {
+		cache.set( cacheKey, postcssConfig );
+		return postcssConfig;
+	}
+
+	for ( const fileName of [
+		'postcss.config.mjs',
+		'postcss.config.js',
+		'postcss.config.cjs',
+	] ) {
+		const configPath = path.join( projectRoot, fileName );
+		if ( await fileExists( configPath ) ) {
+			const module = await import( pathToFileURL( configPath ).href );
+			const config = module.default ?? module;
+			const plugins =
+				typeof config === 'function'
+					? config( { env: process.env.NODE_ENV || 'development' } ).plugins
+					: config.plugins;
+
+			if ( Array.isArray( plugins ) ) {
+				cache.set( cacheKey, plugins );
+				return plugins;
+			}
+		}
+	}
+
+	const fallback = [ autoprefixer ];
+	cache.set( cacheKey, fallback );
+	return fallback;
+}
+
+/**
+ * @param {string} css
+ * @param {import('postcss').AcceptedPlugin[]|false} plugins
+ * @return {Promise<string>}
+ */
+export async function postprocessCss( css, plugins ) {
+	if ( plugins === false ) {
+		return css;
+	}
+
+	const postcss = ( await import( 'postcss' ) ).default;
+	const result = await postcss( plugins ).process( css, { from: undefined } );
+	return result.css;
+}
+
+/**
+ * @param {string} css
+ * @return {Promise<string>}
+ */
+export async function generateRtlCss( css ) {
+	const rtlcss = ( await import( 'rtlcss' ) ).default;
+	return rtlcss.process( css );
+}