DOM de sombra declarativo

O DOM de sombra tradicional é criado por meio de JavaScript (attachShadow). Em páginas renderizadas no servidor, isso significa que a árvore de sombra fica vazia até a execução de JS — o que derrota o objetivo do SSR de entregar HTML completo no primeiro byte. O DOM de sombra declarativo resolve esse problema.

Um <template> com shadowrootmode="open" declara uma raiz de sombra no HTML durante a análise. O navegador anexa automaticamente a raiz de sombra ao elemento pai; o conteúdo do modelo se torna a árvore de sombra. Nenhum JavaScript é necessário.

O DOM de sombra declarativo permite componentes web realmente renderizados no servidor: o servidor emite a árvore de sombra completa em linha, o navegador a analisa e anexa antes da execução de qualquer JS, e o JS de hidratação pode assumir o controle a partir de uma base totalmente renderizada. Em igualdade com o SSR de estruturas.

Os mesmos modos de attachShadow imperativo: shadowrootmode="open" expõe a sombra como element.shadowRoot; shadowrootmode="closed" a oculta. O comportamento é idêntico ao da contraparte anexada por JavaScript.

O navegador anexa a raiz de sombra na primeira vez que encontra o <template shadowrootmode>. Depois de anexado, o modelo é consumido — consultá-lo posteriormente não retorna nada. Isso corresponde ao ciclo de vida de attachShadow: uma sombra existe durante toda a vida do elemento.

Os filhos externos, como o <p> fora do <template> no exemplo, são projetados nos elementos <slot> dentro da árvore de sombra, assim como no DOM de sombra imperativo. A composição é idêntica; apenas o mecanismo de anexação é diferente.

Se <my-card> for um elemento personalizado registrado, o processo de atualização aproveita a raiz de sombra já anexada, em vez de chamar attachShadow novamente. A classe do elemento personalizado pode ler this.shadowRoot em seu connectedCallback sem precisar criá-la.

O Lit-html, os componentes do Astro e várias outras estruturas agora emitem DOM de sombra declarativo como parte de sua saída de SSR. Criar sua própria solução é viável: qualquer sistema de modelos baseado em strings pode escrever o modelo com shadowrootmode.

O DOM de sombra declarativo está disponível no Chrome, Edge, Safari e Firefox. Navegadores mais antigos ignoram o elemento <template> silenciosamente — o conteúdo dentro do modelo fica invisível, o que proporciona uma degradação adequada em ambientes sem suporte.

Para obter suporte mais amplo, um pequeno script pode percorrer o DOM e converter modelos com o atributo de modo da sombra em raízes de sombra reais. Execute-o antes de registrar qualquer elemento personalizado, para garantir que as atualizações posteriores dos componentes encontrem a árvore de sombra esperada.

O DOM de sombra declarativo duplica a estrutura: o conteúdo de <template> permanece no HTML, embora também esteja incorporado à classe do componente. Em páginas com muitos componentes iguais, isso aumenta a carga transferida. Estruturas deduplicam esse conteúdo; soluções de SSR feitas manualmente talvez queiram fazer o mesmo.

Se você distribui componentes web e se preocupa com a renderização no primeiro byte ou com SEO, adote-o agora. O recurso é estável, tem suporte e melhora drasticamente a experiência de SSR para aplicações baseadas em componentes web. Em aplicações que não usam DOM de sombra, ele não se aplica.

Que problema o DOM de sombra declarativo resolve em comparação com attachShadow imperativo?

O DOM de sombra declarativo usa <template shadowrootmode="open"> dentro de um elemento personalizado para anexar uma raiz de sombra durante a análise, sem necessidade de JS. Ele possibilita SSR real para componentes web: a árvore de sombra, os estilos com escopo e os pontos de inserção funcionam antes da hidratação. Há suporte em todos os navegadores modernos; existe uma solução de compatibilidade para os mais antigos. Estruturas como Lit e Astro o emitem automaticamente.