Installation

With the shadcn CLI

If you already have a shadcn project, you do not need the nat-ui CLI. Every component is published in shadcn's registry format as well:

npx shadcn@latest add https://nat-ui-delta.vercel.app/s/button.json

To install by name instead, add the namespace to your components.json once:

{
  "registries": {
    "@nat-ui": "https://nat-ui-delta.vercel.app/s/{name}.json"
  }
}

npx shadcn@latest add @nat-ui/button

Components arrive as source in your project either way. Note that installing one still brings in Base UI (@base-ui/react) — a second primitives library if your project is built on Radix — and assumes your theme defines Tailwind v4's tokens. The nat-ui CLI remains the better option for a new project, where init writing theme tokens and components.json is a service rather than an intrusion.

With the nat-ui CLI

pnpm dlx @nat-ui/cli@latest init

init configures a project in one pass. It asks where your stylesheet and import aliases live, then writes components.json with those answers, creates a cn helper at your utils alias, adds theme variables to your stylesheet, and installs clsx and tailwind-merge with your detected package manager. You also pick a base color, neutral or slate.

That config is what add reads afterwards, so components land where you already keep things, with their imports rewritten to your aliases.

What it needs to find

The one thing init will not guess is your stylesheet. If it cannot find a file that imports tailwindcss, it stops rather than picking one at random — writing theme variables into the wrong file is harder to notice than an error, and harder to undo.

Everything else it detects and offers as a default: the alias prefix from your tsconfig.json paths, TypeScript from the presence of a tsconfig.json, React Server Components from a Next.js project with an app directory, and your package manager from its lockfile.

If your tsconfig.json maps no alias, init says so and carries on, because the components it writes will not resolve until one exists. Next.js projects have one already. Vite projects do not, so set the alias up first.

Running it without prompts

Pass --yes (or -y) to accept every detected default without being asked:

pnpm dlx @nat-ui/cli@latest init --yes

On a project that has no components.json yet, that is the whole run. On one that already has it, see Running it again — --yes declines the overwrite rather than accepting it.

The same defaults apply automatically when stdin is not a TTY, so init will not hang in CI waiting for an answer nobody is there to give.

Running it again

Re-running init is safe. It updates the theme block in your stylesheet in place rather than appending a second copy, and if components.json already exists it asks before overwriting.

Not being asked means no. --yes accepts the defaults, and keeping the config you already have is the default, so init --yes on a configured project prints Found an existing components.json. Nothing was changed. and exits 0 — the same as when stdin is not a TTY. init has no --overwrite; to rewrite the config, answer the prompt or delete components.json first.

Next

Add your first component:

pnpm dlx @nat-ui/cli@latest add button