Stencil FOUC styles should use @layer to avoid cascade conflicts with React 19

Aperta Adatta ai principianti
  • Qualcosa non va?
#6,649 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@johnjenkins ci sta già lavorando.

Dal 29/3/2026.

  • #6657 di @johnjenkins — aperta

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
68/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Tranquilla
Stack tecnologico
css, typescript
Ambito
frontend, web-dev

Direzione di ricerca

Inizia in src/runtime/bootstrap-lazy.ts e controlla come viene popolato l’elemento data-styles e come viene inserito nell’head. Racchiudi il FOUC CSS nella @layer denominata descritta dall’issue, quindi verifica che gli stili generati rimangano a bassa priorità quando React 19 riordina gli stili nell’head e che i componenti idratati e le regole di visibilità per i consumer si comportino correttamente.

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

Descrizione

Stencil v5

Summary

Stencil's FOUC prevention CSS (<style data-styles>) can override consumer CSS when used with React 19, because React 19 reorders <head> elements and changes the cascade order. Wrapping the FOUC styles in @layer would make them lowest-priority by default, fixing the conflict without requiring consumers to patch Stencil.

Current behavior

In bootstrap-lazy.ts, Stencil injects a <style data-styles> tag into <head> with:

market-component-a, market-component-b, ... { visibility: hidden }
[hydrated] { visibility: inherit }

It's inserted via:

head.insertBefore(dataStyles, metaCharset ? metaCharset.nextSibling : head.firstChild);

This relies on source order in <head> — the FOUC styles are placed early so that component-specific and consumer CSS loaded later will override them.

Problem with React 19

React 19 introduced "hoistable" style management — it moves <link rel="stylesheet"> tags to head.firstChild. This pushes <meta charset> down in the head, so when Stencil inserts after metaCharset.nextSibling, the FOUC styles end up after component CSS <link> tags instead of before them.

The result: [hydrated] { visibility: inherit } and consumer class selectors (e.g. .popover { visibility: hidden }) have equal specificity (0,1,0). With the FOUC style now later in source order, it wins — causing components to inherit visibility: hidden from ancestors even after hydration.

This caused a production incident at Square where Market web component popovers became invisible but still captured pointer events, blocking user interaction across the entire dashboard.

Proposed fix

Wrap the FOUC CSS in @layer:

// src/runtime/bootstrap-lazy.ts
- dataStyles.textContent += cmpTags + HYDRATED_CSS;
+ dataStyles.textContent += `@layer stencil-hydration{${cmpTags}${HYDRATED_CSS}}`;

Per the CSS cascade spec, layered styles always lose to unlayered styles, regardless of source order or specificity. This is semantically correct — Stencil's FOUC styles are intentionally low-priority defaults that should yield to any consumer CSS.

Why @layer is the right solution
  • Order-independent: Works regardless of where the <style> tag lands in <head>
  • Semantically correct: FOUC styles are defaults, not overrides
  • No consumer changes needed: Consumers don't need to patch Stencil
  • Framework-agnostic: Fixes the issue for React 19 and any future framework that reorders <head>
  • Browser support: @layer is supported in all modern browsers (Chrome 99+, Firefox 97+, Safari 15.4+). Older browsers silently discard @layer blocks — but the FOUC bug only manifests with React 19 which itself requires modern browsers

Workaround

We're currently working around this by patching Stencil's output at runtime with a MutationObserver that wraps <style data-styles> content in @layer stencil-hydration { ... } before MFEs load.

Environment

  • Stencil: 4.18.0
  • React: 19.x
  • Output target: dist-custom-elements (via @stencil/react-output-target)
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.