---
title: Installation
description: Install next-ai-ready and scaffold your first config.
canonical_url: https://next-ai-ready.vercel.app/en/docs/installation
url: https://next-ai-ready.vercel.app/en/docs/installation
last_updated: 2026-08-02
updated: 2026-08-02
author: next-ai-ready team
summary: Install next-ai-ready and scaffold your first config.
topics: [installation, next.js, zod]
---

# Installation

## Prerequisites

- **Node.js** 20 or later
- **Next.js** 14.2+ with App Router (Next.js 15+ recommended; 14.2, 15, and 16 are covered by the compatibility matrix)
- **pnpm**, npm, or yarn
- **Zod v4** (`zod@^4`) — required for actions (uses `z.toJSONSchema()`)

## Install

```bash
pnpm add next-ai-ready zod@^4
```

This installs the meta package which re-exports everything you need and provides the CLI.

## Complete the basic setup

```bash
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 detailed package map and command reference below are optional reading.

> **Release channel:** this site tracks `main`; npm `latest` and `alpha` currently serve `0.1.0-alpha.17`. This release adds root and `src/` content discovery, correct Nextra and Fumadocs routes, and locale-filtered MCP page search. On August 2, 2026, it passed the complete release gate, npm manifest verification, and a clean public-registry pnpm + Next.js 16 production build; the authenticated production MCP endpoint also passed initialize and all three page discovery calls.

## Package exports

| Import                                                    | Needs Next.js?             | Use for                                                                     |
| --------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------- |
| `next-ai-ready`                                           | Authoring, config, and CLI | `defineConfig`, `defineAction`, `withAiReady`, `aiRobots`, and CLI commands |
| `next-ai-ready/hooks`                                     | Yes                        | Runtime observability                                                       |
| `next-ai-ready/handlers/*`                                | Yes (`server-only`)        | Route stubs in `app/%5Fai-ready/`                                           |
| `next-ai-ready/actions`, `/config`, `/json-ld`, `/robots` | No or runtime-specific     | Focused APIs that avoid loading unrelated build code                        |
| `next-ai-ready/audit`                                     | No                         | Programmatic Audit without the CLI dispatcher                               |

Install **one** meta package for typical apps: `pnpm add next-ai-ready`. The `@next-ai-ready/*` scoped packages are used internally; you do not need to add them separately.

`jiti` is a runtime dependency of `@next-ai-ready/next` and is installed through the meta package. TypeScript `ai-ready.config.ts` files therefore work without adding `jiti` yourself.

**Optional peers and app dependencies** (install only when needed):

| Package                                    | When                                       |
| ------------------------------------------ | ------------------------------------------ |
| `zod@^4`                                   | Actions (required for real projects)       |
| `mcp-handler`, `@modelcontextprotocol/sdk` | MCP HTTP / stdio                           |
| `next`                                     | Route handlers only — not required for CLI |

Only **`next-ai-ready`** exposes the `next-ai-ready` CLI binary. `@next-ai-ready/next` also ships a bin for monorepo dogfooding — use the meta package in consumer apps (C-01).

## Scaffold (recommended)

```bash
npm create next-ai-ready my-site
cd my-site
npm install
npx next-ai-ready init
```

The scaffold creates a runnable minimal Next.js App Router TypeScript app with `app/layout.tsx`, `app/page.tsx`, TypeScript and Next.js configuration, and starter `content/index.mdx`. It intentionally does not include AI-ready config or handler stubs; the final `next-ai-ready init` command creates and wires them after dependencies are installed.

## Initialize

For a scaffolded or existing Next.js app that has not been initialized yet:

```bash
npx next-ai-ready init
```

This creates:

- `ai-ready.config.ts` in TypeScript apps, or `.mjs` in JavaScript apps — your site config (includes robots strategy notes)
- `instrumentation.ts` + `instrumentation-node.ts` — optional observability hooks (`next-ai-ready/hooks`, Edge-safe split)
- `app/%5Fai-ready/` — route handlers for `llms.txt`, `openapi.json`, etc.
- `app/api/actions/` — the action execution endpoint
- `app/api/mcp/` — the MCP server endpoint
- `actions/index.ts` in TypeScript apps, or `.mjs` in JavaScript apps — a starter action file with a `ping` health check

`init` also patches `next.config` with `withAiReady()` from the public meta package and adds `next-ai-ready build` to your build script when missing.

`%5F` is the URL-encoded form of `_`. Next.js treats a literal `app/_ai-ready/` folder as private and excludes it from routing, while `app/%5Fai-ready/` correctly serves the `/_ai-ready/*` URL namespace. Do not rename the generated folder. When upgrading from alpha.10 or earlier, rerun `npx next-ai-ready init` and remove the obsolete `app/_ai-ready/` directory after reviewing local customizations.

## Configure

Edit `ai-ready.config.mjs` to match your site:

```js
import { defineConfig } from "next-ai-ready";

export default defineConfig({
  site: {
    name: "My Site",
    baseUrl: "https://example.com",
    description: "A short description for AI.",
  },
  content: ["app/**/*.mdx", "content/**/*.mdx"],
  actions: "./actions/index.mjs",
});
```

### Robots policy

`next-ai-ready build` emits `public/robots.txt` with explicit AI-bot rules unless you set `emit: { robots: false }`. For dynamic policies, add `app/robots.ts` and use `aiRobots()` from `next-ai-ready` — Next.js serves `app/robots.ts` at runtime. Doctor treats that as valid and does not require a static `public/robots.txt`.

## Build

```bash
npx next-ai-ready build
```

This scans your content, compiles the semantic graph, and writes all AI artifacts to `public/` and `.next-ai-ready/`.

## Verify

```bash
npx next-ai-ready doctor --score
```

Doctor checks your config, validates action exposure rules, detects `noai` meta, robots strategy, and route wiring. With `--score` you get a 0–100 readiness score and **Top fixes**. Use it in CI — exit 0 means no errors (warnings are OK).

For a full walkthrough see the monorepo [quickstart-10min](https://github.com/mustcanbedo/next-ai-ready/blob/main/docs/quickstart-10min.md) guide.