concepts
How It Works
The build pipeline, runtime data flow, and what happens under the hood.
This page walks through what happens from next-ai-ready build to a live AI-ready endpoint.
Build pipeline
When you run npx next-ai-ready build:
1. Load config — reads ai-ready.config.mjs for site metadata, content globs, and action paths.
2. Scan content — uses fast-glob to find all MDX/MD files matching your content globs.
3. Compile — each file passes through the unified pipeline: parse MDX, extract headings/FAQ/entities/summary, strip JSX to clean Markdown, chunk by token budget.
4. Build graph — assembles all compiled pages into a SemanticGraph with stable node IDs and route mappings.
5. Emit Knowledge artifacts — writes graph.json, llms.txt, llms-full.txt, and robots.txt.
6. Emit Capability artifacts — loads your actions, builds the manifest, writes actions.manifest.json, openapi.json, tools.json, and ai-plugin.json.
All JSON output is deterministic: stable key order, no timestamps in payload (except generatedAt in a header field), stable node IDs.
Runtime data flow
At runtime, each AI endpoint reads a cached JSON file:
| Endpoint | Reads | Response |
|---|---|---|
/llms.txt | static file from public/ | text/plain |
/<route>.md | graph.json → node body | text/markdown |
/<route>.ai.json | graph.json → node tree | application/json |
/openapi.json | actions.manifest.json | application/json |
POST /api/actions/:name | imports handler, validates with Zod | result JSON |
/api/mcp | vercel/mcp-handler + registry | MCP stream |
Each handler reads its JSON source once per process and holds it in memory. Invalidation happens on the next deploy (production) or on file change via next-ai-ready dev (development).
Why a separate build step?
The build CLI runs outside the bundler. This is deliberate (ADR-006):
- Turbopack does not accept custom plugins. A webpack-only plugin would break Next 15+ defaults.
- Decoupling from the bundler makes the pipeline portable — it can run in CI before
next build. - Same pattern used by Contentlayer, Velite, and fumadocs-mdx.
The cost is one extra line in your build script: next-ai-ready build && next build. The benefit is that your AI layer works identically under Webpack and Turbopack.
What `withAiReady()` does
The withAiReady() wrapper in next.config.mjs does two things:
1. Adds rewrites — maps clean URLs (/llms.txt, /<route>.md, /openapi.json) to internal handler routes.
2. Enables file tracing — ensures .next-ai-ready/*.json ships with serverless function bundles.
It does not register bundler plugins, inject routes, or use virtual modules. This keeps it Turbopack-safe.