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 브랜치에 데이터를 푸시했습니다. 이렇게 하면 raw 리포트와 프로젝트 정보 JSON 파일에 대한 데이터 처리를 거쳐 사이트의 새로운 릴리스가 트리거됩니다.

저희는 프론트엔드 프로젝트에 공유 CI 템플릿을 사용하므로, 다른 팀 프로젝트의 데이터를 스캔하고 푸시하는 배포 후 단계를 추가할 수 있었습니다.

진행 상황

이제 여러 프로젝트에서 공유 컴포넌트가 어떻게 사용되고 있는지 빠르게 확인할 수 있는 단일 공간이 생겼습니다. 동작 변경이 프로젝트에 어떤 영향을 미칠지 판단하는 데 엔지니어와 디자이너 모두에게 유용합니다.

이 정보를 디자인 시스템 전략에 어떻게 활용할 수 있을지 탐색해 보고 싶습니다. 시간에 따른 디자인 시스템 도입률 지표는 팀을 더 잘 지원하는 방법을 이해하는 데 도움이 됩니다. 팀이 새로운 컴포넌트 사용을 시작하거나 중단한 시점을 파악할 수 있으면 직접 연락해 그 이유를 이해할 기회를 얻을 수 있습니다.