Tutorial 2: Package version tracking

Step-by-step tutorial for tracking the usage of package versions.

In this tutorial, we’ll guide you through setting up a custom CLI hook in Omlet to track the version of your design system package used across your components. This will help you analyze which versions are in use throughout your codebase.

Feel free to customize the script based on your setup—reach us at [e-mail] for any questions/feedback.

1

Install pkg-up

Install pkg-up as a dependency. It will help us locate the nearest package.json file.

npm

npm install pkg-up --save-dev

yarn

yarn add pkg-up --dev

pnpm

pnpm add pkg-up --save-dev

2

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.

hook-script.js

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.

3

Scan your repo

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

npm

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

yarn

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

pnpm

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

4

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.

5

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.