site: sync to current svelte.dev (sveltejs#10187)

documentation/docs/20-core-concepts/10-routing.md

@@ -19,20 +19,20 @@ Each route directory contains one or more _route files_, which can be identified
 A `+page.svelte` component defines a page of your app. By default, pages are rendered both on the server ([SSR](glossary#ssr)) for the initial request and in the browser ([CSR](glossary#csr)) for subsequent navigation.
 
 ```svelte
-/// file: src/routes/+page.svelte
+<!--- file: src/routes/+page.svelte --->
 <h1>Hello and welcome to my site!</h1>
 <a href="/about">About my site</a>
 ```
 
 ```svelte
-/// file: src/routes/about/+page.svelte
+<!--- file: src/routes/about/+page.svelte --->
 <h1>About this site</h1>
 <p>TODO...</p>
 <a href="/">Home</a>
 ```
 
 ```svelte
-/// file: src/routes/blog/[slug]/+page.svelte
+<!--- file: src/routes/blog/[slug]/+page.svelte --->
 <script>
 	/** @type {import('./$types').PageData} */
 	export let data;
@@ -119,7 +119,7 @@ A `+page.server.js` file can also export _actions_. If `load` lets you read data
 If an error occurs during `load`, SvelteKit will render a default error page. You can customise this error page on a per-route basis by adding an `+error.svelte` file:
 
 ```svelte
-/// file: src/routes/blog/[slug]/+error.svelte
+<!--- file: src/routes/blog/[slug]/+error.svelte --->
 <script>
 	import { page } from '$app/stores';
 </script>
@@ -188,7 +188,7 @@ Layouts can be _nested_. Suppose we don't just have a single `/settings` page, b
 We can create a layout that only applies to pages below `/settings` (while inheriting the root layout with the top-level nav):
 
 ```svelte
-/// file: src/routes/settings/+layout.svelte
+<!--- file: src/routes/settings/+layout.svelte --->
 <script>
 	/** @type {import('./$types').LayoutData} */
 	export let data;
@@ -229,7 +229,7 @@ If a `+layout.js` exports [page options](page-options) — `prerender`, `ssr` an
 Data returned from a layout's `load` function is also available to all its child pages:
 
 ```svelte
-/// file: src/routes/settings/profile/+page.svelte
+<!--- file: src/routes/settings/profile/+page.svelte --->
 <script>
 	/** @type {import('./$types').PageData} */
 	export let data;
@@ -286,7 +286,7 @@ If an error is thrown (either `throw error(...)` or an unexpected error), the re
 By exporting `POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`/`HEAD` handlers, `+server.js` files can be used to create a complete API:
 
 ```svelte
-/// file: src/routes/add/+page.svelte
+<!--- file: src/routes/add/+page.svelte --->
 <script>
 	let a = 0;
 	let b = 0;
@@ -340,7 +340,7 @@ Throughout the examples above, we've been importing types from a `$types.d.ts` f
 For example, annotating `export let data` with `PageData` (or `LayoutData`, for a `+layout.svelte` file) tells TypeScript that the type of `data` is whatever was returned from `load`:
 
 ```svelte
-/// file: src/routes/blog/[slug]/+page.svelte
+<!--- file: src/routes/blog/[slug]/+page.svelte --->
 <script>
 	/** @type {import('./$types').PageData} */
 	export let data;

documentation/docs/20-core-concepts/20-load.md

@@ -22,7 +22,7 @@ export function load({ params }) {
 ```
 
 ```svelte
-/// file: src/routes/blog/[slug]/+page.svelte
+<!--- file: src/routes/blog/[slug]/+page.svelte --->
 <script>
 	/** @type {import('./$types').PageData} */
 	export let data;
@@ -83,7 +83,7 @@ export async function load() {
 ```
 
 ```svelte
-/// file: src/routes/blog/[slug]/+layout.svelte
+<!--- file: src/routes/blog/[slug]/+layout.svelte --->
 <script>
 	/** @type {import('./$types').LayoutData} */
 	export let data;
@@ -141,7 +141,7 @@ The `+page.svelte` component, and each `+layout.svelte` component above it, has
 In some cases, we might need the opposite — a parent layout might need to access page data or data from a child layout. For example, the root layout might want to access a `title` property returned from a `load` function in `+page.js` or `+page.server.js`. This can be done with `$page.data`:
 
 ```svelte
-/// file: src/routes/+layout.svelte
+<!--- file: src/routes/+layout.svelte --->
 <script>
 	import { page } from '$app/stores';
 </script>
@@ -341,7 +341,7 @@ export async function load({ parent }) {
 ```
 
 ```svelte
-/// file: src/routes/abc/+page.svelte
+<!--- file: src/routes/abc/+page.svelte --->
 <script>
 	/** @type {import('./$types').PageData} */
 	export let data;
@@ -464,7 +464,7 @@ export function load() {
 This is useful for creating skeleton loading states, for example:
 
 ```svelte
-/// file: src/routes/+page.svelte
+<!--- file: src/routes/+page.svelte --->
 <script>
 	/** @type {import('./$types').PageData} */
 	export let data;
@@ -569,7 +569,7 @@ export async function load({ fetch, depends }) {
 ```
 
 ```svelte
-/// file: src/routes/random-number/+page.svelte
+<!--- file: src/routes/random-number/+page.svelte --->
 <script>
 	import { invalidate, invalidateAll } from '$app/navigation';
 

documentation/docs/20-core-concepts/30-form-actions.md

@@ -23,7 +23,7 @@ export const actions = {
 To invoke this action from the `/login` page, just add a `<form>` — no JavaScript needed:
 
 ```svelte
-/// file: src/routes/login/+page.svelte
+<!--- file: src/routes/login/+page.svelte --->
 <form method="POST">
 	<label>
 		Email
@@ -71,12 +71,12 @@ export const actions = {
 To invoke a named action, add a query parameter with the name prefixed by a `/` character:
 
 ```svelte
-/// file: src/routes/login/+page.svelte
+<!--- file: src/routes/login/+page.svelte --->
 <form method="POST" action="?/register">
 ```
 
 ```svelte
-/// file: src/routes/+layout.svelte
+<!--- file: src/routes/+layout.svelte --->
 <form method="POST" action="/login?/register">
 ```
 
@@ -133,7 +133,7 @@ export const actions = {
 ```
 
 ```svelte
-/// file: src/routes/login/+page.svelte
+<!--- file: src/routes/login/+page.svelte --->
 <script>
 	/** @type {import('./$types').PageData} */
 	export let data;
@@ -401,7 +401,7 @@ In all cases, [focus will be reset](accessibility#focus-management).
 We can also implement progressive enhancement ourselves, without `use:enhance`, with a normal event listener on the `<form>`:
 
 ```svelte
-/// file: src/routes/login/+page.svelte
+<!--- file: src/routes/login/+page.svelte --->
 <script>
 	import { invalidateAll, goto } from '$app/navigation';
 	import { applyAction, deserialize } from '$app/forms';
@@ -456,7 +456,7 @@ const response = await fetch(this.action, {
 Form actions are the preferred way to send data to the server, since they can be progressively enhanced, but you can also use [`+server.js`](routing#server) files to expose (for example) a JSON API. Here's how such an interaction could look like:
 
 ```svelte
-/// file: send-message/+page.svelte
+<!--- file: send-message/+page.svelte --->
 <script>
 	function rerun() {
 		fetch('/api/ci', {
@@ -469,7 +469,7 @@ Form actions are the preferred way to send data to the server, since they can be
 ```
 
 ```js
-// @errors: 2355 1360
+// @errors: 2355 1360 2322
 /// file: api/ci/+server.js
 
 /** @type {import('./$types').RequestHandler} */

documentation/docs/20-core-concepts/50-state-management.md

@@ -84,7 +84,7 @@ If you're not using SSR, then there's no risk of accidentally exposing one user'
 You might wonder how we're able to use `$page.data` and other [app stores](modules#$app-stores) if we can't use our own stores. The answer is that app stores on the server use Svelte's [context API](https://learn.svelte.dev/tutorial/context-api) — the store is attached to the component tree with `setContext`, and when you subscribe you retrieve it with `getContext`. We can do the same thing with our own stores:
 
 ```svelte
-/// file: src/routes/+layout.svelte
+<!--- file: src/routes/+layout.svelte --->
 <script>
 	import { setContext } from 'svelte';
 	import { writable } from 'svelte/store';
@@ -102,7 +102,7 @@ You might wonder how we're able to use `$page.data` and other [app stores](modul
 ```
 
 ```svelte
-/// file: src/routes/user/+page.svelte
+<!--- file: src/routes/user/+page.svelte --->
 <script>
 	import { getContext } from 'svelte';
 
@@ -122,7 +122,7 @@ If you're not using SSR (and can guarantee that you won't need to use SSR in fut
 When you navigate around your application, SvelteKit reuses existing layout and page components. For example, if you have a route like this...
 
 ```svelte
-/// file: src/routes/blog/[slug]/+page.svelte
+<!--- file: src/routes/blog/[slug]/+page.svelte --->
 <script>
 	/** @type {import('./$types').PageData} */
 	export let data;

documentation/docs/25-build-and-deploy/90-adapter-vercel.md

@@ -120,7 +120,7 @@ export function load() {
 ```
 
 ```svelte
-/// file: +layout.svelte
+<!--- file: +layout.svelte --->
 <script>
 	/** @type {import('./$types').LayoutServerData} */
 	export let data;

documentation/docs/30-advanced/10-advanced-routing.md

@@ -254,7 +254,7 @@ src/routes/
 Not all use cases are suited for layout grouping, nor should you feel compelled to use them. It might be that your use case would result in complex `(group)` nesting, or that you don't want to introduce a `(group)` for a single outlier. It's perfectly fine to use other means such as composition (reusable `load` functions or Svelte components) or if-statements to achieve what you want. The following example shows a layout that rewinds to the root layout and reuses components and functions that other layouts can also use:
 
 ```svelte
-/// file: src/routes/nested/route/+layout@.svelte
+<!--- file: src/routes/nested/route/+layout@.svelte --->
 <script>
 	import ReusableLayout from '$lib/ReusableLayout.svelte';
 	export let data;

documentation/docs/30-advanced/25-errors.md

@@ -43,7 +43,7 @@ export async function load({ params }) {
 This tells SvelteKit to set the response status code to 404 and render an [`+error.svelte`](routing#error) component, where `$page.error` is the object provided as the second argument to `error(...)`.
 
 ```svelte
-/// file: src/routes/+error.svelte
+<!--- file: src/routes/+error.svelte --->
 <script>
 	import { page } from '$app/stores';
 </script>

documentation/docs/30-advanced/65-snapshots.md

@@ -9,7 +9,7 @@ For example, if the user fills out a form but clicks a link before submitting, t
 To do this, export a `snapshot` object with `capture` and `restore` methods from a `+page.svelte` or `+layout.svelte`:
 
 ```svelte
-/// file: +page.svelte
+<!--- file: +page.svelte --->
 <script>
 	let comment = '';
 

documentation/docs/40-best-practices/10-accessibility.md

@@ -17,7 +17,7 @@ Since navigation between pages in SvelteKit happens without reloading the page (
 Because of this behavior, every page in your app should have a unique, descriptive title. In SvelteKit, you can do this by placing a `<svelte:head>` element on each page:
 
 ```svelte
-/// file: src/routes/+page.svelte
+<!--- file: src/routes/+page.svelte --->
 <svelte:head>
 	<title>Todo List</title>
 </svelte:head>

documentation/docs/50-reference/40-types.md

@@ -22,10 +22,10 @@ The `RequestHandler` and `Load` types both accept a `Params` argument allowing y
 /// file: src/routes/[foo]/[bar]/[baz]/+page.server.js
 // @errors: 2355 2322 1360
 /** @type {import('@sveltejs/kit').RequestHandler<{
- *   foo: string;
- *   bar: string;
- *   baz: string
- * }>} */
+    foo: string;
+    bar: string;
+    baz: string
+  }>} */
 export async function GET({ params }) {
 	// ...
 }
@@ -98,7 +98,7 @@ export async function load({ params, fetch }) {
 
 > For this to work, your own `tsconfig.json` or `jsconfig.json` should extend from the generated `.svelte-kit/tsconfig.json` (where `.svelte-kit` is your [`outDir`](configuration#outdir)):
 >
->     { "extends": "./.svelte-kit/tsconfig.json" }
+> `{ "extends": "./.svelte-kit/tsconfig.json" }`
 
 ### Default tsconfig.json
 

documentation/faq/80-integrations.md → documentation/docs/60-appendix/01-faq.md

@@ -1,12 +1,54 @@
 ---
-title: How do I use X with SvelteKit?
+title: Frequently asked questions
 ---
 
-Make sure you've read the [documentation section on integrations](docs/integrations). If you're still having trouble, solutions to common issues are listed below.
+## Other resources
+
+Please see [the Svelte FAQ](https://svelte.dev/faq) and [`vite-plugin-svelte` FAQ](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md) as well for the answers to questions deriving from those libraries.
+
+## How do I use HMR with SvelteKit?
+
+SvelteKit has HMR enabled by default powered by [svelte-hmr](https://github.com/sveltejs/svelte-hmr). If you saw [Rich's presentation at the 2020 Svelte Summit](https://svelte.dev/blog/whats-the-deal-with-sveltekit), you may have seen a more powerful-looking version of HMR presented. This demo had `svelte-hmr`'s `preserveLocalState` flag on. This flag is now off by default because it may lead to unexpected behaviour and edge cases. But don't worry, you are still getting HMR with SvelteKit! If you'd like to preserve local state you can use the `@hmr:keep` or `@hmr:keep-all` directives as documented on the [svelte-hmr](https://github.com/sveltejs/svelte-hmr) page.
+
+## How do I include details from package.json in my application?
+
+You cannot directly require JSON files, since SvelteKit expects [`svelte.config.js`](./configuration) to be an ES module. If you'd like to include your application's version number or other information from `package.json` in your application, you can load JSON like so:
+
+```js
+/// file: svelte.config.js
+// @filename: index.js
+/// <reference types="@types/node" />
+import { URL } from 'node:url';
+// ---cut---
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const path = fileURLToPath(new URL('package.json', import.meta.url));
+const pkg = JSON.parse(readFileSync(path, 'utf8'));
+```
+
+## How do I fix the error I'm getting trying to include a package?
+
+Most issues related to including a library are due to incorrect packaging. You can check if a library's packaging is compatible with Node.js by entering it into [the publint website](https://publint.dev/).
+
+Here are a few things to keep in mind when checking if a library is packaged correctly:
+
+- `exports` takes precedence over the other entry point fields such as `main` and `module`. Adding an `exports` field may not be backwards-compatible as it prevents deep imports.
+- ESM files should end with `.mjs` unless `"type": "module"` is set in which any case CommonJS files should end with `.cjs`.
+- `main` should be defined if `exports` is not. It should be either a CommonJS or ESM file and adhere to the previous bullet. If a `module` field is defined, it should refer to an ESM file.
+- Svelte components should be distributed as uncompiled `.svelte` files with any JS in the package written as ESM only. Custom script and style languages, like TypeScript and SCSS, should be preprocessed as vanilla JS and CSS respectively. We recommend using [`svelte-package`](./packaging) for packaging Svelte libraries, which will do this for you.
+
+Libraries work best in the browser with Vite when they distribute an ESM version, especially if they are dependencies of a Svelte component library. You may wish to suggest to library authors that they provide an ESM version. However, CommonJS (CJS) dependencies should work as well since, by default, [`vite-plugin-svelte` will ask Vite to pre-bundle them](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md#what-is-going-on-with-vite-and-pre-bundling-dependencies) using `esbuild` to convert them to ESM.
+
+If you are still encountering issues we recommend searching both [the Vite issue tracker](https://github.com/vitejs/vite/issues) and the issue tracker of the library in question. Sometimes issues can be worked around by fiddling with the [`optimizeDeps`](https://vitejs.dev/config/#dep-optimization-options) or [`ssr`](https://vitejs.dev/config/#ssr-options) config values though we recommend this as only a short-term workaround in favor of fixing the library in question.
+
+## How do I use X with SvelteKit?
+
+Make sure you've read the [documentation section on integrations](./integrations). If you're still having trouble, solutions to common issues are listed below.
 
 ### How do I setup a database?
 
-Put the code to query your database in a [server route](docs/routing#server) - don't query the database in .svelte files. You can create a `db.js` or similar that sets up a connection immediately and makes the client accessible throughout the app as a singleton. You can execute any one-time setup code in `hooks.js` and import your database helpers into any endpoint that needs them.
+Put the code to query your database in a [server route](./routing#server) - don't query the database in .svelte files. You can create a `db.js` or similar that sets up a connection immediately and makes the client accessible throughout the app as a singleton. You can execute any one-time setup code in `hooks.js` and import your database helpers into any endpoint that needs them.
 
 ### How do I use a client-side only library that depends on `document` or `window`?
 
@@ -75,11 +117,11 @@ onMount(() => {
 
 ### How do I use a different backend API server?
 
-You can use [`event.fetch`](docs/load#making-fetch-requests) to request data from an external API server, but be aware that you would need to deal with [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), which will result in complications such as generally requiring requests to be preflighted resulting in higher latency. Requests to a separate subdomain may also increase latency due to an additional DNS lookup, TLS setup, etc. If you wish to use this method, you may find [`handleFetch`](docs/hooks#server-hooks-handlefetch) helpful.
+You can use [`event.fetch`](./load#making-fetch-requests) to request data from an external API server, but be aware that you would need to deal with [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), which will result in complications such as generally requiring requests to be preflighted resulting in higher latency. Requests to a separate subdomain may also increase latency due to an additional DNS lookup, TLS setup, etc. If you wish to use this method, you may find [`handleFetch`](./hooks#server-hooks-handlefetch) helpful.
 
 Another approach is to set up a proxy to bypass CORS headaches. In production, you would rewrite a path like `/api` to the API server; for local development, use Vite's [`server.proxy`](https://vitejs.dev/config/server-options.html#server-proxy) option.
 
-How to setup rewrites in production will depend on your deployment platform. If rewrites aren't an option, you could alternatively add an [API route](https://kit.svelte.dev/docs/routing#server):
+How to setup rewrites in production will depend on your deployment platform. If rewrites aren't an option, you could alternatively add an [API route](./routing#server):
 
 ```js
 /// file: src/routes/api/[...path]/+server.js
@@ -96,6 +138,7 @@ export function GET({ params, url }) {
 `adapter-node` builds a middleware that you can use with your own server for production mode. In dev, you can add middleware to Vite by using a Vite plugin. For example:
 
 ```js
+// @errors: 2322
 // @filename: ambient.d.ts
 declare module '@sveltejs/kit/vite'; // TODO this feels unnecessary, why can't it 'see' the declarations?
 

documentation/faq/10-what-can-i-make-with-sveltekit.md → documentation/docs/60-appendix/10-what-can-i-make-with-sveltekit.md

@@ -19,4 +19,4 @@ SvelteKit can also be deployed to a wide spectrum of hosted architectures via [a
 
 In order to support SSR, a JS backend — such as Node.js or Deno-based server, serverless function, or edge function — is required.
 
-It is also possible to write custom adapters or leverage community adapters to deploy SvelteKit to more platforms such as specialized server environments, browser extensions, or native applications. See [How do I use X with SvelteKit](#integrations) for more examples and integrations.
+It is also possible to write custom adapters or leverage community adapters to deploy SvelteKit to more platforms such as specialized server environments, browser extensions, or native applications. See [How do I use X with SvelteKit](/docs/integrations) for more examples and integrations.