# Tutorial 2: Package version tracking

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.

{% hint style="info" %}
Feel free to customize the script based on your setup—reach us at <support@omlet.dev> for any questions/feedback.
{% endhint %}

{% stepper %}
{% step %}

## Install pkg-up

Install [pkg-up](https://www.npmjs.com/package/pkg-up) as a dependency. It will help us locate the nearest `package.json` file.

{% tabs %}
{% tab title="npm" %}

```bash
npm install pkg-up --save-dev
```

{% endtab %}

{% tab title="yarn" %}

```bash
yarn add pkg-up --dev
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm add pkg-up --save-dev
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### 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.

{% code title="hook-script.js" %}

```javascript
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);
  },
};
```

{% endcode %}

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.&#x20;

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

{% step %}

### Scan your repo

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

{% tabs %}
{% tab title="npm" %}

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}

{% tab title="pnpm" %}

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

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Filter components by DS Version

Once the CLI scan complete, the `DS Version` property will be associated with each component.&#x20;

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.

<figure><img src="https://4214978157-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIRXB2SJ9FZ5x4QW8ihpe%2Fuploads%2FFDwg3xuxO3qj1Mark9PW%2FFrame%202%20(1).png?alt=media&#x26;token=1c7a1907-86e9-49d1-8a82-9ed1231f1764" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://4214978157-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIRXB2SJ9FZ5x4QW8ihpe%2Fuploads%2FvY8TFyxxUTqIKbScM4EC%2FFrame%203.png?alt=media&#x26;token=ec5d1d1f-6ec9-4d4f-b99c-1e45d440fe30" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### 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.

<figure><img src="https://4214978157-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIRXB2SJ9FZ5x4QW8ihpe%2Fuploads%2FZpn0fI4JFu2cCnkCsKwH%2FFrame%204.png?alt=media&#x26;token=755cbed9-74b0-40e2-8a6c-a47eb9a41010" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="https://4214978157-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIRXB2SJ9FZ5x4QW8ihpe%2Fuploads%2FUYuwFKuWfQIQfnOlHFcq%2FFrame%205.png?alt=media&#x26;token=2a7fb76d-a6b4-43a8-8903-ded0c1c30358" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}