From c82ace99fb6cbfb59b90a3b12704333c11a1a726 Mon Sep 17 00:00:00 2001 From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com> Date: Thu, 10 Sep 2026 23:27:52 -0600 Subject: [PATCH 1/5] Add dev/TODO.md with Vercel audit tasks Amp-Thread-ID: https://ampcode.com/threads/T-01a08e2d-682f-75dd-a050-cb9bf8888dac Co-authored-by: Amp --- dev/TODO.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 dev/TODO.md diff --git a/dev/TODO.md b/dev/TODO.md new file mode 100644 index 000000000..6d89a1675 --- /dev/null +++ b/dev/TODO.md @@ -0,0 +1,66 @@ +# TODO + +Vercel project: `sourcegraph-docs` (team `sourcegraph-f8c71130`). Audit +artifacts live in `logs/vercel-audit/` (git-ignored). One PR per task; +link PRs here as they open, delete tasks when they merge. + +## 1. Node 20 build image is deprecated (separate thread) + +Vercel build log warns that Node 20.x deployments fail after 2026-10-01. +`contentlayer` 0.3.4 emits `assert { type: 'json' }`, which Node ≥ 22 +rejects; migrate to `contentlayer2` / `next-contentlayer2` ≥ 0.5.0 first, +then set Node 22 in `.tool-versions` and `package.json#engines`. + +## 2. 24 MB shared JS chunk on every page + +`src/components/Toc.tsx` and `src/components/ContentTabs.jsx` are +`'use client'` and import `allPosts` from `contentlayer/generated`, so +every post's raw + compiled body lands in one client chunk +(`7180-*.js`: 24.4 MB raw, 2.78 MB gzip; First Load JS 2.95 MB). +Fix: compute what those components need on the server +(`src/app/[...slug]/page.tsx`) and pass it as props. + +## 3. Pin the toolchain + +Build log picks `pnpm@9` "based on project creation date" while +`.tool-versions` says pnpm 10.25.0 / Node 20.19.6. Add `packageManager` +and `engines` to `package.json`. + +## 4. Dead Langbase secrets + +`NEXT_LB_PIPE_API_KEY` and `LANGBASE_PIPE_ASK_SG_API_KEY` are set in all +three environments. No other team project, no repo in the org, and no +current code references them (Langbase was removed in #1898). Delete +them from the Vercel project and rotate at Langbase. + +## 5. Runtime + +- a. `/api/md/[...slug]` (reached via the `*.md` middleware rewrite) is a + dynamic lambda with `cache-control: max-age=0, must-revalidate`. + Prerender it (`force-static` + `generateStaticParams`). +- b. Functions run on `standard_legacy` memory with Fluid compute off. + Enable Fluid in `vercel.json`; validate `/api/og` and `.md` latency on + the preview before merging. +- c. `src/middleware.ts` runs on every page and linear-scans ~5,900 + redirects from `src/data/redirects.ts`. Move static redirects to + `next.config.js#redirects()`; keep middleware for `.md` rewrites and + version patterns. + +## 6. Build + +- a. `dev/check-*.mjs` and `generate-mermaid-icons.mjs` run twice per + build because `next.config.js` is evaluated twice. Run them once from + the `build` script. Fix `generate-mermaid-logos` script, which points + at a nonexistent file. +- b. `caniuse-lite` is stale and `next lint` warns on `` in + `Logo.tsx`, `mdx/LinkCards.tsx`, `mdx/ProductCards.tsx`, + `mdx/ZoomableImage.tsx`, `api/og/[...path]/route.tsx`, plus a hook + dependency in `ContentTabs.jsx`. +- c. Build cache upload is ~880 MB (~60 s of a ~140 s build). Measure + what is in it before deciding whether it can shrink. + +## 7. Doubled base path 404s + +Runtime logs show 404s for `/docs/docs/_next/static/...`, all for the +not-found page's asset set. Find the referer (Observability query API, +log drain, or reproduce in a browser) and fix the source. From b04378b3654d6c69cfb08d1bfc6f23c41c2026d6 Mon Sep 17 00:00:00 2001 From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com> Date: Fri, 11 Sep 2026 00:04:58 -0600 Subject: [PATCH 2/5] dev/TODO: Link Vercel audit PRs; record findings for items 2, 6c, 6d, 7 Amp-Thread-ID: https://ampcode.com/threads/T-01a08e2d-682f-75dd-a050-cb9bf8888dac Co-authored-by: Amp --- dev/TODO.md | 68 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 41 insertions(+), 27 deletions(-) diff --git a/dev/TODO.md b/dev/TODO.md index 6d89a1675..60b1b4573 100644 --- a/dev/TODO.md +++ b/dev/TODO.md @@ -16,15 +16,16 @@ then set Node 22 in `.tool-versions` and `package.json#engines`. `src/components/Toc.tsx` and `src/components/ContentTabs.jsx` are `'use client'` and import `allPosts` from `contentlayer/generated`, so every post's raw + compiled body lands in one client chunk -(`7180-*.js`: 24.4 MB raw, 2.78 MB gzip; First Load JS 2.95 MB). +(`7180-*.js`: 24.4 MB raw, 2.78 MB gzip; First Load JS 2.95 MB). Its hash +changes on every deploy, so the CDN and every browser re-download it. +Confirmed in Chrome DevTools: 51 requests, 3.4 MB transferred, 28.0 MB +resources for one page; 2,539 kB of that is this chunk. Fix: compute what those components need on the server (`src/app/[...slug]/page.tsx`) and pass it as props. ## 3. Pin the toolchain -Build log picks `pnpm@9` "based on project creation date" while -`.tool-versions` says pnpm 10.25.0 / Node 20.19.6. Add `packageManager` -and `engines` to `package.json`. +PR #1906. Watch the preview build log for `Using pnpm@10`. ## 4. Dead Langbase secrets @@ -35,32 +36,45 @@ them from the Vercel project and rotate at Langbase. ## 5. Runtime -- a. `/api/md/[...slug]` (reached via the `*.md` middleware rewrite) is a - dynamic lambda with `cache-control: max-age=0, must-revalidate`. - Prerender it (`force-static` + `generateStaticParams`). -- b. Functions run on `standard_legacy` memory with Fluid compute off. - Enable Fluid in `vercel.json`; validate `/api/og` and `.md` latency on - the preview before merging. -- c. `src/middleware.ts` runs on every page and linear-scans ~5,900 - redirects from `src/data/redirects.ts`. Move static redirects to - `next.config.js#redirects()`; keep middleware for `.md` rewrites and - version patterns. +- a./b. PR #1912 (stacked on #1901): prerender `/api/md/[...slug]`, + enable Fluid compute. After the preview deploys, compare `.md` and + `/api/og` latency and `x-vercel-cache` against production. +- c. Draft PR #1907: static redirects moved to `next.config.js`; + middleware kept for `.md` rewrites and version patterns. Conflicts with + #1908 on `next.config.js`; merge one, rebase the other. ## 6. Build -- a. `dev/check-*.mjs` and `generate-mermaid-icons.mjs` run twice per - build because `next.config.js` is evaluated twice. Run them once from - the `build` script. Fix `generate-mermaid-logos` script, which points - at a nonexistent file. -- b. `caniuse-lite` is stale and `next lint` warns on `` in - `Logo.tsx`, `mdx/LinkCards.tsx`, `mdx/ProductCards.tsx`, - `mdx/ZoomableImage.tsx`, `api/og/[...path]/route.tsx`, plus a hook - dependency in `ContentTabs.jsx`. -- c. Build cache upload is ~880 MB (~60 s of a ~140 s build). Measure - what is in it before deciding whether it can shrink. +- a. Draft PR #1908: run `dev/check-*.mjs` once from the `build` script. +- b. Draft PR #1909: caniuse-lite bump, lint warnings to zero. +- c. Build cache is ~880 MB because `node_modules` is ~894 MB and + `.next/cache` ~303 MB (`@next/swc` 110 MB, `next` 101 MB, `mermaid` + 65 MB, `@effect-ts/system` 45 MB via contentlayer, `typescript` 38 MB, + `lucide-react` 30 MB). No quick win; revisit after task 1 replaces + contentlayer and if `mermaid` can be loaded client-side only. +- d. Web Analytics and Speed Insights: disabled 2026-09-11 via API. ## 7. Doubled base path 404s -Runtime logs show 404s for `/docs/docs/_next/static/...`, all for the -not-found page's asset set. Find the referer (Observability query API, -log drain, or reproduce in a browser) and fix the source. +Source found via `vercel.com/api/logs/request-logs` (the `vercel logs` +CLI drops referer/user-agent): 98 % are bingbot with referer +`https://docs.sourcegraph.com/`. Cloudflare answers +`docs.sourcegraph.com/*` with a **302** to `sourcegraph.com/docs/*`, and +Bing resolves the page's `/docs/_next/...` asset URLs against the +pre-redirect host, so they come back as `docs.sourcegraph.com/docs/_next/...` +→ 302 → `sourcegraph.com/docs/docs/_next/...` → 404. + +Fix (Cloudflare, not this repo): +- Make the `docs.sourcegraph.com` redirect a **301** so Bing drops the old + URLs from its index and stops crawling them. +- Add a rule so `docs.sourcegraph.com/docs/*` redirects to + `sourcegraph.com/docs/$1` without doubling the prefix. + +Fix (this repo): +- Every page sets `` + (`src/app/layout.tsx` `alternates.canonical: '/docs'`, never + overridden). Set a per-page canonical in `src/app/[...slug]/page.tsx` + `generateMetadata` so crawlers consolidate on the real URL. +- Optional guard in `next.config.js#redirects()`: + `{source: '/docs/:path*', destination: '/:path*', permanent: true}` + (Next prepends `basePath`, so this matches `/docs/docs/*`). From bda0db5aff41f9cde62c070c0f4a22b721c29866 Mon Sep 17 00:00:00 2001 From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com> Date: Fri, 11 Sep 2026 00:05:11 -0600 Subject: [PATCH 3/5] dev/TODO: Fix markdownlint blank-line warnings Amp-Thread-ID: https://ampcode.com/threads/T-01a08e2d-682f-75dd-a050-cb9bf8888dac Co-authored-by: Amp --- dev/TODO.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/dev/TODO.md b/dev/TODO.md index 60b1b4573..9587dee32 100644 --- a/dev/TODO.md +++ b/dev/TODO.md @@ -65,12 +65,14 @@ pre-redirect host, so they come back as `docs.sourcegraph.com/docs/_next/...` → 302 → `sourcegraph.com/docs/docs/_next/...` → 404. Fix (Cloudflare, not this repo): + - Make the `docs.sourcegraph.com` redirect a **301** so Bing drops the old URLs from its index and stops crawling them. - Add a rule so `docs.sourcegraph.com/docs/*` redirects to `sourcegraph.com/docs/$1` without doubling the prefix. Fix (this repo): + - Every page sets `` (`src/app/layout.tsx` `alternates.canonical: '/docs'`, never overridden). Set a per-page canonical in `src/app/[...slug]/page.tsx` From 27447b9aec31b4640d5992ce6787d37e6a4de634 Mon Sep 17 00:00:00 2001 From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com> Date: Fri, 11 Sep 2026 03:45:27 -0600 Subject: [PATCH 4/5] dev/TODO: Drop merged and completed Vercel audit items Amp-Thread-ID: https://ampcode.com/threads/T-01a08e2d-682f-75dd-a050-cb9bf8888dac Co-authored-by: Amp --- dev/TODO.md | 92 ++++++++++++++++------------------------------------- 1 file changed, 28 insertions(+), 64 deletions(-) diff --git a/dev/TODO.md b/dev/TODO.md index 9587dee32..63267cc6d 100644 --- a/dev/TODO.md +++ b/dev/TODO.md @@ -1,82 +1,46 @@ # TODO -Vercel project: `sourcegraph-docs` (team `sourcegraph-f8c71130`). Audit -artifacts live in `logs/vercel-audit/` (git-ignored). One PR per task; -link PRs here as they open, delete tasks when they merge. +Vercel project `sourcegraph-docs`. One PR per task; delete a task when +its PR merges. ## 1. Node 20 build image is deprecated (separate thread) -Vercel build log warns that Node 20.x deployments fail after 2026-10-01. -`contentlayer` 0.3.4 emits `assert { type: 'json' }`, which Node ≥ 22 -rejects; migrate to `contentlayer2` / `next-contentlayer2` ≥ 0.5.0 first, -then set Node 22 in `.tool-versions` and `package.json#engines`. +Node 20.x deployments fail after 2026-10-01. `contentlayer` 0.3.4 emits +`assert { type: 'json' }`, which Node ≥ 22 rejects. Migrate to +`contentlayer2` / `next-contentlayer2` ≥ 0.5.0, then set Node 22 in +`.tool-versions` and `package.json#engines`. ## 2. 24 MB shared JS chunk on every page `src/components/Toc.tsx` and `src/components/ContentTabs.jsx` are -`'use client'` and import `allPosts` from `contentlayer/generated`, so -every post's raw + compiled body lands in one client chunk -(`7180-*.js`: 24.4 MB raw, 2.78 MB gzip; First Load JS 2.95 MB). Its hash -changes on every deploy, so the CDN and every browser re-download it. -Confirmed in Chrome DevTools: 51 requests, 3.4 MB transferred, 28.0 MB -resources for one page; 2,539 kB of that is this chunk. -Fix: compute what those components need on the server -(`src/app/[...slug]/page.tsx`) and pass it as props. - -## 3. Pin the toolchain - -PR #1906. Watch the preview build log for `Using pnpm@10`. - -## 4. Dead Langbase secrets - -`NEXT_LB_PIPE_API_KEY` and `LANGBASE_PIPE_ASK_SG_API_KEY` are set in all -three environments. No other team project, no repo in the org, and no -current code references them (Langbase was removed in #1898). Delete -them from the Vercel project and rotate at Langbase. +`'use client'` and import `allPosts`, so every post's raw and compiled +body ships in one client chunk (`7180-*.js`: 24.4 MB raw, 2.78 MB gzip, +re-downloaded after every deploy). Fix: resolve the post on the server +in `src/app/[...slug]/page.tsx` and pass only what each component needs +as props (`Toc`: the post `_id`; `ContentTabs`: the rendered fallback +tab), then drop the `allPosts` imports. ## 5. Runtime -- a./b. PR #1912 (stacked on #1901): prerender `/api/md/[...slug]`, - enable Fluid compute. After the preview deploys, compare `.md` and - `/api/og` latency and `x-vercel-cache` against production. -- c. Draft PR #1907: static redirects moved to `next.config.js`; - middleware kept for `.md` rewrites and version patterns. Conflicts with - #1908 on `next.config.js`; merge one, rebase the other. +- Skip builds for non-site changes: #1901. +- Prerender `/api/md/[...slug]`, enable Fluid compute: #1912 (stacked on + #1901; retarget to `main` after it merges). +- Static redirects out of middleware: draft #1907 (rebase on `main` now + that #1908 merged). ## 6. Build -- a. Draft PR #1908: run `dev/check-*.mjs` once from the `build` script. -- b. Draft PR #1909: caniuse-lite bump, lint warnings to zero. -- c. Build cache is ~880 MB because `node_modules` is ~894 MB and - `.next/cache` ~303 MB (`@next/swc` 110 MB, `next` 101 MB, `mermaid` - 65 MB, `@effect-ts/system` 45 MB via contentlayer, `typescript` 38 MB, - `lucide-react` 30 MB). No quick win; revisit after task 1 replaces - contentlayer and if `mermaid` can be loaded client-side only. -- d. Web Analytics and Speed Insights: disabled 2026-09-11 via API. - -## 7. Doubled base path 404s - -Source found via `vercel.com/api/logs/request-logs` (the `vercel logs` -CLI drops referer/user-agent): 98 % are bingbot with referer -`https://docs.sourcegraph.com/`. Cloudflare answers -`docs.sourcegraph.com/*` with a **302** to `sourcegraph.com/docs/*`, and -Bing resolves the page's `/docs/_next/...` asset URLs against the -pre-redirect host, so they come back as `docs.sourcegraph.com/docs/_next/...` -→ 302 → `sourcegraph.com/docs/docs/_next/...` → 404. - -Fix (Cloudflare, not this repo): +- Lint warnings and stale `caniuse-lite`: draft #1909. -- Make the `docs.sourcegraph.com` redirect a **301** so Bing drops the old - URLs from its index and stops crawling them. -- Add a rule so `docs.sourcegraph.com/docs/*` redirects to - `sourcegraph.com/docs/$1` without doubling the prefix. +## 7. Doubled base path 404s and wrong canonical -Fix (this repo): +`sourcegraph.com/docs/docs/_next/...` 404s are bingbot following the +Cloudflare **302** from `docs.sourcegraph.com/` and resolving the +page's `/docs/_next/...` asset URLs against the old host. -- Every page sets `` - (`src/app/layout.tsx` `alternates.canonical: '/docs'`, never - overridden). Set a per-page canonical in `src/app/[...slug]/page.tsx` - `generateMetadata` so crawlers consolidate on the real URL. -- Optional guard in `next.config.js#redirects()`: - `{source: '/docs/:path*', destination: '/:path*', permanent: true}` - (Next prepends `basePath`, so this matches `/docs/docs/*`). +- Cloudflare: make the `docs.sourcegraph.com` redirect a 301, and + redirect `docs.sourcegraph.com/docs/*` to `sourcegraph.com/docs/$1` + without doubling the prefix. +- Repo: every page emits `` + (`src/app/layout.tsx` `alternates.canonical: '/docs'`). Set a per-page + canonical in `src/app/[...slug]/page.tsx#generateMetadata`. From 5441c7ac67abb19b7e5f28dc5951fc38a38d8f83 Mon Sep 17 00:00:00 2001 From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com> Date: Fri, 11 Sep 2026 04:22:44 -0600 Subject: [PATCH 5/5] Allow prerender and bingbot in CSpell Amp-Thread-ID: https://ampcode.com/threads/T-01a08ffc-99f1-7364-9fdd-dee10e0210aa Co-authored-by: Amp --- cspell-allow-list.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/cspell-allow-list.txt b/cspell-allow-list.txt index e5d99ffcd..5e29640b8 100644 --- a/cspell-allow-list.txt +++ b/cspell-allow-list.txt @@ -75,6 +75,7 @@ behaviour behaviours beyang bgwriter +bingbot binutils bitbucketcloud bitbucketserver @@ -412,6 +413,7 @@ pooler PREEMPTIBLE preg premade +prerender Príncipe privkey projectname