cachesdev/svelte-deep-knowledge

Svelte tiefgehendes Wissen

Verwende dies als Index für wahrscheinliche Wissenslücken. Überprüfe die relevanten APIs während der Planung und Implementierung gegen die offizielle Svelte-MCP.

Stand: 2026-11-01, basierend auf Svelte 5.57.3, SvelteKit 3.1.1 und SvelteKit 2.70.3.

Beginne mit den installierten Versionen

1. Überprüfe die Paketversionen und die Vite-Konfiguration. Passe die Anleitung an die installierte Kit-Hauptversion und die aktivierten experimentellen Flags an.
2. Rufe die list-sections der Svelte-MCP auf, rufe dann die relevanten Abschnitte zusammen mit get-documentation ab. Die MCP und svelte.dev enthalten die Kit 3 Dokumentation. Für ein Kit 2 Projekt lies die entsprechende Seite aus dem version-2 Branch von sveltejs/kit unter documentation/docs.
3. Für Kit 3 Projekte und Kit 2 → 3 Migrationen lies die Kit 3 Referenz. Für Kit 2 Projekte lies die Kit 2 Referenz.
4. Führe svelte-autofixer auf neuen oder bearbeiteten Svelte-Komponenten/-Modulen aus und behebe die anwendbaren Ergebnisse. Verwende die Projekt-Checks für Integration und Typen.

Beispiele für neue Svelte-APIs, asynchrones Rendern, Attachments und Compiler-Tools findest du in der Svelte-Referenz.

Remote-Funktionen, Grenzen und await

Bevorzuge für neue SvelteKit-Apps, die experimentelles Async einführen, Remote-Funktionen mit direktem await für Komponentendaten und granulare Grenzen für Lade-/Fehler-UI. Wähle die Platzierung von svelte:boundary basierend darauf, was auf dem Server gerendert werden muss.

• Aktiviere experimental.remoteFunctions und compilerOptions.experimental.async gemeinsam. Das offizielle Remote-Functions-Setup erfordert beide Flags.
• load, Formular-Aktionen und +server-Routen bleiben unterstützt, werden aber nicht empfohlen. Folge der bestehenden Architektur, es sei denn, die Aufgabe umfasst eine Migration.
• .loading, .error und .current bleiben unterstützte Query-APIs. Direktes await ist der bevorzugte Mechanismus.
• Verwende await query(args) in rendern und imperativen Kontexten.
• {#await} bleibt unterstützt, wenn auch nicht empfohlen, und hat sein eigenes Promise-Zustandsverhalten. Verwende direktes await und Grenzen für koordiniertes asynchrones Rendering; behalte {#await} bei, wenn sein Verhalten zur Aufgabe passt.

Überprüfe mit den MCP-Abschnitten kit/remote-functions, svelte/await-expressions und svelte/svelte-boundary.

Asynchrones Rendering-Verhalten

• Await auf Komponentenebene kam in Svelte 5.36; asynchrones SSR kam in 5.39. Await wird im Skript der obersten Ebene, in $derived und im Markup unterstützt.
• Svelte koordiniert abhängige UI-Updates, während asynchrone Arbeit aufgelöst wird. Unabhängige Template-Await-Ausdrücke werden gleichzeitig ausgeführt. Sequentielle Skript-Awaits erzeugen dennoch Wasserfälle; starte unabhängige Arbeit, bevor du auf ihre Ergebnisse wartest.
• Der pending-Snippet einer Grenze erscheint bei der initialen Erstellung. Verwende $effect.pending() für nachfolgende Arbeit in dieser Grenze; dessen Zählung schließt Kind-Grenzen aus.
• Während SSR rendert eine Grenze mit pending den Platzhalter und überspringt ihren Inhalt. Await-Ausdrücke außerhalb solcher Grenzen lösen sich auf, bevor await render(...) abgeschlossen ist. Platziere Inhalte, die im initialen HTML benötigt werden, entsprechend. Diese API bietet noch kein Streaming-SSR.
• $state.eager(value), hinzugefügt in 5.41, ermöglicht sofortiges Feedback, während koordinierte Updates warten. Verwende es für Benutzerfeedback wie einen aktiven Navigationsindikator.
• tick() wartet auf ausstehende Zustandsänderungen; settled(), hinzugefügt in 5.36, wartet auch auf asynchrone Arbeit, die dadurch verursacht wird, und die resultierenden DOM-Updates.

Fehlergrenzen

• <svelte:boundary> unterstützt failed(error, reset) und onerror(error, reset) für Rendering-/Effektfehler. Behandle Event-Handler und losgelöste asynchrone Fehler an ihren Aufrufstellen.
• failed-Snippets fangen seit Svelte 5.53 auch Fehler während SSR ab. In SvelteKit durchläuft der Fehler zuerst handleError, sodass der Snippet das bereinigte App.Error erhält. onerror wird ausgeführt, wenn die fehlgeschlagene Grenze hydriert.
• Kit 3 leitet Rendering-Fehler an handleError und die nächste +error.svelte, die als Grenze fungiert. Ein asynchroner Client-handleError benötigt compilerOptions.experimental.async. Kit 2.54+ benötigt experimental.handleRenderingErrors für dieselbe Integration.
• Der ältere "seit 5.51"-Hinweis in der Grenzen-Dokumentation widerspricht dem veröffentlichten Changelog. Verwende 5.53 als Einführungsversion und überprüfe aktuelle Patches, wenn du SSR-/Hydrierungsprobleme diagnostizierst.

Template-Features

Deklarationstags, Svelte 5.56+

• Bevorzuge {let ...} und {const ...} für markup-lokale Variablen. {@const} ist als Legacy dokumentiert und bleibt für ältere Projekte verfügbar.
• Einfache Deklarationen initialisieren Werte. Verwende explizite Runen für Reaktivität: {let count = $state(0)} und {const doubled = $derived(count * 2)}.
• Das Migrieren von reaktivem {@const area = width * height} erfordert {const area = $derived(width * height)}. Ein einfaches {const area = width * height} ist nicht reaktiv.
• Deklarationen verwenden lexikalischen Gültigkeitsbereich innerhalb ihres Elements/Blocks, können äußere Variablen überschatten und sollten der Verwendung vorausgehen. Mehrere Deklaratoren werden unterstützt.

Attachments

• Bevorzuge {@attach ...} für neue Element-Integrationen ab Svelte 5.29. Gib eine Aufräumfunktion vom Attachment zurück.
• Attachments verfolgen reaktive Lesevorgänge und werden bei Abhängigkeitsänderungen erneut ausgeführt. Falsche Werte deaktivieren sie. Vermeide das Wiederholen teurer Setups, indem du sich ändernde Optionen durch einen Getter innerhalb eines Kind-Effekts liest.
• Komponenten-Wrapper müssen Attachment-tragende Props an das vorgesehene Element weiterleiten. createAttachmentKey() unterstützt Attachments in Spread-Objekten.
• fromAction(action, () => argument) bewahrt das Verhalten einer bestehenden Aktion. Sein zweites Argument ist ein Getter. Dieser Helfer kam in 5.32, nach den Attachments selbst.

Klassen, Bindungen und HTML

• class akzeptiert seit 5.16 verschachtelte Arrays und Objekte. ClassValue von svelte/elements ist seit 5.19 für Wrapper-Props verfügbar.
• Funktionsbindungen verwenden bind:value={get, set} seit 5.9. Verwende null als Getter für schreibgeschützte Bindungen.
• Numerische Eingaben können bei leerem oder ungültigem Wert undefined erzeugen. Der Checkbox-Zustand kann mit bind:checked und bind:indeterminate verwendet werden; Radiogruppen verwenden bind:group.
• Eingaben unterstützen defaultValue/defaultChecked seit 5.6. Selects unterstützen defaultValue seit 5.57, einschließlich Formular-Reset-Verhalten. Überprüfe die Bindungs-Priorität, wenn du Standardwerte angibst.
• Anpassbare native Selects werden seit 5.47 unterstützt. Überprüfe die Browser-Unterstützung und das dokumentierte <selectedcontent>-Muster, bevor du ein benutzerdefiniertes Select-Widget ersetzt.
• JavaScript-artige Kommentare zwischen Attributen sind seit 5.53 gültig: <div /* Erklärung */ class="card">.
• {@html} akzeptiert seit 5.52 TrustedHTML. Die Unterstützung für Trusted Types bereinigt keine willkürlichen Eingaben; verwende eine vertrauenswürdige Quelle oder eine Bereinigungspolicy.

Each-Blöcke und Snippets

• {#each items as { id, name }} destrukturiert Elemente. Bereichsiteration kann {#each { length: 8 }, index} verwenden.
• Bevorzuge stabile Item-Keys für Listen, deren Identität wichtig ist. Wenn du ein Element bearbeitest, binde seine Eigenschaft über das Item-Objekt, sodass Mutationen die Quelle erreichen.
• Snippets werden im Markup deklariert und mit {@render snippet(...)} gerendert. Snippets der obersten Ebene können seit 5.5 aus <script module> exportiert werden, wenn sie keinen Instanzstatus erfassen.
• Snippets unterstützen seit 5.30 Generics. Komponenten-Generics verwenden <script lang="ts" generics="T">.
• Im Runes-Modus werden Komponentenvariablen dynamisch als <Component /> gerendert. Rekursive Komponenten können sich selbst importieren.

Runen und gemeinsamer Zustand

Zustand und Props

• $state.raw verfolgt Neuzuweisungen ohne tiefes Proxying. Verwende es für große Werte, die als Ganzes ersetzt werden. $state.snapshot extrahiert einfache Daten und respektiert toJSON().
• Klasseninstanzen werden nicht tiefgehend proxiert. Verwende $state-Felder oder ihre erste Konstruktorzuweisung seit 5.31. Reaktive Felder werden zu nicht aufzählbaren Accessoren; bewahre this, wenn du Methoden als Callbacks übergibst.
• Die Übergabe eines reaktiven Werts an eine Funktion übergibt seinen aktuellen Wert. Übergib einen Getter, wenn die Funktion zukünftige Werte benötigt. Das Destrukturieren eines Proxys liest ebenfalls aktuelle Werte.
• Verwende .svelte.js/.svelte.ts für gemeinsame Runen-Logik. Exportiere ein stabiles Zustandsobjekt oder Accessoren, wenn Verbraucher einen sich ändernden Zustand benötigen; das direkte Exportieren von neu zugewiesenem Runen-Zustand ist eingeschränkt.
• Begrenze benutzerspezifischen Zustand während SSR durch Komponentenkontext. Gemeinsamer Modulzustand kann über Anfragen hinweg leaken.
• $props.id(), hinzugefügt in 5.20, gibt eine Komponenteninstanz-ID, die zwischen SSR und Hydrierung übereinstimmt.
• $bindable() deklariert ein bindbares Prop. Props können lokal neu zugewiesen werden; das Mutieren eines nicht bindbaren Proxys des übergeordneten Elements löst Ownership-Warnungen aus. Fallback-Werte werden nicht automatisch proxied.
• Behalte den tatsächlichen nicht initialisierten Typ von $state<T>() bei, der undefined enthält, oder gib einen gültigen Anfangswert an. Verwende Narrowing an den Zugriffsstellen.

Deriveds und Effekte

• Verwende $derived(expression) oder $derived.by(fn) für berechnete Werte. Mit let deklarierte Deriveds können seit 5.25 für optimistische UI neu zugewiesen werden; Abhängigkeitsänderungen berechnen sie neu.
• Destrukturierte $derived-Werte bleiben reaktiv. Zurückgegebene Objekte sind nicht automatisch tiefe Proxies. Referentielle Gleichheit kann nachgelagerte Arbeit überspringen.
• Effekte verfolgen synchrone Lesevorgänge aus ihrem letzten Durchlauf. Lesevorgänge innerhalb eines gewöhnlichen asynchronen Callbacks nach await sind nicht automatisch Abhängigkeiten.
• $effect läuft im Browser. Gib die Aufräumfunktion synchron zurück; reserviere Effekte für externe Synchronisation und platziere benutzerausgelöste Arbeit in Handlern.
• $effect.tracking() erkennt einen Tracking-Kontext. $effect.root() erstellt einen manuell verwalteten Gültigkeitsbereich und gibt einen Entsorger zurück.
• getAbortSignal(), hinzugefügt in 5.35, muss innerhalb eines Effekts oder Deriveds ausgeführt werden. Sein Signal bricht bei erneuter Ausführung oder Zerstörung ab. Verwende es für Fetch-Arbeit, die dieser reaktiven Berechnung gehört.
• untrack(fn) schließt Lesevorgänge von der Abhängigkeitsverfolgung aus.
• $inspect(...).with(fn) erhält "init"/"update" gefolgt von Werten. $inspect.trace(label?), hinzugefügt in 5.14, muss die erste Anweisung in der getraceden Funktion sein.
• $host() ist für Custom Elements und gibt ihr Host-DOM-Element zurück.

Runtime-Module

• createContext<T>() bietet seit 5.40 typisierten Kontext. Seit 5.57 gibt es [get, set, has] zurück; has() prüft die Verfügbarkeit, bevor get(), das eine Ausnahme wirft, wenn nicht gesetzt. Die Kontextsuche umfasst die aktuelle Komponente und Vorfahren. Rufe Kontext-Accessoren während der Initialisierung auf und setze den Kontext vor dem ersten await im Skript. Seit 5.57.1 wirft ein späteres setContext set_context_after_init während SSR.
• svelte/reactivity bietet SvelteMap, SvelteSet, SvelteDate, SvelteURL und SvelteURLSearchParams. Map/Set-Einträge werden nicht tief reaktiv gemacht.
• Svelte 5.57 fügt SvelteMap.getOrInsert(key, value) und getOrInsertComputed(key, key => value) hinzu. Der berechnete Callback wird ausgeführt, wenn der Schlüssel fehlt, einschließlich der korrekten Behandlung vorhandener undefined-Einträge.
• MediaQuery und createSubscriber kamen in 5.7. Verwende createSubscriber, um externe Ereignisse mit getrackten Lesevorgängen zu verbinden, mit gemeinsamem Subscriptions-Setup und -Cleanup. MediaQuery akzeptiert einen SSR-Fallback; verwende CSS, wenn es dasselbe Verhalten ausdrücken kann.
• svelte/reactivity/window bietet seit 5.11 reaktive .current-Werte für Abmessungen, Scrollposition, Online-Status, Bildschirmposition und Pixelverhältnis. Berücksichtige nicht verfügbare Fensterwerte während SSR.
• on() von svelte/events bewahrt die Reihenfolge mit deklarativen Ereignis-Handlern und gibt Cleanup zurück. Verwende <svelte:window>/<svelte:document> für deklarative globale Listener.
• flushSync(fn?) spült ausstehende Updates synchron. createRawSnippet unterstützt programmatisches Markup mit Setup/Cleanup. getAllContexts() liefert die aktuelle Kontext-Map für programmatisches Mounting; rufe es während der Initialisierung auf.
• Spring und Tween von svelte/motion ersetzen seit 5.8 die veralteten spring()/tweened()-Stores. Beide exponieren .target, .current, .set() und .of(fn). Spring.set unterstützt preserveMomentum; prefersReducedMotion unterstützt barrierefreie Bewegungen.
• Seit 5.55 enthalten die Motion-Exporte TweenOptions, SpringOptions, SpringUpdateOptions und Updater.
• hydratable(key, fn), hinzugefügt in 5.44, serialisiert Daten zur Wiederverwendung während der Hydrierung. Es verwendet devalue und unterstützt verschachtelte Promises. Namespaced Keys vermeiden Kollisionen. Kit Remote Functions handhaben diese Schicht bereits.
• Mit CSP müssen benutzerdefinierte SSR-Integrationen render mit einem Nonce pro Antwort oder statischen Hashes konfigurieren und entsprechende Werte in die Antwort-Header setzen. Svelte 5.46 fügte Render-CSP-Unterstützung hinzu; 5.57 exportiert RenderOutput, SyncRenderOutput, Csp und Sha256Source aus svelte/server.
• Für Tooling konvertiert print() seit 5.45 einen modernen Svelte-AST in Quellcode; parseCss() kam in 5.48. Compiler-Optionen css, runes und customElement können seit 5.54 dateinamenabhängige Funktionen sein. Lese die Svelte-Referenz, bevor du diese APIs verwendest.

SvelteKit

Neue Apps verwenden Kit 3 (npx sv create). Migriere eine Kit 2 App mit npx sv migrate sveltekit-3 und arbeite dann die generierten TODOs ab. Kit 2 Anleitung gilt nur für Projekte, die auf 2.x bleiben.

Kit 3 Basis

• Kit 3 erfordert Node 22.17, TypeScript 6, Svelte 5.57.1, Vite 8.0.12 und vite-plugin-svelte 7.
• Die Konfiguration befindet sich in sveltekit({...}) innerhalb von vite.config.ts, mit Kit-Optionen auf oberster Ebene neben compilerOptions. Kit 3 liest die svelte.config.js nicht mehr.
• #lib ersetzt $lib durch Subpfad-Imports in package.json. Schreibe Dateierweiterungen, wie #lib/server/db.ts.
• Ein server-Dateinamensegment oder jedes server-Verzeichnis außerhalb von src/routes markiert ein Modul als serverseitig. Ein remote-Dateinamensegment, wie in data.remote.ts oder remote.ts, markiert ein Remote-Modul.
• Deklariere Umgebungsvariablen in src/env.ts mit defineEnvVars von @sveltejs/kit/env. Importiere Werte aus $app/env/private und $app/env/public sowie browser, building, dev, version aus $app/env. Öffentliche Variablen können in app.html als %sveltekit.env.NAME% erscheinen. $env/* und $app/environment sind veraltete Aliase.
• $app/stores ist entfernt; verwende $app/state. page.url ist schreibgeschützt; kopiere es mit new URL und berechne abgeleitete Werte in $derived.