How to use a third-party shadcn registry

The shadcn CLI can install components from more than just the official ui.shadcn.com registry. Any project can publish its own registry — a set of JSON endpoints the CLI reads — and you install from it with the same npx shadcn add command you already use. This guide covers how to add a third-party registry, the common pitfalls, and how it works for Sextant specifically.

What a registry actually is

A shadcn registry is just a URL that returns component JSON. Each item lives at a URL like https://example.com/r/{name}.json, where {name} is the component slug. The CLI fetches that JSON, drops the files into your project, and installs any dependencies — the same flow as the official registry.

There are two ways to install from one.

Option A — Install by URL (zero setup)

The fastest path: pass the full registry URL straight to add. Nothing to configure.

npx shadcn add https://sextant.sh/r/chart-anomaly-timeseries.json

This is great for trying a single free component. The downside is you type the full URL every time, and it only works for components that don't require authentication.

Option B — Register a namespace (recommended)

For repeat use, register the registry once under a @namespace in your components.json. Add a registries block:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "registries": {
    "@sextant": "https://sextant.sh/r/{name}.json"
  }
}

The {name} placeholder is required — the CLI substitutes the component slug into it. Now you can install by short name:

npx shadcn add @sextant/chart-anomaly-timeseries

"Unknown registry: @sextant"

This is the single most common error, and it's expected: the @sextant namespace only exists if you declared it in your components.json. The CLI does not auto-resolve arbitrary namespaces. If you see this, you skipped Option B — add the registries block above and re-run the command.

Authenticated (paid) registries

Some registries serve paid components behind a license check. For those, use the object form of the registry entry so the CLI sends an auth header:

{
  "registries": {
    "@sextant": {
      "url": "https://sextant.sh/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${SEXTANT_LICENSE_KEY}"
      }
    }
  }
}

Then set the key in your environment so it never gets committed:

export SEXTANT_LICENSE_KEY="lic_xxx"

The CLI expands ${SEXTANT_LICENSE_KEY} at install time. Free components install without any of this; paid ones return 401 until the key is present.

Verify it works

npx shadcn add @sextant/chart-revenue-area

You should see the component files written into your configured components directory, themed with your existing tokens. If not, re-check the registries block and that your components.json is at the project root.

For the Sextant-specific version of all this — including the live list of free components — see the install guide.