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. Most notably, the built-in minification feature is still a work in progress.

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

Starter Template

To get started even faster, you can use the ts-starter template. This starter project is pre-configured for TypeScript library development with tsdown, allowing you to hit the ground running.

Clone the repository:

git clone https://github.com/sxzz/ts-starter my-library
cd my-library
pnpm install

This template includes a ready-to-use configuration and best practices for building TypeScript libraries.

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'],
})

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.