{"id":"7846232f-57ae-44e7-b52d-fbf079b4a962","slug":"susee","kind":"skill","name":"susee","summary":"TypeScript library bundler.","owner":"phothinmg","repoUrl":"https://github.com/phothinmg/susee","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-01-27T17:43:20.000Z","addedAt":"2026-10-22T00:28:01.010Z","logoUrl":"https://avatars.githubusercontent.com/u/101423229?u=818245b7eda09351b322f074caa414787d76f1a4&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":["bundler"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T21:11:16.477Z","sample":false,"url":"https://conduits.dev/tools/susee","language":"TypeScript","transports":["stdio"],"install":{"npm":"susee"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<!-- markdownlint-disable MD033 -->\n<!-- markdownlint-disable MD041 -->\n<div align=\"center\">\n<img src=\"https://susee.phothin.dev/logo/susee-bg-white.webp\" width=\"160\" height=\"160\" alt=\"susee\" />\n  <h1>Susee</h1>\n  <p>TypeScript library bundler</p>\n</div>\n<!-- markdownlint-enable MD033 -->\n\n[![NPM][nodei_img]][nodei_url]\n\n[![oxc][oxc_img]][oxc_url] [![npm version][npm_v_img]][npm_v_url] [![license][license_img]](LICENSE) [![OpenSSF Baseline](https://www.bestpractices.dev/projects/13115/baseline)](https://www.bestpractices.dev/projects/13115) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13115/badge)](https://www.bestpractices.dev/projects/13115) ![NPM Downloads](https://img.shields.io/npm/dy/susee?logo=npm&logoColor=%23CB3837)\n\n\n>![important](https://img.shields.io/badge/IMPORTANT-%20?labelColor=%23673ab8&color=%23673ab8)\n>\n> Use **susee v2.3.0 or above**. In v2.3.0, the core bundler was ported from TypeScript to Rust (powered by [`oxc`][oxc_url]) with assistance from the **glm-5.2:cloud** model served via the [Ollama](https://ollama.com) platform, fixing multiple bugs present in earlier versions. Older versions are no longer recommended.\n>\n> See the [bug information since v2.3.0](BUGS.md).\n\n## Overview\n\n`susee` is a **TypeScript bundler** powered by [`oxc`][oxc_url], 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).\n\n## Key Features\n\n- **TypeScript-first build flow** — built around library development, not application bundling. Preserves a package-oriented workflow with declaration output and clean library artifacts.\n- **Dual output support** — produces both ESM and CommonJS from the same entry definition, so packages work with modern `import` and legacy `require` ecosystems.\n- **Duplicate declaration validation** — when source consolidation produces conflicting top-level declarations, the build fails with file and location output instead of silently renaming.\n- **Package metadata update** — can update `package.json` `exports`, `main`, `module`, and `types` fields after build output is generated.\n- **Built-in minification** — runs the `oxc-minify` minifier over emitted JavaScript when enabled.\n- **CLI and programmatic API** — use the CLI for local development/CI, or call the build API for custom scripting.\n- **JSX support** — detects JSX in bundled output and validates the JSX runtime (React or a configured `jsxImportSource`) before compiling.\n\n## Install\n\n```sh\nnpm i -D susee\n```\n\nVerify the installation:\n\n```sh\nnpx susee --version\n```\n\n### Scaffold a new project\n\nGenerate a complete library project pre-configured with susee using [`create-susee`](https://github.com/phothinmg/create-susee):\n\n```sh\nnpm create susee@latest\n# yarn create susee\n# pnpm create susee\n# bun create susee\n```\n\nThe 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](https://biomejs.dev/) or [Oxc](https://oxc.rs/) — 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.\n\n## Quick Start\n\n### 1. Create a config file\n\nGenerate a starter `susee.config.{ts,js,mjs}` in your project root:\n\n```sh\nnpx susee init\n```\n\nThe 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`.\n\n> Starting from scratch? [`create-susee`](https://github.com/phothinmg/create-susee) scaffolds the whole project — config, entry file, tsconfig, and scripts — in one command.\n\n### 2. Define your entries\n\n```ts\n// susee.config.ts\nimport type { SuSeeConfig } from \"susee\";\n\nconst config: SuSeeConfig = {\n  entryPoints: [\n    {\n      entry: \"src/index.ts\",   // required — entry file path\n      exportPath: \".\",         // required — \".\" for main export, or \"./foo\"\n      format: [\"esm\"],         // optional, default [\"esm\"]\n      tsconfigFilePath: undefined, // optional, custom tsconfig\n      checks: {                // optional, all default false\n        checkAnonymous: false,\n        checkDefaultExports: false,\n        checkNpmInstalled: false,\n      },\n      minify: false,           // optional: true | { options: MinifyOptions }\n    },\n  ],\n  outDir: \"dist\",              // optional, default \"dist\"\n  allowUpdatePackageJson: false, // optional, default false\n};\n\nexport default config;\n```\n\n### 3. Build\n\n```sh\nnpx susee build\n```\n\nSusee reads your config, bundles each entry point, compiles to ESM and/or CommonJS, and writes the output to `dist` by default.\n\n## CLI\n\n```\nsusee build                           Build using susee.config.{ts,js,mjs}\nsusee init                            Generate susee.config.{ts,js,mjs}\nsusee check                           Run lint checks on a dependency tree without bundling\nsusee bundle <entry> [options]        Bundle a single entry file to disk without compiling\nsusee --version / -v                  Print version\nsusee --help / -h                     Show help\nsusee build <entry> [options]         Build from a single entry file\n```\n\n### Build Flags\n\n| Flag | Type | Default | Description |\n|------|------|---------|-------------|\n| `--entry <path>` | string | — | Entry file (optional if given positionally) |\n| `--outdir <path>` | string | `dist` | Output directory |\n| `--format` | `cjs\\|commonjs\\|esm\\|both` | `esm` | Output module format (`both` = CJS + ESM) |\n| `--tsconfig <path>` | string | `undefined` | Custom tsconfig path |\n| `--allow-update[=true\\|false]` | boolean | `false` | Allow `package.json` updates |\n| `--minify[=true\\|false]` | boolean | `false` | Minify output JS |\n| `--check[=true\\|false]` | boolean | `false` | Run bundler lint checks |\n\n### Bundle Flags\n\nThe `susee bundle` command writes the bundled source (before TypeScript compilation) to disk. It supports `--entry`, `--outdir`, and `--check[=true|false]`.\n\nFlags accept both `--flag=value` and `--flag value` syntax.\n\n### Examples\n\n```sh\nnpx susee build src/index.ts --outdir dist\nnpx susee build src/index.ts --format commonjs\nnpx susee build src/index.ts --format both        # emit CJS + ESM\nnpx susee build --entry src/index.ts --format esm --tsconfig tsconfig.build.json\nnpx susee build src/index.ts --minify\nnpx susee build src/index.ts --check              # run lint checks during build\nnpx susee bundle src/index.ts --outdir bundled   # write bundled source only\nnpx susee check                                   # lint the dependency tree from config\n```\n\n## Programmatic API\n\n### `build()`\n\n```ts\nimport { build, type SuSeeConfig } from \"susee\";\n\nconst config: SuSeeConfig = {\n  entryPoints: [\n    { entry: \"src/index.ts\", exportPath: \".\" },\n  ],\n  outDir: \"dist\",\n  allowUpdatePackageJson: true,\n};\n\nawait build(config);\n```\n\n`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.\n\n### `suseeBundle()`\n\nBundle a single entry point into a consolidated source string without compiling or writing to disk:\n\n```ts\nimport { suseeBundle, type CheckOptions } from \"susee\";\n\nconst code: string = suseeBundle(\"src/index.ts\");\n\n// with lint checks enabled\nconst checks: CheckOptions = {\n  checkAnonymous: true,\n  checkDefaultExports: true,\n  checkNpmInstalled: true,\n};\nconst checked = suseeBundle(\"src/index.ts\", checks);\n```\n\n`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.\n\n## How It Works\n\n```mermaid\nflowchart TD\n    A[CLI / Programmatic API] --> B[\"build()\"]\n    B --> C{options provided?}\n    C -->|yes| D[generateBuildOptions]\n    C -->|no| E[finalSuseeConfig]\n    E -->|no config| F[Error + exit 1]\n    E -->|found| D\n    D --> G[Compiler]\n    G --> H[For each entry point]\n    H --> I[\"bundler() — suseeBundler (oxc)\"]\n    I --> J[Bundled source string]\n    J --> K{format}\n    K -->|commonjs| L[\"_commonjs()\"]\n    K -->|esm| M[\"_esm()\"]\n    L --> N[\"suseeCompiler — ts6 in-memory host\"]\n    M --> N\n    N --> O[\"getCompilerOptions — tsconfig → per-format\"]\n    O --> P[\"ts6.createProgram + emit\"]\n    P --> Q{minify?}\n    Q -->|yes| R[oxcMinify]\n    Q -->|no| S[\"Write .cjs/.mjs + .d.* + .map\"]\n    R --> S\n    S --> T{update package?}\n    T -->|yes| U[\"files.writePackageJson\"]\n```\n\nThe 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.\n\n## Source Architecture\n\n```\nsrc/\n├── index.ts            # Public API — re-exports build, suseeBundle, SuSeeConfig, CheckOptions\n├── build.ts            # Build orchestrator — resolves config, runs Compiler\n├── bundler.ts          # Wrapper around @suseejs/susee_bundler (oxc) + CLI bundle writer\n├── cli/\n│   ├── index.ts        # CLI entrypoint & command dispatch (build/init/check/bundle)\n│   ├── parse_args.ts   # Parses CLI flags into SuSeeConfig / bundle opts\n│   ├── init.ts         # `susee init` — scaffolds config file\n│   ├── lint.ts         # `susee check` — runs suseeLint over the dependency tree\n│   └── print_help.ts   # `susee --help` output\n├── compiler/\n│   ├── index.ts        # Compiler class — bundles + emits CJS/ESM + types\n│   ├── suseeCompiler.ts# In-memory TypeScript compilation host\n│   └── tsoptions.ts    # Resolves tsconfig.json into per-format options\n├── config/\n│   └── index.ts        # Config types, validation, and normalization\n└── helpers/\n    ├── files.ts        # File system namespace + package.json writer\n    └── minify.ts       # oxc-minify wrapper\n```\n\nSee [`src/README.md`](src/README.md) for detailed module documentation.\n\n## Configuration Reference\n\n### `SuSeeConfig`\n\n| Field | Type | Required | Default | Description |\n|-------|------|----------|---------|-------------|\n| `entryPoints` | `EntryPoint[]` | yes | — | Array of entry point definitions |\n| `outDir` | `string` | no | `dist` | Output directory |\n| `allowUpdatePackageJson` | `boolean` | no | `false` | Allow susee to update `package.json` |\n\n### `EntryPoint`\n\n| Field | Type | Required | Default | Description |\n|-------|------|----------|---------|-------------|\n| `entry` | `string` | yes | — | Entry file path |\n| `exportPath` | `\".\" \\| \"./${string}\"` | yes | — | Export path for this entry |\n| `format` | `(\"commonjs\" \\| \"esm\")[]` | no | `[\"esm\"]` | Output module formats |\n| `tsconfigFilePath` | `string` | no | `undefined` | Custom tsconfig path |\n| `checks` | `CheckOptions` | no | all `false` | Bundler lint checks |\n| `minify` | `boolean \\| { options: MinifyOptions }` | no | `false` | Minify output |\n\n### `CheckOptions`\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `checkAnonymous` | `boolean` | `false` | Check for anonymous declarations |\n| `checkDefaultExports` | `boolean` | `false` | Check default exports |\n| `checkNpmInstalled` | `boolean` | `false` | Check that npm deps are installed |\n\n### TSConfig Resolution Priority\n\nFor each entry point, compiler options resolve in this order:\n\n1. Custom `tsconfigFilePath` on the entry point\n2. `tsconfig.json` at the project root\n3. Susee defaults (`module: ES2020` for ESM, `module: CommonJS` for CJS, `target: Latest`)\n\n## Agent Skills\n\nSusee ships [agent skills](https://skills.sh) that give AI coding agents procedural knowledge about building with and contributing to susee. Install them with the [skills CLI](https://skills.sh):\n\n```sh\nnpx skills add phothinmg/susee\n```\n\n| Skill | Purpose |\n| ----- | ------- |\n| `susee-build` | Configure and run builds — config files, CLI commands, programmatic API, dual ESM/CJS output |\n| `susee-troubleshooting` | Diagnose failing builds — duplicate declarations, entry/exportPath validation, invalid flags, tsconfig issues |\n| `susee-contribution` | Work on the susee codebase — architecture map, local checks, commit conventions, PR checklist |\n\n## Development\n\n```sh\nnpm run build    # compile src/ via oxnode build.ts\nnpm run lint     # oxlint\nnpm run fmt      # oxfmt\n```\n\n## Key Dependencies\n\n- [`@suseejs/susee_bundler`](https://www.npmjs.com/package/@suseejs/susee_bundler) — oxc-powered bundling engine\n- [`@suseejs/ts6`](https://www.npmjs.com/package/@suseejs/ts6) — TypeScript compiler fork for type-checking and declaration emit\n- [`oxc-minify`](https://www.npmjs.com/package/oxc-minify) — JavaScript minification\n\n## License\n\n[Apache-2.0][license] © [Pho Thin Maung][ptm]\n\n<!-- markdownlint-disable MD053 -->\n\n[license]: LICENSE\n[file-contribute]: CONTRIBUTING.md\n[ptm]: https://github.com/phothinmg\n\n[sb_img]: https://badge.socket.dev/npm/package/susee/2.3.0\n[sb_url]: https://badge.socket.dev/npm/package/susee/2.3.0\n\n[nodei_img]: https://nodei.co/npm/susee.svg?color=red\n[nodei_url]: https://nodei.co/npm/susee/\n[npm_v_img]: https://img.shields.io/npm/v/susee\n[npm_v_url]: https://www.npmjs.com/package/susee\n[license_img]: https://img.shields.io/npm/l/susee\n[publish_npm]: https://github.com/phothinmg/susee/actions/workflows/ci.yml\n[publish_npm_svg]: https://github.com/phothinmg/susee/actions/workflows/npm-publish.yml/badge.svg?event=release\n[mmcov_svg]: https://img.shields.io/badge/mmcov-85.01%25-green?style=flat&labelColor=%232c3e50\n[mmcov_url]: https://suseejs.org/coverage\n[oxc_url]: https://oxc.rs/\n[oxc_img]: https://img.shields.io/badge/Powered%20by%20OXC-%20?style=flat&logo=oxc&labelColor=black&color=gray"}