Merge branch 'main' into generated-banner

Author: Rich-Harris

apps/svelte.dev/content/blog/2024-12-01-advent-of-svelte.md

@@ -71,13 +71,17 @@ You can now do `bind:value={get, set}` to validate and transform bound values. T
 - [docs](/docs/svelte/bind#Function-bindings)
 - [demo](/playground/1ddd82f573b94201b3c8fcab33bf0a46?version=5.9.0)
 
-## Day 9
+## Day 9: error and warning documentation
 
-Coming soon!
+When Svelte emits a warning or error (whether at build time, when the compiler is running, or when the app is running on the server or in the browser) it will now be accompanied by a link to the corresponding entry in the documentation containing a description (which is omitted from production builds, to save bytes) and — in some cases, with more to come — more details on why it happened and what you can do to fix it.
 
-## Day 10
+- [demo](/playground/8095884c1f5040ea846669b904083e25?version=5.10.0)
 
-Coming soon!
+## Day 10: SvelteKit `init` hooks
+
+A lot of you wanted a place to put asynchronous setup work that happens before your SvelteKit app starts up. You can now export an `init` function from `hooks.server.js` and `hooks.client.js` that will be awaited before any other stuff happens.
+
+- [docs](https://svelte.dev/docs/kit/hooks#Shared-hooks-init)
 
 ## Day 11
 

apps/svelte.dev/content/docs/kit/30-advanced/20-hooks.md

@@ -238,6 +238,25 @@ During development, if an error occurs because of a syntax error in your Svelte
 
 > [!NOTE] Make sure that `handleError` _never_ throws an error
 
+### init
+
+This function runs once, when the server is created or the app starts in the browser, and is a useful place to do asynchronous work such as initializing a database connection.
+
+> [!NOTE] If your environment supports top-level await, the `init` function is really no different from writing your initialisation logic at the top level of the module, but some environments — most notably, Safari — don't.
+
+```js
+/// file: src/hooks.server.js
+import * as db from '$lib/server/database';
+
+/** @type {import('@sveltejs/kit').ServerInit} */
+export async function init() {
+	await db.connect();
+}
+```
+
+> [!NOTE]
+> In the browser, asynchronous work in `init` will delay hydration, so be mindful of what you put in there.
+
 ## Universal hooks
 
 The following can be added to `src/hooks.js`. Universal hooks run on both server and client (not to be confused with shared hooks, which are environment-specific).

apps/svelte.dev/content/docs/kit/98-reference/[email protected]

@@ -854,6 +854,24 @@ Compress files in `directory` with gzip and brotli, where appropriate. Generates
 </div>
 </div></div>
 
+## ClientInit
+
+<blockquote class="since note">
+
+Available since 2.10.0
+
+</blockquote>
+
+The [`init`](/docs/kit/hooks#Shared-hooks-init) will be invoked once the app starts in the browser
+
+<div class="ts-block">
+
+```dts
+type ClientInit = () => MaybePromise<void>;
+```
+
+</div>
+
 ## Config
 
 See the [configuration reference](/docs/kit/configuration) for details.
@@ -2350,6 +2368,24 @@ A `[file]: size` map of all assets imported by server code
 </div>
 </div></div>
 
+## ServerInit
+
+<blockquote class="since note">
+
+Available since 2.10.0
+
+</blockquote>
+
+The [`init`](/docs/kit/hooks#Shared-hooks-init) will be invoked before the server responds to its first request
+
+<div class="ts-block">
+
+```dts
+type ServerInit = () => MaybePromise<void>;
+```
+
+</div>
+
 ## ServerInitOptions
 
 <div class="ts-block">

apps/svelte.dev/content/docs/kit/98-reference/20-$app-navigation.md

@@ -44,7 +44,7 @@ function afterNavigate(
 
 ## beforeNavigate
 
-A navigation interceptor that triggers before we navigate to a new URL, whether by clicking a link, calling `goto(...)`, or using the browser back/forward controls.
+A navigation interceptor that triggers before we navigate to a URL, whether by clicking a link, calling `goto(...)`, or using the browser back/forward controls.
 
 Calling `cancel()` will prevent the navigation from completing. If `navigation.type === 'leave'` — meaning the user is navigating away from the app (or closing the tab) — calling `cancel` will trigger the native browser unload confirmation dialog. In this case, the navigation may or may not be cancelled depending on the user's response.
 

apps/svelte.dev/content/docs/svelte/98-reference/.generated/client-warnings.md

@@ -66,6 +66,31 @@ The easiest way to log a value as it changes over time is to use the [`$inspect`
 The `%attribute%` attribute on `%html%` changed its value between server and client renders. The client value, `%value%`, will be ignored in favour of the server value
 ```
 
+Certain attributes like `src` on an `<img>` element will not be repaired during hydration, i.e. the server value will be kept. That's because updating these attributes can cause the image to be refetched (or in the case of an `<iframe>`, for the frame to be reloaded), even if they resolve to the same resource.
+
+To fix this, either silence the warning with a [`svelte-ignore`](basic-markup#Comments) comment, or ensure that the value stays the same between server and client. If you really need the value to change on hydration, you can force an update like this:
+
+```svelte
+<script>
+	let { src } = $props();
+
+	if (typeof window !== 'undefined') {
+		// stash the value...
+		const initial = src;
+
+		// unset it...
+		src = undefined;
+
+		$effect(() => {
+			// ...and reset after we've mounted
+			src = initial;
+		});
+	}
+</script>
+
+<img {src} />
+```
+
 ### hydration_html_changed
 
 ```
@@ -76,6 +101,31 @@ The value of an `{@html ...}` block changed between server and client renders. T
 The value of an `{@html ...}` block %location% changed between server and client renders. The client value will be ignored in favour of the server value
 ```
 
+If the `{@html ...}` value changes between the server and the client, it will not be repaired during hydration, i.e. the server value will be kept. That's because change detection during hydration is expensive and usually unnecessary.
+
+To fix this, either silence the warning with a [`svelte-ignore`](basic-markup#Comments) comment, or ensure that the value stays the same between server and client. If you really need the value to change on hydration, you can force an update like this:
+
+```svelte
+<script>
+	let { markup } = $props();
+
+	if (typeof window !== 'undefined') {
+		// stash the value...
+		const initial = markup;
+
+		// unset it...
+		markup = undefined;
+
+		$effect(() => {
+			// ...and reset after we've mounted
+			markup = initial;
+		});
+	}
+</script>
+
+{@html markup}
+```
+
 ### hydration_mismatch
 
 ```
@@ -86,6 +136,10 @@ Hydration failed because the initial UI does not match what was rendered on the
 Hydration failed because the initial UI does not match what was rendered on the server. The error occurred near %location%
 ```
 
+This warning is thrown when Svelte encounters an error while hydrating the HTML from the server. During hydration, Svelte walks the DOM, expecting a certain structure. If that structure is different (for example because the HTML was repaired by the DOM because of invalid HTML), then Svelte will run into issues, resulting in this warning.
+
+During development, this error is often preceeded by a `console.error` detailing the offending HTML, which needs fixing.
+
 ### invalid_raw_snippet_render
 
 ```
@@ -110,6 +164,10 @@ Tried to unmount a component that was not mounted
 %parent% passed a value to %child% with `bind:`, but the value is owned by %owner%. Consider creating a binding between %owner% and %parent%
 ```
 
+Consider three components `GrandParent`, `Parent` and `Child`. If you do `<GrandParent bind:value>`, inside `GrandParent` pass on the variable via `<Parent {value} />` (note the missing `bind:`) and then do `<Child bind:value>` inside `Parent`, this warning is thrown.
+
+To fix it, `bind:` to the value instead of just passing a property (i.e. in this example do `<Parent bind:value />`).
+
 ### ownership_invalid_mutation
 
 ```
@@ -120,6 +178,32 @@ Mutating a value outside the component that created it is strongly discouraged.
 %component% mutated a value owned by %owner%. This is strongly discouraged. Consider passing values to child components with `bind:`, or use a callback instead
 ```
 
+Consider the following code:
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	import Child from './Child.svelte';
+	let person = $state({ name: 'Florida', surname: 'Man' });
+</script>
+
+<Child {person} />
+```
+
+```svelte
+<!--- file: Child.svelte --->
+<script>
+	let { person } = $props();
+</script>
+
+<input bind:value={person.name}>
+<input bind:value={person.surname}>
+```
+
+`Child` is mutating `person` which is owned by `App` without being explicitly "allowed" to do so. This is strongly discouraged since it can create code that is hard to reason about at scale ("who mutated this value?"), hence the warning.
+
+To fix it, either create callback props to communicate changes, or mark `person` as [`$bindable`]($bindable).
+
 ### reactive_declaration_non_reactive_property
 
 ```

apps/svelte.dev/content/docs/svelte/98-reference/.generated/compile-warnings.md

@@ -610,6 +610,20 @@ Empty block
 Unused CSS selector "%name%"
 ```
 
+Svelte traverses both the template and the `<style>` tag to find out which of the CSS selectors are not used within the template, so it can remove them.
+
+In some situations a selector may target an element that is not 'visible' to the compiler, for example because it is part of an `{@html ...}` tag or you're overriding styles in a child component. In these cases, use [`:global`](/docs/svelte/global-styles) to preserve the selector as-is:
+
+```svelte
+<div class="post">{@html content}</div>
+
+<style>
+  .post :global {
+    p {...}
+  }
+</style>
+```
+
 ### element_invalid_self_closing_tag
 
 ```
@@ -622,6 +636,8 @@ Self-closing HTML tags for non-void elements are ambiguous — use `<%name% ...>
 Using `on:%name%` to listen to the %name% event is deprecated. Use the event attribute `on%name%` instead
 ```
 
+See [the migration guide](v5-migration-guide#Event-changes) for more info.
+
 ### export_let_unused
 
 ```
@@ -640,6 +656,8 @@ Component has unused export property '%name%'. If it is for external reference o
 Svelte 5 components are no longer classes. Instantiate them using `mount` or `hydrate` (imported from 'svelte') instead.
 ```
 
+See the [migration guide](v5-migration-guide#Components-are-no-longer-classes) for more info.
+
 ### node_invalid_placement_ssr
 
 ```
@@ -660,6 +678,30 @@ This code will work when the component is rendered on the client (which is why t
 `%name%` is updated, but is not declared with `$state(...)`. Changing its value will not correctly trigger updates
 ```
 
+This warning is thrown when the compiler detects the following:
+- a variable was declared without `$state` or `$state.raw`
+- the variable is reassigned
+- the variable is read in a reactive context
+
+In this case, changing the value will not correctly trigger updates. Example:
+
+```svelte
+<script>
+	let reactive = $state('reactive');
+	let stale = 'stale';
+</script>
+
+<p>This value updates: {reactive}</p>
+<p>This value does not update: {stale}</p>
+
+<button onclick={() => {
+	stale = 'updated';
+	reactive = 'updated';
+}}>update</button>
+```
+
+To fix this, wrap your variable declaration with `$state`.
+
 ### options_deprecated_accessors
 
 ```
@@ -732,6 +774,12 @@ Reassignments of module-level declarations will not cause reactive statements to
 `context="module"` is deprecated, use the `module` attribute instead
 ```
 
+```svelte
+<script ---context="module"--- +++context+++>
+	let foo = 'bar';
+</script>
+```
+
 ### script_unknown_attribute
 
 ```
@@ -744,12 +792,79 @@ Unrecognized attribute — should be one of `generics`, `lang` or `module`. If t
 Using `<slot>` to render parent content is deprecated. Use `{@render ...}` tags instead
 ```
 
+See [the migration guide](v5-migration-guide#Snippets-instead-of-slots) for more info.
+
 ### state_referenced_locally
 
 ```
 State referenced in its own scope will never update. Did you mean to reference it inside a closure?
 ```
 
+This warning is thrown when the compiler detects the following:
+- A reactive variable is declared
+- the variable is reassigned
+- the variable is referenced inside the same scope it is declared and it is a non-reactive context
+
+In this case, the state reassignment will not be noticed by whatever you passed it to. For example, if you pass the state to a function, that function will not notice the updates:
+
+```svelte
+<!--- file: Parent.svelte --->
+<script>
+	import { setContext } from 'svelte';
+
+	let count = $state(0);
+
+	// warning: state_referenced_locally
+	setContext('count', count);
+</script>
+
+<button onclick={() => count++}>
+	increment
+</button>
+```
+
+```svelte
+<!--- file: Child.svelte --->
+<script>
+	import { getContext } from 'svelte';
+
+	const count = getContext('count');
+</script>
+
+<!-- This will never update -->
+<p>The count is {count}</p>
+```
+
+To fix this, reference the variable such that it is lazily evaluated. For the above example, this can be achieved by wrapping `count` in a function:
+
+```svelte
+<!--- file: Parent.svelte --->
+<script>
+	import { setContext } from 'svelte';
+
+	let count = $state(0);
+	setContext('count', +++() => count+++);
+</script>
+
+<button onclick={() => count++}>
+	increment
+</button>
+```
+
+```svelte
+<!--- file: Child.svelte --->
+<script>
+	import { getContext } from 'svelte';
+
+	const count = getContext('count');
+</script>
+
+<!-- This will update -->
+<p>The count is {+++count()+++}</p>
+```
+
+For more info, see [Passing state into functions]($state#Passing-state-into-functions).
+
 ### store_rune_conflict
 
 ```
@@ -805,6 +920,8 @@ A derived value may be used in other contexts:
 `<svelte:self>` is deprecated — use self-imports (e.g. `import %name% from './%basename%'`) instead
 ```
 
+See [the note in the docs](legacy-svelte-self) for more info.
+
 ### unknown_code
 
 ```