Apps v4 site routing and content
Overview
The v4 site is a Next.js App Router app under apps/v4/app/**, with the shared root shell in apps/…/layout.tsx. The root layout imports the global CSS files, sets site-wide metadata from siteConfig, advertises /rss.xml, injects scripts for docs-sidebar scroll restoration and theme-color switching, and wraps all routes in theme, active-theme, query-state, tooltip, toast, Tailwind indicator, and analytics providers. The public marketing/docs shell is the route group apps/…/layout.tsx, which adds SiteHeader, a flexing <main>, and SiteFooter; routes in apps/v4/app/(view)/** intentionally sit outside that shell for iframe/preview rendering.
Documentation content is sourced by Fumadocs. apps/…/source.config.ts defines the MDX pipeline and docs = defineDocs({ dir: "content/docs" }), so apps/v4/content/docs/** is the file-backed source for docs pages. The config replaces the default highlighter with rehype-pretty-code, using the vesper dark theme, github-light-default light theme, and local code transformers. The generated @/.source/server output is loaded in apps/…/source.ts with baseUrl: "/docs", and every route that needs docs data imports that source object.
The main docs route is apps/…/page.tsx. It is fully static (dynamic = "force-static", revalidate = false, dynamicParams = false) and generates paths from source.generateParams(). At request/build time it resolves the slug with source.getPage(params.slug), 404s missing pages or pages without both title and description, emits page metadata and OG/Twitter images through /og, then renders page.data.body with the MDX component map from apps/…/mdx-components.tsx. The docs page also reads raw MDX text through page.data.getText("raw"), runs replaceComponentsList, and passes that to DocsCopyPage; navigation comes from findNeighbour(source.pageTree, page.url), while component and AI-element pages with components|ai-elements/<base>/<component> slugs show DocsBaseSwitcher. apps/…/layout.tsx wraps docs content in a sidebar provider and feeds source.pageTree to DocsSidebar.
apps/…/mdx-components.tsx is the rendering contract between MDX files in apps/v4/content/docs/** and the app UI. It supplies anchored heading renderers that derive deterministic IDs from child text when the MDX compiler did not provide one, wraps wide tables in a horizontal scroller, chooses a collapsible or native <pre> based on data-collapsible, adds copy buttons or package-manager command tabs to code blocks based on injected __raw__, __src__, __npm__, __yarn__, __pnpm__, and __bun__ props, and exposes custom MDX tags such as Callout, CodeTabs, ComponentPreview, ComponentSource, DirectoryList, LinkedCard, and ComponentsList. ComponentsList reads source.pageTree and renders only the components folder, defaulting that docs index to the base component family.
The content tree itself is organized with meta.json files. apps/…/meta.json marks the docs root and orders top-level folders such as components, ai-elements, (root), changelog, installation, and registry. Nested meta.json files like apps/…/meta.json and apps/…/meta.json supply sidebar titles, explicit page ordering, external/internal links, hidden entries, or "..." expansion. Individual MDX files carry frontmatter used by the page route, for example apps/…/index.mdx provides title and description, and component pages such as apps/…/button.mdx also set fields like featured, base, and component while invoking custom MDX tags.
The changelog has a specialized aggregate view at apps/…/page.tsx. It still uses the docs shell but bypasses the generic slug page, calls getChangelogPages() from apps/…/changelog.ts, renders the latest five changelog MDX bodies inline with mdxComponents, and links older entries. getChangelogPages() filters source.getPages() to changelog/*, reads each backing file under content/…/*.mdx to parse a date frontmatter value with front-matter, then sorts descending. The RSS route at apps/…/route.ts uses the same changelog helper to build <item> entries with links under /docs/<slug> and returns application/rss+xml.
API and metadata routes are colocated under apps/v4/app/**. apps/…/route.ts exposes Fumadocs search by passing the same source to createFromSource. apps/…/route.ts serves Markdown for LLM consumers: apps/…/next.config.mjs rewrites /docs/:path*.md to /llm/:path*, the route resolves the docs page, chooses a style from components|ai-elements/<base> slug segments with base-nova as fallback, then calls processMdxForLLMs() from apps/…/llm.ts to expand component lists and replace ComponentPreview tags with source code before returning text/markdown. apps/…/route.tsx creates dynamic Open Graph images from title and description query params using next/og and local base64 Geist font JSON files in apps/…/*.json. apps/…/sitemap.ts combines static routes, every source.getPages() URL, block category URLs, and chart-type URLs under siteConfig.url; apps/…/robots.ts allows all crawlers and points to that sitemap. apps/…/route.ts dynamically reads app/…/typeset.css from disk and serves it as plain text with no-store for the typeset customizer's copy flow. apps/…/route.ts serves a static-ish public registry directory, optionally enriching it with a Vercel Blob health snapshot when REGISTRY_HEALTH_ENABLED=1.
Beyond docs, apps/v4/app/(app)/** defines static content/product pages that share the app shell. apps/…/page.tsx is the homepage and emits WebSite JSON-LD. apps/…/page.tsx shows featured blocks, while apps/…/page.tsx statically generates one page per registryCategories entry and uses getAllBlockIds() plus the active style. apps/…/page.tsx statically generates fixed chart categories (area, bar, line, pie, radar, radial, tooltip), fetches registry items and highlighted code for configured charts, and 404s any type outside that list. apps/…/page.tsx renders palettes from getColors(). The designers at apps/…/page.tsx and apps/…/page.tsx use layouts with Suspense fallbacks because their history providers read useSearchParams(), and they render customizers/previews backed by route-local state providers.
The preview/view route group in apps/v4/app/(view)/** is for embedded demos and generated examples rather than normal site chrome. apps/…/page.tsx statically enumerates legacy style/item pairs from registry and examples indexes, loads the registry component with getRegistryComponent(), and renders only the component inside a minimal ComponentPreview. apps/…/page.tsx statically prebuilds a small set of preview items per base but allows dynamic params, injects scripts used by the create preview iframe, wraps the rendered base component in DesignSystemProvider, and mounts a toaster for the base family. apps/…/page.tsx statically enumerates typeset fixtures from AVAILABLE_CONTENT_OPTIONS and injects prebuilt fixture HTML into a .typeset wrapper. apps/…/page.tsx is a dynamic example renderer with one-hour revalidation, resolving examples from ExamplesIndex and getComponent().
apps/…/next.config.mjs binds this app together at build/runtime. It wraps the Next config with createMDX({}) from fumadocs-mdx/next, disables TypeScript build blocking with typescript.ignoreBuildErrors, sets a monorepo Turbopack root, includes registry/styles/examples/app-example files in output tracing, and configures allowed remote image hosts. In development it scans registry/__components__ for @/styles/<style>/... imports and throws early if generated style outputs under styles/<style>/ui are missing. Redirects preserve older docs URLs, component URL defaults, .mdx to .md, and short aliases like /components, /charts, /cli, and /skills; rewrites route docs Markdown requests to the LLM route, /init.md to /init/md, and proxy the external /oidc zone including normalized RSC paths.
The package and project config files are part of the routing/content contract. apps/…/package.json pins Next 16, React 19, Fumadocs, MDX, code highlighting, and site UI dependencies; scripts run the dev server on port 4000, build registries before next build, regenerate Fumadocs sources on postinstall, and use tsconfig.scripts.json for script execution. apps/…/tsconfig.json enables strict Next typechecking with @/* mapped to the app root and temporary aliases from legacy create imports to app/(app)/(create)/*; those aliases are required while registry payloads still ship old import paths. apps/…/tsconfig.scripts.json loosens module resolution for scripts. apps/…/components.json points shadcn tooling at app/globals.css and aliases ui to @/registry/new-york-v4/ui, which is why MDX and pages can import registry UI primitives through the same project alias.
Coupling
- If
apps/v4/content/docs/**frontmatter or meta.json structure changes, verify apps/…/page.tsx, apps/…/layout.tsx, and apps/…/mdx-components.tsx: the page route requirestitleanddescription,DocsSidebaris driven bysource.pageTree, and custom MDX tags must exist inmdxComponentsor docs builds will fail at render time. - If apps/…/source.config.ts changes the docs directory, MDX plugin behavior, or generated source shape, also check apps/…/source.ts, apps/…/route.ts, apps/…/sitemap.ts, apps/…/page.tsx, apps/…/page.tsx, and apps/…/route.ts; all of them assume one shared Fumadocs
sourcewith/docsURLs. - If a docs route is added or renamed under
apps/v4/app/(app)/docs/**, update apps/…/next.config.mjs redirects/rewrites and metadata routes as needed. /docs/:path*.md is not served by the page route; it is rewritten to/llm/:path*, so Markdown consumers depend on the rewrite plus apps/…/route.ts staying in sync with docs slugs. - If changelog MDX placement or date frontmatter changes, verify both apps/…/page.tsx and apps/…/route.ts. They share
getChangelogPages()from apps/…/changelog.ts, which derives filesystem paths from process.cwd()/…/*.mdx and silently falls back tonulldates on read or parse failure. - If component preview tags or registry style names change in docs content, check apps/…/mdx-components.tsx, apps/…/llm.ts, apps/…/page.tsx, and apps/…/page.tsx. Browser docs rendering, LLM Markdown expansion, and iframe previews each resolve component/demo source through different registry/example indexes and style/base fallbacks.
- If apps/…/sitemap.ts route lists change, keep it aligned with statically generated route params in apps/…/page.tsx and apps/…/page.tsx; the sitemap hardcodes chart types and reads block categories separately, so a route can exist without being advertised if only one list is updated.
- If generated registry styles or output-traced assets move, update apps/…/next.config.mjs and apps/…/components.json together. The config's development guard expects tracked registry shards to import generated files from
styles/<style>/ui, output tracing includes./registry/**/*,./styles/**/*,./examples/**/*, and./app/**/examples/**/*, and shadcn aliases point UI imports to@/registry/new-york-v4/ui.
Risks
- apps/…/page.tsx exports
dynamicParams = falseand only returnssource.generateParams(). If an MDX file is added underapps/v4/content/docs/**but the Fumadocs generated source is stale, the page will not be generated and the docs URL will 404 even though the file exists. - apps/…/changelog.ts reconstructs changelog file paths from page slugs and reads content/…/*.mdx directly. If changelog content is moved, renamed with a non-MDX extension, or no longer includes parseable
datefrontmatter, apps/…/page.tsx and apps/…/route.ts will sort those entries as timestamp0or use the current date in RSS. - apps/…/next.config.mjs intentionally throws during development when generated style files referenced by
registry/__components__are missing. After pulling changes that add a base/style,next devcan fail before routing starts untilpnpm --filter=v4 registry:build --style allis run. - apps/…/route.ts uses
dynamicParams = truebutgenerateStaticParams()returns an empty array, and /docs/:path*.md is wired to it by apps/…/next.config.mjs. If hosting or Next static behavior changes around dynamic route handlers, Markdown docs delivery is the route most likely to break because no concrete LLM paths are predeclared. - apps/…/route.ts enriches registry data only when
REGISTRY_HEALTH_ENABLED=1and a fresh Blob snapshot is available within 2.5 seconds. MissingBLOB_READ_WRITE_TOKEN, a wrongREGISTRY_HEALTH_BLOB_STORE_ID/BLOB_STORE_ID, or a snapshot older than six hours silently downgrades the response to the plain registry directory after logging a warning.