[rekram1-node]

I moved the docs site (packages/web) from Astro 5 to Astro 7, matching packages/posts and services/www.

Versions

Package	Before	After
astro	5.7.13	7.3.8 (now in the root catalog, shared with posts and www)
@astrojs/starlight	0.34.3	0.41.11 (catalog)
@astrojs/cloudflare	12.6.3	14.1.4 (same as posts and www)
@astrojs/solid-js	5.1.0	7.1.0
@astrojs/markdown-remark	6.3.1	7.3.2 (same as www)
@astrojs/check	0.9.6	0.9.11

Starlight stays on 0.41.11 on purpose. 0.42 makes Tabs, Steps and FileTree parse HTML with Sätteri at render time, and Sätteri can't run in workerd, so the server bundle fails to build. The Starlight maintainers recommend staying on 0.41.11 for Cloudflare until that's fixed: withastro/starlight#4194

Config and code changes

• markdown.rehypePlugins → markdown.processor: unified({ rehypePlugins }). Astro 7 uses Sätteri for Markdown by default, so remark/rehype plugins need the unified processor.
• content.config.ts imports z from astro/zod; Astro 6 deprecated z from astro:content.
• Cloudflare adapter:
  • configPath: process.env.SST_WRANGLER_PATH. SST's cloudflare.Astro component checks for this line on Astro 6+ and won't deploy without it. During sst deploy it points the build at the wrangler config SST generates, with nodejs_compat and the worker vars.
  • prerenderEnvironment: "node". Adapter 13+ prerenders in workerd by default. The theme hands its headerLinks option to its components through globalThis, which only works if pages prerender in the same Node process as the config. Without this, the header links disappear from every page. This also matches how Astro 5 prerendered.
• config.json and tui.json are now written to dist/client/, the new assets directory, so they're still served at /config.json and /tui.json.
• s/[id].astro: the share page's page-wide is:global styles ended up in a stylesheet shared with 91 docs pages (all the ones that use Tabs). The rule that hides the first content panel then removed the page title on those pages. I moved the styles into an inline <style is:inline> inside the page. I also reset the top margin that Starlight 0.36+ adds before client islands, so the share page stays where it was.
• Hero.astro uses entry.id instead of entry.slug, which is no longer on Starlight's entry type. No page sets hero, so this doesn't change any output.
• .wrangler/ is gitignored; the adapter now creates it during builds.
• custom.css keeps the old look wherever Starlight 0.41 changed its CSS:
  • overflow-wrap: anywhere on p, headings and inline code (0.41 uses break-word). Without it, long inline code stops shrinking, so the SDK option tables reflow and the Japanese config page scrolls sideways on phones.
  • Tabs keep the old layout: a list item with a border underline instead of 0.41's flexbox and box shadow. This keeps the underline colours, tab heights, focus rings and wrapped labels on phones the same.
  • No bottom margin on a nested list that ends a list item, which 0.41 now adds.
  • text-autospace: no-autospace. 0.41 adds automatic spacing between CJK and Latin text.
  • The language picker keeps its old label colours.
  • The mobile menu's social icons keep their hover fade.
  • The "On this page" column keeps its old width between 1160px and 1320px. 0.41 keeps it at least a sidebar wide, which squeezes the content.
  • text-size-adjust stays at the browser default.
  • The prefixed backdrop-filter now comes before the unprefixed one. The new CSS minifier keeps only the last one of the pair, so the theme's 2px search blur and 8px mobile TOC blur had disappeared.
  • The theme's search dialog styles now apply in every language through site-search dialog. The theme selects dialog[aria-label="Search"], which only matches English, and 0.41 now translates the Thai label too. Translated pages now get the same dialog as English, which is a small fix compared with dev.
• Content:
  • The Danish :::caution asides get an explicit [Caution] title. 0.41 adds Danish strings ("Bemærk", which means "Note"). Our da.json can't override them, because Starlight looks translations up by da-DK.
  • The three broken :::примечание blocks in ru/providers.mdx are now :::note. The old site showed them as literal text, and the new markdown parser turned them into plain divs.
• astro.config.mjs turns off V8's Maglev compiler and concurrent Sparkplug. Under Node 24+, astro build sometimes printed "Complete!" and never exited (Hang at shutdown nodejs/node#64274). It reproduced in 2 of 28 builds, and 0 of 36 hung with the flags. The deploy job has no timeout, so a hang would hold it for hours.

Theme

toolbeam-docs-theme@0.4.8 is the latest release. Its peer ranges are still astro ^5.7.13 and @astrojs/starlight ^0.34.3. Its code works unchanged with Astro 7 and Starlight 0.41: it uses the config:setup hook, astro/zod and Starlight's virtual modules, and its mobile menu CSS still matches 0.41's markup. Because the peers don't match, bun recorded a nested Astro 5 and Starlight 0.34 tree for it in bun.lock. I added astro and @astrojs/starlight to the root catalog and to overrides (the same pattern as solid-js), so the theme's peers resolve to the workspace versions. posts and www now use astro: "catalog:" too, so the version lives in one place. A patch wouldn't help: bun resolves peers from the registry manifest, not from patched files.

Deploy

The docs still deploy via sst.cloudflare.x.Astro in infra/app.ts, and I didn't change anything there. Adapter 14 produces dist/server/entry.mjs, dist/server/wrangler.json and dist/client/ instead of dist/_worker.js and dist. SST 4.13.1 already detects this layout: it reads dist/server/wrangler.json and deploys entry.mjs with dist/client as the assets. _routes.json is gone. SST ignored it before because Workers static assets don't use it, so routing doesn't change. The first real check is the dev deploy after merge.

Verification

• bun run build in packages/web succeeds, both plain and with SST_WRANGLER_PATH pointing at a wrangler config shaped like the one SST writes (nodejs_compat, vars). Warnings match the old build apart from one new info-level Starlight warning (Entry docs → 404 was not found), and the 404 page renders the same.
• I bundled dist/server/entry.mjs with esbuild using the conditions SST uses for workers (workerd, worker, browser). It resolves everything; the only imports left unbundled are node built-ins and cloudflare:workers.
• Routes: the old and new builds produce the same 595 HTML pages and the same static files. The only differences are _routes.json (dropped), _headers and .assetsignore (added by the adapter).
• HTML text of all 595 pages compared after stripping scripts and styles. Remaining differences come from Starlight or Expressive Code updates: localized "Terminal window" labels, new Thai UI strings, updated de/es/tr strings, an x-default hreflang link, tab IDs like tab-0-1, and one French heading ID that now keeps a trailing hyphen. Nothing links to that heading.
• I compared the old and new builds served side by side over three rounds, fixing what each round found:
  • Pixel diffs: all 594 pages at 1440px in light and dark mode, and at 390px and 768px, captured full height. Every page matches except for the accepted differences listed below.
  • Width sweep: layout boxes on ~45 pages at every width from 300px to 2600px in 5px steps, plus 1px either side of every CSS breakpoint. The heights of all 594 pages were checked at 22 widths.
  • Interaction states: search in all 18 languages, tabs (click, keyboard, focus), the copy button, hover and focus on every control, sidebar collapse, TOC highlighting, anchor offsets, the language picker, the mobile menu and TOC dropdown, the 404 page and the banner.
  • Structure: <head> tags, heading ids, a full internal link and anchor check (the 112 broken links already on dev are unchanged), fonts, console errors, the accessibility tree, sitemap, robots and the pagefind index. I also compared the computed style of every element on 33 pages in 6 configurations.
  • Share page: /docs/s/<id> against a mock share API, served the way SST deploys each build, at 390, 1280 and 1440px in light and dark mode. It's pixel-identical.
  • Accepted differences:
    • Starlight's new UI translations: Thai interface strings and aside titles (a few Thai pages change height), the German "Zuletzt aktualisiert" footer label (the German footer wraps at a few narrow widths), the Turkish "Genel Bakış", Spanish strings, localized "Terminal window" labels and copy-button tooltips.
    • Redrawn aside icons (anti-aliasing only).
    • ru/providers now shows real note asides.
    • The French heading id mentioned above.
    • "Last updated" dates on the files this PR edits.
• /docs/config.md, /config.json and /tui.json return 200 on the preview; /docs/s/<id> renders through the worker.
• astro dev serves /docs/, /docs/config/, /docs/ja/ and /docs/config.md.
• astro check: 17 errors before, 17 after. The new Hero.astro type error is fixed; the rest already existed.
• bun install --frozen-lockfile passes. In the lockfile, the only packages added or removed belong to the docs site's dependency tree. The other changed lines are bun moving shared packages up or down a level after Astro 5's dependencies left; each consumer resolves the same version as before.
• bun run build in packages/posts still passes with astro: "catalog:".

[opencodejr]

The upgrade looks sound. I ran bun install and bun run build in packages/web on the PR head and both succeed. The build writes the new dist/server + dist/client layout that SST reads, and config.json and tui.json end up in dist/client/. I also checked that the share page's hide-first-panel rule no longer appears in any shared _astro stylesheet, and that the theme's header links still render with prerenderEnvironment: "node". I didn't test an actual deploy; as you note, the dev deploy after merge is the real check.

Public API: unchanged. This is a docs-site build change, and the SST_WRANGLER_PATH it reads is set by SST's own Astro component.

One small point inline: the Hero.astro check can never match the home page now.

[opencodejr]

The new commit only changes CSS and looks fine. Each override matches what Starlight 0.41.11 changed: overflow-wrap: break-word in its base styles, the tab underline drawn as a box shadow from --sl-tab-color-border, and the new bottom margin on nested lists. Starlight's styles are all in @layer starlight.* blocks, so the unlayered rules in custom.css take effect. bun run build still passes and the rules are in the shared common stylesheet.

Public API: unchanged.

The earlier Hero.astro point (entry.id is never "" for the home page) isn't addressed yet.

[opencodejr]

The build still passes. The ru/providers.mdx fix is a real content fix: :::примечание isn't a valid aside type, so those blocks didn't render as asides before. With :::note they do now. The CSS overrides look fine.

Public API: unchanged.

One point inline: the Danish [Caution] titles swap Starlight's Danish label for English. The earlier Hero.astro point is still open.

[opencodejr]

Starlight 0.41 translates aside.caution to Danish as "Bemærk" (see its translations/da.json), so adding [Caution] hardcodes an English title on Danish pages just to match the old screenshots. The same applies to the other six Danish :::caution[Caution] changes. I'd keep plain :::caution and accept the localized title, like the Thai asides you already accepted.

[opencodejr]

The new CSS commits look fine. bun run build still passes, and the site-search dialog rules land in the shared stylesheet with the theme's fadeInScaleUp/fadeInBackdrop keyframes. That makes the search dialog look the same in every language, not just on pages where the label is the English "Search".

Public API: unchanged.

The earlier Hero.astro and Danish [Caution] points are still open.

[opencodejr]

The new commit is fine. On Node 24.21 in this environment, bun run build in packages/web finished and the process exited on its own (exit 0, ~78s). One run can't confirm an intermittent hang is gone, so your 0-in-36 result is the stronger evidence. Node documents that changing V8 flags after startup can behave unpredictably, but given your numbers it's a reasonable stopgap until the Node fix lands.

Public API: unchanged.

The earlier Hero.astro and Danish [Caution] threads aren't touched by this commit. The description's reasoning for the Danish titles is fair, so I'll leave that one to you.