The features for measuring adoption of your design system in code are experimental features, currently in beta. Access to these features will remain free and unrestricted during the beta period.

Component usage allows you to analyze your codebase using a command line tool and send usage information to zeroheight. This data can help give an overview of how your design system packages are being used across your codebase and which components are more frequently used.

How to get set up

Requirements

To get the best experience, you'll need to ensure you have the following:

• Familiarity with the terminal
• Node >= 20
• A React codebase

Using the CLI

Getting access

You can access @zeroheight/adoption-cli on the NPM registry.

Authenticate zh-adoption with zeroheight

You will need to authenticate to import the results into your zeroheight account. These can be created in your organization settings if you did not create them during the Adoption setup flow. You must grant the access level of "zeroheight CLI - read and write".

1. Authenticate the CLI with zeroheight

   npx @zeroheight/adoption-cli auth

2. You will be asked for a Client ID and an Access Token.

You're now ready to send component usage to zeroheight.

How to track component usage

1. Run npx @zeroheight/adoption-cli analyze in the repository you wish to get insight into.
2. When you are asked if you want to scan files to learn about component usage, you should press Y and then Enter
3. Once analysis is complete, you'll be asked if you want to see more details, this is optional
4. Once analysis is complete, you can then press Y then Enter to send the color usage data to zeroheight
5. The first time you run the command, you will be asked to name the repository you are in, so that you can identify it in zeroheight
6. You will then be presented with the color usage analyze flow, this is optional to complete

Viewing in zeroheight

Head over to the Adoption tab in your account and you should see a chart showing your four most used components

You can click on the panel to move to the Component usage dashboard and see a list of all of the components being used in your projects. If you have imported data from multiple repositories, you are able to filter them down in the sidebar

You can dig into the usage of each component by clicking on its name. This will show you a graph of how many times the component is used within each repo over a range of the past 7, 30 or 90 days.

You are also able to see the prop usage for your components as well. This shows you what props are being passed into your components, as well as the values that are being used.

Note: some values are considered "dynamic", this is because the value of them is determined at runtime. Because we are taking a snapshot of the codebase, we are not able to determine what they might be.

FAQ

Which web frameworks are supported for component usage metrics?

To begin with, we are offering component usage metrics for React only. Based on feedback, we hope to add support for more frameworks in the future.

What data is sent to zeroheight?

Currently, the zh-adoption CLI only sends usage information about the names of React components, how frequently they are used in a codebase and the properties being passed to them. We do not send the entire codebase to zeroheight.

Does my component library need to be on NPM?

No, it doesn't. We support public NPM packages, linked code repos within zeroheight and also using the CLI to track your packages.

How do I install and run the CLI in a project?

If you prefer to install the CLI into a specific project instead of using npx, you can do the following:

1. In your terminal, run: npm i @zeroheight/adoption-cli
2. Authenticate with zh-adoption auth (this only has to be done once)
3. Analyze a project by running zh-adoption analyze within the project directory you wish to analyze component usage.

Where can I view the documentation for the CLI?

You can view the documentation in the README on NPM at @zeroheight/adoption-cli