How to Install a React Component From Any shadcn Registry (Step by Step) | saasuji
How to Install a React Component From Any shadcn Registry (Step by Step)
A complete walkthrough of the shadcn registry system โ what a registry is, the exact CLI commands, how dependencies resolve, and how to fix the errors you'll actually hit.
September 18, 20269 min readBy Saasuji Editorial Team
A shadcn registry is not a package you install from npm. It's a JSON file that tells the shadcn CLI which source files to write into your project, which npm packages those files import, and which other registry items they depend on. Once that clicks, installing a component from any registry โ including one you've never heard of โ becomes a one-line command.
This is the step-by-step version: what a registry is, the exact CLI commands, how dependencies resolve, and what to do when something breaks.
What is a shadcn registry?
A registry is a directory of component definitions that follows the shadcn registry schema. Each item is a JSON document with a predictable shape:
name โ the component slug, such as button
type โ usually registry:ui for a component
files โ the source files and where they should live (src/components/ui/button.tsx)
dependencies โ npm packages the source imports (radix-ui, class-variance-authority)
registryDependencies โ other registry items this one imports, referenced by URL
The CLI reads that JSON, installs what's missing, and copies the source into your repo. Nothing is fetched at runtime, so the component keeps working even if the registry goes offline.
Saasuji publishes one JSON file per component โ for example /r/dialog.json โ plus an index at /r/registry.json that lists every item. The human-readable version is the components hub.
Before you start
You need a React project with Tailwind CSS configured. If the project has never used shadcn before, initialize it once:
npx shadcn@latest init
That command creates components.json, sets up the cn helper, and wires the CSS variables shadcn components rely on. Skip it and installs fail with framework-detection or path errors.
The exact CLI commands
Install by name from the default registry:
npx shadcn@latest add button
Install from a URL โ this is how third-party registries like Saasuji work:
The CLI prompts before overwriting existing files. Pass --overwrite to replace files non-interactively and --yes to skip confirmation prompts. Run without flags first so you can review what changes.
Namespaced installs. Recent versions of the shadcn CLI support registry namespaces in components.json:
With that in place you can run npx shadcn@latest add @saasuji/button, which is easier to remember than a full URL.
How dependencies resolve
When you install a component, two dependency graphs resolve automatically.
npm dependencies. If the source imports radix-ui or class-variance-authority, the CLI adds those packages to your project using your package manager. You don't install them by hand.
registryDependencies. If a component imports another registry component, the CLI fetches that item too โ recursively. A concrete example: Form wraps react-hook-form and renders Label internally, so installing Form also fetches Label and the shared utils.json helper that provides cn.
This matters because shadcn components are source files, not compiled packages. Nothing stops those files from importing a sibling that isn't in your repo โ the registry metadata prevents that, and only if you install through the CLI instead of copying single files by hand.
What actually lands in your repo
After a URL install you should see the component source, any sibling components it depends on, and the shared helper files. Nothing is hidden in node_modules, and there is no build step specific to the registry. That's why shadcn-style components survive registry downtime, framework upgrades, and vendor pricing changes โ the code is simply yours now.
Installing from a URL: step by step
Find the component. Start at the components hub and open a detail page โ for example Button or Dialog.
Copy the install command shown on that page.
Run it from your project root. The CLI fetches the JSON, resolves npm and registry dependencies, and writes the source files.
Review the new files and the git diff. Components land as plain source you can edit.
Import and use it:
import { Button } from "@/components/ui/button";
export function Hero() {
return <Button size="lg">Start free trial</Button>;
}
The agent-readable surface
Every component page has a Markdown twin at the same URL with .md appended โ for example /components/button.md. It contains the title, description, install command, props table, full source, and dependencies, with no HTML to scrape. The index at /r/registry.json lists every item in machine-readable form. If you use an AI coding agent, point it at those two URLs and it can install components without hallucinating props or import paths. The twin is useful without an agent too: curl https://www.saasuji.com/components/button.md is the fastest way to read a component's source from a terminal.
Troubleshooting
Symptom
Cause
Fix
command not found: shadcn
CLI not installed globally
Always run through npx: npx shadcn@latest add ...
"We could not detect a supported framework"
Wrong directory or no setup
Run from the project root containing package.json, then run npx shadcn@latest init
Component files already exist
Name collision with your edits
Re-run with --overwrite, or merge only the changes you want
Registry fetch fails / 404
The URL isn't a registry JSON endpoint
Verify the item exists, e.g. https://www.saasuji.com/r/button.json
Imports of @/lib/utils fail
Missing cn helper
Install https://www.saasuji.com/r/utils.json, or re-run through the CLI so registryDependencies resolve
Styles look unstyled
Tailwind not scanning the components path
Check that your Tailwind v4 content sources include src/components
Colors look wrong
Theme CSS variables missing
Re-run init or copy the variable block into globals.css
Install succeeded but the import fails
Path alias mismatch
Confirm tsconfig.json maps @/* to ./src/*, which init sets up
Peer dependency errors
Version conflicts in your app
Fix the versions; use --legacy-peer-deps only as a last resort
The takeaway
A registry is structured source code plus metadata. Once you know that, installing from any registry is the same three steps: find the item, run npx shadcn@latest add <url>, review the diff. Start at the components hub and add your first component in under a minute.
Launch your SaaS on saasuji
Get discovered by founders, earn honest verdicts, and grow your user base โ all for free.
A shadcn registry is a JSON manifest that describes component source files, their npm dependencies, and their registryDependencies. The shadcn CLI reads the manifest and copies the source into your project. It is not a runtime package, so installed components are fully editable and keep working without the registry.
Can I install components from a registry that isn't shadcn/ui?
Yes. Any host can publish a registry that follows the shadcn registry schema, and the CLI installs from a URL or a configured namespace. Saasuji serves free, MIT-licensed items at URLs like https://www.saasuji.com/r/button.json and an index at /r/registry.json.
How do I uninstall a component installed from a registry?
Delete the source file from src/components/ui and remove any npm packages in its dependencies list that nothing else uses. There is no lock-in and no uninstall command needed, because the component lives in your repository as plain source.
