Next.js quickstart

Keep your secret key on the server. The browser calls your route; your route calls Roadie. Both handlers below are executed in CI; the runnable sources are in documentation/docs/snippets/nextjs/.

New to the SDK? Start with the Node quickstart for the full client, streaming, embeddings, and typed errors — this page focuses on wiring it into App Router routes.

1. Install and configure

pnpm add @roadie/sdk

.env.local

ROADIE_KEY=rd_sk_prod_…

The SDK calls the default hosted gateway (). Set an optional ROADIE_BASE_URL to target a self-hosted or regional host — the routes below already read it.

.env.local is read only on the server. Never expose ROADIE_KEY to the client (no NEXT_PUBLIC_ prefix).

2. A chat route

Create app/api/chat/route.ts. The client is constructed lazily and memoized so it is built once per server instance.

snippets/nextjs/route.ts

import { Roadie } from '@roadie/sdk';

let client: Roadie | undefined;

function roadie(): Roadie {
  if (client === undefined) {
    client = new Roadie({
      apiKey: process.env.ROADIE_KEY!,
      ...(process.env.ROADIE_BASE_URL !== undefined && {
        baseUrl: process.env.ROADIE_BASE_URL,
      }),
    });
  }
  return client;
}

interface ChatBody {
  messages: { role: 'user' | 'assistant' | 'system'; content: string }[];
  userId?: string;
}

export async function POST(request: Request): Promise<Response> {
  const { messages, userId } = (await request.json()) as ChatBody;

  const res = await roadie().chat.create({
    model: 'openai/gpt-4o',
    messages,
    ...(userId !== undefined && { user: { id: userId } }),
  });

  return Response.json({
    reply: res.message.content.map((part) => part.text).join(''),
    usage: res.usage,
    requestId: res.requestId,
  });
}

Call it from the client:

const res = await fetch('/api/chat', {
  method: 'POST',
  body: JSON.stringify({ messages: [{ role: 'user', content: 'Hi' }], userId: 'user_99' }),
});
const { reply } = await res.json();

3. A streaming route

Bridge the SDK’s async-iterable stream onto a ReadableStream the browser can read. Create app/api/chat/stream/route.ts:

snippets/nextjs/stream-route.ts

import { Roadie } from '@roadie/sdk';

let client: Roadie | undefined;

function roadie(): Roadie {
  if (client === undefined) {
    client = new Roadie({
      apiKey: process.env.ROADIE_KEY!,
      ...(process.env.ROADIE_BASE_URL !== undefined && {
        baseUrl: process.env.ROADIE_BASE_URL,
      }),
    });
  }
  return client;
}

interface ChatBody {
  messages: { role: 'user' | 'assistant' | 'system'; content: string }[];
}

export async function POST(request: Request): Promise<Response> {
  const { messages } = (await request.json()) as ChatBody;
  const stream = roadie().chat.stream({ model: 'openai/gpt-4o', messages });

  const encoder = new TextEncoder();
  const body = new ReadableStream<Uint8Array>({
    async start(controller) {
      try {
        for await (const event of stream) {
          if (event.type === 'content_delta') {
            controller.enqueue(encoder.encode(event.delta));
          }
        }
      } catch (error) {
        controller.error(error);
        return;
      }
      controller.close();
    },
  });

  return new Response(body, {
    headers: {
      'content-type': 'text/plain; charset=utf-8',
      'cache-control': 'no-store',
    },
  });
}

Read it on the client:

const res = await fetch('/api/chat/stream', {
  method: 'POST',
  body: JSON.stringify({ messages: [{ role: 'user', content: 'Stream please' }] }),
});
const reader = res.body!.getReader();
const decoder = new TextDecoder();
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

Run these routes on the Node.js runtime (not the Edge runtime) unless you have verified streaming behavior on your deployment target.

Get started

Core concepts

Guides

SDKs

Next.js quickstart

1. Install and configure

2. A chat route

3. A streaming route

Next steps

Node quickstart

Rate limits, quotas & budgets

​1. Install and configure

​2. A chat route

​3. A streaming route

​Next steps

Node quickstart

Rate limits, quotas & budgets

1. Install and configure

2. A chat route

3. A streaming route

Next steps