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

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:

{
  "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:

// 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:

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

#Keep the index fresh in CI

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

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

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