svelte web components template

Sufle-Web-Komponenten-Template

Eine Basisvorlage zum Erstellen einer gemeinsam genutzbaren Webkomponenten -Bibliothek mit VITE, SELTE und TISTICSCIPT.

Diese Vorlagen erzeugen Vanille -Webkomponenten als mit einfachem HTML oder in wichtigen Rahmenbedingungen wie React, Angular, Vue oder Sufle (siehe Kompatibilität).

So verwenden Sie diese Vorlage

Sie können direkt ein neues GitHub -Repo aus dieser Vorlage erstellen, indem Sie die Schaltfläche "diese Vorlage verwenden" auf GitHub auswählen.

Sie können es auch lokal mit den folgenden Befehlen klonen:

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

Ihre Komponenten Quellcode befindet sich in lib/ Ordner. Es werden nur Komponenten mit der Erweiterung .wc.svelte als Webkomponenten exportiert und in Ihrer Bibliothek erhältlich. Dies bedeutet, dass Sie auch regelmäßige Svelte -Komponenten mit der .svelte -Erweiterung als untergeordnete Komponenten für Ihre Implementierungsdetails verwenden können.

Sie können zusätzliche Komponenten hinzufügen, indem Sie sie dem lib -Ordner hinzufügen und lib/index.js bearbeiten.

Testen Sie Ihre Komponenten

Sie können einen Entwicklungsserver mit:

npm start

Öffnen Sie dann Ihren Browser für Localhost: 5173.

Dadurch wird die Demo -Anwendung im demo/ Ordner erstellt, in der Sie Ihre Webkomponenten während der Entwicklung verwenden und testen können.

Wenn Sie Unit -Tests benötigen, können Sie sich die Scherz- und Scherz -Testbibliothek ansehen.

Verwenden der erstellten Webkomponenten mit der Demo -App

Die Demo -Anwendung wird für die Entwicklung und das Testen Ihrer Komponenten bereitgestellt. Deshalb importiert sie die .svelte -Dateien standardmäßig direkt aus dem lib/ Ordner.

Wenn Sie es vorziehen, können Sie die erstellten Webkomponenten stattdessen aus dem dist/ Ordner importieren, indem Sie demo/src/App.svelte bearbeiten und den import '../../lib'; Aussage mit import '../../../dist/lib'; Wenn Sie die Option bundleComponents aktivieren lassen, oder Ihre Komponenten einzeln mit import import '../../dist/MyComponent.wc.js'; ansonsten.

Sie müssen auch sicherstellen, dass das npm run build -Skript ausgeführt wird, um zuerst den dist/lib/ Ordner zu generieren.

Bau der Bibliothek

Der Befehl npm run build erstellt die Webkomponenten -Bibliothek im dist/lib/ Ordner. Es erzeugt sowohl ein ES-Modul ( dist/lib/<your-lib>.js ), das für Bundler geeignet ist (nicht-minifiziert), ein minifiedes ES-Modul ( dist/lib/<your-lib>.min.js ) als auch ein reguläres UMD-Skript ( dist/lib/<your-lib>.umd.js ).

Der Build wird automatisch aufgerufen, wenn die npm publish dank des prepublishOnly Skripteintrags in package.json zur Verteilung Ihrer Bibliothek ausführt.

Anmerkungen und Einschränkungen

Diese Vorlage liefert keine Webkomponenten, die Polyfills für ältere Browser unterstützen. Normalerweise ist es am besten, diese Aufgabe der Host -Anwendung zu überlassen, weshalb sie ausgelassen werden.

Requisiten

Alle von Ihrer Webkomponente akzeptierten Requisiten werden automatisch in Elementattribute transformiert. Da Camelcase oder Pascalcase in HTML nicht funktioniert, müssen Sie Ihre Requisiten in Kleinbuchstaben benennen.

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

Ereignisse

Das Svelte -Syntax -Ereignis zum Anhören von Ereignissen wie on:myevent funktioniert nicht mit Ereignissen, die von einer Svelte -Webkomponente (#3119) entsandt wurden.

Sie müssen dafür eine Problemumgehung verwenden, indem Sie ein CustomEvent erstellen und versenden.

Hier ist ein Beispiel:

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

Bauen Sie jede Komponente in ein eigenes Modul auf

Standardmäßig erstellt diese Vorlage alle Komponenten in ein einzelnes Modul.

Wenn Sie es vorziehen, jede Komponente in ein eigenes Modul zu erstellen, können Sie dies tun, indem Sie die Umgebungsvariable BUNDLE_COMPONENTS auf false oder vite.config.js einstellen und die Option bundleComponents auf false festlegen.

Anschließend müssen Sie auch den Inhalt von packages/lib/index.ts ersetzen mit:

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

Dies ermöglicht die Codespaltung und generiert ein ES-Modul für jede Komponente im Ordner dist/lib/ Ordner.

Während Sie die Art und Weise geändert haben, wie Komponenten exportiert werden, müssen Sie auch den import '../../lib'; Anweisung in demo/src/App.svelte um zu import '../../lib/MyComponent.wc.svelte'; .

Warum allowJs in der TS -Vorlage aktivieren?

Während allowJs: false tatsächlich die Verwendung von .js -Dateien im Projekt verhindern würde, verhindern es nicht die Verwendung von JavaScript -Syntax in .svelte -Dateien. Darüber hinaus würde es checkJs: false erzwingen, das schlimmste in beiden Welten bringt: Sie können nicht in der Lage sein, die gesamte Codebasis TypeScript zu garantieren und auch eine schlechtere typecking für das vorhandene JavaScript zu haben. Darüber hinaus gibt es gültige Anwendungsfälle, in denen eine gemischte Codebasis relevant sein kann.

Warum bewahrt HMR meinen lokalen Komponentenzustand nicht?

HMR State Preservation wird mit einer Reihe von Gotchas geliefert! Es wurde aufgrund seines oft überraschenden Verhaltens standardmäßig sowohl in svelte-hmr als auch in @sveltejs/vite-plugin-svelte deaktiviert. Sie können die Details hier lesen.

Wenn Sie einen Zustand haben, der wichtig ist, um innerhalb einer Komponente zu bleiben, sollten Sie ein externes Geschäft erstellen, das nicht durch HMR ersetzt wird.

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