perf(sdk): stop shipping unused code to browser SDK consumers (#37571)

[fmontes]

Fixes #37571

The problem

• The component map ships everything. Static imports make every mapped content type reachable from the client entry, so a page downloads all of them to render three. The reporting customer has 135.
• TinyMCE ships to every page. DotCMSEditableText imported it at top level, but only renders an editor in UVE edit mode — published pages carried it for nothing. One hook import cost ~10 KB gzip.
• No package declared sideEffects. Without it bundlers must assume every module matters, so importing one export from the barrel kept the whole barrel. Tree-shaking couldn't work regardless of how the code was written.
• Contentlet repeated work per instance. Each registered its own dotcms:analytics:ready listener, called getUVEState(), and ran getBoundingClientRect() — a forced reflow feeding only the dev-mode placeholder, so production computed and discarded it. 60 contentlets, 60 times.

What changed

• TinyMCE split into TinyMCEEditor.tsx, loaded via lazy() on entering edit mode. Complements sideEffects: that handles consumers who never use editable text, this handles the many who do but serve published pages.
• sideEffects declared. false for client/uve/types. React gets an allow-list instead — its CSS modules inject styles on import, and a blanket false would drop the grid silently. A test asserts those stylesheets survive.
• DotCMSPageProvider resolves isDevMode and isAnalyticsActive once and shares them via context; useCheckVisibleContent is gated behind dev mode. One listener and one UVE lookup per page instead of per contentlet, and no reflow in production. Memoizing the context value also required hoisting DotCMSLayoutBody's default props — inline {} defeated it.
• Contentlet provides a Suspense boundary. React.lazy suspends and throws without one; next/dynamic brings its own, plain lazy doesn't. Consumers can now map lazy components in any framework with no extra wiring — this is what makes the Astro example work.
• @dotcms/analytics root is framework-neutral. It was export * from './lib/react', so any import pulled React and next/navigation.
• Examples map content types with next/dynamic / React.lazy, and the READMEs explain why — copying the old snippet is how this reached production.

Before and after

Against published 26.9.14-1, gzip:

Import	Before	After
DotCMSLayoutBody	11.3 KB, with TinyMCE	6.1 KB, none
useEditableDotCMSPage	10.2 KB, with TinyMCE	4.2 KB, none
Analytics root	23.3 KB, pulls React	20.8 KB, no React

Matches the audit in the issue, so we measured the same thing.

Runtime, 10 contentlets: analytics listeners 10 → 1, getBoundingClientRect() in production 10 → 0.

Component map — examples/nextjs, its real 14 content types, same components both ways, measured on the main content route:

Map	/[[...slug]] initial JS	On-demand chunks
Static imports	619.7 KB raw / 181.3 KB gzip	6
next/dynamic	594.7 KB raw / 172.7 KB gzip	20

−25 KB raw / −8.6 KB gzip on a site with 14 content types. Scaled to 135, the same conversion moves that route 710.5 → 615.7 KB raw and 189.5 → 177.8 KB gzip, with 141 on-demand chunks instead of 6.

The gzip deltas are modest because the framework shell dominates a small example. The structural change is the durable part: every mapped component leaves the initial download, so the saving grows with how heavy the components actually are — and real component libraries are heavier than this example's.

What this does not fix

Upgrading won't make an existing consumer's map lazy — it's their code, resolved at their build time. One line per content type; the React README has the migration and two traps: a barrel re-exporting content types undoes it, and customRenderers has the same shape. Either next/dynamic or React.lazy works.

examples/nextjs ships npm run analyze so a consumer can check their own build:

JavaScript downloaded before any interaction, per route:

  /[[...slug]]/page              10 chunks    594.7 KB raw    172.7 KB gzip
  /blog/page                     11 chunks    609.7 KB raw    178.6 KB gzip
  /blog/post/[[...slug]]/page    10 chunks    596.3 KB raw    173.2 KB gzip

  20 further chunks load on demand.

Pass a string from a component's output and it reports whether that code is downloaded up front or deferred. There is no built-in alternative: Turbopack prints no First Load JS column, --experimental-analyze never names components, and @next/bundle-analyzer is a webpack plugin that emits nothing on a Turbopack build. All three were tried.

A publishing bug

React's CSS modules inject via a style-inject helper. With preserveModules, rollup copied that helper into dist/libs/sdk/react/node_modules/.pnpm/… and pointed the import there. Resolves locally, but npm strips node_modules from the tarball — published stylesheet chunks would have imported a missing file and thrown for every consumer. Injection is now emitted inline.

Validation

publint runs against every built package. It checks what a bundle probe can't see — exports resolution, emitted files, module type — and found two pre-existing defects on its first run, both fixed here:

• @dotcms/analytics shipped ESM with no "type": "module". Node reparsed every file on import ([MODULE_TYPELESS_PACKAGE_JSON]); older Node fails outright.
• types was shadowed in the generated exports maps. Conditions match in declaration order and @nx/rollup writes module first, so TypeScript can resolve to JavaScript instead of declarations. tools/rollup/types-first.cjs reorders the key — targets untouched.

The gate fails on errors and warnings, with an explicit accept-list. That matters: the analytics defect was a warning, so an errors-only gate would have missed the very bug that justified the tool.

sdk-bundle-budgets keeps only what publint can't do — proving a named module is absent from a bundle. A layout-only import must contain no TinyMCE, editable text or block-editor renderers; a hook-only import no layout modules or CSS; neutral analytics no React or Next. Plus gzip budgets in budgets.json.

A size budget is not a substitute for that. Removing sideEffects from the built @dotcms/react and measuring with size-limit moved DotCMSLayoutBody 4.3 → 4.3 KB and useEditableDotCMSPage 4.0 → 4.6 KB under rolldown, 4.25 → 4.25 and 3.96 → 4.55 under esbuild. Every configuration passed its budget. The named assertion fails and says which modules came back.

Module lists come from esbuild's metafile filtered to bytes actually contributed — the raw input list includes everything a barrel made it parse and then tree-shake, which would report TinyMCE as present in a bundle shipping none.

examples/scripts/check-initial-bundle.mjs resolves a route's real initial chunks (Next client-reference manifests; for Astro, no static importer and reached via import()) and proves an UnusedComponentProbe and the editor are absent.

sdk-bundle-budgets and the publint gate run in the existing frontend CI job. The example check does not — CI never builds the examples — so it is a local check, run when changing a component map or how the SDK is bundled. Every check was verified by breaking what it protects.

Breaking change

@dotcms/analytics root is now neutral. Importing useContentAnalytics or DotContentAnalytics from root needs /react — the subpath already existed and is what the README shows, so only undocumented usage breaks. MIGRATION.md included; package is 0.0.1-beta, unused in this repo.

Also fixed, pre-existing

• nx build sdk-react didn't work at all. @nx/rollup 23's postcss filter never matches absolute module ids, so rollup parsed Column.module.css as JavaScript. Only SDK with CSS.
• examples/astro had 14 type errors and failed its own build, reproduced against published packages. Fixed, since it now has to build to be verified.

Not included

@dotcms/client/page, /navigation, /content, /ai — built, measured at 3–5 KB gzip each, removed. No example used them, and the saving only lands if you avoid sharing a client instance, which the README recommends doing. Four entrypoints to support forever with nothing demonstrating them. That acceptance criterion is deliberately unmet.

Needs a human

Offline checks only, so unproven:

• A lazily-mapped component is fetched and rendered when its content type appears.
• Edit mode loads the editor; inline editing works.
• Live rendering, client-side navigation, SSR, block editor, analytics, fallbacks.

Untouched: examples/angular and angular-ssr don't build before or after — published @dotcms/angular doesn't match their pinned Angular. Needs its own issue.

🤖 Generated with Claude Code

[github-actions]

❌ Linked Issue Needs Team Label

This PR is linked to issue #37571, but that issue has no Team : * label. Every linked issue must be owned by a team for tracking and triage.

How to fix this:

Apply a Team : * label to the linked issue (e.g., Team : Scout, Team : Platform, Team : Falcon, Team : Maintenance). Then push a new commit or edit the PR description to re-run this check.

---

This comment was automatically generated by the issue linking workflow

[claude]

Claude finished @fmontes's task in 4m 23s —— View job

---

PR Review — perf(sdk): stop shipping unused code to browser SDK consumers

• Gather context (diff, changed files)
• Review SDK react runtime changes (Contentlet, DotCMSPageProvider, hooks)
• Review TinyMCE lazy-loading split
• Review bundle-budgets / publint tooling
• Review examples & analytics changes

I reviewed the SDK runtime changes, the TinyMCE split, the CSS-injection publishing fix, the bundle/publint gates, and the example conversions. This is careful, well-tested work — the reasoning is captured in the code comments and the guards are verified by breaking them. One genuine interaction is worth a look before merge; everything else is clean.

New Issues

• 🟡 Medium: core-web/libs/sdk/react/src/lib/next/components/Contentlet/Contentlet.tsx:68 — The new Suspense boundary around CustomComponent interacts with the dev-mode empty-state measurement in a way static imports didn't. useCheckVisibleContent measures height in a useLayoutEffect whose deps are [ref, enabled]. When a content type is mapped lazily (React.lazy/next/dynamic — exactly what this PR promotes), the child is still suspended at mount, so the div measures height 0, haveContent stays false, and style pins minHeight: '4rem'. When the lazy child resolves, React re-renders from the Suspense boundary downward — the Contentlet function body doesn't re-run, and even if it did the effect deps are unchanged, so it never re-measures. Net effect: in edit/dev mode, a lazily-mapped contentlet keeps the empty-state 4rem floor even when it has content. With the old static imports the child rendered synchronously and measured correctly.

  • Assumption: the 4rem minHeight is a floor to make empty contentlets clickable in the editor; taller real content overrides it, so this is cosmetic (extra space under short lazy contentlets), not a break.
  • What to verify: in the UVE editor, map a content type via React.lazy/next/dynamic, render a short instance, and confirm it doesn't get spurious vertical space. If it does, re-measuring after suspense resolves (e.g. a ResizeObserver, or keying the effect off the resolved child) would fix it. This overlaps the "edit mode / inline editing needs a human" items you already flagged.

  Fix this →

Notes (non-blocking, not defects)

• core-web/libs/sdk/react/rollup.migrated.config.js:32 — replaceBrokenPostcssPlugin reads options.extractCss but is passed nxOptions; if that key is ever named differently upstream, extract silently falls back to falsy. That happens to be the desired value here (inline injection), so it works — just fragile to an Nx rename. Worth a comment pinning the expectation.
• injectStyleInline idempotency comparing textContent (not css.length) is correct and the SSR guard is right — good catch on the published-tarball node_modules stripping.
• The tinymceScriptSrc needle in check-initial-bundle.mjs (rather than bare tinymce) and the mustExistSomewhere counter-check are exactly the right way to avoid a false pass — no issue.

The runtime test (DotCMSLayoutBody.runtime.test.tsx) covers the one-listener / no-reflow-in-prod guarantees, and the bundle-budget probes cover module absence. The lazy/dev-mode measurement interaction above is the one behavior not covered by a test.

Unrelated: the automation comment about the linked issue #37571 missing a Team : * label still needs a human to apply the label — I can't set it.

• sdk-components