Breaking change (6.7.4): resolveSiteGlobals() now runs on all CMS routes, silently activating site globals for sites not using withSiteGlobals()

[JonasJesus42]

Summary

Starting from v6.7.4, resolveSiteGlobals() was moved from withSiteGlobals() into loadCmsPageInternal (inside cmsRoute.ts). This means it now runs on every CMS route, regardless of whether the site uses the withSiteGlobals() wrapper.

This is an undocumented breaking change for sites that use cmsRouteConfig without withSiteGlobals().

What changed

Before 6.7.4 (withSiteGlobals.ts):

• resolveSiteGlobals() was only called inside the withSiteGlobals() wrapper
• Sites using cmsRouteConfig alone had globals (including Theme section) silently not rendered
• The site's :root CSS fallbacks were used for all custom properties

From 6.7.4 (cmsRoute.ts, comment references #233):

// Resolve page sections and site globals in parallel. Globals are merged
// into the same `resolvedSections` array so the path through this server
// function is identical for SSR (F5) and SPA (<Link>) navigations — see
// #233 for the previous SPA-breakage when `withSiteGlobals` ran client-side
const [enrichedSections, globals] = await Promise.all([
  runSectionLoaders(page.resolvedSections, request),
  resolveSiteGlobals(),
]);

• resolveSiteGlobals() now runs unconditionally on all routes
• Globals (e.g. Theme section from site.json) are rendered everywhere
• This silently activates sections that the site had no idea were being injected

Impact

Sites that relied on globals NOT being rendered now have them injected without any code change on their end. In the lebiscuit project this manifested as:

1. The Theme section (registered in site.json → "theme") now renders a <style> block into every page
2. The Theme.tsx toValue() function emitted bare oklch components (47.81% 0.20 29deg) instead of full oklch(...) values
3. These variables override the :root fallback hex values in app.css
4. Tailwind v4's @theme { --color-brand-primary-1: var(--brand-primary-1) } now resolves to invalid CSS, breaking all custom colors site-wide

The site went from working colors to completely broken colors between 6.6.1 → 6.7.4 with no changes to the site's own code.

Reproduction

1. Create a site using cmsRouteConfig without withSiteGlobals()
2. Have a Theme section registered in site.json
3. Run with 6.6.1 → Theme does NOT render, :root fallback CSS is used ✅
4. Upgrade to 6.7.4+ → Theme now renders, overrides :root CSS variables ❌

Suggested fix

Either:

Option A — Document it as a breaking change in the CHANGELOG for 6.7.4, with a migration guide for sites that didn't use withSiteGlobals():

If your Theme section emits CSS variables, ensure the format matches what your app.css :root block expects (e.g. full oklch(...) vs bare components).

Option B — Add a flag to cmsRouteConfig to opt out of automatic globals resolution:

cmsRouteConfig({ resolveGlobals: false })

Option C — Validate that sections injected via resolveSiteGlobals() emit valid CSS custom property values (at least warn in dev when a <style> block contains malformed values).

Environment

• @decocms/start: 6.6.1 → 6.22.1 (breaking introduced in 6.7.4)
• Tailwind v4 + DaisyUI v5
• cmsRouteConfig used without withSiteGlobals() wrapper

[JonasJesus42]

Triage: bug confirmed still present in current (post-split) source; fix PR #294 is unmergeable

I looked at PR #294 and the current code. Documenting the status here since the PR can no longer be merged.

1. The bug is still present

In the current monorepo (@decocms/tanstack), packages/tanstack/src/routes/cmsRoute.ts still resolves site globals unconditionally on every CMS route:

• loadCmsPageInternal(fullPath) calls resolveSiteGlobals() with no gate (~L158–161):

  const [enrichedSections, globals] = await Promise.all([
    runSectionLoaders(page.resolvedSections, request),
    resolveSiteGlobals(),
  ]);

• loadCmsHomePage does the same (~L244–247).
• CmsRouteOptions (~L385–420) has no resolveGlobals flag.
• loadCmsPage's input validator is still (data) => data as string — no { path, resolveGlobals } form.

So the v6.7.4 behavior is intact: any site using cmsRouteConfig without withSiteGlobals() still gets the CMS Site block (theme + global + pageSections) injected into every page, with no opt-out. withSiteGlobals() itself is now a deprecated no-op — resolution lives entirely inside the server functions.

2. What PR #294 did (Option B — opt-out flag, default true)

• Added resolveGlobals?: boolean (default true) to CmsRouteOptions and cmsHomeRouteConfig.
• Threaded it into loadCmsPageInternal(fullPath, resolveGlobals), gating the resolveSiteGlobals() call and falling back to an EMPTY_GLOBALS value of the same shape when false (so the merge path stays identical).
• Made loadCmsPage accept a bare string (back-compat) or { path, resolveGlobals }, and loadCmsHomePage accept { resolveGlobals }; included the flag in the pageInflight dedup key.
• Extracted parseLoadCmsPageInput / parseLoadCmsHomePageInput pure helpers + tests (cmsRouteInput.test.ts).

Default true was deliberate — flipping it off by default would break every already-migrated site whose Theme/Analytics/Wishlist globals now render correctly. resolveGlobals: false restores pre-6.7.4 behavior (:root CSS fallbacks used, no Site/Theme injection).

3. Why #294 can't be merged

The PR was authored against the pre-package-split single-package @decocms/start layout. Its diff imports from relative paths (../cms/loader, ../cms/registry, ../cms/resolve, ../sdk/normalizeUrls, …). After the monorepo split, cmsRoute.ts imports those same symbols from @decocms/blocks/cms and @decocms/blocks/sdk/*. Every touched import line conflicts, so the branch shows as CONFLICTING/DIRTY and is unmergeable.

Recommendation

The fix approach in #294 is still valid, but it has to be re-applied by hand against current packages/tanstack/src/routes/cmsRoute.ts (not rebased). The gating logic is small; the only real translation work is the import paths and matching the current shape of the server functions (which have since gained flags/persistFlags and deferred-section changes).