@vitus-labs/tools-rolldown

Rolldown-powered build tool for TypeScript libraries.

A fast, Rust-based alternative to @vitus-labs/tools-rollup.

Installation

bun add -d @vitus-labs/tools-rolldown

Usage

Add to your package.json:

{
  "scripts": {
    "build": "vl_rolldown_build",
    "dev": "vl_rolldown_build-watch"
  }
}

How it works

The build tool reads your package.json to determine what output bundles to produce:

| package.json field | Format | Platform | |---|---|---| | exports.import | ESM | universal | | exports.require | CJS | universal | | main | CJS or ESM | universal | | module | ESM | universal | | browser | same as source | browser | | react-native | ESM | native | | umd:main | UMD | — | | unpkg | UMD (minified) | — |

TypeScript declarations are generated automatically when exports.types (or types/typings) is set.

Platform globals

These constants are injected at build time based on the output platform:

| Constant | Description | |---|---| | __VERSION__ | Package version from package.json | | __BROWSER__ | true for browser builds | | __NODE__ | true for node builds | | __WEB__ | true for node + browser + universal | | __NATIVE__ | true for React Native builds | | __CLIENT__ | true for browser + native |

Add type declarations to your project:

{
  "compilerOptions": {
    "types": ["@vitus-labs/tools-rolldown/global"]
  }
}

Configuration

Configure via vl-tools.config.mjs (key: build):

export default {
  build: {
    sourceDir: 'src',
    outputDir: 'lib',
    typescript: true,
    esModulesOnly: false,
    replaceGlobals: true,
    external: ['react/jsx-runtime'],
    globals: {
      react: 'React',
      'react-dom': 'ReactDOM',
    },
  },
}

Advanced build options

For non-library builds (Chrome extensions, CLI tools, serverless functions, Electron), you can override the default package.json-driven pipeline:

export default {
  build: {
    // Explicit entries — skips package.json field detection
    entries: [
      { input: 'src/background.ts', file: 'dist/background.js', format: 'iife', env: 'production' },
      { input: 'src/content.ts', file: 'dist/content.js', format: 'iife' },
      { input: 'src/popup.ts', file: 'dist/popup.js', format: 'es' },
    ],

    // Bundle all dependencies (no externals)
    bundleAll: true,

    // Copy static assets after build
    copyFiles: [
      { from: 'src/manifest.json', to: 'dist/manifest.json' },
      { from: 'src/popup.html', to: 'dist/popup.html' },
    ],

    // Inject text at top/bottom of output
    banner: '#!/usr/bin/env node',
    footer: '// Generated by @vitus-labs/tools-rolldown',

    // Resolve aliases
    alias: {
      '@': './src',
      'node:crypto': './src/polyfills/crypto.ts',
    },

    // Custom rolldown plugins (appended to built-in ones)
    plugins: [],

    // Disable declarations for non-library builds
    typescript: false,
  },
}

| Option | Type | Default | Description | |---|---|---|---| | entries | Array<{ input, file, format?, env?, platform? }> | undefined | Explicit entry points (bypasses package.json detection) | | bundleAll | boolean | false | Bundle all dependencies instead of externalizing | | copyFiles | Array<{ from, to }> | undefined | Copy static files/directories after build | | banner | string | undefined | Text injected at the top of each output file | | footer | string | undefined | Text injected at the bottom of each output file | | alias | Record<string, string> | undefined | Resolve aliases for import remapping | | plugins | RolldownPlugin[] | [] | Custom plugins appended to built-in ones |

License

MIT