Home React UI Guides shadcn Registries: How They Work, and Which to Use shadcn Registries: How They Work, and Which to Use
A shadcn registry is a set of JSON files that describe components, so the shadcn CLI can install them into your project. You install from a registry either by URL (npx shadcn@latest add https://.../hero.json) or by namespace (npx shadcn@latest add @watermelon/hero-3). Registries listed in the official shadcn directory, Watermelon UI included, need no setup for the namespace to work.
How a registry is structured A registry.json file lists every item. Schema: https://ui.shadcn.com/schema/registry.json. Each item has its own <name>.json file with its source files and dependencies. Schema: https://ui.shadcn.com/schema/registry-item.json. Registry authors generate these with npx shadcn@latest build. Install by URL Any registry item URL works with add. For example: npx shadcn@latest add https://registry.watermelon.sh/r/hero-3.json. This needs no configuration, which makes it the easiest way to try a component.
Install by namespace Registries in the official shadcn directory, including @watermelon, work with no setup: the CLI looks the namespace up and configures it. To pin a registry yourself (or use one that is not listed), add it to the registries field in components.json, using {name} as the placeholder for the item name:
"registries": { "@watermelon": "https://registry.watermelon.sh/r/{name}.json" }
Then install with npx shadcn@latest add @watermelon/hero-3, or search with npx shadcn@latest search @watermelon --query hero. Private registries can add auth headers in the same config, with tokens read from environment variables.
The shadcn registry directory shadcn keeps an official registry directory at ui.shadcn.com/docs/directory. When you use an @namespace that is not in your components.json, the CLI looks it up in that directory and configures it for you. Registries get listed by opening a pull request to the shadcn/ui repository.
Popular registries Compare options in best free shadcn alternatives .
Popular registries Registry Namespace Best for Watermelon UI @watermelonFree blocks, dashboards, and 130+ animated components Magic UI @magicuiAnimated landing page components Aceternity UI @aceternityAnimated visual effects Kibo UI @kibo-uiAdvanced app components Supabase UI @supabaseAuth, storage, and realtime components for Supabase AI Elements @ai-elementsChat and AI interface components
Frequently asked questions What is the Watermelon UI registry URL? Items live at https://registry.watermelon.sh/r/<name>.json, and the full catalog is at https://registry.watermelon.sh/r/registry.json.
Can my AI agent use a registry? Yes. The shadcn MCP server reads the registries in your components.json. See the shadcn MCP server guide .
References
Related Install Watermelon UI with the CLI : Install any Watermelon UI component, block, or dashboard with the shadcn CLI in one command. Setup, install commands, the base variant, and common fixes.shadcn MCP Server for Claude Code and Cursor : Set up the official shadcn MCP server in Claude Code or Cursor, add registries it can search, and when to use a hosted catalog MCP like Watermelon alongside it.Best Free shadcn/ui Alternatives in 2026 : The best free shadcn/ui alternatives in 2026, compared honestly: Watermelon UI, Aceternity UI, Magic UI, daisyUI, HeroUI, Flowbite, and more.A shadcn/ui Alternative with Blocks, Dashboards, and Animations : Looking for a shadcn/ui alternative? Watermelon UI keeps the shadcn copy-paste model and adds free blocks, dashboards, and 130+ animated components.Last reviewed 2026-09-29 .