Skip to content
Guides

Updating RDX

Update the framework and validate your documentation.

Update the framework

Review the release notes, then stop the development server and update the main package from the project root:

pnpm add @lexibase/rdx@latest

The main package selects compatible runtime and UI versions. You do not need to manage its internal packages individually. Your documents, public files, configuration and custom components are not replaced by this operation.

Check the release notes for migrations and any required Next.js, React or Node.js updates. Those requirements are separate from updating RDX itself.

Update from RDX 4.1 to 4.2

Update the main framework using the commands above. Existing documents, configuration and custom React components remain compatible.

Pages can use .md or .mdx. Both formats support the built-in Markdown components; use .mdx when a page needs JSX or component imports. Keep one file per page route: intro.md and intro.mdx in the same folder share a route.

Use a public image path such as navbar.logo: '/images/logo.png' or keep a React logo component. Store image files in public/; rdx check validates the configured logo alongside other local assets. See Custom logo.

If installed, also update the versioning plugin to 1.3.1 or newer and the i18n plugin to 1.0.1 or newer using the plugin update commands. These releases recognize .md content in translated trees and version-route validation. Existing snapshots and language configuration remain usable.

The next dev run or build refreshes the generated runtime. Mermaid diagrams keep their existing fence syntax and load locally from the UI package.

Direct package integrations should use runtime 4.2 with UI 3.4 or newer within major 3, plus types/core 2.2. The main framework selects compatible packages.

Update from RDX 4.0 to 4.1

Update the main framework using the commands above. Single-language documentation keeps its current files and configuration. Builds automatically run rdx check before compiling; fix reported broken links, assets or Markdown before deploying.

To offer translated content, follow Languages and run rdx add i18n. The installer reuses lang and asks for additional languages. Primary content stays in docs/; translations use locale/<folder>/docs/.

For multilingual snapshots, update the optional versioning plugin to 1.3.0 or newer using the plugin update commands. One rdx version captures all configured languages. Existing snapshots keep their original content; translated files are authored by the project owner and contributors.

Direct consumers of @lexibase/rdx-next must provide @lexibase/rdx-ui 3.3.0 or newer within major 3. The main @lexibase/rdx package supplies this compatible UI automatically.

Update from RDX 3.x to 4.0

RDX 4 manages search-engine indexing automatically. Remove metadata.robots from rdx.config.ts, keeping the rest of your configuration:

ts
metadata: {
  applicationName: 'My documentation',
  metadataBase: 'https://docs.example.com',
}

This shows only the relevant fields; retain your icons, social images, authors and other settings. Set metadataBase to the public URL of your site so RDX can generate absolute sitemap URLs. Without it, the sitemap contains no entries.

Update the main framework using the commands above. If versioning is installed, also update the optional plugin to 1.2.1 or newer. Its commands and manifest format remain compatible. Your Markdown, React component imports, assets and custom styles remain usable, and Node.js, Next.js and React requirements are unchanged.

Use rdx check to review document links, section anchors and local assets, then build and preview your site. After deployment, inspect /sitemap.xml and /robots.txt. The indexing policy is shared by page metadata and the generated sitemap.

The main framework supplies runtime 4.0 and UI 3.2.1. Direct package integrations should update runtime to 4.0 and types/core to 2.0. Runtime retains UI ^3.2.0 compatibility. Native Next.js hosts use getSourceRobots, getRdxSitemap and getRdxRobots to apply the same policy to their own routes; generated projects already include that integration.

Update from RDX 3.1 to 3.2

Update the main framework with the commands above. Existing configuration, Markdown and custom React imports remain usable. RDX 3.2 includes shared skip-to-content navigation, sidebar labels that wrap at narrow widths, and accessible text alternatives for combinations written as :kbd[Ctrl + K]. Write complete combinations with spaces around + to display the keys together with a localized text alternative.

Published documentation editions

If you use versioning, also update the optional plugin to version 1.2 or newer. Update the framework and plugin together before running the publishing commands or deploying their manifest.

Versioning keeps one published edition per major. Running rdx version 3.2.0 copies the ready content from docs/ and replaces the previous major-3 entry with 3.2.0. A patch such as 3.2.1 advances that same edition. A new major adds an edition and preserves the final documentation of previous majors. The live Current/Canary documentation stays independent.

Existing manifests with multiple editions of the same major use the highest version of that major. The next versioning command records the consolidated manifest and its redirects map. Snapshot files stay on disk; historical URLs redirect to the updated edition, preserving the requested page path. Removed pages return a 404. Keep the redirect map with your documentation in Git.

Archiving and restoring use the published label currently listed for that major. Publishing a newer version of an archived major keeps it archived. See Versioning for commands and examples.

For direct package integrations, update the runtime and UI to 3.2 together. Native Next.js integrations should apply the complete object returned by getRdxTracingConfig to their Next configuration, including its redirects. The generated runtime already applies this configuration.

Update from RDX 3.0 to 3.1

Update the main framework with the commands above. RDX 3.1 includes natural Markdown syntax for Callouts, Tabs, Accordion and keyboard keys; Mermaid diagrams; code block titles, line numbers and file trees; mobile navigation motion; and custom highlights through rdx.css.

Existing Markdown and React component imports remain usable. Create rdx.css beside rdx.config.ts to customize highlight colors. See Writing pages for component authoring and Code blocks for fence options.

If the optional versioning plugin is installed, update it separately to use the archive and restore commands:

pnpm add @lexibase/rdx-versioning@latest

Versioning 1.1 provides rdx archive <version> and rdx unarchive <version>. Both preserve snapshot contents and URLs. Follow Versioning for the complete workflow. Direct runtime/UI users should update the runtime and UI to 3.1 together; the main framework handles that pairing automatically.

Upgrade from RDX 2.x to 3.x

RDX 3 includes the complete shadcn Code Block, diff and folder fences, responsive image previews, and the complete shadcn Dialog composition. Update the main package using the commands above. Standard Markdown fences and images continue working automatically.

Custom Code Block components

The React CodeBlock export is now the root of the shadcn composition, with a separate CodeBlockContent. If your custom React components use the former pre wrapper, replace that import with the Markdown adapter:

tsx
import { MdxCodeBlock } from '@lexibase/rdx/ui/components/mdx-code-block'

export function Example() {
  return (
    <MdxCodeBlock>
      <code className="language-ts">{'const search = true'}</code>
    </MdxCodeBlock>
  )
}

You can also consult the official component reference. Pass pre-specific props, wrapping and line-number options to CodeBlockContent; pass the exact clipboard text to CodeBlockCopyButton through value.

Custom Dialog components

DialogContent uses the centered shadcn layout. Custom callers can set their position, width and padding through className, and control the built-in close button with showCloseButton. The built-in search retains its existing layout.

Direct runtime and UI dependencies in 3.x

The main framework selects matching runtime and UI versions. If you maintain direct dependencies on these packages, update both to 3.x together:

pnpm add @lexibase/rdx-next@3 @lexibase/rdx-ui@3

Keep your existing content, configuration, public assets and snapshots. Optional plugins remain separate dependencies.

Upgrade from RDX 1.x to 2.x

Update the main package using the commands above. RDX 2 includes interface translations selected by lang, keyboard shortcut components, page-specific social previews, and the shared custom 404 page. Markdown tables use the default shadcn/ui styling.

Custom navigation components

Replace ButtonLink imports from @lexibase/rdx/ui/components/button-link with Button from @lexibase/rdx/ui/components/button. For direct UI imports, use @lexibase/rdx-ui/components/button.

tsx
import { Button } from '@lexibase/rdx/ui/components/button'

export function DocumentationLink() {
  return (
    <Button href="/docs" variant="link">
      Documentation
    </Button>
  )
}

Keep your existing variant and size when preserving button styling. With href, Button renders a native link; without it, it renders an action button. Projects using only the generated configuration and MDX pages do not need this import change.

Direct runtime and UI dependencies

The main @lexibase/rdx package selects compatible dependencies automatically. If your project declares @lexibase/rdx-next and @lexibase/rdx-ui directly, update both to 2.x together:

pnpm add @lexibase/rdx-next@2 @lexibase/rdx-ui@2

The next development run or production build refreshes the internal app and its 404 page. Keep your documents, configuration, public assets, custom components, and installed plugins in the existing project.

Newly published releases with pnpm

pnpm can apply a minimum release age when installing updates and checking the lockfile before pnpm dev. If an update is blocked with ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION, follow Release-age policies to wait for the configured period or approve the exact versions you reviewed. The error can name internal RDX dependencies as well as the main framework package.

Apply approvals in the pnpm-workspace.yaml that governs the project. In a monorepo, this is usually the workspace-root file, shared by its applications.

Optional plugins

Plugins remain separate dependencies. Update an installed plugin when its release notes recommend a compatible update:

Versioning

pnpm add @lexibase/rdx-versioning@latest

Languages

For projects with the i18n plugin installed:

pnpm add @lexibase/rdx-i18n@latest

Validate and deploy

Restart the development server to check your documentation. For production:

pnpm build
pnpm start

Check documents, relative links, components, assets, search and snapshots before redeploying. Keep customizations in project-owned files; RDX refreshes generated runtime files.

Adopt the main package in an existing package-level setup

Install @lexibase/rdx, then change the configuration import to:

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

For custom React components, use paths such as @lexibase/rdx/ui/components/home instead of direct UI package imports. After migrating those imports, remove direct runtime and UI dependencies:

pnpm remove @lexibase/rdx-next @lexibase/rdx-ui

Keep Next.js, React and any installed plugins. Rebuild and validate before deploying. Advanced applications can also keep using the lower-level packages.