gem-hunter
Language: TypeScript
Zero-config CLI for TypeScript package development
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
# 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.
bun add -g tsdx
bun add -D tsdx
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 |
Build the package for production using bunchee.
tsdx build
# Skip cleaning dist folder
tsdx build --no-cleanOutputs ESM and CommonJS formats with TypeScript declarations.
Start development mode with file watching.
tsdx dev
Rebuilds automatically when files change.
Run tests using vitest.
# Run tests once tsdx test # Watch mode tsdx test --watch # With coverage tsdx test --coverage # Update snapshots tsdx test --update
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
Format the codebase using oxfmt.
# Format all files tsdx format # Check formatting without changes tsdx format --check # Format specific paths tsdx format src test
Run TypeScript type checking.
tsdx typecheck
# Watch mode
tsdx typecheck --watchInitialize 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.
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
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
└── ...
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"
}
}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 |
TSDX creates a modern TypeScript configuration:
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"declaration": true,
"declarationMap": true
}
}Default test configuration:
import { defineConfig } from 'vitest/config'; export default defineConfig({ test: { globals: true, environment: 'node', // or 'jsdom' for React }, });
Optional oxlint configuration:
{
"rules": {
"no-unused-vars": "warn"
}
}Optional oxfmt configuration:
{
"indentWidth": 2,
"lineWidth": 100
}# macOS/Linux curl -fsSL https://bun.sh/install | bash # Windows powershell -c "irm bun.sh/install.ps1 | iex" # npm (alternative) npm install -g bun
See the Migration Guide for detailed instructions on upgrading from the original TSDX.
Quick summary:
package.json scripts to use tsdx commandsbun install# Build the package bun run build # Publish to npm npm publish
We recommend using np or changesets for publishing.
Bun provides significantly faster package installation and script execution. It's compatible with npm packages and the Node.js ecosystem.
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.
oxlint is 50-100x faster than ESLint while catching the most important issues. For comprehensive linting, you can still use ESLint alongside oxlint.
The build output format is fully compatible. Your library consumers won't notice any difference. However, the development workflow and configuration are different.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
TSDX 2.0 is built on the shoulders of giants: