Creare un Web Component con SvelteKit: Guida completa passo dopo passo

Creare un progetto SvelteKit per un Web Component

Per creare un Web Component con SvelteKit, inizia con l'inizializzazione di un nuovo progetto:

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

Configurazione del progetto

Durante l'installazione, seleziona le seguenti opzioni:

• SvelteKit minimale
• TypeScript
• Prettier e ESLint (raccomandato)
• npm

Avviare il progetto in locale

Una volta completata l'installazione, apri il tuo browser all'indirizzo seguente:

http://localhost:5173/

Se la pagina viene visualizzata correttamente, il tuo progetto SvelteKit è pronto per essere utilizzato per creare un Web Component.

Installare SCSS in SvelteKit

Per utilizzare SCSS nel tuo progetto SvelteKit, devi installare il compilatore Sass come dipendenza di sviluppo:

npm install -D sass-embedded

Una volta installato, SvelteKit rileverà automaticamente SCSS nei tuoi file .svelte tramite i tag <style lang="scss">.

Creare un Web Component con SvelteKit

Ora creeremo il nostro primo Web Component con SvelteKit. Per fare ciò, crea un file nella cartella src/lib :

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

Successivamente, aggiungi il seguente codice :

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

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

<p>Hello World</p>

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

👉 L'attributo customElement="my-web-component" definisce il nome del tuo Web Component. Questo nome deve necessariamente contenere un trattino (es: my-component) per essere valido in HTML.

Configurare SvelteKit per i Web Components

Per attivare la creazione di Web Components con SvelteKit, è necessario modificare il file svelte.config.js e attivare l’opzione customElement.

Aggiungi la seguente configurazione:

compilerOptions: {
  customElement: true
}

Ecco un esempio completo di configurazione:

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’opzione customElement: true consente a SvelteKit di compilare i tuoi componenti in Web Components nativi utilizzabili in qualsiasi ambiente.

Configurare il build del Web Component con Vite

Per generare un Web Component riutilizzabile, è necessario configurare un build specifico con Vite. Questo consente di esportare il tuo componente sotto forma di file JavaScript utilizzabile in qualsiasi progetto.

Crea un file di configurazione dedicato:

touch vite.config.webcomponent.js

aggiungi la seguente configurazione:

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'
  }
});

Aggiungere lo script di build

Aggiungi il seguente script nel tuo file package.json:

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

Potrai quindi generare il tuo Web Component con il comando:

npm run build:wc

Testare il Web Component in SvelteKit

Una volta generato il build, puoi testare il tuo Web Component direttamente nel tuo progetto SvelteKit.

Importare lo script

Nel file +page.svelte, aggiungi lo script generato nel tag <svelte:head>:

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

Utilizzare il Web Component

Successivamente, aggiungi il tuo componente nel template:

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

Esempio completo

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

<h1>Benvenuto in SvelteKit</h1>
<p>
  Visita <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> per leggere la documentazione
</p>

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

Avviare il progetto

Esegui i seguenti comandi:

npm run build:wc
npm run dev

Se tutto è configurato correttamente, il tuo Web Component dovrebbe apparire nella pagina.

Aggiungere proprietà (props) a un Web Component SvelteKit

Puoi rendere dinamico il tuo Web Component passando proprietà (props).

Definire una prop nel componente

Nel tuo file my-web-component.svelte :

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

Utilizzare la prop nel template

<p>Ciao {name}</p>

Componente completo

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

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

<p>Ciao {name}</p>

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

Utilizzare la prop nell'HTML

Ora puoi passare un valore direttamente dall'HTML :

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

👉 Il testo mostrato sarà : Ciao Bryan

Esporre metodi JavaScript (API) in un Web Component

Puoi esporre metodi JavaScript per interagire con il tuo Web Component dall’esterno (JavaScript, framework o HTML).

In questo esempio, creeremo un getter e un setter per manipolare la proprietà name.

Creare i metodi

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

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

Esporre i metodi tramite il Web Component

Utilizza $host() per allegare i metodi all’elemento DOM:

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

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

Componente completo

<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>Ciao {name}</p>

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

Utilizzare i metodi da JavaScript

Ora puoi interagire con il tuo Web Component da uno script esterno:

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

// Modificare il valore
el.setName('Bryan');

// Recuperare il valore
console.log(el.getName());

👉 Questo approccio consente di creare una vera API JavaScript per il tuo Web Component.

Interagire con un Web Component da SvelteKit

Puoi interagire direttamente con il tuo Web Component da SvelteKit accedendo ai suoi metodi tramite un riferimento JavaScript.

Dichiarare un riferimento al componente

let wc: HTMLElement;

Collegare il Web Component

Usa bind:this per ottenere un riferimento al componente:

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

aggiungere un typing TypeScript (consigliato)

Per evitare errori nel tuo IDE, puoi tipizzare i metodi esposti:

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

Interagire con il componente

Puoi quindi chiamare i metodi nel ciclo di vita onMount:

import { onMount } from 'svelte';

onMount(() => {
  console.log('Nome attuale:', wc.getName());

  setTimeout(() => {
    console.log('== Cambia Nome ==');
    wc.setName('Admin');
    console.log('Nome attuale:', wc.getName());
  }, 1000);
});

Esempio completo

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

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

  onMount(() => {
    console.log('Nome attuale:', wc.getName());

    setTimeout(() => {
      console.log('== Cambia Nome ==');
      wc.setName('Admin');
      console.log('Nome attuale:', wc.getName());
    }, 1000);
  });
</script>

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

<h1>Benvenuto in SvelteKit</h1>
<p>
  Visita <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> per leggere la documentazione
</p>

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

Risultato nella console

Nome attuale: User
== Cambia Nome ==
Nome attuale: Admin

👉 Il Web Component viene aggiornato dinamicamente e le modifiche sono visibili sia nel DOM che nella console.

Utilizzare gli slot in un Web Component SvelteKit

Gli slot consentono di iniettare contenuti HTML dall'esterno nel tuo Web Component. Questo è essenziale per rendere il tuo componente flessibile e riutilizzabile.

Aggiungere uno slot nel componente

Nel tuo file my-web-component.svelte, aggiungi semplicemente :

<slot />

Modificare il template

Ad esempio, sostituisci :

<p>Hello {name}</p>

Con :

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

Componente completo

<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>

Passare contenuti dalla pagina SvelteKit

Ora puoi iniettare contenuti direttamente nel tuo Web Component :

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

Esempio completo in 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>Benvenuto in SvelteKit</h1>
<p>
  Visita <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> per leggere la documentazione
</p>

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

👉 Il contenuto passato tra i tag del Web Component verrà iniettato nella posizione del <slot />.

Aggiungere un'immagine in un Web Component SvelteKit

Per integrare un'immagine in un Web Component con SvelteKit, non è possibile utilizzare direttamente la cartella static. È necessario importare l'immagine come un modulo affinché venga inclusa correttamente nella build.

Importare un'immagine

Nel tuo componente my-web-component.svelte:

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

Usare l'immagine nel template

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

Componente completo

<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="Logo SvelteKit" />

<p>Prima di Hello {name}</p>
<slot />
<p>Dopo Hello {name}</p>

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

👉 L'immagine sarà automaticamente ottimizzata e inclusa nel bundle finale del Web Component.

Ascoltare gli eventi di un Web Component in SvelteKit

Per comunicare da un Web Component alla tua applicazione, puoi emettere eventi personalizzati (CustomEvent) e ascoltarli lato client.

Creare un evento nel componente

Aggiungi un pulsante e una funzione nel tuo componente:

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

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

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

Creare un'API per ascoltare gli eventi

Per semplificare l'ascolto degli eventi, puoi esporre un metodo on:

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

Espiore il metodo

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

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

Aggiornare il typing lato SvelteKit

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

Ascoltare l'evento nella pagina

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

Esempio completo lato 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>

Risultato

{ name: 'Admin' }

👉 Questo approccio permette di far comunicare il tuo Web Component con qualsiasi applicazione tramite un'API basata su eventi semplice ed efficace.

Conclusione

Ora sapete come creare un Web Component con SvelteKit, compilarlo con Vite e integrarlo in qualsiasi progetto.

• Creare un Web Component con SvelteKit
• Configurare e compilare con Vite
• Integrarlo in qualsiasi ambiente (HTML, React, WordPress…)
• Gestire le props, metodi, slot ed eventi

👉 I Web Components sono una soluzione potente per creare widget riutilizzabili, sia per un SaaS, uno script incorporato (embed), o plugin multi-piattaforma.

Grazie a SvelteKit, potete creare componenti performanti, leggeri e completamente indipendenti dal framework utilizzato lato client.

🚀 Ora potete creare i vostri propri widget e integrarli ovunque: landing page, CMS, applicazioni web o progetti per clienti.

Andare oltre

Desideri creare un Web Component su misura per il tuo progetto o la tua azienda?

Propongo soluzioni personalizzate per sviluppare widget performanti, integrabili su qualsiasi piattaforma (WordPress, Shopify, SaaS…).