Npx Cli

npx CLI Tool Development (Bun-First)

Build and publish npx-executable command-line tools using Bun as the primary runtime and toolchain, producing binaries that work for all npm/npx users (Node.js runtime).

When to Use This Skill

Use when:

• Creating a new CLI tool from scratch
• Building an npx-executable binary
• Setting up argument parsing, sub-commands, or terminal UX for a CLI
• Publishing a CLI tool to npm
• Adding a CLI to an existing library package

Do NOT use when:

• Building a library without a CLI (use the npm-package skill)
• Building an application (not a published package)
• Working in a monorepo (this skill targets single-package repos)

Toolchain

Scaffolding a New CLI

Run the scaffold script:

bun run <skill-path>/scripts/scaffold.ts ./my-cli \
  --name my-cli \
  --bin my-cli \
  --description "What this CLI does" \
  --author "Your Name" \
  --license MIT

Options:

• --bin <name> — Binary name for npx (defaults to package name without scope)
• --cli-only — No library exports, CLI binary only
• --no-eslint — Skip ESLint, use Biome only

Then install dependencies:

cd my-cli
bun install
bun add -d bunup typescript vitest @vitest/coverage-v8 @biomejs/biome @changesets/cli
bun add citty picocolors
bun add -d eslint typescript-eslint  # unless --no-eslint

Project Structure

Dual (Library + CLI) — Default

my-cli/
├── src/
│   ├── index.ts            # Library exports (programmatic API)
│   ├── index.test.ts       # Unit tests for library
│   ├── cli.ts              # CLI entry point (imports from index.ts)
│   └── cli.test.ts         # CLI integration tests
├── dist/
│   ├── index.js            # Library bundle
│   ├── index.d.ts          # Type declarations
│   └── cli.js              # CLI binary (with shebang)
├── .changeset/
│   └── config.json
├── package.json
├── tsconfig.json
├── bunup.config.ts
├── biome.json
├── eslint.config.ts
├── vitest.config.ts
├── .gitignore
├── README.md
└── LICENSE

CLI-Only (No Library Exports)

Same structure minus src/index.ts and src/index.test.ts. No exports field in package.json, only bin.

Architecture Pattern

Separate logic from CLI wiring. The CLI entry (cli.ts) is a thin wrapper that: 1. Parses arguments with citty 2. Calls into the library/core modules 3. Formats output for the terminal

All business logic lives in importable modules (index.ts or internal modules). This makes logic unit-testable without spawning processes.

cli.ts → imports from → index.ts / core modules
                              ↑
                         unit tests

Key Rules (Non-Negotiable)

All rules from the npm-package skill apply here. These additional rules are specific to CLI packages:

Binary Configuration

1. Always use `#!/usr/bin/env node` in published bin files. Never #!/usr/bin/env bun. The vast majority of npx users don't have Bun installed.

2. Point `bin` at compiled JavaScript in `dist/`. Never at TypeScript source. npx consumers won't have your build toolchain.

3. Ensure the bin file is executable. The build script includes chmod +x dist/cli.js after compilation.

4. Build with Node.js as the target. Bunup's output must run on Node.js, not require Bun runtime features.

Package Configuration

5. Always use `"type": "module"` in package.json.

6. `types` must be the first condition in every exports block.

7. Use `files: ["dist"]`. Whitelist only.

8. For dual packages (library + CLI): The exports field exposes the library API. The bin field exposes the CLI. They are independent — bin is NOT part of exports.

Code Quality

9. `any` is banned. Use unknown and narrow.

10. Use `import type` for type-only imports.

11. Handle errors gracefully. CLI users should never see raw stack traces. Use citty's runMain() which handles this automatically, plus process.on('SIGINT', ...) for cleanup.

12. Exit with appropriate codes. 0 for success, 1 for errors, 2 for bad arguments, 130 for SIGINT.

Reference Documentation

Read these before modifying configuration:

• [reference/cli-patterns.md](./reference/cli-patterns.md) — bin setup, citty patterns, sub-commands, error handling, terminal UX, testing CLI binaries
• [reference/esm-cjs-guide.md](./reference/esm-cjs-guide.md) — exports map, dual package hazard, common mistakes
• [reference/strict-typescript.md](./reference/strict-typescript.md) — tsconfig, Biome rules, ESLint type-aware rules, Vitest config
• [reference/publishing-workflow.md](./reference/publishing-workflow.md) — Changesets, files field, Trusted Publishing, CI pipeline

Argument Parsing with citty

Single Command

import { defineCommand, runMain } from 'citty';

const main = defineCommand({
  meta: { name: 'my-cli', version: '1.0.0', description: '...' },
  args: {
    input: { type: 'positional', description: 'Input file', required: true },
    output: { alias: 'o', type: 'string', description: 'Output path', default: './out' },
    verbose: { alias: 'v', type: 'boolean', description: 'Verbose output', default: false },
  },
  run({ args }) {
    // args is fully typed
  },
});

void runMain(main);

Sub-Commands

import { defineCommand, runMain } from 'citty';

const init = defineCommand({ meta: { name: 'init' }, /* ... */ });
const build = defineCommand({ meta: { name: 'build' }, /* ... */ });

const main = defineCommand({
  meta: { name: 'my-cli', version: '1.0.0' },
  subCommands: { init, build },
});

void runMain(main);

See reference/cli-patterns.md for complete examples including error handling, colors, and spinners.

Testing Strategy

Unit Tests — Test the Logic

// src/index.test.ts
import { describe, it, expect } from 'vitest';
import { processInput } from './index.js';

describe('processInput', () => {
  it('handles valid input', () => {
    expect(processInput('test')).toBe('expected');
  });
});

Integration Tests — Test the Binary

Build first (bun run build), then spawn the compiled binary:

// src/cli.test.ts
import { describe, it, expect } from 'vitest';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';

const exec = promisify(execFile);

describe('CLI', () => {
  it('prints help', async () => {
    const { stdout } = await exec('node', ['./dist/cli.js', '--help']);
    expect(stdout).toContain('my-cli');
  });
});

Development Workflow

# Write code and tests
bun run test:watch    # Vitest watch mode

# Check everything
bun run lint          # Biome + ESLint
bun run typecheck     # tsc --noEmit
bun run test          # Vitest

# Build and try the CLI locally
bun run build
node ./dist/cli.js --help
node ./dist/cli.js some-input

# Prepare release
bunx changeset
bunx changeset version

# Publish
bun run release       # Build + npm publish --provenance

Adding Sub-Commands Later

1. Create a new file per sub-command: src/commands/init.ts, src/commands/build.ts 2. Each exports a defineCommand() result 3. Import and wire into the main command's subCommands 4. Keep logic in testable modules, commands are thin wrappers

Converting a CLI-Only Package to Dual (Library + CLI)

1. Create src/index.ts with the public API 2. Update bunup.config.ts to include both entry points 3. Add exports field to package.json alongside the existing bin 4. Add .d.ts generation: dts: { entry: ['src/index.ts'] }

Bun-Specific Gotchas

• `bun build` does not generate .d.ts files. Use Bunup or tsc --emitDeclarationOnly.
• `bun build` does not downlevel syntax. ES2022+ ships as-is.
• `bun publish` does not support `--provenance`. Use npm publish.
• `bun publish` uses `NPM_CONFIG_TOKEN`, not NODE_AUTH_TOKEN.
• Never use `#!/usr/bin/env bun` in published packages. Your users don't have Bun.
• Bunup `banner` adds the shebang to ALL output files, including the library entry. If this is a problem, use a post-build script to add the shebang only to dist/cli.js.

CLI Package Patterns

Bin Entry Point Configuration

package.json bin Field

{
  "bin": {
    "my-cli": "./dist/cli.js"
  }
}

For single-command CLIs where the binary name matches the package name:

{
  "bin": "./dist/cli.js"
}

Critical Rules

1. Always use `#!/usr/bin/env node` in the compiled output — never #!/usr/bin/env bun. Bun is not installed for the vast majority of npm/npx users. The shebang must target Node.js for universal compatibility.

2. Point `bin` at compiled JavaScript in `dist/`, never at TypeScript source. npx consumers won't have your build toolchain.

3. Build with `--target node` to ensure Node.js runtime compatibility.

4. Ensure the bin file is executable. The build script should chmod +x dist/cli.js after compilation, or the scaffold's build step should handle this.

Bunup Configuration for CLI

import { defineConfig } from 'bunup';

export default defineConfig({
  entry: {
    index: 'src/index.ts',  // Library exports (if any)
    cli: 'src/cli.ts',      // CLI entry point
  },
  format: ['esm'],
  dts: true,
  clean: true,
  // Bunup adds shebang to bin entries automatically when
  // it detects them in package.json. If not, add manually:
  banner: {
    js: '#!/usr/bin/env node',
  },
});

Note: If the CLI is the only entry point (no library exports), simplify to a single entry:

import { defineConfig } from 'bunup';

export default defineConfig({
  entry: ['src/cli.ts'],
  format: ['esm'],
  dts: false,  // No types needed for CLI-only packages
  clean: true,
  banner: {
    js: '#!/usr/bin/env node',
  },
});

Argument Parsing with citty

citty is a lightweight (~3KB), TypeScript-native argument parser from the UnJS ecosystem. It's built on Node.js's native util.parseArgs.

Basic Structure

// src/cli.ts
import { defineCommand, runMain } from 'citty';

const main = defineCommand({
  meta: {
    name: 'my-cli',
    version: '1.0.0',
    description: 'What this CLI does',
  },
  args: {
    input: {
      type: 'positional',
      description: 'Input file path',
      required: true,
    },
    output: {
      alias: 'o',
      type: 'string',
      description: 'Output file path',
      default: './output',
    },
    verbose: {
      alias: 'v',
      type: 'boolean',
      description: 'Enable verbose output',
      default: false,
    },
  },
  run({ args }) {
    // args is fully typed: { input: string; output: string; verbose: boolean }
    console.log(`Processing ${args.input} → ${args.output}`);
  },
});

runMain(main);

Sub-Commands

import { defineCommand, runMain } from 'citty';

const init = defineCommand({
  meta: { name: 'init', description: 'Initialize a new project' },
  args: {
    template: {
      alias: 't',
      type: 'string',
      description: 'Template to use',
      default: 'default',
    },
  },
  run({ args }) {
    console.log(`Initializing with template: ${args.template}`);
  },
});

const build = defineCommand({
  meta: { name: 'build', description: 'Build the project' },
  args: {
    watch: {
      alias: 'w',
      type: 'boolean',
      description: 'Watch for changes',
      default: false,
    },
  },
  run({ args }) {
    console.log(`Building${args.watch ? ' (watch mode)' : ''}...`);
  },
});

const main = defineCommand({
  meta: {
    name: 'my-cli',
    version: '1.0.0',
    description: 'My CLI tool',
  },
  subCommands: { init, build },
});

runMain(main);

Why citty Over Alternatives

• citty: ~3KB, TypeScript-native types, built on util.parseArgs, auto-generated help, runMain() handles errors gracefully. Best for new projects.
• commander: Most widely used, imperative API, massive community. Better if you need extensive documentation/examples from the ecosystem.
• yargs: Feature-rich, ~200KB+, excellent validation. Overkill for most CLIs.

Error Handling

runMain() Pattern

citty's runMain() automatically:

• Catches unhandled errors and prints clean messages (no stack traces)
• Handles --help and --version flags
• Exits with appropriate codes

For custom error handling:

import { defineCommand, runMain } from 'citty';
import process from 'node:process';

const main = defineCommand({
  meta: { name: 'my-cli', version: '1.0.0' },
  run() {
    // Your logic here
  },
});

// Graceful shutdown
process.on('SIGINT', () => {
  console.log('\nInterrupted. Cleaning up...');
  // Cleanup logic
  process.exit(130);
});

// Unhandled rejections
process.on('unhandledRejection', (error) => {
  console.error('Unexpected error:', error instanceof Error ? error.message : error);
  if (process.env['DEBUG']) {
    console.error(error);
  }
  process.exit(1);
});

runMain(main);

Exit Codes

• 0 — Success
• 1 — General error
• 2 — Misuse of command (bad arguments)
• 130 — SIGINT (Ctrl+C)

Terminal Output

Colors: picocolors

import pc from 'picocolors';

console.log(pc.green('✓ Success'));
console.log(pc.red('✗ Error: file not found'));
console.log(pc.yellow('⚠ Warning: deprecated option'));
console.log(pc.dim('  Processing files...'));

picocolors is ~7KB, supports CJS and ESM, auto-detects color support. No chained API — use template literals for combinations: ` pc.bold(pc.red('Error')) `.

For chained styles or Truecolor support, use ansis instead.

Note: Node.js v22+ includes util.styleText() for zero-dependency coloring. Consider it if you want to eliminate the picocolors dependency for Node.js 22+ targets.

Spinners: nanospinner

import { createSpinner } from 'nanospinner';

const spinner = createSpinner('Processing...').start();
// ... do work ...
spinner.success({ text: 'Done!' });
// or
spinner.error({ text: 'Failed!' });

Dual Library + CLI Package

Some packages export both a programmatic API and a CLI. Structure these as:

src/
├── index.ts    # Library exports (public API)
├── cli.ts      # CLI entry point (imports from index.ts)
└── internal/   # Shared implementation

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./package.json": "./package.json"
  },
  "bin": {
    "my-cli": "./dist/cli.js"
  }
}

The CLI entry (cli.ts) imports from the library entry (index.ts) — never the reverse. This keeps the library tree-shakeable and the CLI as a thin wrapper.

Testing CLI Commands

Unit Test the Logic, Not the CLI

Separate business logic from CLI argument handling:

// src/core.ts — pure logic, fully testable
export function processInput(input: string, options: ProcessOptions): Result {
  // ...
}

// src/cli.ts — thin CLI wrapper
import { processInput } from './core.js';

const main = defineCommand({
  // ...
  run({ args }) {
    const result = processInput(args.input, { verbose: args.verbose });
    console.log(result);
  },
});

Integration Test the CLI Binary

For end-to-end CLI tests, spawn the built binary:

import { describe, it, expect } from 'vitest';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';

const exec = promisify(execFile);

describe('CLI', () => {
  it('prints help', async () => {
    const { stdout } = await exec('node', ['./dist/cli.js', '--help']);
    expect(stdout).toContain('my-cli');
  });

  it('processes input', async () => {
    const { stdout } = await exec('node', ['./dist/cli.js', 'input.txt', '-o', 'output.txt']);
    expect(stdout).toContain('Processing');
  });

  it('exits with error on missing input', async () => {
    await expect(exec('node', ['./dist/cli.js'])).rejects.toThrow();
  });
});

ESM/CJS Interoperability Guide

The Current State (2026)

ESM-only is now the correct default for new packages. require(esm) is stable and unflagged in all supported Node.js LTS versions (v20.19.0+, v22.12.0+). Node.js 18 reached EOL in April 2025.

Default to ESM-only (`"type": "module"`) unless the package has a specific, documented need to support Node.js < 20.19.0.

Package.json exports Map

ESM-Only (Preferred)

{
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./package.json": "./package.json"
  },
  "files": ["dist"]
}

Dual CJS/ESM (When Required)

Use the module-sync condition (Node.js 22.10+, backported to 20.19.0) to serve ESM to both import and require() consumers, eliminating the dual package hazard:

{
  "type": "module",
  "exports": {
    ".": {
      "module-sync": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      },
      "import": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    },
    "./package.json": "./package.json"
  }
}

Critical Rules

types Must Be First

Within each condition block, types must appear before default or any other condition. TypeScript silently fails to resolve types otherwise.

// CORRECT
{ "types": "./dist/index.d.ts", "default": "./dist/index.js" }

// BROKEN — TypeScript won't find types
{ "default": "./dist/index.js", "types": "./dist/index.d.ts" }

exports Encapsulates Completely

Once you add an exports field, all non-exported paths become inaccessible to consumers. Always explicitly export "./package.json": "./package.json" — many tools need it.

Condition Order Matters

default must always be last. Custom conditions go before import/require. Wrong order silently serves the wrong file to some consumers.

Prefer Named Exports

Default exports behave differently between CJS and ESM. A CJS consumer doing const pkg = require('your-pkg') gets the module namespace, not the default export, unless they use pkg.default. Named exports avoid this entirely.

// PREFER
export function doThing(): void { /* ... */ }
export const CONFIG = { /* ... */ };

// AVOID as primary API surface
export default class MyThing { /* ... */ }

Changes to exports Are Semver-Major

Adding, removing, or restructuring export paths will break some consumer in some environment. Treat exports map changes as breaking.

The Dual Package Hazard

When Node.js loads both a CJS and ESM copy of the same package (e.g., one dependency imports it and another require()s it), the package initializes twice. This causes:

• Duplicate state (singletons aren't singletons)
• instanceof checks fail across module boundaries
• Side effects run twice

Solutions (in order of preference): 1. Ship ESM-only — no hazard possible 2. Use module-sync condition — both import and require resolve to the same ESM file 3. Use a stateless API design where duplicate instantiation doesn't matter

Subpath Exports

For packages that expose multiple entry points:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./utils": {
      "types": "./dist/utils.d.ts",
      "default": "./dist/utils.js"
    },
    "./package.json": "./package.json"
  }
}

Each subpath needs its own types + default pair. The types condition must be first in every subpath.

Common Mistakes

1. Using `main` instead of `exports`: main is legacy. Use exports for all new packages. Only add main as a fallback for very old tooling.

2. Forgetting `"type": "module"`: Without this, .js files are treated as CJS by Node.js, even if they contain ESM syntax.

3. Using `.mjs`/`.cjs` extensions when unnecessary: With "type": "module", .js is ESM. Only use .cjs for the rare CJS file in an ESM package. Avoid .mjs in new packages — it causes issues with some tooling.

4. Path aliases in published code: tsc does not rewrite path aliases ("@lib/utils") in emitted JS or .d.ts files. Consumers can't resolve them. Use Node.js subpath imports ("#imports" in package.json) instead, or keep directory structures flat.

Publishing Workflow

Versioning: Changesets

`standard-version` is deprecated. Use Changesets for new projects.

Changesets uses a file-based approach: each PR includes a changeset file describing what changed and whether it's a patch, minor, or major bump. At release time, changesets are consumed to bump versions and generate changelogs.

Setup

bun add -d @changesets/cli
bunx changeset init

This creates a .changeset/ directory with a config.json:

{
  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

Workflow

1. During development: Run bunx changeset to create a changeset file describing the change 2. At release time: Run bunx changeset version to consume changesets, bump package.json version, update CHANGELOG.md 3. Publish: Run the build + publish pipeline

Package.json Scripts

{
  "scripts": {
    "changeset": "changeset",
    "version": "changeset version",
    "release": "bun run build && npm publish"
  }
}

Pre-Publish Checklist

Use files Field, Never .npmignore

The files field is a whitelist — only listed paths are included in the published tarball. This prevents accidentally shipping secrets, .env files, test fixtures, or source code.

{
  "files": ["dist"]
}

.npmignore is a blacklist that replaces .gitignore (they are not merged). This is a common source of credential leaks — if .gitignore blocks .env but .npmignore doesn't, your secrets ship to npm.

Verify Before Publishing

Always dry-run before publishing:

npm pack --dry-run

This shows exactly what will be in the tarball. Review the file list. If anything unexpected appears, fix files in package.json.

Use prepublishOnly for Build + Test

{
  "scripts": {
    "prepublishOnly": "bun run lint && bun run test && bun run build"
  }
}

Never use the legacy prepublish hook — it runs on both npm publish AND npm install (in npm v7+), which is almost never what you want.

Publishing

npm publish with Provenance (Recommended)

npm publish --provenance --access public

Provenance signing creates a cryptographic attestation linking the published package to its source code and build process. This is the gold standard for supply chain security.

Note: bun publish exists and works, but does NOT support --provenance. Use npm publish for provenance signing.

npm Trusted Publishing (OIDC)

npm Trusted Publishing eliminates long-lived npm tokens. Configure it on npmjs.com by linking your GitHub repository to your npm package. Then in GitHub Actions:

name: Release
on:
  push:
    tags: ['v*']

permissions:
  contents: read
  id-token: write  # Required for OIDC

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: bun run build
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          registry-url: 'https://registry.npmjs.org'
      - run: npm publish --provenance --access public

No NODE_AUTH_TOKEN needed — the OIDC token is obtained automatically.

bun publish (When Provenance Not Required)

bun publish --access public

Bun publish handles workspace: protocol stripping, respects .npmrc, supports --dry-run and --tag. Use NPM_CONFIG_TOKEN (not NODE_AUTH_TOKEN) for authentication in CI.

GitHub Actions: Full Release Pipeline

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: bun run lint
      - run: bun run typecheck
      - run: bun run test
      - run: bun run build

Version Tagging Convention

After changeset version bumps the version:

git add .
git commit -m "chore: release v$(node -p "require('./package.json').version")"
git tag "v$(node -p "require('./package.json').version")"
git push --follow-tags

Or automate this with a release script.

Access Control

For scoped packages (@scope/package-name), the first publish requires --access public (scoped packages default to restricted). Subsequent publishes inherit the access level.

{
  "publishConfig": {
    "access": "public"
  }
}

Adding publishConfig.access to package.json avoids needing --access public on every publish.

Strict TypeScript & Linting Configuration

TypeScript: nodenext for Libraries

Use module: "nodenext" for all published packages. Not "bundler".

Why: "bundler" allows extensionless imports (import { foo } from "./utils") that work in bundlers but crash in Node.js with ERR_MODULE_NOT_FOUND. Code satisfying nodenext constraints works everywhere; the reverse is not true.

Recommended tsconfig.json

{
  "compilerOptions": {
    // Module system
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "moduleDetection": "force",
    "verbatimModuleSyntax": true,
    "isolatedModules": true,

    // Output
    "target": "es2022",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "rootDir": "src",
    "outDir": "dist",

    // Strict type safety — ALL of these are non-negotiable for published packages
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,

    // Build optimization
    "skipLibCheck": true,

    // Interop
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

Key Settings Explained

`strict: true` enables noImplicitAny, strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, alwaysStrict, useUnknownInCatchVariables. This is non-negotiable for published packages — without it, your .d.ts files can contain types that error when consumers compile with strict mode.

`noUncheckedIndexedAccess: true` adds | undefined to all index signature access. Not part of strict, but catches real runtime bugs where array/object access might be undefined.

`exactOptionalPropertyTypes: true` distinguishes between { x?: string } (property may be absent) and { x: string | undefined } (property present but undefined). Catches subtle API design bugs.

`verbatimModuleSyntax: true` replaces isolatedModules conceptually. Ensures import/export statements are preserved exactly as written — critical for tree-shaking and type-only import elision. Guarantees each file can be independently transpiled (required by esbuild, SWC, Bun).

`declarationMap: true` generates .d.ts.map files enabling "Go to Definition" to navigate to your original source. Always ship these — they dramatically improve consumer DX.

`moduleDetection: "force"` treats every file as a module regardless of whether it has import/export statements. Prevents accidental global script files.

What NOT to Do

Don't use path aliases (`paths`) in published packages. tsc does not rewrite path aliases in emitted JS or .d.ts files. Your consumers will see unresolvable "@lib/utils" imports. Use relative imports or Node.js subpath imports (#imports in package.json) instead.

Don't set `target` lower than `es2022` unless you have a documented reason. Bun and all supported Node.js versions support ES2022. Lower targets lose features like top-level await and cause-chained errors.

Don't use `composite: true` for single-package repos. It's a project-references feature for monorepos and adds unnecessary build artifacts.

Biome Configuration

Biome handles formatting and syntax-level linting. It's 10-25x faster than ESLint for linting and 25x faster than Prettier for formatting.

biome.json

{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "organizeImports": {
    "enabled": true
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "tab",
    "lineWidth": 100
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "suspicious": {
        "noExplicitAny": "error"
      },
      "style": {
        "noNonNullAssertion": "warn",
        "useImportType": "error",
        "useConsistentArrayType": {
          "level": "error",
          "options": { "syntax": "generic" }
        },
        "noNamespace": "error"
      },
      "complexity": {
        "noBannedTypes": "error",
        "useOptionalChain": "error"
      },
      "correctness": {
        "noUnusedImports": "error",
        "noUnusedVariables": "warn",
        "useExhaustiveDependencies": "warn"
      },
      "nursery": {
        "noFloatingPromises": "error"
      }
    }
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "all",
      "semicolons": "always"
    }
  }
}

Biome Key Rules for Strict TypeScript

• `noExplicitAny: "error"` — Bans any type annotations. Use unknown and narrow, or use // biome-ignore suspicious/noExplicitAny: <reason> when genuinely unavoidable.
• `useImportType: "error"` — Enforces import type for type-only imports, aligning with verbatimModuleSyntax.
• `noFloatingPromises: "error"` — Biome v2's first type-aware rule. Catches unhandled promise rejections.
• `noUnusedImports: "error"` — Keeps imports clean. Biome auto-fixes these.

What Biome Cannot Do (Yet)

Biome v2 has exactly one type-aware rule (noFloatingPromises). ESLint + typescript-eslint provides 40+ type-aware rules. For strict library authoring, the most impactful missing rules are:

• no-misused-promises — Catches promises used in boolean contexts
• await-thenable — Catches await on non-Promise values
• no-unsafe-assignment / no-unsafe-return — Catches any propagation even from inferred types
• strict-boolean-expressions — Catches falsy-value bugs
• no-unnecessary-condition — Catches always-truthy/falsy checks

ESLint: Type-Aware Rules Only

Use ESLint exclusively for type-aware rules that Biome cannot provide. Biome handles everything else.

eslint.config.ts

import tseslint from 'typescript-eslint';

export default tseslint.config(
  {
    ignores: ['dist/', 'node_modules/', '*.config.*'],
  },
  {
    files: ['src/**/*.ts'],
    extends: [tseslint.configs.strictTypeChecked],
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
    rules: {
      // Disable rules that Biome already covers
      '@typescript-eslint/no-explicit-any': 'off',
      '@typescript-eslint/no-unused-vars': 'off',
      '@typescript-eslint/no-non-null-assertion': 'off',
      '@typescript-eslint/consistent-type-imports': 'off',

      // Keep the type-aware rules that Biome can't do
      '@typescript-eslint/no-misused-promises': 'error',
      '@typescript-eslint/await-thenable': 'error',
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/no-unsafe-assignment': 'error',
      '@typescript-eslint/no-unsafe-return': 'error',
      '@typescript-eslint/no-unsafe-call': 'error',
      '@typescript-eslint/no-unsafe-member-access': 'error',
      '@typescript-eslint/no-unsafe-argument': 'error',
      '@typescript-eslint/no-unnecessary-condition': 'error',
      '@typescript-eslint/strict-boolean-expressions': 'warn',
      '@typescript-eslint/prefer-readonly': 'error',
      '@typescript-eslint/require-await': 'error',
      '@typescript-eslint/return-await': ['error', 'always'],
    },
  },
);

Why This Hybrid Works

Biome runs in ~50ms for a medium project. ESLint with type-checking runs in 2-10 seconds. By using Biome for all syntax-level checks (fast, in-editor feedback) and ESLint only for type-aware rules (slower, CI and pre-commit), you get:

• Fast editor feedback (Biome)
• Deep type safety (ESLint)
• No rule conflicts (Biome rules disabled in ESLint config)

Package.json Scripts

{
  "scripts": {
    "lint": "biome check . && eslint src/",
    "lint:fix": "biome check --write . && eslint src/ --fix",
    "format": "biome format --write ."
  }
}

Vitest Configuration

Vitest is the testing framework. It provides test isolation (each file in its own worker), mature mocking, coverage, snapshot testing, and rich IDE integration.

vitest.config.ts

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: false,
    coverage: {
      provider: 'v8',
      reporter: ['text', 'lcov'],
      include: ['src/**/*.ts'],
      exclude: ['src/**/*.test.ts', 'src/**/*.d.ts'],
      thresholds: {
        branches: 80,
        functions: 80,
        lines: 80,
        statements: 80,
      },
    },
    include: ['src/**/*.test.ts'],
    typecheck: {
      enabled: true,
    },
  },
});

Test File Convention

Place test files next to the code they test:

src/
├── utils.ts
├── utils.test.ts
├── parser.ts
└── parser.test.ts

Running Tests

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage"
  }
}