Serve from Nest

mountOrbitDocs serves the static docs build from your own Nest server. Your API and its docs then share one origin and one deployment. It also enforces private docs and runs Ask AI and the MCP servers when the build has them.

Set it upCopy Anchor Link

export default defineConfig({
  // ...
  output: { mode: 'static', basePath: '/docs' },
});

cd docs
npm run build

import { existsSync } from 'node:fs';
import { join } from 'node:path';

import { NestFactory } from '@nestjs/core';
import { mountOrbitDocs } from '@orbitdocs/nestjs';

import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Serve the docs at /docs once `orbitdocs build` has run.
  const docs = join(__dirname, '../docs/out');
  if (existsSync(docs)) mountOrbitDocs(app, { root: docs, path: '/docs' });

  await app.listen(3000);
}

void bootstrap();

npx orbitdocs deploy --target nest builds the site and prints this snippet with your paths filled in.

OptionsCopy Anchor Link

mountOrbitDocs(app: INestApplication, options: MountOrbitDocsOptions): void

authCopy Anchor Link

aiCopy Anchor Link

specCopy Anchor Link

The built site already serves each spec at <path>/openapi/<api id>.json. Use spec when you want it at another URL as well:

mountOrbitDocs(app, {
  root: join(__dirname, '../docs/out'),
  path: '/docs',
  spec: { file: join(__dirname, '../docs/openapi/travel.json'), path: '/openapi.json' },
});

What it servesCopy Anchor Link

Every request under path goes through these steps:

1. orbitdocs-access.json and orbitdocs-ai.json answer 404. They are internal files.
2. Ask AI (<path>/_ai/…) and MCP (<path>/mcp, <path>/mcp/<api id>) requests are answered, when the build has ai.
3. Sign-in routes (<path>/_auth/…) are answered, when the build has access.
4. The access gate checks the page. A reader without access is sent to sign in, or denied.
5. The file is served. /docs/quickstart serves quickstart/index.html, and .html extensions are optional.
6. Anything not found gets the site's 404.html.

Environment variablesCopy Anchor Link

mountOrbitDocs reads secrets from the Nest process's environment at runtime. The build only stores their names. Set them where your API runs.

A complete example, from the sample app:

# Private docs (examples/nest-sample/docs/orbitdocs.config.ts → access)
ORBITDOCS_AUTH_SECRET=change-me-to-a-random-string-of-32-plus-chars
MOCK_OIDC_SECRET=anything
DOCS_HOOK_SECRET=change-me-too
DOCS_LLM_KEY=anything

There, MOCK_OIDC_SECRET is a provider's clientSecretEnv, DOCS_HOOK_SECRET the personalization secret and DOCS_LLM_KEY the ai.apiKeyEnv. OrbitDocs reads no variable for the output mode; that comes from output.mode in the config. See Environment variables for every variable, including the CLI's and the platform's.

GotchasCopy Anchor Link

• Start the server from the project root. mountOrbitDocs loads express from the package.json in the current working directory, so it uses your app's copy.
• The global prefix doesn't apply. path is an absolute URL path. app.setGlobalPrefix('api') does not move the docs to /api/docs.
• path and basePath must match. Otherwise pages load but links, styles and scripts point to the wrong place.
• Ship the build with the app. Copy docs/out/ into your image or artifact, at the place root points to. In a Dockerfile, build the docs before the final stage and copy the folder.
• Rebuild the docs after API changes. The server serves files; it doesn't re-extract. Run orbitdocs build in CI before you deploy.

Next stepsCopy Anchor Link