svelte web components template

СВЕЛТА-ВЕБ-Компонент-ТЕМПЛАТ

Базовый шаблон для создания библиотеки общих веб -компонентов с использованием Vite, Svelte и TypeScript.

Эти шаблоны генерируют ванильные веб -компоненты, чем можно использовать с простым HTML или в любых основных структурах, таких как React, Angular, Vue или Svelte (см. Совместимость).

Как использовать этот шаблон

Вы можете напрямую создать новую репо Github из этого шаблона, выбрав кнопку « Использовать этот шаблон» на Github.

Вы также можете клонировать его локально со следующими командами:

npx degit sinedied/svelte-web-components-template#main my-component-lib
cd my-component-lib
npm install

Ваш исходный код компонентов живет в lib/ папке. Только компоненты с расширением .wc.svelte Это означает, что вы также можете использовать обычные стройные компоненты с расширением .svelte в качестве дочерних компонентов для деталей вашей реализации.

Вы можете добавить дополнительные компоненты, добавив их в папку lib и редактируя lib/index.js .

Тестирование ваших компонентов

Вы можете начать сервер разработки с:

npm start

Затем откройте свой браузер для Localhost: 5173.

Это создаст демонстрационное приложение, расположенное в demo/ папке, в которой вы можете использовать и проверять свои веб -компоненты во время разработки.

Если вам нужны модульные тесты, вы можете взглянуть на библиотеку Jest и Jest Testing.

Использование встроенных веб -компонентов с демонстрационным приложением

Демонстрационное приложение предусмотрено для разработки и тестирования ваших компонентов, поэтому он импортирует файлы .svelte из lib/ папки непосредственно по умолчанию.

Если вы предпочитаете, вместо этого вы можете импортировать встроенные веб -компоненты из папки dist/ , редактируя demo/src/App.svelte и заменив import '../../lib'; утверждение с import '../../../dist/lib'; Если у вас есть опция bundleComponents , или индивидуально импортируйте ваши компоненты с помощью import import '../../dist/MyComponent.wc.js'; в противном случае.

Вам также придется убедиться, что запустить сценарий npm run build , чтобы сначала генерировать папку dist/lib/ .

Построение библиотеки

Команда npm run build создаст библиотеку веб -компонентов в папке dist/lib/ . Он создает как модуль ES ( dist/lib/<your-lib>.js ), подходящий для Bundler (не Минифицированный), так и модуль Minified ES ( dist/lib/<your-lib>.min.js ) и обычный сценарий UMD ( dist/lib/<your-lib>.umd.js ).

Сборка автоматически вызывается при выполнении npm publish для распространения вашей библиотеки благодаря prepublishOnly записи скрипта в package.json .

Примечания и ограничения

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

Реквизит

Любые реквизиты, принятые вашим веб -компонентом, автоматически преобразуются в атрибуты элемента. Поскольку Camelcase или Pascalcase не работает в HTML, вы должны убедиться, что ваши реквизиты в строчных строках.

 < script >
  export let myvalue = "Default" ;
</ script >

События

Синтаксическое событие Svelte для прослушивания событий, таких как on:myevent не работает с событиями, отправленными из стройного веб -компонента (#3119).

Вы должны использовать обходной путь для этого, создав CustomEvent и отправив его.

Вот пример:

// MyComponent.wc.svelte
< svelte:options tag =" my-component " />
< script >
  import { get_current_component } from "svelte/internal" ;
  const component = get_current_component ( ) ;
  
  // example function for dispatching events
  const dispatchEvent = ( name , detail ) =>
    component . dispatchEvent ( new CustomEvent ( name , { detail } ) ) ;
</ script >
< button on:click = {() = > dispatchEvent("test", "Hello!")} >
  Click to dispatch event
</ button > 

Построение каждого компонента в свой собственный модуль

По умолчанию этот шаблон будет создавать все компоненты в один модуль.

Если вы предпочитаете построить каждый компонент в свой собственный модуль, вы можете сделать это, установив переменную среды BUNDLE_COMPONENTS для false , или редактировать vite.config.js и установив опцию bundleComponents на false .

Затем вам также необходимо заменить содержание packages/lib/index.ts :

 export default ( ) => {
  import ( './MyComponent.wc.svelte' ) ;
  // Import each of your component this way
} ;

Это обеспечит распределение кода и будет генерировать модуль ES для каждого компонента в папке dist/lib/ .

Когда вы изменили способ экспорта компонентов, вам также необходимо заменить import '../../lib'; Заявление в demo/src/App.svelte для import '../../lib/MyComponent.wc.svelte'; Полем

Зачем разрешать allowJs в шаблоне TS?

Несмотря на то, что allowJs: false действительно предотвратит использование файлов .js в проекте, он не предотвращает использование синтаксиса JavaScript в файлах .svelte . Кроме того, это заставило бы checkJs: false , принося худшее из обоих миров: неспособность гарантировать, что вся кодовая база является TypeScript, а также хуже Typechecking для существующего JavaScript. Кроме того, существуют действительные варианты использования, в которых может быть актуальна смешанная кодовая база.

Почему HMR не сохраняет мое местное состояние компонентов?

Сохранение штата HMR поставляется с рядом GotChas! Он был отключен по умолчанию как в svelte-hmr , так и в @sveltejs/vite-plugin-svelte за его часто удивительного поведения. Вы можете прочитать детали здесь.

Если у вас есть состояние, которое важно сохранить в компоненте, рассмотрите возможность создания внешнего магазина, который не будет заменен HMR.

 // store.ts
// An extremely simple external store
import { writable } from 'svelte/store'
export default writable ( 0 )