AtroUI Host APIs: own the UI, bring your keys

Last week we shipped AtroUI: a free React and Next.js catalog on the shadcn registry. Own the source. Edit CONTENT. Keep the dark-first system. That launch answered the ownership half of the problem we see on client sprints.

The other half is less glamorous. You still need /api/contact, waitlist, newsletter, OG, thumbnail, and scope routes. Validation. Honeypots. Body caps. Rate limits. Mail and AI providers. Most kits shrug and leave that glue to you, or burn shared studio keys on a demo host.

We refuse both.

This week we productized Host APIs: UI you own, thin routes on your Next.js app, hardened handlers in the published atroui package, and secrets that stay in your env. The line is deliberate:

Own the UI in your repo. Borrow the boring API security. Bring your own keys.

What a Host API is

Host means your Next.js deployment. API means the backend handler that runs there. Together: Host API.

Three layers fit together:

Browser  →  your /api/contact  →  atroui/api/contact (library)
                                      ↓
                            your SMTP / Resend / HF / xAI

UI comes from the registry (@atroui/contact-form, @atroui/og-workspace, and siblings). The CLI copies source into your repo.

Route stubs like @atroui/api-contact drop a thin App Router file that forwards POST to the package.

Handlers live under atroui/api/contact|waitlist|newsletter|generate|thumbnail|scope. Shared validation, honeypot, body caps, rate limits, and provider wiring. You upgrade the package with npm instead of re-vendoring native image deps into every app.

import { handleContactPost } from "atroui/api/contact"

export const runtime = "nodejs"

export async function POST(req: Request) {
  return handleContactPost(req)
}

Host APIs are not a SaaS API on atroui.com that you call with an AtroUI key. Pure marketing sections still install registry-only. Host APIs are the optional backend chapter for Next.js App Router hosts.

The long guide lives on AtroUI: Host APIs. The essay-length walkthrough is also on the AtroUI blog.

Three install modes, one rule

Never lead with npm i atroui for pure UI. The matrix is identical across Host APIs docs, Installation, and the READMEs:

# 1) Registry UI only (no npm package)
npx shadcn@latest add @atroui/home-hero

# 2) Forms: package + thin route stubs
npm i atroui
# next.config.ts → transpilePackages: ["atroui"]
npx shadcn@latest add @atroui/contact-form @atroui/api-contact

# 3) AI tools: same package setup
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

transpilePackages: ["atroui"] matters when you import handlers from the package. It does not matter when you only copy heroes. That boundary is the product story, not packaging trivia.

BYOK is a product rule

Bring your own keys means AtroUI never stores Resend, SMTP, Hugging Face, Gemini, or xAI credentials. atroui.com demos fail closed: preview-only, rule-based scope, or 503 when paid paths need env that is not set.

Supported AI engines today are Hugging Face, Gemini, and xAI where each tool needs them. Dropping OPENAI_API_KEY or ANTHROPIC_API_KEY does not auto-wire those vendors. We ship a known BYOK set and expand providers on purpose. Until then you can fork the thin route and keep the UI.

Forms need mail config (CONTACT_EMAIL_TO plus SMTP or Resend). Without it, handlers return 503: host not configured, not a client payload bug. Bots that fill the honeypot field get a fake 200 and no send.

Boring security defaults

Handlers already apply the controls teams forget when they paste a route from a gist:

Honeypot field honeypot. Body cap 8 MB JSON. Contact attachment cap 5 MB decoded.

Per-IP sliding windows (15 minutes): contact 5 · waitlist/newsletter 10 · scope 30 · generate/thumbnail preview 30 · AI 5.

429 means rate limit exceeded (retryAfterSec). 503 means missing mail or AI config.

You still own auth, CDN or WAF abuse controls, email deliverability, provider spend, and shared rate-limit storage across instances. Host APIs cover the copy-paste mistakes. Production ownership stays with the host.

Memory limits vs multi-instance hosts

Default checkRateLimit is an in-memory sliding window per Node process. Fine locally and on a single instance. On multi-region Vercel, each process has its own map, so effective limits multiply.

Set Upstash Redis REST or Vercel KV env vars on the host. The same API switches to a shared backend. You do not fork handlers. Redis is optional. If Redis is unreachable, handlers fall back to memory so forms stay up.

# Upstash Redis REST (recommended)
UPSTASH_REDIS_REST_URL=https://….upstash.io
UPSTASH_REDIS_REST_TOKEN=…

# or Vercel KV (same REST protocol)
KV_REST_API_URL=…
KV_REST_API_TOKEN=…

Why handlers stay on npm

UI moved to the registry so you own files day one. Handlers stayed in atroui on purpose.

Contact and waitlist are mostly TypeScript. OG and thumbnail pull in Satori, resvg, sharp, fonts, and compose logic. Vendoring that into every consumer via the CLI would ship native .node addons and font paths into app trees in painful ways. A versioned package keeps one upgrade path for security and compose fixes while UI remains editable source in your repo.

That split is the same pattern behind studio tools on makershot.tech, including the free OG image generator: UI and compose can be shared; secrets never leave the host that pays the bill.

What else moved this week

Dedicated Host APIs docs under Getting started, linked from Installation, Registry, Compare, and Host API component pages.

Vitest coverage across newsletter, waitlist, thumbnail, scope, shared helpers, and rate-limit backends (memory plus mocked Redis).

Optional Upstash / Vercel KV behind the same checkRateLimit contract.

Install-mode matrix shared across docs and READMEs so CLI-first UI stays the default path.

Marketing and landing copy locked to the Host API line. Sketch display type (Caveat) for brand stamps and display, Outfit for body.

What this is not

It is not AtroUI billing for your AI or mail usage.

It is not a universal backend for every framework. Host APIs target Next.js App Router today. Other stacks can still own registry UI.

It is not magic support for every LLM vendor on day one. Known providers only, with honest 503s and forkable routes.

It is not a replacement for product thinking. You still own copy, routing, deliverability, and spend.

Try the path

If you only need a section, stay registry-only:

npx shadcn add @atroui/home-hero

If you need a form that actually posts:

npm i atroui
# transpilePackages: ["atroui"]
npx shadcn add @atroui/contact-form @atroui/api-contact

Then set mail env on the host and deploy. Full steps: Installation and Host APIs.

The launch essay is still here: Introducing AtroUI.

Want the whole product built

AtroUI is the open catalog. Makershot is the studio when you want the full Next.js product, not only the UI layer: MVP sprints, AI integrations, and design system work on a fixed scope.

Own the files. Borrow the boring security. Keep the keys. That is the Host API bet, and it is live on atroui.com.