next-ai-ready

next-ai-ready

中文文档 | English

Live docs: English · 中文

Support and services: support the open-source project or request a fixed-scope diagnostic

Add AI-readable discovery and Markdown endpoints to a Next.js App Router site in about 10 minutes. Add authenticated agent actions later, when you need them.

Start in 10 minutes

pnpm add next-ai-ready
pnpm exec next-ai-ready init
# Add or update content/**/*.mdx, then:
pnpm exec next-ai-ready build
pnpm exec next-ai-ready doctor --score

The basic setup is complete when doctor reports 0 errors and public/llms.txt lists your content. The generated discovery and Markdown endpoints run alongside your existing UI.

Next: follow the 10-minute guide, read the App Router llms.txt tutorial, or add authenticated agent actions.

Already using Fumadocs? Its native LLM and documentation MCP routes may be enough. Read the native-first integration decision before adding another content pipeline. Choose next-ai-ready for a shared semantic graph and structured outputs across content collections, or optional callable application actions.

Already using Next SEO, Fumadocs, or Nextra? Compare responsibilities before adding another integration. Native metadata and existing LLM endpoints may already meet your needs.

Prefer a disposable demo before editing an existing project?

npm create next-ai-ready@alpha next-ai-ready-demo

The generated project is a normal Next.js TypeScript app that can be committed and deployed.

Third-party tool baseline: the production documentation scored 100/100 with Vercel's open-source @vercel/agent-readability@0.5.0 on 2026-08-01. Review the machine-readable result or reproduce it with pnpm audit:vercel:site. This measures technical agent readability, not search ranking, indexing, or citation.

Release candidate: this repository and the documentation site track main and currently target 0.1.0-alpha.22. Treat npm view next-ai-ready dist-tags --json as the source of truth for public availability. Alpha.21 makes the default init flow Knowledge-first: five AI-readable content files, no mandatory Capability dependencies, and an explicit --with-capabilities upgrade path.

If you installed alpha.21, upgrade to alpha.22 to remove its false missing-OpenAPI warning in Knowledge-only projects. OpenAPI is optional; do not enable capabilities just to remove that warning. Follow the quickstart HTTP checks to verify actual content.

Published alpha.22 removes that false warning while retaining checks for configured capabilities, builds breadcrumbs only from existing graph pages, and includes canonical nextaiready.com homepage metadata for seven internal packages. Public APIs and the Knowledge-only default remain unchanged.

Published baseline (2026-10-03): npm latest and alpha were verified as 0.1.0-alpha.22 for next-ai-ready and @next-ai-ready/next. Release Alpha #11 passed the full gate, publication, and tag checks. A fresh public-registry pnpm / Next.js 16.3.8 install passed initialization, artifact generation, doctor, and the production build. The unchanged create-next-ai-ready remains alpha.13; this is not the final GA release.

---

What this is

next-ai-ready is the AEO / Agent-API layer for Next.js.

SEO optimizes your site for browsers and search engines. next-ai-ready adds interfaces for AI consumers — so:

1. AI systems can discover and retrieve clean representations of your content.
2. Authorized AI agents can call your features as tools on behalf of users.

These interfaces improve technical accessibility; they do not guarantee indexing, ranking, citation, or inclusion in an AI-generated answer.

This is not a SaaS, not a dashboard, not a chatbot. It is a developer infra tool that lives next to next.config.js.

What it produces

From the same Next.js app, with zero changes to your UI, you get:

Artifact	Consumer
HTML	Browsers (untouched)
/llms.txt, /llms-full.txt	LLMs, AI search crawlers
/sitemap.md	Agent-readable page discovery
/<route>.md, /<route>.ai.json	Retrieval, RAG, AI ingestion
JSON-LD (Article, FAQPage, WebPage, BreadcrumbList)	Search engines, AI search
/openapi.json, /tools.json, /.well-known/ai-plugin.json	Agents, OpenAPI consumers
/api/mcp (MCP server)	MCP clients (Claude Desktop, Cursor, agents)
/robots.txt (explicit AI-bot policy)	AI crawlers

Keep AI search visible without opting into training

AI search, model training, and user-requested retrieval are different access decisions. Configure them independently instead of applying one opaque switch to every AI crawler:

// ai-ready.config.ts
import { defineConfig } from "next-ai-ready"

export default defineConfig({
  site: { name: "Acme", baseUrl: "https://acme.com" },
  robots: {
    aiBots: {
      search: "allow",
      training: "disallow",
      user: "allow",
      other: "disallow",
    },
  },
})

The existing aiBots: "allow" | "disallow" form remains supported. See the AI crawler policy guide for provider-specific limits and verification steps.

The two planes

                  ┌────────────────────────┐
                  │   Next.js App Router   │
                  └───────────┬────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
       ┌────────────┐                  ┌──────────────┐
       │ Knowledge  │  ← MDX +         │  Capability  │  ← defineAction()
       │   plane    │   semantic{}     │     plane    │
       └─────┬──────┘                  └──────┬───────┘
             │                                │
        llms.txt                         openapi.json
        page.md / .ai.json               tools.json
        JSON-LD                          MCP server

Quick taste

// app/docs/getting-started/page.mdx
export const semantic = {
  summary: "Install and run Acme in under 60 seconds.",
  topics: ["install", "quickstart"],
  questions: [{ q: "How do I install Acme?", a: "Run `pnpm i acme`." }],
}

# Getting Started
...

// actions/search-product.ts
import { defineAction } from "next-ai-ready"
import { z } from "zod"

export default defineAction({
  name: "search_product",
  description: "Search products by keyword.",
  whenToUse: "When the user wants to find products in our catalog.",
  input: z.object({ keyword: z.string(), limit: z.number().default(10) }),
  output: z.object({ items: z.array(z.object({ id: z.string(), title: z.string() })) }),
  public: true,
  async handler({ keyword, limit }, ctx) {
    return { items: await db.products.search(keyword, limit) }
  },
})

pnpm add next-ai-ready
npx next-ai-ready init     # scaffold the Knowledge Plane
npx next-ai-ready build    # emit llms.txt, sitemap.md, graph, OpenAPI, tools, robots
npx next-ai-ready doctor   # validate config, action exposure, route wiring (CI-friendly)
npx next-ai-ready audit https://example.com/about  # verify the deployed page agents receive
npx next-ai-ready audit https://example.com/about --version 2 --json  # five-dimensional report
npx next-ai-ready audit https://example.com/about --version 3 --json  # three-plane strict preflight
npx next-ai-ready mcp      # run an MCP server over stdio (Claude Desktop / Cursor)

When you need Actions and MCP, install their runtime peers and opt in:

pnpm add zod@^4 @modelcontextprotocol/sdk mcp-handler
npx next-ai-ready init --with-capabilities

Then run next build to expose the generated discovery, retrieval, and capability interfaces.

Opt in to Markdown content negotiation in next.config.mjs:

// next.config.mjs
import { withAiReady } from "next-ai-ready"

const nextConfig = {}

export default withAiReady({ agentReadable: true })(nextConfig)

This serves page Markdown for Accept: text/markdown and known agent User-Agents, while normal browser requests continue to receive HTML. Missing browser pages keep a real HTTP 404; missing Markdown representations return a 200 recovery document with the requested path, discovery links, and up to five relevant pages so agents can continue navigating.

next-ai-ready audit <url> verifies those browser and agent behaviors independently. Audit v1 remains the default, preserving its JSON shape, score, and CI exit behavior. Audit v2 remains available for its original five weighted dimensions. Use --version 3 for separate Agent Readability, Semantic/AEO Quality, and Agent Capability planes with strict pass-only tier scoring. V3 is a fast local subset preflight, while the repository's pinned @vercel/agent-readability command remains the official external Readability quality gate.

Every v3 check also returns a bounded judgment: pass, fail, or unknown, plus finite confidence, traceable evidence, and an explicit review decision. Scores remain useful summaries, but missing evidence and credential-bound checks are routed to review instead of being presented as certain facts.

Get started in 10 minutes: docs/quickstart-10min.md · 中文

Or scaffold with:

npm create next-ai-ready my-app
cd my-app
npm install
npx next-ai-ready init
npm run dev

The scaffold creates a runnable minimal Next.js App Router TypeScript project and starter content/index.mdx. It deliberately leaves AI-ready config, route handlers, and withAiReady() wiring to the following next-ai-ready init step. Actions and MCP remain opt-in through --with-capabilities.

Analytics hooks

Know which AI bots read your content and which actions agents invoke:

// instrumentation.ts — runs in Node.js and Edge; keep Node-only imports in a separate file
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./instrumentation-node");
  }
}

// instrumentation-node.ts
import "server-only";
import { registerAiHooks } from "next-ai-ready/hooks";

registerAiHooks({
  onAiRequest: (info) => analytics.track("ai_request", info),  // bot, ua, path, artifact
  onInvoke:    (info) => analytics.track("ai_invoke", info),   // action, latency, ok, caller
})

Use next-ai-ready/hooks — not the main package entry — so Turbopack does not pull Node-only build code into the Edge instrumentation bundle.

Package imports

Install only next-ai-ready in consumer apps. The alpha.22 repository candidate supports these imports:

Import	Use for
next-ai-ready	defineConfig(), defineAction(), withAiReady(), aiRobots(), and shared page search
next-ai-ready/hooks	Runtime observability hooks
next-ai-ready/handlers/*	Generated App Router handlers
next-ai-ready/actions, /config, /json-ld, /robots	Focused runtime APIs with smaller tracing surfaces
next-ai-ready/search	Shared page search without loading build-time SDK modules
next-ai-ready/audit	Programmatic Audit without loading the CLI dispatcher

Status

🚧 Pre-alpha (0.1.0-alpha.22 repository candidate; see the dated published baseline above for npm availability). The guarded release workflow validates packages and tags; see the current improvement ledger for the external-adoption gate before the final 0.1.0 GA release.

• ✅ Knowledge plane — MDX → semantic graph → llms.txt / *.md / *.ai.json / JSON-LD
• ✅ Capability plane — defineAction → /api/actions/<name> + OpenAPI 3.1 / tools.json / ai-plugin.json
• ✅ MCP server — actions as tools, pages as resources, and locale-aware, CJK-friendly list_pages / get_page / search_pages discovery (HTTP + stdio)
• ✅ Shared retrieval — one replaceable PageSearchProvider powers MCP and HTTP actions, so ranking cannot drift between protocols
• ✅ Dev tooling — build / init / doctor / versioned audit / mcp CLIs, robots.txt, analytics hooks
• ✅ Docs site — live at nextaiready.com (source)
• ✅ Nextra 4 compatibility fixture — one MDX collection drives the Nextra UI and AI-readable endpoints, with a production smoke contract (run it, first-party walkthrough with screenshots)

See docs/ (full index):

• docs/goals.md — North star: AEO + Agent capability
• docs/ga-readiness.md — 0.1 GA checklist
• docs/post-ga.md — Planned work after GA
• docs/research.md — Competitive landscape
• docs/architecture.md — Full architecture
• docs/decisions.md — Architecture decision records
• docs/roadmap.md — Phased delivery plan
• docs/quickstart-10min.md — 10-minute onboarding

Known limitations

• Zod v4 required — actions use z.toJSONSchema() which only exists in Zod v4. Install zod@^4.
• Nextra 4.6.1 needs a scoped Zod workaround — Nextra's published range can resolve its private dependency to Zod 4.4.x and break theme layout validation. The executable fixture pins only Nextra's internal Zod to 4.3.6 while the application continues using Zod 4.4.x; remove the override after the upstream fix ships (#4989, #5036).
• Node.js runtime only — all handlers export runtime = "nodejs". Edge Runtime is not supported.
• No static export — output: 'export' in Next.js config is not compatible (handlers need server runtime).
• No Pages Router — App Router only. The withAiReady() wrapper and route handlers target App Router conventions.
• Next.js 15+ recommended — handlers use async params; Next 14 sync params supported via resolveParams() helper.
• i18n graph is route-level, not CMS-aware — SemanticGraph includes locale and routesByLocale when routes use prefixes (e.g. /en/docs/...). You still curate llms.txt sections and MCP resources per locale manually. See i18n guide and Phase 6 design.

Package layout (C-01)

Consumer apps should install next-ai-ready (meta package) only. It re-exports APIs, handler subpaths, and the CLI. The @next-ai-ready/next scoped package duplicates the CLI bin for monorepo development — do not install both in the same app.

See installation — package exports.

License

MIT