Proposal: make the hydrate/ssr output tree-shakable for V5

[Burzmalian]

Proposal: make the ssr output tree-shakable

This is scoped to land alongside the V5 dist-hydrate-script → ssr rename, the Rolldown swap, and the move to @stencil/core/runtime/server. None of those changes on their own make the hydrate bundle tree-shakable — the closure architecture and treeshake: false are the actual blockers. Doing this in V5 piggybacks on breaks already happening so we don't need a second breaking release later.

Why today's bundle isn't shakable

Every component, the runtime, and the platform are stringified into one hydrateFactory($stencilWindow, ...) { ... } IIFE in hydrate-factory-closure.ts. The Rollup build in generate-hydrate-app.ts is forced to treeshake: false with inlineDynamicImports: true, and the emitted bundle is post-processed with regex string replacement in write-hydrate-outputs.ts and relocate-hydrate-context.ts (e.g. injecting $stencilTagTransform, un-commenting modeResolutionChain). Those regex passes break under any DCE/minification, which is why tree-shaking has to stay off. ESM-by-default (already in the V5 plan) is necessary but not sufficient — the .mjs file still contains the same opaque closure today.

Step-by-step plan

1. Replace the hydrateFactory closure with a context-object pattern

Drop HYDRATE_FACTORY_INTRO / HYDRATE_FACTORY_OUTRO and the var window = $stencilWindow; var Element = $stencilWindow.Element; ... shadowing. Plumb the mock window via an explicit setHydrateContext(win) call (or a context object passed into hydrateApp). Platform code reads from this context instead of relying on closure-scoped vars. Remove the declare const $stencilTagTransform hack in src/hydrate/platform/index.ts — tag transforms become a normal import.

This is the keystone change. Everything else is gated on it.

2. Switch the inner factory build to ESM and remove inlineDynamicImports

In bundle-hydrate-factory.ts and generate-hydrate-app.ts, drop format: 'cjs', esModule: false, strict: false, and inlineDynamicImports: true. Component lazy chunks then survive as separate modules a downstream bundler can shake. CJS becomes a thin wrapper over ESM.

3. Replace regex post-processing with Rolldown plugins

The string-injection passes in write-hydrate-outputs.ts and relocate-hydrate-context.ts must become AST-aware Rolldown plugins. They'll otherwise break the moment DCE renames or removes the functions they're matching on. The Rollup → Rolldown swap is the right moment to rewrite these rather than porting the regex hacks forward. Hard prerequisite for step 4.

4. Flip treeshake: false → true

Trivial line change in generate-hydrate-app.ts, valid only after steps 1–3.

5. Remove module-level side effects in the server platform

In src/hydrate/platform/index.ts:

• export const win = window; → lazy accessor backed by the context object from step 1.
• cmpModules, styles, modeResolutionChain, plt initializers → annotate with /*@__PURE__*/ so unreferenced ones can be dropped.

6. Mark outputs side-effect-free

• Add sideEffects: false to scripts/esbuild/internal-platform-hydrate.ts's writePkgJson call. All sibling internal packages already do this — hydrate is the lone exception.
• Document in the migration guide that users adding exports for dist/ssr/hydrate.js should set sideEffects: false. Add a stencil migrate hint.

7. Split the runner barrel

src/hydrate/runner/index.ts re-exports renderToString, ssrDocument, streamToString, serializeDocumentToString, createWindowFromHtml, serializeProperty/deserializeProperty, and setTagTransformer/transformTag from one module that eagerly imports @hydrate-factory, @platform, mock-doc, and three compiler/html/* helpers. Either:

• (preferred) expose them as subpath exports (runtime/server/render, .../props, .../window, .../tag-transform) in the package exports map; or
• at minimum, lazy-load the heavy imports inside render.ts (removeUnusedStyles, relocateMetaCharset, updateCanonicalLink) so they only load on the code paths that use them.

8. Audit BUILD.* conditionals

Once Rolldown is shaking, getHydrateBuildConditionals becomes effective again — if (BUILD.shadowDom) / if (BUILD.scoped) branches can actually be dropped. Worth a pass to find conditions previously force-enabled because shaking didn't run.

9. Drop the stub exports

After step 1, the setTagTransformer = null as any / transformTag = null as any stubs in src/hydrate/runner/hydrate-factory.ts (which existed only to be string-replaced by the post-processor) become honest re-exports from the platform module.

[johnjenkins]

I guess I'd want to understand why first? 🙂

It's not something people have been asking for; it feels like a more work for a few less KBs (the difference between the minimal runtime and a full runtime with no DCE is ~15KB non gzip)

Component lazy chunks then survive as separate modules a downstream bundler can shake

Again - this doesn't feel like a 'win' to me - atm it you drop it into your node backend and it works.
In the next iteration, the reliance on node:stream has been replaced, so users can also just drop it into edge environments too.
Also, in the next iteration it's been tweaked to build into wasm too so users can run it agnostically in any language they like.

[Burzmalian]

yeah considering this plan you are probably right. what im noticing as an end user in a react app for example is that the hydrate script is bundling the entire library instead of only the components that are used. wish we could get tree shaking working for that script so the hydrate script is only composed of the components that are actually imported.

I will revise this a bit and try to come up with something that makes sense

[johnjenkins]

That’s purely an issue for the react (/ cursed next js 😄) output I feel? - generally speaking, people are fine with the hydrate script because it only lives on a server - you call it once and get the output you need.
With next js we’re forced to do per-component output. But should be ok as long as it doesn’t end up in the client?

[Burzmalian]

it does work fine as is, i just saw some potential for perf improvements here. they way its structured now, it makes tree shaking the script impossible, if the hydrate script only contains the components imported, its going to be much smaller to call and parse, even if it is on the server. From what im seeing in stencil core, it might be a large lift to make this friendly for that, so maybe the effort/benefit is not worth it. thanks for the feedback!