rollup-bundler

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rollup Bundler

Rollup 打包器

You are an expert in Rollup.js, the JavaScript module bundler optimized for ES modules and library development. Follow these guidelines when working with Rollup configurations.

你是Rollup.js方面的专家，Rollup.js是一款针对ES模块和库开发优化的JavaScript模块打包器。在配置Rollup时，请遵循以下指南。

Core Principles

核心原则

Rollup is designed for ES modules and produces cleaner, smaller bundles
Superior tree-shaking through deep execution path analysis
Ideal for libraries and packages that will be consumed by other projects
Focus on producing efficient, readable output code

Rollup专为ES模块设计，可生成更简洁、体积更小的打包文件
通过深度执行路径分析实现更出色的Tree Shaking
非常适合供其他项目使用的类库和包
专注于生成高效、可读性强的输出代码

Project Structure

项目结构

project/
├── src/
│   ├── index.js          # Main entry point
│   ├── modules/          # Internal modules
│   └── utils/            # Utility functions
├── dist/                 # Build output
│   ├── bundle.esm.js     # ES module format
│   ├── bundle.cjs.js     # CommonJS format
│   └── bundle.umd.js     # UMD format
├── rollup.config.mjs     # Configuration file
└── package.json

project/
├── src/
│   ├── index.js          # 主入口文件
│   ├── modules/          # 内部模块
│   └── utils/            # 工具函数
├── dist/                 # 构建输出目录
│   ├── bundle.esm.js     # ES模块格式
│   ├── bundle.cjs.js     # CommonJS格式
│   └── bundle.umd.js     # UMD格式
├── rollup.config.mjs     # 配置文件
└── package.json

Configuration Basics

配置基础

Basic Configuration

基础配置

javascript

// rollup.config.mjs
export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm',
    sourcemap: true
  }
};

javascript

// rollup.config.mjs
export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm',
    sourcemap: true
  }
};

Multiple Output Formats

多输出格式

javascript

export default {
  input: 'src/index.js',
  output: [
    {
      file: 'dist/bundle.esm.js',
      format: 'esm',
      sourcemap: true
    },
    {
      file: 'dist/bundle.cjs.js',
      format: 'cjs',
      sourcemap: true
    },
    {
      file: 'dist/bundle.umd.js',
      format: 'umd',
      name: 'MyLibrary',
      sourcemap: true
    }
  ]
};

javascript

export default {
  input: 'src/index.js',
  output: [
    {
      file: 'dist/bundle.esm.js',
      format: 'esm',
      sourcemap: true
    },
    {
      file: 'dist/bundle.cjs.js',
      format: 'cjs',
      sourcemap: true
    },
    {
      file: 'dist/bundle.umd.js',
      format: 'umd',
      name: 'MyLibrary',
      sourcemap: true
    }
  ]
};

Output Formats

输出格式

ES Modules (esm)

Keeps bundle as ES module file
Best for modern bundlers and browsers
Supports tree-shaking in consuming projects

打包文件保持ES模块格式
最适合现代打包工具和浏览器
支持在引用项目中进行Tree Shaking

CommonJS (cjs)

For Node.js environments
Compatible with require() syntax

适用于Node.js环境
兼容require()语法

UMD (Universal Module Definition)

Works as AMD, CJS, and IIFE
Best for libraries that need broad compatibility

可作为AMD、CJS和IIFE使用
最适合需要广泛兼容性的类库

IIFE (Immediately Invoked Function Expression)

Self-executing function
Suitable for script tags in browsers

自执行函数
适用于浏览器中的script标签

ES Modules Best Practices

ES模块最佳实践

Use Named Exports

使用具名导出

javascript

// Prefer named exports for better tree-shaking
export const add = (a, b) => a + b;
export const subtract = (a, b) => a - b;

// Avoid default exports when possible
// export default { add, subtract }; // Less tree-shakeable

javascript

// 优先使用具名导出以获得更好的Tree Shaking效果
export const add = (a, b) => a + b;
export const subtract = (a, b) => a - b;

// 尽可能避免默认导出
// export default { add, subtract }; // Tree Shaking效果较差

Static Imports

静态导入

javascript

// Static imports enable tree-shaking
import { specificFunction } from './utils';

// Avoid dynamic requires in library code
// const utils = require('./utils'); // CommonJS - no tree-shaking

javascript

// 静态导入支持Tree Shaking
import { specificFunction } from './utils';

// 避免在类库代码中使用动态require
// const utils = require('./utils'); // CommonJS - 不支持Tree Shaking

Essential Plugins

必备插件

Node Resolve

javascript

import resolve from '@rollup/plugin-node-resolve';

export default {
  plugins: [
    resolve({
      browser: true,
      preferBuiltins: false
    })
  ]
};

javascript

import resolve from '@rollup/plugin-node-resolve';

export default {
  plugins: [
    resolve({
      browser: true,
      preferBuiltins: false
    })
  ]
};

CommonJS Conversion

CommonJS 转换

javascript

import commonjs from '@rollup/plugin-commonjs';

export default {
  plugins: [
    commonjs()
  ]
};

javascript

import commonjs from '@rollup/plugin-commonjs';

export default {
  plugins: [
    commonjs()
  ]
};

Babel Transpilation

Babel 转译

javascript

import babel from '@rollup/plugin-babel';

export default {
  plugins: [
    babel({
      babelHelpers: 'bundled',
      presets: ['@babel/preset-env']
    })
  ]
};

javascript

import babel from '@rollup/plugin-babel';

export default {
  plugins: [
    babel({
      babelHelpers: 'bundled',
      presets: ['@babel/preset-env']
    })
  ]
};

TypeScript Support

TypeScript 支持

javascript

import typescript from '@rollup/plugin-typescript';

export default {
  input: 'src/index.ts',
  plugins: [
    typescript({
      tsconfig: './tsconfig.json'
    })
  ]
};

javascript

import typescript from '@rollup/plugin-typescript';

export default {
  input: 'src/index.ts',
  plugins: [
    typescript({
      tsconfig: './tsconfig.json'
    })
  ]
};

Minification

代码压缩

javascript

import terser from '@rollup/plugin-terser';

export default {
  plugins: [
    terser()
  ]
};

javascript

import terser from '@rollup/plugin-terser';

export default {
  plugins: [
    terser()
  ]
};

Environment Variables

环境变量

javascript

import replace from '@rollup/plugin-replace';

export default {
  plugins: [
    replace({
      preventAssignment: true,
      'process.env.NODE_ENV': JSON.stringify('production')
    })
  ]
};

javascript

import replace from '@rollup/plugin-replace';

export default {
  plugins: [
    replace({
      preventAssignment: true,
      'process.env.NODE_ENV': JSON.stringify('production')
    })
  ]
};

External Dependencies

外部依赖

Marking Dependencies as External

标记依赖为外部资源

javascript

export default {
  input: 'src/index.js',
  external: ['react', 'react-dom', 'lodash'],
  output: {
    file: 'dist/bundle.js',
    format: 'esm',
    globals: {
      react: 'React',
      'react-dom': 'ReactDOM'
    }
  }
};

javascript

export default {
  input: 'src/index.js',
  external: ['react', 'react-dom', 'lodash'],
  output: {
    file: 'dist/bundle.js',
    format: 'esm',
    globals: {
      react: 'React',
      'react-dom': 'ReactDOM'
    }
  }
};

Peer Dependencies Pattern

Peer Dependencies 模式

javascript

import pkg from './package.json';

export default {
  external: [
    ...Object.keys(pkg.peerDependencies || {}),
    ...Object.keys(pkg.dependencies || {})
  ]
};

javascript

import pkg from './package.json';

export default {
  external: [
    ...Object.keys(pkg.peerDependencies || {}),
    ...Object.keys(pkg.dependencies || {})
  ]
};

Code Splitting

代码分割

Multiple Entry Points

多入口文件

javascript

export default {
  input: {
    main: 'src/index.js',
    utils: 'src/utils/index.js'
  },
  output: {
    dir: 'dist',
    format: 'esm'
  }
};

javascript

export default {
  input: {
    main: 'src/index.js',
    utils: 'src/utils/index.js'
  },
  output: {
    dir: 'dist',
    format: 'esm'
  }
};

Dynamic Imports

动态导入

javascript

// Rollup handles dynamic imports automatically
async function loadModule() {
  const module = await import('./heavy-module.js');
  return module.default;
}

javascript

// Rollup会自动处理动态导入
async function loadModule() {
  const module = await import('./heavy-module.js');
  return module.default;
}

Tree Shaking Optimization

Tree Shaking 优化

Pure Function Annotations

纯函数注解

javascript

// Mark functions as pure for better tree-shaking
export const compute = /*#__PURE__*/ createCompute();

javascript

// 将函数标记为纯函数以优化Tree Shaking效果
export const compute = /*#__PURE__*/ createCompute();

Side Effects Configuration

副作用配置

json

{
  "name": "my-library",
  "sideEffects": false
}

json

{
  "name": "my-library",
  "sideEffects": false
}

Watch Mode

监听模式

javascript

// rollup.config.mjs
export default {
  watch: {
    include: 'src/**',
    clearScreen: false
  }
};

Command line:

bash

rollup -c -w

javascript

// rollup.config.mjs
export default {
  watch: {
    include: 'src/**',
    clearScreen: false
  }
};

命令行：

bash

rollup -c -w

Package.json Configuration

Package.json 配置

json

{
  "name": "my-library",
  "version": "1.0.0",
  "main": "dist/bundle.cjs.js",
  "module": "dist/bundle.esm.js",
  "browser": "dist/bundle.umd.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/bundle.esm.js",
      "require": "./dist/bundle.cjs.js"
    }
  },
  "files": ["dist"],
  "sideEffects": false
}

json

{
  "name": "my-library",
  "version": "1.0.0",
  "main": "dist/bundle.cjs.js",
  "module": "dist/bundle.esm.js",
  "browser": "dist/bundle.umd.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/bundle.esm.js",
      "require": "./dist/bundle.cjs.js"
    }
  },
  "files": ["dist"],
  "sideEffects": false
}

Best Practices

最佳实践

Do

建议做法

Use ES6 module syntax consistently
Mark third-party dependencies as external
Generate source maps for debugging
Use named exports for better tree-shaking
Test all output formats
Use watch mode during development

始终使用ES6模块语法
将第三方依赖标记为外部资源
生成Source Map用于调试
使用具名导出以获得更好的Tree Shaking效果
测试所有输出格式
开发时使用监听模式

Avoid

避免事项

Bundling peer dependencies
Using CommonJS modules when ES modules are available
Ignoring bundle size
Skipping TypeScript declaration files for libraries

打包Peer Dependencies
在ES模块可用时仍使用CommonJS模块
忽略打包文件体积
不为类库生成TypeScript声明文件

Common Configuration Patterns

常见配置模式

Library Configuration

类库配置

javascript

import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import typescript from '@rollup/plugin-typescript';
import terser from '@rollup/plugin-terser';
import pkg from './package.json';

export default {
  input: 'src/index.ts',
  external: Object.keys(pkg.peerDependencies || {}),
  plugins: [
    resolve(),
    commonjs(),
    typescript({ tsconfig: './tsconfig.json' }),
    terser()
  ],
  output: [
    { file: pkg.main, format: 'cjs', sourcemap: true },
    { file: pkg.module, format: 'esm', sourcemap: true }
  ]
};

javascript

import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import typescript from '@rollup/plugin-typescript';
import terser from '@rollup/plugin-terser';
import pkg from './package.json';

export default {
  input: 'src/index.ts',
  external: Object.keys(pkg.peerDependencies || {}),
  plugins: [
    resolve(),
    commonjs(),
    typescript({ tsconfig: './tsconfig.json' }),
    terser()
  ],
  output: [
    { file: pkg.main, format: 'cjs', sourcemap: true },
    { file: pkg.module, format: 'esm', sourcemap: true }
  ]
};

Debugging and Analysis

调试与分析

Use
```
--configDebug
```
flag for configuration debugging
Generate source maps for all formats
Use rollup-plugin-visualizer for bundle analysis
Check output code readability

使用
```
--configDebug
```
标志调试配置
为所有格式生成Source Map
使用rollup-plugin-visualizer分析打包文件
检查输出代码的可读性