ts-project-builder

ts-project-builder

Rollup-based TypeScript builder with multi-format output and built-in common plugins.

• ✨ Release Notes

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-builder

You 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 terminal

Basic Usage

Run the builder with a single entry file:

ts-project-builder ./src/index.ts

By 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 cjs will 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.

• Must be used together with the --clean flag.
• Uses the same syntax and format as --clean.

[!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-dirs flag.
• 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, and hidden.
• 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=false

Config 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();

License

MIT License