diff --git a/.changeset/fix-svelte-map-undefined.md b/.changeset/fix-svelte-map-undefined.md new file mode 100644 index 0000000000..fa981c46f8 --- /dev/null +++ b/.changeset/fix-svelte-map-undefined.md @@ -0,0 +1,5 @@ +--- +'svelte': patch +--- + +fix: `SvelteMap` incorrectly handles keys with `undefined` values diff --git a/.changeset/fix-svelte-url-search-normalization.md b/.changeset/fix-svelte-url-search-normalization.md new file mode 100644 index 0000000000..013acfd551 --- /dev/null +++ b/.changeset/fix-svelte-url-search-normalization.md @@ -0,0 +1,5 @@ +--- +'svelte': patch +--- + +fix: SvelteURL `search` setter now returns the normalized value, matching native URL behavior diff --git a/.changeset/itchy-carpets-watch.md b/.changeset/itchy-carpets-watch.md new file mode 100644 index 0000000000..2bafdae5ea --- /dev/null +++ b/.changeset/itchy-carpets-watch.md @@ -0,0 +1,5 @@ +--- +'svelte': patch +--- + +fix: visit synthetic value node during ssr diff --git a/.changeset/proud-seas-study.md b/.changeset/proud-seas-study.md new file mode 100644 index 0000000000..ec12b7232a --- /dev/null +++ b/.changeset/proud-seas-study.md @@ -0,0 +1,5 @@ +--- +'svelte': patch +--- + +fix: always case insensitive event handlers during ssr diff --git a/.changeset/tidy-brooms-train.md b/.changeset/tidy-brooms-train.md new file mode 100644 index 0000000000..4f680bd33f --- /dev/null +++ b/.changeset/tidy-brooms-train.md @@ -0,0 +1,5 @@ +--- +"svelte": patch +--- + +perf: optimize compiler analysis phase diff --git a/.well-known/funding-manifest-urls b/.well-known/funding-manifest-urls new file mode 100644 index 0000000000..b8ccc27b78 --- /dev/null +++ b/.well-known/funding-manifest-urls @@ -0,0 +1,2 @@ +https://svelte.dev/funding.json + diff --git a/documentation/docs/07-misc/01-best-practices.md b/documentation/docs/07-misc/01-best-practices.md new file mode 100644 index 0000000000..ac275e4d9a --- /dev/null +++ b/documentation/docs/07-misc/01-best-practices.md @@ -0,0 +1,184 @@ +--- +title: Best practices +name: svelte-core-bestpractices +description: Guidance on writing fast, robust, modern Svelte code. Load this skill whenever in a Svelte project and asked to write/edit or analyze a Svelte component or module. Covers reactivity, event handling, styling, integration with libraries and more. +--- + + +This document outlines some best practices that will help you write fast, robust Svelte apps. It is also available as a `svelte-core-bestpractices` skill for your agents. + + +## `$state` + +Only use the `$state` rune for variables that should be _reactive_ — in other words, variables that cause an `$effect`, `$derived` or template expression to update. Everything else can be a normal variable. + +Objects and arrays (`$state({...})` or `$state([...])`) are made deeply reactive, meaning mutation will trigger updates. This has a trade-off: in exchange for fine-grained reactivity, the objects must be proxied, which has performance overhead. In cases where you're dealing with large objects that are only ever reassigned (rather than mutated), use `$state.raw` instead. This is often the case with API responses, for example. + +## `$derived` + +To compute something from state, use `$derived` rather than `$effect`: + +```js +// @errors: 2451 +let num = 0; +// ---cut--- +// do this +let square = $derived(num * num); + +// don't do this +let square; + +$effect(() => { + square = num * num; +}); +``` + +> [!NOTE] `$derived` is given an expression, _not_ a function. If you need to use a function (because the expression is complex, for example) use `$derived.by`. + +Deriveds are writable — you can assign to them, just like `$state`, except that they will re-evaluate when their expression changes. + +If the derived expression is an object or array, it will be returned as-is — it is _not_ made deeply reactive. You can, however, use `$state` inside `$derived.by` in the rare cases that you need this. + +## `$effect` + +Effects are an escape hatch and should mostly be avoided. In particular, avoid updating state inside effects. + +- If you need to sync state to an external library such as D3, it is often neater to use [`{@attach ...}`](@attach) +- If you need to run some code in response to user interaction, put the code directly in an event handler or use a [function binding](bind#Function-bindings) as appropriate +- If you need to log values for debugging purposes, use [`$inspect`]($inspect) +- If you need to observe something external to Svelte, use [`createSubscriber`](svelte-reactivity#createSubscriber) + +Never wrap the contents of an effect in `if (browser) {...}` or similar — effects do not run on the server. + +## `$props` + +Treat props as though they will change. For example, values that depend on props should usually use `$derived`: + +```js +// @errors: 2451 +let { type } = $props(); + +// do this +let color = $derived(type === 'danger' ? 'red' : 'green'); + +// don't do this — `color` will not update if `type` changes +let color = type === 'danger' ? 'red' : 'green'; +``` + +## `$inspect.trace` + +`$inspect.trace` is a debugging tool for reactivity. If something is not updating properly or running more than it should you can add `$inspect.trace(label)` as the first line of an `$effect` or `$derived.by` (or any function they call) to trace their dependencies and discover which one triggered an update. + +## Events + +Any element attribute starting with `on` is treated as an event listener: + +```svelte + + + + + + + +``` + +If you need to attach listeners to `window` or `document` you can use `` and ``: + +```svelte + + +``` + +Avoid using `onMount` or `$effect` for this. + +## Snippets + +[Snippets](snippet) are a way to define reusable chunks of markup that can be instantiated with the [`{@render ...}`](@render) tag, or passed to components as props. They must be declared within the template. + +```svelte +{#snippet greeting(name)} +

hello {name}!

+{/snippet} + +{@render greeting('world')} +``` + +> [!NOTE] Snippets declared at the top level of a component (i.e. not inside elements or blocks) can be referenced inside ` + + + + + + + x + + + \ No newline at end of file diff --git a/packages/svelte/tests/server-side-rendering/samples/select-option-store-implicit-value/_expected.html b/packages/svelte/tests/server-side-rendering/samples/select-option-store-implicit-value/_expected.html new file mode 100644 index 0000000000..0a0a4351f1 --- /dev/null +++ b/packages/svelte/tests/server-side-rendering/samples/select-option-store-implicit-value/_expected.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/svelte/tests/server-side-rendering/samples/select-option-store-implicit-value/main.svelte b/packages/svelte/tests/server-side-rendering/samples/select-option-store-implicit-value/main.svelte new file mode 100644 index 0000000000..5d133d5bf3 --- /dev/null +++ b/packages/svelte/tests/server-side-rendering/samples/select-option-store-implicit-value/main.svelte @@ -0,0 +1,11 @@ + + + diff --git a/packages/svelte/tests/server-side-rendering/samples/select-option-store-text-content/_expected.html b/packages/svelte/tests/server-side-rendering/samples/select-option-store-text-content/_expected.html new file mode 100644 index 0000000000..daf2176928 --- /dev/null +++ b/packages/svelte/tests/server-side-rendering/samples/select-option-store-text-content/_expected.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/svelte/tests/server-side-rendering/samples/select-option-store-text-content/main.svelte b/packages/svelte/tests/server-side-rendering/samples/select-option-store-text-content/main.svelte new file mode 100644 index 0000000000..27055caad6 --- /dev/null +++ b/packages/svelte/tests/server-side-rendering/samples/select-option-store-text-content/main.svelte @@ -0,0 +1,13 @@ + + +