Automatic Routes

Routes tell the AI what pages exist in your application, enabling it to navigate users to the right place when asked. The recommended approach is automatic scanning — Yak reads your filesystem to discover routes with zero configuration.

Default Behavior

By default, createNextYakHandler automatically scans your ./src/app and ./src/pages directories. It skips api/ folders and extracts title and description from static metadata exports in your page files.

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

// Scans ./src/app and ./src/pages automatically
export const { GET, POST } = createNextYakHandler();

That's it — no route list to maintain. As you add or remove pages, Yak picks them up automatically.

Customizing Route Scanning

Override the directories to scan or filter which routes are included:

import { createNextYakHandler } from "@yak-io/nextjs/server";

export const { GET, POST } = createNextYakHandler({
  appDir: "./app",           // Override app directory path
  pagesDir: false,           // Disable pages directory scanning
  routeFilter: {
    include: [/^\/docs/],    // Only include routes matching these patterns
    exclude: [/^\/docs\/drafts/],  // Exclude routes matching these patterns
  },
});

If routeFilter.include is set, at least one regex must match the path. routeFilter.exclude removes any matching routes after inclusion.

Production Setup

During local development, routes are scanned from your filesystem. In production, the compiled .next output doesn't include source files like ./src/app, so route scanning fails. The route manifest solves this by pre-generating routes at build time.

{
  "scripts": {
    "prebuild": "yak-nextjs generate-manifest",
    "build": "next build"
  }
}

# Generated route manifest
src/yak.routes.ts

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

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

Filtering Manifest Routes

Control which routes from the manifest are exposed using allowedRoutes and disallowedRoutes:

import { createNextYakHandler, createRouteManifestAdapter } from "@yak-io/nextjs/server";
import { routes } from "@/yak.routes";

export const { GET, POST } = createNextYakHandler({
  routes: createRouteManifestAdapter({
    routes,
    allowedRoutes: ["/docs/*", "/pricing", "/"],
    disallowedRoutes: ["/docs/internal/*"],
  }),
});

Pattern matching:

• Exact match: "/pricing" matches only /pricing
• Prefix match: "/docs/*" matches /docs, /docs/getting-started, etc.

Search & filter routes

By default the assistant's first instinct for a "show me…" / "find…" request is to drive your UI — navigate the user to a page that answers it — rather than fetch the data and render it inside the chat. For that to work for searches and filtered listings, tell Yak which routes are searchable and which query params they accept. The assistant only ever uses params you declare here; it never invents them.

Add search and/or filters to a route. Use the transform callback to annotate auto-scanned routes (the scanner can't infer these), or set them directly when you author routes manually:

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

export const { GET, POST } = createNextYakHandler({
  routes: createRouteManifestAdapter({
    routes,
    transform: (route) =>
      route.path === "/products"
        ? {
            ...route,
            // Free-text search: "show me boots" → /products?q=boots
            search: { queryParam: "q" },
            // Filters: "size 10 boots" → /products?q=boots&size=10
            filters: [
              { param: "category", description: "Product category" },
              { param: "size", values: ["8", "9", "10", "11"] },
            ],
          }
        : route,
  }),
});

When no route can serve a browse request, the assistant falls back to rendering the results in chat — so existing apps that don't declare search/filter routes keep working exactly as before.

CLI Reference

yak-nextjs generate-manifest [options]