From 213d70b39cc8ce430aa485ecfb046a1634dfcc77 Mon Sep 17 00:00:00 2001 From: Gonzalo Ruiz Date: Wed, 23 Oct 2024 18:36:07 +0200 Subject: [PATCH 1/5] docs: clarify svelte:component migration to avoid lowercase component name gotcha --- .../docs/07-misc/07-v5-migration-guide.md | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/documentation/docs/07-misc/07-v5-migration-guide.md b/documentation/docs/07-misc/07-v5-migration-guide.md index c7cdd36106ff..001b9591a3b3 100644 --- a/documentation/docs/07-misc/07-v5-migration-guide.md +++ b/documentation/docs/07-misc/07-v5-migration-guide.md @@ -613,6 +613,21 @@ To declare that a component of a certain type is required: ``` +Or using the [new syntax](#svelte-component-no-longer-necessary): + +```svelte + + +``` The two utility types `ComponentEvents` and `ComponentType` are also deprecated. `ComponentEvents` is obsolete because events are defined as callback props now, and `ComponentType` is obsolete because the new `Component` type is the component type already (e.g. `ComponentType>` == `Component<{ prop: string }>`). @@ -700,9 +715,9 @@ In Svelte 4, doing the following triggered reactivity: This is because the Svelte compiler treated the assignment to `foo.value` as an instruction to update anything that referenced `foo`. In Svelte 5, reactivity is determined at runtime rather than compile time, so you should define `value` as a reactive `$state` field on the `Foo` class. Wrapping `new Foo()` with `$state(...)` will have no effect — only vanilla objects and arrays are made deeply reactive. -### `` is no longer necessary +### `` is no longer necessary {#svelte-component-no-longer-necessary} -In Svelte 4, components are _static_ — if you render ``, and the value of `Thing` changes, [nothing happens](/playground/7f1fa24f0ab44c1089dcbb03568f8dfa?version=4.2.18). To make it dynamic you must use ``. +In Svelte 4, components are _static_ — if you render ``, and the value of `Thing` changes, [nothing happens](/playground/7f1fa24f0ab44c1089dcbb03568f8dfa?version=4.2.18). To make it dynamic you had to use ``. This is no longer true in Svelte 5: @@ -723,6 +738,7 @@ This is no longer true in Svelte 5: ``` +While migrating, keep in mind that your user-defined component's name should be capitalized (`Thing`) to distinguish it from a normal HTML element and avoid incorrect types. ### Touch and wheel events are passive From f5954fa6294db87a20ff66835aa98fb810789b05 Mon Sep 17 00:00:00 2001 From: Gonzalo Ruiz Date: Sat, 26 Oct 2024 18:14:23 +0200 Subject: [PATCH 2/5] docs: move section out of Breaking Changes, since it is not breaking. Change links. --- .../docs/07-misc/07-v5-migration-guide.md | 52 +++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/documentation/docs/07-misc/07-v5-migration-guide.md b/documentation/docs/07-misc/07-v5-migration-guide.md index 001b9591a3b3..52486446c384 100644 --- a/documentation/docs/07-misc/07-v5-migration-guide.md +++ b/documentation/docs/07-misc/07-v5-migration-guide.md @@ -613,7 +613,7 @@ To declare that a component of a certain type is required: ``` -Or using the [new syntax](#svelte-component-no-longer-necessary): +Or using the [new syntax](#svelte:component-is-no-longer-necessary): ```svelte + + + + + + +``` +While migrating, keep in mind that your user-defined component's name should be capitalized (`Thing`) to distinguish it from a normal HTML element and avoid incorrect types. + ## Whitespace handling changed Previously, Svelte employed a very complicated algorithm to determine if whitespace should be kept or not. Svelte 5 simplifies this which makes it easier to reason about as a developer. The rules are: @@ -715,31 +740,6 @@ In Svelte 4, doing the following triggered reactivity: This is because the Svelte compiler treated the assignment to `foo.value` as an instruction to update anything that referenced `foo`. In Svelte 5, reactivity is determined at runtime rather than compile time, so you should define `value` as a reactive `$state` field on the `Foo` class. Wrapping `new Foo()` with `$state(...)` will have no effect — only vanilla objects and arrays are made deeply reactive. -### `` is no longer necessary {#svelte-component-no-longer-necessary} - -In Svelte 4, components are _static_ — if you render ``, and the value of `Thing` changes, [nothing happens](/playground/7f1fa24f0ab44c1089dcbb03568f8dfa?version=4.2.18). To make it dynamic you had to use ``. - -This is no longer true in Svelte 5: - -```svelte - - - - - - - -``` -While migrating, keep in mind that your user-defined component's name should be capitalized (`Thing`) to distinguish it from a normal HTML element and avoid incorrect types. - ### Touch and wheel events are passive When using `onwheel`, `onmousewheel`, `ontouchstart` and `ontouchmove` event attributes, the handlers are [passive](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#using_passive_listeners) to align with browser defaults. This greatly improves responsiveness by allowing the browser to scroll the document immediately, rather than waiting to see if the event handler calls `event.preventDefault()`. From 11fb311c43aef15c5dfdb09083a310dac34c0436 Mon Sep 17 00:00:00 2001 From: Gonzalo Ruiz Date: Sat, 26 Oct 2024 18:16:13 +0200 Subject: [PATCH 3/5] docs: move migration dot notation component initialization notes to svelte:component section --- .../docs/07-misc/07-v5-migration-guide.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/documentation/docs/07-misc/07-v5-migration-guide.md b/documentation/docs/07-misc/07-v5-migration-guide.md index 52486446c384..1dc3e285c318 100644 --- a/documentation/docs/07-misc/07-v5-migration-guide.md +++ b/documentation/docs/07-misc/07-v5-migration-guide.md @@ -660,6 +660,16 @@ This is no longer true in Svelte 5: ``` While migrating, keep in mind that your user-defined component's name should be capitalized (`Thing`) to distinguish it from a normal HTML element and avoid incorrect types. +### Dot notation indicates a component + +In Svelte 4, `` would create an element with a tag name of `"foo.bar"`. In Svelte 5, `foo.bar` is treated as a component instead. This is particularly useful inside `each` blocks: + +```svelte +{#each items as item} + +{/each} +``` + ## Whitespace handling changed Previously, Svelte employed a very complicated algorithm to determine if whitespace should be kept or not. Svelte 5 simplifies this which makes it easier to reason about as a developer. The rules are: @@ -693,16 +703,6 @@ The `legacy` compiler option, which generated bulkier but IE-friendly code, no l Content inside component tags becomes a snippet prop called `children`. You cannot have a separate prop by that name. -## Dot notation indicates a component - -In Svelte 4, `` would create an element with a tag name of `"foo.bar"`. In Svelte 5, `foo.bar` is treated as a component instead. This is particularly useful inside `each` blocks: - -```svelte -{#each items as item} - -{/each} -``` - ## Breaking changes in runes mode Some breaking changes only apply once your component is in runes mode. From a583b9673656250a129c4902fb30faf411018eca Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 8 Jan 2025 14:54:29 -0500 Subject: [PATCH 4/5] tweaks --- .../docs/07-misc/07-v5-migration-guide.md | 41 +++++-------------- 1 file changed, 10 insertions(+), 31 deletions(-) diff --git a/documentation/docs/07-misc/07-v5-migration-guide.md b/documentation/docs/07-misc/07-v5-migration-guide.md index 991457f9d425..29179cd849c4 100644 --- a/documentation/docs/07-misc/07-v5-migration-guide.md +++ b/documentation/docs/07-misc/07-v5-migration-guide.md @@ -597,39 +597,18 @@ export declare const MyComponent: Component<{ To declare that a component of a certain type is required: -```svelte - - - -``` -Or using the [new syntax](#svelte:component-is-no-longer-necessary): +```js +import { ComponentA, ComponentB } from 'component-library'; +---import type { SvelteComponent } from 'svelte';--- ++++import type { Component } from 'svelte';+++ -```svelte - - +---let C: typeof SvelteComponent<{ foo: string }> = $state(--- ++++let C: Component<{ foo: string }> = $state(+++ + Math.random() ? ComponentA : ComponentB +); ``` -The two utility types `ComponentEvents` and `ComponentType` are also deprecated. `ComponentEvents` is obsolete because events are defined as callback props now, and `ComponentType` is obsolete because the new `Component` type is the component type already (e.g. `ComponentType>` == `Component<{ prop: string }>`). +The two utility types `ComponentEvents` and `ComponentType` are also deprecated. `ComponentEvents` is obsolete because events are defined as callback props now, and `ComponentType` is obsolete because the new `Component` type is the component type already (i.e. `ComponentType>` is equivalent to `Component<{ prop: string }>`). ### bind:this changes @@ -658,7 +637,7 @@ This is no longer true in Svelte 5: ``` -While migrating, keep in mind that your user-defined component's name should be capitalized (`Thing`) to distinguish it from a normal HTML element and avoid incorrect types. +While migrating, keep in mind that your component's name should be capitalized (`Thing`) to distinguish it from elements, unless using dot notation. ### Dot notation indicates a component From e0d6a7bc7d40ee28214dd8bbb82fdb9284b23631 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 8 Jan 2025 15:03:11 -0500 Subject: [PATCH 5/5] fix link --- documentation/docs/99-legacy/30-legacy-svelte-component.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/99-legacy/30-legacy-svelte-component.md b/documentation/docs/99-legacy/30-legacy-svelte-component.md index 3da2e3350e3f..a0407e58bfbf 100644 --- a/documentation/docs/99-legacy/30-legacy-svelte-component.md +++ b/documentation/docs/99-legacy/30-legacy-svelte-component.md @@ -2,7 +2,7 @@ title: --- -In runes mode, `` will re-render if the value of `MyComponent` changes. See the [Svelte 5 migration guide](/docs/svelte/v5-migration-guide#Breaking-changes-in-runes-mode-svelte:component-is-no-longer-necessary) for an example. +In runes mode, `` will re-render if the value of `MyComponent` changes. See the [Svelte 5 migration guide](/docs/svelte/v5-migration-guide#svelte:component-is-no-longer-necessary) for an example. In legacy mode, it won't — we must use ``, which destroys and recreates the component instance when the value of its `this` expression changes: