About

A TypeScript-first bundler designed specifically for library packages that delivers fast builds, type safety, and modern JavaScript output with minimal configuration.

Key Features

✅ TypeScript-first - Built with TypeScript for maximum type safety

✅ Dual Output - Generate both ESM and CommonJS formats automatically

✅ Automatic Renaming - Handles duplicate declarations intelligently

✅ Fast Builds - Optimized for library packages with minimal overhead

✅ Package.json Management - Automatic updates to package.json fields based on the build results

✅ Plugin System - Extend functionality with custom plugins

✅ CLI & Programmatic API - Use as a CLI tool or integrate directly

Installation and Quick Start

Installation Methods

Local Development Dependency (Recommended)

Install susee as a development dependency in your project:

npm i -D susee

This method is recommended for library projects as it ensures the bundler version is locked to the project and available for CI/CD pipelines.

Global Installation

For system-wide availability of the susee CLI:

npm install -g susee

Global installation enables running susee directly from any directory without the npx prefix.

Installation Verification

After installation, verify the package is available by checking the version command:

npx susee --version

Quick Start

Using config file

The easiest way to start is using the built-in initialization command which generates a configuration template at your project root.This command creates a susee.config.ts, susee.config.js, or susee.config.mjs file.

npx susee init

Build your project by running:

npx susee

Using Programmatic API

You can trigger the build process within a TypeScript/JavaScript script using the build() function.

import { build } from "susee";

await build({
  entryPoints: [
    {
      entry: "src/index.ts",
      exportPath: ".",
      format: ["esm", "commonjs"],
      renameDuplicates: true,
    },
  ],
  outDir: "dist",
  allowUpdatePackageJson: true,
});

Using CLI (Direct Build)

Build a single entry directly without a config file.This method uses default values for options not explicitly provided.

npx susee build src/index.ts --outdir dist --format esm

Contributor Setup (Repository)

When contributing to this repository, use npm to keep installs aligned with package-lock.json and npm-based scripts.

npm install
npm run hooks:install

This installs project dependencies and configures local git hooks for commit workflow checks.

Security

Please report vulnerabilities privately and follow the disclosure process in SECURITY.md.

Do not open public issues for security reports.

API Quick Reference

| Surface | Command / API | Purpose | Defaults | | ------------ | -------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Programmatic | build(options?) | Build from provided options or discovered config file | Exits with code 1 when options and config are both missing | | CLI | susee | Build using susee.config.ts/js/mjs in project root | Uses resolved config | | CLI | susee init | Create config template in project root | Prompts for TypeScript project | | CLI | susee build <entry> [options] | Build a single entry directly from CLI args | --outdir dist, --format esm, --rename true, --allow-update false, --minify false, --warning false | | Config | entryPoints[].format | Output module format(s) | ["esm"] | | Config | entryPoints[].renameDuplicates | Rename duplicate declarations | true | | Config | entryPoints[].tsconfigFilePath | Custom tsconfig path | undefined | | Config | entryPoints[].plugins | Post-process plugin list | [] | | Config | outDir | Root output directory | "dist" | | Config | allowUpdatePackageJson | Update package fields based on output | false |

CLI Usage

Susee CLI.

Usage:
  susee                                 Build using susee.config.{ts,js,mjs}
  susee init                            Generate susee.config.{ts,js,mjs}
  susee --version | -v                  Check susee version
  susee --help | -h                     Show this message
  susee build <entry> [options]         Build from a single entry file

CLI Build Options

--entry <path>                Entry file (optional if provided as positional <entry>)
--outdir <path>               Output directory (default: dist)
--format <cjs|commonjs|esm>   Output format (default: esm)
--tsconfig <path>             Custom tsconfig path
--rename[=true|false]         Rename duplicate declarations (default: true)
--allow-update[=true|false]   Allow package.json updates (default: false)
--minify[=true|false]         Minify output (default: false)
--warning[=true|false]        Enable warnings (default: false)

CLI Examples

npx susee build src/index.ts --outdir dist
npx susee build src/index.ts --format commonjs
npx susee build --entry src/index.ts --format esm --minify

Config File

Supported config filenames at project root:

1. susee.config.ts
2. susee.config.js
3. susee.config.mjs

SuSeeConfig shape

type OutputFormat = ("commonjs" | "esm")[];

interface EntryPoint {
  entry: string;
  exportPath: "." | `./${string}`;
  format?: OutputFormat; // default: ["esm"]
  tsconfigFilePath?: string | undefined; // default: undefined
  renameDuplicates?: boolean; // default: true
  plugins?: unknown[]; // default: []
  warning?: boolean; // default: false
}

interface SuSeeConfig {
  entryPoints: EntryPoint[];
  outDir?: string; // default: "dist"
  allowUpdatePackageJson?: boolean; // default: false
}

Example susee.config.ts

import type { SuSeeConfig } from "susee";

const config: SuSeeConfig = {
  entryPoints: [
    {
      entry: "src/index.ts",
      exportPath: ".",
      format: ["esm", "commonjs"],
    },
  ],
  outDir: "dist",
  allowUpdatePackageJson: false,
};

export default config;

Programmatic API

build(options?)

Signature:

function build(options?: SuSeeConfig): Promise<void>;

Parameters:

1. options (optional): Build options passed directly from code.

Returns:

1. Promise<void> that resolves when compilation completes.

Runtime behavior:

1. If options is provided, Susee builds from that object.
2. If options is omitted, Susee tries to load config from project root.
3. If both are missing, Susee logs an error and exits with code 1.

import { build, type SuSeeConfig } from "susee";

const options: SuSeeConfig = {
  entryPoints: [
    {
      entry: "src/index.ts",
      exportPath: ".",
      format: ["esm", "commonjs"],
    },
  ],
};

await build(options);

Output Notes

For an entry like src/index.ts with both formats enabled, output includes:

1. ESM: dist/index.mjs
2. CommonJS: dist/index.cjs
3. Sourcemaps: .mjs.map and .cjs.map

Declaration files are emitted by the compiler when available.

Build Output Matrix

| Input | Output Directory Rule | ESM Files | CommonJS Files | | -------------------------------------------- | --------------------- | ------------------------------------------- | ------------------------------------------- | | entry: "src/index.ts", exportPath: "." | <outDir> | index.mjs, index.mjs.map, index.d.mts | index.cjs, index.cjs.map, index.d.cts | | entry: "src/foo.ts", exportPath: "./foo" | <outDir>/foo | foo.mjs, foo.mjs.map, foo.d.mts | foo.cjs, foo.cjs.map, foo.d.cts |

Notes:

1. Default outDir is dist when not set.
2. For subpath exports, output directory is computed as outDir + exportPath.slice(1).
3. Declarations (.d.mts / .d.cts) are emitted when provided by the underlying compiler result.

Package.json Update Matrix

When allowUpdatePackageJson (config) or --allow-update (CLI build) is enabled, Susee can update package fields.

| Context | Condition | Updated Fields | Observed Result | | -------------------- | --------------------------------------------- | --------------------------- | ----------------------------------------------------------- | | Main export build | exportPath: "." with ESM + CommonJS outputs | main, module | main: "dist/index.cjs", module: "dist/index.mjs" | | Main export build | exportPath: "." with declarations | types | Set from generated CommonJS declaration path when available | | Subpath export build | exportPath: "./foo" | exports (subpath mapping) | Currently remains {} in tested behavior |

Notes:

1. Package update requires a package.json file in the project root.
2. With update disabled, package fields are left unchanged.
3. Existing tests in this repo currently assert exports remains {} for the tested update flows.

Validation Rules

From config validation logic:

1. At least one entryPoints item is required.
2. Duplicate exportPath values are rejected.
3. Each entry path must exist.

Violations print an error and exit with code 1.

License

Apache-2.0 © Pho Thin Maung