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

``bash


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

$3

`bash
bun add -g tsdx
`

$3

`bash
bun add -D tsdx
`

Commands

$3

Create a new TypeScript package from a template.

`bash


Interactive template selection

bunx tsdx create mylib

Specify template directly

bunx tsdx create mylib --template react
`

Available Templates:

| Template | Description |
|----------|-------------|
| basic | A basic TypeScript library with vitest |
| react | A React component library with Testing Library |

$3

Build the package for production using bunchee.

`bash
tsdx build

Skip cleaning dist folder


tsdx build --no-clean
`

Outputs ESM and CommonJS formats with TypeScript declarations.

$3

Start development mode with file watching.

`bash
tsdx dev
`

Rebuilds automatically when files change.

$3

Run tests using vitest.

`bash


Run tests once

tsdx test

Watch mode

tsdx test --watch

With coverage

tsdx test --coverage

Update snapshots

tsdx test --update
`

$3

Lint the codebase using oxlint.

`bash


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
`

$3

Format the codebase using oxfmt.

`bash


Format all files

tsdx format

Check formatting without changes

tsdx format --check

Format specific paths

tsdx format src test
`

$3

Run TypeScript type checking.

`bash
tsdx typecheck

Watch mode


tsdx typecheck --watch
`

$3

Initialize tsdx configuration in an existing project.

`bash
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
`

$3

`
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:

| File | Format | Usage |
|------|--------|-------|
| dist/index.js | ESM | Modern bundlers, Node.js with type: "module" |
| dist/index.cjs | CommonJS | Legacy Node.js, older bundlers |
| dist/index.d.ts | TypeScript | Type definitions |
| dist/index.d.cts | TypeScript | CJS type definitions |

The package.json exports field is configured automatically:

`json
{
"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:

| Tool | Purpose | Performance |
|------|---------|-------------|
| bunchee | Bundling | Zero-config, built on Rollup + SWC |
| vitest | Testing | Vite-native, Jest-compatible API |
| oxlint | Linting | 50-100x faster than ESLint |
| oxfmt | Formatting | 35x faster than Prettier |
| bun | Package Management | Native speed, npm-compatible |

Configuration

$3

TSDX creates a modern TypeScript configuration:

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

$3

Default test configuration:

`typescript
import { defineConfig } from 'vitest/config';

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

$3

Optional oxlint configuration:

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

$3

Optional oxfmt configuration:

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

Requirements

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

$3

`bash


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

`bash


Build the package

bun run build

Publish to npm

npm publish
``

We recommend using np or changesets for publishing.

FAQ

$3

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

$3

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.

$3

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

$3

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