Track which projects are using the latest version of your design system packages
How to get set up
Head over to the "Adoption" section, found in the top navigation bar
Hit "Get started" and then you will be asked where you like to track the package from.
We recommend using the zeroheight CLI tool to set up the adoption features as they can be used within your CI/CD pipelines to make sure the data you have in zeroheight is the most up to date. It also means you aren't required to link any external git accounts and only have to send the data you want to zeroheight.
Via the CLI
Requirements
To get the best experience, you'll need to ensure you have the following:
- Familiarity with the terminal
- Node >= 20 (some lower versions may work but are not guaranteed)
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 package version data into your zeroheight account.
- Authenticate the CLI with zeroheight —
npx @zeroheight/adoption-cli auth - You will be asked for a Client ID and an Access Token.
You're now ready to send package version data to zeroheight.
Note: If you need new credentials, they can be created in your organization settings. You must grant the access level of "CLI read/write".
How to track your design system package version
- Run
npx @zeroheight/adoption-cli track-package - If multiple packages are found, you will be asked to choose which ones you wish to import
- Once chosen, you'll be be asked if you want to send the data to zeroheight. Enter "Y" to send it to your account.
How to monitor which version of your package is being used
- Run
npx @zeroheight/adoption-cli monitor-repo - The data will be sent straight to zeroheight
You also have the option to analyze component usage at this stage as well. More infomation on that feature can be found here.
Finally, go to the Adoption page in your browser and you should be able to see your monitor repos listed against each of your design system packages
Using code repositories or Public NPM
You can select multiple packages from the public NPM registry
You can also select multiple packages from your code repositories
If you have chosen to track a package from a code repository will we attempt to find the package file to take the name and version from. If you have multiple to choose from, you will have the option to pick which one you want to use.
You will then reach a screen that asks what you want to set up, click on "Track package adoption"
Next, select the repositories you want to track the usage in. Once again we will automatically try to find the correct lock files to look in.
You will then be able to see how up-to-date your projects are with your latest package version.
How do I get the latest results?
Hit the update button at the top of the page and we will fetch the latest versions all of your packages and monitored repositories and refresh the data shown in the tables.
If you imported your package data via the zeroheight CLI tool you will need to update the data from there as the update button will not be able to refresh said data.
FAQs
Which repository services do you support?
We integrate with the following:
- GitHub (cloud and self-hosted)
- GitLab (cloud and self-hosted)
- Bitbucket (cloud only)
- Azure DevOps (cloud only)
I have a mono repo; how does that work?
You will be given the option to choose which of the package/lock files you want to monitor as part of the flow. Each of these will then be treated as separate entities in terms of monitoring.
My packages are hosted privately; can I track their usage?
Yes. You will need to use our code repo integrations to monitor the versions of private packages.
Do I need to have my repos connect to zeroheight?
Yes. In order to know what version of the package your repos are using, we will require them to be linked to your zeroheight account.