svelte web components template

plantilla

Una plantilla base para construir una biblioteca de componentes web compartibles utilizando VITE, SVELTE y TypeScript.

Esta plantilla genera componentes web de vainilla que los que se pueden usar con HTML simple o dentro de cualquier marcos principales, como React, Angular, Vue o Svelte (ver Compatibilidad).

Cómo usar esta plantilla

Puede crear directamente un nuevo repositorio de GitHub a partir de esta plantilla seleccionando el botón Usar esta plantilla en GitHub.

También puede clonarlo localmente con los siguientes comandos:

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

El código fuente de sus componentes vive en la carpeta lib/ . Solo los componentes con la extensión .wc.svelte se exportarán como componentes web y disponibles en su biblioteca. Esto significa que también puede usar componentes selts regulares con la extensión .svelte como componentes infantiles para sus detalles de implementación.

Puede agregar componentes adicionales agregándolos a la carpeta lib y editando lib/index.js .

Probar sus componentes

Puede iniciar un servidor de desarrollo con:

npm start

Luego abra su navegador a localhost: 5173.

Esto creará la aplicación de demostración ubicada en la demo/ carpeta, en la que puede usar y probar sus componentes web durante el desarrollo.

Si necesita pruebas unitarias, puede echar un vistazo a la biblioteca de pruebas de broma y broma.

Uso de los componentes web construidos con la aplicación de demostración

La aplicación de demostración se proporciona para el desarrollo y las pruebas de sus componentes, por eso importa los archivos .svelte desde la carpeta lib/ directamente de forma predeterminada.

Si lo prefiere, puede importar los componentes web construidos desde la carpeta dist/ , editando demo/src/App.svelte y reemplazando la import '../../lib'; declaración con import '../../../dist/lib'; Si tiene la opción bundleComponents habilitada, o importe individualmente sus componentes con import import '../../dist/MyComponent.wc.js'; de lo contrario.

También tendrá que asegurarse de ejecutar el script npm run build para generar primero la carpeta dist/lib/ .

Construyendo la biblioteca

El comando npm run build creará la biblioteca de componentes web en la carpeta dist/lib/ . Crea un módulo ES ( dist/lib/<your-lib>.js ) adecuado para Bundler (no minificado), un módulo ES minificado ( dist/lib/<your-lib>.min.js ) y un script UMD regular ( dist/lib/<your-lib>.umd.js ).

La compilación se llama automáticamente al ejecutar npm publish para distribuir su biblioteca, gracias a la entrada de script prepublishOnly en package.json .

Notas y limitaciones

Esta plantilla no proporciona ningún componente web polyfills para soporte de navegadores más antiguos. Por lo general, es mejor dejar esa tarea en la aplicación del host, de ahí que se queden fuera.

Accesorios

Cualquier accesorio aceptado por su componente web se transforma automáticamente en atributos de elementos. Dado que CamelCase o Pascalcase no funciona en HTML, debe asegurarse de nombrar sus accesorios en minúsculas.

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

Eventos

El evento de sintaxis esbele para escuchar eventos como on:myevent no funciona con eventos enviados desde un componente web de Svelte (#3119).

Debe usar una solución para eso, creando un CustomEvent y enviándolo.

Aquí hay un ejemplo:

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

Construir cada componente en su propio módulo

Por defecto, esta plantilla construirá todos los componentes en un solo módulo.

Si prefiere incorporar cada componente en su propio módulo, puede hacerlo configurando la variable de entorno BUNDLE_COMPONENTS en false o editando vite.config.js y configurando la opción bundleComponents en false .

Luego también debe reemplazar el contenido de packages/lib/index.ts con:

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

Esto habilitará la división de código y generará un módulo ES para cada componente en la carpeta dist/lib/ .

A medida que cambió la forma en que se exportan los componentes, también debe reemplazar la import '../../lib'; declaración en demo/src/App.svelte para import '../../lib/MyComponent.wc.svelte'; .

¿Por qué habilitar allowJs en la plantilla TS?

Mientras que allowJs: false evitaría el uso de archivos .js en el proyecto, no impide el uso de la sintaxis de JavaScript en archivos .svelte . Además, forzaría checkJs: false , trayendo lo peor de ambos mundos: no poder garantizar que la base de código completa sea mecanografiada, y también tener una tecnología peor para el JavaScript existente. Además, hay casos de uso válidos en los que una base de código mixta puede ser relevante.

¿Por qué HMR no preserva mi estado de componente local?

¡La preservación del estado de HMR viene con una serie de Gotchas! Se ha deshabilitado de forma predeterminada tanto en svelte-hmr como @sveltejs/vite-plugin-svelte debido a su comportamiento a menudo sorprendente. Puedes leer los detalles aquí.

Si tiene un estado que es importante retener dentro de un componente, considere crear una tienda externa que no sea reemplazada por HMR.

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