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