Creating your own React design system analytics tool

2024-11-13

打造自己的 React 设计系统分析工具

原文由 Alex O'Callaghan 于 2024-11-13 发布，订阅该博客

像 Omlet 这样的服务可以帮你了解 React 设计系统在各个项目中的使用情况。这对于维护设计系统的团队来说非常有用。但它的定价并不便宜，而且会按 React 组件的数量来计费。我便开始研究如何自建一套系统，在不额外花钱的情况下也能获得类似的洞察。

react-scanner

react-scanner 是一个可以对 React 应用进行静态分析的 npm 包。它能输出 JSON，描述代码库中来自指定包的组件的使用情况。

该包通过 @typescript-eslint/typescript-estree 和 astray 来构建并遍历代码库的抽象语法树（AST）。它会找出从设计系统中引入的组件，以及这些组件使用了哪些 props。

搭建 CLI

我把 react-scanner 封装成了一个 CLI，这样就能在每次发布时于项目的 CI 流水线中执行：

#! /usr/bin/env node

import { Command } from "@commander-js/extra-typings";

const program = new Command().option(
  "-d, --dir <path>",
  "set project directory"
);

program.parse();

const options = program.opts();

const dir = path.resolve(options.dir) || cwd();

const scannerConfig = {
  rootDir: dir,
  crawlFrom: "./src",
  includeSubComponents: true,
  importedFrom: "your-design-system-package",
  processors: [["raw-report", { outputTo: `${dir}/raw-report.json` }]],
};

await scanner.run(scannerConfig);

相关结构可以在 react-scanner 文档中找到。

我还想收集一些关于项目的额外信息，并将其写入单独的项目信息 JSON 文件中：

const pkg = JSON.parse(fs.readFileSync(`${dir}/package.json`, "utf8"));

// Create project info file
const projectInfo = {
  name: pkg.name,
  pkgVersion: pkg.dependencies["your-design-system-package"],
  timestamp: new Date().getTime(),
  url: process.env.CI_PROJECT_URL,
};

if (!projectInfo.pkgVersion) {
  console.log(
    "No design system package version found in package.json, exiting..."
  );
  process.exit();
}

name - 项目名称，用于标识报告来自哪个项目
pkgVersion - 项目中所用设计系统包的版本，用于了解各项目的更新情况
timestamp - 报告生成的时间，用于判断报告的新旧程度，也便于观察随时间的变化
url - 项目的 URL，这样就能直接拼接出跳转到组件使用处文件的链接。我们使用 GitLab，该环境变量会在 GitLab CI 流水线中自动设置。

存储与展示数据

我决定用一个简单的静态网站来展示数据，就像我之前做 DORA 指标时采用的方案一样。

我为该项目配置了 GitLab 项目访问令牌，并通过 GitLab Commits API 将数据推送到数据仓库的 main 分支。这会触发网站的新版本发布，并对原始报告和项目信息 JSON 文件进行一些数据处理。

我们的前端项目使用共享的 CI 模板，因此我得以添加一个部署后步骤，自动扫描并推送其他团队项目的数据。

目前的效果

现在，我们有了一个统一的地方，可以快速查看共享组件在各个项目中的使用情况。这对工程师和设计师都很有用，能帮助大家评估行为变更可能对项目造成的影响。

我还想进一步探索如何利用这些信息来指导设计系统的策略。设计系统随时间推移的采用率指标，能帮助我们了解如何更好地支持团队。而当我们能看到团队何时开始或停止使用某个新组件时，就有机会主动去沟通，了解背后的原因。

打造自己的 React 设计系统分析工具

react-scanner

搭建 CLI

存储与展示数据

目前的效果

评论