Introducing a new way to review your PRs.

Read the announcement

shadcn-ui / ui

Composable, accessible components with thoughtful defaults. Build your own component library with code you can customize, extend, and make your own.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / apps-v4-site-routing-content

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

Risks

  • apps/…/page.tsx exports dynamicParams = false and only returns source.generateParams(). If an MDX file is added under apps/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 date frontmatter, apps/…/page.tsx and apps/…/route.ts will sort those entries as timestamp 0 or 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 dev can fail before routing starts until pnpm --filter=v4 registry:build --style all is run.
  • apps/…/route.ts uses dynamicParams = true but generateStaticParams() 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=1 and a fresh Blob snapshot is available within 2.5 seconds. Missing BLOB_READ_WRITE_TOKEN, a wrong REGISTRY_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.