Getting started
Installation
Prerequisites
- Next.js app (App Router preferred)
- Tailwind CSS v4 — not v3
@apply/ opacity syntax - shadcn path only: a
components.jsonfromshadcn init
Add via shadcn (recommended)
@atroui is in the official shadcn registry directory. No manual registry add URL step.
npx shadcn@latest initDark-first tokens that match the catalog: Theming.
npx shadcn@latest add @atroui/home-heroAdd more when you need them — each as its own @atroui/… name.
Without shadcn: AtroUI CLI
Same /r/{name}.json registry, no shadcn toolchain. Use bare item names (not the @atroui/ prefix).
# Add one or more items (resolves registry deps)
npx @atroui/cli@latest add home-hero
# Interactive picker
npx @atroui/cli@latest add
# Browse the catalog
npx @atroui/cli@latest listFiles write under your project (for example components/blocks/home-hero.tsx). You still own the source.
What landed in the repo
The CLI copies source into your project (for example components/blocks/home-hero.tsx). Edit the CONTENT object at the top. Dependencies resolve as @atroui/brand, @atroui/utils, and so on. Full map: Registry.
NEXT_PUBLIC_SITE_NAME=Acme
NEXT_PUBLIC_SITE_DOMAIN=acme.test
NEXT_PUBLIC_SITE_EMAIL=hello@acme.test
NEXT_PUBLIC_SITE_URL=https://acme.testOptional brand env after adding @atroui/brand. Or edit DEFAULT_BRAND in the copied file.
When you need the npm package
Pure UI stops after add. Forms and AI tools that post to /api/* need the package, transpilePackages: ["atroui"], matching route handlers, and your keys:
npm i atroui
# next.config.ts → transpilePackages: ["atroui"]
npx shadcn@latest add @atroui/waitlist-form @atroui/api-waitlistEnv, security defaults, rate limits: Host APIs. Example mail vars:
CONTACT_EMAIL_TO=hello@acme.test
SMTP_USER=…
SMTP_PASSWORD=…
# or
RESEND_API_KEY=…
RESEND_AUDIENCE_ID=…Troubleshooting
- Utilities missing after add — Tailwind cannot see the copied files. Check
@source/ content paths. This is host config, not a Host API failure. 503on form or AI routes — missing keys in your env. Preview-only OG downloads and rule-based scope replies work without keys; full generation does not. See Host APIs.- Wrong Tailwind major — AtroUI targets v4. Do not mix v3 opacity /
@applyhabits into the copied files.
Install modes
Never lead with npm i atroui for pure UI. Add a registry block first; install the package only when /api/* handlers show up.
Owned source files. No npm package.
Pure UI stops at add. Source lands in your repo — no atroui package. Prefer shadcn when you use it; @atroui/cli when you do not.
# shadcn (directory / components.json)
npx shadcn@latest add @atroui/home-hero
# or AtroUI CLI (no shadcn)
npx @atroui/cli@latest add home-heroEnv, security, rate limits: Host APIs.
Why we split them: npm → shadcn registry.
Host-bound tools (optional)
OG, thumbnail, and scope chat ship as thin app/api/*/route.ts files that call atroui/api/*. AtroUI never ships keys.
npx shadcn@latest add @atroui/og-workspace @atroui/api-generate
npx shadcn@latest add @atroui/thumbnail-workspace @atroui/api-thumbnail
npx shadcn@latest add @atroui/scope-chat @atroui/api-scope
# Your keys only (examples):
HUGGINGFACE_API_KEY=…Clone the monorepo
Contributing to AtroUI itself:
git clone https://github.com/atroui/atroui.git
cd atroui
pnpm install
pnpm devFAQ3
So form and AI routes can share validation, honeypot, and rate limits without vendoring native image deps into every copied file.