Build System

Relevant source files

• package.json
• pnpm-lock.yaml
• tsconfig.json
• tsdown.config.ts

The build system transforms TypeScript source files in src/ into an executable JavaScript bundle at dist/index.mjs. This page documents the compilation process, bundler configuration, and build artifact generation.

Overview

The build system uses a two-stage compilation approach:

1. Type Checking: The TypeScript compiler (tsc) validates types without emitting files package.json41
2. Bundling: tsdown compiles and bundles source code into an optimized executable module package.json39

This separation allows fast type checking during development while producing optimized production bundles.

Build Process Flow

Sources: package.json38-44 tsconfig.json1-15 tsdown.config.ts1-7

TypeScript Configuration

The tsconfig.json file defines compilation settings optimized for modern Node.js environments and bundler compatibility.

Compiler Options

Option	Value	Purpose
target	ESNext	Generate latest ECMAScript features tsconfig.json3
moduleResolution	bundler	Use bundler-style resolution for imports tsconfig.json4
resolveJsonModule	true	Allow importing .json files tsconfig.json5
noEmit	true	Prevent tsc from generating files (handled by tsdown) tsconfig.json10
verbatimModuleSyntax	true	Enforce consistent import/export syntax tsconfig.json11

The configuration uses moduleResolution: "bundler" tsconfig.json4 which allows tsdown to resolve modules according to modern bundler semantics. This enables better tree-shaking and support for package exports.

Type Safety Configuration

Sources: tsconfig.json1-15

Bundler Configuration

The project utilizes tsdown as its primary build tool, configured via tsdown.config.ts. This configuration ensures the output is a minified, executable CLI tool.

Key Configuration Options

Option	Value	Purpose
banner	#!/usr/bin/env node	Prepend shebang for Unix execution tsdown.config.ts4
minify	true	Compress the output bundle tsdown.config.ts5
publint	true	Validate package compatibility for NPM tsdown.config.ts6

The shebang banner #!/usr/bin/env node tsdown.config.ts4 is automatically prepended to the output bundle, allowing the file to be executed directly as ./dist/index.mjs or via the bin entries defined in package.json package.json26-29

Bundler Processing Pipeline

Sources: tsdown.config.ts1-7 package.json26-29

Build Scripts

The package.json defines scripts to orchestrate the build and validation process.

Script Definitions

Script	Command	Purpose
build	tsdown	Bundle source into executable dist/index.mjs package.json39
lint:ts	tsc	Run type checking based on tsconfig.json package.json41
lint:js	eslint .	Lint source code using ESLint package.json42
lint:all	npm run lint:ts && npm run lint:js	Comprehensive static analysis package.json44

Build Execution Flow

Sources: package.json38-46

Output Artifacts

The build process generates artifacts in the dist/ directory, which are explicitly included in the published package.

Distribution Files

File	Type	Purpose
dist/index.mjs	ES Module	The minified executable bundle package.json27

The package.json specifies which files are included in the NPM distribution package.json30-34:

• dist/
• LICENSE.md
• README.md

Binary Entry Points The bin field package.json26-29 maps the generated bundle to CLI commands:

• git-merged-branches: Points to dist/index.mjs
• gmb: Points to dist/index.mjs (short alias)

Executable Architecture

Sources: package.json3-34 tsdown.config.ts4