Shadow DOM dichiarativo

Lo Shadow DOM tradizionale viene creato tramite JavaScript (attachShadow). Per le pagine renderizzate dal server, ciò significa che l'albero shadow è vuoto finché non viene eseguito JavaScript, vanificando lo scopo dell'SSR di fornire HTML completo già al primo byte. Declarative Shadow DOM risolve questo problema.

Un <template> con shadowrootmode="open" dichiara uno shadow root nell'HTML al momento del parsing. Il browser collega automaticamente lo shadow root all'elemento padre; il contenuto del template diventa l'albero shadow. Non è necessario JavaScript.

Declarative Shadow DOM abilita veri Web Components renderizzati dal server: il server emette inline l'intero albero shadow, il browser lo analizza e lo collega prima dell'esecuzione di qualsiasi JS, quindi il codice JS di hydration può subentrare partendo da una base completamente renderizzata. È sullo stesso piano dell'SSR dei framework.

Le modalità sono le stesse di attachShadow imperativo: shadowrootmode="open" espone lo shadow come element.shadowRoot; shadowrootmode="closed" lo nasconde. Il comportamento è identico a quello della controparte collegata tramite JavaScript.

Il browser collega lo shadow root la prima volta che incontra <template shadowrootmode>. Una volta collegato, il template viene consumato: se lo si cerca in seguito non viene restituito nulla. Questo corrisponde al ciclo di vita di attachShadow: uno shadow esiste per tutta la vita dell'elemento.

I figli del light DOM, ovvero il <p> esterno al <template> nell'esempio, vengono proiettati negli elementi <slot> all'interno dell'albero shadow, proprio come nel caso dello Shadow DOM imperativo. Il modello di composizione è identico; cambia solo il meccanismo di collegamento.

Se <my-card> è un custom element registrato, il processo di upgrade utilizza lo shadow root già collegato invece di chiamare nuovamente attachShadow. La classe del custom element può leggere this.shadowRoot nel proprio connectedCallback senza doverlo creare.

Il render di Lit-html, i componenti Astro e diversi altri framework ora emettono Declarative Shadow DOM come parte del loro output SSR. È possibile anche realizzare un'implementazione personalizzata: qualunque sistema di template basato su stringhe può scrivere il template shadowrootmode.

Declarative Shadow DOM è disponibile in Chrome, Edge, Safari e Firefox. I browser meno recenti ignorano silenziosamente l'elemento <template>: il contenuto al suo interno resta invisibile, garantendo un degrado graduale per gli ambienti che non lo supportano.

Per ottenere un supporto più ampio, un piccolo script può attraversare il DOM e convertire template[shadowrootmode] in veri shadow root. Lo esegua prima di registrare qualsiasi custom element, così gli upgrade successivi dei componenti troveranno l'albero shadow previsto.

Declarative Shadow DOM duplica la struttura: il contenuto di <template> è presente nell'HTML anche se è incorporato nella classe del componente. Per le pagine con molti componenti uguali, questo aumenta le dimensioni del payload. I framework eliminano i duplicati; anche un SSR realizzato manualmente potrebbe voler fare lo stesso.

Se distribuisce Web Components e considera importanti il rendering al primo byte o la SEO, lo adotti ora. La funzionalità è stabile, supportata e migliora notevolmente l'SSR delle applicazioni basate sui Web Components. Non è applicabile alle applicazioni che non usano lo Shadow DOM.

Quale problema risolve Declarative Shadow DOM rispetto ad attachShadow imperativo?

Declarative Shadow DOM usa <template shadowrootmode="open"> all'interno di un custom element per collegare uno shadow root al momento del parsing, senza bisogno di JS. Abilita un vero SSR per i Web Components: l'albero shadow, gli stili con scope e gli slot funzionano già prima dell'hydration. È supportato in tutti i browser moderni; per quelli meno recenti è disponibile un polyfill. I framework, come Lit e Astro, lo emettono automaticamente.