# Next.js and React

In a Next.js app, or any React app with a server, ondocs is three pieces: an index built by the CLI, a route handler made with `createAskHandler`, and the `<AskDialog />` component. The ondocs website is built exactly this way.

## Install for Next.js

```sh
npm i ondocs ai @ai-sdk/openai @radix-ui/react-dialog cmdk
```

`@radix-ui/react-dialog` and `cmdk` work with React 18.3 and 19.

## Index your content

Build the index from the folder that holds your pages, and commit `ask-index.json`. Running it before every build keeps it current, and only changed chunks are embedded again:

```json
{
  "scripts": {
    "index": "ondocs index content --base-url /docs -e openai:text-embedding-3-small --dimensions 512",
    "prebuild": "npm run index"
  }
}
```

`--base-url /docs` makes `content/setup.md` cite `/docs/setup`. The CLI detects Next.js-style content (Fumadocs, Nextra) and leaves `(group)` folders out of URLs.

## Mount the route handler

To add the endpoint to Next.js, export the handler as `POST` from a route handler. It is a plain `(request: Request) => Promise<Response>` function:

```ts
// app/api/ask/route.ts
import { openai } from '@ai-sdk/openai';
import { createAskHandler, memoryRateLimit } from 'ondocs/server';
import index from '../../../ask-index.json';

export const POST = createAskHandler({
  index,
  model: openai('gpt-5.4-mini'),
  embeddingModel: openai.embedding('text-embedding-3-small'),
  siteName: 'Acme Docs',
  rateLimit: memoryRateLimit({ limit: 10, windowMs: 60_000 }),
});
```

Importing the JSON bundles the index with the function, and it is loaded into memory once per server instance. Set `OPENAI_API_KEY` in your deployment's environment.

## Render the dialog

Render the dialog once, near the root, from a client component. `onNavigate` sends citations through the Next.js router instead of a full page load:

```tsx
// app/ask.tsx
'use client';
import { AskDialog } from 'ondocs/react';
import 'ondocs/react/styles.css';
import 'ondocs/embed/launcher.css';
import { useRouter } from 'next/navigation';

export function Ask() {
  const router = useRouter();
  return (
    <AskDialog
      launcher
      suggestions={['How do I install it?', 'Which runtimes are supported?']}
      onNavigate={(url, event) => {
        event.preventDefault();
        router.push(url);
      }}
    />
  );
}
```

Then render `<Ask />` in `app/layout.tsx`. `launcher` shows a floating "Ask AI" button; the dialog also opens with ⌘K or Ctrl+K.

## Open it from your own button

Leave `launcher` out and pass `trigger` to open the dialog from an element of your own, such as a search box in your header: `<AskDialog trigger={<button type="button">Ask the docs</button>} />`. Change the shortcut with `shortcut="j"`, or turn it off with `shortcut={false}`.

## Other React frameworks and runtimes

`createAskHandler` returns a Web-standard handler, so it mounts anywhere that speaks `Request` and `Response`: `app.post('/api/ask', (c) => handler(c.req.raw))` in Hono, `Bun.serve({ fetch: handler })`, or `export default { fetch: handler }` in a Cloudflare Worker. React Router, Remix, SvelteKit and Astro endpoints also receive a `Request`, which you pass to the handler as it is. The dialog only needs React and the endpoint's URL.

## Build your own interface

`useAsk()` from `ondocs/react` is the hook behind the dialog. It returns `ask`, `stop` and `reset`, plus the streaming `answer`, its `sources` and a `status`, so you can render answers inline on a page instead of in a dialog. `AskAnswer` renders an answer with clickable citations. See [The ask dialog](/docs/ask-dialog#the-useask-hook).

## Keep the index fresh in CI

Add the check to CI so a pull request that changes content without rebuilding the index fails:

```sh
npx ondocs index content --base-url /docs --check   # exit 1 if stale
```

The check never calls a model and needs no API key.