Launch a React Component Library for Free: npm, Storybook and the shadcn Registry
Launch a React component library by making the live demo your product, because developers judge components by looking at them and pasting them into a project. Decide whether you ship an npm package, a copy-paste registry such as shadcn’s, or both. Publish a Storybook or similar static docs site, test the install in a fresh Next.js and Vite project, and publish to npm with provenance before you announce.
Package, copy-paste registry, or both?
Two distribution models now compete for the same developer. In the first, you publish an npm package and people import it. In the second, you publish source that a command copies into their project, so they own and edit the code. The shadcn/ui documentation describes the second model directly: you can run a code registry to distribute components, hooks, pages, config, rules and other files to any project, described by a registry.json and per-item registry-item.json files.
| npm package | Copy-paste registry | |
|---|---|---|
| Reader’s first step | Install, import, render | Run an add command, then edit the files they received |
| Updates | You release a version; they bump it | They already have the code; you offer a diff or a new item |
| Customisation | Props, theming and escape hatches you design | Anything, because the code is theirs |
| Your support burden | Bugs in every version you shipped | Questions about code they changed |
| Good fit | Behaviour that must stay consistent, such as a data grid | Styling-heavy pieces, such as a landing-page block |
If you are unsure, start with whichever your first three users asked for. The shadcn docs also list community registries in a Registry Directory, built into its command so that a user can add a component from any listed registry, and they say what to do if yours is missing. They warn readers to review third-party code on installation, which is a hint about the trust you will need to earn.
Make the live demo the product
Nobody learns what a component library is like from a README. They learn from a page where every component is on screen, with controls and code beside it. Storybook’s documentation points out that a Storybook is a static web application and can be published to any web host, such as GitHub Pages. That makes a hosted component gallery a free, one-evening job, and it can double as your docs.
- One page per component with the usage code, every state, and a dark-theme view.
- A playground that lets a visitor edit props and see the result, since people trust what they have touched.
- An accessibility line for each component: which keyboard keys work and what a screen reader hears. If you have not tested, say so rather than imply it.
- A real example app, such as a settings page or a dashboard, built only from your components.
Which installs must work before you announce?
Most first issues on a component library are installation problems in a setup you did not test. Create three throwaway projects and install the library into each before every release: a fresh Next.js app that uses server components, a plain Vite and React app, and one on the oldest React version you claim to support. Render one component in each.
- React as a peer dependency, not a bundled copy, so users do not end up with two Reacts.
- Types included, with the package entry points declared for both module formats if you ship both.
- The client boundary marked for components that use state or effects, so server-rendered apps do not break on import.
- One CSS strategy, documented: shipped styles, a Tailwind preset or tokens, but not a mix that needs a guide to understand.
- Small and honest size, measured on the bundle a user would actually produce.
Publish so that a cautious team can verify you
A component library ends up in many apps, so teams read your supply chain. The npm documentation describes provenance attestations: a signed, publicly logged statement that links a package to its source code and build instructions, produced when you publish from supported CI. It also documents trusted publishing, which uploads from a workflow using OpenID Connect instead of a long-lived token. Do both, and add a line to the README saying so. It costs an afternoon and answers a question some readers will otherwise ask.
Put a changelog beside the version numbers, and follow semantic versioning strictly: a change in a prop’s meaning is a major release even if the code diff is tiny. The changelog template is a place to start.
Three weeks from first component to announcement
- Week 1: ship twelve components that cover one complete screen, not forty that cover nothing. Document each in the gallery as you build it.
- Week 2: run the install matrix, add the example app, publish a release candidate with provenance, and give it to three developers who build interfaces for a living.
- Week 3: fix what they report, publish the first stable version, announce with a link to the gallery rather than the repository.
Twelve components is a suggestion, not a rule. The test is whether someone can build one believable page with the library alone. If they have to reach for something else on screen two, the scope is still too wide.
Where do interface developers pick up a new library?
From a clip of something they would like to build, posted where they already watch such clips, and from a Show HN post when the gallery lets them try it with no sign-up. Frame the post around a problem, such as a table with keyboard navigation that stays small, and let the gallery speak for the rest. See the Show HN playbook for the format.
You can launch the library free on this board too: one verified email, no queue, and a followed link to the gallery. Look through the design tool ideas for gaps other builders mention, and read how a design-file product differs in the UI kit playbook. The places that suit component libraries go further.
Frequently asked questions
Should I publish an npm package or a shadcn-style registry?
Publish an npm package when behaviour must stay consistent across versions, such as a complex data grid. Publish a registry when users want to own and edit the code. You can do both. The shadcn documentation describes running your own registry with registry.json and registry-item.json files.
How do I host a Storybook for free?
Storybook builds to a static web application, and its documentation says you can publish that to any web host, including GitHub Pages. Add a workflow that builds on every release and deploys the output, then link the hosted gallery from your README and your launch posts.
What does npm provenance do?
According to the npm documentation, provenance attestations link a published package to its source code and build instructions. They are signed through Sigstore and logged in a public transparency ledger, so users can verify where the package was built. You generate them when publishing from supported CI.
Where do I announce a React component library?
Post a short clip in communities where interface developers share work, try a Show HN with a gallery people can use without signing up, and add a free public launch page. Link the live gallery, not only the repository, and tag every link to see which one sends visitors.
Written by Post your build ideas with AI assistance and edited for this site. Where a page names another product, the facts came from that product’s own pages on the date shown above; terms change, so check them before you rely on them. About the publisher.