跨环境前端组件库打包方案（node+esm）

朝花夕拾

跨环境前端组件库打包方案（node+esm）

By ZTao-z 1

背景

最近项目中需要把一个功能做成通用方案，抽离一个公共组件库。方案由两部分组成，包括一个用在页面上的组件库（lib.ts），以及一个用在打包期间的vite插件（plugin.ts）。

- src
  - lib.ts
  - plugin.ts

设想打包后的结果可以通过import引入

// 页面
import { Lib } from 'MyLib/lib';
// vite.config.js
import { VitePlugin } from 'MyLib/plugin';

初始方案

一开始打算直接使用 vite 采用多入口的方式打包，然后使用dts库生成对应的.d.ts文件。由于vite-plugin运行在node环境中，里面用到的库都是node环境库，在浏览器上不可使用，因此需要加一个nodePolyfills进行兼容。

// vite.config.js
import { defineConfig } from 'vite';
import { nodePolyfills } from 'vite-plugin-node-polyfills';
import dts from "vite-plugin-dts";

// https://vitejs.dev/config/
export default defineConfig({
  build: {
    //打包后文件目录
    outDir: "build",
    //压缩
    minify: false,
    lib: {
      entry: ["./src/lib.ts", "./src/plugin.ts"],
      name: "MyLib",
      formats: ["es", "cjs"]
    },
  },
  plugins: [
    vue(),
    dts({
      insertTypesEntry: true,
    }),
    nodePolyfills({
      // To exclude specific polyfills, add them to this list.
      include: [
        'fs', // Excludes the polyfill for `fs` and `node:fs`.
        'path', // Excludes the polyfill for `path` and `node:path`.
      ],
      // Whether to polyfill specific globals.
      globals: {
        Buffer: true, // can also be 'build', 'dev', or false
        global: true,
        process: true,
      },
      // Whether to polyfill `node:` protocol imports.
      protocolImports: true,
    }),
  ],
})

思路看起来很美好，配置也简单，也确实生成了对应的打包后的js。但有两个小问题：

  1. plugin.ts 本身只有20行代码，但是加了polyfill后体积直接爆炸，变成了400+行。况且node脚本本来就能直接运行的，不需要过度打包
  2. 跑不起来，node脚本polyfill后的结果与node环境不兼容，寄

思路

  1. 对于在页面上使用的组件库，采用vite + esm打包方式，并输出.d.ts文件
  2. 对于node脚本，直接采用tsc进行编译就好了，并输出.d.ts文件

实现方式

lib.ts 交由vite进行esm打包，而 plugin.ts 直接用命令行 + tsc 打包即可。

// vite.config.js
import { defineConfig } from 'vite';
import dts from "vite-plugin-dts";

// https://vitejs.dev/config/
export default defineConfig({
  build: {
    //打包后文件目录
    outDir: "build",
    //压缩
    minify: false,
    lib: {
      entry: ["./src/lib.ts"],
      name: "MyLib",
      formats: ["es", "cjs"]
    },
  },
  plugins: [
    dts({
      insertTypesEntry: true,
    }),
  ],
})

在 package.json 中编写打包命令

{
    "script": {
        "build": "pnpm build:lib && pnpm build:plugin",
        "build:lib": "vite build",
        "build:plugin": "tsc --outDir build src/plugin.ts --declaration"
    }
}

最后直接运行 npm build 就完成打包了，再用 npm publish 就发布成独立组件库了。

使用问题

当使用npm安装组件库时，发现上一步打包生成的.d.ts文件，在项目中居然没有自动识别到对应的类型定义并应用。查了很多文档才发现需要在 package.json 中声明类型文件。

如果是纯组件库，一般声明文件会放在同一个.d.ts文件里，可以简单地用 types 字段声明类型文件，形如：

{
    "name": "awesome",
    "author": "Vandelay Industries",
    "version": "1.0.0",
    "main": "./lib/main.js",
    "types": "./lib/main.d.ts"
}

但在这个项目里，存在不同场景的组件，各组件分别有自己的一个类型文件，不能通过一个.d.ts来实现。通过查找文档，发现了一个更灵活的属性 exports。通过它可以指定引用路径以及对应的文件：

{
  "exports": {
    "./lib": {
      "import": {
        "default": "./build/lib.js",
        "types": "./build/lib.d.ts"
      },
      "require": {
        "default": "./build/lib.mjs",
        "types": "./build/lib.d.ts"
      }
    },
    "./plugin": {
      "import": {
        "default": "./build/plugin.js",
        "types": "./build/plugin.d.ts"
      },
      "require": {
        "default": "./build/plugin.js",
        "types": "./build/plugin.d.ts"
      }
    }
  }
}

至此，问题圆满解决~