svelte web components template

Template de componentes com-web suja

Um modelo básico para criar uma biblioteca de componentes da Web compartilhável usando vite, esbelto e datilografript.

Esses modelos gera componentes da Web de baunilha do que podem ser usados com HTML simples ou em qualquer estrutura principal, como React, Angular, Vue ou Sitete (consulte Compatibilidade).

Como usar este modelo

Você pode criar diretamente um novo repo Github a partir deste modelo selecionando o botão Usar este modelo no Github.

Você também pode cloná -lo localmente com os seguintes comandos:

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

O código -fonte dos seus componentes vive na lib/ pasta. Somente componentes com a extensão .wc.svelte serão exportados como componentes da Web e disponíveis em sua biblioteca. Isso significa que você também pode usar componentes esbeltos regulares com a extensão .svelte como componentes filhos para seus detalhes de implementação.

Você pode adicionar componentes adicionais adicionando -os à pasta lib e editando lib/index.js .

Testando seus componentes

Você pode iniciar um servidor de desenvolvimento com:

npm start

Em seguida, abra seu navegador para localhost: 5173.

Isso criará o aplicativo de demonstração localizado na demo/ pasta, na qual você pode usar e testar seus componentes da Web durante o desenvolvimento.

Se você precisar de testes de unidade, pode dar uma olhada na biblioteca de testes de brincadeira e jest.

Usando os componentes da web construídos com o aplicativo de demonstração

O aplicativo Demo é fornecido para o desenvolvimento e teste de seus componentes, é por isso que importa os arquivos .svelte da pasta lib/ por padrão.

Se preferir, você pode importar os componentes da Web construídos a partir da pasta dist/ em vez disso, editando demo/src/App.svelte e substituindo a import '../../lib'; declaração com import '../../../dist/lib'; Se você tiver a opção bundleComponents ativada ou importe individualmente seus componentes com import import '../../dist/MyComponent.wc.js'; de outra forma.

Você também precisará executar o script npm run build para gerar primeiro a pasta dist/lib/ .

Construindo a biblioteca

O comando npm run build criará a biblioteca de componentes da web na pasta dist/lib/ . Ele cria um módulo ES ( dist/lib/<your-lib>.js ) adequado para o Bundler (não minificado), um módulo ES minificado ( dist/lib/<your-lib>.min.js ) e um script UMD regular ( dist/lib/<your-lib>.umd.js ).

A compilação é chamada automaticamente ao executar npm publish para distribuir sua biblioteca, graças à entrada de script prepublishOnly no package.json .

Notas e limitações

Este modelo não fornece nenhum componente da web polyfills para o suporte aos navegadores mais antigos. Geralmente, é melhor deixar essa tarefa para o aplicativo host, por isso eles estão de fora.

Adereços

Quaisquer adereços aceitos pelo seu componente da Web são automaticamente transformados em atributos de elemento. Como CamelCase ou PascalCase não funciona no HTML, você deve nomear seus adereços em minúsculas.

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

Eventos

O evento de sintaxe esbelto para ouvir eventos como on:myevent não funciona com eventos despachados de um componente da Web esbelto (#3119).

Você precisa usar uma solução alternativa para isso, criando um CustomEvent e despacando -o.

Aqui está um exemplo:

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

Construindo cada componente em seu próprio módulo

Por padrão, este modelo criará todos os componentes em um único módulo.

Se você preferir construir cada componente em seu próprio módulo, pode fazê -lo definindo o ambiente variável BUNDLE_COMPONENTS como false ou editando vite.config.js e definindo a opção bundleComponents como false .

Então você também precisa substituir o conteúdo de packages/lib/index.ts por:

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

Isso ativará a divisão de código e gerará um módulo ES para cada componente na pasta dist/lib/ .

À medida que você mudou a maneira como os componentes são exportados, você também precisa substituir a import '../../lib'; declaração em demo/src/App.svelte para import '../../lib/MyComponent.wc.svelte'; .

Por que habilitar allowJs no modelo TS?

Embora allowJs: false realmente impediria o uso de arquivos .js no projeto, ele não impedirá o uso da sintaxe JavaScript nos arquivos .svelte . Além disso, forçaria checkJs: false , trazendo o pior dos dois mundos: não poder garantir que toda a base de código é TypeScript e também tendo pior digitando o JavaScript existente. Além disso, existem casos de uso válidos nos quais uma base de código mista pode ser relevante.

Por que a HMR não está preservando meu estado de componente local?

A Preservação do Estado da HMR vem com vários Gotchas! Ele foi desativado por padrão em svelte-hmr e @sveltejs/vite-plugin-svelte devido ao seu comportamento muitas vezes surpreendente. Você pode ler os detalhes aqui.

Se você tem um estado importante para reter dentro de um componente, considere criar uma loja externa que não seja substituída pelo HMR.

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