Upgrade to Next.js 16.3 + migrate to App Router + adopt Cache Components

.github/workflows/analyze.yml

@@ -42,13 +42,18 @@ jobs:
           key: ${{ runner.os }}-build-${{ env.cache-name }}
 
       - name: Build next.js app
-        # change this if your site requires a custom build command
-        run: ./node_modules/.bin/next build
-
-      # Here's the first place where next-bundle-analysis' own script is used
-      # This step pulls the raw bundle stats for the current bundle
+        # This project pins the webpack pipeline (see next.config.js): the custom
+        # webpack config and Sandpack's raw-loader imports aren't Turbopack-ready,
+        # and Next 16's `next build` defaults to Turbopack. Match the `build`/`analyze`
+        # npm scripts by forcing `--webpack`.
+        run: ./node_modules/.bin/next build --webpack
+
+      # Measure the current build's bundle sizes (App Router-aware).
+      # See scripts/analyzeBundle.mjs — reads build-manifest.json + .next/static
+      # and sums gzipped sizes, since nextjs-bundle-analysis only understands the
+      # Pages Router and reports 0 B for the App Router.
       - name: Analyze bundle
-        run: npx -p nextjs-bundle-analysis@0.5.0 report
+        run: node scripts/analyzeBundle.mjs report
 
       - name: Upload bundle
         uses: actions/upload-artifact@v4
@@ -65,22 +70,12 @@ jobs:
           name: bundle_analysis.json
           path: .next/analyze/base/bundle
 
-      # And here's the second place - this runs after we have both the current and
-      # base branch bundle stats, and will compare them to determine what changed.
-      # There are two configurable arguments that come from package.json:
-      #
-      # - budget: optional, set a budget (bytes) against which size changes are measured
-      #           it's set to 350kb here by default, as informed by the following piece:
-      #           https://infrequently.org/2021/03/the-performance-inequality-gap/
-      #
-      # - red-status-percentage: sets the percent size increase where you get a red
-      #                          status indicator, defaults to 20%
-      #
-      # Either of these arguments can be changed or removed by editing the `nextBundleAnalysis`
-      # entry in your package.json file.
+      # Compare the current build against the base-branch stats downloaded above
+      # and write the Markdown comment body. Degrades gracefully when the base
+      # branch has no stats yet (or still has the old format).
       - name: Compare with base branch bundle
         if: success() && github.event.number
-        run: ls -laR .next/analyze/base && npx -p nextjs-bundle-analysis compare
+        run: node scripts/analyzeBundle.mjs compare
 
       - name: Upload analysis comment
         uses: actions/upload-artifact@v4

.gitignore

@@ -43,9 +43,13 @@ public/rss.xml
 # claude local settings
 .claude/*.local.*
 .claude/react/
+.claude/launch.json
 
 # worktrees
 .worktrees/
 
 # Generated OG images (scripts/generateOgImages.mjs)
 public/images/og/
+
+# Generated Sandpack RSC runtime sources (scripts/buildRscWorker.mjs)
+public/sandpack-rsc/

CLAUDE.md

@@ -25,8 +25,9 @@ src/
 │   ├── reference/     # API reference docs
 │   ├── blog/          # Blog posts
 │   └── community/     # Community pages
+├── app/               # Next.js App Router routes
 ├── components/        # React components
-├── pages/             # Next.js pages
+├── lib/               # Server-only helpers (MDX loading, metadata)
 ├── hooks/             # Custom React hooks
 ├── utils/             # Utility functions
 └── styles/            # CSS/Tailwind styles
@@ -50,3 +51,13 @@ For Sandpack code examples, invoke `/docs-sandpack`.
 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/` (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.
+
+<!-- END:nextjs-agent-rules -->

eslint-local-rules/__tests__/lint-markdown-code-blocks.test.js

@@ -10,32 +10,30 @@ const fs = require('fs');
 const path = require('path');
 const {ESLint} = require('eslint');
 const plugin = require('..');
+const parser = require('../parser');
 
-const FIXTURES_DIR = path.join(
-  __dirname,
-  'fixtures',
-  'src',
-  'content'
-);
-const PARSER_PATH = path.join(__dirname, '..', 'parser.js');
-
+const FIXTURES_DIR = path.join(__dirname, 'fixtures', 'src', 'content');
 function createESLint({fix = false} = {}) {
   return new ESLint({
-    useEslintrc: false,
+    overrideConfigFile: true,
     fix,
-    plugins: {
-      'local-rules': plugin,
-    },
-    overrideConfig: {
-      parser: PARSER_PATH,
-      plugins: ['local-rules'],
-      rules: {
-        'local-rules/lint-markdown-code-blocks': 'error',
-      },
-      parserOptions: {
-        sourceType: 'module',
+    overrideConfig: [
+      {
+        files: ['**/*.md'],
+        languageOptions: {
+          parser,
+          parserOptions: {
+            sourceType: 'module',
+          },
+        },
+        plugins: {
+          'local-rules': plugin,
+        },
+        rules: {
+          'local-rules/lint-markdown-code-blocks': 'error',
+        },
       },
-    },
+    ],
   });
 }
 
@@ -53,11 +51,7 @@ async function lintFixture(name, {fix = false} = {}) {
 
 async function run() {
   const basicResult = await lintFixture('basic-error.md');
-  assert.strictEqual(
-    basicResult.messages.length,
-    1,
-    'expected one diagnostic'
-  );
+  assert.strictEqual(basicResult.messages.length, 1, 'expected one diagnostic');
   assert(
     basicResult.messages[0].message.includes('Calling setState during render'),
     'expected message to mention setState during render'
@@ -91,9 +85,7 @@ async function run() {
     fix: true,
   });
   assert(
-    duplicateFixed.output.includes(
-      "{expectedErrors: {'react-compiler': [4]}}"
-    ),
+    duplicateFixed.output.includes("{expectedErrors: {'react-compiler': [4]}}"),
     'expected duplicates to be rewritten to a single canonical block'
   );
   assert(
@@ -118,14 +110,12 @@ async function run() {
     fix: true,
   });
   assert(
-    malformedFixed.output.includes(
-      "{expectedErrors: {'react-compiler': [4]}}"
-    ),
+    malformedFixed.output.includes("{expectedErrors: {'react-compiler': [4]}}"),
     'expected malformed metadata to be replaced with canonical form'
   );
 }
 
-run().catch(error => {
+run().catch((error) => {
   console.error(error);
   process.exitCode = 1;
 });

eslint-local-rules/package.json

@@ -7,6 +7,6 @@
     "test": "node __tests__/lint-markdown-code-blocks.test.js"
   },
   "devDependencies": {
-    "eslint-mdx": "^2"
+    "eslint-mdx": "^3.8.1"
   }
 }