jaredpalmer/tsdx

TSDX

Zero-config CLI for TypeScript package development.

Modern TypeScript library development, simplified. TSDX provides a zero-config CLI that helps you develop, test, and publish TypeScript packages with ease.

TSDX 2.0 is a complete rewrite using modern, high-performance Rust-based tooling. See the Migration Guide if upgrading from v0.x

Features

• Zero config - Sensible defaults, just start coding
• Modern tooling - Built on bunchee, vitest, oxlint, and oxfmt
• Dual ESM/CJS - Automatic dual module builds with proper exports
• TypeScript first - Full TypeScript support with declaration generation
• Lightning fast - Rust-powered linting (50-100x faster than ESLint) and formatting (35x faster than Prettier)
• Bun-native - Uses bun for package management
• Modern Node.js - Supports Node.js 20+ (LTS)

Quick Start

# Create a new package
bunx tsdx create mylib

# Navigate to the project
cd mylib

# Start development
bun run dev

That's it! Start editing src/index.ts and build your library.

Installation

Global Installation (recommended for creating projects)

bun add -g tsdx

Per-Project Installation

bun add -D tsdx

Commands

tsdx create <name>

Create a new TypeScript package from a template.

# Interactive template selection
bunx tsdx create mylib

# Specify template directly
bunx tsdx create mylib --template react

Available Templates:

tsdx build

Build the package for production using bunchee.

tsdx build

# Skip cleaning dist folder
tsdx build --no-clean

Outputs ESM and CommonJS formats with TypeScript declarations.

tsdx dev / tsdx watch

Start development mode with file watching.

tsdx dev

Rebuilds automatically when files change.

tsdx test

Run tests using vitest.

# Run tests once
tsdx test

# Watch mode
tsdx test --watch

# With coverage
tsdx test --coverage

# Update snapshots
tsdx test --update

tsdx lint

Lint the codebase using oxlint.

# Lint src and test directories (default)
tsdx lint

# Lint specific paths
tsdx lint src lib

# Auto-fix issues
tsdx lint --fix

# Use custom config
tsdx lint --config .oxlintrc.json

tsdx format

Format the codebase using oxfmt.

# Format all files
tsdx format

# Check formatting without changes
tsdx format --check

# Format specific paths
tsdx format src test

tsdx typecheck

Run TypeScript type checking.

tsdx typecheck

# Watch mode
tsdx typecheck --watch

tsdx init

Initialize tsdx configuration in an existing project.

bunx tsdx init

This adds the necessary configuration to your package.json, creates tsconfig.json and vitest.config.ts if they don't exist.

Project Structure

Projects created with tsdx follow this structure:

mylib/
├── src/
│   └── index.ts          # Library entry point
├── test/
│   └── index.test.ts     # Tests (vitest)
├── dist/                  # Build output (generated)
│   ├── index.js          # ESM
│   ├── index.cjs         # CommonJS
│   └── index.d.ts        # TypeScript declarations
├── .github/
│   └── workflows/        # CI/CD workflows
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── LICENSE
└── README.md

React Template Additional Structure

mylib/
├── src/
│   └── index.tsx         # React component entry
├── test/
│   └── index.test.tsx    # Tests with Testing Library
├── example/              # Demo app (Vite-powered)
│   ├── index.tsx
│   ├── index.html
│   ├── package.json
│   └── vite.config.ts
└── ...

Module Formats

TSDX outputs both ESM and CommonJS formats:

The package.json exports field is configured automatically:

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

Tool Stack

TSDX 2.0 uses modern, high-performance tools:

Configuration

TypeScript (tsconfig.json)

TSDX creates a modern TypeScript configuration:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "declaration": true,
    "declarationMap": true
  }
}

Vitest (vitest.config.ts)

Default test configuration:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node', // or 'jsdom' for React
  },
});

Linting (.oxlintrc.json)

Optional oxlint configuration:

{
  "rules": {
    "no-unused-vars": "warn"
  }
}

Formatting (.oxfmtrc.json)

Optional oxfmt configuration:

{
  "indentWidth": 2,
  "lineWidth": 100
}

Requirements

• Node.js: 20+ (LTS)
• Bun: Latest version

Installing Bun

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1 | iex"

# npm (alternative)
npm install -g bun

Migrating from TSDX v0.x

See the Migration Guide for detailed instructions on upgrading from the original TSDX.

Quick summary:

1. Install bun
2. Update package.json scripts to use tsdx commands
3. Replace Jest with vitest
4. Replace ESLint with oxlint (optional)
5. Replace Prettier with oxfmt (optional)
6. Run bun install

Publishing

# Build the package
bun run build

# Publish to npm
npm publish

We recommend using np or changesets for publishing.

FAQ

Why bun?

Bun provides significantly faster package installation and script execution. It's compatible with npm packages and the Node.js ecosystem.

Can I still use npm/yarn/pnpm?

The generated projects use bun for package management, but the built packages are compatible with any package manager. Your library consumers can use npm, yarn, pnpm, or bun.

Why oxlint instead of ESLint?

oxlint is 50-100x faster than ESLint while catching the most important issues. For comprehensive linting, you can still use ESLint alongside oxlint.

Is this compatible with the old TSDX?

The build output format is fully compatible. Your library consumers won't notice any difference. However, the development workflow and configuration are different.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Acknowledgments

TSDX 2.0 is built on the shoulders of giants:

• bunchee by Jiachi Liu
• vitest by the Vitest team
• oxc by the OXC team
• bun by the Bun team

Author

• Jared Palmer

License

MIT