Créer un Web Component avec SvelteKit : Guide complet étape par étape

Créer un projet SvelteKit pour un Web Component

Pour créer un Web Component avec SvelteKit, commencez par initialiser un nouveau projet :

npx sv create example-webcomponent
cd example-webcomponent
npm run dev

Configuration du projet

Lors de l’installation, sélectionnez les options suivantes :

• SvelteKit minimal
• TypeScript
• Prettier et ESLint (recommandé)
• npm

Lancer le projet en local

Une fois l’installation terminée, ouvrez votre navigateur à l’adresse suivante :

http://localhost:5173/

Si la page s’affiche correctement, votre projet SvelteKit est prêt à être utilisé pour créer un Web Component.

Installer SCSS dans SvelteKit

Pour utiliser SCSS dans votre projet SvelteKit, vous devez installer le compilateur Sass en tant que dépendance de développement :

npm install -D sass-embedded

Une fois installé, SvelteKit détectera automatiquement SCSS dans vos fichiers .svelte via les balises <style lang="scss">.

Créer un Web Component avec SvelteKit

Nous allons maintenant créer notre premier Web Component avec SvelteKit. Pour cela, créez un fichier dans le dossier src/lib :

touch src/lib/my-web-component.svelte

Ajoutez ensuite le code suivant :

<svelte:options customElement="my-web-component" />

<script lang="ts">
</script>

<p>Hello World</p>

<style lang="scss">
  p {
    color: red;
  }
</style>

👉 L’attribut customElement="my-web-component" définit le nom de votre Web Component. Ce nom doit obligatoirement contenir un tiret (ex : my-component) pour être valide en HTML.

Configurer SvelteKit pour les Web Components

Pour activer la création de Web Components avec SvelteKit, vous devez modifier le fichier svelte.config.js et activer l’option customElement.

Ajoutez la configuration suivante :

compilerOptions: {
  customElement: true
}

Voici un exemple complet de configuration :

import adapter from '@sveltejs/adapter-static';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
    adapter: adapter()
  },
  vitePlugin: {
    dynamicCompileOptions: ({ filename }) =>
      filename.includes('node_modules') ? undefined : { runes: true }
  },
  compilerOptions: {
    customElement: true
  }
};

export default config;

👉 L’option customElement: true permet à SvelteKit de compiler vos composants en Web Components natifs utilisables dans n’importe quel environnement.

Configurer le build du Web Component avec Vite

Pour générer un Web Component réutilisable, vous devez configurer un build spécifique avec Vite. Cela permet d’exporter votre composant sous forme de fichier JavaScript utilisable dans n’importe quel projet.

Créez un fichier de configuration dédié :

touch vite.config.webcomponent.js

Ajoutez la configuration suivante :

import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { name, version } from './package.json';

export default defineConfig({
  plugins: [svelte()],
  publicDir: 'playground',
  build: {
    lib: {
      entry: './src/lib/my-web-component.svelte',
      fileName: `${name}-${version}`,
      name,
      formats: ['es']
    },
    outDir: 'static/webcomponent',
    minify: 'esbuild'
  }
});

Ajouter le script de build

Ajoutez le script suivant dans votre fichier package.json :

"build:wc": "vite build -c vite.config.webcomponent.js"

Vous pourrez ensuite générer votre Web Component avec la commande :

npm run build:wc

Tester le Web Component dans SvelteKit

Une fois le build généré, vous pouvez tester votre Web Component directement dans votre projet SvelteKit.

Importer le script

Dans le fichier +page.svelte, ajoutez le script généré dans la balise <svelte:head> :

<svelte:head>
  <script type="module" src="/webcomponent/example-webcomponent-0.0.1.js"></script>
</svelte:head>

Utiliser le Web Component

Ajoutez ensuite votre composant dans le template :

<my-web-component></my-web-component>

Exemple complet

<svelte:head>
  <script type="module" src="/webcomponent/example-webcomponent-0.0.1.js"></script>
</svelte:head>

<h1>Welcome to SvelteKit</h1>
<p>
  Visit <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> to read the documentation
</p>

<my-web-component></my-web-component>

Lancer le projet

Exécutez les commandes suivantes :

npm run build:wc
npm run dev

Si tout est correctement configuré, votre Web Component devrait s’afficher dans la page.

Ajouter des propriétés (props) à un Web Component SvelteKit

Vous pouvez rendre votre Web Component dynamique en lui passant des propriétés (props).

Définir une prop dans le composant

Dans votre fichier my-web-component.svelte :

let { name = 'World' } = $props();

Utiliser la prop dans le template

<p>Hello {name}</p>

Composant complet

<svelte:options customElement="my-web-component" />

<script lang="ts">
  let { name = 'World' } = $props();
</script>

<p>Hello {name}</p>

<style lang="scss">
  p {
    color: red;
  }
</style>

Utiliser la prop dans le HTML

Vous pouvez maintenant passer une valeur directement depuis le HTML :

<my-web-component name="Bryan"></my-web-component>

👉 Le texte affiché sera alors : Hello Bryan

Exposer des méthodes JavaScript (API) dans un Web Component

Vous pouvez exposer des méthodes JavaScript pour interagir avec votre Web Component depuis l’extérieur (JavaScript, framework, ou HTML).

Dans cet exemple, nous allons créer un getter et un setter pour manipuler la propriété name.

Créer les méthodes

const getName = (): string => {
  return name;
};

const setName = (newName: string) => {
  name = newName;
};

Exposer les méthodes via le Web Component

Utilisez $host() pour attacher les méthodes à l’élément DOM :

$effect(() => {
  const host = $host();

  Object.assign(host, {
    getName,
    setName
  });
});

Composant complet

<svelte:options customElement="my-web-component" />

<script lang="ts">
  let { name = 'World' } = $props();

  const getName = (): string => {
    return name;
  };

  const setName = (newName: string) => {
    name = newName;
  };

  $effect(() => {
    const host = $host();

    Object.assign(host, {
      getName,
      setName
    });
  });
</script>

<p>Hello {name}</p>

<style lang="scss">
  p {
    color: red;
  }
</style>

Utiliser les méthodes depuis JavaScript

Vous pouvez maintenant interagir avec votre Web Component depuis un script externe :

const el = document.querySelector('my-web-component');

// Modifier la valeur
el.setName('Bryan');

// Récupérer la valeur
console.log(el.getName());

👉 Cette approche permet de créer une véritable API JavaScript pour votre Web Component.

Interagir avec un Web Component depuis SvelteKit

Vous pouvez interagir directement avec votre Web Component depuis SvelteKit en accédant à ses méthodes via une référence JavaScript.

Déclarer une référence vers le composant

let wc: HTMLElement;

Lier le Web Component

Utilisez bind:this pour récupérer une référence vers le composant :

<my-web-component bind:this={wc} name="User"></my-web-component>

Ajouter un typage TypeScript (recommandé)

Pour éviter les erreurs dans votre IDE, vous pouvez typer les méthodes exposées :

let wc: HTMLElement & {
  getName: () => string;
  setName: (newName: string) => void;
};

Interagir avec le composant

Vous pouvez ensuite appeler les méthodes dans le cycle de vie onMount :

import { onMount } from 'svelte';

onMount(() => {
  console.log('Current Name:', wc.getName());

  setTimeout(() => {
    console.log('== Change Name ==');
    wc.setName('Admin');
    console.log('Current Name:', wc.getName());
  }, 1000);
});

Exemple complet

<script lang="ts">
  import { onMount } from 'svelte';

  let wc: HTMLElement & {
    getName: () => string;
    setName: (newName: string) => void;
  };

  onMount(() => {
    console.log('Current Name:', wc.getName());

    setTimeout(() => {
      console.log('== Change Name ==');
      wc.setName('Admin');
      console.log('Current Name:', wc.getName());
    }, 1000);
  });
</script>

<svelte:head>
  <script type="module" src="/webcomponent/example-webcomponent-0.0.1.js"></script>
</svelte:head>

<h1>Welcome to SvelteKit</h1>
<p>
  Visit <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> to read the documentation
</p>

<my-web-component bind:this={wc} name="User"></my-web-component>

Résultat dans la console

Current Name: User
== Change Name ==
Current Name: Admin

👉 Le Web Component est mis à jour dynamiquement, et les changements sont visibles à la fois dans le DOM et dans la console.

Utiliser les slots dans un Web Component SvelteKit

Les slots permettent d’injecter du contenu HTML depuis l’extérieur dans votre Web Component. C’est essentiel pour rendre votre composant flexible et réutilisable.

Ajouter un slot dans le composant

Dans votre fichier my-web-component.svelte, ajoutez simplement :

<slot />

Modifier le template

Par exemple, remplacez :

<p>Hello {name}</p>

Par :

<p>Before Hello {name}</p>
<slot />
<p>After Hello {name}</p>

Composant complet

<svelte:options customElement="my-web-component" />

<script lang="ts">
  let { name = 'World' } = $props();

  const getName = (): string => {
    return name;
  };

  const setName = (newName: string) => {
    name = newName;
  };

  $effect(() => {
    const host = $host();

    Object.assign(host, {
      getName,
      setName
    });
  });
</script>

<p>Before Hello {name}</p>
<slot />
<p>After Hello {name}</p>

<style lang="scss">
  p {
    color: red;
  }
</style>

Passer du contenu depuis la page SvelteKit

Vous pouvez maintenant injecter du contenu directement dans votre Web Component :

<my-web-component bind:this={wc} name="User">
  <p>New content</p>
</my-web-component>

Exemple complet dans SvelteKit

<script lang="ts">
  import { onMount } from 'svelte';

  let wc: HTMLElement & {
    getName: () => string;
    setName: (newName: string) => void;
  };

  onMount(() => {
    console.log('Current Name:', wc.getName());

    setTimeout(() => {
      console.log('== Change Name ==');
      wc.setName('Admin');
      console.log('Current Name:', wc.getName());
    }, 1000);
  });
</script>

<svelte:head>
  <script type="module" src="/webcomponent/example-webcomponent-0.0.1.js"></script>
</svelte:head>

<h1>Welcome to SvelteKit</h1>
<p>
  Visit <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> to read the documentation
</p>

<my-web-component bind:this={wc} name="User">
  <p>New content</p>
</my-web-component>

👉 Le contenu passé entre les balises du Web Component sera injecté à l’emplacement du <slot />.

Ajouter une image dans un Web Component SvelteKit

Pour intégrer une image dans un Web Component avec SvelteKit, vous ne pouvez pas utiliser directement le dossier static. Vous devez importer l’image comme un module afin qu’elle soit correctement incluse dans le build.

Importer une image

Dans votre composant my-web-component.svelte :

import logo from './assets/favicon.svg';

Utiliser l’image dans le template

<img src={logo} alt="SvelteKit Logo" />

Composant complet

<svelte:options customElement="my-web-component" />

<script lang="ts">
  import logo from './assets/favicon.svg';

  let { name = 'World' } = $props();

  const getName = (): string => {
    return name;
  };

  const setName = (newName: string) => {
    name = newName;
  };

  $effect(() => {
    const host = $host();

    Object.assign(host, {
      getName,
      setName
    });
  });
</script>

<img src={logo} alt="SvelteKit Logo" />

<p>Before Hello {name}</p>
<slot />
<p>After Hello {name}</p>

<style lang="scss">
  p {
    color: red;
  }
</style>

👉 L’image sera automatiquement optimisée et incluse dans le bundle final du Web Component.

Écouter les événements d’un Web Component dans SvelteKit

Pour communiquer depuis un Web Component vers votre application, vous pouvez émettre des événements personnalisés (CustomEvent) et les écouter côté client.

Créer un événement dans le composant

Ajoutez un bouton et une fonction dans votre composant :

<button on:click={handleClick}>Test</button>

const handleClick = () => {
  const event = new CustomEvent('test', {
    detail: {
      name
    }
  });

  $host().dispatchEvent(event);
};

Créer une API pour écouter les événements

Pour simplifier l’écoute des événements, vous pouvez exposer une méthode on :

const on = (event: string, callback: Function) => {
  $host().addEventListener(event, (e: any) => callback(e.detail));
};

Exposer la méthode

$effect(() => {
  const host = $host();

  Object.assign(host, {
    getName,
    setName,
    on
  });
});

Mettre à jour le typage côté SvelteKit

let wc: HTMLElement & {
  getName: () => string;
  setName: (newName: string) => void;
  on: (event: string, callback: Function) => void;
};

Écouter l’événement dans la page

wc.on('test', (detail: { name: string }) => {
  console.log(detail);
});

Exemple complet côté SvelteKit

<script lang="ts">
  import { onMount } from 'svelte';

  let wc: HTMLElement & {
    getName: () => string;
    setName: (newName: string) => void;
    on: (event: string, callback: Function) => void;
  };

  onMount(() => {
    wc.on('test', (detail: { name: string }) => {
      console.log(detail);
    });
  });
</script>

<svelte:head>
  <script type="module" src="/webcomponent/example-webcomponent-0.0.1.js"></script>
</svelte:head>

<my-web-component bind:this={wc} name="Admin"></my-web-component>

Résultat

{ name: 'Admin' }

👉 Cette approche permet de faire communiquer votre Web Component avec n’importe quelle application via une API événementielle simple et efficace.

Conclusion

Vous savez maintenant comment créer un Web Component avec SvelteKit, le builder avec Vite et l’intégrer dans n’importe quel projet.

• Créer un Web Component avec SvelteKit
• Configurer et builder avec Vite
• L’intégrer dans n’importe quel environnement (HTML, React, WordPress…)
• Gérer les props, méthodes, slots et événements

👉 Les Web Components sont une solution puissante pour créer des widgets réutilisables, que ce soit pour un SaaS, un script embarqué (embed), ou des plugins multi-plateformes.

Grâce à SvelteKit, vous pouvez créer des composants performants, légers et totalement indépendants du framework utilisé côté client.

🚀 Vous pouvez maintenant créer vos propres widgets et les intégrer partout : landing pages, CMS, applications web ou projets clients.

Aller plus loin

Vous souhaitez créer un Web Component sur mesure pour votre projet ou votre entreprise ?

Je propose des solutions personnalisées pour développer des widgets performants, intégrables sur n’importe quelle plateforme (WordPress, Shopify, SaaS…).