Lessons from shipping AtroUI (registry + package internals)
Practical lessons from shipping AtroUI: shadcn registry for consumers, peers, CSS entrypoints, and keeping demo content off the public path.
Consumers add AtroUI through the shadcn registry. Behind that, the docs site and catalog still need a clean package boundary, peers, and assets that do not 404 in the wild.
Here are the lessons worth stealing if you are building a similar catalog.
Lead with the registry for consumers
The happy path is npx shadcn add @atroui/…. Document that first. Package internals matter for the docs host and for maintainers - not as the primary install story. See Installation.
Peers must be real peers
Theme bridges like next-themes belong in peerDependencies (or CLI-installed deps) with install instructions. Soft-assuming the docs app’s dependencies exist in the consumer is how you get “works on my machine” libraries.
One CSS entrypoint for tokens
Whether tokens ship via a stylesheet you copy or a shared theme file, consumers should import once. Do not rely on monorepo-only @source paths that resolve in the docs app and break outside it.
Media used by components must travel with them
If a component references /images/founder-portrait.png and that file only exists in the docs public/ folder, every consumer gets a 404. Bundle assets with registry items or the package, or do not ship the component as public API.
Keep demo content off the default barrel
Portfolio MDX, journal loaders, and studio sample data are fine for docs demos. They are poison on the main export if they pull unknown module types into Turbopack. Split registries from loaders; let consumers opt into content.
Brand defaults need an escape hatch
Defaulting chrome to your brand is correct for your site. Consumers need getBrand()-style overrides and env keys on day one. Otherwise every install ships with your logo text until someone forks.
AtroUI’s approach: Rebrand with getBrand().
Install docs are part of the product
A four-step quickstart with copy-paste CLI commands beats a beautiful catalog that nobody can mount. Keep Installation and the install blog post aligned with the live registry.