ts-project-builder

ts-project-builder

A powerful TypeScript project builder supporting multiple output formats, automatic cleaning, and customizable 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

Environment Requirements

• Node.js version 18.12 or higher

Installation

Add dependency (example using pnpm).

pnpm add -D ts-project-builder

You 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 ✨.

Usage

Use the -h flag to view usage and all available flags:

ts-project-builder -h # package.json script
npx ts-project-builder -h # terminal

Here is the most basic usage, using ./src/index.ts as the entry point:

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

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

[!IMPORTANT] 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.

Flags

--clean

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 cjs

[!IMPORTANT] 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.

-c, --config

The path to the config file. Only .mjs files are accepted.

Default: ./ts-project-builder.config.mjs

--dirs

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=./dist

--exts

The 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=js

--files

The 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.cjs

--force-clean

Force 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.

-f, --formats

The output formats. Can accept multiple formats, but duplicates will only be considered once.

Default: cjs,esm

-m, --minify

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.

--preserve-modules

Refer to the Rollup documentation for more details.

The configuration method is the same as for the --clean flag.

--preserve-modules-roots

Refer to the Rollup documentation for more details.

Default: ./src

The configuration method is the same as for the --dirs flag.

--sourcemaps

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=false

Config File

If 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.

Direct Import Usage

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

License

MIT License