Manual Routes
If you'd rather not rely on filesystem scanning, you can define routes explicitly. This is useful when you want precise control over what's exposed, need to include routes from external sources, or are building a non-standard application structure.
Static Route List
Pass a routes array to bypass automatic scanning entirely:
// app/api/yak/[[...yak]]/route.ts
import { createNextYakHandler } from "@yak-io/nextjs/server";
export const { GET, POST } = createNextYakHandler({
routes: [
{ path: "/", title: "Home" },
{ path: "/pricing", title: "Pricing", description: "View our plans" },
{ path: "/dashboard", title: "Dashboard" },
],
});When you provide routes, automatic filesystem scanning is disabled. Only the routes you list will be visible to the AI.
Combining Route Sources
Mix automatic scanning with additional manual sources using the scanRoutes helper:
import { createNextYakHandler, scanRoutes } from "@yak-io/nextjs/server";
const marketingRoutes = {
id: "marketing",
getRoutes: async () => [
{ path: "/", title: "Home" },
{ path: "/pricing", title: "Pricing", description: "View our plans" },
],
};
export const { GET, POST } = createNextYakHandler({
routes: [() => scanRoutes("./src/app"), marketingRoutes],
});Each route source is an object with an id and a getRoutes async function, or a function returning routes directly.
Dynamic Route Sources
Fetch routes at runtime from external sources like a CMS or database:
const cmsRoutes = {
id: "cms",
getRoutes: async () => {
const res = await fetch("https://cms.example.com/api/pages");
return res.json();
},
};
export const { GET, POST } = createNextYakHandler({
routes: [cmsRoutes],
});Route Schema
Each route object supports these properties:
| Property | Type | Required | Description |
|---|---|---|---|
path | string | Yes | The URL path |
title | string | No | Human-readable page title |
description | string | No | Brief description for AI context |
search | { queryParam: string } | No | Marks a free-text search page so the AI can drive it (e.g. /search?q=…) |
filters | { param, description?, values? }[] | No | Query-param filters the route accepts, so the AI can narrow a listing |
Descriptive titles and descriptions help the AI make better decisions about when to navigate users to specific pages. To make the AI prefer driving your UI (navigating to a search or filtered listing) over rendering results in the chat, declare search/filters — see Search & filter routes.