chore: bump to astro 7#32240
Merged
Merged
Conversation
MohamedH1998
requested review from
a team,
GregBrimble,
MattieTK,
WalshyDev,
irvinebroque,
kodster28 and
korinne
as code owners
July 22, 2026 14:05
Contributor
Review
👉 Fix in your agent 👈Fix the following review findings in PR #32240 (https://github.com/cloudflare/cloudflare-docs/pull/32240).
Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g. the fix requires disproportionate effort for minimal benefit,
or the finding is factually incorrect), explain why
- If you need clarification before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order
After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.
The comment must come before the commit — the bot reads PR comments when a new
push triggers a review, so skip comments posted after the push will be missed.
---
## Code Review
### Warnings (2)
#### CR-398fa0ea3c2e · Vite major version may be unsupported
- **File:** `package.json` line 152
- **Issue:** Astro 7.0.2 predates Vite 8 and likely does not declare Vite 8 in its peer-dependency range. Setting vite to ^8.0.0 risks install warnings or build/runtime failures.
- **Fix:** Confirm Astro 7.0.2's supported Vite range and pin vite to a compatible version (likely ^6.0.0 or ^7.0.0).
#### CR-dd9461086a2c · Inconsistent diagram package import
- **File:** `src/nimbus/components/react/diagram/DiagramControls.tsx` line 4
- **Issue:** This file now imports `useDiagram` from `@cloudflare/nimbus-docs/react`, while sibling diagram components (e.g., `scene.tsx`, `DiagramDebug.tsx`, `DiagramPauseAll.tsx`, `Tabs.tsx`) still import `Diagram`, `useDiagram`, `diagramRegistry`, and `useTabIndicator` from the unscoped `nimbus-docs/react`. `package.json` lists both `nimbus-docs` and `@cloudflare/nimbus-docs` as separate dependencies, so they can resolve to distinct modules with separate React contexts.
- **Fix:** Make sure all diagram-related imports in this directory use the same package scope (`@cloudflare/nimbus-docs/react`) so the `Diagram` provider and `useDiagram` consumer share the same context.
### Suggestions (1)
#### CR-ad0878cce0ca · Incorrect package name in comment
- **File:** `pnpm-workspace.yaml` line 17
- **Issue:** The comment says `@astrojs/markdown-satteri` to explain the peer-dependency resolution, which appears to be a typo for `@astrojs/markdown-remark`.
- **Fix:** Correct the package name to `@astrojs/markdown-remark` so the comment accurately describes why the old `allowedVersions` override is obsolete.
Code ReviewThis code review is in beta and may not always be helpful — use your judgment. Warnings (2)
Suggestions (1)
ConventionsNo convention issues found. Style Guide ReviewNo style-guide issues found. CommandsOnly codeowners can run commands. Post a comment with the command to trigger it.
|
github-actions
Bot
assigned
GregBrimble,
irvinebroque,
korinne,
MattieTK,
WalshyDev and
kodster28
Contributor
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
Contributor
|
/rebase |
Contributor
|
Nimbus Preview URL: https://4309b029.preview.developers.cloudflare.com |
Contributor
grrrrr |
mvvmm
approved these changes
Jul 22, 2026
Contributor
|
Preview URL: https://7f73044b.preview.developers.cloudflare.com Files with changes (up to 15)
|
1 task
mvvmm
added a commit
that referenced
this pull request
Jul 22, 2026
Nimbus is the only build target now — the srcDir/cacheDir split that
existed to run Starlight and Nimbus side by side no longer serves a
purpose. This merges src/nimbus/* into src/, matching Astro's default
srcDir and eliminating the cross-graph aliasing that split required.
- Merge src/nimbus/{components,scripts,util,plugins,layouts,pages,
schemas,styles,lib,content.config.ts,mdx-components.ts,components.ts,
astro-config.ts} into src/ (git mv, no name collisions)
- astro.config.ts: drop the srcDir/cacheDir override (Astro defaults)
- src/astro-config.ts: delete the ~120-line aliasResolver + resolveId
fallback Vite plugin entirely — with one tree, ~ and @ resolve to
src/* via the standard tsconfig paths, no override needed
- tsconfig.json: single config (~/* and @/* -> src/*), no more
src/nimbus exclude or separate src/nimbus/tsconfig.json
- Fix 6 relative imports whose depth changed with the move
(PageHead.astro, llms.txt.ts x2, 404.astro, docsearch-config.ts,
webmcp.ts, plugins/docsearch/index.ts)
- Fix 5 broken src/components.ts barrel paths (../components/AiSearch*
-> ./components/AiSearch*)
Removing the srcDir override also removed the root tsconfig's
'exclude: ["src/nimbus"]', which had been silently hiding the real
app from 'astro check' since the migration (check was only exercising
~40 leftover top-level files, not the ~400 files under src/nimbus).
Fixing the app for real type-checking surfaced two categories of
pre-existing issues, both fixed here:
- Astro 7 / @cloudflare/nimbus-docs 0.2.2->0.6.1 API changes that
landed in #32240 without anyone being able to see them break:
'incrementalBuilds' and 'partialResolver' were removed from
NimbusIntegrationOptions (partialResolver was already dead — Render
.astro resolves partials itself via getEntry); shiki's CodeLanguage
narrowed (lang="curl" -> lang="bash", a real highlighting
improvement, not just a cast); GetRSSItemsOptions dropped an
already-inert 'markdown' flag; [...slug].astro used two content
frontmatter fields ('canonical', 'styleGuide') never declared in
content.config.ts's schemaFields.
- ~50 pre-existing null-safety gaps on the permissive 'directory'
collection schema (data.entry / data.name are .optional()), mostly
'!' assertions or '?.' at existing, already-safe access sites (e.g.
mobile-sidebar.client.ts's hoisted function declarations couldn't
see the outer null-guard's narrowing).
Also found and fixed two independent bugs while unblocking 'check':
- SkillsList.astro called getCollection("cloudflare-skills-manifest"),
which doesn't exist — the declared collection is "skills". Fixed to
the correct name.
- McpServerList.astro calls getCollection("cloudflare-mcps-manifest"),
which also doesn't exist and has no declared collection anywhere.
Astro's getCollection warns + returns [] for unknown collections
rather than throwing, so this has been silently rendering an empty
MCP server list on 6 live agent-setup pages. Left a
'@ts-expect-error' + FIXME rather than guessing at a fix — this
needs a real collection/loader, which is out of scope here.
Verified locally: pnpm run check/lint/format:check/test all clean,
full 'pnpm run build' succeeds (8707 pages), test:postbuild passes.
mvvmm
added a commit
that referenced
this pull request
Jul 22, 2026
Nimbus is the only build target now — the srcDir/cacheDir split that
existed to run Starlight and Nimbus side by side no longer serves a
purpose. This merges src/nimbus/* into src/, matching Astro's default
srcDir and eliminating the cross-graph aliasing that split required.
- Merge src/nimbus/{components,scripts,util,plugins,layouts,pages,
schemas,styles,lib,content.config.ts,mdx-components.ts,components.ts,
astro-config.ts} into src/ (git mv, no name collisions)
- astro.config.ts: drop the srcDir/cacheDir override (Astro defaults)
- src/astro-config.ts: delete the ~120-line aliasResolver + resolveId
fallback Vite plugin entirely — with one tree, ~ and @ resolve to
src/* via the standard tsconfig paths, no override needed
- tsconfig.json: single config (~/* and @/* -> src/*), no more
src/nimbus exclude or separate src/nimbus/tsconfig.json
- Fix 6 relative imports whose depth changed with the move
(PageHead.astro, llms.txt.ts x2, 404.astro, docsearch-config.ts,
webmcp.ts, plugins/docsearch/index.ts)
- Fix 5 broken src/components.ts barrel paths (../components/AiSearch*
-> ./components/AiSearch*)
Removing the srcDir override also removed the root tsconfig's
'exclude: ["src/nimbus"]', which had been silently hiding the real
app from 'astro check' since the migration (check was only exercising
~40 leftover top-level files, not the ~400 files under src/nimbus).
Fixing the app for real type-checking surfaced two categories of
pre-existing issues, both fixed here:
- Astro 7 / @cloudflare/nimbus-docs 0.2.2->0.6.1 API changes that
landed in #32240 without anyone being able to see them break:
'incrementalBuilds' and 'partialResolver' were removed from
NimbusIntegrationOptions (partialResolver was already dead — Render
.astro resolves partials itself via getEntry); shiki's CodeLanguage
narrowed (lang="curl" -> lang="bash", a real highlighting
improvement, not just a cast); GetRSSItemsOptions dropped an
already-inert 'markdown' flag; [...slug].astro used two content
frontmatter fields ('canonical', 'styleGuide') never declared in
content.config.ts's schemaFields.
- ~50 pre-existing null-safety gaps on the permissive 'directory'
collection schema (data.entry / data.name are .optional()), mostly
'!' assertions or '?.' at existing, already-safe access sites (e.g.
mobile-sidebar.client.ts's hoisted function declarations couldn't
see the outer null-guard's narrowing).
Also found and fixed two independent bugs while unblocking 'check':
- SkillsList.astro called getCollection("cloudflare-skills-manifest"),
which doesn't exist — the declared collection is "skills". Fixed to
the correct name.
- McpServerList.astro calls getCollection("cloudflare-mcps-manifest"),
which also doesn't exist and has no declared collection anywhere.
Astro's getCollection warns + returns [] for unknown collections
rather than throwing, so this has been silently rendering an empty
MCP server list on 6 live agent-setup pages. Left a
'@ts-expect-error' + FIXME rather than guessing at a fix — this
needs a real collection/loader, which is out of scope here.
Verified locally: pnpm run check/lint/format:check/test all clean,
full 'pnpm run build' succeeds (8707 pages), test:postbuild passes.
mvvmm
added a commit
that referenced
this pull request
Jul 22, 2026
* chore: promote src/nimbus to src (single build target)
Nimbus is the only build target now — the srcDir/cacheDir split that
existed to run Starlight and Nimbus side by side no longer serves a
purpose. This merges src/nimbus/* into src/, matching Astro's default
srcDir and eliminating the cross-graph aliasing that split required.
- Merge src/nimbus/{components,scripts,util,plugins,layouts,pages,
schemas,styles,lib,content.config.ts,mdx-components.ts,components.ts,
astro-config.ts} into src/ (git mv, no name collisions)
- astro.config.ts: drop the srcDir/cacheDir override (Astro defaults)
- src/astro-config.ts: delete the ~120-line aliasResolver + resolveId
fallback Vite plugin entirely — with one tree, ~ and @ resolve to
src/* via the standard tsconfig paths, no override needed
- tsconfig.json: single config (~/* and @/* -> src/*), no more
src/nimbus exclude or separate src/nimbus/tsconfig.json
- Fix 6 relative imports whose depth changed with the move
(PageHead.astro, llms.txt.ts x2, 404.astro, docsearch-config.ts,
webmcp.ts, plugins/docsearch/index.ts)
- Fix 5 broken src/components.ts barrel paths (../components/AiSearch*
-> ./components/AiSearch*)
Removing the srcDir override also removed the root tsconfig's
'exclude: ["src/nimbus"]', which had been silently hiding the real
app from 'astro check' since the migration (check was only exercising
~40 leftover top-level files, not the ~400 files under src/nimbus).
Fixing the app for real type-checking surfaced two categories of
pre-existing issues, both fixed here:
- Astro 7 / @cloudflare/nimbus-docs 0.2.2->0.6.1 API changes that
landed in #32240 without anyone being able to see them break:
'incrementalBuilds' and 'partialResolver' were removed from
NimbusIntegrationOptions (partialResolver was already dead — Render
.astro resolves partials itself via getEntry); shiki's CodeLanguage
narrowed (lang="curl" -> lang="bash", a real highlighting
improvement, not just a cast); GetRSSItemsOptions dropped an
already-inert 'markdown' flag; [...slug].astro used two content
frontmatter fields ('canonical', 'styleGuide') never declared in
content.config.ts's schemaFields.
- ~50 pre-existing null-safety gaps on the permissive 'directory'
collection schema (data.entry / data.name are .optional()), mostly
'!' assertions or '?.' at existing, already-safe access sites (e.g.
mobile-sidebar.client.ts's hoisted function declarations couldn't
see the outer null-guard's narrowing).
Also found and fixed two independent bugs while unblocking 'check':
- SkillsList.astro called getCollection("cloudflare-skills-manifest"),
which doesn't exist — the declared collection is "skills". Fixed to
the correct name.
- McpServerList.astro calls getCollection("cloudflare-mcps-manifest"),
which also doesn't exist and has no declared collection anywhere.
Astro's getCollection warns + returns [] for unknown collections
rather than throwing, so this has been silently rendering an empty
MCP server list on 6 live agent-setup pages. Left a
'@ts-expect-error' + FIXME rather than guessing at a fix — this
needs a real collection/loader, which is out of scope here.
Verified locally: pnpm run check/lint/format:check/test all clean,
full 'pnpm run build' succeeds (8707 pages), test:postbuild passes.
* fix: wire up the real MCP servers manifest from middlecache
McpServerList.astro called getCollection("cloudflare-mcps-manifest"),
which never existed as a declared collection anywhere — it silently
rendered an empty list on all 6 agent-setup pages (getCollection warns
+ returns [] for unknown collections rather than throwing).
There's already a reusable pattern for exactly this (middlecacheLoader
in src/util/custom-loaders.ts, used by product-availability and
granular-control-applications) — I'd missed it when I first found this
gap. The real middlecache key is v1/cloudflare-mcps/mcps-manifest.json:
{ name, description, servers: [{ name, description, url }, ...] },
matching the component's existing usage exactly.
Adds a mcp-servers collection (src/content/collections/mcp-servers.ts)
using middlecacheLoader with a parser that flattens the servers array
into an id-keyed lookup (slugified name), same shape as the existing
product-availability/granular-control-applications loaders. Updates
McpServerList.astro to read from it and removes the @ts-expect-error/
FIXME workaround.
Verified: pnpm run check clean, full build succeeds, and the rendered
agent-setup pages now show the real server list (previously empty).
* fix: wire up the real skills manifest from middlecache, not the local skills collection
My earlier fix for SkillsList.astro (which called
getCollection("cloudflare-skills-manifest") — a collection that never
existed) repointed it at the existing "skills" collection instead.
That was the wrong fix: "skills" is populated by astro-skills's
skillsLoader reading the full SKILL.md bundle tarball, which exists to
serve the /.well-known/skills/ discovery routes — a different purpose
with a heavier loading mechanism than a simple name+description list.
bin/fetch-skills.ts already downloads a lightweight, purpose-built
manifest for exactly this display case
(v1/cloudflare-skills/skills-manifest.json: { skills: [{ name,
description, files }] }) to .tmp/middlecache/, but nothing ever reads
it afterward — same class of bug as the MCP servers manifest.
Adds a skills-manifest collection (mirroring mcp-servers.ts) using the
same middlecacheLoader pattern, fetching the manifest directly rather
than reusing the local skills/ bundle. Points SkillsList.astro at it.
Verified against a fresh (non-stale-cached) middlecache fetch: the
build now renders all 11 skills, not the 8 that happened to be present
in the local skills/ bundle when I ran the original (wrong) fix.
* fix: address bot review findings — unsafe non-null assertions
Fixes 10 findings from PR review, all pre-existing null-safety gaps
introduced when adding !/?? handling for the permissive directory
schema in the earlier check-fixing commit:
- mcp-servers.ts: detect duplicate slugified server names and throw
instead of silently overwriting a colliding entry (CR-9f8cfe630555)
- Header.astro: entry!.title -> entry?.title ?? product.id, matching
the fallback already used two lines away for the sort comparator
(CR-b89feaef75fa)
- Directory.astro: name!/entry! at 5 sites (sort comparator,
description fallback, data-name attr, href, icon-letter fallback)
replaced with ?? "" / ?. plus a real fallback href (/${product.id}/)
instead of asserting non-null on fields the schema declares optional
(CR-dd0c61f74f87, CR-7e2e21a47e40, CR-c4d911cf54f4, CR-fd550522934f,
CR-3fbf0fffe23d)
- PagesBuildEnvironment.astro: filter out any version missing
build_environment (with a type predicate so the narrowing actually
holds) rather than asserting it's always present (CR-5def7f09bcad,
CR-b6e4e5021685)
- AvailableChangelogFeeds.astro: entry!.url/.title -> ?. plus fallback
to the entry's own id/path — the upstream filter only guarantees
entry.data.entry itself is defined, not its url/title fields
(CR-7fd7872dd3a9)
All 10 findings were agreed with — see PR discussion for the full
triage. Verified: pnpm run check/lint/format:check/test all clean,
full build succeeds (8707 pages, no collision-check throw), spot
checked rendered output for /directory/, /changelog/, and
/fundamentals/new-features/available-rss-feeds/ (uses
AvailableChangelogFeeds) all render correctly, test:postbuild passes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
8 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Bumps cloudflare-docs from Astro 6.4.7 + unscoped
nimbus-docs@0.2.2toAstro 7 + the scoped
@cloudflare/nimbus-docs@^0.6.1. This is a cleansingle-target migration (Starlight was already torn out), plus the dependency,
Tailwind/Vite-8, and Sätteri-plugin changes Astro 7 requires.
What changed
Dependencies
astro6.4.7→^7.0.2,@astrojs/mdx6.0.3→^7.0.3,@astrojs/react5.0.7→^6.0.1,@astrojs/markdown-remark7.2.0→7.2.1,satteri0.6.3→^0.9.1,vite7.3.5→^8.0.0.nimbus-docs@0.2.2→@cloudflare/nimbus-docs@^0.6.1(package rename;53 import sites updated across
src/nimbus/).@tailwindcss/postcss→@tailwindcss/vite(the PostCSS plugindoesn't build under Vite 8);
postcss.config.mjsremoved.globals.cssunchanged.
(
@astrojs/starlight*,astro-expressive-code,@expressive-code/*,astro-breadcrumbs,starlight-*plugins). Kept@docsearch/js+@docsearch/css(still power search).patches/@astrojs+starlight-docsearch+0.7.0.patch—dropping the dead dep left it failing
postinstall.Workspace
pnpm-workspace.yaml: removed the now-obsoletepeerDependencyRules.allowedVersionsoverride (the@astrojs/mdx→@astrojs/markdown-satteripeer is satisfied natively on Astro 7), andrenamed the
minimumReleaseAgeExcludeentrynimbus-docs→@cloudflare/nimbus-docs.Sätteri 0.9 plugin port
filename(string)→
fileURL(URL | undefined). Onlyplugins/satteri/shift-headings.tsused it; updated to read
ctx.fileURL?.pathname, and updated thepipeline.node.test.tsharness to passfileURL: pathToFileURL(...). Thisrestores changelog heading demotion (
pipeline.node.test.tsback to 20/20).Content
tenantIdimport indynamic-workers/usage/dynamic-workflows.mdx(Astro 7's bundler hard-fails onmissing named imports where Astro 6 only warned).
Verification
pnpm install --frozen-lockfile— clean, no peer warnings,postinstallclean.
pnpm test:prebuild— 77/77.pnpm check:astro— no errors in migrated files.pnpm build— exits 0, 8,706 pages, sitemap +.md/.mdxtwins emitted.pnpm test:postbuild(Workers) — 16/16.~/*alias resolution verified intact under Vite 8.Notes / follow-ups
existing
--max-old-space-size=8192heap cap (no JS-heap OOM). Peak RSS is~16 GB, dominated by native memory (
sharpacross ~1,600 images + the Vite 8bundler), i.e. right at the
ubuntu-latest16 GB ceiling. No Node flag changeis needed; if CI is OS-OOM-killed, the lever is a larger runner, not the heap
size.
smartypantsemits a non-blocking Astro 7 deprecation warning; nimbus stilluses the native flag (a nimbus-side follow-up will move it).
Screenshots (optional)
Documentation checklist