Aller au contenu

@astrojs/ lit

v4.3.0 GitHub npm Changelog

Cette intégration Astro permet un rendu côté serveur et une hydratation côté client pour vos éléments personnalisés Lit.

Installation

Titre de la section Installation

Astro inclut une commande astro add pour automatiser l’installation des intégrations officielles. Si vous préférez, vous pouvez installer les intégrations manuellement à la place.

Pour installer @astrojs/lit, exécutez ce qui suit depuis le répertoire de votre projet et suivez les instructions :

Fenêtre de terminal
npx astro add lit

Si vous rencontrez des problèmes, n’hésitez pas à nous les signaler sur GitHub et essayez les étapes d’installation manuelle ci-dessous.

Installation manuelle

Titre de la section Installation manuelle

Tout d’abord, installez le paquet @astrojs/lit :

Fenêtre de terminal
npm install @astrojs/lit

La plupart des gestionnaires de paquets installent également les dépendances associées. Si vous voyez un avertissement “Cannot find package ‘lit’” (ou similaire) lorsque vous démarrez Astro, vous devrez installer lit et @webcomponents/template-shadowroot :

Fenêtre de terminal
npm install lit @webcomponents/template-shadowroot

Ensuite, appliquez l’intégration à votre fichier astro.config.* en utilisant la propriété integrations :

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


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

Démarrage

Titre de la section Démarrage

Pour utiliser votre premier composant Lit dans Astro, consultez notre documentation sur les Frameworks UI. Ceci explique :

  • 📦 comment les composants du Framework sont chargés,
  • 💧 les options d’hydratation côté client, et
  • 🤝 les possibilités de mélanger et d’imbriquer les Frameworks.

L’écriture et l’importation d’un composant Lit dans Astro se présentent comme suit :

src/components/my-element.js
import { LitElement, html } from 'lit';


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


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

Le composant est maintenant prêt à être importé via le frontmatter Astro :

src/pages/index.astro
---
import { MyElement } from '../components/my-element.js';
---


<MyElement />

Décorateurs expérimentaux

Titre de la section Décorateurs expérimentaux

Pour utiliser les décorateurs expérimentaux dans Lit, ajoutez ce qui suit à votre fichier tsconfig.json :

tsconfig.json
{
  "compilerOptions": {
    "experimentalDecorators": true,
  }
}

Cela vous permet d’utiliser des décorateurs expérimentaux tels que @customElement et @state pour enregistrer un élément personnalisé et définir une propriété d’état dans votre composant 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>Bonjour à tous ! De ${this.name}</p>`;
    }
}

Polyfills et hydratation

Titre de la section Polyfills et hydratation

Le moteur de rendu gère automatiquement l’ajout des polyfills appropriés pour le support des navigateurs qui n’ont pas Declarative Shadow DOM. Le polyfill fait environ 1.5kB. Si le navigateur supporte Declarative Shadow DOM, moins de 250 octets sont chargés (pour détecter le support).

L’hydratation est également gérée automatiquement. Vous pouvez utiliser les mêmes directives d’hydratation telles que client:load, client:idle et client:visible que vous pouvez utiliser avec d’autres bibliothèques supportées par Astro.

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


<MyElement client:visible />

Ce qui précède ne chargera le JavaScript de l’élément que lorsque qu’il sera visible par l’utilsateur. Comme il s’agit d’un rendu serveur, l’utilisateur ne verra pas de jank ; le chargement et l’hydratation se feront de manière transparente.

Dépannage

Titre de la section Dépannage

Pour obtenir de l’aide, consultez le canal #support sur Discord. Nos sympathiques membres de l’équipe d’assistance sont là pour vous aider !

Vous pouvez également consulter notre Documentation d’intégration Astro pour plus d’informations sur les intégrations.

Les problèmes courants sont listés ci-dessous :

Éléments globaux du navigateur

Titre de la section Éléments globaux du navigateur

Le SSR de l’intégration Lit fonctionne en ajoutant quelques propriétés globales du navigateur à l’environnement global. Certaines des propriétés ajoutées incluent window, document, et location.

Ces propriétés globales peuvent interférer avec d’autres bibliothèques qui pourraient utiliser l’existence de ces variables pour détecter qu’elles s’exécutent dans le navigateur, alors qu’elles s’exécutent en fait dans le serveur. Cela peut provoquer des bogues avec ces bibliothèques.

Pour cette raison, l’intégration de Lit peut ne pas être compatible avec ces types de bibliothèques. Une chose qui peut aider est de changer l’ordre des intégrations lorsque Lit interfère avec d’autres intégrations :

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()]
  });

L’ordre correct peut être différent en fonction de la cause fondamentale du problème. Cependant, il n’est pas garanti que cela corrige tous les problèmes, et certaines bibliothèques ne peuvent pas être utilisées si vous utilisez l’intégration Lit.

Gestionnaires de paquets stricts

Titre de la section Gestionnaires de paquets stricts

Lorsque vous utilisez un gestionnaire de paquets strict comme pnpm, vous pouvez obtenir une erreur telle que ReferenceError : module is not defined lors de l’exécution de votre site. Pour remédier à ce problème, hissez les dépendances Lit avec un fichier .npmrc :

.npmrc
public-hoist-pattern[]=*lit*

Limites

Titre de la section Limites

L’intégration Lit est alimentée par @lit-labs/ssr qui a quelques limitations. Voir leur documentation sur les limitations pour en savoir plus.

  • Astro ne prend pas en charge IntelliSense pour les composants Lit.

Plus d'intégrations

Framework d'interface utilisateur

Adaptateurs SSR

Autres intégrations