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

This setup is required for production deployments when using automatic scanning. If you provide routes manually via the routes option, you can skip this section.

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.

Generate the manifest at build time

Add a prebuild script to your package.json:

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

This generates ./src/yak.routes.ts containing your routes.

Different directory structure? The CLI auto-detects common layouts. For non-standard paths:

Project structure	Command
`src/app/` (default)	`yak-nextjs generate-manifest`
`app/`	`yak-nextjs generate-manifest --app-dir ./app --output ./app/yak.routes.ts`
`src/app/` + `src/pages/`	`yak-nextjs generate-manifest --pages-dir ./src/pages`
`app/` + `pages/`	`yak-nextjs generate-manifest --app-dir ./app --pages-dir ./pages --output ./app/yak.routes.ts`

Add to `.gitignore`

Since the file is generated at build time:

# Generated route manifest
src/yak.routes.ts

Use the route manifest in your handler

// 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 }),
});

The import path depends on your tsconfig.json paths. Common configurations:

src/yak.routes.ts → @/yak.routes (when @/* maps to ./src/*)
app/yak.routes.ts → @/yak.routes (when @/* maps to ./app/*) or use a relative path

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.

CLI Reference

yak-nextjs generate-manifest [options]

Option	Default	Description
`--app-dir <path>`	`./src/app`	App directory to scan
`--pages-dir <path>`	—	Pages directory (optional, scanned in addition to app-dir)
`--output <path>`	`./src/yak.routes.ts`	Output file path