Install shadcncraft Using the shadcn CLI

Learn how to install our Pro + React shadcn/ui Kit components and blocks into your projects using the shadcn CLI 3.0.

We support the new shadcn namespaced registries and authentication via the shadcn CLI, enabling seamless integration with the Shadcn MCP server.

Getting Started

1. Ensure your project has shadcn/ui installed

Your project must include shadcn/ui and a valid components.json file.

pnpmyarnnpmbun
$ pnpm dlx shadcn@latest init

For framework specific installation, read the official shadcn installation guide.

2. Get your License Key

Copy your Pro + React shadcn/ui Kit License Key.

• If you purchased the Pro + React shadcn/ui Kit, your key was generated automatically after checkout.
• You can also find it in the email sent after purchase or in your Polar Portal.

3. Activate (Single and Team only)

Enterprise licenses do not use activations. Skip this step and go to Configure your Environment.

For Single and Team licenses you must activate once before the registry can verify your instance:

1. Open Activate license, enter your license key, and choose an instance name, such as your work email. Team members each pick a unique instance name.
2. After activation, use the same instance name in SHADCNCRAFT_INSTANCE_NAME and in the X-Instance-Name header in components.json.

The registry authorizes requests with your license key plus, for Single/Team, a matching activated instance name. Sending the key alone is not enough for those tiers until at least one activation exists; after that, key + instance name grant access.

If you are unsure what instance name is on your license, open the Polar Portal and check your activations. Some older orders were activated with a legacy instance name DEFAULT; use that exact value in your environment if that is what the Polar Portal shows.

Optional: use Validate license to confirm your key and instance name are recognized. Validation does not activate; it only checks.

4. Configure your Environment

Create a .env or .env.local file in the root of your project and add your license key.

Single and Team: add both the key and the instance name you used when activating:

SHADCNCRAFT_LICENSE_KEY="your_license_key"
SHADCNCRAFT_INSTANCE_NAME="your-instance@example.com"

Enterprise: set SHADCNCRAFT_LICENSE_KEY only.

For Enterprise-only setups you can omit SHADCNCRAFT_INSTANCE_NAME, the SHADCNCRAFT_LICENSE_KEY alone grants access.

5. Update components.json

Add our namespaced registry configuration to your components.json. The registry serves two URL templates: pick the one that matches your needs.

Option A — Style-aware (recommended)

Use {style}/{name} so the shadcn CLI installs the variant that matches your project's style. To switch presets later, change the style field and re-install — no other edits required.

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "radix-vega",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "lucide",
  "rtl": false,
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "menuColor": "default",
  "menuAccent": "subtle",
  "registries": {
    "@shadcncraft": {
      "url": "https://shadcncraft.com/r/{style}/{name}",
      "headers": {
        "X-License-Key": "${SHADCNCRAFT_LICENSE_KEY}",
        "X-Instance-Name": "${SHADCNCRAFT_INSTANCE_NAME}"
      }
    }
  }
}

Option B — Name-only (legacy)

Use {name} if you only want the legacy new-york-v4 variant and don't plan to switch presets. The CLI ignores the style field for this registry; every install returns the default variant.

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "lucide",
  "rtl": false,
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "menuColor": "default",
  "menuAccent": "subtle",
  "registries": {
    "@shadcncraft": {
      "url": "https://shadcncraft.com/r/{name}",
      "headers": {
        "X-License-Key": "${SHADCNCRAFT_LICENSE_KEY}",
        "X-Instance-Name": "${SHADCNCRAFT_INSTANCE_NAME}"
      }
    }
  }
}

Which one should I use?

• Option A (recommended) — consumer-controlled style variant. components.json#style drives which style preset the CLI installs. Swap presets by editing one field; no more changes are needed. Same setup effort as Option B but future-proof.
• Option B — fixed legacy style variant. Pick this only if you're certain you won't want a different preset or your app is currently locked to the new-york-v4 style variant.

Valid style values

Presets (combine as {base}-{preset}):

• Bases: radix, base
• Presets: vega, nova, maia, lyra, mira, luma, sera
• Examples: radix-vega, base-luma, radix-sera, base-nova

Legacy aliases — default, new-york, new-york-v4. All three collapse to the same legacy variant via the shadcn CLI's FALLBACK_STYLE and Tailwind v4 upgrade path. Existing projects using any of these keep working without changes.

The shadcn CLI accepts any string for style at runtime. If your editor lints a newer preset (e.g. sera) as invalid against ui.shadcn.com/schema.json, it's a cosmetic JSON-schema lag — the install will still succeed.

That's it. You can now use the shadcn CLI to install our Pro + React shadcn/ui Kit components and blocks.

6. Team License: Configure Instance Name

If you purchased the Pro + React shadcn/ui Kit – Team License, each team member must activate and then configure their own unique instance name so activations are tracked correctly.

Every team member must use a different identifier. We recommend using the email address that identifies each team member, but any unique string works as long as each person uses a different one. Use the same identifier consistently. If someone is unsure which instance name is on their license, they can check activations in the Polar Portal.

1. Each team member adds their unique instance name to .env or .env.local:

SHADCNCRAFT_LICENSE_KEY="SHADCNCRAFT_XXXX_XXXX_XXXX"
SHADCNCRAFT_INSTANCE_NAME="your_name@company.com"

2. Update the components.json headers to include the instance name:

"registries": {
  "@shadcncraft": {
    "url": "https://shadcncraft.com/r/{style}/{name}",
    "headers": {
      "X-License-Key": "${SHADCNCRAFT_LICENSE_KEY}",
      "X-Instance-Name": "${SHADCNCRAFT_INSTANCE_NAME}"
    }
  }
}

If you're on the name-only template instead, the URL is https://shadcncraft.com/r/{name} — see Option B above.

Important: Using a team license without a unique instance name per team member can consume an extra seat for an unidentified activation and lead to activation limit errors. See Activation limit reached.

That's it! You can now use the shadcn CLI to install our Pro + React shadcn/ui Kit components and blocks.

Installation

Install a component or block:

pnpmyarnnpmbun
$ pnpm dlx shadcn@latest add @shadcncraft/mobile-navigation-menu

pnpmyarnnpmbun
$ pnpm dlx shadcn@latest add @shadcncraft/header-1

Install multiple items

pnpmyarnnpmbun
$ pnpm dlx shadcn@latest add @shadcncraft/top-navigation-1 @shadcncraft/placeholder-logo @shadcncraft/footer-2

Bonus: shadcn CLI Commands

The shadcn CLI can list, view, or search items in our private registry. No extra configuration is required.

List all items

pnpmyarnnpmbun
$ pnpm dlx shadcn@latest list @shadcncraft

View an item

pnpmyarnnpmbun
$ pnpm dlx shadcn@latest view @shadcncraft/top-navigation-1

Search items

pnpmyarnnpmbun
$ pnpm dlx shadcn@latest search @shadcncraft -q "navigation"

pnpmyarnnpmbun
$ pnpm dlx shadcn@latest search @shadcncraft --query "blog"

Bonus: shadcn MCP Server

Our private registry supports the shadcn MCP Server out of the box. With the MCP Server, you can browse components, search, and install items directly into your project using natural language.

Install the shadcn MCP Server and configure it for your preferred client.

Cursor

pnpmyarnnpmbun
$ pnpm dlx shadcn@latest mcp init --client cursor

Claude Code

pnpmyarnnpmbun
$ pnpm dlx shadcn@latest mcp init --client claude

VS Code

pnpmyarnnpmbun
$ pnpm dlx shadcn@latest mcp init --client vscode

Codex

Codex requires manual configuration. See the official docs.

Support

Still having trouble? See troubleshooting, or reach out to us.