Build is a powerful tool that compiles all your TypeScript files into JavaScript, leveraging the speed of ESBuild and the type-checking capabilities of the TypeScript compiler.

• Fast compilation using ESBuild
• TypeScript support with type-checking (tsc & tsc-alias)
• Watch mode for development (--Watch)
• Customizable ESBuild configuration via object or function (--ESBuild)
• Supports both CommonJS and ES modules
• Glob pattern support for input files
• Exclusion patterns for input files

Install the package as a development dependency:

# Using npm npm install -D -E @playform/build # Or using yarn # yarn add -D -E @playform/build # Or using pnpm # pnpm add -D -E @playform/build

Run the build tool from the command line, providing file patterns:

npx @playform/build 'Source/**/*.ts' 'OtherSource/**/*.mts'

Usage: Build [options] <File...> Arguments: File One or more glob patterns matching files to build 📝 Options: -V, --version Output the version number -E, --ESBuild <File> Path to a custom ESBuild configuration file (exports an object or a function) 📜 -T, --TypeScript <File> Path to a custom TypeScript configuration file (default: "tsconfig.json") 📜 -W, --Watch Enable watch mode: rebuild on file changes 👁️ -h, --help Display help information 

Add Build to your package.json scripts:

{ "scripts": { "Build": "Build 'Source/**/*.ts'", "Run": "Build 'Source/**/*.ts' --Watch", "prepublishOnly": "Build 'Source/**/*.ts'"	} }

You can provide a custom configuration file to modify the default ESBuild options used by @playform/build. This file (e.g., ESBuild.js or esbuild.config.ts) should use export default with either a configuration object or a function.

1. Exporting an Object:

Provide an object with ESBuild options. These will be merged with the base configuration.

// ESBuild.js /** @type {import('esbuild').BuildOptions} */ const config = { minify: true, sourcemap: "external", platform: "node", // Add other esbuild options here }; export default config;

2. Exporting a Function:

Provide a function that receives the current ESBuild configuration object (BuildOptions from esbuild) as its argument. You can modify this object directly or return a new (partial) object containing options to be merged. This allows for dynamic configuration, such as filtering entry points.

// ESBuild.js /**  * @param {import('esbuild').BuildOptions} Current The configuration object before this function runs.  * @returns {import('esbuild').BuildOptions | void} Return changes to merge, or modify Current directly.  */ export default (Current) => { console.log("Applying custom ESBuild function..."); // Example: Filter out test files from entry points if (Array.isArray(Current.entryPoints)) { Current.entryPoints = Current.entryPoints.filter( (entry) => !/\.(test|spec)\.[mc]?[jt]s$/.test(entry), ); console.log("Filtered entry points:", Current.entryPoints); } // Example: Modify the config directly Current.define = {	...(Current.define ?? {}), // Preserve existing defines "process.env.BUILD_TIME": `"${new Date().toISOString()}"`, }; // Example: Return additional options to merge return { banner: { js: "// Generated by @playform/build", }, logLevel: "info", }; // If you only modify 'Current' directly, you can simply have no return: // return; // or return undefined; };

Usage:

Specify the path to your configuration file using the --ESBuild option:

npx @playform/build 'Source/**/*.ts' --ESBuild ESBuild.ts

See the base configuration used internally in Source/Variable/ESBuild.ts (link might need adjustment based on your actual path).

By default, Build looks for tsconfig.json in the current working directory. You can specify a different path using the --TypeScript option. This tsconfig.json is used by ESBuild for path resolution and by the tsc and tsc-alias commands run after the build for type checking and path alias replacement.

A typical tsconfig.json might look like this:

// tsconfig.json { "compilerOptions": { // --- Essential for tsc/tsc-alias --- "outDir": "Target", // Must match esbuild's outdir/outfile directory "rootDir": "Source", // Or your source root "baseUrl": ".", // Often needed for path aliases "paths": { // Example alias - must match esbuild alias config if used "@/*": ["Source/*"]	}, // --- Type Checking Options --- "strict": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, // --- Module Settings (match esbuild target/format) --- "target": "ES2020", "module": "ESNext", // or CommonJS "moduleResolution": "node", // or node16/nodenext // --- Interoperability --- "esModuleInterop": true, "allowSyntheticDefaultImports": true, // --- Other --- "resolveJsonModule": true, "isolatedModules": true, // Good practice with transpilers like esbuild "noEmit": true // Important: Set noEmit to true as esbuild handles file emission	}, // Use @playform/build's base config for sensible defaults (optional) // "extends": "@playform/build/tsconfig", "include": ["Source/**/*"], // Files to be type-checked "exclude": ["node_modules", "Target"] // Exclude output and dependencies }

Important: Ensure compilerOptions.outDir in your tsconfig.json aligns with the output directory configured for ESBuild (either via the default Source/Variable/ESBuild.ts or your custom --ESBuild config). Also, set "noEmit": true as esbuild handles the file generation; tsc is only used for type checking here.

If you are working with JavaScript and JSDoc for type checking, you can use a jsconfig.json file instead of tsconfig.json. The principles are similar.

// jsconfig.json { "compilerOptions": { "outDir": "Target", "rootDir": "Source", "checkJs": true, // Enable type checking for JS files "target": "ES2020", "module": "ESNext", // or CommonJS "moduleResolution": "node", // or node16/nodenext "baseUrl": ".", "paths": { "@/*": ["Source/*"]	}, "noEmit": true // Still important	}, "extends": "@playform/build/jsconfig", // If you provide a base jsconfig "include": ["Source/**/*"], "exclude": ["node_modules", "Target"] }

Remember to pass the path to this file if it's not named tsconfig.json (even if it's a JS project, the default flag might still look for tsconfig.json unless you explicitly pass --TypeScript jsconfig.json).

Contributions are welcome! Please see CONTRIBUTING.md for guidelines and feel free to submit a Pull Request.

See CHANGELOG.md for a history of changes to this component.