Nextra v4 Integrated at /docs Route

Date: 2026-03-11 Status: accepted

Context

LuckyPlans needs a public documentation site for architecture, developer guides, API reference, and infrastructure deep-dives. Options were:

  1. Separate deployment (subdomain docs.luckyplans.xyz) with its own Next.js app
  2. nextra-theme-docs as a standalone Next.js app
  3. Nextra v4 core integrated as a route within the existing apps/web Next.js app

A separate subdomain is not viable — all services run on a single node behind one IP. A second Docker image would add deployment complexity with no benefit.

Decision

Integrated Nextra v4 (without nextra-theme-docs) at the /docs route inside apps/web. A custom sidebar and layout are built using the existing Tailwind CSS classes to match the landing page’s design system.

nextra-theme-docs is explicitly excluded because it ships its own CSS bundle that conflicts with the HeroUI @heroui/styles/css global stylesheet and Tailwind v4’s @import 'tailwindcss' baseline loaded in apps/web/src/styles/globals.css.

The key configuration: withNextra({ contentDirBasePath: '/docs' }) in next.config.ts scopes all MDX processing to the /docs URL prefix. All documentation source lives in apps/web/content/ — a single source of truth, no separate docs/ directory.

Consequences

  • Easier: Single deployment — no separate app, no subdomain routing, no second Docker image.
  • Easier: Docs and landing page share the same Tailwind design tokens, font, and component library.
  • Easier: Content lives in apps/web/content/ alongside the app — one repo, one CI pipeline, no duplication.
  • Easier: ADRs are published at /docs/architecture/decisions/ — fully public and accessible.
  • Harder: Custom layout requires maintaining DocsSidebar, DocsNavbar, and mdx-components — no free theme updates from nextra-theme-docs.