Crear un Componente Web con SvelteKit: Guía completa paso a paso

Crear un proyecto SvelteKit para un Web Component

Para crear un Web Component con SvelteKit, comienza por inicializar un nuevo proyecto:

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

Configuración del proyecto

Durante la instalación, selecciona las siguientes opciones:

• SvelteKit mínimo
• TypeScript
• Prettier y ESLint (recomendado)
• npm

Ejecutar el proyecto en local

Una vez que la instalación haya terminado, abre tu navegador en la siguiente dirección:

http://localhost:5173/

Si la página se muestra correctamente, tu proyecto SvelteKit está listo para ser utilizado para crear un Web Component.

Instalar SCSS en SvelteKit

Para utilizar SCSS en tu proyecto SvelteKit, debes instalar el compilador Sass como una dependencia de desarrollo:

npm install -D sass-embedded

Una vez instalado, SvelteKit detectará automáticamente SCSS en tus archivos .svelte a través de las etiquetas <style lang="scss">.

Crear un Web Component con SvelteKit

Ahora vamos a crear nuestro primer Web Component con SvelteKit. Para eso, crea un archivo en la carpeta src/lib :

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

A continuación, añade el siguiente código :

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

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

<p>Hola Mundo</p>

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

👉 El atributo customElement="my-web-component" define el nombre de tu Web Component. Este nombre debe contener obligatoriamente un guion (ej: my-component) para ser válido en HTML.

Configurar SvelteKit para Web Components

Para habilitar la creación de Web Components con SvelteKit, debes modificar el archivo svelte.config.js y activar la opción customElement.

Agrega la siguiente configuración:

compilerOptions: {
  customElement: true
}

Aquí tienes un ejemplo completo de configuración:

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;

👉 La opción customElement: true permite a SvelteKit compilar tus componentes en Web Components nativos utilizables en cualquier entorno.

Configurar la compilación del Web Component con Vite

Para generar un Web Component reutilizable, debes configurar una compilación específica con Vite. Esto permite exportar tu componente en forma de archivo JavaScript utilizable en cualquier proyecto.

Crea un archivo de configuración dedicado:

touch vite.config.webcomponent.js

Agrega la siguiente configuración:

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

Agregar el script de compilación

Agrega el siguiente script en tu archivo package.json:

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

Luego podrás generar tu Web Component con el comando:

npm run build:wc

Probar el Web Component en SvelteKit

Una vez que se genera el build, puedes probar tu Web Component directamente en tu proyecto SvelteKit.

Importar el script

En el archivo +page.svelte, añade el script generado en la etiqueta <svelte:head>:

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

Utilizar el Web Component

Luego, añade tu componente en la plantilla:

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

Ejemplo completo

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

<h1>Bienvenido a SvelteKit</h1>
<p>
  Visita <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> para leer la documentación
</p>

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

Iniciar el proyecto

Ejecuta los siguientes comandos:

npm run build:wc
npm run dev

Si todo está correctamente configurado, tu Web Component debería aparecer en la página.

Agregar propiedades (props) a un Web Component SvelteKit

Puede hacer que su Web Component sea dinámico pasándole propiedades (props).

Definir una prop en el componente

En su archivo my-web-component.svelte :

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

Usar la prop en la plantilla

<p>Hola {name}</p>

Componente completo

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

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

<p>Hola {name}</p>

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

Usar la prop en el HTML

Ahora puede pasar un valor directamente desde el HTML :

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

👉 El texto mostrado será: Hola Bryan

Exponer métodos JavaScript (API) en un Web Component

Puedes exponer métodos JavaScript para interactuar con tu Web Component desde el exterior (JavaScript, framework o HTML).

En este ejemplo, vamos a crear un getter y un setter para manipular la propiedad name.

Crear los métodos

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

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

Exponer los métodos a través del Web Component

Utiliza $host() para adjuntar los métodos al 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>Hola {name}</p>

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

Usar los métodos desde JavaScript

Ahora puedes interactuar con tu Web Component desde un script externo:

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

// Modificar el valor
el.setName('Bryan');

// Recuperar el valor
console.log(el.getName());

👉 Este enfoque permite crear una verdadera API JavaScript para tu Web Component.

Interactuar con un Web Component desde SvelteKit

Puede interactuar directamente con su Web Component desde SvelteKit accediendo a sus métodos a través de una referencia JavaScript.

Declarar una referencia hacia el componente

let wc: HTMLElement;

Vincular el Web Component

Utilice bind:this para obtener una referencia al componente:

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

Agregar tipado TypeScript (recomendado)

Para evitar errores en su IDE, puede tipar los métodos expuestos:

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

Interactuar con el componente

Luego puede llamar a los métodos en el ciclo de vida onMount:

import { onMount } from 'svelte';

onMount(() => {
  console.log('Nombre actual:', wc.getName());

  setTimeout(() => {
    console.log('== Cambiar Nombre ==');
    wc.setName('Admin');
    console.log('Nombre actual:', wc.getName());
  }, 1000);
});

Ejemplo completo

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

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

  onMount(() => {
    console.log('Nombre actual:', wc.getName());

    setTimeout(() => {
      console.log('== Cambiar Nombre ==');
      wc.setName('Admin');
      console.log('Nombre actual:', wc.getName());
    }, 1000);
  });
</script>

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

<h1>Bienvenido a SvelteKit</h1>
<p>
  Visite <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> para leer la documentación
</p>

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

Resultado en la consola

Nombre actual: User
== Cambiar Nombre ==
Nombre actual: Admin

👉 El Web Component se actualiza dinámicamente, y los cambios son visibles tanto en el DOM como en la consola.

Usar slots en un Web Component SvelteKit

Los slots permiten inyectar contenido HTML desde el exterior en su Web Component. Es esencial para hacer que su componente sea flexible y reutilizable.

Agregar un slot en el componente

En su archivo my-web-component.svelte, simplemente agregue :

<slot />

Modificar la plantilla

Por ejemplo, reemplace :

<p>Hola {name}</p>

Por :

<p>Antes de Hola {name}</p>
<slot />
<p>Después de Hola {name}</p>

Componente completo

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

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

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

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

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

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

<p>Antes de Hola {name}</p>
<slot />
<p>Después de Hola {name}</p>

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

Pasar contenido desde la página SvelteKit

Ahora puede inyectar contenido directamente en su Web Component :

<my-web-component bind:this={wc} name="Usuario">
  <p>Nuevo contenido</p>
</my-web-component>

Ejemplo completo en SvelteKit

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

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

  onMount(() => {
    console.log('Nombre Actual:', wc.getName());

    setTimeout(() => {
      console.log('== Cambiar Nombre ==');
      wc.setName('Administrador');
      console.log('Nombre Actual:', wc.getName());
    }, 1000);
  });
</script>

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

<h1>Bienvenido a SvelteKit</h1>
<p>
  Visite <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> para leer la documentación
</p>

<my-web-component bind:this={wc} name="Usuario">
  <p>Nuevo contenido</p>
</my-web-component>

👉 El contenido pasado entre las etiquetas del Web Component será inyectado en la ubicación del <slot />.

Agregar una imagen en un Web Component SvelteKit

Para integrar una imagen en un Web Component con SvelteKit, no puede utilizar directamente la carpeta static. Debe importar la imagen como un módulo para que se incluya correctamente en la compilación.

Importar una imagen

En su componente my-web-component.svelte :

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

Usar la imagen en el template

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

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

<p>Antes de Hola {name}</p>
<slot />
<p>Después de Hola {name}</p>

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

👉 La imagen se optimizará automáticamente e incluirá en el paquete final del Web Component.

Escuchar los eventos de un Web Component en SvelteKit

Para comunicarse desde un Web Component hacia su aplicación, puede emitir eventos personalizados (CustomEvent) y escucharlos del lado del cliente.

Crear un evento en el componente

Agregue un botón y una función en su componente:

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

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

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

Crear una API para escuchar los eventos

Para simplificar la escucha de eventos, puede exponer un método on:

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

Exponer el método

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

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

Actualizar el tipo del lado de SvelteKit

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

Escuchar el evento en la página

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

Ejemplo completo del lado de 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>

Resultado

{ name: 'Admin' }

👉 Este enfoque permite hacer que su Web Component se comunique con cualquier aplicación a través de una API basada en eventos simple y efectiva.

Conclusión

Ahora sabes cómo crear un Web Component con SvelteKit, compilarlo con Vite e integrarlo en cualquier proyecto.

• Crear un Web Component con SvelteKit
• Configurar y compilar con Vite
• Integrarlo en cualquier entorno (HTML, React, WordPress…)
• Manejar las props, métodos, slots y eventos

👉 Los Web Components son una solución poderosa para crear widgets reutilizables, ya sea para un SaaS, un script embebido (embed) o plugins multiplataforma.

Gracias a SvelteKit, puedes crear componentes eficientes, ligeros y totalmente independientes del framework utilizado en el cliente.

🚀 Ahora puedes crear tus propios widgets e integrarlos en cualquier lugar: landing pages, CMS, aplicaciones web o proyectos de clientes.

Ir más allá

¿Deseas crear un Componente Web a medida para tu proyecto o empresa?

Ofrezco soluciones personalizadas para desarrollar widgets de alto rendimiento, integrables en cualquier plataforma (WordPress, Shopify, SaaS…).