@lexibase/rdx-next 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -2,11 +2,33 @@
 
 The official Next.js runtime for RDX documentation projects.
 
+Requires Node.js 22.18+ (22.x) or 24.11+ (24.x). Use the latest patch of either line.
+The MDX renderer keeps JavaScript expression blocking enabled. Markdown, fenced
+code and registered JSX components with literal props remain supported, but
+expressions such as `{value}` or `style={{ ... }}` are not evaluated. Documentation
+must still be trusted project-owned content, not untrusted uploads.
+
 It exposes the `rdx` command used by generated projects to create their
 internal `.rdx` application and run Next.js.
 
+Run `pnpm rdx add versioning` (or `npm exec -- rdx add versioning`) from a
+documentation project to install and activate the official optional plugin.
+The command detects the package manager, preserves config and plugin options,
+validates the result before saving it without creating backups, and prepares
+the runtime. Repeating it does not duplicate or upgrade an installed plugin.
+Use `--package-manager npm|pnpm|yarn` to resolve ambiguous lockfiles. Dynamic
+configurations receive manual instructions and are not automatically edited.
+Installing a package with npm/pnpm/yarn alone never edits `rdx.config.ts`.
+
+First plugin installation follows the installed runtime: stable releases use
+`latest`, betas use `beta`, and release candidates use `rc`. Unknown prerelease
+channels require manual installation; missing tags do not fall back to another
+channel. A missing but declared plugin is restored with the manager's `install`
+command, without replacing its dependency range or section. Package-manager
+lockfile rules and security policies still apply normally.
+
 Generated sites use the same theme and components as the development website,
-through `@lexibase/rdx-ui`: logo, navbar, Radix version dropdown, mobile/desktop
+through `@lexibase/rdx-ui`: logo, navbar, Base UI version dropdown, mobile/desktop
 sidebar, landing page, MDX styles and theme provider. The adapter owns content
 and route data; it does not implement a parallel UI theme.
 
@@ -18,9 +40,76 @@ explicitly configured plugins enable the shared navbar dropdown.
 `.rdx/` is generated. Configure the site or edit a project-owned `home.tsx`
 instead of modifying files inside `.rdx/`.
 
+The generated project loader supports both the documentation project root and
+the internal `.rdx/` application as the server working directory. This matters
+for serverless Next workers, which can start inside `.rdx/`. Content and version
+manifests stay in the project root; do not copy them into the generated folder
+or initialize versioning again to work around a runtime path error.
+
 Place images, favicon and downloads in the project-root `public/` directory.
 The CLI links `.rdx/public` to it using a junction on Windows or a directory
 symlink elsewhere. `/images/logo.svg` serves `public/images/logo.svg` in dev and
 production. No asset copies are cached and original files are never removed.
 Restart/redeploy production after adding/removing assets. Documentation versions
 share this directory; snapshots do not copy its contents.
+
+Production builds trace only configured documentation (`.mdx` and
+`_category.json`) and runtime files declared by configured plugins. The versioning
+plugin declares its manifest, including a custom `versionsFile`; current, active
+and archived content sources are included. Live documentation always uses `docs/`;
+custom plugin snapshot paths remain supported without copying the whole project
+into the server deployment.
+Rebuild/redeploy after changing production content or version manifests.
+
+Native Next.js applications using the RDX core (such as `apps/web`) must spread
+`await getRdxTracingConfig({ rootDir })` from `@lexibase/rdx-next/config` into
+their Next configuration. If Next runs in a subdirectory, also pass `appDir` and
+set `outputFileTracingRoot` to include the documentation project root. Generated
+`.rdx/next.config.mjs` already does this. Do not remove the explicit tracing
+configuration: the core intentionally does not ask Turbopack to trace arbitrary
+project-relative filesystem paths.
+
+## Site metadata
+
+Configure SEO in `rdx.config.ts`; the generated layout uses Next.js's native
+Metadata API. `metadata.applicationName` is the single site name, while
+`description` sets the default site description at the top level.
+
+```ts
+export default defineConfig({
+  description: 'Learn how to use our project.',
+  metadata: {
+    applicationName: 'My documentation',
+    metadataBase: 'https://docs.example.com',
+    authors: [{ name: 'My team', url: 'https://example.com' }],
+    keywords: ['documentation', 'my-project'],
+    icons: { icon: '/favicon.ico' },
+    robots: { index: true, follow: true },
+    openGraph: {
+      type: 'website',
+      images: [{ url: '/og.png', width: 1200, height: 630, alt: 'My project' }],
+    },
+    twitter: { card: 'summary_large_image', images: ['/og.png'] },
+  },
+})
+```
+
+The starter provides `metadata.applicationName: 'My documentation'`. This name
+is required and supplies browser titles (including the `%s | Name` page title
+template), social preview defaults, accessible logo labels, the footer and the
+built-in homepage fallback. `navbar.title` is independent and optional. Custom
+homepage components own their contents; RDX does not inject this name into them.
+When upgrading, move the former root `title` into `metadata.applicationName`;
+there is no separate `metadata.title` to repeat. Set
+`metadataBase` to your real public URL when deploying; RDX does not invent a
+production domain or force localhost. Image, favicon and manifest paths refer
+to files you create in `public/`. Nothing creates those assets automatically.
+
+Supported fields are `metadataBase` (an absolute http(s) string),
+`applicationName`, `authors`, `keywords`, `icons`, `manifest`, `robots`,
+`openGraph` and `twitter`. TypeScript describes the supported nested options,
+and invalid fields fail during configuration validation. This is a portable
+subset, not an unrestricted pass-through of all Next.js metadata options.
+Open Graph and Twitter inherit `metadata.applicationName` and the site description
+unless explicitly overridden within their own options.
+No site-wide canonical or fixed Open Graph URL is emitted for every document.

package/bin/add-plugin.mjs

@@ -0,0 +1,277 @@
+import { randomUUID } from 'node:crypto'
+import { createRequire } from 'node:module'
+import { lstat, readFile, writeFile, rename, unlink } from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+
+import { createRdxProject, resolveConfig } from '@lexibase/rdx-core/config'
+import spawn from 'cross-spawn'
+import { createJiti } from 'jiti'
+
+import { activateVersioning, versioningPackage } from './plugin-config.mjs'
+
+const managers = new Set(['npm', 'pnpm', 'yarn'])
+const runtimeVersion = createRequire(import.meta.url)('../package.json').version
+
+// Internal installer policy; channels belong to the installed runtime release,
+// not the user's docs version, invoking command or dependency range.
+export function versioningInstallRequest(version, declared) {
+  if (declared !== undefined) {
+    if (typeof declared !== 'string' || !declared.trim())
+      throw new Error(
+        'The declared @lexibase/rdx-versioning dependency must be a non-empty string.'
+      )
+    return { kind: 'restore' }
+  }
+  const match =
+    typeof version === 'string' &&
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*))?(?:\+[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?$/.exec(
+      version
+    )
+  if (
+    !match ||
+    match[4]
+      ?.split('.')
+      .some(
+        (part) => /^\d+$/.test(part) && part.length > 1 && part.startsWith('0')
+      )
+  )
+    throw new Error(
+      'Cannot select a plugin channel: the RDX runtime version is invalid.'
+    )
+  const prerelease = match[4]?.split('.')[0]
+  if (prerelease && !['beta', 'rc'].includes(prerelease))
+    throw new Error(
+      `Unsupported RDX runtime prerelease channel "${prerelease}". Install and configure the official plugin manually; no channel fallback was attempted.`
+    )
+  return {
+    kind: 'add',
+    specifier: `${versioningPackage}@${prerelease ?? 'latest'}`,
+  }
+}
+
+export function parseAddArguments(args) {
+  const [plugin, ...rest] = args
+  if (plugin !== 'versioning')
+    throw new Error(
+      'Usage: rdx add versioning [--package-manager npm|pnpm|yarn]. Only the official versioning plugin is currently supported.'
+    )
+  if (!rest.length) return {}
+  if (
+    rest.length === 2 &&
+    rest[0] === '--package-manager' &&
+    managers.has(rest[1])
+  )
+    return { packageManager: rest[1] }
+  throw new Error(
+    'Usage: rdx add versioning [--package-manager npm|pnpm|yarn].'
+  )
+}
+
+async function exists(filename) {
+  try {
+    await lstat(filename)
+    return true
+  } catch (error) {
+    if (error.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+export async function detectPackageManager(
+  rootDir,
+  pkg,
+  env = process.env,
+  explicit
+) {
+  if (explicit) {
+    if (!managers.has(explicit)) throw new Error('Unsupported package manager.')
+    return explicit
+  }
+  if (
+    pkg.packageManager !== undefined &&
+    typeof pkg.packageManager !== 'string'
+  )
+    throw new Error('packageManager in package.json must be a string.')
+  const declared = pkg.packageManager?.split('@')[0]
+  if (declared && !managers.has(declared))
+    throw new Error(
+      'Unsupported packageManager in package.json. Choose --package-manager npm, pnpm or yarn explicitly.'
+    )
+  const locks = []
+  for (const [manager, filenames] of [
+    ['npm', ['package-lock.json', 'npm-shrinkwrap.json']],
+    ['pnpm', ['pnpm-lock.yaml']],
+    ['yarn', ['yarn.lock']],
+  ]) {
+    if (
+      (
+        await Promise.all(
+          filenames.map((filename) => exists(path.join(rootDir, filename)))
+        )
+      ).some(Boolean)
+    )
+      locks.push(manager)
+  }
+  if (locks.length > 1 || (declared && locks.length && locks[0] !== declared))
+    throw new Error(
+      'Conflicting package managers. Keep the intended lockfile or choose --package-manager npm, pnpm or yarn explicitly.'
+    )
+  const agent = env.npm_config_user_agent?.split('/')[0]
+  return declared ?? locks[0] ?? (managers.has(agent) ? agent : 'npm')
+}
+
+export function installPackage(
+  manager,
+  rootDir,
+  env = process.env,
+  request = versioningInstallRequest(runtimeVersion)
+) {
+  return new Promise((resolve, reject) => {
+    const args =
+      request.kind === 'restore'
+        ? ['install']
+        : [manager === 'npm' ? 'install' : 'add', request.specifier]
+    const nodeEntry =
+      env.npm_config_user_agent?.startsWith(`${manager}/`) &&
+      env.npm_execpath &&
+      /\.[cm]?js$/i.test(env.npm_execpath)
+    const child = spawn(
+      nodeEntry ? process.execPath : manager,
+      nodeEntry ? [env.npm_execpath, ...args] : args,
+      { cwd: rootDir, env, stdio: 'inherit' }
+    )
+    child.once('error', (error) =>
+      reject(
+        new Error(
+          `Could not run ${manager}: ${error.message}. Install it or choose --package-manager explicitly.`
+        )
+      )
+    )
+    child.once('exit', (code, signal) => {
+      if (code === 0) resolve()
+      else
+        reject(
+          new Error(
+            `${manager} installation failed (${signal ?? code}). rdx.config.ts was not changed. Package/lock files may have changed; inspect them before retrying. If pnpm reports a release-age policy error, approve only the trusted RDX release in your project policy.`
+          )
+        )
+    })
+  })
+}
+
+async function validateCandidate(filename) {
+  const jiti = createJiti(import.meta.url, {
+    moduleCache: false,
+    fsCache: false,
+    jsx: { runtime: 'automatic' },
+  })
+  const input = await jiti.import(filename, { default: true })
+  const config = resolveConfig(input)
+  // Validate paths and command registrations without running plugin setup hooks.
+  await createRdxProject(
+    {
+      ...config,
+      plugins: config.plugins.map((plugin) => ({
+        ...plugin,
+        setup: undefined,
+      })),
+    },
+    { rootDir: path.dirname(filename), command: 'prepare' }
+  )
+  if (
+    config.plugins.filter((plugin) => plugin.name === versioningPackage)
+      .length !== 1
+  )
+    throw new Error(
+      'Expected exactly one official versioning plugin in the resulting configuration.'
+    )
+}
+
+export async function addVersioning(rootDir, options = {}) {
+  const {
+    install = installPackage,
+    log = console.log,
+    env = process.env,
+  } = options
+  const filename = path.join(rootDir, 'rdx.config.ts')
+  let info
+  try {
+    info = await lstat(filename)
+  } catch (error) {
+    if (error.code === 'ENOENT')
+      throw new Error(
+        'Missing rdx.config.ts. Run rdx add from the documentation project root.'
+      )
+    throw error
+  }
+  if (!info.isFile() || info.isSymbolicLink())
+    throw new Error('rdx.config.ts must be a regular project file, not a link.')
+  const original = await readFile(filename, 'utf8')
+  // Refuse unsupported configurations before running the package manager.
+  const updated = activateVersioning(original)
+  const pkg = JSON.parse(
+    await readFile(path.join(rootDir, 'package.json'), 'utf8')
+  )
+  const manager = await detectPackageManager(
+    rootDir,
+    pkg,
+    env,
+    options.packageManager
+  )
+  const declared =
+    pkg.dependencies?.[versioningPackage] ??
+    pkg.devDependencies?.[versioningPackage]
+  let installed = false
+  try {
+    createRequire(path.join(rootDir, 'package.json')).resolve(versioningPackage)
+    installed = true
+  } catch (error) {
+    // The official package exposes ESM imports only. require.resolve can find
+    // its manifest but reject the require condition; validation below uses Jiti.
+    if (error.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') installed = true
+    else if (!['MODULE_NOT_FOUND', 'ERR_MODULE_NOT_FOUND'].includes(error.code))
+      throw error
+  }
+  if (!declared || !installed) {
+    const request = versioningInstallRequest(runtimeVersion, declared)
+    log(
+      request.kind === 'restore'
+        ? `Restoring the declared ${versioningPackage} dependency with ${manager}...`
+        : `Installing ${request.specifier} with ${manager}...`
+    )
+    await install(manager, rootDir, env, request)
+  } else
+    log(`${versioningPackage} is already installed; preserving its version.`)
+
+  const temporary = path.join(rootDir, `rdx.config.add-${randomUUID()}.ts`)
+  try {
+    await writeFile(temporary, updated, { flag: 'wx', mode: info.mode })
+    try {
+      await validateCandidate(temporary)
+    } catch (error) {
+      throw new Error(
+        `Plugin configuration validation failed: ${error.message}. rdx.config.ts was not changed. Installed dependencies were kept; fix the error and retry.`
+      )
+    }
+    if ((await readFile(filename, 'utf8')) !== original)
+      throw new Error(
+        'rdx.config.ts changed during installation. No configuration was overwritten; retry after reviewing your edits.'
+      )
+    const currentInfo = await lstat(filename)
+    if (!currentInfo.isFile() || currentInfo.isSymbolicLink())
+      throw new Error(
+        'rdx.config.ts was replaced during installation. No configuration was overwritten.'
+      )
+    if (updated !== original) {
+      await rename(temporary, filename)
+      log('Versioning activated in rdx.config.ts.')
+    } else
+      log('Versioning is already configured; no configuration changes needed.')
+  } finally {
+    await unlink(temporary).catch((error) => {
+      if (error.code !== 'ENOENT') throw error
+    })
+  }
+  return { changed: updated !== original }
+}

package/bin/plugin-config.mjs

@@ -0,0 +1,155 @@
+import ts from 'typescript'
+
+export const versioningPackage = '@lexibase/rdx-versioning'
+const manual = `Cannot safely edit rdx.config.ts. Add "import { versioning } from '${versioningPackage}'" and versioning() to plugins manually, then run rdx prepare.`
+
+function unwrap(node) {
+  while (
+    ts.isParenthesizedExpression(node) ||
+    ts.isAsExpression(node) ||
+    ts.isSatisfiesExpression(node)
+  )
+    node = node.expression
+  return node
+}
+
+// Edit only known literal shapes; never print/reconstruct the user's entire file.
+export function activateVersioning(source) {
+  const file = ts.createSourceFile(
+    'rdx.config.ts',
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  )
+  if (file.parseDiagnostics.length) throw new Error(manual)
+  const imports = file.statements.filter(ts.isImportDeclaration)
+  const definitions = new Set()
+  let factory
+  for (const entry of imports) {
+    const name = entry.moduleSpecifier.text
+    const clause = entry.importClause
+    if (!clause || clause.isTypeOnly) continue
+    const bindings = clause.namedBindings
+    if (bindings && ts.isNamedImports(bindings)) {
+      for (const specifier of bindings.elements) {
+        if (specifier.isTypeOnly) continue
+        const imported = (specifier.propertyName ?? specifier.name).text
+        if (
+          ['@lexibase/rdx-next', '@lexibase/rdx-core/config'].includes(name) &&
+          imported === 'defineConfig'
+        )
+          definitions.add(specifier.name.text)
+        if (name === versioningPackage && imported === 'versioning') {
+          if (factory) throw new Error(manual)
+          factory = specifier.name.text
+        }
+      }
+    } else if (
+      bindings &&
+      ts.isNamespaceImport(bindings) &&
+      name === versioningPackage
+    ) {
+      if (factory) throw new Error(manual)
+      factory = `${bindings.name.text}.versioning`
+    }
+  }
+  const exports = file.statements.filter(ts.isExportAssignment)
+  if (exports.length !== 1 || exports[0].isExportEquals) throw new Error(manual)
+  let config = unwrap(exports[0].expression)
+  if (ts.isCallExpression(config)) {
+    if (
+      !ts.isIdentifier(config.expression) ||
+      !definitions.has(config.expression.text) ||
+      config.arguments.length !== 1
+    )
+      throw new Error(manual)
+    config = unwrap(config.arguments[0])
+  }
+  if (!ts.isObjectLiteralExpression(config)) throw new Error(manual)
+  const properties = config.properties
+  if (
+    properties.some(
+      (entry) =>
+        !ts.isPropertyAssignment(entry) || ts.isComputedPropertyName(entry.name)
+    )
+  )
+    throw new Error(manual)
+  const pluginsProperties = properties.filter(
+    (entry) => entry.name.text === 'plugins'
+  )
+  if (pluginsProperties.length > 1) throw new Error(manual)
+  const plugins = pluginsProperties.length
+    ? unwrap(pluginsProperties[0].initializer)
+    : undefined
+  if (
+    plugins &&
+    (!ts.isArrayLiteralExpression(plugins) ||
+      plugins.elements.some(ts.isSpreadElement))
+  )
+    throw new Error(manual)
+  if (plugins && factory) {
+    const matches = plugins.elements.filter(
+      (entry) =>
+        ts.isCallExpression(unwrap(entry)) &&
+        unwrap(entry).expression.getText(file) === factory
+    )
+    if (matches.length > 1)
+      throw new Error(
+        'Versioning is configured more than once. Remove the duplicate plugin before retrying.'
+      )
+    if (matches.length === 1) return source
+  }
+  const newline = source.includes('\r\n') ? '\r\n' : '\n'
+  const edits = []
+  if (!factory) {
+    const identifiers = new Set()
+    function visit(node) {
+      if (ts.isIdentifier(node)) identifiers.add(node.text)
+      ts.forEachChild(node, visit)
+    }
+    visit(file)
+    factory = 'versioning'
+    let suffix = 1
+    while (identifiers.has(factory)) factory = `rdxVersioning${suffix++}`
+    const specifier =
+      factory === 'versioning' ? 'versioning' : `versioning as ${factory}`
+    let position = imports.length
+      ? imports.at(-1).end
+      : file.statements[0].getStart(file)
+    if (!imports.length) {
+      for (const statement of file.statements) {
+        if (
+          !ts.isExpressionStatement(statement) ||
+          !ts.isStringLiteral(statement.expression)
+        )
+          break
+        position = statement.end
+      }
+    }
+    edits.push({
+      position,
+      text: `${newline}import { ${specifier} } from '${versioningPackage}'${newline}`,
+    })
+  }
+  if (plugins) {
+    const position = plugins.elements.length
+      ? plugins.elements.at(-1).end
+      : plugins.getStart(file) + 1
+    edits.push({
+      position,
+      text: `${plugins.elements.length ? ',' : ''} ${factory}()`,
+    })
+  } else {
+    if (properties.length && !properties.hasTrailingComma)
+      edits.push({ position: properties.at(-1).end, text: ',' })
+    edits.push({
+      position: config.end - 1,
+      text: `${newline}  plugins: [${factory}()],${newline}`,
+    })
+  }
+  for (const edit of edits.sort((a, b) => b.position - a.position))
+    source =
+      source.slice(0, edit.position) + edit.text + source.slice(edit.position)
+  return source
+}

package/bin/rdx.mjs

@@ -13,7 +13,7 @@ import { createJiti } from 'jiti'
 import { preparePublicAssets } from './public-assets.mjs'
 
 const supportedCommands = new Set(['dev', 'build', 'start'])
-const command = process.argv[2]
+let command = process.argv[2]
 const commandArgs = process.argv.slice(3)
 const projectRoot = process.cwd()
 const packageRoot = path.resolve(
@@ -31,13 +31,22 @@ async function prepareRuntime() {
 
 async function main() {
   if (!command || command === 'help' || command === '--help') {
-    console.log('Usage: rdx <dev|build|start|prepare|plugin-command>')
+    console.log('Usage: rdx <dev|build|start|prepare|add|plugin-command>')
+    console.log('  rdx add versioning [--package-manager npm|pnpm|yarn]')
     console.log(
       'Plugin commands are registered through plugins in rdx.config.ts.'
     )
     return
   }
 
+  if (command === 'add') {
+    const { addVersioning, parseAddArguments } =
+      await import('./add-plugin.mjs')
+    const options = parseAddArguments(commandArgs)
+    await addVersioning(projectRoot, options)
+    command = 'prepare'
+  }
+
   const configPath = path.join(projectRoot, 'rdx.config.ts')
   try {
     await access(configPath)
@@ -78,7 +87,7 @@ async function main() {
     )
     if (!pluginCommand)
       throw new Error(
-        `Unknown command "${command}". Available: dev, build, start, prepare${project.commands.map((entry) => `, ${entry.name}`).join('')}. Install and configure the plugin that provides this command.`
+        `Unknown command "${command}". Available: dev, build, start, prepare, add${project.commands.map((entry) => `, ${entry.name}`).join('')}. Install and configure the plugin that provides this command.`
       )
     await pluginCommand.run({
       rootDir: projectRoot,

package/config.d.mts

@@ -0,0 +1,5 @@
+/** Explicit deployment files for a native Next.js application using RDX. */
+export function getRdxTracingConfig(options: {
+  rootDir: string
+  appDir?: string
+}): Promise<{ outputFileTracingIncludes: Record<string, string[]> }>

package/config.mjs

@@ -0,0 +1,80 @@
+import { readdir, stat } from 'node:fs/promises'
+import path from 'node:path'
+
+import { createRdxProject, resolveProjectPath } from '@lexibase/rdx-core/config'
+import { createJiti } from 'jiti'
+
+// These files are enumerated by Next's configuration loader, not by a server
+// bundle. The core's dynamic readers deliberately leave tracing to this adapter.
+async function contentFiles(directory) {
+  let entries
+  try {
+    entries = await readdir(directory, { withFileTypes: true })
+  } catch (error) {
+    if (error.code === 'ENOENT') return []
+    throw error
+  }
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const filename = path.join(directory, entry.name)
+      if (entry.isDirectory()) return contentFiles(filename)
+      return entry.isFile() &&
+        (entry.name.endsWith('.mdx') || entry.name === '_category.json')
+        ? [filename]
+        : []
+    })
+  )
+  return files.flat()
+}
+
+// outputFileTracingIncludes takes globs. Escape configured names so a literal
+// bracket, wildcard or parenthesis cannot silently widen the deployment trace.
+function literalPattern(filename) {
+  return filename
+    .split(path.sep)
+    .join('/')
+    .replace(/([*?[\]{}()!+@])/g, '\\$1')
+}
+
+/** Next.js tracing for configured RDX content, independent of plugin names. */
+export async function getRdxTracingConfig({ rootDir, appDir = rootDir }) {
+  rootDir = path.resolve(rootDir)
+  appDir = path.resolve(appDir)
+  const jiti = createJiti(import.meta.url, {
+    moduleCache: false,
+    fsCache: false,
+    jsx: { runtime: 'automatic' },
+  })
+  const input = await jiti.import(path.join(rootDir, 'rdx.config.ts'), {
+    default: true,
+  })
+  const project = await createRdxProject(input, { rootDir })
+  const files = (
+    await Promise.all(
+      project.sources.map((source) =>
+        contentFiles(
+          resolveProjectPath(rootDir, source.docsDir, 'content source docsDir')
+        )
+      )
+    )
+  ).flat()
+  for (const filename of project.runtimeFiles) {
+    const resolved = resolveProjectPath(
+      rootDir,
+      filename,
+      'plugin runtimeFiles'
+    )
+    if (!(await stat(resolved)).isFile())
+      throw new Error(`Plugin runtimeFiles must name a file: ${filename}`)
+    files.push(resolved)
+  }
+  return {
+    outputFileTracingIncludes: {
+      '/*': [
+        ...new Set(
+          files.map((file) => literalPattern(path.relative(appDir, file)))
+        ),
+      ].sort(),
+    },
+  }
+}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { defineConfig } from '@lexibase/rdx-core/config';
-export { RdxConfig, RdxHomepage, RdxPlugin, RdxPluginContext, RdxRuntimeConfig } from '@lexibase/rdx-types';
+export { RDXConfig, RdxHomepage, RdxMetadata, RdxPlugin, RdxPluginContext, RdxRuntimeConfig } from '@lexibase/rdx-types';

package/dist/runtime/index.d.ts

@@ -1,19 +1,28 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { ReactNode } from 'react';
-import { RdxProject, RdxRuntimeConfig } from '@lexibase/rdx-types';
+import { RdxProject, RDXConfig } from '@lexibase/rdx-types';
 export { createRdxProject, getProjectDocsPaths } from '@lexibase/rdx-core';
+import { Metadata } from 'next';
+
+declare function getSearchSources(project: RdxProject): {
+    source: string;
+}[];
+declare function getSearchResponse(project: RdxProject, key: string): Response;
+
+/** Translate the shared configuration through Next's native Metadata API. */
+declare function getRdxMetadata(config: RDXConfig): Metadata;
 
 declare function RdxLayout({ children, config, bodyClassName, }: {
     children: ReactNode;
-    config: RdxRuntimeConfig;
+    config: RDXConfig;
     bodyClassName?: string;
-}): react_jsx_runtime.JSX.Element;
+}): react.JSX.Element;
 declare function HomePage({ project }: {
     project: RdxProject;
-}): react_jsx_runtime.JSX.Element;
+}): react.JSX.Element;
 declare function DocsPage({ slug, project, }: {
     slug?: string[];
     project: RdxProject;
-}): Promise<react_jsx_runtime.JSX.Element>;
+}): Promise<react.JSX.Element>;
 
-export { DocsPage, HomePage, RdxLayout };
+export { DocsPage, HomePage, RdxLayout, getRdxMetadata, getSearchResponse, getSearchSources };

package/dist/runtime/index.js

@@ -1,12 +1,15 @@
 // src/runtime/index.tsx
 import {
-  getDocument,
+  getDocument as getDocument2,
   getDocsPaths,
-  getSourceOptions,
+  getSourceOptions as getSourceOptions2,
   resolveDocsRoute
 } from "@lexibase/rdx-core";
 import { Button } from "@lexibase/rdx-ui/components/button";
+import { ButtonLink } from "@lexibase/rdx-ui/components/button-link";
 import { DocsSidebar } from "@lexibase/rdx-ui/components/docs-sidebar";
+import { DocsToc } from "@lexibase/rdx-ui/components/docs-toc";
+import { DocsSearch } from "@lexibase/rdx-ui/components/docs-search";
 import { Home } from "@lexibase/rdx-ui/components/home";
 import { Logo } from "@lexibase/rdx-ui/components/logo";
 import { mdxComponents } from "@lexibase/rdx-ui/components/mdx-components";
@@ -15,10 +18,90 @@ import {
   VersionDropdown
 } from "@lexibase/rdx-ui/components/version-dropdown";
 import { ThemeProvider } from "@lexibase/rdx-ui/providers/theme-provider";
-import { compileMDX } from "next-mdx-remote/rsc";
-import Link from "next/link";
 import { notFound, redirect } from "next/navigation";
+
+// src/runtime/mdx.ts
+import { compileMDX } from "next-mdx-remote/rsc";
+import remarkGfm from "remark-gfm";
+import {
+  remarkDocumentLinks,
+  rehypeDocumentationHeadings,
+  rehypeDocumentationCode
+} from "@lexibase/rdx-core/mdx";
+function compileDocumentation(source, components, links) {
+  return compileMDX({
+    source,
+    components,
+    options: {
+      blockJS: true,
+      blockDangerousJS: true,
+      mdxOptions: {
+        remarkPlugins: [remarkGfm, [remarkDocumentLinks, links]],
+        rehypePlugins: [rehypeDocumentationHeadings, rehypeDocumentationCode]
+      }
+    }
+  });
+}
+
+// src/runtime/index.tsx
 import { createRdxProject, getProjectDocsPaths } from "@lexibase/rdx-core";
+
+// src/runtime/search.ts
+import { getDocsIndex, getDocument, getSourceOptions } from "@lexibase/rdx-core";
+import { buildSearchIndex } from "@lexibase/rdx-core/search";
+function getSearchSources(project) {
+  return project.config.search ? project.sources.map((source) => ({ source: source.routePrefix || "_" })) : [];
+}
+function getSearchResponse(project, key) {
+  if (!project.config.search) return new Response(null, { status: 404 });
+  const source = project.sources.find(
+    (entry) => (entry.routePrefix || "_") === key
+  );
+  if (!source) return new Response(null, { status: 404 });
+  const options = getSourceOptions(project, source);
+  const documents = getDocsIndex(options).flatMap(
+    (category) => category.pages.map((page) => ({
+      title: page.title,
+      description: page.description,
+      category: category.title,
+      href: [
+        "/docs",
+        source.routePrefix,
+        page.slug.split("/").map(encodeURIComponent).join("/")
+      ].filter(Boolean).join("/"),
+      content: getDocument(page.slug, options)?.content ?? ""
+    }))
+  );
+  return Response.json(buildSearchIndex(documents));
+}
+
+// src/runtime/metadata.ts
+function getRdxMetadata(config) {
+  const { metadataBase, ...metadata } = config.metadata;
+  const name = metadata.applicationName;
+  return {
+    title: { default: name, template: `%s | ${name}` },
+    description: config.description,
+    ...metadata,
+    ...metadataBase ? { metadataBase: new URL(metadataBase) } : {},
+    ...metadata.openGraph ? {
+      openGraph: {
+        title: name,
+        description: config.description,
+        ...metadata.openGraph
+      }
+    } : {},
+    ...metadata.twitter ? {
+      twitter: {
+        title: name,
+        description: config.description,
+        ...metadata.twitter
+      }
+    } : {}
+  };
+}
+
+// src/runtime/index.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 function RdxLayout({
   children,
@@ -46,8 +129,8 @@ function RdxHeader({
   const { config } = project;
   const { source, slug: currentSlug } = resolveDocsRoute(project, slug);
   const options = project.sources.map((edition) => {
-    const docs = getSourceOptions(project, edition);
-    const destination = currentSlug && getDocument(currentSlug, docs) ? currentSlug : getDocsPaths(docs)[0];
+    const docs = getSourceOptions2(project, edition);
+    const destination = currentSlug && getDocument2(currentSlug, docs) ? currentSlug : getDocsPaths(docs)[0];
     return {
       id: edition.id,
       label: edition.id === "current" ? "Current" : `Version ${edition.label}`,
@@ -60,7 +143,14 @@ function RdxHeader({
     Navbar,
     {
       title: config.navbar?.title ?? "",
-      siteTitle: config.title,
+      search: config.search ? /* @__PURE__ */ jsx(
+        DocsSearch,
+        {
+          indexUrl: `/rdx-search/${encodeURIComponent(source.routePrefix || "_")}`,
+          version: source.label
+        }
+      ) : void 0,
+      siteTitle: config.metadata.applicationName,
       logo: /* @__PURE__ */ jsx(BrandLogo, { className: "size-5" }),
       homeHref: config.homepage?.enabled ? "/" : "/docs",
       docsHref: ["/docs", source.routePrefix].filter(Boolean).join("/"),
@@ -87,7 +177,7 @@ function HomePage({ project }) {
         children: CustomHome ? /* @__PURE__ */ jsx(CustomHome, {}) : /* @__PURE__ */ jsx(
           Home,
           {
-            title: homepage.title ?? config.title,
+            title: homepage.title ?? config.metadata.applicationName,
             logo: /* @__PURE__ */ jsx(BrandLogo, { className: "size-52 hover:scale-105 hover:rotate-1 transition-[scale,rotation] duration-1000" }),
             description: homepage.description,
             buttons: homepage.buttons
@@ -116,10 +206,16 @@ async function DocsPage({
       ] })
     ] });
   if (!document) notFound();
-  const { content } = await compileMDX({
-    source: document.content,
-    components: mdxComponents
-  });
+  const { content } = await compileDocumentation(
+    document.content,
+    mdxComponents,
+    {
+      sourceRoot: getSourceOptions2(project, source).docsDir,
+      sourcePath: document.sourcePath,
+      routePrefix: source.routePrefix,
+      documents: categories.flatMap((category2) => category2.pages)
+    }
+  );
   const title = typeof document.frontmatter.title === "string" ? document.frontmatter.title : currentSlug;
   const description = typeof document.frontmatter.description === "string" ? document.frontmatter.description : null;
   const hrefFor = (pageSlug) => ["/docs", source.routePrefix, pageSlug].filter(Boolean).join("/");
@@ -147,37 +243,69 @@ async function DocsPage({
           pathname: hrefFor(currentSlug)
         }
       ),
-      /* @__PURE__ */ jsx("div", { className: "flex-1 h-full overflow-y-auto pt-12 md:pt-0 outline-none", children: /* @__PURE__ */ jsxs("section", { className: "w-full min-h-full px-7 flex flex-col gap-5 pb-8 md:py-8", children: [
-        /* @__PURE__ */ jsxs("div", { className: "w-full flex flex-col gap-5 md:mx-auto md:max-w-[860px] pt-14 md:pt-0 flex-1", children: [
-          /* @__PURE__ */ jsxs("header", { className: "mb-6", children: [
-            source.badge && /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground mb-4", children: source.badge }),
-            /* @__PURE__ */ jsx("span", { className: "text-xs text-zinc-600 font-semibold uppercase block -mb-0.5", children: category?.title }),
-            /* @__PURE__ */ jsx("h1", { className: "text-4xl uppercase font-bold mb-2", children: title }),
-            description && /* @__PURE__ */ jsx("p", { className: "text-sm text-ring max-w-[726px]", children: description })
-          ] }),
-          /* @__PURE__ */ jsx(
-            "main",
-            {
-              id: "rdx-main",
-              tabIndex: -1,
-              className: "h-full w-full flex-1 max-w-[960px]",
-              children: content
-            }
-          )
-        ] }),
-        /* @__PURE__ */ jsxs("footer", { className: "flex flex-col", children: [
-          /* @__PURE__ */ jsxs("section", { className: "flex items-center justify-between", children: [
-            previous ? /* @__PURE__ */ jsx(Button, { variant: "outline", size: "sm", asChild: true, children: /* @__PURE__ */ jsx(Link, { href: hrefFor(previous.slug), children: previous.title }) }) : /* @__PURE__ */ jsx(Button, { variant: "outline", size: "sm", disabled: true, children: "Previous" }),
-            next ? /* @__PURE__ */ jsx(Button, { variant: "outline", size: "sm", asChild: true, children: /* @__PURE__ */ jsx(Link, { href: hrefFor(next.slug), children: next.title }) }) : /* @__PURE__ */ jsx(Button, { variant: "outline", size: "sm", disabled: true, children: "Next" })
-          ] }),
-          /* @__PURE__ */ jsx("section", { className: "flex items-center justify-center w-full py-5", children: /* @__PURE__ */ jsxs("p", { className: "text-sm text-muted-foreground", children: [
-            "\xA9 ",
-            (/* @__PURE__ */ new Date()).getFullYear(),
-            " ",
-            /* @__PURE__ */ jsx("strong", { children: project.config.title })
-          ] }) })
-        ] })
-      ] }) })
+      /* @__PURE__ */ jsxs(
+        "div",
+        {
+          "data-rdx-docs-scroll": true,
+          className: "relative flex-1 min-w-0 h-full overflow-y-auto pt-12 md:pt-0 outline-none",
+          children: [
+            project.config.TOC && /* @__PURE__ */ jsx(DocsToc, {}, hrefFor(currentSlug)),
+            /* @__PURE__ */ jsxs(
+              "section",
+              {
+                className: `w-full min-h-full px-7 flex flex-col gap-5 pb-8 md:py-8 ${project.config.TOC ? "xl:pr-20" : ""}`,
+                children: [
+                  /* @__PURE__ */ jsxs("div", { className: "w-full flex flex-col gap-5 md:mx-auto md:max-w-[860px] pt-14 md:pt-0 flex-1", children: [
+                    /* @__PURE__ */ jsxs("header", { className: "mb-6", children: [
+                      source.badge && /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground mb-4", children: source.badge }),
+                      /* @__PURE__ */ jsx("span", { className: "text-xs text-zinc-600 font-semibold uppercase block -mb-0.5", children: category?.title }),
+                      /* @__PURE__ */ jsx("h1", { className: "text-4xl uppercase font-bold mb-2", children: title }),
+                      description && /* @__PURE__ */ jsx("p", { className: "text-sm text-ring max-w-[726px]", children: description })
+                    ] }),
+                    /* @__PURE__ */ jsx(
+                      "main",
+                      {
+                        id: "rdx-main",
+                        tabIndex: -1,
+                        className: "h-full w-full flex-1 max-w-[960px]",
+                        children: content
+                      }
+                    )
+                  ] }),
+                  /* @__PURE__ */ jsxs("footer", { className: "flex flex-col", children: [
+                    /* @__PURE__ */ jsxs("section", { className: "flex items-center justify-between", children: [
+                      previous ? /* @__PURE__ */ jsx(
+                        ButtonLink,
+                        {
+                          variant: "outline",
+                          size: "sm",
+                          href: hrefFor(previous.slug),
+                          children: previous.title
+                        }
+                      ) : /* @__PURE__ */ jsx(Button, { variant: "outline", size: "sm", disabled: true, children: "Previous" }),
+                      next ? /* @__PURE__ */ jsx(
+                        ButtonLink,
+                        {
+                          variant: "outline",
+                          size: "sm",
+                          href: hrefFor(next.slug),
+                          children: next.title
+                        }
+                      ) : /* @__PURE__ */ jsx(Button, { variant: "outline", size: "sm", disabled: true, children: "Next" })
+                    ] }),
+                    /* @__PURE__ */ jsx("section", { className: "flex items-center justify-center w-full py-5", children: /* @__PURE__ */ jsxs("p", { className: "text-sm text-muted-foreground", children: [
+                      "\xA9 ",
+                      (/* @__PURE__ */ new Date()).getFullYear(),
+                      " ",
+                      /* @__PURE__ */ jsx("strong", { children: project.config.metadata.applicationName })
+                    ] }) })
+                  ] })
+                ]
+              }
+            )
+          ]
+        }
+      )
     ] })
   ] });
 }
@@ -186,5 +314,8 @@ export {
   HomePage,
   RdxLayout,
   createRdxProject,
-  getProjectDocsPaths
+  getProjectDocsPaths,
+  getRdxMetadata,
+  getSearchResponse,
+  getSearchSources
 };

package/package.json

@@ -1,15 +1,25 @@
 {
   "name": "@lexibase/rdx-next",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0",
   "description": "The Next.js runtime for RDX documentation projects.",
   "license": "MIT",
   "type": "module",
+  "engines": {
+    "node": "^22.18.0 || ^24.11.0"
+  },
   "bin": {
     "rdx": "./bin/rdx.mjs"
   },
   "exports": {
+    "./config": {
+      "types": "./config.d.mts",
+      "import": "./config.mjs"
+    },
     "./postcss.config": "./postcss.config.mjs",
-    "./styles.css": "./src/runtime/styles.css",
+    "./styles.css": {
+      "types": "./src/runtime/styles.d.css.ts",
+      "default": "./src/runtime/styles.css"
+    },
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
@@ -20,24 +30,30 @@
     }
   },
   "files": [
+    "config.mjs",
+    "config.d.mts",
     "bin",
     "dist",
     "templates",
     "postcss.config.mjs",
     "src/runtime/styles.css",
+    "src/runtime/styles.d.css.ts",
     "README.md"
   ],
   "dependencies": {
+    "cross-spawn": "^7.0.6",
     "jiti": "^2.6.1",
-    "next-mdx-remote": "^5.0.0",
-    "@lexibase/rdx-ui": "1.0.0-beta.1",
-    "@lexibase/rdx-types": "1.0.0-beta.4",
-    "@lexibase/rdx-core": "1.0.0-beta.5"
+    "next-mdx-remote": "^6.0.0",
+    "remark-gfm": "^4",
+    "typescript": "6.0.3",
+    "@lexibase/rdx-core": "1.0.0",
+    "@lexibase/rdx-ui": "1.0.0",
+    "@lexibase/rdx-types": "1.0.0"
   },
   "peerDependencies": {
-    "next": "^15.5.0",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0"
+    "next": "^16.4.2",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
   },
   "publishConfig": {
     "access": "public"
@@ -53,17 +69,17 @@
   "homepage": "https://github.com/lexibase/rdx#readme",
   "devDependencies": {
     "@types/node": "^22.15.3",
-    "@types/react": "19.1.0",
-    "@types/react-dom": "19.1.1",
-    "eslint": "^9.34.0",
-    "next": "^15.5.0",
-    "react": "19.1.0",
-    "react-dom": "19.1.0",
-    "typescript": "5.9.2",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "eslint": "^9.39.5",
+    "next": "^16.4.2",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
     "@rdx/typescript-config": "1.0.0",
     "@rdx/eslint-config": "1.0.0"
   },
   "scripts": {
+    "dev": "tsup src/index.ts src/runtime/index.tsx --format esm --dts --watch --external @lexibase/rdx-core --external @lexibase/rdx-types --external next --external react --external react-dom --external next-mdx-remote",
     "build": "tsup src/index.ts src/runtime/index.tsx --format esm --dts --clean --external @lexibase/rdx-core --external @lexibase/rdx-types --external next --external react --external react-dom --external next-mdx-remote",
     "lint": "eslint . --max-warnings 0",
     "check-types": "tsc --noEmit",

package/src/runtime/styles.d.css.ts

@@ -0,0 +1,2 @@
+// Global runtime styles are loaded for their side effects only.
+export {}

package/templates/runtime/app/globals.d.css.ts

@@ -0,0 +1,2 @@
+// Next.js loads this global stylesheet for its side effects only.
+export {}

package/templates/runtime/app/layout.tsx

@@ -1,6 +1,6 @@
 import type { Metadata } from 'next'
 
-import { RdxLayout } from '@lexibase/rdx-next/runtime'
+import { getRdxMetadata, RdxLayout } from '@lexibase/rdx-next/runtime'
 
 import { getProject } from '../rdx-project'
 
@@ -8,10 +8,7 @@ import './globals.css'
 
 export async function generateMetadata(): Promise<Metadata> {
   const { config } = await getProject()
-  return {
-    title: { default: config.title, template: `%s | ${config.title}` },
-    description: config.description,
-  }
+  return getRdxMetadata(config)
 }
 
 export default async function RootLayout({

package/templates/runtime/app/rdx-search/[source]/route.ts

@@ -0,0 +1,16 @@
+import { getSearchResponse, getSearchSources } from '@lexibase/rdx-next/runtime'
+import { getProject } from '../../../rdx-project'
+
+export const dynamic = 'force-static'
+export const dynamicParams = false
+
+export async function generateStaticParams() {
+  return getSearchSources(await getProject())
+}
+
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ source: string }> }
+) {
+  return getSearchResponse(await getProject(), (await params).source)
+}

package/templates/runtime/next.config.mjs

@@ -1,7 +1,17 @@
+import { fileURLToPath } from 'node:url'
+
+import { getRdxTracingConfig } from '@lexibase/rdx-next/config'
+
+const rootDir = fileURLToPath(new URL('..', import.meta.url))
+const appDir = fileURLToPath(new URL('.', import.meta.url))
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
-  experimental: {
-    externalDir: true,
+  ...(await getRdxTracingConfig({ rootDir, appDir })),
+  outputFileTracingRoot: rootDir,
+  agentRules: false,
+  turbopack: {
+    root: fileURLToPath(new URL('..', import.meta.url)),
   },
   transpilePackages: [
     '@lexibase/rdx-core',

package/templates/runtime/rdx-project.ts

@@ -1,7 +1,13 @@
+import path from 'node:path'
+
 import { createRdxProject } from '@lexibase/rdx-next/runtime'
 
 import config from '../rdx.config'
 
 export function getProject() {
-  return createRdxProject(config)
+  // The CLI starts at the project root; serverless Next workers start in .rdx.
+  // Keep project-owned content outside the generated application in both cases.
+  const cwd = process.cwd()
+  const rootDir = path.basename(cwd) === '.rdx' ? path.dirname(cwd) : cwd
+  return createRdxProject(config, { rootDir })
 }

package/templates/runtime/tsconfig.json

@@ -1,10 +1,14 @@
 {
   "compilerOptions": {
+    "rootDir": "..",
+    "types": ["node", "react"],
+    "allowArbitraryExtensions": true,
+    "noUncheckedSideEffectImports": true,
     "allowJs": true,
     "esModuleInterop": true,
     "incremental": true,
     "isolatedModules": true,
-    "jsx": "preserve",
+    "jsx": "react-jsx",
     "lib": ["dom", "dom.iterable", "esnext"],
     "module": "esnext",
     "moduleResolution": "bundler",
@@ -15,6 +19,12 @@
     "strict": true,
     "target": "esnext"
   },
-  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
   "exclude": ["node_modules", "public"]
 }