---
title: Installation
description: Install next-ai-ready and scaffold your first config.
canonical_url: https://nextaiready.com/en/docs/installation
url: https://nextaiready.com/en/docs/installation
last_updated: 2026-09-29
updated: 2026-09-29
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 only when enabling Actions (uses `z.toJSONSchema()`)

## Install

```bash
pnpm add next-ai-ready
```

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.

For the complete decision path, generated endpoints, production evidence, and deployment checks,
follow the [Next.js App Router llms.txt walkthrough](./guides/nextjs-llms-txt).

> **Release channel:** this site tracks `main` and currently targets the `0.1.0-alpha.21` repository candidate. Verify public availability with npm dist-tags. Alpha.21 makes Knowledge-only setup the five-file default; use `--with-capabilities` when you need Actions, MCP, OpenAPI, and observability. The guarded release workflow reruns the complete gate before publication.

## 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)
- `app/%5Fai-ready/` — route handlers for `llms.txt`, full text, page Markdown, and AI JSON
- `next.config` wiring with `agentReadable: true`, so browsers keep HTML while agents can request Markdown

`init` also adds `next-ai-ready build` to your build script when missing. To add callable Actions, MCP, OpenAPI/tool routes, and observability hooks, install Zod and opt in explicitly:

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

`%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"],
});
```

Add `actions: "./actions/index.mjs"` only after running `init --with-capabilities`.

### 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.