Handle MDX better and use turbopack

Author: aurorascharff

.gitignore

@@ -50,3 +50,6 @@ public/rss.xml
 
 # Generated OG images (scripts/generateOgImages.mjs)
 public/images/og/
+
+# Generated Sandpack RSC runtime sources (scripts/buildRscWorker.mjs)
+public/sandpack-rsc/

CLAUDE.md

@@ -53,9 +53,11 @@ See `.claude/docs/react-docs-patterns.md` for comprehensive style guidelines.
 Prettier is used for formatting (config in `.prettierrc`).
 
 <!-- BEGIN:nextjs-agent-rules -->
+
 # This is NOT the Next.js you know
 
-This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
 
-**Keep this block, including in commits.** It is part of the project's agent setup, maintained by `next dev` for every agent that works here. If it appears as an uncommitted change, that is intentional — commit it as-is. Do not remove it to clean up a diff; it will be regenerated.
 <!-- END:nextjs-agent-rules -->

next.config.js

@@ -17,25 +17,27 @@ const nextConfig = {
   reactStrictMode: true,
   reactCompiler: true,
   cacheComponents: true,
+  outputFileTracingIncludes: {
+    '/*': ['./src/content/**/*.md'],
+  },
   serverExternalPackages: [
     '@babel/core',
     '@babel/plugin-transform-modules-commonjs',
     '@babel/preset-react',
     '@mdx-js/mdx',
-    'metro-cache',
     'gray-matter',
     'unist-util-visit',
     'remark-gfm',
     'remark-frontmatter',
   ],
-  // Next 16 defaults to Turbopack, but this project still relies on the custom
-  // `webpack()` config below (module aliases, IgnorePlugin, and Sandpack's
-  // `raw-loader` imports) which Turbopack can't run yet. The build scripts pass
-  // `--webpack` to force the webpack pipeline; this empty `turbopack` object
-  // silences the "webpack config without turbopack config" warning in the
-  // meantime.
-  // TODO: port the webpack customizations to Turbopack and drop `--webpack`.
-  turbopack: {},
+  turbopack: {
+    resolveAlias: {
+      'use-sync-external-store/shim': 'react',
+      esquery: 'esquery/dist/esquery.min.js',
+      raf: './src/utils/rafShim.js',
+      process: './src/utils/processShim.js',
+    },
+  },
   async rewrites() {
     return {
       beforeFiles: [

package.json

@@ -4,10 +4,12 @@
   "private": true,
   "license": "CC",
   "scripts": {
+    "preanalyze": "node scripts/buildRscWorker.mjs",
     "analyze": "ANALYZE=true next build --webpack",
-    "dev": "next dev --webpack",
+    "predev": "node scripts/buildRscWorker.mjs",
+    "dev": "next dev",
     "prebuild:rsc": "node scripts/buildRscWorker.mjs",
-    "build": "node scripts/buildRscWorker.mjs && next build --webpack && node --experimental-modules ./scripts/downloadFonts.mjs && node ./scripts/generateOgImages.mjs",
+    "build": "node scripts/buildRscWorker.mjs && next build && node --experimental-modules ./scripts/downloadFonts.mjs && node ./scripts/generateOgImages.mjs",
     "lint": "eslint \"{src,plugins}/**/*.{js,jsx,ts,tsx}\" && eslint \"src/content/**/*.md\"",
     "lint:fix": "eslint --fix \"{src,plugins}/**/*.{js,jsx,ts,tsx}\" && eslint --fix \"src/content/**/*.md\"",
     "format:source": "prettier --config .prettierrc --write \"{plugins,src}/**/*.{js,ts,jsx,tsx,css}\"",
@@ -38,7 +40,6 @@
     "github-slugger": "^1.3.0",
     "next": "16.3.0",
     "parse-numeric-range": "^1.2.0",
-    "raw-loader": "^4.0.2",
     "react": "19.2.7",
     "react-collapsed": "^4.2.0",
     "react-dom": "19.2.7",
@@ -87,7 +88,6 @@
     "is-ci": "^3.0.1",
     "lint-staged": ">=10",
     "mdast-util-to-string": "^1.1.0",
-    "metro-cache": "0.72.2",
     "npm-run-all": "^4.1.5",
     "postcss": "^8.4.5",
     "postcss-flexbugs-fixes": "4.2.1",

scripts/buildRscWorker.mjs

@@ -42,3 +42,29 @@ const shimCode = fs.readFileSync(shimPath, 'utf8');
 workerCode = shimCode + '\n' + workerCode;
 
 fs.writeFileSync(workerOutfile, workerCode);
+
+const publicSourceDir = path.resolve(root, 'public/sandpack-rsc');
+fs.rmSync(publicSourceDir, {recursive: true, force: true});
+fs.mkdirSync(publicSourceDir, {recursive: true});
+
+const publicSources = {
+  'webpack-shim.js': shimPath,
+  'rsc-client.js': path.resolve(sandboxBase, 'rsc-client.js'),
+  'react-refresh-init.js': path.resolve(
+    sandboxBase,
+    '__react_refresh_init__.js'
+  ),
+  'worker-bundle.js': workerOutfile,
+  'rsdw-client.js': path.resolve(
+    root,
+    'node_modules/react-server-dom-webpack/cjs/react-server-dom-webpack-client.browser.production.js'
+  ),
+  'react-refresh-runtime.js': path.resolve(
+    root,
+    'node_modules/next/dist/compiled/react-refresh/cjs/react-refresh-runtime.development.js'
+  ),
+};
+
+for (const [name, source] of Object.entries(publicSources)) {
+  fs.copyFileSync(source, path.resolve(publicSourceDir, name));
+}

src/app/DocsPage.tsx

@@ -5,31 +5,36 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-'use client';
-
 import {Page, type PageSection} from 'components/Layout/Page';
-import {useDeserializedMDX} from 'components/Layout/useDeserializedMDX';
 import type {RouteItem} from 'components/Layout/getRouteMeta';
 import type {PageData} from 'lib/readMarkdownPage';
+import {renderCompiledMDX} from 'utils/compileMDX';
+import type {ReactNode} from 'react';
 
 interface DocsPageProps {
   data: PageData;
   pathname: string;
   section: PageSection;
   routeTree: RouteItem;
+  children?: ReactNode;
 }
 
-export function DocsPage({data, pathname, section, routeTree}: DocsPageProps) {
-  const {parsedContent, parsedToc} = useDeserializedMDX(data.content, data.toc);
+export async function DocsPage({
+  data,
+  pathname,
+  section,
+  routeTree,
+  children,
+}: DocsPageProps) {
+  const {content, toc} = await renderCompiledMDX(data);
   return (
     <Page
-      toc={parsedToc}
+      toc={toc}
       routeTree={routeTree}
       meta={data.meta}
       section={section}
-      pathname={pathname}
-      languages={data.languages}>
-      {parsedContent}
+      pathname={pathname}>
+      {children ?? content}
     </Page>
   );
 }

src/app/api/md/[...path]/route.ts

@@ -50,7 +50,7 @@ async function readContentMarkdown(
   ];
   for (const fullPath of candidates) {
     try {
-      return fs.readFileSync(fullPath, 'utf8');
+      return fs.readFileSync(/* turbopackIgnore: true */ fullPath, 'utf8');
     } catch {
       // Try next candidate
     }

src/app/community/layout.tsx

@@ -5,13 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-'use client';
-
-import * as React from 'react';
-import {usePathname} from 'next/navigation';
 import {SidebarNav} from 'components/Layout/SidebarNav';
 import {TopNav} from 'components/Layout/TopNav';
-import {getRouteMeta} from 'components/Layout/getRouteMeta';
 import type {RouteItem} from 'components/Layout/getRouteMeta';
 import sidebarCommunity from '../../sidebarCommunity.json';
 
@@ -20,20 +15,14 @@ export default function CommunityLayout({
 }: {
   children: React.ReactNode;
 }) {
-  const pathname = usePathname() || '/';
   const routeTree = sidebarCommunity as RouteItem;
-  const {breadcrumbs} = getRouteMeta(pathname, routeTree);
   return (
     <>
-      <TopNav
-        section="community"
-        routeTree={routeTree}
-        breadcrumbs={breadcrumbs}
-      />
+      <TopNav section="community" routeTree={routeTree} />
       <div className="grid grid-cols-only-content lg:grid-cols-sidebar-content 2xl:grid-cols-sidebar-content-toc">
         <div className="lg:-mt-16 z-10">
           <div className="fixed top-0 py-0 shadow lg:pt-16 lg:sticky start-0 end-0 lg:shadow-none">
-            <SidebarNav routeTree={routeTree} breadcrumbs={breadcrumbs} />
+            <SidebarNav routeTree={routeTree} />
           </div>
         </div>
         {children}

src/app/errors/ErrorDecoderView.tsx

@@ -5,22 +5,23 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-'use client';
-
 import {Page} from 'components/Layout/Page';
-import {useDeserializedMDX} from 'components/Layout/useDeserializedMDX';
 import {ErrorDecoderContext} from 'components/ErrorDecoderContext';
 import sidebarLearn from '../../sidebarLearn.json';
 import type {RouteItem} from 'components/Layout/getRouteMeta';
 import type {ErrorDecoderData} from 'lib/loadErrorDecoderData';
+import {renderCompiledMDX} from 'utils/compileMDX';
 
 interface ErrorDecoderViewProps {
   data: ErrorDecoderData;
   pathname: string;
 }
 
-export function ErrorDecoderView({data, pathname}: ErrorDecoderViewProps) {
-  const {parsedContent} = useDeserializedMDX(data.content, data.toc);
+export async function ErrorDecoderView({
+  data,
+  pathname,
+}: ErrorDecoderViewProps) {
+  const {content} = await renderCompiledMDX(data);
   return (
     <ErrorDecoderContext
       value={{errorMessage: data.errorMessage, errorCode: data.errorCode}}>
@@ -34,7 +35,7 @@ export function ErrorDecoderView({data, pathname}: ErrorDecoderViewProps) {
         routeTree={sidebarLearn as RouteItem}
         section="unknown"
         pathname={pathname}>
-        <div>{parsedContent}</div>
+        <div>{content}</div>
       </Page>
     </ErrorDecoderContext>
   );

src/app/learn/layout.tsx

@@ -5,49 +5,23 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-'use client';
-
-import * as React from 'react';
-import {usePathname} from 'next/navigation';
 import {SidebarNav} from 'components/Layout/SidebarNav';
 import {TopNav} from 'components/Layout/TopNav';
-import {getRouteMeta} from 'components/Layout/getRouteMeta';
 import type {RouteItem} from 'components/Layout/getRouteMeta';
 import sidebarLearn from '../../sidebarLearn.json';
 
-function RestoreHashAfterNavigation({pathname}: {pathname: string}) {
-  React.useEffect(() => {
-    if (!window.location.hash) {
-      return;
-    }
-
-    const id = decodeURIComponent(window.location.hash.slice(1));
-    // The Learn content remounts after a history traversal, so reapply the
-    // fragment once the replacement content is in the DOM.
-    const frame = requestAnimationFrame(() => {
-      document.getElementById(id)?.scrollIntoView();
-    });
-    return () => cancelAnimationFrame(frame);
-  }, [pathname]);
-
-  return null;
-}
-
 export default function LearnLayout({children}: {children: React.ReactNode}) {
-  const pathname = usePathname() || '/';
   const routeTree = sidebarLearn as RouteItem;
-  const {breadcrumbs} = getRouteMeta(pathname, routeTree);
   return (
     <>
-      <RestoreHashAfterNavigation pathname={pathname} />
-      <TopNav section="learn" routeTree={routeTree} breadcrumbs={breadcrumbs} />
+      <TopNav section="learn" routeTree={routeTree} />
       <div className="grid grid-cols-only-content lg:grid-cols-sidebar-content 2xl:grid-cols-sidebar-content-toc">
         <div className="lg:-mt-16 z-10">
           <div className="fixed top-0 py-0 shadow lg:pt-16 lg:sticky start-0 end-0 lg:shadow-none">
-            <SidebarNav routeTree={routeTree} breadcrumbs={breadcrumbs} />
+            <SidebarNav routeTree={routeTree} />
           </div>
         </div>
-        <React.Fragment key={pathname}>{children}</React.Fragment>
+        {children}
       </div>
     </>
   );