A powerful TypeScript project builder supporting multiple output formats, automatic cleaning, and customizable plugins.
- 🛠️ Primarily operated through the CLI with various configurable flags and parameters
- 📦 Supports multiple output formats, including CommonJS, ESM, UMD, and more
- 🔧 Built-in support for TypeScript, JSON, and CommonJS modules
- 🧹 Automatically cleans output directories
- 💨 Minification support with esbuild
- 📂 Preserves module structure if required
- 🚀 Easy configuration through a config file
- 📜 Customizable Rollup plugins for input and output
- 🔄 Merges or replaces configurations for flexible build setups
- Node.js version 18.12 or higher
Add dependency (example using pnpm).
pnpm add -D ts-project-builderYou can also use yarn, npm, or bun to add the dependency.
That's it! You're ready to use this package for your project. Check out the usage instructions below ✨.
Use the -h flag to view usage and all available flags:
ts-project-builder -h # package.json script
npx ts-project-builder -h # terminalHere is the most basic usage, using ./src/index.ts as the entry point:
ts-project-builder ./src/index.tsBy default, it will generate files in both CJS and ESM formats. The output directory is ./dist, with file extensions cjs and mjs respectively.
The input path supports Glob Patterns. Before building, the paths will be processed using glob. Please use quotation marks when specifying the paths.
You can also specify multiple inputs simultaneously and designate the output formats:
# amd, cjs, esm
ts-project-builder ./src/cli.ts ./src/index.ts -f amd,cjs,esm
# cjs
ts-project-builder './src/**/*.ts' -f cjsImportant
Ensure that input parameters are specified before any other flags to avoid incorrect parsing.
By default, different formats will generate files with different extensions, as shown in the table below:
| Format | Extension |
|---|---|
| amd | amd.js |
| cjs | cjs |
| commonjs | cjs |
| es | mjs |
| esm | mjs |
| iife | iife.js |
| module | mjs |
| system | system.js |
| systemjs | system.js |
| umd | umd.js |
This builder includes the following Rollup input plugins (listed in execution order):
- rollup-plugin-node-externals
- @rollup/plugin-node-resolve
- @rollup/plugin-commonjs
- @rollup/plugin-json
- @rollup/plugin-typescript
For more flags and usage details, please refer to flags.
Clean the target directory or files before output.
If the flag is used without any value, all formats will be enabled. If specific formats are provided, only the specified formats will be enabled.
# All formats will clean the target directory or files before output
ts-project-builder ./src/index.ts --clean
# Only the CJS format will clean the target directory or files before output
ts-project-builder ./src/index.ts --clean cjsImportant
An error will be thrown if the path to be cleaned is not under the directory where the builder is running. To force cleaning, please use this flag.
The path to the config file. Only .mjs files are accepted.
Default: ./ts-project-builder.config.mjs
The output directory paths. Refer to the Rollup documentation for more details.
Default: ./dist
You can specify different output paths for different formats, separated by commas and designated using the <format>=[path] method. If there is no <format>= and only a path is provided, that path will be used as the common value for all formats.
# All formats are output to ./dist
ts-project-builder ./src/index.ts --dirs ./dist
# CJS output to ./cjs, others output to ./dist
ts-project-builder ./src/index.ts --dirs cjs=./cjs
# ESM output to ./dist, others output to ./output
ts-project-builder ./src/index.ts --dirs ./output,esm=./distThe output file extensions.
If not set, or if the corresponding format is not specified, the default file extension from the table above will be used.
The priority is: specified value > specified common value > table value.
The configuration method is the same as for the --dirs flag.
# CJS uses cjs, others use js
ts-project-builder ./src/index.ts --exts cjs=cjs,js
# ESM uses js, others use the corresponding values from the table
ts-project-builder ./src/index.ts --exts esm=jsThe output file paths. Refer to the Rollup documentation for more details.
If this flag is set, it will override the --dirs flag.
The configuration method is the same as for the --dirs flag.
# CJS output to ./cjs.cjs, others output to the ./dist directory
ts-project-builder ./src/index.ts --files cjs=./cjs.cjs
# CJS output to ./cjs/index.cjs, ESM output to the ./esm directory, others output to the ./dist directory
ts-project-builder ./src/index.ts --dirs cjs=./cjs-dist,esm=./esm --files cjs=./cjs/index.cjsForce clean the target directory or files before output. Must be used together with the --clean flag.
The configuration method is the same as for the --clean flag.
Caution
Use this flag with caution.
The output formats. Can accept multiple formats, but duplicates will only be considered once.
Default: cjs,esm
Minify the code using the minify feature provided by rollup-plugin-esbuild before the final output.
The configuration method is the same as for the --clean flag.
Refer to the Rollup documentation for more details.
The configuration method is the same as for the --clean flag.
Refer to the Rollup documentation for more details.
Default: ./src
The configuration method is the same as for the --dirs flag.
Refer to the Rollup documentation for more details.
The configuration method is the same as for the --dirs flag.
However, the settings are different, using true, false, inline and hidden settings.
# All formats are enabled (use the 'true' setting).
ts-project-builder ./src/index.ts --sourcemaps
# In addition to ESM's use of inline, the rest of the format closure.
ts-project-builder ./src/index.ts --sourcemaps false,esm=inline
# Close ESM format only.
ts-project-builder ./src/index.ts --sourcemaps esm=falseIf you need to pass options to built-in plugins, modify the output of specific formats, or use other options, you can use a config file.
By default, the build process will attempt to read the ./ts-project-builder.config.mjs file. You can use the -c flag to specify the config file path.
After creating the file, fill in the following code:
import { defineConfig } from 'ts-project-builder';
export default defineConfig({});For detailed config instructions, please refer to the Config interface in this file.
You can also directly import the Builder class in your code, create a builder instance, and execute the builder.build method.
import { Builder } from 'ts-project-builder';
const builder = new Builder({
inputs: ['./src/index.ts'],
output: {
formats: new Set([
'cjs',
'esm'
])
}
});
await builder.build();