susee

Use susee v2.3.0 or above. In v2.3.0, the core bundler was ported from TypeScript to Rust (powered by oxc) with assistance from the glm-5.2:cloud model served via the Ollama platform, fixing multiple bugs present in earlier versions. Older versions are no longer recommended.

See the bug information since v2.3.0.

Overview

susee is a TypeScript bundler powered by oxc, specialized for library packages. Unlike general-purpose bundlers, susee focuses on consolidating a package's local TypeScript dependency tree into consolidated source units and compiling them into dual-format artifacts (ESM and CommonJS).

Key Features

• TypeScript-first build flow — built around library development, not application bundling. Preserves a package-oriented workflow with declaration output and clean library artifacts.
• Dual output support — produces both ESM and CommonJS from the same entry definition, so packages work with modern import and legacy require ecosystems.
• Duplicate declaration validation — when source consolidation produces conflicting top-level declarations, the build fails with file and location output instead of silently renaming.
• Package metadata update — can update package.json exports, main, module, and types fields after build output is generated.
• Built-in minification — runs the oxc-minify minifier over emitted JavaScript when enabled.
• CLI and programmatic API — use the CLI for local development/CI, or call the build API for custom scripting.
• JSX support — detects JSX in bundled output and validates the JSX runtime (React or a configured jsxImportSource) before compiling.

Install

npm i -D susee

Verify the installation:

npx susee --version

Scaffold a new project

Generate a complete library project pre-configured with susee using create-susee:

npm create susee@latest
# yarn create susee
# pnpm create susee
# bun create susee

The scaffolder generates src/index.ts, a ready-to-use susee.config.ts, tsconfig.json, and a package.json with build/check scripts. It prompts you to pick a linter (Biome or Oxc — oxlint + oxfmt), optionally generates an AGENTS.md with project context for AI coding agents, auto-detects your package manager, and installs the latest published versions of all dependencies.

Quick Start

1. Create a config file

Generate a starter susee.config.{ts,js,mjs} in your project root:

npx susee init

The interactive prompt asks whether your project is TypeScript. For TypeScript projects, it writes susee.config.ts; for JavaScript projects, it writes susee.config.js (ESM) or susee.config.mjs (CommonJS) based on your package.json#type.

Starting from scratch? create-susee scaffolds the whole project — config, entry file, tsconfig, and scripts — in one command.

2. Define your entries

// susee.config.ts
import type { SuSeeConfig } from "susee";

const config: SuSeeConfig = {
  entryPoints: [
    {
      entry: "src/index.ts",   // required — entry file path
      exportPath: ".",         // required — "." for main export, or "./foo"
      format: ["esm"],         // optional, default ["esm"]
      tsconfigFilePath: undefined, // optional, custom tsconfig
      checks: {                // optional, all default false
        checkAnonymous: false,
        checkDefaultExports: false,
        checkNpmInstalled: false,
      },
      minify: false,           // optional: true | { options: MinifyOptions }
    },
  ],
  outDir: "dist",              // optional, default "dist"
  allowUpdatePackageJson: false, // optional, default false
};

export default config;

3. Build

npx susee build

Susee reads your config, bundles each entry point, compiles to ESM and/or CommonJS, and writes the output to dist by default.

CLI

susee build                           Build using susee.config.{ts,js,mjs}
susee init                            Generate susee.config.{ts,js,mjs}
susee check                           Run lint checks on a dependency tree without bundling
susee bundle <entry> [options]        Bundle a single entry file to disk without compiling
susee --version / -v                  Print version
susee --help / -h                     Show help
susee build <entry> [options]         Build from a single entry file

Build Flags

Flag	Type	Default	Description
--entry <path>	string	—	Entry file (optional if given positionally)
--outdir <path>	string	dist	Output directory
--format	cjs|commonjs|esm|both	esm	Output module format (both = CJS + ESM)
--tsconfig <path>	string	undefined	Custom tsconfig path
--allow-update[=true|false]	boolean	false	Allow package.json updates
--minify[=true|false]	boolean	false	Minify output JS
--check[=true|false]	boolean	false	Run bundler lint checks

Bundle Flags

The susee bundle command writes the bundled source (before TypeScript compilation) to disk. It supports --entry, --outdir, and --check[=true|false].

Flags accept both --flag=value and --flag value syntax.

Examples

npx susee build src/index.ts --outdir dist
npx susee build src/index.ts --format commonjs
npx susee build src/index.ts --format both        # emit CJS + ESM
npx susee build --entry src/index.ts --format esm --tsconfig tsconfig.build.json
npx susee build src/index.ts --minify
npx susee build src/index.ts --check              # run lint checks during build
npx susee bundle src/index.ts --outdir bundled   # write bundled source only
npx susee check                                   # lint the dependency tree from config

Programmatic API

build()

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

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

await build(config);

build() resolves options from the argument first, then from a root config file. If neither is available it logs an error and exits with code 1.

suseeBundle()

Bundle a single entry point into a consolidated source string without compiling or writing to disk:

import { suseeBundle, type CheckOptions } from "susee";

const code: string = suseeBundle("src/index.ts");

// with lint checks enabled
const checks: CheckOptions = {
  checkAnonymous: true,
  checkDefaultExports: true,
  checkNpmInstalled: true,
};
const checked = suseeBundle("src/index.ts", checks);

suseeBundle() runs the oxc-powered bundler over the entry's local dependency tree and returns the bundled source. When CheckOptions are provided the bundler runs diagnostics (anonymous declarations, default exports, npm-installed deps) before returning.

How It Works

flowchart TD
    A[CLI / Programmatic API] --> B["build()"]
    B --> C{options provided?}
    C -->|yes| D[generateBuildOptions]
    C -->|no| E[finalSuseeConfig]
    E -->|no config| F[Error + exit 1]
    E -->|found| D
    D --> G[Compiler]
    G --> H[For each entry point]
    H --> I["bundler() — suseeBundler (oxc)"]
    I --> J[Bundled source string]
    J --> K{format}
    K -->|commonjs| L["_commonjs()"]
    K -->|esm| M["_esm()"]
    L --> N["suseeCompiler — ts6 in-memory host"]
    M --> N
    N --> O["getCompilerOptions — tsconfig → per-format"]
    O --> P["ts6.createProgram + emit"]
    P --> Q{minify?}
    Q -->|yes| R[oxcMinify]
    Q -->|no| S["Write .cjs/.mjs + .d.* + .map"]
    R --> S
    S --> T{update package?}
    T -->|yes| U["files.writePackageJson"]

The pipeline bundles each entry point's local dependency tree into a single source string, compiles it in-memory with the TypeScript compiler (@suseejs/ts6), optionally minifies with oxc-minify, and writes dual-format artifacts with declaration and source-map files.

Source Architecture

src/
├── index.ts            # Public API — re-exports build, suseeBundle, SuSeeConfig, CheckOptions
├── build.ts            # Build orchestrator — resolves config, runs Compiler
├── bundler.ts          # Wrapper around @suseejs/susee_bundler (oxc) + CLI bundle writer
├── cli/
│   ├── index.ts        # CLI entrypoint & command dispatch (build/init/check/bundle)
│   ├── parse_args.ts   # Parses CLI flags into SuSeeConfig / bundle opts
│   ├── init.ts         # `susee init` — scaffolds config file
│   ├── lint.ts         # `susee check` — runs suseeLint over the dependency tree
│   └── print_help.ts   # `susee --help` output
├── compiler/
│   ├── index.ts        # Compiler class — bundles + emits CJS/ESM + types
│   ├── suseeCompiler.ts# In-memory TypeScript compilation host
│   └── tsoptions.ts    # Resolves tsconfig.json into per-format options
├── config/
│   └── index.ts        # Config types, validation, and normalization
└── helpers/
    ├── files.ts        # File system namespace + package.json writer
    └── minify.ts       # oxc-minify wrapper

See src/README.md for detailed module documentation.

Configuration Reference

SuSeeConfig

Field	Type	Required	Default	Description
entryPoints	EntryPoint[]	yes	—	Array of entry point definitions
outDir	string	no	dist	Output directory
allowUpdatePackageJson	boolean	no	false	Allow susee to update package.json

EntryPoint

Field	Type	Required	Default	Description
entry	string	yes	—	Entry file path
exportPath	"." | "./${string}"	yes	—	Export path for this entry
format	("commonjs" | "esm")[]	no	["esm"]	Output module formats
tsconfigFilePath	string	no	undefined	Custom tsconfig path
checks	CheckOptions	no	all false	Bundler lint checks
minify	boolean | { options: MinifyOptions }	no	false	Minify output

CheckOptions

Field	Type	Default	Description
checkAnonymous	boolean	false	Check for anonymous declarations
checkDefaultExports	boolean	false	Check default exports
checkNpmInstalled	boolean	false	Check that npm deps are installed

TSConfig Resolution Priority

For each entry point, compiler options resolve in this order:

1. Custom tsconfigFilePath on the entry point
2. tsconfig.json at the project root
3. Susee defaults (module: ES2020 for ESM, module: CommonJS for CJS, target: Latest)

Agent Skills

Susee ships agent skills that give AI coding agents procedural knowledge about building with and contributing to susee. Install them with the skills CLI:

npx skills add phothinmg/susee

Skill	Purpose
susee-build	Configure and run builds — config files, CLI commands, programmatic API, dual ESM/CJS output
susee-troubleshooting	Diagnose failing builds — duplicate declarations, entry/exportPath validation, invalid flags, tsconfig issues
susee-contribution	Work on the susee codebase — architecture map, local checks, commit conventions, PR checklist

Development

npm run build    # compile src/ via oxnode build.ts
npm run lint     # oxlint
npm run fmt      # oxfmt

Key Dependencies

• @suseejs/susee_bundler — oxc-powered bundling engine
• @suseejs/ts6 — TypeScript compiler fork for type-checking and declaration emit
• oxc-minify — JavaScript minification

License

Apache-2.0 © Pho Thin Maung