Registry

How the registry works

Refinery ships components as shadcn CLI-compatible registry JSON files. Each installable component has a public URL:

https://refinery.abhii.me/r/[component-name].json

For example:

https://refinery.abhii.me/r/terminal-text.json

Because Refinery is not currently listed as a built-in shadcn registry namespace, the @refinery alias will not work in a fresh project until you configure the registry yourself. You have two good options:

• - Use the full URL every time.
• - Add a custom @refinery registry entry to components.json, then install by name.

Install with the full URL

This is the most direct workflow and works without editing components.json:

For another component, replace the last part of the URL (for example, waveform-bars).

The CLI reads the registry item, installs declared package dependencies, writes files into your configured component folders, and may ask before overwriting an existing file.

This is the easiest way to get started with Refinery. It is also the most explicit way to install a component because the URL shows exactly where the registry item is coming from. However, it can get tedious if you are installing multiple components. For a smoother workflow, you can add the @refinery registry alias with the steps below.

Add the Refinery registry alias

If you plan to install more than one component, add a registry alias. The shadcn CLI supports custom registries through the registries field in components.json.

You can add it with the CLI:

Or add it manually to components.json:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "@refinery": "https://refinery.abhii.me/r/{name}.json"
  }
}

Only add the registries block to your existing file. DO NOT replace your whole components.json with the example above unless the rest of the paths match your app.

The {name} placeholder is required. When you run shadcn add @refinery/terminal-text, the CLI replaces {name} with terminal-text and fetches https://refinery.abhii.me/r/terminal-text.json. Only add registries you trust, since the CLI will copy files and install dependencies declared by the registry item.

Install with the alias

After the alias is configured, install components like this:

You can install another component by changing the name (for example, @refinery/testimonial-carousel).

Available component names

Current Refinery registry items include:

• - terminal-text
• - waveform-bars
• - voice-aura
• - floating-card
• - move-to-top-button
• - testimonial-grid
• - testimonial-carousel
• - testimonial-canvas
• - dvd-screensaver
• - sleeping-cat-screensaver
• - analog-clock-screensaver
• - glowy-button
• - notification-badge
• - floating-nav
• - avatar-circle

Utility items such as utils may be pulled automatically when a component declares them as registry dependencies.

What the CLI changes

When you run "shadcn add", the CLI can:

• - Fetch the component registry JSON from Refinery.
• - Install npm dependencies listed by the component, such as motion or clsx.
• - Copy component files into your configured component path.
• - Copy utility files into your configured utility path when needed.
• - Ask before overwriting files that already exist.

The exact destination comes from components.json. If your aliases point to @/components and @/lib/utils, Refinery components will be written into those parts of your app.

Recommended workflow

Start from a current stack using the Installation guide, then add the registry alias and install components by name. Use the full URL workflow only when you want the most explicit command or you have not added the alias yet.

Troubleshooting

If the CLI says Unknown registry, the @refinery alias is missing or misspelled in components.json. Add this entry:

{
  "registries": {
    "@refinery": "https://refinery.abhii.me/r/{name}.json"
  }
}

If the CLI cannot find components.json, run the shadcn init command from your project root first:

If imports fail after installation, check the aliases in components.json and your tsconfig.json or jsconfig.json. They should agree on paths such as @/components and @/lib/utils.

If animation components fail to compile, make sure Motion is installed and imported from motion/react:

In your component file:

import { motion } from "motion/react";

That is it for the registry. From here, start browsing the components and install the pieces you want to own in your app.