Создание веб-компонента с SvelteKit: Полное пошаговое руководство

Создание проекта SvelteKit для веб-компонента

Чтобы создать веб-компонент с помощью SvelteKit, начните с инициализации нового проекта:

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

Настройка проекта

Во время установки выберите следующие опции:

• Минимальный SvelteKit
• TypeScript
• Prettier и ESLint (рекомендуется)
• npm

Запуск проекта локально

После завершения установки откройте ваш браузер по следующему адресу:

http://localhost:5173/

Если страница отображается корректно, ваш проект SvelteKit готов к использованию для создания веб-компонента.

Установка SCSS в SvelteKit

Чтобы использовать SCSS в вашем проекте SvelteKit, вам нужно установить компилятор Sass в качестве зависимости для разработки:

npm install -D sass-embedded

После установки SvelteKit автоматически обнаружит SCSS в ваших файлах .svelte через теги <style lang="scss">.

Создание веб-компонента с помощью SvelteKit

Теперь мы создадим наш первый веб-компонент с помощью SvelteKit. Для этого создайте файл в папке src/lib :

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

Затем добавьте следующий код :

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

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

<p>Привет, мир</p>

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

👉 Атрибут customElement="my-web-component" определяет имя вашего веб-компонента. Это имя должно обязательно содержать дефис (например: my-component), чтобы быть допустимым в HTML.

Настройка SvelteKit для Web Components

Чтобы активировать создание Web Components с SvelteKit, вам нужно изменить файл svelte.config.js и включить опцию customElement.

Добавьте следующую конфигурацию:

compilerOptions: {
  customElement: true
}

Вот полный пример конфигурации:

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;

👉 Опция customElement: true позволяет SvelteKit компилировать ваши компоненты в нативные Web Components, которые можно использовать в любом окружении.

Настройка сборки веб-компонента с Vite

Чтобы создать многоразовый веб-компонент, вам необходимо настроить специальную сборку с Vite. Это позволяет экспортировать ваш компонент в виде файла JavaScript, который можно использовать в любом проекте.

Создайте файл конфигурации:

touch vite.config.webcomponent.js

Добавьте следующую конфигурацию:

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

Добавить скрипт сборки

Добавьте следующий скрипт в ваш файл package.json:

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

Затем вы сможете сгенерировать ваш веб-компонент с помощью команды:

npm run build:wc

Протестируйте веб-компонент в SvelteKit

После генерации сборки вы можете протестировать ваш веб-компонент непосредственно в вашем проекте SvelteKit.

Импортировать скрипт

В файле +page.svelte добавьте сгенерированный скрипт в тег <svelte:head> :

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

Использовать веб-компонент

Затем добавьте ваш компонент в шаблон :

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

Полный пример

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

<h1>Добро пожаловать в SvelteKit</h1>
<p>
  Посетите <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a>, чтобы прочитать документацию
</p>

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

Запустить проект

Выполните следующие команды :

npm run build:wc
npm run dev

Если все настроено правильно, ваш веб-компонент должен отображаться на странице.

Добавить свойства (props) в Web Component SvelteKit

Вы можете сделать ваш Web Component динамическим, передав ему свойства (props).

Определить проп в компоненте

В вашем файле my-web-component.svelte :

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

Использовать проп в шаблоне

<p>Привет {name}</p>

Полный компонент

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

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

<p>Привет {name}</p>

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

Использовать проп в HTML

Теперь вы можете передать значение напрямую из HTML :

<my-web-component name="Брайан"></my-web-component>

👉 Отображаемый текст будет: Привет Брайан

Экспонирование методов JavaScript (API) в Web Component

Вы можете экспонировать методы JavaScript для взаимодействия с вашим Web Component извне (JavaScript, фреймворк или HTML).

В этом примере мы создадим геттер и сеттер для управления свойством name.

Создание методов

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

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

Экспонирование методов через Web Component

Используйте $host() для привязки методов к элементу DOM:

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

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

Полный компонент

<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>Привет {name}</p>

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

Использование методов из JavaScript

Теперь вы можете взаимодействовать с вашим Web Component из внешнего скрипта:

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

// Изменить значение
el.setName('Брайан');

// Получить значение
console.log(el.getName());

👉 Этот подход позволяет создать полноценное JavaScript API для вашего Web Component.

Взаимодействие с веб-компонентом из SvelteKit

Вы можете взаимодействовать непосредственно с вашим веб-компонентом из SvelteKit, получая доступ к его методам через ссылку на JavaScript.

Объявление ссылки на компонент

let wc: HTMLElement;

Связывание веб-компонента

Используйте bind:this, чтобы получить ссылку на компонент:

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

Добавление типизации TypeScript (рекомендуется)

Чтобы избежать ошибок в вашей IDE, вы можете типизировать открытые методы:

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

Взаимодействие с компонентом

Вы можете затем вызывать методы в жизненном цикле onMount:

import { onMount } from 'svelte';

onMount(() => {
  console.log('Т текущее имя:', wc.getName());

  setTimeout(() => {
    console.log('== Изменить имя ==');
    wc.setName('Admin');
    console.log('Т текущее имя:', wc.getName());
  }, 1000);
});

Полный пример

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

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

  onMount(() => {
    console.log('Т текущее имя:', wc.getName());

    setTimeout(() => {
      console.log('== Изменить имя ==');
      wc.setName('Admin');
      console.log('Т текущее имя:', wc.getName());
    }, 1000);
  });
</script>

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

<h1>Добро пожаловать в SvelteKit</h1>
<p>
  Посетите <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a>, чтобы прочитать документацию
</p>

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

Результат в консоли

Т текущее имя: User
== Изменить имя ==
Т текущее имя: Admin

👉 Веб-компонент обновляется динамически, и изменения видны как в DOM, так и в консоли.

Использование слотов в Web Component SvelteKit

Слоты позволяют внедрять HTML-контент из внешнего источника в ваш Web Component. Это необходимо для того, чтобы сделать ваш компонент гибким и повторно используемым.

Добавление слота в компонент

В вашем файле my-web-component.svelte просто добавьте:

<slot />

Изменение шаблона

Например, замените:

<p>Привет {name}</p>

На:

<p>Перед Привет {name}</p>
<slot />
<p>После Привет {name}</p>

Полный компонент

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

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

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

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

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

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

<p>Перед Привет {name}</p>
<slot />
<p>После Привет {name}</p>

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

Передача контента из страницы SvelteKit

Теперь вы можете внедрять контент непосредственно в ваш Web Component:

<my-web-component bind:this={wc} name="Пользователь">
  <p>Новый контент</p>
</my-web-component>

Полный пример в SvelteKit

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

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

  onMount(() => {
    console.log('Текущее имя:', wc.getName());

    setTimeout(() => {
      console.log('== Изменить имя ==');
      wc.setName('Администратор');
      console.log('Текущее имя:', wc.getName());
    }, 1000);
  });
</script>

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

<h1>Добро пожаловать в SvelteKit</h1>
<p>
  Посетите <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> для чтения документации
</p>

<my-web-component bind:this={wc} name="Пользователь">
  <p>Новый контент</p>
</my-web-component>

👉 Контент, переданный между тегами Web Component, будет внедрён на место <slot />.

Добавить изображение в Web Component SvelteKit

Чтобы интегрировать изображение в Web Component с помощью SvelteKit, вы не можете использовать директорию static напрямую. Вам нужно импортировать изображение как модуль, чтобы оно было правильно включено в сборку.

Импортировать изображение

В вашем компоненте my-web-component.svelte :

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

Использовать изображение в шаблоне

<img src={logo} alt="Логотип SvelteKit" />

Полный компонент

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

<p>Перед Привет {name}</p>
<slot />
<p>После Привет {name}</p>

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

👉 Изображение будет автоматически оптимизировано и включено в финальный пакет Web Component.

Слушать события веб-компонента в SvelteKit

Чтобы общаться с вашим приложением из веб-компонента, вы можете генерировать пользовательские события (CustomEvent) и слушать их на стороне клиента.

Создать событие в компоненте

Добавьте кнопку и функцию в ваш компонент:

<button on:click={handleClick}>Тест</button>

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

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

Создать API для прослушивания событий

Чтобы упростить прослушивание событий, вы можетеExpose метод on:

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

Экспонировать метод

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

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

Обновить типизацию на стороне SvelteKit

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

Слушать событие на странице

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

Полный пример на стороне 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>

Результат

{ name: 'Admin' }

👉 Этот подход позволяет сделать ваш веб-компонент совместимым с любым приложением через простую и эффективную событийную API.

Заключение

Теперь вы знаете, как создать Web Component с помощью SvelteKit, собрать его с Vite и интегрировать в любой проект.

• Создать Web Component с SvelteKit
• Настроить и собрать с Vite
• Интегрировать в любую среду (HTML, React, WordPress…)
• Управлять свойствами, методами, слотами и событиями

👉 Web Components — это мощное решение для создания переиспользуемых виджетов, будь то для SaaS, встраиваемых скриптов или многоплатформенных плагинов.

Благодаря SvelteKit вы можете создавать производительные, легкие и полностью независимые от используемого клиентского фреймворка компоненты.

🚀 Теперь вы можете создавать собственные виджеты и интегрировать их повсюду: на лендингах, в CMS, веб-приложениях или клиентских проектах.

Идти дальше

Вы хотите создать индивидуальный веб-компонент для вашего проекта или компании?

Я предлагаю персонализированные решения для разработки эффективных виджетов, которые можно интегрировать на любую платформу (WordPress, Shopify, SaaS…).