Merge branch 'main' into fix-highlighting

Author: Ocean-OS

.github/workflows/docs-preview-create.yml

@@ -19,6 +19,10 @@ on:
         description: 'Branch (eg. my-feature-branch)'
         required: true
         type: string
+      check_id:
+        description: 'The ID of the check that triggered this workflow'
+        required: false
+        type: string
 
 permissions:
   contents: write
@@ -62,7 +66,7 @@ jobs:
 
       - name: Push
         id: push
-        run: git add -A && git commit -m "sync docs" && git push -u origin ${{ env.BRANCH }} --force
+        run: git add -A && git commit -m "sync docs for check run ${{ inputs.check_id }}" && git push -u origin ${{ env.BRANCH }} --force
 
       - name: Request preview comment
         uses: peter-evans/repository-dispatch@v3

apps/svelte.dev/.prettierignore

@@ -1,3 +1,4 @@
 content/docs
 scripts/create-tutorial-zip/common/.svelte-kit
 land-110m.json
+src/lib/tutorial/adapters/common/unzip.cjs

apps/svelte.dev/content/docs/kit/20-core-concepts/20-load.md

@@ -207,7 +207,7 @@ Universal `load` functions are called with a `LoadEvent`, which has a `data` pro
 
 A universal `load` function can return an object containing any values, including things like custom classes and component constructors.
 
-A server `load` function must return data that can be serialized with [devalue](https://github.com/rich-harris/devalue) — anything that can be represented as JSON plus things like `BigInt`, `Date`, `Map`, `Set` and `RegExp`, or repeated/cyclical references — so that it can be transported over the network. Your data can include [promises](#Streaming-with-promises), in which case it will be streamed to browsers. If you need to serialize/deserialize custom types, use [transport hooks](https://svelte.dev/docs/kit/hooks#Universal-hooks-transport).
+A server `load` function must return data that can be serialized with [devalue](https://github.com/rich-harris/devalue) — anything that can be represented as JSON plus things like `BigInt`, `Date`, `Map`, `Set` and `RegExp`, or repeated/cyclical references — so that it can be transported over the network. Your data can include [promises](#Streaming-with-promises), in which case it will be streamed to browsers. If you need to serialize/deserialize custom types, use [transport hooks](hooks#Universal-hooks-transport).
 
 ### When to use which
 

apps/svelte.dev/content/docs/kit/20-core-concepts/60-remote-functions.md

@@ -419,7 +419,7 @@ The override will be applied immediately, and released when the submission compl
 
 By default, submitting a form will send a request to the URL indicated by the `<form>` element's [`action`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/form#attributes_for_form_submission) attribute, which in the case of a remote function is a property on the form object generated by SvelteKit.
 
-It's possible for a `<button>` inside the `<form>` to send the request to a _different_ URL, using the [`formaction`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button#formaction) attribute. For example, you might have a single form that allows you to login or register depending on which button was clicked.
+It's possible for a `<button>` inside the `<form>` to send the request to a _different_ URL, using the [`formaction`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button#formaction) attribute. For example, you might have a single form that allows you to log in or register depending on which button was clicked.
 
 This attribute exists on the `buttonProps` property of a form object:
 
@@ -453,7 +453,7 @@ The `command` function, like `form`, allows you to write data to the server. Unl
 
 > [!NOTE] Prefer `form` where possible, since it gracefully degrades if JavaScript is disabled or fails to load.
 
-As with `query`, if the function accepts an argument it should be [validated](#query-Query-arguments) by passing a [Standard Schema](https://standardschema.dev) as the first argument to `command`.
+As with `query`, if the function accepts an argument, it should be [validated](#query-Query-arguments) by passing a [Standard Schema](https://standardschema.dev) as the first argument to `command`.
 
 ```ts
 /// file: likes.remote.js
@@ -728,7 +728,7 @@ export const getStuff = query('unchecked', async ({ id }: { id: string }) => {
 
 ## Using `getRequestEvent`
 
-Inside `query`, `form` and `command` you can use [`getRequestEvent`](https://svelte.dev/docs/kit/$app-server#getRequestEvent) to get the current [`RequestEvent`](@sveltejs-kit#RequestEvent) object. This makes it easy to build abstractions for interacting with cookies, for example:
+Inside `query`, `form` and `command` you can use [`getRequestEvent`]($app-server#getRequestEvent) to get the current [`RequestEvent`](@sveltejs-kit#RequestEvent) object. This makes it easy to build abstractions for interacting with cookies, for example:
 
 ```ts
 /// file: user.remote.ts
@@ -757,4 +757,4 @@ Note that some properties of `RequestEvent` are different inside remote function
 
 ## Redirects
 
-Inside `query`, `form` and `prerender` functions it is possible to use the [`redirect(...)`](https://svelte.dev/docs/kit/@sveltejs-kit#redirect) function. It is *not* possible inside `command` functions, as you should avoid redirecting here. (If you absolutely have to, you can return a `{ redirect: location }` object and deal with it in the client.)
+Inside `query`, `form` and `prerender` functions it is possible to use the [`redirect(...)`](@sveltejs-kit#redirect) function. It is *not* possible inside `command` functions, as you should avoid redirecting here. (If you absolutely have to, you can return a `{ redirect: location }` object and deal with it in the client.)

apps/svelte.dev/content/docs/kit/25-build-and-deploy/50-adapter-static.md

@@ -37,7 +37,9 @@ export default config;
 
 ```js
 /// file: src/routes/+layout.js
-// This can be false if you're using a fallback (i.e. SPA mode)
+// If you're using a fallback (i.e. SPA mode) you don't need to prerender all
+// pages by setting this here, but should prerender as many as possible to
+// avoid large performance and SEO impacts
 export const prerender = true;
 ```
 
@@ -77,7 +79,9 @@ The directory to write static assets (the contents of `static`, plus client-side
 
 ### fallback
 
-Specify a fallback page for [SPA mode](single-page-apps), e.g. `index.html` or `200.html` or `404.html`.
+To create a [single page app (SPA)](single-page-apps) you must specify the name of the fallback page to be generated by SvelteKit, which is used as the entry point for URLs that have not been prerendered. This is commonly `200.html`, but can vary depending on your deployment platform. You should avoid `index.html` where possible to avoid conflicting with a prerendered homepage. 
+
+> This option has large negative performance and SEO impacts. It is only recommended in certain circumstances such as wrapping the site in a mobile app. See the [single page apps](single-page-apps) documentation for more details and alternatives.
 
 ### precompress
 

apps/svelte.dev/content/docs/kit/25-build-and-deploy/55-single-page-apps.md

@@ -3,20 +3,21 @@ NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-doc
 title: Single-page apps
 ---
 
-You can turn any SvelteKit app, using any adapter, into a fully client-rendered single-page app (SPA) by disabling SSR at the root layout:
+You can turn a SvelteKit app into a fully client-rendered single-page app (SPA) by specifying a _fallback page_. This page will be served for any URLs that can't be served by other means such as returning a prerendered page.
 
+> [!NOTE] SPA mode has a large negative performance impact by forcing multiple network round trips (for the blank HTML document, then for the JavaScript, and then for any data needed for the page) before content can be shown. Unless you are serving the app from a local network (e.g.a mobile app that wraps a locally-served SPA) this will delay startup, especially when considering the latency of mobile devices. It also harms SEO by often causing sites to be downranked for performance (SPAs are much more likely to fail [Core Web Vitals](https://web.dev/explore/learn-core-web-vitals)), excluding search engines that don't render JS, and causing your site to receive less frequent updates from those that do. And finally, it makes your app inaccessible to users if JavaScript fails or is disabled (which happens [more often than you probably think](https://kryogenix.org/code/browser/everyonehasjs.html)).
+>
+> You can avoid these drawbacks by [prerendering](#Prerendering-individual-pages) as many pages as possible when using SPA mode (especially your homepage). If you can prerender all pages, you can simply use [static site generation](adapter-static) rather than a SPA. Otherwise, you should strongly consider using an adapter which supports server side rendering. SvelteKit has officially supported adapters for various providers with generous free tiers.
+
+## Usage
+
+First, disable SSR for the pages you don't want to prerender. These pages will be served via the fallback page. E.g. to serve all pages via the fallback by default, you can update the root layout as shown below. You should [opt back into prerendering individual pages and directories](#Prerendering-individual-pages) where possible.
 ```js
 /// file: src/routes/+layout.js
 export const ssr = false;
 ```
 
-> [!NOTE] In most situations this is not recommended: it harms SEO, tends to slow down perceived performance, and makes your app inaccessible to users if JavaScript fails or is disabled (which happens [more often than you probably think](https://kryogenix.org/code/browser/everyonehasjs.html)).
-
-If you don't have any server-side logic (i.e. `+page.server.js`, `+layout.server.js` or `+server.js` files) you can use [`adapter-static`](adapter-static) to create your SPA by adding a _fallback page_.
-
-## Usage
-
-Install with `npm i -D @sveltejs/adapter-static`, then add the adapter to your `svelte.config.js` with the following options:
+If you don't have any server-side logic (i.e. `+page.server.js`, `+layout.server.js` or `+server.js` files) you can use [`adapter-static`](adapter-static) to create your SPA. Install `adapter-static` with `npm i -D @sveltejs/adapter-static` and add it to your `svelte.config.js` with the `fallback` option:
 
 ```js
 /// file: svelte.config.js
@@ -36,10 +37,22 @@ export default config;
 
 The `fallback` page is an HTML page created by SvelteKit from your page template (e.g. `app.html`) that loads your app and navigates to the correct route. For example [Surge](https://surge.sh/help/adding-a-200-page-for-client-side-routing), a static web host, lets you add a `200.html` file that will handle any requests that don't correspond to static assets or prerendered pages.
 
-On some hosts it may be `index.html` or something else entirely — consult your platform's documentation.
+On some hosts it may be something else entirely — consult your platform's documentation. We recommend avoiding `index.html` if possible as it may conflict with prerendering.
 
 > [!NOTE] Note that the fallback page will always contain absolute asset paths (i.e. beginning with `/` rather than `.`) regardless of the value of [`paths.relative`](configuration#paths), since it is used to respond to requests for arbitrary paths.
 
+## Prerendering individual pages
+
+If you want certain pages to be prerendered, you can re-enable `ssr` alongside `prerender` for just those parts of your app:
+
+```js
+/// file: src/routes/my-prerendered-page/+page.js
+export const prerender = true;
+export const ssr = true;
+```
+
+You won't need a Node server or server capable of running JavaScript to deploy this page. It will only server render your page while building your project for the purposes of outputting an `.html` page that can be served from any static web host.
+
 ## Apache
 
 To run an SPA on [Apache](https://httpd.apache.org/), you should add a `static/.htaccess` file to route requests to the fallback page:
@@ -54,13 +67,3 @@ To run an SPA on [Apache](https://httpd.apache.org/), you should add a `static/.
 	RewriteRule . /200.html [L]
 </IfModule>
 ```
-
-## Prerendering individual pages
-
-If you want certain pages to be prerendered, you can re-enable `ssr` alongside `prerender` for just those parts of your app:
-
-```js
-/// file: src/routes/my-prerendered-page/+page.js
-export const prerender = true;
-export const ssr = true;
-```

apps/svelte.dev/content/docs/kit/25-build-and-deploy/60-adapter-cloudflare.md

@@ -238,7 +238,7 @@ export default config;
 /// file: wrangler.toml
 ---site.bucket = ".cloudflare/public"---
 +++assets.directory = ".cloudflare/public"
-assets.binding = "ASSETS"+++
+assets.binding = "ASSETS" # Exclude this if you don't have a `main` key configured.+++
 ```
 
 ### wrangler.jsonc
@@ -251,7 +251,7 @@ assets.binding = "ASSETS"+++
 	},---
 +++	"assets": {
 		"directory": ".cloudflare/public",
-		"binding": "ASSETS"
+		"binding": "ASSETS" // Exclude this if you don't have a `main` key configured.
 	}+++
 }
 ```

apps/svelte.dev/content/docs/kit/25-build-and-deploy/90-adapter-vercel.md

@@ -195,3 +195,7 @@ You can't use `fs` in edge functions.
 You _can_ use it in serverless functions, but it won't work as expected, since files are not copied from your project into your deployment. Instead, use the [`read`]($app-server#read) function from `$app/server` to access your files. It also works inside routes deployed as edge functions by fetching the file from the deployed public assets location.
 
 Alternatively, you can [prerender](page-options#prerender) the routes in question.
+
+### Deployment protection
+
+If using [`read`]($app-server#read) in an edge function, SvelteKit will `fetch` the file in question from your deployment. If you are using [Deployment Protection](https://vercel.com/docs/deployment-protection), you must also enable [Protection Bypass for Automation](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation) so that the request does not result in a [401 Unauthorized](https://http.dog/401) response.

apps/svelte.dev/content/docs/kit/30-advanced/68-observability.md

@@ -70,7 +70,7 @@ To view your first trace, you'll need to set up a local collector. We'll use [Ja
 - Turn on the experimental flags mentioned earlier in your `svelte.config.js` file
 - Use your package manager to install the dependencies you'll need:
   ```sh
-  npm i @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-oltp-proto import-in-the-middle
+  npm i @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-proto import-in-the-middle
   ```
 - Create `src/instrumentation.server.js` with the following:
 

apps/svelte.dev/content/docs/kit/30-advanced/70-packaging.md

@@ -243,6 +243,7 @@ You can create so-called declaration maps (`d.ts.map` files) by setting `"declar
 - `-w`/`--watch` — watch files in `src/lib` for changes and rebuild the package
 - `-i`/`--input` — the input directory which contains all the files of the package. Defaults to `src/lib`
 - `-o`/`--output` — the output directory where the processed files are written to. Your `package.json`'s `exports` should point to files inside there, and the `files` array should include that folder. Defaults to `dist`
+- `-p`/`--preserve-output` — prevent deletion of the output directory before packaging. Defaults to `false`, which means that the output directory will be emptied first
 - `-t`/`--types` — whether or not to create type definitions (`d.ts` files). We strongly recommend doing this as it fosters ecosystem library quality. Defaults to `true`
 - `--tsconfig` - the path to a tsconfig or jsconfig. When not provided, searches for the next upper tsconfig/jsconfig in the workspace path.