How the registry works

Most component libraries are a package: you add it to package.json, import from it and get new versions by bumping a number. rapidUI works the other way round. The shadcn CLI copies the source of each component into your app, and from then on the file is part of your code.

What the registry is

The registry is a folder of JSON files on this site, one per component, at https://rdf.dev.360online.com/r/<name>.json. Each file holds the component's source code, the npm packages it needs and the other rapidUI components it builds on. This is the file for Button:

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "button",
  "title": "Button",
  "description": "Button with default, outline, secondary, ghost, destructive and link variants, sm, default and lg sizes plus icon sizes; renders as a link or another element with `render`.",
  "dependencies": [
    "@base-ui/react@^1.8.0",
    "class-variance-authority@^0.7.1"
  ],
  "files": [
    {
      "path": "registry/rapid/ui/button/button.tsx",
      "content": "import { Button as ButtonPrimitive } from '@base-ui/react/button'\n…",
      "type": "registry:ui",
      "target": "components/ui/button.tsx"
    }
  ],
  "type": "registry:ui"
}

There is no server and no login behind it. The files are static and follow shadcn's registry format, so the standard shadcn CLI can read them. The full list is in /r/registry.json.

What happens when you install a component

pnpm dlx shadcn@latest add https://rdf.dev.360online.com/r/button.json

1. The CLI downloads the JSON file for the component.
2. It downloads the components that one builds on, and theirs in turn. Data Table, for example, brings 10 other components with it.
3. It writes the files to components/ui and adjusts the imports to the aliases in your components.json.
4. It installs the npm packages with your package manager, at the version range rapidUI is built and tested with.

The theme is installed the same way. shadcn init https://rdf.dev.360online.com/r/styles/rapid.json writes the colour tokens as CSS variables into your global stylesheet.

After that, nothing in your app points back to rapidUI. There is no rapidUI entry in package.json and nothing is fetched at build time or at runtime.

Why a registry

• You can change the code. When an app needs something a component doesn't do, you edit the file. You don't have to wait for a release, wrap the component or override its styles from outside.
• Each app updates at its own pace. A package moves every component in every app at once. With a registry an app takes one component at a time, when it has time to test it. A large change such as the move to Base UI can be done screen by screen.
• Nothing to publish. There is no package feed, no access token and no version number to agree on. The registry is deployed with this site, and any app that can reach it can install from it, whichever repository the app lives in.
• It is the shadcn model. rapidUI uses shadcn's CLI, file layout and token names. shadcn components, blocks and examples work next to rapidUI unchanged, and developers who know shadcn already know how rapidUI works.
• AI coding agents can read it. The source is in the project, so an agent sees exactly what a component does. llms.txt tells it what exists and how to install it.
• You only get what you use. An app holds the components it has installed and their dependencies, not the whole library.

What it costs

A registry moves some work from the library to the app. These are the trade-offs we accepted:

• Updates are not automatic. A fix reaches an app when someone re-installs the component. The changelog lists every change that reaches apps and says which components to re-install.
• Re-installing overwrites local changes. If you have edited a component, you have to merge your change with the new version yourself.
• Apps can drift apart. Two apps can run different versions of the same component, or different local variations of it.

To keep the cost down, change a component's look with className, variants and theme tokens where you can, and edit the file only when you need different behaviour. If the change would help other apps, open an issue so it can go into the registry.

Getting updates

Read the changelog, then re-install the components it names. The CLI asks before it replaces a file; --overwrite skips the question.

pnpm dlx shadcn@latest add https://rdf.dev.360online.com/r/button.json --overwrite

Review the result with git diff before you commit. The diff shows what changed in the component and whether the update removed a local edit.

How the registry is built

For those who work on rapidUI itself:

1. The source of each component is in registry/rapid/ui/<name>/, next to its stories and documentation.
2. registry.json lists every component with its description, files, npm packages and registry dependencies.
3. bun registry:build turns the two into the JSON files in public/r. It fails if an npm package isn't pinned to the version range in package.json.
4. The files in public/r are committed. A check on every pull request rebuilds them and fails if they are out of date.
5. A merge to main deploys this site, and the registry with it, as static files.

The docs site, Storybook and llms.txt read the same registry.json, stories and documentation, so a component is described in one place. The README has the steps for adding a component.