A component registry that stays in git.
One npm package per component, docs generated from the source, live examples, versions with Changesets, and a static site you can deploy anywhere. Open source under MIT.
Component registry
- Open source, MIT
- Next.js static export
- No database
- No required env vars
The idea
Your repo is the registry
Most component libraries end up with their documentation somewhere else: a hosted platform, a separate docs repo, a wiki that drifts. I built this registry on the opposite bet. Everything the docs need is already in the component's folder, so the folder tree is the registry and the docs are generated from it at build time.
A change to a component changes its docs in the same pull request, reviewed together. There is no database to keep in step, no server to patch, and nothing to export if you stop using it: your components are npm packages in git, which is where they were anyway.
I built it for my own library first. It is now the open-source template behind the Behive Tech registry, and the starting point I use when a client wants a design system with documentation that keeps up.
What you get
Docs that cannot drift from the code
One package per component
A scope owns categories, a category owns components, and each component folder is a complete npm package. Deleting a component is deleting a folder.
Docs from the source
The Overview tab is the component's README, and its code blocks run live. The props table is built from the TypeScript interface and its JSDoc.
Live, editable examples
Each named export of a component's example file becomes an editable example on the Examples tab and the thumbnail in the catalog.
Versions with Changesets
Every component is versioned and published on its own. The Changelog tab is the package's CHANGELOG, written by Changesets.
Status, tags and tokens
Stable, beta, draft or deprecated per component, tags for finding things, and an optional design tokens page generated from a scope's token sheet.
Deploys anywhere
A static export that runs on Vercel, Netlify, Cloudflare Pages, S3 or the included Docker image. No auth, no database, no required environment variables.
How it works
Four moving parts, all in git
The folder tree is the registry
registry/<scope>/<category>/<name> is the npm package @<scope>/<category>.<name>, with its README, examples, source and changelog alongside.
A catalog is generated before every build
A script reads every package and writes the catalog the pages are generated from. Nothing is stored anywhere else, so nothing can drift.
Every package describes itself
Each component's build writes a docs file into the package, so a published tarball carries its own documentation and old versions can be documented from the registry alone.
Publishing is Changesets
Add a changeset, version, release. Publish to npmjs, GitHub Packages or a private registry by changing one value in the config file.
Get started
Running in a few minutes
npx create-bht-component-registry my-registry
cd my-registry
pnpm devThe command asks for your npm scope, the registry you publish to and the starter categories you want, then installs, builds and serves the docs site locally. The guide covers components, scopes, publishing, deploying and updating to newer versions of the template.
See it running
The Behive Tech registry
The Behive Tech registry is this template running with my own scope: components from atoms through forms, molecules and organisms to page templates, each with its docs, live examples, props table and changelog.
This site is one of its consumers. The buttons, cards, stats, hero banner and page template you are looking at are installed from that registry as npm packages and themed with its Material Design 3 token sheet.
The expanded version
A workspace for the team on top
The open registry is complete on its own. The expanded version keeps all of it unchanged and layers a workspace for the people who maintain the registry on top.
The expanded version is set up for your team as a consulting engagement: installation on your infrastructure, SSO wired to your provider, your existing components and metadata carried over, and a session for the people who will maintain it. Engagements are governed by a separate written agreement.
Want a registry like this for your team?
Setting one up, moving an existing library into it, or adding the expanded version on top are all things I do as fixed-scope engagements. A short call is the quickest way to find out which fits.