Backend recipes

The same registry that ships UI components also ships server-side recipes: route handlers and helpers that drop into your project as plain TypeScript. They’re configured with @nyxis/core so the engine stays hidden — when we swap the underlying provider SDK, your code keeps working without changes.

Five frameworks are supported out of the box: Next.js App Router (default), Astro, SvelteKit, Hono, and Express. Each recipe targets file-based routing where the framework supports it, and a router-export pattern where it doesn’t (Hono, Express).

The four recipes

Install matrix

Pick the slug that matches your framework. Each entry is a one-line npx shadcn@latest add invocation:

# example: a streaming chat endpoint in your Astro app
npx shadcn@latest add https://nyxisai.vercel.app/r/api-chat-astro.json

Cascading dependencies cover the shared lib helpers automatically — installing api-tools-hono pulls api-chat-hono, which pulls system-prompt.ts. Run the chat install first if you want explicit control over what gets written.

Where each recipe lands

The CLI writes the source files into your project at the canonical path for that framework:

Next.js     app/api/<route>/route.ts        + lib/ai/<helper>.ts
Astro       src/pages/api/<route>.ts        + src/lib/ai/<helper>.ts
SvelteKit   src/routes/api/<route>/+server.ts + src/lib/ai/<helper>.ts
Hono        src/lib/ai/<route>.ts           + src/lib/ai/<helper>.ts
Express     src/lib/ai/<route>.ts           + src/lib/ai/<helper>.ts

For Hono and Express, the recipe exports a router (aiChatRoutes, aiChatRouter, etc.) that you mount on your app:

// Hono
import { Hono } from 'hono';
import { aiChatRoutes } from './lib/ai/chat';

const app = new Hono();
app.route('/api', aiChatRoutes); // POST /api/chat

// Express
import express from 'express';
import { aiChatRouter } from './lib/ai/chat';

const app = express();
app.use('/api', aiChatRouter); // POST /api/chat

Wiring to the client (any framework)

'use client';
import { useChat } from '@nyxis/core';
import { ChatThread } from '@/components/nyxis/chat-thread';
import { ChatMessage } from '@/components/nyxis/chat-message';

export function Chat() {
  const { messages } = useChat({ api: '/api/chat' });
  return (
    <ChatThread messages={messages}>
      {messages.map((m) => (
        <ChatMessage key={m.id} role={m.role}>
          {m.content}
        </ChatMessage>
      ))}
    </ChatThread>
  );
}

Configure providers

Every recipe defaults to Anthropic. Set the env var for the providers you actually use:

ANTHROPIC_API_KEY=sk-ant-…
OPENAI_API_KEY=sk-…
GOOGLE_GENERATIVE_AI_API_KEY=AIza…
MISTRAL_API_KEY=…
# Ollama needs no key but expects `ollama serve` on localhost:11434

Switch the default per recipe by editing defaultProvider and defaultModel, or let the client pass them per request — the handler honours both.

Why hidden engine

The recipes call createChatHandler and createCompletionHandler from @nyxis/core/server, which lazily resolve a provider via createModel. You don’t import ai or @ai-sdk/<provider> directly. When the underlying SDK changes (or we swap engines), your route handler stays the same. When you want full control, copy the body of createChatHandler into your route and edit it to taste — that’s the shadcn-style escape hatch.