Tutorial 2: Package version tracking

Setting up the hook script

Create a file named hook-script.js in the root of your application repository and copy the following code. Then, make sure to replace @design-system with your actual design system package name in line 21.

const fs = require("fs/promises");
const path = require("path");
const pkgUp = require("pkg-up");

/**
 * Find the closest package.json file and retrieve the design system version.
 *
 * @param {string} filePath - The file path to start the search from.
 * @returns {Promise<string>} - The design system version or 'unknown' if not found.
 */
async function findDSPackageVersion(filePath) {
  try {
    const packageJsonPath = await pkgUp({ cwd: filePath });
    if (!packageJsonPath) return "unknown";

    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf-8"));
    const dependencies = packageJson.dependencies || {};
    const devDependencies = packageJson.devDependencies || {};

    // Example: Replace '@design-system' with your actual design system package name.
    return dependencies["@design-system"] || devDependencies["@design-system"] || "unknown";
  } catch (error) {
    console.error(`Error finding DS version for ${filePath}:`, error);
    return "unknown";
  }
}

/**
 * @type {import('@omlet/cli').CliHookModule}
 */
module.exports = {
  async afterScan(components) {
    const promises = components.map(async (component) => {
      const dsVersion = await findDSPackageVersion(component.filePath);
      component.setMetadata("DS Version", dsVersion);
    });

    // Wait for all metadata to be set
    await Promise.all(promises);
  },
};

This findDSPackageVersion function searches for the nearest package.json file relative to a given component’s file path and retrieves the version of your design system package.

The afterScan hook processes each component and sets it as DS Version property. Feel free to update the property to a preferred name.

Scan your repo

Use the --hook-script argument with the analyze command, specifying the path to your script:

npx @omlet/cli analyze --hook-script ./hook-script.js

yarn dlx @omlet/cli analyze --hook-script ./hook-script.js

pnpm dlx @omlet/cli analyze --hook-script ./hook-script.js

Filter components by DS Version

Once the CLI scan complete, the DS Version property will be associated with each component.

Navigate to the "Components" page. From the "Custom properties" filter, click DS Version and select a version from the revealed dropdown. This will list all the components using the selected package version.

You can create a tag based on this filter to easily access it later on and generate charts for your specific needs.

Analyze the usage

To analyze component usage, open your Analytics dashboard and click "Create new analysis" button on top-right. Under the Analyze section, select "DS Version" from "Custom properties". Total number of component usages for each package version will be listed.

From there, you can break down the chart by "Project it's used in" to understand which projects are using an older version of your design system.