@lexibase/rdx-next 1.0.0-beta.9 → 1.0.1

package/README.md

@@ -2,20 +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,
-creates a config backup when changing it, validates the result and prepares
+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.
 
@@ -27,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

@@ -11,6 +11,44 @@ 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
@@ -83,12 +121,17 @@ export async function detectPackageManager(
   return declared ?? locks[0] ?? (managers.has(agent) ? agent : 'npm')
 }
 
-export function installPackage(manager, rootDir, env = process.env) {
+export function installPackage(
+  manager,
+  rootDir,
+  env = process.env,
+  request = versioningInstallRequest(runtimeVersion)
+) {
   return new Promise((resolve, reject) => {
-    const args = [
-      manager === 'npm' ? 'install' : 'add',
-      `${versioningPackage}@beta`,
-    ]
+    const args =
+      request.kind === 'restore'
+        ? ['install']
+        : [manager === 'npm' ? 'install' : 'add', request.specifier]
     const nodeEntry =
       env.npm_config_user_agent?.startsWith(`${manager}/`) &&
       env.npm_execpath &&
@@ -191,13 +234,17 @@ export async function addVersioning(rootDir, options = {}) {
       throw error
   }
   if (!declared || !installed) {
-    log(`Installing ${versioningPackage}@beta with ${manager}...`)
-    await install(manager, rootDir, env)
+    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`)
-  let backup
   try {
     await writeFile(temporary, updated, { flag: 'wx', mode: info.mode })
     try {
@@ -217,12 +264,8 @@ export async function addVersioning(rootDir, options = {}) {
         'rdx.config.ts was replaced during installation. No configuration was overwritten.'
       )
     if (updated !== original) {
-      backup = path.join(rootDir, `rdx.config.ts.${randomUUID()}.bak`)
-      await writeFile(backup, original, { flag: 'wx', mode: info.mode })
       await rename(temporary, filename)
-      log(
-        `Versioning activated. Original configuration saved to ${path.basename(backup)}.`
-      )
+      log('Versioning activated in rdx.config.ts.')
     } else
       log('Versioning is already configured; no configuration changes needed.')
   } finally {
@@ -230,5 +273,5 @@ export async function addVersioning(rootDir, options = {}) {
       if (error.code !== 'ENOENT') throw error
     })
   }
-  return { backup, changed: updated !== original }
+  return { changed: updated !== original }
 }

package/bin/rdx.mjs

@@ -40,9 +40,8 @@ async function main() {
   }
 
   if (command === 'add') {
-    const { addVersioning, parseAddArguments } = await import(
-      './add-plugin.mjs'
-    )
+    const { addVersioning, parseAddArguments } =
+      await import('./add-plugin.mjs')
     const options = parseAddArguments(commandArgs)
     await addVersioning(projectRoot, options)
     command = 'prepare'

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,33 @@
-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;
+
+/** Read metadata from the same content source and index used by the page. */
+declare function getDocumentMetadata({ project, slug, }: {
+    project: RdxProject;
+    slug?: string[];
+}): Metadata;
+/** 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, getDocumentMetadata, getRdxMetadata, getSearchResponse, getSearchSources };

package/dist/runtime/index.js

@@ -1,12 +1,15 @@
 // src/runtime/index.tsx
 import {
-  getDocument,
+  getDocument as getDocument2,
   getDocsPaths,
-  getSourceOptions,
-  resolveDocsRoute
+  getSourceOptions as getSourceOptions2,
+  resolveDocsRoute as resolveDocsRoute2
 } 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,105 @@ import {
   VersionDropdown
 } from "@lexibase/rdx-ui/components/version-dropdown";
 import { ThemeProvider } from "@lexibase/rdx-ui/providers/theme-provider";
+import { notFound as notFound2, redirect } from "next/navigation";
+
+// src/runtime/mdx.ts
 import { compileMDX } from "next-mdx-remote/rsc";
-import Link from "next/link";
-import { notFound, redirect } from "next/navigation";
+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
+import { resolveDocsRoute } from "@lexibase/rdx-core";
+import { notFound } from "next/navigation";
+function getDocumentMetadata({
+  project,
+  slug
+}) {
+  const route = resolveDocsRoute(project, slug);
+  if (!route.slug) return {};
+  if (!route.document) notFound();
+  const page = route.categories.flatMap((category) => category.pages).find((page2) => page2.slug === route.slug);
+  return {
+    title: page.title,
+    description: page.description || project.config.description
+  };
+}
+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,
@@ -44,10 +142,10 @@ function RdxHeader({
   slug
 }) {
   const { config } = project;
-  const { source, slug: currentSlug } = resolveDocsRoute(project, slug);
+  const { source, slug: currentSlug } = resolveDocsRoute2(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 +158,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 +192,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
@@ -106,7 +211,7 @@ async function DocsPage({
     slug: currentSlug,
     document,
     categories
-  } = resolveDocsRoute(project, slug);
+  } = resolveDocsRoute2(project, slug);
   if (!currentSlug)
     return /* @__PURE__ */ jsxs(Fragment, { children: [
       /* @__PURE__ */ jsx(RdxHeader, { project, slug }),
@@ -115,11 +220,17 @@ async function DocsPage({
         /* @__PURE__ */ jsx("p", { children: "Add an .mdx file inside your configured documentation directory." })
       ] })
     ] });
-  if (!document) notFound();
-  const { content } = await compileMDX({
-    source: document.content,
-    components: mdxComponents
-  });
+  if (!document) notFound2();
+  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 +258,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 +329,9 @@ export {
   HomePage,
   RdxLayout,
   createRdxProject,
-  getProjectDocsPaths
+  getDocumentMetadata,
+  getProjectDocsPaths,
+  getRdxMetadata,
+  getSearchResponse,
+  getSearchSources
 };

package/package.json

@@ -1,15 +1,25 @@
 {
   "name": "@lexibase/rdx-next",
-  "version": "1.0.0-beta.9",
+  "version": "1.0.1",
   "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,26 +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",
-    "typescript": "5.9.2",
     "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.6"
+    "next-mdx-remote": "^6.0.0",
+    "remark-gfm": "^4",
+    "typescript": "6.0.3",
+    "@lexibase/rdx-types": "1.0.0",
+    "@lexibase/rdx-core": "1.0.0",
+    "@lexibase/rdx-ui": "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"
@@ -55,16 +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",
-    "@rdx/eslint-config": "1.0.0",
-    "@rdx/typescript-config": "1.0.0"
+    "@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/docs/[[...slug]]/page.tsx

@@ -1,7 +1,21 @@
-import { DocsPage, getProjectDocsPaths } from '@lexibase/rdx-next/runtime'
+import type { Metadata } from 'next'
+import {
+  DocsPage,
+  getDocumentMetadata,
+  getProjectDocsPaths,
+} from '@lexibase/rdx-next/runtime'
 
 import { getProject } from '../../../rdx-project'
 
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug?: string[] }>
+}): Promise<Metadata> {
+  const { slug } = await params
+  return getDocumentMetadata({ project: await getProject(), slug })
+}
+
 export async function generateStaticParams() {
   return getProjectDocsPaths(await getProject()).map((slug) => ({
     slug: slug.split('/'),

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"]
 }