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。
# 两个项目分离,防止相对路径掩盖发布包缺失的问题
mkdir -p token-pkg/generated token-pkg/scripts consumer
cd token-pkg预期结果:当前位于 token-pkg,同级存在 consumer 目录。
以下三个文件代表上游 Token 转换器已经生成的产物;可先照此保存,用于独立复现打包流程。实际工程应让三个文件从同一份 Token 数据生成,避免 JS 和 CSS 的值漂移。
generated/index.js 提供运行时 ESM 导出:
// JS 常量与 CSS 变量来自同一组 Token
export const tokens = Object.freeze({
colorBrand600: "#2563eb",
spaceControlGap: "8px"
});generated/index.d.ts 声明相同的公开 API:
export declare const tokens: Readonly<{
colorBrand600: "#2563eb";
spaceControlGap: "8px";
}>;generated/tokens.css 提供浏览器可用的自定义属性:
:root {
--color-brand-600: #2563eb;
--space-control-gap: 8px;
}
声明公开入口并构建 dist
在包根目录创建 package.json。type: module 让 .js 按 ESM 解释;exports 只开放根模块与 CSS 子路径,types 条件置于 import 之前,供 TypeScript 解析。files 限制发布目录,sideEffects 保留需要副作用加载的 CSS。
{
"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 转换,只将确定的三个成品复制到发布目录。
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");执行构建:
npm run build预期输出中包含:
built: index.js, index.d.ts, tokens.cssprepack 会在 npm pack 或 npm publish 前自动执行 build;不要把它误写成仅在本地安装时触发的钩子。这个包只提供 ESM,不承诺支持 require()。
用真正的安装包验证 ESM 与 CSS
继续在 token-pkg 目录打包,再切换到同级 consumer。不要在包项目内部直接导入自己的源码,那样会绕过 tarball 的文件白名单。
# 先检查清单,再安装实际生成的 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 文件,验证资源确实发布。
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;"));运行:
node consumer.mjs预期输出:
#2563eb
true检查类型声明在包外可解析
在 consumer 中新建 check.mts。.mts 固定按 ESM 检查,精确字面量赋值可验证声明被正确读取,而不是仅确认文件存在。
import { tokens } from "@example/design-tokens";
// 类型来自发布包的 index.d.ts
const brand: "#2563eb" = tokens.colorBrand600;
void brand;安装 TypeScript 并执行检查:
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 处理能力:
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 和类型检查,才能确认包的公开入口可复用。正式发布前仍应让上游生成流程产出三份同源文件,而不是长期手工维护它们。