@astrojs/ lit

Esta integración de Astro permite renderización en el servidor e hidratación en el cliente para tus elementos personalizados de Lit.

Instalación

Sección titulada Instalación

Astro incluye un comando astro add para automatizar la configuración de las integraciones oficiales. Si lo prefieres, puedes instalar las integraciones manualmente en su lugar.

Para instalar @astrojs/lit, ejecuta lo siguiente desde el directorio de tu proyecto y sigue las indicaciones:

npm

npx astro add lit

pnpm

pnpm astro add lit

Yarn

yarn astro add lit

Si tienes algún problema, no dudes en informárnoslo en GitHub y prueba los pasos de instalación manual a continuación.

Instalación manual

Sección titulada Instalación manual

Primero, instala el paquete @astrojs/lit:

npm

npm install @astrojs/lit

pnpm

pnpm add @astrojs/lit

Yarn

yarn add @astrojs/lit

La mayoría de los gestores de paquetes también instalarán las dependencias asociadas. Sin embargo, si ves un aviso “No se puede encontrar el paquete ‘lit’” (o similar) al iniciar Astro, tendrás que instalar lit y @webcomponents/template-shadowroot:

npm

npm install lit @webcomponents/template-shadowroot

pnpm

pnpm add lit @webcomponents/template-shadowroot

Yarn

yarn add lit @webcomponents/template-shadowroot

Luego, aplica la integración a tu archivo astro.config.* usando la propiedad integrations:

astro.config.mjs

import { defineConfig } from 'astro/config';
import lit from '@astrojs/lit';

export default defineConfig({
  // ...
  integrations: [lit()],
});

Empezando

Sección titulada Empezando

Para usar tu primer componente React en Astro, dirígete a nuestra documentación de frameworks UI. Explorarás:

• 📦 como se cargan los componentes de framework,
• 💧 opciones de hidratación del lado del cliente, y
• 🤝 oportunidades para mezclar y anidar frameworks juntos

Escribir e importar un componente de Lit en Astro se ve así:

src/components/my-element.js

import { LitElement, html } from 'lit';

export class MyElement extends LitElement {
  render() {
    return html`<p>Hello world! From my-element</p>`;
  }
}

customElements.define('my-element', MyElement);

Ahora, el componente está listo para ser importado a través del frontmatter de Astro:

src/pages/index.astro

---
import { MyElement } from '../components/my-element.js';
---

<MyElement />

Nota

Lit requiere que los globales del navegador, como HTMLElement y customElements, estén presentes. Por esta razón, el renderizador de Lit simula estos globales en el servidor para que Lit pueda funcionar. Es posible que te encuentres con bibliotecas que funcionen incorrectamente debido a esto.

Decoradores Experimentales

Sección titulada Decoradores Experimentales

Para utilizar los decoradores experimentales en Lit, agrega las siguientes lineas en tu archivo tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "experimentalDecorators": true,
  }
}

Esto te permite utilizar los decoradores experimentales como @customElement y @state para registrar un elemento personalizado y definir una propiedad de estado en tu componente Lit:

src/components/my-element.ts

import { LitElement, html } from "lit";
import { customElement, state } from "lit/decorators.js";

@customElement("my-element")
export class MyElement extends LitElement {
    @state() name = "my-element";

    override render() {
        return html`<p>¡Hola Mundo! Desde ${this.name}</p>`;
    }
}

Polyfills y Hidratación

Sección titulada Polyfills y Hidratación

El renderizador maneja automáticamente la adición de los polifills adecuados para brindar soporte en navegadores que no tienen Declarative Shadow DOM. El polifill tiene un tamaño aproximado de 1.5kB. Si el navegador admite Declarative Shadow DOM, se cargan menos de 250 bytes (para detectar la compatibilidad con la función).

La hidratación también se maneja automáticamente. Puedes usar las mismas directivas de hidratación, como client:load, client:idle y client:visible, como lo harías con otras bibliotecas compatibles con Astro.

---
import { MyElement } from '../components/my-element.js';
---

<MyElement client:visible />

Lo anterior solo cargará el JavaScript del elemento cuando el usuario lo haya desplazado a la vista. Dado que se renderiza en el servidor, el usuario no verá ningún parpadeo; se cargará y se hidratará de manera transparente.

Solución de problemas

Sección titulada Solución de problemas

Para obtener ayuda, consulta el canal #support en Discord. ¡Nuestros amables miembros del Equipo de Soporte están aquí para ayudar!

También puedes consultar nuestra documentación de integración de Astro para obtener más información sobre las integraciones.

A continuación se enumeran algunos problemas comunes:

Globales del navegador

Sección titulada Globales del navegador

La renderización del lado del servidor (SSR) de la integración de Lit funciona mediante la adición de algunas propiedades globales del navegador al entorno global. Algunas de las propiedades que se agregan incluyen window, document y location.

Estos globales pueden interferir con otras bibliotecas que utilizan la existencia de estas variables para detectar que se están ejecutando en el navegador, cuando en realidad se están ejecutando en el servidor. Esto puede provocar errores en estas bibliotecas.

Debido a esto, la integración de Lit puede no ser compatible con este tipo de bibliotecas. Una cosa que puede ayudar es cambiar el orden de las integraciones cuando Lit interfiere con otras integraciones:

astro.config.mjs

  import { defineConfig } from 'astro/config';
  import vue from '@astrojs/vue';
  import lit from '@astrojs/lit';

  export default defineConfig({
    integrations: [vue(), lit()]
    integrations: [lit(), vue()]
  });

El orden correcto puede variar según la causa subyacente del problema. Sin embargo, no se garantiza que esto solucione todos los problemas, y algunas bibliotecas no se pueden utilizar si estás utilizando la integración de Lit debido a esto.

Gestores de paquetes estrictos

Sección titulada Gestores de paquetes estrictos

Cuando utilizas un gestor de paquetes estricto como pnpm, es posible que obtengas un error como ReferenceError: module is not defined al ejecutar tu sitio. Para solucionar esto, debes elevar las dependencias de Lit con un archivo .npmrc:

.npmrc

public-hoist-pattern[]=*lit*

Limitaciones

Sección titulada Limitaciones

• La integración de Lit está impulsada por @lit-labs/ssrque tiene algunas limitaciones. Consulta su documentación de limitaciones para obtener más información al respecto.

• Astro no admite componentes IntelliSense para Lit.

Más integraciones

Frameworks UI

• 

  @astrojs/alpinejs

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

Adaptadores SSR

• 

  @astrojs/cloudflare

• 

  @astrojs/node

• 

  @astrojs/netlify

• 

  @astrojs/vercel

Otras integraciones

• 

  @astrojs/db

• 

  @astrojs/mdx

• 

  @astrojs/markdoc

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind