Rendez les composants du pack sur le serveur avec Nuxt, Next ou SvelteKit, ou servez-les en HTML statique. Pour chaque cible : un exemple de code, ce que le serveur envoie, ce qui s’active dans le navigateur et les pièges connus.
Provisoire
Les noms de paquets @unisson/<framework> et les composants d’enveloppe <O<Pascal>> (par exemple OButton) sont provisoires : ils suivront le nom définitif du produit. Les balises natives, elles, gardent leur nom bythium-<nom>.
Le même partage vaut pour les quatre cibles.
Un composant du pack est une balise native. Le serveur l’écrit dans la page comme n’importe quelle autre balise ; le navigateur la définit ensuite et lui donne son comportement.
bythium-<nom>, à sa place dans la page.variant, avec les valeurs du catalogue.Le contenu glissé reste lisible avant l’activation : une page rendue sur le serveur garde son sens pendant que le pack se charge.
<!-- Ce que le serveur envoie, avant toute activation -->
<bythium-button variant="primary">
Enregistrer
</bythium-button>Importez l’enveloppe Vue dans une page ou un composant : Nuxt la rend sur le serveur, puis l’hydrate dans le navigateur.
@click.nuxt.config, avec l’option isCustomElement du compilateur. Sinon, Vue la cherche parmi ses propres composants.<ClientOnly> retire son contenu de la réponse du serveur. Gardez-le pour ce qui ne peut vraiment pas se rendre sans navigateur.<!-- Dans le bloc de configuration de la page :
import { OButton } from '@unisson/vue'; -->
<template>
<OButton variant="primary">
Enregistrer
</OButton>
</template>Dans le routeur d’application, une page est un composant serveur. L’enveloppe React s’y rend tant que la page ne lui passe aucune fonction.
'use client'.onClick, placez-le dans un fichier qui commence par 'use client'.window ou customElements pendant le rendu échoue sur le serveur. Placez-le dans un effet.import { OButton } from '@unisson/react';
export default function Page() {
return (
<OButton variant="primary">
Enregistrer
</OButton>
);
}'use client';
import { OButton } from '@unisson/react';
export function BoutonEnregistrer() {
return (
<OButton
variant="primary"
onClick={() => console.log('Clic reçu')}
>
Enregistrer
</OButton>
);
}Importez l’enveloppe Svelte dans une route : SvelteKit rend la page sur le serveur par défaut, puis l’hydrate.
window ou customElements au premier niveau du code de la page s’exécute aussi sur le serveur. Placez-le dans onMount, ou gardez-le derrière browser de $app/environment.export const ssr = false coupe le rendu serveur de toute la route : la réponse ne contient alors plus les composants.<!-- Dans le bloc de code de la page :
import { OButton } from '@unisson/svelte'; -->
<OButton variant="primary">
Enregistrer
</OButton>Sans cadriciel, il n’y a pas d’étape de rendu : le serveur envoie le fichier tel quel, balises natives comprises.
main.js, chargé comme module, définit toutes les balises bythium-<nom> d’un seul import, puis chaque balise présente dans la page s’active.<!-- main.js, chargé comme module dans l’en-tête,
importe le pack et définit les balises -->
<main>
<bythium-button variant="primary">
Enregistrer
</bythium-button>
</main>Deux pièges reviennent dans toutes les cibles.
La définition d’une balise passe par customElements, qui n’existe pas sur le serveur. Quand une page utilise les balises natives plutôt qu’une enveloppe, chargez le pack du côté du navigateur.
// Chargé comme module par la page : navigateur seulement
import '@unisson/web-components';Avant l’activation
Entre l’arrivée de la page et la définition des balises, un composant s’affiche sans son apparence finale. La pseudo-classe :not(:defined) permet de lui réserver sa place ou de l’estomper pendant ce court moment.
/* Tant que la balise n’est pas définie */
bythium-button:not(:defined) {
visibility: hidden;
}Affichez le code source de la page reçue. Les balises bythium-<nom>, leurs attributs et leur contenu glissé doivent s’y trouver.
Désactivez JavaScript dans le navigateur, puis rechargez. Le contenu glissé doit rester lisible et dans le bon ordre.
Réactivez JavaScript et ouvrez la console. Un avertissement d’hydratation signale que le serveur et le navigateur n’ont pas produit la même page.
Page de maquette, contenu cible.Proposer une modification