@astrojs/ lit
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 InstallationAstro 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 :
npx astro add litpnpm astro add lityarn astro add litSi 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 manuelleTout d’abord, installez le paquet @astrojs/lit :
npm install @astrojs/litpnpm add @astrojs/lityarn add @astrojs/litLa 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 :
npm install lit @webcomponents/template-shadowrootpnpm add lit @webcomponents/template-shadowrootyarn add lit @webcomponents/template-shadowrootEnsuite, appliquez l’intégration à votre fichier astro.config.* en utilisant la propriété integrations :
import { defineConfig } from 'astro/config';import lit from '@astrojs/lit';
export default defineConfig({ // ... integrations: [lit()],});Démarrage
Titre de la section DémarragePour 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 :
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 :
---import { MyElement } from '../components/my-element.js';---
<MyElement />Polyfills et hydratation
Titre de la section Polyfills et hydratationLe 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épannagePour 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 navigateurLe 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 :
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 strictsLorsque 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 :
public-hoist-pattern[]=*lit*Limites
Titre de la section LimitesL’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.
