Skip to content

WIP: nimbus build target#31721

Draft
MohamedH1998 wants to merge 15 commits into
productionfrom
feat/nimbus-wire-up
Draft

WIP: nimbus build target#31721
MohamedH1998 wants to merge 15 commits into
productionfrom
feat/nimbus-wire-up

Conversation

@MohamedH1998

Copy link
Copy Markdown
Contributor

Summary

Priming work for the Starlight → Nimbus migration. Single branch by design — this will not be split. It's large because it vendors the Nimbus app in one place; review is aided by the fact that none of it is wired into production.

What it adds

  • src/nimbus/ app + a BUILD_TARGET=nimbus branch in astro.config.ts. Default build stays Starlight.
  • Content/assets shared in place (read-only); consumes published nimbus-docs@0.1.16.
  • nimbus-build.yml: non-deploying parity build, scoped to my PRs only.

Derisked — no impact on production, contributors, or CI (verified on this branch vs production):

  • Default pnpm build → Starlight ./dist unchanged
  • pnpm test:postbuild (Worker contracts) — 15/15 pass.
  • pnpm check — identical to production (no branch-introduced errors).
  • pnpm install --frozen-lockfile — clean.
  • Nimbus target never deploys; its CI job skips on everyone else's PRs and is not a required check.

Out of scope / later PRs: output contracts, parity gate, and the cutover (the flip to Nimbus is its own reversible PR).

Documentation checklist

@github-actions

github-actions Bot commented Jun 26, 2026

Copy link
Copy Markdown
Contributor

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern Owners
/.github/ @cloudflare/content-engineering, @kodster28, @mvvmm, @colbywhite, @ahaywood, @MohamedH1998
* @cloudflare/product-owners
*.ts @cloudflare/content-engineering, @kodster28
*.js @cloudflare/content-engineering, @kodster28
package.json @cloudflare/content-engineering
/src/content/changelog/waf/ @cloudflare/firewall, @vs-mg, @fb1337, @cloudflare/pm-changelogs, @cloudflare/appsec-reviewers, @elithrar, @cloudflare/product-owners, @hsaxenaCF, @danielegm, @ay-cf
/src/content/docs/workers/wrangler/ @cloudflare/wrangler, @irvinebroque, @cloudflare/product-owners, @MattieTK, @vy-ton
*.astro @cloudflare/content-engineering, @kodster28

Comment thread src/nimbus/scripts/mermaid.client.ts Dismissed
Comment thread src/nimbus/util/model-markdown.ts Fixed
cloudflare-docs-bot Bot and others added 2 commits June 26, 2026 11:44
…caping or encoding'

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
@ask-bonk

ask-bonk Bot commented Jun 26, 2026

Copy link
Copy Markdown
Contributor

PR Review: WIP: nimbus build target (#31721)


Summary

This PR introduces a parallel Nimbus documentation build target as priming work for the Starlight → Nimbus migration. It adds:

  • src/nimbus/ — a vendored Astro app (~70 component ports, layouts, routes) that reads shared src/content/ and src/assets/ in place via aliases.
  • nimbus-docs@0.1.16 dependency with pnpm-workspace.yaml peer-dependency rules for @astrojs/markdown-satteri.
  • BUILD_TARGET=nimbus branch in astro.config.ts — default (Starlight) build is unchanged.
  • .github/workflows/nimbus-build.yml — non-deploying parity CI job scoped to the author's PRs only.
  • .nimbus/routes.json — 8,465-line known-routes manifest.

The strategy is sound: shared content in place, build artifacts isolated (dist-nimbus/, .astro-cache-nimbus/), zero contributor impact, and the cutover deferred to a later reversible PR. Prebuild tests pass and formatting is clean.


Labels

  • infrastructure
  • nimbus
  • build

Issues Requiring Attention

1. @ts-ignore regression in astro.config.ts causes lint failure

File: astro.config.ts
Line: 129

The PR changed // @ts-expect-error (production) to // @ts-ignore. The repo's ESLint config explicitly forbids @ts-ignore (@typescript-eslint/ban-ts-comment), so pnpm run lint now fails.

-					// @ts-ignore
+					// @ts-expect-error plugins types are outdated but functional
 					rehypeTitleFigure,

Action: Revert to @ts-expect-error (or remove the directive if the types are now correct).


2. Type-check failure introduced by lockfile changes

File: src/plugins/rehype/heading-slugs.ts
Line: 32

pnpm run check now fails with:

src/plugins/rehype/heading-slugs.ts:32:33 - error ts(2345):
Argument of type 'MdxTextExpression' is not assignable to parameter of type 'ElementContent'.

This file wasn't modified, but the lockfile changes (adding @astrojs/markdown-satteri@0.2.1) pull in differing versions of @types/hast / mdast-util-mdx-expression types that surface this incompatibility. The PR description states pnpm check is "identical to production," but it now errors in practice.

Action: Fix the type mismatch in heading-slugs.ts — either adjust the cast on line 30–32 or use a compatible union type so element.children.with(-2, text) accepts MdxTextExpression.


3. .nimbus/routes.json is committed inside a .gitignored directory

Files: .gitignore, .nimbus/routes.json

.gitignore adds .nimbus/ ("nimbus-docs generated lint report"), yet .nimbus/routes.json is tracked in git. This is confusing for contributors: the directory looks ignored, but one file inside it is committed. Future generated files in .nimbus/ will be silently untracked.

Action: Choose one of:

  • Move routes.json out of .nimbus/ (e.g., src/nimbus/routes.json or data/nimbus-routes.json), or
  • Make .gitignore specific (e.g., .nimbus/lint-report/ instead of .nimbus/), or
  • If .nimbus/ is meant to contain committed data, remove it from .gitignore and document its purpose.

4. Title prefix "WIP:"

The body says this is "Single branch by design — this will not be split" and the checklist is complete. The WIP: prefix signals "do not merge," which contradicts the intent. Consider removing it or renaming to something like infra: Add Nimbus build target to avoid confusion.


Minor / Non-blocking Notes

  • src/nimbus/ excluded from Prettier and ESLint — acknowledged as temporary priming debt. Ensure there's a tracking item (e.g., Epic H1) to re-enable before cutover.
  • src/content/changelog/waf/2026-05-04-waf-release.mdx appears in changed files (+9/-9) but content is identical; likely a merge-base artifact — no action needed.
  • No changelog entry — appropriate for internal infrastructure with no customer-facing change.
  • No redirects — appropriate since no pages are being removed or relocated.

Overall

Comment / Request changes on the @ts-ignore regression, the type-check failure, and the .nimbus/ .gitignore inconsistency. Once those three items are addressed, this is safe to merge as priming infrastructure.

github run

@MohamedH1998

Copy link
Copy Markdown
Contributor Author

/bonk review this PR, does it have any side-effects on the Starlight build which will still be used in production

@ask-bonk ask-bonk Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a focused review of side-effects on the Starlight production build (the default path).

TL;DR

The branching strategy is sound and most of the default Starlight path is unchanged, but two shared files were modified that directly affect the production build:

  1. — adds visible border-radius to tables (visual side-effect)
  2. — type-only fix with no runtime side-effect

Verification (ran on this branch)

  • �[2m16:33:32�[22m �[34m[astro-skills]�[39m Setting up Agent Skills Discovery routes
    �[2m16:33:32�[22m �[34m[astro-skills]�[39m Agent Skills Discovery routes configured
    �[2m16:33:33�[22m �[34m[content]�[39m Syncing content
    �[33m�[1m16:33:33�[22m [WARN] [skills-loader]�[39m Skills directory "skills" does not exist.
    �[2m16:33:33�[22m �[34m[skills-loader]�[39m Loaded 0 skill(s) from "skills"
    �[2m16:33:36�[22m �[34m[content]�[39m Synced content
    �[2m16:33:36�[22m �[34m[types]�[39m Generated �[2m4.40s�[22m
    �[2m16:33:36�[22m �[34m[check]�[39m Getting diagnostics for Astro files in /home/runner/work/cloudflare-docs/cloudflare-docs...
    �[96mbin/post-link-validation-comment/index.ts�[0m:�[93m93�[0m:�[93m4�[0m - �[93mwarning�[0m�[90m ts(7027): �[0mUnreachable code detected.

�[7m93�[0m return;
�[7m �[0m �[93m ~~~~~~�[0m
�[96mbin/post-link-validation-comment/index.ts�[0m:�[93m56�[0m:�[93m4�[0m - �[93mwarning�[0m�[90m ts(7027): �[0mUnreachable code detected.

�[7m56�[0m return;
�[7m �[0m �[93m ~~~~~~�[0m

�[96msrc/components/OneTrust.astro�[0m:�[93m20�[0m:�[93m11�[0m - �[93mwarning�[0m�[90m ts(6133): �[0m'OptanonWrapper' is declared but its value is never read.

�[7m20�[0m function OptanonWrapper() {}
�[7m �[0m �[93m ~~~~~~~~~~~~~~�[0m

�[96msrc/util/custom-loaders.ts�[0m:�[93m27�[0m:�[93m28�[0m - �[93mwarning�[0m�[90m ts(6385): �[0m'(params?: string | { normalize?: boolean | undefined; abort?: boolean | undefined; pattern?: RegExp | undefined; protocol?: RegExp | undefined; hostname?: RegExp | undefined; error?: string | ... 1 more ... | undefined; message?: string | undefined; } | undefined): ZodString' is deprecated.

�[7m27�[0m const source = z.string().url().parse(url);
�[7m �[0m �[93m ~~~�[0m

Result (375 files):

  • 0 errors
  • 0 warnings
  • 4 hints — passes (0 errors)
  • — passes
  • Checking formatting...
    All matched files use Prettier code style! — passes
  • �[2m16:34:15�[22m �[34m[astro-skills]�[39m Setting up Agent Skills Discovery routes
    �[2m16:34:15�[22m �[34m[astro-skills]�[39m Agent Skills Discovery routes configured

RUN v4.1.9 /home/runner/work/cloudflare-docs/cloudflare-docs

Test Files 7 passed (7)
Tests 72 passed (72)
Start at 16:34:16
Duration 1.95s (transform 207ms, setup 0ms, import 785ms, tests 496ms, environment 2.58s) — 72/72 pass (Workers suite fails as expected without artifacts)

What is safe (no production side-effect)

  • — the default path correctly falls back to the exact same Starlight , , and config blocks. The only addition to the default path is , which the inline comment correctly notes is dev-watcher only.
  • — new deps (, , iconify sets, fonts, , ) are all that are only imported by , which is behind the conditional dynamic import.
  • — the lockfile adds for the optional peer dep of , but existing package versions are unchanged (confirmed by diff: only tarball-URL normalizations for packages). �[2m16:34:23�[22m �[34m[astro-skills]�[39m Setting up Agent Skills Discovery routes
    �[2m16:34:23�[22m �[34m[astro-skills]�[39m Agent Skills Discovery routes configured
    �[2m16:34:24�[22m �[34m[content]�[39m Syncing content
    �[33m�[1m16:34:24�[22m [WARN] [skills-loader]�[39m Skills directory "skills" does not exist.
    �[2m16:34:24�[22m �[34m[skills-loader]�[39m Loaded 0 skill(s) from "skills"
    �[2m16:34:27�[22m �[34m[content]�[39m Synced content
    �[2m16:34:27�[22m �[34m[types]�[39m Generated �[2m4.40s�[22m
    �[2m16:34:27�[22m �[34m[check]�[39m Getting diagnostics for Astro files in /home/runner/work/cloudflare-docs/cloudflare-docs...
    �[96mbin/post-link-validation-comment/index.ts�[0m:�[93m93�[0m:�[93m4�[0m - �[93mwarning�[0m�[90m ts(7027): �[0mUnreachable code detected.

�[7m93�[0m return;
�[7m �[0m �[93m ~~~~~~�[0m
�[96mbin/post-link-validation-comment/index.ts�[0m:�[93m56�[0m:�[93m4�[0m - �[93mwarning�[0m�[90m ts(7027): �[0mUnreachable code detected.

�[7m56�[0m return;
�[7m �[0m �[93m ~~~~~~�[0m

�[96msrc/components/OneTrust.astro�[0m:�[93m20�[0m:�[93m11�[0m - �[93mwarning�[0m�[90m ts(6133): �[0m'OptanonWrapper' is declared but its value is never read.

�[7m20�[0m function OptanonWrapper() {}
�[7m �[0m �[93m ~~~~~~~~~~~~~~�[0m

�[96msrc/util/custom-loaders.ts�[0m:�[93m27�[0m:�[93m28�[0m - �[93mwarning�[0m�[90m ts(6385): �[0m'(params?: string | { normalize?: boolean | undefined; abort?: boolean | undefined; pattern?: RegExp | undefined; protocol?: RegExp | undefined; hostname?: RegExp | undefined; error?: string | ... 1 more ... | undefined; message?: string | undefined; } | undefined): ZodString' is deprecated.

�[7m27�[0m const source = z.string().url().parse(url);
�[7m �[0m �[93m ~~~�[0m

Result (375 files):

  • 0 errors
  • 0 warnings
  • 4 hints passing confirms it is inert for the Starlight target.
  • — correctly scoped to the author's PRs only () and non-deploying. Zero impact on production CI.
  • — only adds and to .

What has a production side-effect

**** — This shared stylesheet adds to and border-radius corner rules for first/last header cells. Because in loads every file under into Starlight's , this will change the visual appearance of tables in the current production Starlight build. If this was an intentional design improvement, it should be noted in the PR description. If it was intended only for Nimbus, it should move to instead.

**** — Changes to (two occurrences). This is a correct type-level fix with no runtime behavior change, but it is a modification to shared production code driven by the lockfile changes.

Previous review follow-up

The three items flagged in the earlier review appear resolved in the current branch state:

  • The regression is gone (lint passes).
  • The type-check failure is fixed via the rename.
  • now specifically ignores rather than the whole directory, so being tracked is no longer inconsistent.

Bottom line

The infrastructure branching is clean, but the ** change is a genuine, visible side-effect on the Starlight production build**. I'd flag that for explicit confirmation before merging.

@ask-bonk ask-bonk Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a focused review of side-effects on the Starlight production build (the default BUILD_TARGET path).

TL;DR

The branching strategy is sound and most of the default Starlight path is unchanged, but two shared files were modified that directly affect the production build:

  1. src/styles/table.css — adds visible border-radius to tables (visual side-effect)
  2. src/plugins/rehype/heading-slugs.ts — type-only fix with no runtime side-effect

Verification (ran on this branch)

  • pnpm run check — passes (0 errors)
  • pnpm run lint — passes
  • pnpm run format:core:check — passes
  • pnpm run test:prebuild — 72/72 pass (Workers suite fails as expected without dist/ artifacts)

What is safe (no production side-effect)

  • astro.config.ts — the default BUILD_TARGET path correctly falls back to the exact same Starlight markdown, integrations, and vite config blocks. The only addition to the default path is vite.server.watch.ignored, which the inline comment correctly notes is dev-watcher only.
  • package.json — new deps (nimbus-docs, satteri, iconify sets, fonts, clsx, tailwind-merge) are all devDependencies that are only imported by src/nimbus/astro-config.ts, which is behind the conditional BUILD_TARGET=nimbus dynamic import.
  • pnpm-lock.yaml — the lockfile adds @astrojs/markdown-satteri@0.2.1 for the optional peer dep of @astrojs/mdx, but existing package versions are unchanged (confirmed by diff: only tarball-URL normalizations for @cloudflare/* packages). pnpm run check passing confirms it is inert for the Starlight target.
  • .github/workflows/nimbus-build.yml — correctly scoped to the author's PRs only (if: github.event.pull_request.user.login == 'MohamedH1998') and non-deploying. Zero impact on production CI.
  • tsconfig.json — only adds dist-nimbus and src/nimbus to exclude.

What has a production side-effect

src/styles/table.css — This shared stylesheet adds border-radius: 0.75rem to .sl-markdown-content table and border-radius corner rules for first/last header cells. Because autogenStyles() in astro.config.ts loads every file under src/styles/ into Starlight's customCss, this will change the visual appearance of tables in the current production Starlight build. If this was an intentional design improvement, it should be noted in the PR description. If it was intended only for Nimbus, it should move to src/nimbus/styles/ instead.

src/plugins/rehype/heading-slugs.ts — Changes MdxTextExpression to MdxTextExpressionHast (two occurrences). This is a correct type-level fix with no runtime behavior change, but it is a modification to shared production code driven by the lockfile changes.

Previous review follow-up

The three items flagged in the earlier ask-bonk review appear resolved in the current branch state:

  • The @ts-ignore regression is gone (lint passes).
  • The heading-slugs.ts type-check failure is fixed via the MdxTextExpressionHast rename.
  • .gitignore now specifically ignores .nimbus/lint.json rather than the whole .nimbus/ directory, so .nimbus/routes.json being tracked is no longer inconsistent.

Bottom line

The infrastructure branching is clean, but the table.css change is a genuine, visible side-effect on the Starlight production build. I'd flag that for explicit confirmation before merging.

@ask-bonk

ask-bonk Bot commented Jun 26, 2026

Copy link
Copy Markdown
Contributor

Review posted to PR #31721.

Short answer: The branching strategy is clean and the default Starlight build path is almost entirely untouched, but I found one genuine visual side-effect on production Starlight:

  • src/styles/table.css — adds border-radius: 0.75rem to .sl-markdown-content table and corner radius rules for header cells. Because autogenStyles() loads every file in src/styles/ into Starlight's customCss, this will change table styling in the current production build.

Everything else is safe:

  • astro.config.ts correctly falls back to the exact same Starlight config when BUILD_TARGET is unset.
  • New deps (nimbus-docs, satteri, etc.) are only imported behind the conditional Nimbus dynamic import.
  • pnpm-lock.yaml adds @astrojs/markdown-satteri but doesn't change versions of existing packages; pnpm run check and pnpm run lint both pass.
  • The prior review issues (@ts-ignore, type-check failure, .gitignore inconsistency) are already resolved in the current branch.

I also flagged that src/plugins/rehype/heading-slugs.ts was modified (a correct type-only fix with no runtime impact), which is technically a change to shared production code.

github run

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.