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.

Deploy under a subpath

Set basePath in rdx.config.ts to serve the whole site from a path such as /scs-intellisense. Use a leading slash and URL-safe segments. Leave metadataBase set to the public origin.

rdx.config.ts
import { defineConfig } from '@lexibase/rdx'

export default defineConfig({
  basePath: '/scs-intellisense',
  metadata: {
    applicationName: 'SCS IntelliSense',
    metadataBase: 'https://docs.example.com',
  },
})

Write Markdown and configuration paths as usual, such as /images/logo.png and /docs/guides/installation. RDX adds the prefix when it renders them. Rebuild the project after changing basePath. To preview the build locally, open /scs-intellisense on the development host or /scs-intellisense/docs when the homepage is disabled.

In a custom homepage, use docsHref with RDX's Button or Next's Link. For native elements such as <video> and <img>, import withBasePath from @lexibase/rdx and pass the basePath prop to it, for example withBasePath('/videos/walkthrough.webm', basePath).

Route multiple Vercel projects from one domain

Give each RDX project a unique basePath and deploy it independently. In the project that owns the public domain, configure an external rewrite for each zone. Keep the prefix on both sides so page, asset and API requests reach the same zone.

vercel.json
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "rewrites": [
    {
      "source": "/scs-intellisense/:path*",
      "destination": "https://scs-intellisense.vercel.app/scs-intellisense/:path*"
    },
    {
      "source": "/sightline/:path*",
      "destination": "https://sightline.vercel.app/sightline/:path*"
    }
  ]
}

Serve /robots.txt from the router at the domain root. Crawlers look for the file there. Have it reference a sitemap index served by the router, and list each zone's sitemap in that index, such as /scs-intellisense/sitemap.xml and /sightline/sitemap.xml.

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.