Skip to content
Get packs

Guide · Open source

How to use tsdx: create, build and test a TypeScript library

Updated · written with AI from the project's own documentation and checked against our catalogue data

tsdx is a command-line tool for building TypeScript libraries that you publish to npm. It creates a project from a template, builds ESM and CommonJS output with type declarations, and runs tests, linting and formatting with sensible defaults. This guide shows you how to install it, create a package, and run each main command.

TSDXjaredpalmer/tsdx · ★ 11.5k · MIT

Quick start

  1. 1Check requirements. Confirm you have Node.js 20 or newer and Bun installed.
  2. 2Install tsdx. Run bun add -g tsdx to install it globally for creating projects.
  3. 3Create a package. Run bunx tsdx create mylib, choosing basic or react when prompted or with --template.
  4. 4Start development. Enter the folder with cd mylib and run bun run dev to rebuild on changes.
  5. 5Test and check. Run tsdx test, tsdx lint and tsdx format --check before release.
  6. 6Build and publish. Run bun run build, then npm publish.

What you need before installing tsdx

tsdx 2.0 requires Node.js 20 or newer and Bun (latest version). The README lists these as requirements, and projects that cannot use Bun or need an older Node.js are not a good fit.

  • Node.js 20+ (LTS)
  • Bun, latest version
curl -fsSL https://bun.sh/install | bash

Install tsdx globally or per project

The README recommends a global install for creating new projects, and a per-project install for an existing package.

  • Global install (for creating projects): bun add -g tsdx
  • Per-project install: bun add -D tsdx
bun add -g tsdx

Create a new package from a template

Use tsdx create to generate a project. Without a template flag you get interactive template selection. The README lists two templates: basic, a TypeScript library with vitest, and react, a React component library with Testing Library.

  • basic: a basic TypeScript library with vitest
  • react: a React component library with Testing Library
bunx tsdx create mylib --template react

Build, develop and test the package

tsdx build compiles the package using bunchee and writes ESM and CommonJS output with TypeScript declarations. Use tsdx dev (or tsdx watch) to rebuild on file changes, and tsdx test to run vitest. The README also documents tsdx typecheck for type checking.

  • tsdx build: production build; use --no-clean to skip cleaning the dist folder
  • tsdx dev / tsdx watch: rebuild when files change
  • tsdx test: run once; add --watch, --coverage or --update as needed
  • tsdx typecheck: run TypeScript type checking; add --watch for watch mode
tsdx build tsdx test --coverage

Lint and format the code

tsdx lint uses oxlint and checks src and test by default. tsdx format uses oxfmt. Both accept options; the README shows --fix for lint and --check for format, which reports formatting problems without changing files.

  • tsdx lint --fix: auto-fix issues
  • tsdx lint --config .oxlintrc.json: use a custom config
  • tsdx format --check: check formatting without changing files
tsdx lint --fix tsdx format --check

Understand the output files

A build writes files to dist. The README lists dist/index.js for ESM, dist/index.cjs for CommonJS, and dist/index.d.ts and dist/index.d.cts for type definitions. The package.json exports field is set up automatically, so consumers can use either import or require.

  • dist/index.js: ESM
  • dist/index.cjs: CommonJS
  • dist/index.d.ts and dist/index.d.cts: TypeScript definitions

Publish to npm

Build first, then publish. The README shows bun run build followed by npm publish, and recommends np or changesets for publishing.

bun run build npm publish

Upgrading from TSDX v0.x

tsdx 2.0 replaces the original Jest and ESLint setup with vitest and oxlint. The README gives a short migration checklist and points to the Migration Guide for full instructions. The build output format is described as fully compatible, but the development workflow and configuration differ.

  • Install bun
  • Update package.json scripts to use tsdx commands
  • Replace Jest with vitest
  • Replace ESLint with oxlint (optional)
  • Replace Prettier with oxfmt (optional)
  • Run bun install

What people use it for

  • Publishing a reusable TypeScript library to npm without writing build configuration
  • Starting a React component library with a Testing Library template
  • Building and testing packages in a Bun-based workflow with one tool
  • Upgrading an existing v0.x TSDX project by following the migration guide

Frequently asked questions

How do I install tsdx?

Install Bun first, then run bun add -g tsdx for a global install that creates projects, or bun add -D tsdx inside an existing project. The README lists Node.js 20+ and Bun as requirements.

What are the requirements for tsdx?

The README lists Node.js 20 or newer (LTS) and the latest version of Bun. Projects that need an older Node.js or cannot use Bun are not suited to tsdx 2.0.

Is tsdx free to use?

The repository is licensed under MIT, as stated in the README and the project's license file. Check the LICENSE file in the repository for the full terms.

How does tsdx compare to tsup or unbuild?

tsup, unbuild and microbundle are comparable projects for building TypeScript packages. tsdx differs by bundling its own template, testing, linting and formatting in one CLI, and by using bun for package management. This page does not benchmark them against each other.

Can I use tsdx with npm, yarn or pnpm?

The README says generated projects use bun for package management, but the built packages work with any package manager. Library consumers can use npm, yarn, pnpm or bun.

How do I upgrade from TSDX v0.x?

Follow the Migration Guide linked in the README. In summary, install Bun, update package.json scripts, replace Jest with vitest, and optionally replace ESLint with oxlint and Prettier with oxfmt, then run bun install.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

tsdx suits developers who want to publish a TypeScript library to npm with little configuration, especially if they already use Bun or want a React template with Testing Library. If you are building an application or website, or you cannot use Bun or Node.js 20+, pick a different tool and consider comparable projects such as tsup, unbuild or microbundle.

Install options & downloads