Developer tutorial: installing Pro Blocks from the registry

You’re a frontend developer using shadcn/ui, and you want to drop a Pro Block — a hero, a footer, a CRM dashboard — into your project. Here’s how to wire the Obra registry into your shadcn setup and install your first block.

This tutorial assumes you already have a working shadcn/ui project (Next.js, Vite, Remix — anything with components.json at the root). If you don’t, run npx shadcn@latest init first, or follow step 1 and step 2 of the CSS Export plugin developer tutorial to scaffold one that matches the kit’s defaults.

Step 1: Add the Obra registry to your `components.json`#

shadcn/ui supports custom registries out of the box. You declare them in your components.json under a top-level registries key, and from then on the CLI knows how to fetch components from them.

Open components.json at the root of your project and add the following registries block:

{
  "registries": {
    "@obra": {
      "url": "https://registry.shadcn.obra.studio/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${OBRA_TOKEN}"
      }
    }
  }
}

A couple of things worth pointing out:

@obra is the namespace. When you later run npx shadcn@latest add @obra/hero-02, the CLI sees the @obra prefix and uses this registry. You can pick any namespace you want, but we recommend @obra for consistency with the rest of our docs.
{name} is a placeholder the CLI fills in with the block name. So @obra/hero-02 resolves to https://registry.shadcn.obra.studio/r/hero-02.json.
${OBRA_TOKEN} is an environment variable reference. The CLI reads it from your .env.local (or your shell) at install time. We use a variable instead of hardcoding the token so you don’t accidentally commit it.

Step 2: Authenticate with your license key#

The Obra registry is private. Every request needs an Authorization header with a valid Pro license token. The CLI handles the header — you just need to provide the token via an environment variable.

Find your token#

When you buy a Pro license, LemonSqueezy emails you a license key. Your registry token is the first two segments of that key, like the highlighted part below:

XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Add it to `.env.local`#

In the root of your project, create (or edit) a .env.local file and add:

OBRA_TOKEN="XXXXXXXX-XXXX"

Replace the value with the first two segments of your own license key.

Make sure .env.local is in your .gitignore. Most framework starters (Next.js, Vite) already ignore it by default — but double-check before you commit.

Step 3: Install your first block#

You’re ready to pull a block. Try one of the heroes:

npx shadcn@latest add @obra/hero-02

The CLI will:

Read components.json and resolve @obra to our registry URL.
Read OBRA_TOKEN from .env.local and send it as a Bearer token.
Download hero-02.json, which contains the JSX source plus a list of dependencies (shadcn/ui components, OC components, npm packages).
Write the block to your @/components directory (or wherever your aliases point), and install any missing shadcn/ui components, OC components, and npm packages along the way.

You’ll see something like this in the output:

✔ Checking registry.
✔ Created 3 files:
  - components/blocks/marketing/hero-02.jsx
  - components/registry/components/oc-marketing-block.jsx
  - components/registry/components/oc-image-placeholder.jsx
✔ Installed 2 dependencies:
  - @/components/ui/button
  - @/components/ui/badge

Drop the block into a page to verify:

import { Hero02 } from "@/components/blocks/marketing/hero-02"

export default function Page() {
  return <Hero02 />
}

Open the page in your browser and you should see the hero render exactly as it does in Figma.

Browsing what’s available#

Block names follow the same pattern across the registry: lowercase, dashes, category-and-number. A few examples:

Command	What it installs
`npx shadcn@latest add @obra/hero-02`	The Hero 02 marketing block
`npx shadcn@latest add @obra/footer-01`	The Footer 01 marketing block
`npx shadcn@latest add @obra/faq-02`	The FAQ 02 marketing block
`npx shadcn@latest add @obra/pricing-01`	The Pricing 01 marketing block
`npx shadcn@latest add @obra/crm-dashboard-01`	The CRM Dashboard 01 application block
`npx shadcn@latest add @obra/table-01`	The Table 01 application block

For the full list of currently-published blocks, see the Pro Blocks page.

How OC components are handled#

A handful of the Pro Blocks use OC (Obra Custom) components — small primitives like OCMarketingBlock (the shared grid wrapper) and OCImagePlaceholder (an AspectRatio-based placeholder). The CLI installs them automatically as dependencies the first time a block needs them, into @/components/registry/components/ by default.

You don’t need to install OC components by hand. If you want to inspect one, just open the file the CLI created and treat it like any other component in your project — modify it, theme it, replace it.

Pairing with the CSS Export plugin#

The Pro Blocks are styled entirely through shadcn/ui tokens — bg-background, text-foreground, border-border, and the rest. They don’t ship hardcoded colors.

That means the Pro Blocks pick up your project’s tokens automatically. If you’ve already run the CSS Export plugin to sync your Figma file’s variables into globals.css, the Pro Blocks will instantly render with your brand colors, type styles, and radii — no extra step needed.

This is the workflow we’ve been building toward:

Designer customizes the kit in Figma.
Developer exports tokens via the CSS Export plugin → globals.css.
Developer installs Pro Blocks via npx shadcn add @obra/....

The blocks consume the tokens. The tokens come from Figma. Everything stays in sync.

Troubleshooting#

401 Unauthorized from the registry

Your token is wrong or missing. Double-check that OBRA_TOKEN is set in .env.local, that it’s the first two segments of your license key (not the full key), and that you’ve restarted your shell or dev server so the new env var is loaded.

Cannot find module ... after installing a block

The CLI installs npm dependencies for you, but if your project is mid-install or your lockfile is out of sync, you may need to run npm install (or your package manager equivalent) once more.

The block uses a shadcn component I don’t have

The CLI should pull missing shadcn components in automatically. If it didn’t, install them manually with npx shadcn@latest add <component>.

The block looks wrong / unstyled

Check that Tailwind is processing the files at the new location. Most starters glob ./components/**/*.{js,ts,jsx,tsx}, so newly-added blocks are picked up automatically. If you’re using a custom content/@source config, make sure it includes the directory the CLI wrote the block into.

Step 1: Add the Obra registry to your components.json#