@cloudcatch/wp-esbuild 1.1.0

package/lib/build.mjs

@@ -0,0 +1,111 @@
+/**
+ * Build orchestrator for WordPress blocks, JS, modules, and SCSS assets.
+ */
+
+import path from 'path';
+import chokidar from 'chokidar';
+import { loadProjectConfig } from './load-config.mjs';
+import { getEntriesForChangedPath } from './normalize-config.mjs';
+import { runEntry } from './handlers/index.mjs';
+import { buildBlocksManifest } from './build-blocks-manifest.mjs';
+
+/**
+ * @param {string} projectRoot
+ * @param {object} config
+ * @param {object[]} [entries]
+ * @return {Promise<void>}
+ */
+async function runUserPlugins( projectRoot, config, entries = config.entries ) {
+	for ( const plugin of config.plugins || [] ) {
+		if ( typeof plugin.build === 'function' ) {
+			await plugin.build( { projectRoot, config, entries } );
+		}
+	}
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {object} config
+ * @param {object[]} entries
+ * @return {Promise<void>}
+ */
+async function runEntries( projectRoot, config, entries ) {
+	const buildContext = {
+		minify: config.minify,
+		sourcemap: config.sourcemap,
+		projectRoot,
+		globalEsbuild: config.esbuild,
+		wordpressExternals: config.wordpressExternals,
+		postcss: config.postcss,
+		rtl: config.rtl,
+	};
+
+	for ( const entry of entries ) {
+		await runEntry( projectRoot, entry, buildContext );
+	}
+
+	const hasBlocksEntry = entries.some( ( entry ) => entry.type === 'blocks' );
+	if ( hasBlocksEntry && config.blocksManifest?.enabled ) {
+		await buildBlocksManifest( {
+			projectRoot,
+			inputDir: config.blocksManifest.input,
+			outputFile: config.blocksManifest.output,
+		} );
+	}
+
+	await runUserPlugins( projectRoot, config, entries );
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {object} [options]
+ * @param {boolean} [options.watch]
+ * @return {Promise<void>}
+ */
+export async function build( projectRoot, options = {} ) {
+	const config = await loadProjectConfig( projectRoot );
+
+	const runBuild = async ( entries = config.entries ) => {
+		console.log( `Building ${ projectRoot }...` );
+		await runEntries( projectRoot, config, entries );
+		console.log( 'Build complete.' );
+	};
+
+	await runBuild();
+
+	if ( options.watch ) {
+		const watchPaths = config.watchPaths.map( ( watchPath ) =>
+			path.join( projectRoot, watchPath )
+		);
+
+		console.log( 'Watching for changes...' );
+
+		const watcher = chokidar.watch( watchPaths, {
+			ignoreInitial: true,
+			ignored: /(^|[/\\])\../,
+		} );
+
+		let debounceTimer;
+		const scheduleRebuild = ( changedPath ) => {
+			clearTimeout( debounceTimer );
+			debounceTimer = setTimeout( () => {
+				const entries = changedPath
+					? getEntriesForChangedPath( changedPath, projectRoot, config )
+					: config.entries;
+
+				runBuild( entries ).catch( ( error ) => {
+					console.error( error );
+				} );
+			}, 100 );
+		};
+
+		watcher.on( 'all', ( eventName, changedPath ) => {
+			scheduleRebuild( changedPath );
+		} );
+
+		await new Promise( () => {} );
+	}
+}
+
+export { normalizeConfig } from './normalize-config.mjs';
+export { defineConfig } from './define-config.mjs';

package/lib/config.mjs

@@ -0,0 +1,96 @@
+/**
+ * Default esbuild and project configuration for @cloudcatch/wp-esbuild.
+ */
+
+export const defaultWordpressBundledPackages = [
+	'@wordpress/admin-ui',
+	'@wordpress/dataviews',
+	'@wordpress/fields',
+	'@wordpress/global-styles-engine',
+	'@wordpress/global-styles-ui',
+	'@wordpress/grid',
+	'@wordpress/icons',
+	'@wordpress/image-cropper',
+	'@wordpress/interface',
+	'@wordpress/ui',
+	'@wordpress/views',
+];
+
+export const defaultProjectConfig = {
+	srcDir: 'src',
+	outDir: 'build',
+	blocks: {
+		src: 'src/blocks',
+		out: 'build/blocks',
+		discover: '*/block.json',
+		copy: [ 'block.json', 'render.php' ],
+	},
+	js: {
+		src: 'src/js',
+		out: 'build/js',
+	},
+	modules: {
+		src: 'src/js/modules',
+		out: 'build/js/modules',
+	},
+	scss: {
+		src: 'src/scss',
+		out: 'build/css',
+	},
+	copy: [],
+	blocksManifest: {
+		enabled: true,
+		input: 'build/blocks',
+		output: 'build/blocks/blocks-manifest.php',
+	},
+	wordpressExternals: {
+		bundle: [],
+		external: [],
+		vendors: {},
+	},
+	postcss: true,
+	rtl: false,
+	esbuild: {},
+	plugins: [],
+	minify: process.env.NODE_ENV === 'production',
+	sourcemap: process.env.NODE_ENV !== 'production',
+};
+
+/**
+ * Default esbuild options for WordPress browser bundles.
+ *
+ * @param {object} options
+ * @param {boolean} options.minify
+ * @param {boolean} options.sourcemap
+ * @return {import('esbuild').BuildOptions}
+ */
+export function getDefaultEsbuildOptions( { minify, sourcemap } ) {
+	return {
+		bundle: true,
+		platform: 'browser',
+		target: 'es2018',
+		jsx: 'automatic',
+		jsxImportSource: 'react',
+		loader: {
+			'.js': 'jsx',
+			'.jsx': 'jsx',
+			'.ts': 'tsx',
+			'.tsx': 'tsx',
+			'.png': 'file',
+			'.jpg': 'file',
+			'.jpeg': 'file',
+			'.gif': 'file',
+			'.svg': 'file',
+			'.webp': 'file',
+			'.woff': 'file',
+			'.woff2': 'file',
+			'.ttf': 'file',
+			'.eot': 'file',
+		},
+		assetNames: 'assets/[name]-[hash]',
+		minify,
+		sourcemap,
+		logLevel: 'info',
+		define: {},
+	};
+}

package/lib/define-config.mjs

@@ -0,0 +1,51 @@
+/**
+ * defineConfig helper with basic validation warnings.
+ */
+
+const KNOWN_KEYS = new Set( [
+	'srcDir',
+	'outDir',
+	'entries',
+	'blocks',
+	'js',
+	'modules',
+	'scss',
+	'copy',
+	'blocksManifest',
+	'minify',
+	'sourcemap',
+	'esbuild',
+	'wordpressExternals',
+	'postcss',
+	'rtl',
+	'plugins',
+] );
+
+/**
+ * @param {object} config
+ * @return {object}
+ */
+export function defineConfig( config ) {
+	if ( config && typeof config === 'object' ) {
+		for ( const key of Object.keys( config ) ) {
+			if ( ! KNOWN_KEYS.has( key ) ) {
+				console.warn( `[wp-esbuild] Unknown config key "${ key }".` );
+			}
+		}
+
+		if ( Array.isArray( config.entries ) ) {
+			for ( const entry of config.entries ) {
+				if ( ! entry.type ) {
+					console.warn( '[wp-esbuild] entries item missing "type".' );
+				}
+				if ( entry.type !== 'copy' && ! entry.src && ! entry.from ) {
+					console.warn(
+						`[wp-esbuild] entry "${ entry.name || '(unnamed)' }" missing src/from.`
+					);
+				}
+			}
+		}
+	}
+
+	return config;
+}

package/lib/handlers/blocks.mjs

@@ -0,0 +1,159 @@
+/**
+ * Gutenberg blocks handler.
+ */
+
+import glob from 'fast-glob';
+import path from 'path';
+import { cp, mkdir, readFile } from 'fs/promises';
+import { fileExists } from '../utils.mjs';
+import { buildScssFile } from './scss.mjs';
+import { buildScriptFile } from './script.mjs';
+
+/**
+ * @param {string} blockDir
+ * @param {string} projectRoot
+ * @param {object} entryConfig
+ * @return {Promise<object>}
+ */
+async function readBlockMetadata( blockDir ) {
+	const blockJsonPath = path.join( blockDir, 'block.json' );
+	if ( ! ( await fileExists( blockJsonPath ) ) ) {
+		return {};
+	}
+
+	return JSON.parse( await readFile( blockJsonPath, 'utf8' ) );
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {object} entryConfig
+ * @return {Promise<string[]>}
+ */
+async function discoverBlocks( projectRoot, entryConfig ) {
+	const blocksSrc = path.join( projectRoot, entryConfig.src );
+	if ( ! ( await fileExists( blocksSrc ) ) ) {
+		return [];
+	}
+
+	const discoverPattern = entryConfig.discover || '*/block.json';
+	const blockJsonFiles = await glob( discoverPattern, {
+		cwd: blocksSrc,
+		absolute: true,
+	} );
+
+	return blockJsonFiles.map( ( blockJsonPath ) => path.dirname( blockJsonPath ) );
+}
+
+/**
+ * @param {string} blockDir
+ * @param {string} blocksOut
+ * @param {object} buildContext
+ * @param {object} entryConfig
+ * @return {Promise<void>}
+ */
+async function buildBlock( blockDir, blocksOut, buildContext, entryConfig ) {
+	const slug = path.basename( blockDir );
+	const outDir = path.join( blocksOut, slug );
+	const metadata = await readBlockMetadata( blockDir );
+	await mkdir( outDir, { recursive: true } );
+
+	const indexJs = path.join( blockDir, 'index.js' );
+	if ( await fileExists( indexJs ) ) {
+		await buildScriptFile( {
+			entry: indexJs,
+			outfile: path.join( outDir, 'index.js' ),
+			buildContext,
+			entryConfig: {
+				...entryConfig,
+				format: 'iife',
+				wordpressExternals: true,
+				assetPhp: true,
+			},
+		} );
+	}
+
+	const styleScss = path.join( blockDir, 'style.scss' );
+	if ( await fileExists( styleScss ) ) {
+		await buildScssFile( {
+			entry: styleScss,
+			outfile: path.join( outDir, 'style-index.css' ),
+			buildContext,
+			entryConfig,
+		} );
+	}
+
+	const editorScss = path.join( blockDir, 'editor.scss' );
+	if ( await fileExists( editorScss ) ) {
+		await buildScssFile( {
+			entry: editorScss,
+			outfile: path.join( outDir, 'index.css' ),
+			buildContext,
+			entryConfig,
+		} );
+	}
+
+	const viewEntry = await findViewScript( blockDir );
+	if ( viewEntry ) {
+		const viewOut = path.join( outDir, 'view.js' );
+		const isModule = Boolean( metadata.viewScriptModule );
+
+		await buildScriptFile( {
+			entry: viewEntry,
+			outfile: viewOut,
+			buildContext,
+			entryConfig: {
+				...entryConfig,
+				format: isModule ? 'esm' : 'iife',
+				wordpressExternals: ! isModule,
+				assetPhp: true,
+			},
+		} );
+	}
+
+	const copyList = entryConfig.copy || [ 'block.json', 'render.php' ];
+	for ( const fileName of copyList ) {
+		const source = path.join( blockDir, fileName );
+		if ( ! ( await fileExists( source ) ) ) {
+			continue;
+		}
+
+		const destination = path.join( outDir, fileName );
+		await mkdir( path.dirname( destination ), { recursive: true } );
+		await cp( source, destination, { recursive: true, force: true } );
+	}
+}
+
+/**
+ * @param {string} blockDir
+ * @return {Promise<string|null>}
+ */
+async function findViewScript( blockDir ) {
+	for ( const fileName of [ 'view.ts', 'view.tsx', 'view.js', 'view.mjs' ] ) {
+		const candidate = path.join( blockDir, fileName );
+		if ( await fileExists( candidate ) ) {
+			return candidate;
+		}
+	}
+
+	return null;
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {object} entryConfig
+ * @param {object} buildContext
+ * @return {Promise<void>}
+ */
+export async function runBlocksHandler( projectRoot, entryConfig, buildContext ) {
+	const blocksOut = path.join( projectRoot, entryConfig.out );
+	const blockDirs = await discoverBlocks( projectRoot, entryConfig );
+
+	for ( const blockDir of blockDirs ) {
+		await buildBlock( blockDir, blocksOut, buildContext, entryConfig );
+	}
+}
+
+export const blocksHandler = {
+	type: 'blocks',
+	run: runBlocksHandler,
+};

package/lib/handlers/copy.mjs

@@ -0,0 +1,59 @@
+/**
+ * Static copy handler.
+ */
+
+import glob from 'fast-glob';
+import path from 'path';
+import { cp, copyFile, mkdir } from 'fs/promises';
+import { fileExists } from '../utils.mjs';
+
+/**
+ * @param {string} projectRoot
+ * @param {object} entryConfig
+ * @return {Promise<void>}
+ */
+export async function runCopyHandler( projectRoot, entryConfig ) {
+	const fromPath = path.join( projectRoot, entryConfig.from );
+	const toPath = path.join( projectRoot, entryConfig.to );
+
+	if ( ! entryConfig.from ) {
+		return;
+	}
+
+	const hasGlob = /[*?[\]]/.test( entryConfig.from );
+
+	if ( ! hasGlob ) {
+		if ( ! ( await fileExists( fromPath ) ) ) {
+			return;
+		}
+
+		await mkdir( path.dirname( toPath ), { recursive: true } );
+		await cp( fromPath, toPath, { recursive: true, force: true } );
+		return;
+	}
+
+	const matchedFiles = await glob( entryConfig.from, {
+		cwd: projectRoot,
+		absolute: true,
+		onlyFiles: true,
+	} );
+
+	const baseDir = path.dirname(
+		path.join( projectRoot, entryConfig.from.split( '*' )[ 0 ] )
+	);
+
+	for ( const sourceFile of matchedFiles ) {
+		const relativePath = path.relative( baseDir, sourceFile );
+		const destination = entryConfig.flatten
+			? path.join( toPath, path.basename( sourceFile ) )
+			: path.join( toPath, relativePath );
+
+		await mkdir( path.dirname( destination ), { recursive: true } );
+		await copyFile( sourceFile, destination );
+	}
+}
+
+export const copyHandler = {
+	type: 'copy',
+	run: runCopyHandler,
+};

package/lib/handlers/index.mjs

@@ -0,0 +1,44 @@
+/**
+ * Handler registry for wp-esbuild pipelines.
+ */
+
+import { blocksHandler } from './blocks.mjs';
+import { copyHandler } from './copy.mjs';
+import { scssHandler } from './scss.mjs';
+import { scriptHandler } from './script.mjs';
+
+/** @type {Record<string, { type: string, run: Function }>} */
+export const handlersByType = {
+	blocks: blocksHandler,
+	script: scriptHandler,
+	scss: scssHandler,
+	copy: copyHandler,
+};
+
+/**
+ * @param {object} entry
+ * @return {{ type: string, run: Function }|undefined}
+ */
+export function getHandlerForEntry( entry ) {
+	return handlersByType[ entry.type ];
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {object} entry
+ * @param {object} buildContext
+ * @return {Promise<void>}
+ */
+export async function runEntry( projectRoot, entry, buildContext ) {
+	const handler = getHandlerForEntry( entry );
+	if ( ! handler ) {
+		throw new Error( `Unknown entry type "${ entry.type }" for entry "${ entry.name }".` );
+	}
+
+	if ( entry.type === 'copy' ) {
+		await handler.run( projectRoot, entry );
+		return;
+	}
+
+	await handler.run( projectRoot, entry, buildContext );
+}

package/lib/handlers/script.mjs

@@ -0,0 +1,141 @@
+/**
+ * Script bundle handler (IIFE and ESM).
+ */
+
+import esbuild from 'esbuild';
+import glob from 'fast-glob';
+import path from 'path';
+import { mkdir } from 'fs/promises';
+import { mergeEsbuildOptions } from '../merge-esbuild-options.mjs';
+import { fileExists } from '../utils.mjs';
+
+/**
+ * @param {string} srcDir
+ * @param {string} outDir
+ * @param {string} entry
+ * @param {object} entryConfig
+ * @return {string}
+ */
+function resolveScriptOutfile( srcDir, outDir, entry, entryConfig ) {
+	const relativeEntryPath = path.relative( srcDir, entry );
+	const outRelativePath = relativeEntryPath.replace( /\.(tsx|ts|mjs|jsx|js)$/, '.js' );
+	const globPattern = entryConfig.glob || '*.{js,jsx,mjs,ts,tsx}';
+	const preserveStructure = globPattern.includes( '**' );
+
+	if ( entryConfig.outName === 'entry-dir' ) {
+		const parentDir = path.dirname( relativeEntryPath );
+		const baseName =
+			parentDir === '.'
+				? path.basename( outRelativePath, '.js' )
+				: parentDir.split( path.sep ).join( '-' );
+		return path.join( outDir, `${ baseName }.js` );
+	}
+
+	if ( preserveStructure ) {
+		return path.join( outDir, outRelativePath );
+	}
+
+	return path.join( outDir, `${ path.basename( outRelativePath, '.js' ) }.js` );
+}
+import {
+	extractStyleImportsPlugin,
+	stripStyleImportsPlugin,
+	wordpressExternalsPlugin,
+	wordpressModuleExternalsPlugin,
+} from '../wordpress-externals-plugin.mjs';
+
+/**
+ * @param {object} options
+ * @param {string} options.entry
+ * @param {string} options.outfile
+ * @param {object} options.buildContext
+ * @param {object} options.entryConfig
+ * @return {Promise<import('esbuild').BuildResult>}
+ */
+export async function buildScriptFile( { entry, outfile, buildContext, entryConfig } ) {
+	const {
+		minify,
+		sourcemap,
+		projectRoot,
+		globalEsbuild,
+		wordpressExternals: globalExternals,
+	} = buildContext;
+
+	const format = entryConfig.format || 'iife';
+	const extractCss = entryConfig.extractCss === true;
+	const assetPhp = entryConfig.assetPhp !== false;
+	const assetBaseName = path.basename( outfile, path.extname( outfile ) );
+
+	const stylePlugin = extractCss ? extractStyleImportsPlugin() : stripStyleImportsPlugin();
+	const plugins = [ stylePlugin, ...( entryConfig.esbuild?.plugins || [] ), ...( globalEsbuild?.plugins || [] ) ];
+
+	if ( assetPhp ) {
+		if ( format === 'esm' ) {
+			plugins.push(
+				wordpressModuleExternalsPlugin( assetBaseName, globalExternals )
+			);
+		} else if ( entryConfig.wordpressExternals !== false ) {
+			plugins.push(
+				wordpressExternalsPlugin( assetBaseName, [], globalExternals )
+			);
+		}
+	}
+
+	await mkdir( path.dirname( outfile ), { recursive: true } );
+
+	const esbuildOptions = mergeEsbuildOptions( {
+		minify,
+		sourcemap,
+		globalEsbuild,
+		entryEsbuild: entryConfig.esbuild,
+		projectRoot,
+	} );
+
+	return esbuild.build( {
+		...esbuildOptions,
+		entryPoints: [ entry ],
+		outfile,
+		format,
+		plugins: [ ...plugins, ...( esbuildOptions.plugins || [] ) ].filter(
+			( plugin, index, all ) =>
+				all.findIndex( ( item ) => item.name === plugin.name ) === index
+		),
+	} );
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {object} entryConfig
+ * @param {object} buildContext
+ * @return {Promise<void>}
+ */
+export async function runScriptHandler( 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 || '*.{js,jsx,mjs,ts,tsx}';
+	const entries = await glob( globPattern, {
+		cwd: srcDir,
+		absolute: true,
+	} );
+
+	for ( const entry of entries ) {
+		const outfile = resolveScriptOutfile( srcDir, outDir, entry, entryConfig );
+
+		await buildScriptFile( {
+			entry,
+			outfile,
+			buildContext,
+			entryConfig,
+		} );
+	}
+}
+
+export const scriptHandler = {
+	type: 'script',
+	run: runScriptHandler,
+};