feat: avoid re-evaluating the hydrate platform closure on every SSR render

Aperta
  • Qualcosa non va?
#6,793 1 commento 9 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Tranquilla
Stack tecnologico
typescript
Ambito
performance, web-dev

Direzione di ricerca

Inizia da src/compiler/output-targets/dist-hydrate-script/hydrate-factory-closure.ts, src/hydrate/runner/render.ts e src/declarations/stencil-public-compiler.ts. Esegui prima le suite di test di hydrate e il benchmark di riproduzione collegato; il lavoro è completo quando la nuova opzione e il riutilizzo della closure funzionano senza rompere il comportamento esistente, incluso il rendering e la serializzazione delle finestre raggruppate.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Feature: Want this? Upvote it! Stencil v5
Prerequisites
Describe the Feature Request

Every call to renderToString() / hydrateDocument() from the dist-hydrate-script output re-executes hydrateAppClosure and constructs a fresh MockWindow. hydrateAppClosure is the function in the generated hydrate module that wraps the whole Stencil platform (runtime, vdom) and every component class in the library. The closure exists so the platform can capture the per-call window/document, but re-evaluating it on each render is a fixed cost that scales with the size of the component library rather than with the content being rendered.

This request is for two changes:

  1. Cache the evaluated closure per window (transparent, no API change): in HYDRATE_FACTORY_OUTRO, store the result of hydrateAppClosure(win) on the window object and reuse it when the same window is passed again.
  2. Add an opt-in reuseWindow?: boolean hydrate option. When set, hydrateDocument/renderToString reuse a pooled MockWindow across calls instead of creating and destroying one per render. The pool is keyed by the serializeShadowRoot configuration, because 'scoped' permanently ORs shadowNeedsScopedCss into cmpMeta flags inside the evaluated closure. Fresh head/body elements are swapped in per render, so the rootAppliedStyles WeakMap (keyed on the head node) resets correctly, and renders against a shared window are serialized through an internal queue.
Describe the Use Case

We maintain a design system (~300 shadow components, hydrate module >10 MB) consumed by high-traffic Next.js (App Router) sites via @stencil/react-output-target. Its SSR integration (createComponentForServerSideRendering) calls renderToString once per component boundary in the React tree, so a page with 150 Stencil component boundaries pays the fixed per-call overhead 150 times per request.

Measured with the attached reproduction (300 components, @stencil/core 4.43.5, Node 22):

  • The fixed overhead is ~0.5 ms median per renderToString call. A page with one component instance costs 6% of a page with 200 instances, so the per-call cost comes from platform re-evaluation and window construction, not from rendering.
  • A simulated request (150 component boundaries) spends ~54-62 ms in pure hydrate overhead before any application work.
  • A CPU profile of 500 small renders under the V8 sampling profiler puts 42-49% of all sampled time inside hydrateAppClosure (platform re-evaluation, with registerComponents alone at 19.6% self time), plus ~17% in garbage collection caused by the allocation churn. MockWindow construction is ~6.5%.
  • With both proposed changes the simulated request drops to 7.9 ms (6.7x), the p95 of single-component renders drops from 1.60 ms to 0.19 ms, and hydrateAppClosure and MockWindow fall to 0.0% of profile samples.

Single large one-shot renders are unaffected (1.03x), since their time is real rendering work. The win is specific to the many-small-renders SSR pattern that production React/Next.js integrations use.

Describe Preferred Solution

Implementation is complete on a branch (test/hydrate-platform-reuse, happy to open a PR):

  • src/compiler/output-targets/dist-hydrate-script/hydrate-factory-closure.ts caches hydrateAppClosure(win) on the window object in the factory outro.
  • src/hydrate/runner/render.ts adds the reuseWindow support: a Map of pooled MockWindows keyed by serialized serializeShadowRoot options. Per render, fresh head/body elements are swapped in via replaceChild and the render is queued behind any in-flight render on the same window. destroyWindow/destroyDocument are forced off for pooled windows.
  • src/declarations/stencil-public-compiler.ts documents the new reuseWindow?: boolean option on HydrateDocumentOptions (default false, fully backwards compatible).

Existing test suites pass (test.jest, test.end-to-end).

Describe Alternatives
  • Userland window pooling via the existing destroyWindow: false option is not enough. The platform closure is still re-evaluated per call (the cache in change 1 is not reachable from userland), and internal state such as rootAppliedStyles and the mode/flag mutations under serializeShadowRoot: 'scoped' make naive window reuse incorrect.
  • Caching rendered HTML at the application layer only helps repeated identical pages; personalised and dynamic pages still pay the full cost.
Related Code

Reproduction repo: https://github.com/Armand-Lluka/stencil-hydrate-perf-repro. Run npm install && npm run generate && npm run build && npm run bench. The benchmark prints the baseline table above and, when run against a build containing the proposed changes, a comparison section. node profile.mjs produces the CPU profile attribution.

Additional Information
  • The closure cache (change 1) alone benefits any consumer that passes the same window twice; reuseWindow (change 2) is what makes it reachable through the public renderToString/hydrateDocument API.
  • Concurrency: parallel renderToString calls with reuseWindow: true are serialized per pooled window; callers wanting parallelism can keep the default behaviour.
Lingua principale
TypeScript
Stelle
13.2k
Fork
865
Merge medio
2g 16h
PR unite (30g)
29

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di stenciljs/core

Tutte le issue di stenciljs/core

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.