Rolldown

Rolldown is a modern JavaScript bundler that focuses on simplicity, performance, and ease of use. It's designed to be a drop-in replacement for tools like Rollup or esbuild, with a focus on modern JavaScript and TypeScript projects.

Overview

Rolldown is the underlying bundler used by tsdown in the ts-package-template. It provides:

Fast builds: Optimized for modern JavaScript and TypeScript
Simple configuration: Easy to understand and customize
ESM-first: Designed for ECMAScript Modules
TypeScript support: Native TypeScript support through plugins like tsdown
Modern features: Support for the latest JavaScript features

Why Rolldown?

The template uses Rolldown because:

Performance: Rolldown is optimized for fast builds
Modern: Designed for modern JavaScript and TypeScript
Simple: Easy to configure and use
Extensible: Supports plugins for additional functionality
Active Development: Actively maintained with regular updates

Integration with tsdown

In the ts-package-template, Rolldown is used through tsdown, which is a TypeScript plugin for Rolldown. This provides seamless TypeScript integration without requiring complex configuration.

The tsdown.config.ts file configures both tsdown and Rolldown:

import { defineConfig } from "tsdown";

export default defineConfig({
  entry: {
    index: "src/index.ts",
  },
  dts: true,
  tsconfig: "tsconfig.build.json",
  format: "esm",
  sourcemap: false,
});

Rolldown Features Used in the Template

Entry Points

Rolldown supports multiple entry points for your package:

entry: {
  index: "src/index.ts",
  utils: "src/utils/index.ts",
}

Output Formats

Generate different module formats:

format: "esm",      // ECMAScript Modules
format: "cjs",      // CommonJS
format: ["esm", "cjs"], // Multiple formats

Code Splitting

Rolldown supports code splitting for better performance:

// Automatic code splitting based on imports

Minification

Minify the output for production:

minify: true,

Source Maps

Generate source maps for debugging:

sourcemap: true,

Using Rolldown Directly

While the template uses tsdown (which uses Rolldown internally), you can also use Rolldown directly for more control.

Install Rolldown

pnpm add -D rolldown

Basic Rolldown Configuration

Create a rolldown.config.ts file:

import { defineConfig } from "rolldown";

export default defineConfig({
  input: "src/index.ts",
  output: {
    dir: "dist",
    format: "esm",
  },
  plugins: [
    // Add plugins as needed
  ],
});

Using Rolldown with TypeScript

To use Rolldown directly with TypeScript, you need to:

Install the TypeScript plugin:
```
pnpm add -D @rolldown/plugin-typescript
```

Configure Rolldown:

import { defineConfig } from "rolldown";
import typescript from "@rolldown/plugin-typescript";

export default defineConfig({
  input: "src/index.ts",
  output: {
    dir: "dist",
    format: "esm",
  },
  plugins: [
    typescript({
      tsconfig: "tsconfig.build.json",
    }),
  ],
});

Rolldown vs Other Bundlers

Rolldown vs Rollup

Feature	Rolldown	Rollup
Performance	⚡ Faster	🏃‍♂️ Good
Configuration	🎯 Simple	📚 Complex
ESM Support	✅ Native	✅ Good
TypeScript	🔌 Plugin	🔌 Plugin
Modern Features	✅ Yes	✅ Yes

Rolldown vs esbuild

Feature	Rolldown	esbuild
Performance	⚡ Very Fast	⚡ Very Fast
Configuration	🎯 Simple	🎯 Simple
ESM Support	✅ Native	✅ Native
TypeScript	🔌 Plugin	✅ Built-in
Plugins	✅ Yes	❌ Limited

Rolldown vs Vite

Feature	Rolldown	Vite
Primary Use	📦 Library	🌐 App
Performance	⚡ Fast	⚡ Fast
HMR	❌ No	✅ Yes
Dev Server	❌ No	✅ Yes
TypeScript	🔌 Plugin	✅ Built-in

Rolldown is primarily designed for building libraries and packages, while Vite is optimized for building applications with features like HMR and dev server.

Advanced Rolldown Features

Custom Plugins

Create custom plugins for Rolldown:

import { defineConfig } from "rolldown";

const myPlugin = () => ({
  name: "my-plugin",
  // Plugin hooks
  buildStart() {
    console.log("Build started");
  },
  buildEnd() {
    console.log("Build finished");
  },
});

export default defineConfig({
  input: "src/index.ts",
  plugins: [myPlugin()],
});

Environment Variables

Access environment variables in your configuration:

import { defineConfig } from "rolldown";

export default defineConfig({
  input: "src/index.ts",
  define: {
    "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV),
  },
});

External Dependencies

Mark dependencies as external (not bundled):

export default defineConfig({
  input: "src/index.ts",
  external: ["react", "react-dom", "lodash"],
});

Aliases

Configure path aliases:

export default defineConfig({
  input: "src/index.ts",
  resolve: {
    alias: {
      "@": "./src",
      "~": ".",
    },
  },
});

Build fails with TypeScript errors:
- Run pnpm run check to identify and fix type errors
- Ensure your TypeScript configuration is correct
Missing output files:
- Check that the entry point paths are correct
- Verify that the source files exist
Slow builds:
- Limit the number of entry points
- Use minify: false during development
- Check for circular dependencies
Module resolution issues:
- Ensure moduleResolution: "bundler" in tsconfig.json
- Check that all dependencies are installed

Debug Mode

Run Rolldown with debug logging:

DEBUG=rolldown pnpm run build

Resources

Rolldown Documentation
Rolldown GitHub Repository
Rolldown Configuration Reference
Rolldown Plugins
tsdown Documentation - TypeScript plugin for Rolldown

TPT