Rollup.js参考手册

指南 | guide

指南 | tutorial

创建第一个bundle(Creating your first bundle)

开始前, 需要安装 Node.js，这样才可以使用 npm ；还需要了解如何使用 command line。

使用 Rollup 最简单的方法是通过 Command Line Interface （或 CLI）。先全局安装 Rollup （之后会介绍如何在项目中进行安装，更便于打包，但现在不用担心这个问题）。在命令行中输入以下内容：

npm install rollup --global # or `npm i rollup -g` for short

现在可以运行 rollup 命令了。试试吧~

rollup

由于没有传递参数，所以 Rollup 打印出了使用说明。这和运行 rollup --help 或 rollup -h 的效果一样。

我们来创建一个简单的项目：

mkdir -p my-rollup-project/src
cd my-rollup-project

首先，我们需要个入口。将以下代码粘贴到新建的文件 src/main.js 中：

// src/main.js
import foo from './foo.js';
export default function () {
  console.log(foo);
}

之后创建入口文件引用的 foo.js 模块：

// src/foo.js
export default 'hello world!';

现在可以创建 bundle 了：

rollup src/main.js -f cjs

-f 选项（--output.format 的缩写）指定了所创建 bundle 的类型——这里是 CommonJS（在 Node.js 中运行）。由于没有指定输出文件，所以会直接打印在 stdout 中：

'use strict';

var foo = 'hello world!';

var main = function () {
  console.log(foo);
};

module.exports = main;

也可以像下面一样将 bundle 保存为文件：

rollup src/main.js -o bundle.js -f cjs

（你也可以用 rollup src/main.js -f cjs > bundle.js，但是我们之后会提到，这种方法在生成 sourcemap 时灵活性不高。）

试着运行下面的代码：

node
> var myBundle = require('./bundle.js');
> myBundle();
'hello world!'

恭喜，你已经用 Rollup 完成了第一个 bundle。

使用配置文件(Using config files)

上面的方式还不错，但是如果添加更多的选项，这种命令行的方式就显得麻烦了。

为此，我们可以创建配置文件来囊括所需的选项。配置文件由 JavaScript 写成，比 CLI 更加灵活。

在项目中创建一个名为 rollup.config.js 的文件，增加如下代码：

// rollup.config.js
export default {
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
    format: 'cjs'
  }
};

我们用 --config 或 -c 来使用配置文件：

rm bundle.js # so we can check the command works!
rollup -c

同样的命令行选项将会覆盖配置文件中的选项：

rollup -c -o bundle-2.js # `-o` is short for `--output.file`

（注意 Rollup 本身会处理配置文件，所以可以使用 export default 语法——代码不会经过 Babel 等类似工具编译，所以只能使用所用 Node.js 版本支持的 ES2015 语法。）

如果愿意的话，也可以指定与默认 rollup.config.js 文件不同的配置文件：

rollup --config rollup.config.dev.js
rollup --config rollup.config.prod.js

使用插件(Using plugins)

目前为止，我们通过相对路径，将一个入口文件和一个模块创建成了一个简单的 bundle。随着构建更复杂的 bundle，通常需要更大的灵活性——引入 npm 安装的模块、通过 Babel 编译代码、和 JSON 文件打交道等。

为此，我们可以用 插件(plugins) 在打包的关键过程中更改 Rollup 的行为。the Rollup wiki 维护了可用的插件列表。

此教程中，我们将使用 rollup-plugin-json，令 Rollup 从 JSON 文件中读取数据。

在工程的根目录创建一个package.json 文件，内容如下：

{
  "name": "rollup-tutorial",
  "version": "1.0.0",
  "scripts": {
    "build": "rollup -c"
  }
}

将 rollup-plugin-json 安装为开发依赖：

npm install --save-dev rollup-plugin-json

（我们用的是 --save-dev 而不是 --save，因为代码实际执行时不依赖这个插件——只是在打包时使用。）

更新 src/main.js 文件，从 package.json 而非 src/foo.js 中读取数据：

// src/main.js
import { version } from '../package.json';

export default function () {
  console.log('version ' + version);
}

编辑 rollup.config.js 文件，加入 JSON 插件：

// rollup.config.js
import json from 'rollup-plugin-json';

export default {
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
    format: 'cjs'
  },
  plugins: [ json() ]
};

npm run build 执行 Rollup。结果如下：

'use strict';

var version = "1.0.0";

var main = function () {
  console.log('version ' + version);
};

module.exports = main;

（注意只有我们实际需要的数据——name 和 devDependencies 和 package.json 中的其它数据被忽略了。这是 tree-shaking 起了作用。）

实验中的代码分割（Experimental Code Splitting）

为了使用实验中性代码分割特性，我们添加第二个入口文件src/main2.js ，它将动态加载main.js

// src/main2.js
export default function () {
  return import('./main.js').then(({ default: main }) => {
    main();
  });
}

我们可以使用--dir 选项将输出设置为一个文件夹而不是文件，把它和入口文件一起传给rollup来构建（也要传如实验标签）

rollup src/main.js src/main2.js -f cjs --dir dist --experimentalCodeSplitting

任何构建入口的方式都可以在NodeJS中运行而不会在模块中重复任何代码

node -e "require('./dist/main2.js')()"

You can build the same code for the browser, for native ES modules, an AMD loader or SystemJS.

For example, with -f es for native modules:

你可以为浏览器、原生ES模块，AMD 加载器或者SystemJS构建同样的代码。

举个例子，可以 -f es 构建原生ES模块

rollup src/main.js src/main2.js -f es --dir dist --experimentalCodeSplitting

<!doctype html>
<script type="module">
  import main2 from './dist/main2.js';
  main2();
</script>

或者，为SystemJS使用 -f system:

rollup src/main.js src/main2.js -f system --dir dist --experimentalCodeSplitting

安装SystemJS通过

npm install --save-dev systemjs

现在按照需要可以为HTML页面加载任意一个或者全部入口文件：

<!doctype html>
<script src="node_modules/systemjs/dist/system-production.js"></script>
<script>
  System.import('./dist/main2.js')
  .then(({ default: main }) => main());
</script>

指南 | guide 相关

1.入门 \| introduction
2.命令行 \| command-line-reference
3. JavaScript API
4.其他工具 \| tools
5.模块语法 \| module-syntax
6.大选项列表 \| big-list-of-options
7.常见问题 \| faqs

Rollup.js

Rollup 是一个 JavaScript 模块打包工具，可以将小块代码编译成大块复杂的代码，例如 library 或应用程序。

Rollup.js目录

1.指南 \| guide