tsdx README

The project's README from github.com/jaredpalmer/tsdx. As one markdown file: README.md.

TSDX

Zero-config CLI for TypeScript package development.

CI npm License: MIT

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

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

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:

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

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:

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:

{
  "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

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

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:

Author

License

MIT

tsdx (jaredpalmer/tsdx)

Searching Database…

11.5K ·GitHub
Tsdx
这是什么？TSDX 是一个零配置的命令行工具，帮助你以最少的设置开发、测试和发布 TypeScript 包。
它本身是打包工具，还是封装了其他工具？它是一个命令行封装工具，统筹调度其他现代工具：用 bunchee 打包，用 vitest 测试，用 oxlint 检查代码，用 oxfmt 格式化代码。
我该如何用它创建一个新的 TypeScript 包？全局安装后运行 'tsdx create'，从模板生成一个新包，然后编辑 src/index.ts 并进行构建。
使用它需要安装 bun 吗？需要。生成的项目使用 bun 管理包，并要求 Node.js 20+ 以及最新版本的 Bun。
使用我构建的库的人会注意到切换到 TSDX 2.0 吗？不会。构建输出格式与旧版 TSDX 完全兼容，不过开发流程和配置本身有所不同。
TSDX 2.0 为什么改用 bun 和基于 Rust 的工具？TSDX 2.0 重写为使用高性能的 Rust 工具：oxlint 比 ESLint 快 50–100 倍，oxfmt 比 Prettier 快 35 倍；bun 的包安装和脚本执行明显更快，同时保持与 npm 兼容。
tsdx build 会生成哪些输出格式？它会同时输出 ESM（dist/index.js）和 CommonJS（dist/index.cjs）格式，以及 TypeScript 声明文件（dist/index.d.ts 和 dist/index.d.cts），并自动配置 package.json 的 exports 字段。
我的库的用户仍然可以用 npm 或 yarn 而不是 bun 吗？可以。bun 只用于 TSDX 自身在开发过程中的包管理；构建后的包在使用方那边兼容 npm、yarn、pnpm 或 bun。
tsdx create 有哪些可用模板？内置两个模板：'basic'，即带有 vitest 的普通 TypeScript 库；'react'，即带有 Testing Library 的 React 组件库。
What are similar projects?Inquirer.js, nx, js-stack-from-scratch, patch-package, nexe, tsup, pkg, chokidar
Which topics is it in?linting, vitest, yarn, jest, packaging, build-tool, npm-package, node, javascript-library, testing, command-line-tool, react
Creator
jaredpalmer
Size
4.2 MB
Stars
11.5K
Updated
CommitDec 29Releasev2.0.0Dec 29
Age
7y
Commits · 90 Days