Next.js SDK

The @yak-io/nextjs package provides the best experience for Next.js applications with automatic route scanning, a CLI for production builds, and App Router integration.

Prerequisites

Next.js 14+ (App Router)
React 18+
Node.js 18+
A Yak app ID (from your dashboard)

Installation

npm install @yak-io/nextjs

pnpm add @yak-io/nextjs

yarn add @yak-io/nextjs

bun add @yak-io/nextjs

Quick Start

Configure environment

Add your app ID to .env.local:

NEXT_PUBLIC_YAK_APP_ID=yak_app_123

Add the API handler

Create a catch-all route that serves configuration and handles tool calls:

// app/api/yak/[[...yak]]/route.ts
import { createNextYakHandler } from "@yak-io/nextjs/server";

export const { GET, POST } = createNextYakHandler();

Wrap your layout

Add YakProvider and YakWidget to your root layout:

// app/layout.tsx
import { YakProvider, YakWidget } from "@yak-io/nextjs/client";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <YakProvider appId={process.env.NEXT_PUBLIC_YAK_APP_ID!}>
          {children}
          <YakWidget />
        </YakProvider>
      </body>
    </html>
  );
}

That's it — the widget appears in your app and can navigate users between pages.

Adding Tools

Pass tool adapters to expose your APIs to the AI assistant. Here's an example with tRPC:

// app/api/yak/[[...yak]]/route.ts
import { createNextYakHandler } from "@yak-io/nextjs/server";
import { createTRPCToolAdapter } from "@yak-io/trpc";
import { appRouter, createContext } from "@/server/trpc";

const trpcTools = createTRPCToolAdapter({
  router: appRouter,
  createContext: async ({ req }) => createContext({ req }),
  allowedProcedures: ["orders.list", "orders.detail", "products.search"],
});

export const { GET, POST } = createNextYakHandler({
  tools: [trpcTools],
});

See Tool Adapters for all available options including tRPC, GraphQL, REST/OpenAPI, and custom adapters.

YakProvider Props

Prop	Type	Default	Description
`appId`	`string`	—	Your Yak application ID (required)
`getConfig`	`() => Promise<ChatConfig>`	Fetches from `/api/yak`	Custom config provider
`onToolCall`	`(name, args) => Promise<unknown>`	POSTs to `/api/yak`	Custom tool call handler
`theme`	`Theme`	—	Widget styling options
`onRedirect`	`(path: string) => void`	—	Custom navigation handler
`disableRestartButton`	`boolean`	`false`	Hide the restart button in the chat header

YakWidget Props

Prop	Type	Default	Description
`iframeClassName`	`string`	—	CSS class for the iframe
`triggerLabel`	`string`	`"Ask with AI"`	Text on the floating button

Next Steps

Automatic Routes — How route scanning works and production setup
Manual Routes — Define routes explicitly or fetch them dynamically
Programmatic Control — Open the widget, send prompts from code
Styling — Customize appearance and theming