Skip to content
Guides

Build and deployment

Validate production locally, then deploy the complete documentation project.

Build locally

rdx build automatically checks your documentation before compiling. Broken document links, missing sections, missing local files and parsing errors stop the build with their source locations.

Set metadata.metadataBase in rdx.config.ts to your public site URL so RDX can generate absolute sitemap URLs. After deployment, visit /sitemap.xml and /robots.txt to inspect the generated files. See Search engine indexing for the automatic rules for current, published and archived documentation.

RDX also publishes a Markdown index at /docs/llms.txt.

From the directory containing package.json and rdx.config.ts:

pnpm build

pnpm start

The generated scripts call rdx build and rdx start; they run Next.js against the internal .rdx/ app.

Do not deploy the development server. Test your pages, assets, navigation, search, and a nonexistent URL before making a deployment public.

Keep the source

Your build environment needs docs/, public/, rdx.config.ts, the package manifest and lockfile, and any imported React components. With versioning, include versions.json and versioned_docs/ too.

Do not upload only .rdx/.next. Do not commit generated .rdx/ files or copy Windows dependencies into a Linux build environment. Install and build on the host.

Vercel

Create vercel.json beside your documentation project's package.json and rdx.config.ts. For a pnpm project:

json
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "nextjs",
  "installCommand": "pnpm install --frozen-lockfile",
  "buildCommand": "pnpm build",
  "outputDirectory": ".rdx/.next"
}

Commit the package manifest, lockfile, configuration, and documentation sources before deploying. --frozen-lockfile uses the committed dependency versions and fails if the lockfile needs updating. With npm and a committed package-lock.json, use npm ci for installCommand and npm run build for buildCommand.

Import your Git repository through the Vercel dashboard. Set Root Directory to the folder containing rdx.config.ts. For a standalone documentation repository, this is the repository root. The configuration selects the Next.js preset, runs the RDX build script, and points Vercel to the generated Next.js output in .rdx/.next.

Inside a monorepo

For documentation installed in apps/web, keep the configuration inside that application:

Folder
my-repository/
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
apps/
web/
package.json
rdx.config.ts
vercel.json
docs/
public/

Include the application in your workspace, for example through apps/* in pnpm-workspace.yaml, and commit the updated repository-root lockfile. Set the Vercel project's Root Directory to apps/web. Keep outputDirectory as .rdx/.next: the path is relative to that application directory.

If the build needs workspace files outside apps/web, enable Include source files outside of the Root Directory in the Build Step in the Vercel project's Root Directory settings. If your app depends on local packages that require compilation, include those build steps before the documentation build.

See Vercel's monorepo setup and vercel.json reference for the corresponding platform settings.

The framework traces configured documentation and plugin runtime files into the server build. Keep your source content available during the build; do not create snapshots inside a serverless request.

Node.js hosting

On a Node.js server, install dependencies, run the build, and start the generated project:

pnpm start

Configure HTTPS, a process supervisor, and the host's network settings. Keep the complete project available to the runtime, including configuration, content, local components, and plugin data. Install and build on the destination host with its Node.js version.

The process needs permission to read the project and write to .rdx/ when it starts. Keep public/ as a regular directory so RDX can link it into the generated application.

Updates

Content, configuration, component, and version changes require a new build and deployment. Search indexes are built from the documentation at build time. Set metadata.metadataBase to your final public URL for social previews.