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

Abierto
  • ¿Algo no está bien?
#6,793 1 comentario 9 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Tranquilo
Stack tecnológico
typescript
Área
performance, web-dev

Línea de trabajo

Empieza por src/compiler/output-targets/dist-hydrate-script/hydrate-factory-closure.ts, src/hydrate/runner/render.ts y src/declarations/stencil-public-compiler.ts. Ejecuta primero las suites de pruebas de hydrate y el benchmark de reproducción enlazado; se considera terminado cuando la nueva opción y la reutilización de la closure funcionan sin romper el comportamiento existente, incluido el renderizado y la serialización de ventanas agrupadas.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
TypeScript
Estrellas
13.2k
Forks
865
Merge medio
2 d 16 h
PR fusionados (30 d)
29

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de stenciljs/core

Todos los issues de stenciljs/core

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.