API Reference

runBuild()

runBuild(): Promise<void>

Orchestrates the complete build pipeline. Reads configuration, generates build variants, and executes each sequentially.

Steps:

Clean output directory (rimraf)
Create build pipeline from package.json fields
Execute each build with Rolldown
Report file sizes and generate visualization

import { runBuild } from '@vitus-labs/tools-rolldown'

await runBuild()

Configuration Shape

interface BuildConfig {
  sourceDir: string              // Input directory (default: 'src')
  outputDir: string              // Output directory (default: 'lib')
  typesDir: string               // Types output directory (default: 'lib/types')
  typescript: boolean            // Generate .d.ts files (default: true)
  replaceGlobals: boolean        // Inject platform globals (default: true)
  filesize: boolean              // Show file size stats (default: true)
  visualise: {
    template: string             // 'network' | 'treemap' | 'sunburst'
    gzipSize: boolean            // Show gzip sizes
    outputDir: string            // Analysis output dir (default: 'analysis')
  } | false
  extensions: string[]           // File extensions to resolve
  include: string[]              // Include patterns
  external: string[]             // Additional external packages
  exclude: string[]              // Exclude patterns
  globals: Record<string, string>  // UMD global variable mappings

  // Advanced build options
  entries?: Array<{              // Explicit entries (bypasses package.json)
    input: string
    file: string
    format?: 'es' | 'cjs' | 'umd' | 'iife'
    env?: 'development' | 'production'
    platform?: 'universal' | 'browser' | 'node' | 'native'
  }>
  bundleAll?: boolean            // Bundle all deps, no externals (default: false)
  copyFiles?: Array<{            // Copy static files post-build
    from: string
    to: string
  }>
  banner?: string                // Inject at top of output
  footer?: string                // Inject at bottom of output
  alias?: Record<string, string> // Resolve aliases
  plugins?: RolldownPlugin[]     // Custom plugins (default: [])
}

Default Configuration

{
  sourceDir: 'src',
  outputDir: 'lib',
  typesDir: 'lib/types',
  typescript: true,
  replaceGlobals: true,
  filesize: true,
  visualise: {
    template: 'network',
    gzipSize: true,
    outputDir: 'analysis',
  },
  extensions: ['.json', '.js', '.jsx', '.ts', '.tsx', '.es6', '.es', '.mjs'],
  include: ['src'],
  external: ['react/jsx-runtime'],
  exclude: [
    'lib',
    'node_modules/**',
    '**/__tests__/**',
    '**/__specs__/**',
    '**/__stories__/**',
    '*.test.*',
    '*.spec.*',
    '*.stories.*',
    'stories.*',
    '*.story.*',
  ],
  globals: {
    react: 'React',
    ReactDOM: 'react-dom',
  },
  entries: undefined,
  bundleAll: false,
  copyFiles: undefined,
  banner: undefined,
  footer: undefined,
  alias: undefined,
  plugins: [],
}

Build Pipeline Generation

The pipeline is generated from package.json fields:

exports Field Processing

Condition Key	Output Format	Platform
`import`	`'es'`	`'universal'`
`require`	`'cjs'`	`'universal'`
`node`	`'es'`	`'node'`
`default`	`'es'`	`'universal'`

Fallback Fields

Field	Output Format	Platform
`main`	Inferred from extension (`.cjs` → CJS, `.js` with `type: "module"` → ESM)	`'universal'`
`module`	`'es'`	`'universal'`
`react-native`	`'es'`	`'native'`

Build Variant Shape

interface BuildVariant {
  file: string           // Output file path
  format: 'es' | 'cjs' | 'umd' | 'iife'
  env: 'development' | 'production'
  platform: 'universal' | 'browser' | 'node' | 'web' | 'native'
  input?: string         // Per-entry input (overrides sourceDir)
  typesFilePath?: string // Only first build gets DTS
}

Plugin Pipeline

Each build uses these plugins (in order):

Plugin	Condition	Purpose
`nodeResolve`	Always	Resolves npm modules with platform-specific extensions
`rolldown-plugin-dts`	When `typesFilePath` set	Generates rolled-up `.d.ts` file
`replace`	When `replaceGlobals: true`	Injects platform constants
`visualizer`	When `visualise` configured	Bundle composition HTML
`filesize`	When `filesize: true`	Console file size reporting

Platform-Specific Extensions

For platform "browser", the resolver checks (in order):

.browser.json, .browser.js, .browser.jsx, .browser.ts, .browser.tsx,
.browser.es6, .browser.es, .browser.mjs,
.json, .js, .jsx, .ts, .tsx, .es6, .es, .mjs

Same pattern applies to node, web, and native platforms.

Output Configuration

ESM Output

{
  format: 'es',
  sourcemap: true,
  esModule: true,
}

CJS Output

{
  format: 'cjs',
  exports: 'named',
  sourcemap: true,
  esModule: true,
  interop: 'compat',
}

UMD Output

{
  format: 'umd',
  exports: 'named',
  name: PKG.bundleName,   // camelCase package name
  globals: swapGlobals(CONFIG.globals),
  sourcemap: true,
}

IIFE Output

{
  format: 'iife',
  exports: 'named',
  name: PKG.bundleName,
  sourcemap: true,
  esModule: true,
}

Exports

import { runBuild } from '@vitus-labs/tools-rolldown'

On this page