Shadow DOM declarativo

El Shadow DOM tradicional se crea mediante JavaScript (attachShadow). En páginas renderizadas en el servidor, esto significa que el árbol shadow está vacío hasta que se ejecuta JavaScript, lo que contradice el propósito del SSR de entregar HTML completo desde el primer byte. Declarative Shadow DOM resuelve este problema.

Un <template> con shadowrootmode="open" declara un shadow root en HTML durante el análisis. El navegador adjunta automáticamente el shadow root al elemento padre; el contenido de template se convierte en el árbol shadow. No se necesita JavaScript.

Declarative Shadow DOM permite usar verdaderos web components renderizados en el servidor: el servidor emite el árbol shadow completo en línea, el navegador lo analiza y lo adjunta antes de ejecutar cualquier JS, y el JS de hidratación puede tomar el control desde una base completamente renderizada. Está en igualdad de condiciones con el SSR de los frameworks.

Son los mismos modos que en attachShadow imperativo: shadowrootmode="open" expone el shadow como element.shadowRoot; shadowrootmode="closed" lo oculta. El comportamiento es idéntico al de su equivalente adjunto mediante JavaScript.

El navegador adjunta el shadow root la primera vez que encuentra <template shadowrootmode>. Una vez adjunto, template se consume; si se consulta más adelante, no se devuelve nada. Esto coincide con el ciclo de vida de attachShadow: un shadow existe durante toda la vida del elemento.

Los hijos light (el <p> situado fuera de <template> en el ejemplo) se proyectan en los elementos <slot> dentro del árbol shadow, igual que con Shadow DOM imperativo. La composición es idéntica; solo cambia el mecanismo de adjunción.

Si <my-card> es un custom element registrado, el proceso de actualización recoge el shadow root ya adjunto en lugar de volver a llamar a attachShadow. La clase del custom element puede leer this.shadowRoot en su connectedCallback sin necesidad de crearlo.

Lit-html's render, los componentes de Astro y varios frameworks más ya emiten Declarative Shadow DOM como parte de su salida de SSR. Crear una solución propia es viable: cualquier sistema de plantillas basado en cadenas puede escribir el template con shadowrootmode.

Declarative Shadow DOM está disponible en Chrome, Edge, Safari y Firefox. Los navegadores antiguos ignoran silenciosamente el elemento <template>; el contenido dentro de template permanece invisible, lo que proporciona una degradación progresiva adecuada en entornos que no lo admiten.

Para ampliar la compatibilidad, un script pequeño puede recorrer el DOM y convertir template[shadowrootmode] en shadow roots reales. Ejecútelo antes de registrar cualquier custom element para garantizar que las actualizaciones posteriores de los componentes encuentren el árbol shadow esperado.

Declarative Shadow DOM duplica la estructura: el contenido de <template> está presente en el HTML aunque también esté integrado en la clase del componente. En páginas con muchos componentes iguales, esto aumenta el tamaño del payload. Los frameworks eliminan duplicados; en una implementación de SSR propia quizá le convenga hacer lo mismo.

Si distribuye web components y le importan el renderizado desde el primer byte o el SEO, adóptelo ahora. La función es estable, cuenta con compatibilidad y mejora enormemente el SSR de las aplicaciones basadas en web components. No se aplica a aplicaciones que no utilizan Shadow DOM.

¿Qué problema resuelve Declarative Shadow DOM en comparación con attachShadow imperativo?

Declarative Shadow DOM utiliza <template shadowrootmode="open"> dentro de un custom element para adjuntar un shadow root durante el análisis, sin necesidad de JS. Permite un SSR real para web components: el árbol shadow, los estilos encapsulados y los slots funcionan antes de la hidratación. Es compatible con todos los navegadores modernos y hay un polyfill disponible para los más antiguos. Los frameworks (Lit, Astro) lo emiten automáticamente.