rollup 最佳实践🧻！可调试的微型开源项目思路

站长

2023年02月09日 04:54 · 阅读数 55

📖阅读本文，你将:

手把手带你搭建一个极简 npm 包（ rollup + esbuild + ts ）；
从工程结构全方位思考 npm 包的开发原则。
学会 rollup、esbuild 等新兴构建工具的使用（文末有本文结构的参考开源项目）；

一、前置阅读（推荐）

本文章不再赘述 rollup 和官方 rollup 插件的使用，因此有需要的话建议先阅读前置文章：

如果你对 rollup 和其官方插件有了一定了解，可跳过本节推荐的相关阅读；

二、目标

先制定一个小目标：

从零构建一个通过 rollup 构建的 npm 包；它可发布、可调试、支持 TypeScript、能够通过 cdn 引入页面、也可以通过 npm 在项目里安装引入。

这个目标有哪些关键词？让我们拆解一下：

是一个 可发布 的 npm 包；
通过 rollup 构建；
支持调试；
支持 TypeScript ;
能通过 cdn 方式引入
也支持通过 npm 安装；

看似简单，其实内中蕴含着许多前端相关的知识点，让我们一一梳理；

三、典型 `npm` 包的结构

我们发布一个 npm 包时，我们在发布什么？

一个用来声明 npm 属性的 package.json 文件；
若干可执行、可引入的文件；

仅此而已。

只有 package.json 是特殊的，除此之外的一切都可以被归为 “若干文件” 之列；

找一个最典型、最简单的 npm 包来印证我们的想法，你可以随便找个项目，执行以下命令：

npm i the-answer
# 传说，此库以 “功能丰富”、“毫无破绽” 闻名于世

然后找到 node_modules/the-answer 文件夹，看看其项目目录:

rollup 最佳实践🧻！可调试的微型开源项目思路

是以，要理解 npm 包，必须先从 package.json 入手，而一个典型的 package.json 至少应该具备以下属性：

{
  "name": "the-answer",
  "version": "1.0.0",
  "description": "description",
  "main": "dist/the-answer.js",
  "files": [
    "dist"
  ]
}

以上内容分别表示：

name: 包名
version: 版本
description: 包描述
main：入口
files：包发布时，需要将哪些文件打包上传

以上5个属性，足以支撑一个 npm 包的发布，但后续我们可能还会用到更多，此时，请先记住它们；

那么其他文件呢？

“协议” 和 “文档” 可以手动创建，但是 “构建物” 通常难逃 “构建” 这一过程。

rollup 是个不错的选择；

四、 `rollup` 的最简用法

4.1 安装 `rollup`

执行脚本：

npm i -D rollup
# or
yarn add -D rollup

4.2 创建 `rollup.config.js`

rollup.config.js 是 rollup 默认的配置文件

在这个配置文件里，最简单的配置莫过于：

配置入口文件
配置输出路径&格式

export default {
  input: path.resolve(__dirname, './src/index.ts'),
  output: [
    {
      dir: path.resolve(__dirname, 'dist/esm'),
      format: 'esm', // 通过esm格式输出
    }
  ]
}

4.3 编写构建脚本

在 package.json 文件中添加如下代码：

{
  ...,
  "scripts": {
    "build": "rollup -c"
  }
}

编写完上面脚本后，只需要执行：npm run build，就能成功完成一个最简单的 rollup 构建了。

但这还远远不够。

五、梳理：构建过程应该输出什么？

构建是为了有输出，输出是为了给客户使用。

因此，当我们构建时，应该率先考虑客户会在什么场景下使用我们的库。

（哪怕没有人真的用，但我们得假装自己的库会非常受欢迎，不是吗？🤣）

最常见的三种情况：

在构建工具中引入（esm）
在页面中直接引入（umd）
在nodejs 环境中使用 (cjs)

而本文的主要目标不涉及 nodejs 环境，因此暂时不考虑 cjs 输出，所以我们应该输出至少两种格式：

esm
umd

关于以上格式的区别，以及怎么输出，前置阅读推荐《说不清rollup能输出哪6种格式😥差点被鄙视》里有详细介绍；

通过参考目前开源社区的实现方式，我们还可以发现，通常一个开源库的 esm 产出物，并不是和 rollup 默认行为那样“把所有文件打包成一个 index.esm.js”，而是：

只编译，不打包；（这样就能完美支持按需引入了）

rollup 最佳实践🧻！可调试的微型开源项目思路

是的，文件结构依然和源码结构保持一致，只是将 TypeScript 编译为 javascript；

记住这个目标，它很重要；

六、编译 `TS` 哪家强？

虽然有提案让 ts 成为下一代的浏览器语言，但这只是还未到来的未来。

因此，如果我们的库是 TypeScript 编写的，那么我们在发布之前，一定需要将其编译为 javascript 类型。

那么，应该怎么编译呢？

社区里目前的主流方案有三类：

a. TypeScript www.npmjs.com/package/typ…

b. Esbuild esbuild.github.io/

c. Babel babeljs.io/

通过这篇文章：juejin.cn/post/708329… 的对比分析，可以得出结论：

【c】 比 【a】 支持的语言更丰富、编译速度更快；但是 .d.ts 还是推荐通过 【a】 中的 tsc 编译生成；

那么 【b】 选项 Esbuild 呢？

答案是：速度更快 ！

所以，我做出了如下选择：

使用 esbuild 进行 ts => js 的编译
使用 TypeScript 进行 .d.ts 文件的编译；

七、编译成 `esm` 格式

整个构建过程梳理清楚后，我们可以在项目里加入如下依赖：

npm i typescript esbuild rollup-plugin-esbuild --save-dev

除了以上这些之外，还有一些常规 rollup 插件不在此赘述；

创建文件：rollup.esm.config.js

export default {
  input: path.resolve(__dirname, './src/index.ts'),
  output: [
    {
      dir: path.resolve(__dirname, 'dist/esm'),
      format: 'esm',
    }
  ],
  // 关键属性，只有将其设置为 `true` 才能保证只编译、不打包
  preserveModules: true,
  plugins: [
    esbuild({
      target: 'es2018'
    }),
    nodeResolve(),
    json(),
  ],
  // 在 `esm` 构件中，`external` 非常重要，项目的 `dependencies` 里的内容理应都在此列
  external: ['gsap']
};

编写如下脚本：

{
  "scripts": {
    "build:esm": "rollup -c rollup.esm.config.js",
    "postbuild:esm": "tsc  --emitDeclarationOnly --declaration --project ts.config.json --outDir dist/esm",
  }
}

解释一下，postbuild:esm 是 build:esm 脚本的后置钩子，当 build:esm 执行完成后会自动执行 postbuild:esm；

执行脚本：

npm run build:esm

可以编译出如下效果的代码：

rollup 最佳实践🧻！可调试的微型开源项目思路

基本满足我们对 esm 格式编译产出的要求。

八、编译 `umd` 格式

和 esm 格式的编译要求不同，umd 格式更多的被用在 cdn 加载。

因此：

构建物不仅需要编译，还需要打包
无需 .d.ts 文件

创建 rollup.umd.config.js:


export default {
  input: path.resolve(__dirname, './src/index.ts'),
  output: [
    {
      file: path.resolve(__dirname, 'dist/umd/index.js'),
      format: 'umd',
      // 这个name属性非常重要，是通过 cdn 引入后，挂载到 window上的属性名
      name: 'rain'
    }
  ],
  plugins: [
    esbuild({
      // 为了应对 umd 直接加载到浏览器里，构建目标需要设定得兼容性更强
      target: 'es2015'
    }),
    // 需要babel plugin
    babel({
      presets: ['@babel/preset-env'],
      exclude: 'node_modules/**',
      babelHelpers: 'bundled'
    }),
    nodeResolve(),
    json(),
    commonjs()
  ],
};

编写脚本：

{
  "scripts": {
    "build:umd": "rollup -c rollup.umd.config.js",
  }
}

执行脚本 npm run build:umd 即可完成 umd 格式的编译。

完成 esm 和 umd 的编译后，需要考虑一下：

如何拥有一个良好的开发调试环境呢？

九、`umd` 构建物的调试

rollup 的命令行支持参数 -w （和 --watch 等价），其含义是监听源文件的变动，当文件发生变化时立刻更新文件；

这听起来和 webpack 的 hrm 类似。

因此，umd 环境下构建物的调试思路便出来了：

创建文件：examples/base/index.html
在 index.html里引入 dist/umd/index.js
起一个 http 静态服务以便访问 index.html 页面

这就是最简单的前端调试逻辑。

此时，我们需要用到三个工具：

cross-env 工具库通过 cross-env，我们可以轻易地跨平台地设置环境变量，比如:

cross-env NODE_ENV=production

可以把 process.env.NODE_ENV 设置成 production，这对我们的区分 “调试” 与 “构建” 具有非常大的帮助，

rollup-plugin-serve 插件这是一个 rollup 插件；通过这个插件，你可以：

在固定端口启动 http 静态服务
指定该端口的 root 文件夹
指定浏览器默认打开页面，并可以指定直接访问某个路由

rollup-plugin-livereload 插件这也是一个 rollup 插件；通过这个插件，可以监听某个文件夹，当里面的文件发生变动后，刷新页面。

使用以上三个工具，可以写出如下代码：

const isProduction = process.env.NODE_ENV === 'production'
const pluginsWithEnv = isProduction ? [] : [serve({
  open: true,
  openPage: '/base/',
  port: 10001,
  contentBase: ['dist', 'examples']
}), livereload('dist/umd')]

// 然后通过 ...pluginsWithEnv 把配置结构到 rollup的plugins 里面去

并添加脚本：

{
  "scripts": {
    "dev:umd": "cross-env NODE_ENV=development rollup -w -c rollup.umd.config.js"
  }
}

完成以上步骤：执行 npm run dev:umd 就能正常打开页面，以及完成调试了。

十、`esm` 构建物的调试

相比于 umd 那简单的调试结构，esm 通常情况下需要依赖构建工具，事情就变得复杂起来了。

我的选择是 在项目里内置一个基于 webpack/vite 的项目 ；

10.1 用 `vue-cli` 新增项目

先安装 vue-cli，见 vue-cli 官网

然后执行以下命令：

cd examples
vue create vue3

10.2 `import` 构建物

在 vue3 项目中通过相对路径引用 esm 构建物，引入方式如下：

import xx from '../../../'

注意，此处不需要指定到某个 js 文件，是因为要通过 esm 的导入方式，通过命中项目的 package.json，通过 exports、main、module 等属性命中它该命中的入口文件。

10.3 编写脚本

编写如下脚本：

{
  "scripts": {
    "serve:vue3": "cd ./examples/vue3 && yarn && yarn serve",
    "watch:esm": "cross-env NODE_ENV=development rollup -w -c rollup.esm.config.js",
  }
}

如果分别运行 npn run watch:esm 和 npm run serve:vue3，就能成功运行一个 vue3 项目，并成功进行调试。

10.4 并联两个脚本

因为 serve:vue3 和 watch:esm 这两个脚本都是会导致命令行的命令，因此如果你这样写一个脚本：

npn run watch:esm && npm run serve:vue3

那么 后者永远不会执行。

因此，两者必须同时执行。

再推荐一个小工具：npm-run-all www.npmjs.com/package/npm…

有了以上这个工具，你可以轻易的串行或者并行各种脚本。

此处只需要再新增一个脚本：

{
  "scripts": {
    "dev:esm": "run-p watch:esm serve:vue3",
  }
}

这样就可以异步同时执行两个脚本了。

十一、开发 & 发布

完成了以上所有步骤，你就可以开始安心开发脚本了，无论是 “构建” 抑或是 “调试”，目前都已经非常清晰了。

对于 rollup.js 在一个小型前端开源项目中应该如何使用，也渐渐摸清了脉络。

等开发完项目，则需要考虑发布的过程。

执行以下过程

npm version patch

项目编号会自动从 0.0.1 升级为 0.0.2。

再执行：

npm login
npm publish

就能成功发布你的开源库了。

十二、文章源码（供参考）

参见：github.com/zhangshichu…

十三、结束语

我是春哥。大龄前端打工仔，依然在努力学习。我的目标是给大家分享最实用、最有用的知识点，希望大家都可以早早下班，并可以飞速完成工作，淡定摸鱼🐟。

你可以在公众号里找到我：前端要摸鱼。

转载自:https://juejin.cn/post/7109260656431333390

rollup 最佳实践🧻！可调试的微型开源项目思路

📖阅读本文，你将:

一、前置阅读（推荐）

二、目标

三、典型 npm 包的结构

四、 rollup 的最简用法

4.1 安装 rollup

4.2 创建 rollup.config.js

4.3 编写构建脚本

五、梳理：构建过程应该输出什么？

六、编译 TS 哪家强？

七、编译成 esm 格式

八、编译 umd 格式

九、umd 构建物的调试

十、esm 构建物的调试

10.1 用 vue-cli 新增项目

10.2 import 构建物

10.3 编写脚本

10.4 并联两个脚本

十一、开发 & 发布

十二、文章源码（供参考）

十三、结束语

三、典型 `npm` 包的结构

四、 `rollup` 的最简用法

4.1 安装 `rollup`

4.2 创建 `rollup.config.js`

六、编译 `TS` 哪家强？

七、编译成 `esm` 格式

八、编译 `umd` 格式

九、`umd` 构建物的调试

十、`esm` 构建物的调试

10.1 用 `vue-cli` 新增项目

10.2 `import` 构建物