# Next.js (/docs/integrations/nextjs)

`@yaakdoc/next` serves your yaakdoc site at a path of a Next.js app, such as `/docs`, in development and in production.

```npm
npm i @yaakdoc/next
```

```ts title="next.config.ts"
import type { NextConfig } from "next";
import { createNextYaakdoc } from "@yaakdoc/next";

const withYaakdoc = createNextYaakdoc({
  path: "/docs",
  export: "./yaak.json",
  config: {
    branding: {
      title: "Acme API"
    },
    pages: "per-request",
  },
});

const nextConfig: NextConfig = {};

export default withYaakdoc(nextConfig);
```

Add the build output to `.gitignore`:

```text title=".gitignore"
public/docs
```

`createNextYaakdoc(options)` returns `withYaakdoc`. You can keep it in a file of its own and import it into `next.config.ts`. `withYaakdoc(nextConfig)` accepts an object or a function (`(phase, context) => config`), like any Next.js config. Next's `basePath` is respected.

The docs are configured inline, so you don't need a `yaakdoc.config.*` file. If there is one, `config` is merged over it. See the [options](#options).

## How it works [#how-it-works]

- **`next dev`.** The yaakdoc dev server starts in a child process, and the docs are proxied to it with rewrites. Editing the export or the theme reloads the page.
- **`next build`.** The docs are prerendered into `public/<path>` and served as static files, so they're deployed with the app, on Vercel or any other host. The build replaces that folder each time, and refuses to touch one that yaakdoc didn't create.
- **`next start`.** The docs are served from `public/<path>` through rewrites.
- **`output: "export"`.** The docs are part of the exported site, and no rewrites are added.

## Notes [#notes]

- **Trailing slashes.** yaakdoc links to `/docs/page/`. With Next's default `trailingSlash: false`, these redirect to `/docs/page`, which then serves the page.
- **Not found pages.** An unknown page under `/docs` shows your app's 404 page.

## Options [#options]

| Option | Description |
| --- | --- |
| `path` | Where the docs are served. Default: `/docs`. It takes precedence over `config.base`. |
| `config` | yaakdoc [config](/docs/reference/configuration), merged over `yaakdoc.config.*` if there is one. Paths are relative to `cwd`. |
| `export` | Path of the Yaak export. Shorthand for `config.export`. By default, `yaakdoc.json`, then `yaak.json`, is looked up in `cwd`. |
| `cwd` | Project directory. Default: `process.cwd()`. |
| `configFile` | An explicit config file, or `false` to not look for one. |
| `publicDir` | A folder copied to the docs' root as is. Default: none, because the app's `public/` folder isn't meant for the docs. |