Why is atroui an npm package at all?

So form and AI routes can share validation, honeypot, and rate limits without vendoring native image deps into every copied file.

Do I need a GitHub token to install @atroui?

No. @atroui is on the public shadcn directory. Private GitHub registries are a different shadcn feature.

Getting started

Installation

AtroUI ships as a shadcn-compatible registry. Run the CLI, components land in your project, and you edit CONTENT at the top of each file. Works best with Next.js, Tailwind CSS v4, and a dark-friendly token sheet. @atroui is the public shadcn directory namespace. You do not need a GitHub token. Private GitHub registries are a different shadcn feature.

What you own after install

The shadcn CLI copies component files into your repo. Edit them freely. AtroUI does not remote-control those files after install.

Tailwind CSS v4 setup (@source, content paths, monorepo scanning) is your app configuration. If utility classes are missing after shadcn add, check that Tailwind can see the copied files - that is not an AtroUI Host API issue.

Pure UI needs only the CLI. Forms and AI tools that post to /api/* also need npm i atroui and your keys. Boundary and env: Host APIs.

1. Init shadcn (if needed)

bash

npx shadcn@latest init

You need a components.json in the app. See the Theming guide for dark-first tokens that match the catalog.

2. Add a component

@atroui is in the official shadcn registry directory. No manual registry add step. The CLI resolves the namespace and can write it into components.json for you.

bash

npx shadcn@latest add @atroui/home-hero
npx shadcn@latest add @atroui/site-header
npx shadcn@latest add @atroui/faq
npx shadcn@latest add @atroui/site-footer

Source files land under your aliases (for example components/blocks/home-hero.tsx). Open the file and edit the constants at the top. Dependencies resolve as @atroui/brand, @atroui/utils, and so on. Full catalog: Registry.

3. Forms + Host APIs

Contact, waitlist, and newsletter UIs post to /api/*. Install the matching route handlers (they call atroui/api/* with honeypot checks, body caps, and in-memory rate limits):

bash

npm i atroui
# next.config.ts → transpilePackages: ["atroui"]

npx shadcn@latest add @atroui/contact-form @atroui/api-contact
npx shadcn@latest add @atroui/waitlist-form @atroui/api-waitlist
npx shadcn@latest add @atroui/newsletter-form @atroui/api-newsletter

Then set mail env (SMTP and/or Resend). Full Host API guide (env, security defaults, rate limits): Host APIs. See also .env.example in the repo.

bash

CONTACT_EMAIL_TO=hello@acme.test
SMTP_USER=…
SMTP_PASSWORD=…
# or
RESEND_API_KEY=…
RESEND_AUDIENCE_ID=…

Brand overrides

After adding @atroui/brand, edit DEFAULT_BRAND or set NEXT_PUBLIC_SITE_* in the host:

bash

NEXT_PUBLIC_SITE_NAME=Acme
NEXT_PUBLIC_SITE_DOMAIN=acme.test
NEXT_PUBLIC_SITE_EMAIL=hello@acme.test
NEXT_PUBLIC_SITE_URL=https://acme.test

Install modes

Never lead with npm i atroui for pure UI. Use a registry CLI first (npx @atroui/cli add or npx shadcn add @atroui/…); add the package only when /api handlers appear.

Owned source files. No npm package.

Install with npx @atroui/cli add … or npx shadcn add @atroui/…. Source lands in your repo. No atroui package required.

Full Host API guide (env, security, rate limits): Host APIs.

Why we split registry UI from the package: npm → shadcn registry migration.

Host-bound tools

Forms and AI tool routes ship as thin app/api/*/route.ts files that call atroui/api/*. AtroUI never ships API keys and does not run paid AI on atroui.com - you set keys in your env.

bash

npm i atroui
# next.config.ts → transpilePackages: ["atroui"]

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=…
# GEMINI_API_KEY=…          # optional freeform / Pro image
# XAI_API_KEY=…             # optional scope LLM + thumbnail Pro pipeline

Preview-only OG/thumbnail downloads and rule-based scope replies work without keys. Full AI generation returns 503 until you configure providers. Marked Host API in the sidebar — details on Host APIs.

Clone the monorepo

Contributing to AtroUI itself:

bash

git clone https://github.com/atroui/atroui.git
cd atroui
pnpm install
pnpm dev

FAQ

Why is atroui an npm package at all?: So form and AI routes can share validation, honeypot, and rate limits without vendoring native image deps into every copied file.
Do I need a GitHub token to install @atroui?: No. @atroui is on the public shadcn directory. Private GitHub registries are a different shadcn feature.

Getting started

Installation

What you own after install

The shadcn CLI copies component files into your repo. Edit them freely. AtroUI does not remote-control those files after install.

Pure UI needs only the CLI. Forms and AI tools that post to /api/* also need npm i atroui and your keys. Boundary and env: Host APIs.

1. Init shadcn (if needed)

bash

npx shadcn@latest init

You need a components.json in the app. See the Theming guide for dark-first tokens that match the catalog.

2. Add a component

@atroui is in the official shadcn registry directory. No manual registry add step. The CLI resolves the namespace and can write it into components.json for you.

bash

npx shadcn@latest add @atroui/home-hero
npx shadcn@latest add @atroui/site-header
npx shadcn@latest add @atroui/faq
npx shadcn@latest add @atroui/site-footer

3. Forms + Host APIs

Contact, waitlist, and newsletter UIs post to /api/*. Install the matching route handlers (they call atroui/api/* with honeypot checks, body caps, and in-memory rate limits):

bash

npm i atroui
# next.config.ts → transpilePackages: ["atroui"]

npx shadcn@latest add @atroui/contact-form @atroui/api-contact
npx shadcn@latest add @atroui/waitlist-form @atroui/api-waitlist
npx shadcn@latest add @atroui/newsletter-form @atroui/api-newsletter

Then set mail env (SMTP and/or Resend). Full Host API guide (env, security defaults, rate limits): Host APIs. See also .env.example in the repo.

bash

CONTACT_EMAIL_TO=hello@acme.test
SMTP_USER=…
SMTP_PASSWORD=…
# or
RESEND_API_KEY=…
RESEND_AUDIENCE_ID=…

Brand overrides

After adding @atroui/brand, edit DEFAULT_BRAND or set NEXT_PUBLIC_SITE_* in the host:

bash

NEXT_PUBLIC_SITE_NAME=Acme
NEXT_PUBLIC_SITE_DOMAIN=acme.test
NEXT_PUBLIC_SITE_EMAIL=hello@acme.test
NEXT_PUBLIC_SITE_URL=https://acme.test

Install modes

Never lead with npm i atroui for pure UI. Use a registry CLI first (npx @atroui/cli add or npx shadcn add @atroui/…); add the package only when /api handlers appear.

Owned source files. No npm package.

Install with npx @atroui/cli add … or npx shadcn add @atroui/…. Source lands in your repo. No atroui package required.

Full Host API guide (env, security, rate limits): Host APIs.

Why we split registry UI from the package: npm → shadcn registry migration.

Host-bound tools

Forms and AI tool routes ship as thin app/api/*/route.ts files that call atroui/api/*. AtroUI never ships API keys and does not run paid AI on atroui.com - you set keys in your env.

bash

npm i atroui
# next.config.ts → transpilePackages: ["atroui"]

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=…
# GEMINI_API_KEY=…          # optional freeform / Pro image
# XAI_API_KEY=…             # optional scope LLM + thumbnail Pro pipeline

Clone the monorepo

Contributing to AtroUI itself:

bash

git clone https://github.com/atroui/atroui.git
cd atroui
pnpm install
pnpm dev

FAQ

Why is atroui an npm package at all?: So form and AI routes can share validation, honeypot, and rate limits without vendoring native image deps into every copied file.
Do I need a GitHub token to install @atroui?: No. @atroui is on the public shadcn directory. Private GitHub registries are a different shadcn feature.