Getting Started

🚧 Beta Software

Rolldown is currently in beta status. While it can already handle most production use cases, there may still be bugs and rough edges.

Installation

There are several ways to get started with tsdown. You can:

• Manually install it as a development dependency in your project.
• Use the starter templates to quickly scaffold a new project.
• Try it online using StackBlitz.

Manual Installation

Install tsdown as a development dependency using your preferred package manager:

npm

npm install -D tsdown

pnpm

pnpm add -D tsdown

yarn

yarn add -D tsdown

bun

bun add -D tsdown

Optionally, if you're not using isolatedDeclarations, you should also install TypeScript as a development dependency:

npm

npm install -D typescript

pnpm

pnpm add -D typescript

yarn

yarn add -D typescript

bun

bun add -D typescript

Compatibility Note

tsdown requires Node.js version 20.19 or higher. Please ensure your development environment meets this requirement before installing. While tsdown is primarily tested with Node.js, support for Deno and Bun is experimental and may not work as expected.

Starter Templates

To get started even faster, you can use the create-tsdown CLI, which provides a set of starter templates for building pure TypeScript libraries, as well as frontend libraries like React and Vue.

npm

npm create tsdown@latest

pnpm

pnpm create tsdown@latest

yarn

yarn create tsdown@latest

bun

bun create tsdown@latest

These templates includes ready-to-use configurations and best practices for building, testing and linting TypeScript projects.

Try Online

You can try tsdown directly in your browser using StackBlitz:

This template is preconfigured for tsdown, so you can experiment and get started quickly—no local setup required.

Using the CLI

To verify that tsdown is installed correctly, run the following command in your project directory:

./node_modules/.bin/tsdown --version

You can also explore the available CLI options and examples with:

./node_modules/.bin/tsdown --help

Your First Bundle

Let's create two source TypeScript files:

src/index.ts

import { hello } from './hello.ts'

hello()

src/hello.ts

export function hello() {
  console.log('Hello tsdown!')
}

Next, initialize the tsdown configuration file:

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['./src/index.ts'],
})

Now, run the following command to bundle your code:

./node_modules/.bin/tsdown

You should see the bundled output written to dist/index.mjs. To verify it works, run the output file:

node dist/index.mjs

You should see the message Hello tsdown! printed to the console.

Using the CLI in npm Scripts

To simplify the command, you can add it to your package.json scripts:

package.json

{
  "name": "my-tsdown-project",
  "type": "module",
  "scripts": {
    "build": "tsdown"
  },
  "devDependencies": {
    "tsdown": "^0.9.0"
  }
}

Now, you can build your project with:

npm run build

Using the Config File

While you can use the CLI directly, it's recommended to use a configuration file for more complex projects. This allows you to define and manage your build settings in a centralized and reusable way.

For more details, refer to the Config File documentation.

Using Plugins

tsdown supports plugins to extend its functionality. You can use Rolldown plugins, Unplugin plugins, and most Rollup plugins seamlessly. To use plugins, add them to the plugins array in your configuration file. For example:

tsdown.config.ts

import SomePlugin from 'some-plugin'
import { defineConfig } from 'tsdown'

export default defineConfig({
  plugins: [SomePlugin()],
})

For more details, refer to the Plugins documentation.

Using Watch Mode

You can enable watch mode to automatically rebuild your project whenever files change. This is particularly useful during development to streamline your workflow. Use the --watch (or -w) option:

tsdown --watch

For more details, refer to the Watch Mode documentation.