tsdown: Instructions file for Codex

AGENTS.md

This file provides guidance to coding agents when working with code in this repository.

Project Overview

tsdown is a blazing-fast bundler for TypeScript libraries powered by Rolldown and Oxc. It's designed as a seamless migration path from tsup with enhanced performance and features.

Key technologies:

• Rolldown: Core bundler (Rust-based Rollup alternative)
• pnpm: Package manager (v11)
• Node.js: ^22.18.0 || ^24.11.0 || >=26.0.0 (see engines in package.json)
• Vitest: Testing framework
• TypeScript: Strict mode with isolated declarations enabled
• ESM: Pure ESM package ("type": "module")

Development Commands

Building

# Build tsdown using itself (runs from source via Node's `dev` condition)
pnpm build

# Alias of `pnpm build`
pnpm dev

Testing

# Run all tests in watch mode
pnpm test

# Run tests without watch
pnpm test run

# Run a specific test file
pnpm test <file-pattern>
# Example: pnpm test src/config/options.test.ts

# Run with UI
pnpm test --ui

# Generate coverage
pnpm test --coverage

Code Quality

# Lint (ESLint with cache)
pnpm lint

# Fix lint issues
pnpm lint:fix

# Type check
pnpm typecheck

# Format code (Prettier)
pnpm format

Documentation

# Run docs dev server
pnpm docs:dev

# Build docs
pnpm docs:build

# Preview built docs
pnpm docs:preview

Architecture

Core Build Flow

CLI (src/run.ts → src/cli.ts)
  → build() (src/build.ts)
  → resolveConfig() (src/config/index.ts)
  → buildWithConfigs()
  → buildSingle() for each config
    → Hook: build:prepare
    → cleanOutDir()
    → getBuildOptions() → constructs Rolldown config
    → Hook: build:before
    → rolldownBuild() / rolldownWatch()
    → postBuild() → copy files, bundle processing
    → Hook: build:done
    → executeOnSuccess()

Configuration System

Multi-stage resolution pipeline:

1. Load config file (src/config/file.ts)
   • Searches for tsdown.config.{ts,mts,cts,js,mjs,cjs,json} or package.json (tsdown field)
   • Supports multiple loaders: native (Node.js native TS), tsx, unrun, auto (intelligent selection)
   • Can load from Vite/Vitest configs via fromVite option