kiki-kanri
ts-project-builder
Rollup-based TypeScript builder with multi-format output and built-in common plugins.
Features
- 🛠️ 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
Requirements
- Node.js
>= 18.12.1
Installation
Using pnpm:
pnpm add -D ts-project-builderYou can also use yarn, npm, or bun.
Usage
Use the -h flag to view usage and all available options:
ts-project-builder -h # from package.json script
npx ts-project-builder -h # directly from terminalBasic Usage
Run the builder with a single entry file:
ts-project-builder ./src/index.tsBy default, it outputs both CommonJS (.cjs) and ESM (.mjs) formats to the ./dist directory.
Multiple Inputs and Format Control
You can pass multiple inputs and specify desired output formats:
# Output as amd, cjs, and esm
ts-project-builder ./src/cli.ts ./src/index.ts -f amd,cjs,esm
# Use glob patterns (wrap in quotes!)
ts-project-builder './src/**/*.ts' -f cjs[!IMPORTANT] Input files must be listed before any flags to ensure correct parsing.
Format Extensions
Each format will generate files with the following extensions:
| 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 |
Built-in Rollup Plugins
This builder uses the following Rollup input plugins (in order):
- rollup-plugin-node-externals
- @rollup/plugin-node-resolve
- @rollup/plugin-commonjs
- @rollup/plugin-json
- @rollup/plugin-typescript
For more options and advanced configuration, see the CLI Flags section.
CLI Flags
--clean
Cleans the output directory or files right before writing output files.
- If used without a value, all formats will be cleaned.
- If specific formats are provided, only output files for the specified formats will be cleaned.
- If the build fails, nothing will be cleaned.
Files or folders to be cleaned are determined by their output paths.
👉 If multiple formats (e.g. CJS and ESM) share the same output directory (like
./dist), using--clean cjswill still clean the entire directory.
# Clean all formats before output
ts-project-builder ./src/index.ts --clean
# Clean only CJS format before output
ts-project-builder ./src/index.ts --clean cjs[!IMPORTANT] An error will be thrown if the path to be cleaned is outside the current working directory.
To bypass this check, use
--force-clean.
-c, --config
Specifies the path to the config file.
Only .mjs files are supported — the file must be an ES module, as it is loaded using await import.
Default: ./ts-project-builder.config.mjs
--force-clean
Forcibly cleans the target directory or files before output, even if they are outside the current working directory.
[!CAUTION]
Use this flag with caution — it can delete files outside your project folder.
-f, --formats
Specifies the output formats.
Multiple formats can be provided, separated by commas. Duplicate entries will be ignored.
Default: cjs,esm
-m, --minify
Minifies the output using the minify option from rollup-plugin-esbuild.
- Uses the same configuration syntax as
--clean.
--out-dirs
Specifies the output directory path(s).
See Rollup's output.dir documentation for more details.
Default: ./dist
You can define separate output directories for different formats using <format>=<path>, separated by commas.
- If only a path is provided (e.g.
./dist), it will be used for all formats. - If format-specific paths are provided, those formats will output to the corresponding directories.
# All formats output to ./dist
ts-project-builder ./src/index.ts --out-dirs ./dist
# CJS outputs to ./cjs, all others use default ./dist
ts-project-builder ./src/index.ts --out-dirs cjs=./cjs
# ESM outputs to ./dist, all others to ./output
ts-project-builder ./src/index.ts --out-dirs ./output,esm=./dist--out-exts
Specifies the output file extensions for each format.
- If not set, or if a specific format is not listed, the default extension from the format table will be used.
- The priority order is explicit per-format value > common extension value > default table value.
- The syntax is the same as
--out-dirs, using<format>=<ext>and separating multiple values with commas.
# CJS uses `.cjs`, others use `.js`
ts-project-builder ./src/index.ts --out-exts cjs=cjs,js
# ESM uses `.js`, others use default extensions from the format table
ts-project-builder ./src/index.ts --out-exts esm=js--out-files
Specifies exact output file paths.
See the Rollup documentation for more details.
- If this flag is set, it will override the
--out-dirsflag. - The format and syntax are the same as
--out-dirs, using<format>=<path>.
# CJS outputs to ./cjs.cjs, all other formats use ./dist
ts-project-builder ./src/index.ts --out-files cjs=./cjs.cjs
# - CJS outputs to ./cjs/index.cjs (from --out-files)
# - ESM outputs to ./esm (from --out-dirs)
# - All others output to ./dist (default)
ts-project-builder ./src/index.ts --out-dirs cjs=./cjs-dist,esm=./esm --out-files cjs=./cjs/index.cjs--preserve-modules
Preserves the module structure in the output (i.e., does not bundle into a single file).
See Rollup documentation for details.
- Uses the same configuration syntax as
--clean.
--preserve-modules-roots
Specifies the root directory for preserved modules.
See Rollup documentation for details.
- Default:
./src - Uses the same configuration syntax as
--out-dirs.
--sourcemaps
Enables or configures sourcemap output.
See the Rollup documentation for more details.
- Supports values:
true,false,inline, andhidden. - Uses the same configuration syntax as
--out-dirs. - If no format is specified, the setting applies to all formats.
# All formats use the 'true' setting (sourcemaps enabled)
ts-project-builder ./src/index.ts --sourcemaps
# ESM format uses 'inline', all others use 'false' (sourcemaps disabled)
ts-project-builder ./src/index.ts --sourcemaps false,esm=inline
# Only disable sourcemaps for the ESM format
ts-project-builder ./src/index.ts --sourcemaps esm=falseConfig File
If you need to customize plugin behavior, modify per-format output, or access advanced options, you can use a configuration file.
By default, the builder looks for ./ts-project-builder.config.mjs.
You can override this using the -c flag.
Example
Create a config file and start with the following template:
import { defineConfig } from 'ts-project-builder';
export default defineConfig({});For full type definitions and configuration options, refer to the Config interface in ./src/types.ts.
Direct Import Usage
You can also use ts-project-builder as a library by directly importing the Builder class.
Create a builder instance and call the 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();