Skip to content

README.md

Latest commit

 

History

History
148 lines (104 loc) · 3.62 KB

README.md

File metadata and controls

148 lines (104 loc) · 3.62 KB

t-packer

A small SWC-powered build utility to assemble TypeScript/TSX/JavaScript projects into CommonJS and ES Module outputs. It exposes a minimal assemble API and a pluggable transformer layer.

📖 中文文档: 查看中文版 README

Features

  • SWC-based transpilation with source maps
  • Parallel builds for CJS and ESM
  • Recursive transform with output cleaning
  • Extensible via ModuleTransformer

Requirements & Installation

  • Node.js 18+ is required
  • Package manager: pnpm (or npm/yarn)
  • Runtime dependency:
    • @swc/core
  • Recommended dev dependencies (for TypeScript projects):
    • typescript, @types/node

Install dependencies in your project:

# using pnpm
pnpm add @swc/core
pnpm add -D typescript @types/node

# optional: if you want to run TS build scripts directly
pnpm add -D ts-node

Quick start

Create a build script and call assemble.

// scripts/build.ts
import { assemble } from "./src/index"; // or from the installed package name

assemble({
  src: "./src",
  output: "./dist",
  cjs: { output: "./cjs" },
  esm: { output: "./esm" },
  target: "es2020",
});

Run it (examples):

# with ts-node
pnpm ts-node scripts/build.ts

# or transpile first and run JS
pnpm tsc && node scripts/build.js

The output layout will be:

./dist/
  cjs/
  esm/

CLI (experimental)

An experimental CLI exists under src/bin/index.ts (Commander-based). When published and compiled, usage will look like:

t-packer -s ./src -o ./dist -c ./cjs -e ./esm -t es2020

Options:

  • -c, --cjs <output>: CJS output dir
  • -e, --esm <output>: ESM output dir
  • -t, --target <target>: target JS version (e.g., es2020)
  • -s, --src <src>: source dir
  • -o, --output <output>: output dir

API

assemble(options)

Assembles the project to the desired module formats.

import type { Options } from "./src/config"; // or from the installed package
export const assemble: (options?: Options) => Promise<void>;

Options:

  • src (string, default "./src"): Source directory
  • output (string, default "./dist"): Root output directory
  • cjs ({ output: string } | null, default { output: "./cjs" }): Set to null to disable CJS
  • esm ({ output: string } | null, default { output: "./esm" }): Set to null to disable ESM
  • target (string, default "es2020"): SWC JSC target

The build:

  • Cleans target directories inside output
  • Recursively processes files from src
  • Builds CJS and/or ESM in parallel
  • Writes source maps when available
  • Logs total time

Transformer system

The transformer system is managed by ModuleTransformer. A default SWC-based transformer for TS/TSX/JS/JSX is registered in the transformer module and auto-added in the constructor.

import { ModuleTransformer } from "./src/transformer";

const transformer = new ModuleTransformer();
// custom transformers can be added with transformer.addTransformer(...)

Writing a custom transformer

Implement TransformerHook and register it.

import { ModuleTransformer, type TransformerHook, type TransformOptions } from "./src/transformer";

const myTransformer: TransformerHook = {
  exts: [[".txt", ".js"]],
  transformSync: (code: Buffer, _options: TransformOptions) => {
    const js = `export const text = ${JSON.stringify(code.toString("utf-8"))};\n`;
    return { code: Buffer.from(js) };
  },
};

const t = new ModuleTransformer();
 t.addTransformer(myTransformer);

When assemble runs, files handled by your transformer will be converted accordingly.

Further reading

  • English docs: docs/en/README.md
  • 中文文档: docs/zh/README.md