Build π
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 TypeScriptsupport with type-checking (tsc&tsc-alias)- Watch mode for development (
--Watch) - Customizable
ESBuildconfiguration via object or function (--ESBuild) - Supports both
CommonJSandESmodules - 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.tsSee 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.