UI 视觉设计 / 系统课时

打包可复用的 ESM 资源入口

打包可复用的 ESM 资源入口

把上游生成的 Token JavaScript、CSS 和 TypeScript 声明收成一个可安装的 npm 包,避免业务项目直接依赖内部构建目录。完成后将获得明确的 ESM 与样式公开入口,并能在包外项目验证安装、导入和类型解析。

学习目标

  • 区分运行时 index.js、样式 tokens.css 与类型声明 index.d.ts 的职责。
  • 配置 exports、发布文件白名单和自动打包脚本。
  • 用独立消费项目验收 ESM 导入、CSS 子路径和 TypeScript 类型。

固定生成产物与目录边界

以 Node.js 22+、npm 10+ 和 Bash 为例,在空工作目录建立包项目与消费项目。Windows 可使用 WSL 或 Git Bash。

bash
# 两个项目分离,防止相对路径掩盖发布包缺失的问题
mkdir -p token-pkg/generated token-pkg/scripts consumer
cd token-pkg

预期结果:当前位于 token-pkg,同级存在 consumer 目录。

以下三个文件代表上游 Token 转换器已经生成的产物;可先照此保存,用于独立复现打包流程。实际工程应让三个文件从同一份 Token 数据生成,避免 JS 和 CSS 的值漂移。

generated/index.js 提供运行时 ESM 导出:

js
// JS 常量与 CSS 变量来自同一组 Token
export const tokens = Object.freeze({
  colorBrand600: "#2563eb",
  spaceControlGap: "8px"
});

generated/index.d.ts 声明相同的公开 API:

ts
export declare const tokens: Readonly<{
  colorBrand600: "#2563eb";
  spaceControlGap: "8px";
}>;

generated/tokens.css 提供浏览器可用的自定义属性:

css
:root {
  --color-brand-600: #2563eb;
  --space-control-gap: 8px;
}

Token 发布包从生成目录到独立项目的构建与消费路径

声明公开入口并构建 dist

在包根目录创建 package.json。type: module 让 .js 按 ESM 解释;exports 只开放根模块与 CSS 子路径,types 条件置于 import 之前,供 TypeScript 解析。files 限制发布目录,sideEffects 保留需要副作用加载的 CSS。

json
{
  "name": "@example/design-tokens",
  "version": "0.1.0",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./tokens.css": "./dist/tokens.css"
  },
  "sideEffects": ["**/*.css"],
  "scripts": {
    "build": "node scripts/build.mjs",
    "prepack": "npm run build"
  }
}

在 scripts/build.mjs 编写构建收口脚本。这里不重复实现上游 Token 转换,只将确定的三个成品复制到发布目录。

js
import { copyFile, mkdir, rm } from "node:fs/promises";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";

const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
const output = resolve(root, "dist");
// 删除旧产物,避免不再使用的文件混入新版本
await rm(output, { recursive: true, force: true });
await mkdir(output, { recursive: true });
for (const filename of ["index.js", "index.d.ts", "tokens.css"]) {
  // 缺任何一个发布文件都让构建立即失败
  await copyFile(resolve(root, "generated", filename), resolve(output, filename));
}
console.log("built: index.js, index.d.ts, tokens.css");

执行构建:

bash
npm run build

预期输出中包含:

text
built: index.js, index.d.ts, tokens.css

prepack 会在 npm pack 或 npm publish 前自动执行 build;不要把它误写成仅在本地安装时触发的钩子。这个包只提供 ESM,不承诺支持 require()。

用真正的安装包验证 ESM 与 CSS

继续在 token-pkg 目录打包,再切换到同级 consumer。不要在包项目内部直接导入自己的源码,那样会绕过 tarball 的文件白名单。

bash
# 先检查清单,再安装实际生成的 tgz,而不是源码目录
npm pack --dry-run
npm pack --pack-destination ../consumer
cd ../consumer
npm init -y
npm install ./example-design-tokens-0.1.0.tgz

预期结果:打包清单包含 package.json 和 dist/ 下的三个文件;消费项目的 node_modules/@example/design-tokens/ 也包含这些文件。打包日志和安装耗时会随环境变化。

在消费项目创建 consumer.mjs。Node.js 不会像 Vite 那样直接处理 CSS import,所以此处通过公开子路径定位并读取 CSS 文件,验证资源确实发布。

js
import { tokens } from "@example/design-tokens";
import { readFileSync } from "node:fs";

const stylesheet = new URL(import.meta.resolve("@example/design-tokens/tokens.css"));
const css = readFileSync(stylesheet, "utf8");
// 分别检查 JS 根入口和公开的 CSS 子路径
console.log(tokens.colorBrand600);
console.log(css.includes("--color-brand-600: #2563eb;"));

运行:

bash
node consumer.mjs

预期输出:

text
#2563eb
true

检查类型声明在包外可解析

在 consumer 中新建 check.mts。.mts 固定按 ESM 检查,精确字面量赋值可验证声明被正确读取,而不是仅确认文件存在。

ts
import { tokens } from "@example/design-tokens";
// 类型来自发布包的 index.d.ts
const brand: "#2563eb" = tokens.colorBrand600;
void brand;

安装 TypeScript 并执行检查:

bash
npm install --save-dev typescript@^5
npx tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 check.mts

预期结果:命令退出码为 0,TypeScript 不输出错误,也不生成 JS 文件。若报找不到模块,应先核对 tarball 是否包含 index.d.ts,再检查 exports["."]["types"] 的目标路径。

区分浏览器消费与常见失败

在已经配置 Vite 的前端项目中,CSS 需通过公开子路径主动导入。以下是放入现有 src/main.js 的片段示例,依赖浏览器 DOM 和 Vite 的 CSS 处理能力:

js
import "@example/design-tokens/tokens.css";
import { tokens } from "@example/design-tokens";

// 用 CSS 自定义属性控制界面颜色,而非重新硬编码色值
const badge = document.createElement("span");
badge.textContent = "Token";
badge.style.color = "var(--color-brand-600)";
document.body.append(badge);
console.log(tokens.spaceControlGap);

预期结果:页面显示蓝色文字 Token(#2563eb),浏览器控制台打印 8px。Node 的 consumer.mjs 测试通过,不代表浏览器已经自动加载 CSS。

失败现象 原因与修复
ERR_PACKAGE_PATH_NOT_EXPORTED 消费者导入了未公开的 dist/index.js;改用 @example/design-tokens。
ERR_MODULE_NOT_FOUND 入口指向的发布文件缺失;查看 npm pack --dry-run,重跑 npm run build。
变量存在但页面无样式 未导入 @example/design-tokens/tokens.css,或 CSS 被摇树删除;检查入口导入和 sideEffects。
TypeScript 无法解析类型 声明文件未打包或 types 路径错误;在独立项目重新执行 tsc。

只有从 .tgz 安装的项目同时通过运行时、CSS 和类型检查,才能确认包的公开入口可复用。正式发布前仍应让上游生成流程产出三份同源文件,而不是长期手工维护它们。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

打包可复用的 ESM 资源入口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通