How do I get started with Assistant-UI in an existing Next.js project (App Router) — install steps?
AI Chat UI Toolkits

How do I get started with Assistant-UI in an existing Next.js project (App Router) — install steps?

7 min read

If you already have a Next.js App Router project and you want a ChatGPT‑style interface without spending days on UI work, Assistant‑UI is designed exactly for that. This guide walks you through the installation steps, wiring it up to an API route, and rendering a production‑ready chat in your existing app.

1. Prerequisites and project check

Before installing Assistant‑UI, confirm:

  • You’re using Next.js 13+ with the App Router (app/ directory).
  • You have React 18+.
  • You’re comfortable with server routes in app/api and React client components.

If your project is already running, you’re good to go.

2. Install Assistant‑UI in your Next.js project

Assistant‑UI is an open‑source TypeScript/React toolkit, so installation is just an npm command.

From your project root, run:

npx assistant-ui init

Or, if you want to add it manually:

npm install assistant-ui
# or
yarn add assistant-ui
# or
pnpm add assistant-ui

This pulls in the React components and hooks you’ll use to build the chat UI.

3. Decide how you’ll talk to your LLM

Assistant‑UI works with:

  • Any LLM provider (OpenAI, Anthropic, Groq, etc.)
  • Any orchestration layer like LangChain, LangGraph, or Vercel AI SDK

At a high level, you need:

  1. A route handler under app/api/... that:

    • Receives messages from the UI
    • Calls your chosen LLM or agent logic
    • Streams or sends responses back

  2. A chat client in your React components that:

    • Sends user messages to that API route
    • Renders streaming responses in the UI

You can swap out the backend implementation later; the UI wiring stays mostly the same.

4. Create a chat API route (App Router)

Let’s create a simple chat route in app/api/chat/route.ts. This example assumes you’re using a generic POST endpoint and returning JSON; adjust for streaming/Vercel AI SDK as needed.

// app/api/chat/route.ts
import { NextRequest, NextResponse } from 'next/server';
// import your LLM SDK or agent logic here
// e.g. import OpenAI from "openai";

export async function POST(req: NextRequest) {
  const body = await req.json();
  const { messages } = body as {
    messages: { role: 'user' | 'assistant' | 'system'; content: string }[];
  };

  // Call your LLM or agent here with `messages`
  // Example placeholder response:
  const lastUserMessage = messages[messages.length - 1]?.content ?? '';
  const reply = `You said: ${lastUserMessage}`;

  return NextResponse.json({
    message: {
      role: 'assistant',
      content: reply,
    },
  });
}

Later, you can replace the placeholder logic with:

  • A call to OpenAI / Claude / Grok / Gemini / Perplexity
  • A LangChain chain
  • A LangGraph agent
  • A Vercel AI SDK handler with streaming

Assistant‑UI doesn’t force a backend; it just expects an endpoint like this to exist.

5. Add Assistant‑UI provider and chat component

Next, wire the chat UI into your Next.js App Router pages.

5.1. Mark your chat page as a client component

In app/chat/page.tsx (or wherever you want the chat):

// app/chat/page.tsx
'use client';

import React from 'react';
import { AssistantUIProvider } from 'assistant-ui';
import { Chat } from 'assistant-ui'; // or whatever core chat component the package exposes

export default function ChatPage() {
  return (
    <AssistantUIProvider>
      <div className="h-screen flex items-center justify-center bg-gray-50">
        <div className="w-full max-w-2xl h-[600px] border rounded-xl bg-white shadow-sm">
          <Chat />
        </div>
      </div>
    </AssistantUIProvider>
  );
}

Key points:

  • The file uses 'use client'; because Assistant‑UI is a React client‑side library.
  • AssistantUIProvider wraps the chat to manage state (messages, streaming, retries, etc.).
  • Chat is the ChatGPT‑style UI that talks to your backend.

(If the specific component names differ in your version of Assistant‑UI, follow the package docs—but the pattern is the same: provider + chat component.)

6. Connect the chat component to your API

Now configure Assistant‑UI to call your /api/chat route. Many Assistant‑UI setups provide a way to specify a transport or chat client that defines how messages are sent and received.

A common pattern is something like:

import React from 'react';
import {
  AssistantUIProvider,
  useAssistantChat,
  Chat,
} from 'assistant-ui';

function ChatWithBackend() {
  const chat = useAssistantChat({
    // Adjust to the actual config supported by your version
    api: '/api/chat',
    fetchImpl: async (messages) => {
      const res = await fetch('/api/chat', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ messages }),
      });
      const data = await res.json();
      return data.message;
    },
  });

  return <Chat chat={chat} />;
}

export default function ChatPage() {
  return (
    <AssistantUIProvider>
      <ChatWithBackend />
    </AssistantUIProvider>
  );
}

Explanation:

  • useAssistantChat encapsulates state management: message history, streaming, retries, etc.
  • The handler passes messages to /api/chat.
  • The Chat component consumes that chat object and renders the full UI.

If your Assistant‑UI version includes preconfigured integrations (e.g., for Vercel AI SDK, LangChain, or LangGraph), you can swap fetchImpl for those built‑ins to save more boilerplate.

7. Configure layout and styling in App Router

To make the chat feel native in your app:

  1. Use your root layout in app/layout.tsx to define global fonts, colors, and containers.
  2. Let Assistant‑UI components inherit styling (or wrap them with your design system).
  3. Ensure the chat container has a defined height to showcase streaming well.

Example layout integration:

// app/layout.tsx
import './globals.css';
import type { ReactNode } from 'react';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body className="bg-slate-100 text-slate-900">
        <main className="min-h-screen">
          {children}
        </main>
      </body>
    </html>
  );
}

Your /chat page will now sit inside this layout while Assistant‑UI handles all chat‑specific UI logic.

8. Wire in your actual agent logic

Once the UI is working end‑to‑end with a dummy reply, connect the tools and frameworks you’re using.

8.1. Using LangChain or LangGraph

Assistant‑UI is built to work well with LangChain and LangGraph:

// app/api/chat/route.ts
import { NextRequest, NextResponse } from 'next/server';
// import your LangChain or LangGraph logic
import { runAgent } from '@/lib/agent'; // your custom agent

export async function POST(req: NextRequest) {
  const { messages } = await req.json();

  const agentReply = await runAgent(messages); // let LangGraph / LangChain handle tools, memory, etc.

  return NextResponse.json({
    message: {
      role: 'assistant',
      content: agentReply,
    },
  });
}

With this setup, Assistant‑UI focuses purely on UX (streaming, interruptions, retries), while LangGraph/LangChain handle your stateful reasoning and tools.

8.2. Using Vercel AI SDK or provider SDKs directly

If you use Vercel AI SDK, you might stream responses. Assistant‑UI is optimized for streaming, so integrate a streaming transport from your version’s docs instead of a simple JSON return.

9. Enable production‑ready behavior

Assistant‑UI is designed for production out of the box, but in a real Next.js app you should:

  1. Secure your API route

    • Add authentication checks in app/api/chat/route.ts.
    • Rate limit if needed.

  2. Configure environment variables

    • Store provider keys (e.g., OPENAI_API_KEY) in .env.local.
    • Use process.env only in server code.

  3. Optimize bundle size

    • Keep heavy logic in server files.
    • Ensure you only import server‑side SDKs inside route handlers, not client components.

  4. Test streaming and error paths

    • Check how the UI behaves when the LLM fails or times out.
    • Confirm retry behavior and loading states.

10. Quick checklist: “Did I set up Assistant‑UI correctly?”

Use this list to validate your install steps in an existing Next.js App Router project:

  • Assistant‑UI installed via npx assistant-ui init or npm install assistant-ui.
  • A client page under app/chat/page.tsx (or similar) with 'use client';.
  • AssistantUIProvider wraps your chat components.
  • Chat (or equivalent Assistant‑UI chat component) is rendered.
  • A working API route at app/api/chat/route.ts.
  • Messages flow: user message → /api/chat → LLM/agent → response visible in UI.
  • Optional: integrated with LangChain, LangGraph, or Vercel AI SDK.
  • Basic styling and layout matches your app design.

Once all of the above are in place, you have a ChatGPT‑like experience running directly inside your existing Next.js App Router project, powered by Assistant‑UI and ready to evolve with more advanced agent logic over time.

If you share how you’re calling your LLM today (OpenAI, LangChain, LangGraph, Vercel AI SDK, etc.), I can outline the exact route.ts and useAssistantChat code tailored to your stack.

Back to AI Chat UI Toolkits

Keep Reading

More from AI Chat UI Toolkits

How do I implement a real “Stop generating” button that actually cancels a streaming response?

Read more

Assistant-UI Enterprise: who do I contact for SLA/on-prem, and what security info do they provide?

Read more

Assistant-UI React Native (Expo): how do I reuse the same tools/runtime from my web app?

Read more