diff --git a/apps/svelte.dev/content/blog/2022-11-01-whats-new-in-svelte-november-2022.md b/apps/svelte.dev/content/blog/2022-11-01-whats-new-in-svelte-november-2022.md index eba7d9f97f..44db8f84d2 100644 --- a/apps/svelte.dev/content/blog/2022-11-01-whats-new-in-svelte-november-2022.md +++ b/apps/svelte.dev/content/blog/2022-11-01-whats-new-in-svelte-november-2022.md @@ -13,7 +13,7 @@ There's also a _huge_ showcase to cover... so let's jump in! - The new `update` method for `use:enhance` lets you easily get back the default form behavior while augmenting it with your own logic ([docs](https://kit.svelte.dev/docs/form-actions#progressive-enhancement-use-enhance), [#7083](https://github.com/sveltejs/kit/pull/7083) and [#7326](https://github.com/sveltejs/kit/pull/7326)) - `[[optional]]` parameters are now available for routing ([docs](https://kit.svelte.dev/docs/advanced-routing#optional-parameters), [#7051](https://github.com/sveltejs/kit/pull/7051)) -- `goto` now has `invalidateAll` to (re-)run all `load` functions belonging to the new active page ([docs](https://kit.svelte.dev/docs/modules#$app-navigation-goto), [#7407](https://github.com/sveltejs/kit/pull/7407)) +- `goto` now has `invalidateAll` to (re-)run all `load` functions belonging to the new active page ([docs](https://kit.svelte.dev/docs/$app-navigation#goto), [#7407](https://github.com/sveltejs/kit/pull/7407)) - `config.kit.paths.base` is now used in adapters looking for static assets - fixing 404 issues across `adapter-netlify`, `adapter-vercel`, `adapter-cloudflare`, and `adapter-cloudflare-workers` ([#4448](https://github.com/sveltejs/kit/pull/4448)) ### Breaking changes: diff --git a/apps/svelte.dev/content/blog/2023-08-31-view-transitions.md b/apps/svelte.dev/content/blog/2023-08-31-view-transitions.md index 7a9c7b13f2..58c0267be5 100644 --- a/apps/svelte.dev/content/blog/2023-08-31-view-transitions.md +++ b/apps/svelte.dev/content/blog/2023-08-31-view-transitions.md @@ -7,7 +7,7 @@ authorURL: https://geoffrich.net The [view transitions API](https://developer.chrome.com/docs/web-platform/view-transitions/) has been sweeping the web development world lately, and for good reason. It streamlines the process of animating between two page states, which is especially useful for page transitions. -However, until now, you couldn’t easily use this API in a SvelteKit app, since it was difficult to slot into the right place in the navigation lifecycle. SvelteKit 1.24 brought a new [`onNavigate`](https://kit.svelte.dev/docs/modules#$app-navigation-onnavigate) lifecycle hook to make view transitions integration much easier – let’s dive in. +However, until now, you couldn’t easily use this API in a SvelteKit app, since it was difficult to slot into the right place in the navigation lifecycle. SvelteKit 1.24 brought a new [`onNavigate`](https://kit.svelte.dev/docs/$app-navigation#onNavigate) lifecycle hook to make view transitions integration much easier – let’s dive in. ## How view transitions work @@ -30,9 +30,9 @@ It’s important to note that view transitions is a browser API, not a SvelteKit ## How `onNavigate` works -Before learning how to write view transitions, let's highlight the function that makes it all possible: [`onNavigate`](https://kit.svelte.dev/docs/modules#$app-navigation-onnavigate). +Before learning how to write view transitions, let's highlight the function that makes it all possible: [`onNavigate`](https://kit.svelte.dev/docs/$app-navigation#onNavigate). -Until recently, SvelteKit had two navigation lifecycle functions: [`beforeNavigate`](https://kit.svelte.dev/docs/modules#$app-navigation-beforenavigate), which fires before a navigation starts, and [`afterNavigate`](https://kit.svelte.dev/docs/modules#$app-navigation-afternavigate), which fires after the page has been updated following a navigation. SvelteKit 1.24 introduces a third: `onNavigate`, which will fire on every navigation, immediately before the new page is rendered. Importantly, it will run _after_ any data loading for the page has completed – since starting a view transition prevents any interaction with the page, we want to start it as late as possible. +Until recently, SvelteKit had two navigation lifecycle functions: [`beforeNavigate`](https://kit.svelte.dev/docs/$app-navigation#beforeNavigate), which fires before a navigation starts, and [`afterNavigate`](https://kit.svelte.dev/docs/$app-navigation#afterNavigate), which fires after the page has been updated following a navigation. SvelteKit 1.24 introduces a third: `onNavigate`, which will fire on every navigation, immediately before the new page is rendered. Importantly, it will run _after_ any data loading for the page has completed – since starting a view transition prevents any interaction with the page, we want to start it as late as possible. You can also return a promise from `onNavigate`, which will suspend the navigation until it resolves. This will let us wait to complete the navigation until the view transition has started. diff --git a/apps/svelte.dev/content/docs/kit/10-getting-started/10-introduction.md b/apps/svelte.dev/content/docs/kit/10-getting-started/10-introduction.md index f4e88c5db8..ac329fafd6 100644 --- a/apps/svelte.dev/content/docs/kit/10-getting-started/10-introduction.md +++ b/apps/svelte.dev/content/docs/kit/10-getting-started/10-introduction.md @@ -12,7 +12,7 @@ title: Introduction SvelteKit is a framework for rapidly developing robust, performant web applications using [Svelte](https://svelte.dev/). If you're coming from React, SvelteKit is similar to Next. If you're coming from Vue, SvelteKit is similar to Nuxt. -To learn more about the kinds of applications you can build with SvelteKit, see the [FAQ](/docs/faq#what-can-i-make-with-sveltekit). +To learn more about the kinds of applications you can build with SvelteKit, see the [FAQ](faq#what-can-i-make-with-sveltekit). ## What is Svelte? diff --git a/apps/svelte.dev/content/docs/kit/10-getting-started/30-project-structure.md b/apps/svelte.dev/content/docs/kit/10-getting-started/30-project-structure.md index b8ba7fa0f8..c0962bc5ba 100644 --- a/apps/svelte.dev/content/docs/kit/10-getting-started/30-project-structure.md +++ b/apps/svelte.dev/content/docs/kit/10-getting-started/30-project-structure.md @@ -38,7 +38,7 @@ You'll also find common files like `.gitignore` and `.npmrc` (and `.prettierrc` The `src` directory contains the meat of your project. Everything except `src/routes` and `src/app.html` is optional. -- `lib` contains your library code (utilities and components), which can be imported via the [`$lib`](modules#$lib) alias, or packaged up for distribution using [`svelte-package`](packaging) +- `lib` contains your library code (utilities and components), which can be imported via the [`$lib`]($lib) alias, or packaged up for distribution using [`svelte-package`](packaging) - `server` contains your server-only library code. It can be imported by using the [`$lib/server`](server-only-modules) alias. SvelteKit will prevent you from importing these in client code. - `params` contains any [param matchers](advanced-routing#matching) your app needs - `routes` contains the [routes](routing) of your application. You can also colocate other components that are only used within a single route here @@ -83,7 +83,7 @@ This file (or `jsconfig.json`, if you prefer type-checked `.js` files over `.ts` ### vite.config.js -A SvelteKit project is really just a [Vite](https://vitejs.dev) project that uses the [`@sveltejs/kit/vite`](modules#sveltejs-kit-vite) plugin, along with any other [Vite configuration](https://vitejs.dev/config/). +A SvelteKit project is really just a [Vite](https://vitejs.dev) project that uses the [`@sveltejs/kit/vite`](@sveltejs-kit-vite) plugin, along with any other [Vite configuration](https://vitejs.dev/config/). ## Other files diff --git a/apps/svelte.dev/content/docs/kit/10-getting-started/40-web-standards.md b/apps/svelte.dev/content/docs/kit/10-getting-started/40-web-standards.md index 926fbb17f3..bf921a2a72 100644 --- a/apps/svelte.dev/content/docs/kit/10-getting-started/40-web-standards.md +++ b/apps/svelte.dev/content/docs/kit/10-getting-started/40-web-standards.md @@ -26,7 +26,7 @@ An instance of [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Res ### Headers -The [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) interface allows you to read incoming `request.headers` and set outgoing `response.headers`. For example, you can get the `request.headers` as shown below, and use the [`json` convenience function](modules#sveltejs-kit-json) to send modified `response.headers`: +The [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) interface allows you to read incoming `request.headers` and set outgoing `response.headers`. For example, you can get the `request.headers` as shown below, and use the [`json` convenience function](@sveltejs-kit#json) to send modified `response.headers`: ```js // @errors: 2461 @@ -78,7 +78,7 @@ Most of the time, your endpoints will return complete data, as in the `userAgent ## URL APIs -URLs are represented by the [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) interface, which includes useful properties like `origin` and `pathname` (and, in the browser, `hash`). This interface shows up in various places — `event.url` in [hooks](hooks) and [server routes](routing#server), [`$page.url`](modules#$app-stores) in [pages](routing#page), `from` and `to` in [`beforeNavigate` and `afterNavigate`](modules#$app-navigation) and so on. +URLs are represented by the [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) interface, which includes useful properties like `origin` and `pathname` (and, in the browser, `hash`). This interface shows up in various places — `event.url` in [hooks](hooks) and [server routes](routing#server), [`$page.url`]($app-stores) in [pages](routing#page), `from` and `to` in [`beforeNavigate` and `afterNavigate`]($app-navigation) and so on. ### URLSearchParams diff --git a/apps/svelte.dev/content/docs/kit/20-core-concepts/10-routing.md b/apps/svelte.dev/content/docs/kit/20-core-concepts/10-routing.md index 2ba9db472d..a0cd32077b 100644 --- a/apps/svelte.dev/content/docs/kit/20-core-concepts/10-routing.md +++ b/apps/svelte.dev/content/docs/kit/20-core-concepts/10-routing.md @@ -83,7 +83,7 @@ You can find more information about these in [page options](page-options). ### +page.server.js -If your `load` function can only run on the server — for example, if it needs to fetch data from a database or you need to access private [environment variables](modules#$env-static-private) like API keys — then you can rename `+page.js` to `+page.server.js` and change the `PageLoad` type to `PageServerLoad`. +If your `load` function can only run on the server — for example, if it needs to fetch data from a database or you need to access private [environment variables]($env-static-private) like API keys — then you can rename `+page.js` to `+page.server.js` and change the `PageLoad` type to `PageServerLoad`. ```js /// file: src/routes/blog/[slug]/+page.server.js @@ -283,7 +283,7 @@ export function GET({ url }) { The first argument to `Response` can be a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream), making it possible to stream large amounts of data or create server-sent events (unless deploying to platforms that buffer responses, like AWS Lambda). -You can use the [`error`](modules#sveltejs-kit-error), [`redirect`](modules#sveltejs-kit-redirect) and [`json`](modules#sveltejs-kit-json) methods from `@sveltejs/kit` for convenience (but you don't have to). +You can use the [`error`](@sveltejs-kit#error), [`redirect`](@sveltejs-kit#redirect) and [`json`](@sveltejs-kit#json) methods from `@sveltejs/kit` for convenience (but you don't have to). If an error is thrown (either `error(...)` or an unexpected error), the response will be a JSON representation of the error or a fallback error page — which can be customised via `src/error.html` — depending on the `Accept` header. The [`+error.svelte`](#error) component will _not_ be rendered in this case. You can read more about error handling [here](errors). @@ -390,7 +390,7 @@ You can read more about omitting `$types` in our [blog post](https://svelte.dev/ Any other files inside a route directory are ignored by SvelteKit. This means you can colocate components and utility modules with the routes that need them. -If components and modules are needed by multiple routes, it's a good idea to put them in [`$lib`](modules#$lib). +If components and modules are needed by multiple routes, it's a good idea to put them in [`$lib`]($lib). ## Further reading diff --git a/apps/svelte.dev/content/docs/kit/20-core-concepts/20-load.md b/apps/svelte.dev/content/docs/kit/20-core-concepts/20-load.md index 5437a4fb4c..fb00198cd1 100644 --- a/apps/svelte.dev/content/docs/kit/20-core-concepts/20-load.md +++ b/apps/svelte.dev/content/docs/kit/20-core-concepts/20-load.md @@ -398,7 +398,7 @@ export async function load({ params, parent }) { ## Errors -If an error is thrown during `load`, the nearest [`+error.svelte`](routing#error) will be rendered. For [_expected_](/docs/errors#expected-errors) errors, use the `error` helper from `@sveltejs/kit` to specify the HTTP status code and an optional message: +If an error is thrown during `load`, the nearest [`+error.svelte`](routing#error) will be rendered. For [_expected_](errors#expected-errors) errors, use the `error` helper from `@sveltejs/kit` to specify the HTTP status code and an optional message: ```js /// file: src/routes/admin/+layout.server.js @@ -430,7 +430,7 @@ export function load({ locals }) { Calling `error(...)` will throw an exception, making it easy to stop execution from inside helper functions. -If an [_unexpected_](/docs/errors#unexpected-errors) error is thrown, SvelteKit will invoke [`handleError`](hooks#shared-hooks-handleerror) and treat it as a 500 Internal Error. +If an [_unexpected_](errors#unexpected-errors) error is thrown, SvelteKit will invoke [`handleError`](hooks#shared-hooks-handleerror) and treat it as a 500 Internal Error. > [In SvelteKit 1.x](migrating-to-sveltekit-2#redirect-and-error-are-no-longer-thrown-by-you) you had to `throw` the error yourself @@ -463,7 +463,7 @@ export function load({ locals }) { > Don't use `redirect()` inside a `try {...}` block, as the redirect will immediately trigger the catch statement. -In the browser, you can also navigate programmatically outside of a `load` function using [`goto`](modules#$app-navigation-goto) from [`$app.navigation`](modules#$app-navigation). +In the browser, you can also navigate programmatically outside of a `load` function using [`goto`]($app-navigation#goto) from [`$app.navigation`]($app-navigation). > [In SvelteKit 1.x](migrating-to-sveltekit-2#redirect-and-error-are-no-longer-thrown-by-you) you had to `throw` the `redirect` yourself @@ -615,7 +615,7 @@ export async function load({ untrack, url }) { ### Manual invalidation -You can also rerun `load` functions that apply to the current page using [`invalidate(url)`](modules#$app-navigation-invalidate), which reruns all `load` functions that depend on `url`, and [`invalidateAll()`](modules#$app-navigation-invalidateall), which reruns every `load` function. Server load functions will never automatically depend on a fetched `url` to avoid leaking secrets to the client. +You can also rerun `load` functions that apply to the current page using [`invalidate(url)`]($app-navigation#invalidate), which reruns all `load` functions that depend on `url`, and [`invalidateAll()`]($app-navigation#invalidateAll), which reruns every `load` function. Server load functions will never automatically depend on a fetched `url` to avoid leaking secrets to the client. A `load` function depends on `url` if it calls `fetch(url)` or `depends(url)`. Note that `url` can be a custom identifier that starts with `[a-z]:`: @@ -665,12 +665,12 @@ To summarize, a `load` function will rerun in the following situations: - It calls `url.searchParams.get(...)`, `url.searchParams.getAll(...)` or `url.searchParams.has(...)` and the parameter in question changes. Accessing other properties of `url.searchParams` will have the same effect as accessing `url.search`. - It calls `await parent()` and a parent `load` function reran - A child `load` function calls `await parent()` and is rerunning, and the parent is a server load function -- It declared a dependency on a specific URL via [`fetch`](#making-fetch-requests) (universal load only) or [`depends`](types#public-types-loadevent), and that URL was marked invalid with [`invalidate(url)`](modules#$app-navigation-invalidate) -- All active `load` functions were forcibly rerun with [`invalidateAll()`](modules#$app-navigation-invalidateall) +- It declared a dependency on a specific URL via [`fetch`](#making-fetch-requests) (universal load only) or [`depends`](types#public-types-loadevent), and that URL was marked invalid with [`invalidate(url)`]($app-navigation#invalidate) +- All active `load` functions were forcibly rerun with [`invalidateAll()`]($app-navigation#invalidateAll) -`params` and `url` can change in response to a `` link click, a [`
` interaction](form-actions#get-vs-post), a [`goto`](modules#$app-navigation-goto) invocation, or a [`redirect`](modules#sveltejs-kit-redirect). +`params` and `url` can change in response to a `` link click, a [`` interaction](form-actions#get-vs-post), a [`goto`]($app-navigation#goto) invocation, or a [`redirect`](@sveltejs-kit#redirect). -Note that rerunning a `load` function will update the `data` prop inside the corresponding `+layout.svelte` or `+page.svelte`; it does _not_ cause the component to be recreated. As a result, internal state is preserved. If this isn't what you want, you can reset whatever you need to reset inside an [`afterNavigate`](modules#$app-navigation-afternavigate) callback, and/or wrap your component in a [`{#key ...}`](https://svelte.dev/docs#template-syntax-key) block. +Note that rerunning a `load` function will update the `data` prop inside the corresponding `+layout.svelte` or `+page.svelte`; it does _not_ cause the component to be recreated. As a result, internal state is preserved. If this isn't what you want, you can reset whatever you need to reset inside an [`afterNavigate`]($app-navigation#afterNavigate) callback, and/or wrap your component in a [`{#key ...}`](https://svelte.dev/docs#template-syntax-key) block. ## Implications for authentication diff --git a/apps/svelte.dev/content/docs/kit/20-core-concepts/40-page-options.md b/apps/svelte.dev/content/docs/kit/20-core-concepts/40-page-options.md index 465d5c2efc..160fcf4356 100644 --- a/apps/svelte.dev/content/docs/kit/20-core-concepts/40-page-options.md +++ b/apps/svelte.dev/content/docs/kit/20-core-concepts/40-page-options.md @@ -35,7 +35,7 @@ export const prerender = 'auto'; The prerenderer will start at the root of your app and generate files for any prerenderable pages or `+server.js` routes it finds. Each page is scanned for `` elements that point to other pages that are candidates for prerendering — because of this, you generally don't need to specify which pages should be accessed. If you _do_ need to specify which pages should be accessed by the prerenderer, you can do so with [`config.kit.prerender.entries`](configuration#prerender), or by exporting an [`entries`](#entries) function from your dynamic route. -While prerendering, the value of `building` imported from [`$app/environment`](modules#$app-environment) will be `true`. +While prerendering, the value of `building` imported from [`$app/environment`]($app-environment) will be `true`. ### Prerendering server routes diff --git a/apps/svelte.dev/content/docs/kit/20-core-concepts/50-state-management.md b/apps/svelte.dev/content/docs/kit/20-core-concepts/50-state-management.md index 12dffc021c..39f47ff7a8 100644 --- a/apps/svelte.dev/content/docs/kit/20-core-concepts/50-state-management.md +++ b/apps/svelte.dev/content/docs/kit/20-core-concepts/50-state-management.md @@ -81,7 +81,7 @@ If you're not using SSR, then there's no risk of accidentally exposing one user' ## Using stores with context -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: +You might wonder how we're able to use `$page.data` and other [app stores]($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 @@ -155,7 +155,7 @@ Instead, we need to make the value [_reactive_](https://learn.svelte.dev/tutoria ``` -> If your code in `onMount` and `onDestroy` has to run again after navigation you can use [afterNavigate](modules#$app-navigation-afternavigate) and [beforeNavigate](modules#$app-navigation-beforenavigate) respectively. +> If your code in `onMount` and `onDestroy` has to run again after navigation you can use [afterNavigate]($app-navigation#afterNavigate) and [beforeNavigate]($app-navigation#beforeNavigate) respectively. Reusing components like this means that things like sidebar scroll state are preserved, and you can easily animate between changing values. In the case that you do need to completely destroy and remount a component on navigation, you can use this pattern: diff --git a/apps/svelte.dev/content/docs/kit/25-build-and-deploy/10-building-your-app.md b/apps/svelte.dev/content/docs/kit/25-build-and-deploy/10-building-your-app.md index d7c4cb71b5..4cf211adbf 100644 --- a/apps/svelte.dev/content/docs/kit/25-build-and-deploy/10-building-your-app.md +++ b/apps/svelte.dev/content/docs/kit/25-build-and-deploy/10-building-your-app.md @@ -10,7 +10,7 @@ Secondly, an _adapter_ takes this production build and tunes it for your target ## During the build -SvelteKit will load your `+page/layout(.server).js` files (and all files they import) for analysis during the build. Any code that should _not_ be executed at this stage must check that `building` from [`$app/environment`](modules#$app-environment) is `false`: +SvelteKit will load your `+page/layout(.server).js` files (and all files they import) for analysis during the build. Any code that should _not_ be executed at this stage must check that `building` from [`$app/environment`]($app-environment) is `false`: ```diff +import { building } from '$app/environment'; diff --git a/apps/svelte.dev/content/docs/kit/25-build-and-deploy/55-single-page-apps.md b/apps/svelte.dev/content/docs/kit/25-build-and-deploy/55-single-page-apps.md index efc73ca7a9..d20f94e772 100644 --- a/apps/svelte.dev/content/docs/kit/25-build-and-deploy/55-single-page-apps.md +++ b/apps/svelte.dev/content/docs/kit/25-build-and-deploy/55-single-page-apps.md @@ -35,7 +35,7 @@ The `fallback` page is an HTML page created by SvelteKit from your page template On some hosts it may be `index.html` or something else entirely — consult your platform's documentation. -> Note that the fallback page will always contain absolute asset paths (i.e. beginning with `/` rather than `.`) regardless of the value of [`paths.relative`](/docs/configuration#paths), since it is used to respond to requests for arbitrary paths. +> 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. ## Apache diff --git a/apps/svelte.dev/content/docs/kit/25-build-and-deploy/90-adapter-vercel.md b/apps/svelte.dev/content/docs/kit/25-build-and-deploy/90-adapter-vercel.md index 570e4cda70..2846b772c5 100644 --- a/apps/svelte.dev/content/docs/kit/25-build-and-deploy/90-adapter-vercel.md +++ b/apps/svelte.dev/content/docs/kit/25-build-and-deploy/90-adapter-vercel.md @@ -149,7 +149,7 @@ Since all of these variables are unchanged between build time and run time when ## Skew protection -When a new version of your app is deployed, assets belonging to the previous version may no longer be accessible. If a user is actively using your app when this happens, it can cause errors when they navigate — this is known as _version skew_. SvelteKit mitigates this by detecting errors resulting from version skew and causing a hard reload to get the latest version of the app, but this will cause any client-side state to be lost. (You can also proactively mitigate it by observing the [`updated`](/docs/modules#$app-stores-updated) store value, which tells clients when a new version has been deployed.) +When a new version of your app is deployed, assets belonging to the previous version may no longer be accessible. If a user is actively using your app when this happens, it can cause errors when they navigate — this is known as _version skew_. SvelteKit mitigates this by detecting errors resulting from version skew and causing a hard reload to get the latest version of the app, but this will cause any client-side state to be lost. (You can also proactively mitigate it by observing the [`updated`]($app-stores#updated) store value, which tells clients when a new version has been deployed.) [Skew protection](https://vercel.com/docs/deployments/skew-protection) is a Vercel feature that routes client requests to their original deployment. When a user visits your app, a cookie is set with the deployment ID, and any subsequent requests will be routed to that deployment for as long as skew protection is active. When they reload the page, they will get the newest deployment. (The `updated` store is exempted from this behaviour, and so will continue to report new deployments.) To enable it, visit the Advanced section of your project settings on Vercel. diff --git a/apps/svelte.dev/content/docs/kit/30-advanced/20-hooks.md b/apps/svelte.dev/content/docs/kit/30-advanced/20-hooks.md index 1dfab113a7..58c8f8c35c 100644 --- a/apps/svelte.dev/content/docs/kit/30-advanced/20-hooks.md +++ b/apps/svelte.dev/content/docs/kit/30-advanced/20-hooks.md @@ -67,7 +67,7 @@ export async function handle({ event, resolve }) { } ``` -You can define multiple `handle` functions and execute them with [the `sequence` helper function](modules#sveltejs-kit-hooks). +You can define multiple `handle` functions and execute them with [the `sequence` helper function](@sveltejs-kit-hooks). `resolve` also supports a second, optional parameter that gives you more control over how the response will be rendered. That parameter is an object that can have the following fields: @@ -140,7 +140,7 @@ The following can be added to `src/hooks.server.js` _and_ `src/hooks.client.js`: ### handleError -If an [unexpected error](/docs/errors#unexpected-errors) is thrown during loading or rendering, this function will be called with the `error`, `event`, `status` code and `message`. This allows for two things: +If an [unexpected error](errors#unexpected-errors) is thrown during loading or rendering, this function will be called with the `error`, `event`, `status` code and `message`. This allows for two things: - you can log the error - you can generate a custom representation of the error that is safe to show to users, omitting sensitive details like messages and stack traces. The returned value, which defaults to `{ message }`, becomes the value of `$page.error`. @@ -227,7 +227,7 @@ export async function handleError({ error, event, status, message }) { > In `src/hooks.client.js`, the type of `handleError` is `HandleClientError` instead of `HandleServerError`, and `event` is a `NavigationEvent` rather than a `RequestEvent`. -This function is not called for _expected_ errors (those thrown with the [`error`](modules#sveltejs-kit-error) function imported from `@sveltejs/kit`). +This function is not called for _expected_ errors (those thrown with the [`error`](@sveltejs-kit#error) function imported from `@sveltejs/kit`). During development, if an error occurs because of a syntax error in your Svelte code, the passed in error has a `frame` property appended highlighting the location of the error. @@ -235,7 +235,7 @@ During development, if an error occurs because of a syntax error in your Svelte ## 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). +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). ### reroute diff --git a/apps/svelte.dev/content/docs/kit/30-advanced/25-errors.md b/apps/svelte.dev/content/docs/kit/30-advanced/25-errors.md index b594c6dd31..cb26b04a54 100644 --- a/apps/svelte.dev/content/docs/kit/30-advanced/25-errors.md +++ b/apps/svelte.dev/content/docs/kit/30-advanced/25-errors.md @@ -12,7 +12,7 @@ You can add additional properties, like a `code` or a tracking `id`, as shown in ## Expected errors -An _expected_ error is one created with the [`error`](modules#sveltejs-kit-error) helper imported from `@sveltejs/kit`: +An _expected_ error is one created with the [`error`](@sveltejs-kit#error) helper imported from `@sveltejs/kit`: ```js /// file: src/routes/blog/[slug]/+page.server.js diff --git a/apps/svelte.dev/content/docs/kit/30-advanced/40-service-workers.md b/apps/svelte.dev/content/docs/kit/30-advanced/40-service-workers.md index 11d8806987..f968a6ba2d 100644 --- a/apps/svelte.dev/content/docs/kit/30-advanced/40-service-workers.md +++ b/apps/svelte.dev/content/docs/kit/30-advanced/40-service-workers.md @@ -18,7 +18,7 @@ if ('serviceWorker' in navigator) { ## Inside the service worker -Inside the service worker you have access to the [`$service-worker` module](modules#$service-worker), which provides you with the paths to all static assets, build files and prerendered pages. You're also provided with an app version string, which you can use for creating a unique cache name, and the deployment's `base` path. If your Vite config specifies `define` (used for global variable replacements), this will be applied to service workers as well as your server/client builds. +Inside the service worker you have access to the [`$service-worker` module]($service-worker), which provides you with the paths to all static assets, build files and prerendered pages. You're also provided with an app version string, which you can use for creating a unique cache name, and the deployment's `base` path. If your Vite config specifies `define` (used for global variable replacements), this will be applied to service workers as well as your server/client builds. The following example caches the built app and any files in `static` eagerly, and caches all other requests as they happen. This would make each page work offline once visited. diff --git a/apps/svelte.dev/content/docs/kit/30-advanced/50-server-only-modules.md b/apps/svelte.dev/content/docs/kit/30-advanced/50-server-only-modules.md index 22e141d489..eb6d23f9c4 100644 --- a/apps/svelte.dev/content/docs/kit/30-advanced/50-server-only-modules.md +++ b/apps/svelte.dev/content/docs/kit/30-advanced/50-server-only-modules.md @@ -6,11 +6,11 @@ Like a good friend, SvelteKit keeps your secrets. When writing your backend and ## Private environment variables -The `$env/static/private` and `$env/dynamic/private` modules, which are covered in the [modules](modules) section, can only be imported into modules that only run on the server, such as [`hooks.server.js`](hooks#server-hooks) or [`+page.server.js`](routing#page-page-server-js). +The [`$env/static/private`]($env-static-private) and [`$env/dynamic/private`]($env-dynamic-private) modules can only be imported into modules that only run on the server, such as [`hooks.server.js`](hooks#server-hooks) or [`+page.server.js`](routing#page-page-server-js). ## Server-only utilities -The [`$app/server`](/docs/modules#$app-server) module, which contains a `read` function for reading assets from the filesystem, can likewise only be imported by code that runs on the server. +The [`$app/server`]($app-server) module, which contains a `read` function for reading assets from the filesystem, can likewise only be imported by code that runs on the server. ## Your modules diff --git a/apps/svelte.dev/content/docs/kit/30-advanced/67-shallow-routing.md b/apps/svelte.dev/content/docs/kit/30-advanced/67-shallow-routing.md index 0b85fbed5c..97a29c55de 100644 --- a/apps/svelte.dev/content/docs/kit/30-advanced/67-shallow-routing.md +++ b/apps/svelte.dev/content/docs/kit/30-advanced/67-shallow-routing.md @@ -6,7 +6,7 @@ As you navigate around a SvelteKit app, you create _history entries_. Clicking t Sometimes, it's useful to create history entries _without_ navigating. For example, you might want to show a modal dialog that the user can dismiss by navigating back. This is particularly valuable on mobile devices, where swipe gestures are often more natural than interacting directly with the UI. In these cases, a modal that is _not_ associated with a history entry can be a source of frustration, as a user may swipe backwards in an attempt to dismiss it and find themselves on the wrong page. -SvelteKit makes this possible with the [`pushState`](/docs/modules#$app-navigation-pushstate) and [`replaceState`](/docs/modules#$app-navigation-replacestate) functions, which allow you to associate state with a history entry without navigating. For example, to implement a history-driven modal: +SvelteKit makes this possible with the [`pushState`]($app-navigation#pushState) and [`replaceState`]($app-navigation#replaceState) functions, which allow you to associate state with a history entry without navigating. For example, to implement a history-driven modal: ```svelte @@ -33,7 +33,7 @@ The modal can be dismissed by navigating back (unsetting `$page.state.showModal` The first argument to `pushState` is the URL, relative to the current URL. To stay on the current URL, use `''`. -The second argument is the new page state, which can be accessed via the [page store](/docs/modules#$app-stores-page) as `$page.state`. You can make page state type-safe by declaring an [`App.PageState`](/docs/types#app) interface (usually in `src/app.d.ts`). +The second argument is the new page state, which can be accessed via the [page store]($app-stores#page) as `$page.state`. You can make page state type-safe by declaring an [`App.PageState`](types#app) interface (usually in `src/app.d.ts`). To set page state without creating a new history entry, use `replaceState` instead of `pushState`. @@ -41,7 +41,7 @@ To set page state without creating a new history entry, use `replaceState` inste When shallow routing, you may want to render another `+page.svelte` inside the current page. For example, clicking on a photo thumbnail could pop up the detail view without navigating to the photo page. -For this to work, you need to load the data that the `+page.svelte` expects. A convenient way to do this is to use [`preloadData`](/docs/modules#$app-navigation-preloaddata) inside the `click` handler of an `` element. If the element (or a parent) uses [`data-sveltekit-preload-data`](/docs/link-options#data-sveltekit-preload-data), the data will have already been requested, and `preloadData` will reuse that request. +For this to work, you need to load the data that the `+page.svelte` expects. A convenient way to do this is to use [`preloadData`]($app-navigation#preloadData) inside the `click` handler of an `` element. If the element (or a parent) uses [`data-sveltekit-preload-data`](link-options#data-sveltekit-preload-data), the data will have already been requested, and `preloadData` will reuse that request. ```svelte @@ -61,7 +61,7 @@ For this to work, you need to load the data that the `+page.svelte` expects. A c if (innerWidth < 640 // bail if the screen is too small || e.shiftKey // or the link is opened in a new window || e.metaKey || e.ctrlKey // or a new tab (mac: metaKey, win/linux: ctrlKey) - // should also consider clicking with a mouse scroll wheel + // should also consider clicking with a mouse scroll wheel ) return; // prevent navigation diff --git a/apps/svelte.dev/content/docs/kit/30-advanced/70-packaging.md b/apps/svelte.dev/content/docs/kit/30-advanced/70-packaging.md index 6455c2ce7d..90a1dab374 100644 --- a/apps/svelte.dev/content/docs/kit/30-advanced/70-packaging.md +++ b/apps/svelte.dev/content/docs/kit/30-advanced/70-packaging.md @@ -4,7 +4,7 @@ title: Packaging You can use SvelteKit to build apps as well as component libraries, using the `@sveltejs/package` package (`npm create svelte` has an option to set this up for you). -When you're creating an app, the contents of `src/routes` is the public-facing stuff; [`src/lib`](modules#$lib) contains your app's internal library. +When you're creating an app, the contents of `src/routes` is the public-facing stuff; [`src/lib`]($lib) contains your app's internal library. A component library has the exact same structure as a SvelteKit app, except that `src/lib` is the public-facing bit, and your root `package.json` is used to publish the package. `src/routes` might be a documentation or demo site that accompanies the library, or it might just be a sandbox you use during development. @@ -182,7 +182,7 @@ You can read more about that feature [here](https://www.typescriptlang.org/docs/ ## Best practices -You should avoid using [SvelteKit-specific modules](modules) like `$app` in your packages unless you intend for them to only be consumable by other SvelteKit projects. E.g. rather than using `import { browser } from '$app/environment'` you could use `import { BROWSER } from 'esm-env'` ([see esm-env docs](https://github.com/benmccann/esm-env)). You may also wish to pass in things like the current URL or a navigation action as a prop rather than relying directly on `$app/stores`, `$app/navigation`, etc. Writing your app in this more generic fashion will also make it easier to setup tools for testing, UI demos and so on. +You should avoid using SvelteKit-specific modules like `$app/environment` in your packages unless you intend for them to only be consumable by other SvelteKit projects. E.g. rather than using `import { browser } from '$app/environment'` you could use `import { BROWSER } from 'esm-env'` ([see esm-env docs](https://github.com/benmccann/esm-env)). You may also wish to pass in things like the current URL or a navigation action as a prop rather than relying directly on `$app/stores`, `$app/navigation`, etc. Writing your app in this more generic fashion will also make it easier to setup tools for testing, UI demos and so on. Ensure that you add [aliases](configuration#alias) via `svelte.config.js` (not `vite.config.js` or `tsconfig.json`), so that they are processed by `svelte-package`. diff --git a/apps/svelte.dev/content/docs/kit/40-best-practices/05-performance.md b/apps/svelte.dev/content/docs/kit/40-best-practices/05-performance.md index e66c200cbd..c7df362ebd 100644 --- a/apps/svelte.dev/content/docs/kit/40-best-practices/05-performance.md +++ b/apps/svelte.dev/content/docs/kit/40-best-practices/05-performance.md @@ -27,7 +27,7 @@ Your browser also includes useful developer tools for analysing your site, wheth * Firefox - [Network](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/) and [Performance](https://hacks.mozilla.org/2022/03/performance-tool-in-firefox-devtools-reloaded/) devtools * Safari - [enhancing the performance of your webpage](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/Web_Inspector_Tutorial/EnhancingyourWebpagesPerformance/EnhancingyourWebpagesPerformance.html) -Note that your site running locally in `dev` mode will exhibit different behaviour than your production app, so you should do performance testing in [preview](/docs/building-your-app#preview-your-app) mode after building. +Note that your site running locally in `dev` mode will exhibit different behaviour than your production app, so you should do performance testing in [preview](building-your-app#preview-your-app) mode after building. ### Instrumenting @@ -88,7 +88,7 @@ For slow-loading data that isn't needed immediately, the object returned from yo One of the biggest performance killers is what is referred to as a _waterfall_, which is a series of requests that is made sequentially. This can happen on the server or in the browser. - Asset waterfalls can occur in the browser when your HTML requests JS which requests CSS which requests a background image and web font. SvelteKit will largely solve this class of problems for you by adding [`modulepreload`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/modulepreload) tags or headers, but you should view [the network tab in your devtools](#diagnosing-issues) to check whether additional resources need to be preloaded. Pay special attention to this if you use web [fonts](#optimizing-assets-fonts) since they need to be handled manually. -- If a universal `load` function makes an API call to fetch the current user, then uses the details from that response to fetch a list of saved items, and then uses _that_ response to fetch the details for each item, the browser will end up making multiple sequential requests. This is deadly for performance, especially for users that are physically located far from your backend. Avoid this issue by using [server `load` functions](/docs/load#universal-vs-server) where possible. +- If a universal `load` function makes an API call to fetch the current user, then uses the details from that response to fetch a list of saved items, and then uses _that_ response to fetch the details for each item, the browser will end up making multiple sequential requests. This is deadly for performance, especially for users that are physically located far from your backend. Avoid this issue by using [server `load` functions](load#universal-vs-server) where possible. - Server `load` functions are also not immune to waterfalls (though they are much less costly since they rarely involve roundtrips with high latency). For example if you query a database to get the current user and then use that data to make a second query for a list of saved items, it will typically be more performant to issue a single query with a database join. ## Hosting diff --git a/apps/svelte.dev/content/docs/kit/40-best-practices/10-accessibility.md b/apps/svelte.dev/content/docs/kit/40-best-practices/10-accessibility.md index af82648370..dbe5d005a3 100644 --- a/apps/svelte.dev/content/docs/kit/40-best-practices/10-accessibility.md +++ b/apps/svelte.dev/content/docs/kit/40-best-practices/10-accessibility.md @@ -45,7 +45,7 @@ afterNavigate(() => { }); ``` -You can also programmatically navigate to a different page using the [`goto`](modules#$app-navigation-goto) function. By default, this will have the same client-side routing behavior as clicking on a link. However, `goto` also accepts a `keepFocus` option that will preserve the currently-focused element instead of resetting focus. If you enable this option, make sure the currently-focused element still exists on the page after navigation. If the element no longer exists, the user's focus will be lost, making for a confusing experience for assistive technology users. +You can also programmatically navigate to a different page using the [`goto`]($app-navigation#goto) function. By default, this will have the same client-side routing behavior as clicking on a link. However, `goto` also accepts a `keepFocus` option that will preserve the currently-focused element instead of resetting focus. If you enable this option, make sure the currently-focused element still exists on the page after navigation. If the element no longer exists, the user's focus will be lost, making for a confusing experience for assistive technology users. ## The "lang" attribute diff --git a/apps/svelte.dev/content/docs/kit/40-best-practices/20-seo.md b/apps/svelte.dev/content/docs/kit/40-best-practices/20-seo.md index cb94fc71e4..94ee1b1e16 100644 --- a/apps/svelte.dev/content/docs/kit/40-best-practices/20-seo.md +++ b/apps/svelte.dev/content/docs/kit/40-best-practices/20-seo.md @@ -26,7 +26,7 @@ SvelteKit redirects pathnames with trailing slashes to ones without (or vice ver Every page should have well-written and unique `` and `<meta name="description">` elements inside a [`<svelte:head>`](https://svelte.dev/docs#template-syntax-svelte-head). Guidance on how to write descriptive titles and descriptions, along with other suggestions on making content understandable by search engines, can be found on Google's [Lighthouse SEO audits](https://web.dev/lighthouse-seo/) documentation. -> A common pattern is to return SEO-related `data` from page [`load`](load) functions, then use it (as [`$page.data`](modules#$app-stores)) in a `<svelte:head>` in your root [layout](routing#layout). +> A common pattern is to return SEO-related `data` from page [`load`](load) functions, then use it (as [`$page.data`]($app-stores)) in a `<svelte:head>` in your root [layout](routing#layout). ### Sitemaps diff --git a/apps/svelte.dev/content/docs/kit/60-appendix/10-faq.md b/apps/svelte.dev/content/docs/kit/60-appendix/10-faq.md index c566fff8f9..6df2714ff8 100644 --- a/apps/svelte.dev/content/docs/kit/60-appendix/10-faq.md +++ b/apps/svelte.dev/content/docs/kit/60-appendix/10-faq.md @@ -10,18 +10,18 @@ Please see [the Svelte FAQ](https://svelte.dev/faq) and [`vite-plugin-svelte` FA SvelteKit can be used to create most kinds of applications. Out of the box, SvelteKit supports many features including: -- Dynamic page content with [load](/docs/load) functions and [API routes](/docs/routing#server). -- SEO-friendly dynamic content with [server-side rendering (SSR)](/docs/glossary#ssr). -- User-friendly progressively-enhanced interactive pages with SSR and [Form Actions](/docs/form-actions). -- Static pages with [prerendering](/docs/page-options#prerender). +- Dynamic page content with [load](load) functions and [API routes](routing#server). +- SEO-friendly dynamic content with [server-side rendering (SSR)](glossary#ssr). +- User-friendly progressively-enhanced interactive pages with SSR and [Form Actions](form-actions). +- Static pages with [prerendering](page-options#prerender). -SvelteKit can also be deployed to a wide spectrum of hosted architectures via [adapters](/docs/adapters). In cases where SSR is used (or server-side logic is added without prerendering), those functions will be adapted to the target backend. Some examples include: +SvelteKit can also be deployed to a wide spectrum of hosted architectures via [adapters](adapters). In cases where SSR is used (or server-side logic is added without prerendering), those functions will be adapted to the target backend. Some examples include: -- Self-hosted dynamic web applications with a [Node.js backend](/docs/adapter-node). -- Serverless web applications with backend loaders and APIs deployed as remote functions. See [zero-config deployments](/docs/adapter-auto) for popular deployment options. -- [Static pre-rendered sites](/docs/adapter-static) such as a blog or multi-page site hosted on a CDN or static host. Statically-generated sites are shipped without a backend. -- [Single-page Applications (SPAs)](/docs/single-page-apps) with client-side routing and rendering for API-driven dynamic content. SPAs are shipped without a backend and are not server-rendered. This option is commonly chosen when bundling SvelteKit with an app written in PHP, .Net, Java, C, Golang, Rust, etc. -- A mix of the above; some routes can be static, and some routes can use backend functions to fetch dynamic information. This can be configured with [page options](/docs/page-options) that includes the option to opt out of SSR. +- Self-hosted dynamic web applications with a [Node.js backend](adapter-node). +- Serverless web applications with backend loaders and APIs deployed as remote functions. See [zero-config deployments](adapter-auto) for popular deployment options. +- [Static pre-rendered sites](adapter-static) such as a blog or multi-page site hosted on a CDN or static host. Statically-generated sites are shipped without a backend. +- [Single-page Applications (SPAs)](single-page-apps) with client-side routing and rendering for API-driven dynamic content. SPAs are shipped without a backend and are not server-rendered. This option is commonly chosen when bundling SvelteKit with an app written in PHP, .Net, Java, C, Golang, Rust, etc. +- A mix of the above; some routes can be static, and some routes can use backend functions to fetch dynamic information. This can be configured with [page options](page-options) that includes the option to opt out of SSR. In order to support SSR, a JS backend — such as Node.js or Deno-based server, serverless function, or edge function — is required. @@ -65,7 +65,7 @@ If you are still encountering issues we recommend searching both [the Vite issue ## How do I use the view transitions API with SvelteKit? -While SvelteKit does not have any specific integration with [view transitions](https://developer.chrome.com/docs/web-platform/view-transitions/), you can call `document.startViewTransition` in [`onNavigate`](/docs/modules#$app-navigation-onnavigate) to trigger a view transition on every client-side navigation. +While SvelteKit does not have any specific integration with [view transitions](https://developer.chrome.com/docs/web-platform/view-transitions/), you can call `document.startViewTransition` in [`onNavigate`]($app-navigation#onNavigate) to trigger a view transition on every client-side navigation. ```js // @errors: 2339 2810 diff --git a/apps/svelte.dev/content/docs/kit/60-appendix/30-migrating-to-sveltekit-2.md b/apps/svelte.dev/content/docs/kit/60-appendix/30-migrating-to-sveltekit-2.md index 555fa4d886..ccb4d6763d 100644 --- a/apps/svelte.dev/content/docs/kit/60-appendix/30-migrating-to-sveltekit-2.md +++ b/apps/svelte.dev/content/docs/kit/60-appendix/30-migrating-to-sveltekit-2.md @@ -20,7 +20,7 @@ import { error } from '@sveltejs/kit' `svelte-migrate` will do these changes automatically for you. -If the error or redirect is thrown inside a `try {...}` block (hint: don't do this!), you can distinguish them from unexpected errors using [`isHttpError`](/docs/modules#sveltejs-kit-ishttperror) and [`isRedirect`](/docs/modules#sveltejs-kit-isredirect) imported from `@sveltejs/kit`. +If the error or redirect is thrown inside a `try {...}` block (hint: don't do this!), you can distinguish them from unexpected errors using [`isHttpError`](@sveltejs-kit#isHttpError) and [`isRedirect`](@sveltejs-kit#isRedirect) imported from `@sveltejs/kit`. ## path is required when setting cookies @@ -72,9 +72,9 @@ export function load({ fetch }) { ## paths are now relative by default -In SvelteKit 1, `%sveltekit.assets%` in your `app.html` was replaced with a relative path by default (i.e. `.` or `..` or `../..` etc, depending on the path being rendered) during server-side rendering unless the [`paths.relative`](/docs/configuration#paths) config option was explicitly set to `false`. The same was true for `base` and `assets` imported from `$app/paths`, but only if the `paths.relative` option was explicitly set to `true`. +In SvelteKit 1, `%sveltekit.assets%` in your `app.html` was replaced with a relative path by default (i.e. `.` or `..` or `../..` etc, depending on the path being rendered) during server-side rendering unless the [`paths.relative`](configuration#paths) config option was explicitly set to `false`. The same was true for `base` and `assets` imported from `$app/paths`, but only if the `paths.relative` option was explicitly set to `true`. -This inconsistency is fixed in version 2. Paths are either always relative or always absolute, depending on the value of [`paths.relative`](/docs/configuration#paths). It defaults to `true` as this results in more portable apps: if the `base` is something other than the app expected (as is the case when viewed on the [Internet Archive](https://archive.org/), for example) or unknown at build time (as is the case when deploying to [IPFS](https://ipfs.tech/) and so on), fewer things are likely to break. +This inconsistency is fixed in version 2. Paths are either always relative or always absolute, depending on the value of [`paths.relative`](configuration#paths). It defaults to `true` as this results in more portable apps: if the `base` is something other than the app expected (as is the case when viewed on the [Internet Archive](https://archive.org/), for example) or unknown at build time (as is the case when deploying to [IPFS](https://ipfs.tech/) and so on), fewer things are likely to break. ## Server fetches are not trackable anymore @@ -82,7 +82,7 @@ Previously it was possible to track URLs from `fetch`es on the server in order t ## `preloadCode` arguments must be prefixed with `base` -SvelteKit exposes two functions, [`preloadCode`](/docs/modules#$app-navigation-preloadcode) and [`preloadData`](/docs/modules#$app-navigation-preloaddata), for programmatically loading the code and data associated with a particular path. In version 1, there was a subtle inconsistency — the path passed to `preloadCode` did not need to be prefixed with the `base` path (if set), while the path passed to `preloadData` did. +SvelteKit exposes two functions, [`preloadCode`]($app-navigation#preloadCode) and [`preloadData`]($app-navigation#preloadData), for programmatically loading the code and data associated with a particular path. In version 1, there was a subtle inconsistency — the path passed to `preloadCode` did not need to be prefixed with the `base` path (if set), while the path passed to `preloadData` did. This is fixed in SvelteKit 2 — in both cases, the path should be prefixed with `base` if it is set. @@ -107,7 +107,7 @@ As such, SvelteKit 2 replaces `resolvePath` with a (slightly better named) funct ## Improved error handling -Errors are handled inconsistently in SvelteKit 1. Some errors trigger the `handleError` hook but there is no good way to discern their status (for example, the only way to tell a 404 from a 500 is by seeing if `event.route.id` is `null`), while others (such as 405 errors for `POST` requests to pages without actions) don't trigger `handleError` at all, but should. In the latter case, the resulting `$page.error` will deviate from the [`App.Error`](/docs/types#app-error) type, if it is specified. +Errors are handled inconsistently in SvelteKit 1. Some errors trigger the `handleError` hook but there is no good way to discern their status (for example, the only way to tell a 404 from a 500 is by seeing if `event.route.id` is `null`), while others (such as 405 errors for `POST` requests to pages without actions) don't trigger `handleError` at all, but should. In the latter case, the resulting `$page.error` will deviate from the [`App.Error`](types#app-error) type, if it is specified. SvelteKit 2 cleans this up by calling `handleError` hooks with two new properties: `status` and `message`. For errors thrown from your code (or library code called by your code) the status will be `500` and the message will be `Internal Error`. While `error.message` may contain sensitive information that should not be exposed to users, `message` is safe. @@ -121,7 +121,7 @@ Because of this, dynamic environment variables can no longer be read during prer ## `form` and `data` have been removed from `use:enhance` callbacks -If you provide a callback to [`use:enhance`](/docs/form-actions#progressive-enhancement-use-enhance), it will be called with an object containing various useful properties. +If you provide a callback to [`use:enhance`](form-actions#progressive-enhancement-use-enhance), it will be called with an object containing various useful properties. In SvelteKit 1, those properties included `form` and `data`. These were deprecated some time ago in favour of `formElement` and `formData`, and have been removed altogether in SvelteKit 2. diff --git a/apps/svelte.dev/content/docs/kit/60-appendix/40-migrating.md b/apps/svelte.dev/content/docs/kit/60-appendix/40-migrating.md index ec55a195da..885828330d 100644 --- a/apps/svelte.dev/content/docs/kit/60-appendix/40-migrating.md +++ b/apps/svelte.dev/content/docs/kit/60-appendix/40-migrating.md @@ -53,7 +53,7 @@ When using `adapter-node` the equivalent is a [custom server](adapter-node#custo ### src/service-worker.js -Most imports from `@sapper/service-worker` have equivalents in [`$service-worker`](modules#$service-worker): +Most imports from `@sapper/service-worker` have equivalents in [`$service-worker`]($service-worker): - `files` is unchanged - `routes` has been removed @@ -68,7 +68,7 @@ Remove `%sapper.base%`, `%sapper.scripts%` and `%sapper.styles%`. Replace `%sapp ### src/node_modules -A common pattern in Sapper apps is to put your internal library in a directory inside `src/node_modules`. This doesn't work with Vite, so we use [`src/lib`](modules#$lib) instead. +A common pattern in Sapper apps is to put your internal library in a directory inside `src/node_modules`. This doesn't work with Vite, so we use [`src/lib`]($lib) instead. ## Pages and layouts @@ -85,11 +85,11 @@ Your custom error page component should be renamed from `_error.svelte` to `+err ### Imports -The `goto`, `prefetch` and `prefetchRoutes` imports from `@sapper/app` should be replaced with `goto`, `preloadData` and `preloadCode` imports respectively from [`$app/navigation`](modules#$app-navigation). +The `goto`, `prefetch` and `prefetchRoutes` imports from `@sapper/app` should be replaced with `goto`, `preloadData` and `preloadCode` imports respectively from [`$app/navigation`]($app-navigation). The `stores` import from `@sapper/app` should be replaced — see the [Stores](migrating#pages-and-layouts-stores) section below. -Any files you previously imported from directories in `src/node_modules` will need to be replaced with [`$lib`](modules#$lib) imports. +Any files you previously imported from directories in `src/node_modules` will need to be replaced with [`$lib`]($lib) imports. ### Preload @@ -115,7 +115,7 @@ const { preloading, page, session } = stores(); The `page` store still exists; `preloading` has been replaced with a `navigating` store that contains `from` and `to` properties. `page` now has `url` and `params` properties, but no `path` or `query`. -You access them differently in SvelteKit. `stores` is now `getStores`, but in most cases it is unnecessary since you can import `navigating`, and `page` directly from [`$app/stores`](modules#$app-stores). +You access them differently in SvelteKit. `stores` is now `getStores`, but in most cases it is unnecessary since you can import `navigating`, and `page` directly from [`$app/stores`]($app-stores). ### Routing diff --git a/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md b/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md index 1fd2b42104..eebb6debe9 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md @@ -550,7 +550,7 @@ publicPrefix?: string; </div> -A prefix that signals that an environment variable is safe to expose to client-side code. See [`$env/static/public`](/docs/kit/reference/$env-all#$env-static-public) and [`$env/dynamic/public`](/docs/kit/reference/$env-all#$env-dynamic-public). Note that Vite's [`envPrefix`](https://vitejs.dev/config/shared-options.html#envprefix) must be set separately if you are using Vite's environment variable handling - though use of that feature should generally be unnecessary. +A prefix that signals that an environment variable is safe to expose to client-side code. See [`$env/static/public`](https://kit.svelte.dev/docs/modules#$env-static-public) and [`$env/dynamic/public`](https://kit.svelte.dev/docs/modules#$env-dynamic-public). Note that Vite's [`envPrefix`](https://vitejs.dev/config/shared-options.html#envprefix) must be set separately if you are using Vite's environment variable handling - though use of that feature should generally be unnecessary. </div> </div> @@ -568,7 +568,7 @@ privatePrefix?: string; </div> -A prefix that signals that an environment variable is unsafe to expose to client-side code. Environment variables matching neither the public nor the private prefix will be discarded completely. See [`$env/static/private`](/docs/kit/reference/$env-all#$env-static-private) and [`$env/dynamic/private`](/docs/kit/reference/$env-all#$env-dynamic-private). +A prefix that signals that an environment variable is unsafe to expose to client-side code. Environment variables matching neither the public nor the private prefix will be discarded completely. See [`$env/static/private`](https://kit.svelte.dev/docs/modules#$env-static-private) and [`$env/dynamic/private`](https://kit.svelte.dev/docs/modules#$env-dynamic-private). </div> </div></div> @@ -916,7 +916,7 @@ base?: '' | `/${string}`; </div> -A root-relative path that must start, but not end with `/` (e.g. `/base-path`), unless it is the empty string. This specifies where your app is served from and allows the app to live on a non-root path. Note that you need to prepend all your root-relative links with the base value or they will point to the root of your domain, not your `base` (this is how the browser works). You can use [`base` from `$app/paths`](/docs/kit/reference/$app-paths#base) for that: `<a href="{base}/your-page">Link</a>`. If you find yourself writing this often, it may make sense to extract this into a reusable component. +A root-relative path that must start, but not end with `/` (e.g. `/base-path`), unless it is the empty string. This specifies where your app is served from and allows the app to live on a non-root path. Note that you need to prepend all your root-relative links with the base value or they will point to the root of your domain, not your `base` (this is how the browser works). You can use [`base` from `$app/paths`](https://kit.svelte.dev/docs/modules#$app-paths-base) for that: `<a href="{base}/your-page">Link</a>`. If you find yourself writing this often, it may make sense to extract this into a reusable component. </div> </div> @@ -1232,7 +1232,7 @@ Not all navigations will result in an error though, for example if the JavaScrip </script> ``` -If you set `pollInterval` to a non-zero value, SvelteKit will poll for new versions in the background and set the value of the [`updated`](/docs/kit/reference/$app-stores#updated) store to `true` when it detects one. +If you set `pollInterval` to a non-zero value, SvelteKit will poll for new versions in the background and set the value of the [`updated`](https://kit.svelte.dev/docs/modules#$app-stores-updated) store to `true` when it detects one. <div class="ts-block-property-children"><div class="ts-block-property"> diff --git a/apps/svelte.dev/content/docs/kit/98-reference/20-$app-paths.md b/apps/svelte.dev/content/docs/kit/98-reference/20-$app-paths.md index 358e3696ba..ca3b091db8 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/20-$app-paths.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/20-$app-paths.md @@ -11,7 +11,7 @@ import { assets, base, resolveRoute } from '$app/paths'; ## assets -An absolute path that matches [`config.kit.paths.assets`](/docs/kit/reference/configuration#paths). +An absolute path that matches [`config.kit.paths.assets`](https://kit.svelte.dev/docs/configuration#paths). > If a value for `config.kit.paths.assets` is specified, it will be replaced with `'/_svelte_kit_assets'` during `vite dev` or `vite preview`, since the assets don't yet live at their eventual URL. @@ -31,7 +31,7 @@ let assets: ## base -A string that matches [`config.kit.paths.base`](/docs/kit/reference/configuration#paths). +A string that matches [`config.kit.paths.base`](https://kit.svelte.dev/docs/configuration#paths). Example usage: `<a href="{base}/your-page">Link</a>` diff --git a/apps/svelte.dev/content/docs/kit/98-reference/20-$app-stores.md b/apps/svelte.dev/content/docs/kit/98-reference/20-$app-stores.md index 935b92632a..aab4d54ad5 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/20-$app-stores.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/20-$app-stores.md @@ -67,7 +67,7 @@ const page: import('svelte/store').Readable< ## updated -A readable store whose initial value is `false`. If [`version.pollInterval`](/docs/kit/reference/configuration#version) is a non-zero value, SvelteKit will poll for new versions of the app and update the store value to `true` when it detects one. `updated.check()` will force an immediate check, regardless of polling. +A readable store whose initial value is `false`. If [`version.pollInterval`](https://kit.svelte.dev/docs/configuration#version) is a non-zero value, SvelteKit will poll for new versions of the app and update the store value to `true` when it detects one. `updated.check()` will force an immediate check, regardless of polling. On the server, this store can only be subscribed to during component initialization. In the browser, it can be subscribed to at any time. diff --git a/apps/svelte.dev/content/docs/kit/98-reference/25-$env-dynamic-private.md b/apps/svelte.dev/content/docs/kit/98-reference/25-$env-dynamic-private.md index 5e28ccb1fc..2a8ca76147 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/25-$env-dynamic-private.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/25-$env-dynamic-private.md @@ -2,7 +2,7 @@ title: $env/dynamic/private --- -This module provides access to runtime environment variables, as defined by the platform you're running on. For example if you're using [`adapter-node`](https://github.com/sveltejs/kit/tree/main/packages/adapter-node) (or running [`vite preview`](/docs/kit/reference/cli)), this is equivalent to `process.env`. This module only includes variables that _do not_ begin with [`config.kit.env.publicPrefix`](/docs/kit/reference/configuration#env) _and do_ start with [`config.kit.env.privatePrefix`](/docs/kit/reference/configuration#env) (if configured). +This module provides access to runtime environment variables, as defined by the platform you're running on. For example if you're using [`adapter-node`](https://github.com/sveltejs/kit/tree/main/packages/adapter-node) (or running [`vite preview`](https://kit.svelte.dev/docs/cli)), this is equivalent to `process.env`. This module only includes variables that _do not_ begin with [`config.kit.env.publicPrefix`](https://kit.svelte.dev/docs/configuration#env) _and do_ start with [`config.kit.env.privatePrefix`](https://kit.svelte.dev/docs/configuration#env) (if configured). This module cannot be imported into client-side code. diff --git a/apps/svelte.dev/content/docs/kit/98-reference/25-$env-dynamic-public.md b/apps/svelte.dev/content/docs/kit/98-reference/25-$env-dynamic-public.md index cd47676336..f506759a61 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/25-$env-dynamic-public.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/25-$env-dynamic-public.md @@ -2,7 +2,7 @@ title: $env/dynamic/public --- -Similar to [`$env/dynamic/private`](/docs/kit/reference/$env-all#$env-dynamic-private), but only includes variables that begin with [`config.kit.env.publicPrefix`](/docs/kit/reference/configuration#env) (which defaults to `PUBLIC_`), and can therefore safely be exposed to client-side code. +Similar to [`$env/dynamic/private`](https://kit.svelte.dev/docs/modules#$env-dynamic-private), but only includes variables that begin with [`config.kit.env.publicPrefix`](https://kit.svelte.dev/docs/configuration#env) (which defaults to `PUBLIC_`), and can therefore safely be exposed to client-side code. Note that public dynamic environment variables must all be sent from the server to the client, causing larger network requests — when possible, use `$env/static/public` instead. diff --git a/apps/svelte.dev/content/docs/kit/98-reference/25-$env-static-private.md b/apps/svelte.dev/content/docs/kit/98-reference/25-$env-static-private.md index 6a063e1115..a9054b7d3d 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/25-$env-static-private.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/25-$env-static-private.md @@ -2,9 +2,9 @@ title: $env/static/private --- -Environment variables [loaded by Vite](https://vitejs.dev/guide/env-and-mode.html#env-files) from `.env` files and `process.env`. Like [`$env/dynamic/private`](/docs/kit/reference/$env-all#$env-dynamic-private), this module cannot be imported into client-side code. This module only includes variables that _do not_ begin with [`config.kit.env.publicPrefix`](/docs/kit/reference/configuration#env) _and do_ start with [`config.kit.env.privatePrefix`](/docs/kit/reference/configuration#env) (if configured). +Environment variables [loaded by Vite](https://vitejs.dev/guide/env-and-mode.html#env-files) from `.env` files and `process.env`. Like [`$env/dynamic/private`](https://kit.svelte.dev/docs/modules#$env-dynamic-private), this module cannot be imported into client-side code. This module only includes variables that _do not_ begin with [`config.kit.env.publicPrefix`](https://kit.svelte.dev/docs/configuration#env) _and do_ start with [`config.kit.env.privatePrefix`](https://kit.svelte.dev/docs/configuration#env) (if configured). -_Unlike_ [`$env/dynamic/private`](/docs/kit/reference/$env-all#$env-dynamic-private), the values exported from this module are statically injected into your bundle at build time, enabling optimisations like dead code elimination. +_Unlike_ [`$env/dynamic/private`](https://kit.svelte.dev/docs/modules#$env-dynamic-private), the values exported from this module are statically injected into your bundle at build time, enabling optimisations like dead code elimination. ```ts import { API_KEY } from '$env/static/private'; diff --git a/apps/svelte.dev/content/docs/kit/98-reference/25-$env-static-public.md b/apps/svelte.dev/content/docs/kit/98-reference/25-$env-static-public.md index 0d974c5aa4..43b6d1acc2 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/25-$env-static-public.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/25-$env-static-public.md @@ -2,7 +2,7 @@ title: $env/static/public --- -Similar to [`$env/static/private`](/docs/kit/reference/$env-all#$env-static-private), except that it only includes environment variables that begin with [`config.kit.env.publicPrefix`](/docs/kit/reference/configuration#env) (which defaults to `PUBLIC_`), and can therefore safely be exposed to client-side code. +Similar to [`$env/static/private`](https://kit.svelte.dev/docs/modules#$env-static-private), except that it only includes environment variables that begin with [`config.kit.env.publicPrefix`](https://kit.svelte.dev/docs/configuration#env) (which defaults to `PUBLIC_`), and can therefore safely be exposed to client-side code. Values are replaced statically at build time. diff --git a/apps/svelte.dev/content/docs/kit/98-reference/26-$lib.md b/apps/svelte.dev/content/docs/kit/98-reference/26-$lib.md new file mode 100644 index 0000000000..2feb1a4402 --- /dev/null +++ b/apps/svelte.dev/content/docs/kit/98-reference/26-$lib.md @@ -0,0 +1,5 @@ +--- +title: $lib +--- + +TODO diff --git a/apps/svelte.dev/content/docs/kit/98-reference/27-$service-worker.md b/apps/svelte.dev/content/docs/kit/98-reference/27-$service-worker.md index d961fdf906..481fa309a2 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/27-$service-worker.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/27-$service-worker.md @@ -9,7 +9,7 @@ title: $service-worker import { base, build, files, prerendered, version } from '$service-worker'; ``` -This module is only available to [service workers](/docs/service-workers). +This module is only available to [service workers](https://kit.svelte.dev/docs/service-workers). ## base @@ -43,7 +43,7 @@ const build: string[]; ## files -An array of URL strings representing the files in your static directory, or whatever directory is specified by `config.kit.files.assets`. You can customize which files are included from `static` directory using [`config.kit.serviceWorker.files`](/docs/kit/reference/configuration) +An array of URL strings representing the files in your static directory, or whatever directory is specified by `config.kit.files.assets`. You can customize which files are included from `static` directory using [`config.kit.serviceWorker.files`](https://kit.svelte.dev/docs/configuration) <div class="ts-block"> @@ -72,7 +72,7 @@ const prerendered: string[]; ## version -See [`config.kit.version`](/docs/kit/reference/configuration#version). It's useful for generating unique cache names inside your service worker, so that a later deployment of your app can invalidate old caches. +See [`config.kit.version`](https://kit.svelte.dev/docs/configuration#version). It's useful for generating unique cache names inside your service worker, so that a later deployment of your app can invalidate old caches. <div class="ts-block"> diff --git a/apps/svelte.dev/content/docs/kit/98-reference/50-configuration.md b/apps/svelte.dev/content/docs/kit/98-reference/50-configuration.md index 54f59919ea..a5da3e4d3c 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/50-configuration.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/50-configuration.md @@ -387,7 +387,7 @@ publicPrefix?: string; </div> -A prefix that signals that an environment variable is safe to expose to client-side code. See [`$env/static/public`](/docs/kit/reference/$env-all#$env-static-public) and [`$env/dynamic/public`](/docs/kit/reference/$env-all#$env-dynamic-public). Note that Vite's [`envPrefix`](https://vitejs.dev/config/shared-options.html#envprefix) must be set separately if you are using Vite's environment variable handling - though use of that feature should generally be unnecessary. +A prefix that signals that an environment variable is safe to expose to client-side code. See [`$env/static/public`](https://kit.svelte.dev/docs/modules#$env-static-public) and [`$env/dynamic/public`](https://kit.svelte.dev/docs/modules#$env-dynamic-public). Note that Vite's [`envPrefix`](https://vitejs.dev/config/shared-options.html#envprefix) must be set separately if you are using Vite's environment variable handling - though use of that feature should generally be unnecessary. </div> </div> @@ -406,7 +406,7 @@ privatePrefix?: string; </div> -A prefix that signals that an environment variable is unsafe to expose to client-side code. Environment variables matching neither the public nor the private prefix will be discarded completely. See [`$env/static/private`](/docs/kit/reference/$env-all#$env-static-private) and [`$env/dynamic/private`](/docs/kit/reference/$env-all#$env-dynamic-private). +A prefix that signals that an environment variable is unsafe to expose to client-side code. Environment variables matching neither the public nor the private prefix will be discarded completely. See [`$env/static/private`](https://kit.svelte.dev/docs/modules#$env-static-private) and [`$env/dynamic/private`](https://kit.svelte.dev/docs/modules#$env-dynamic-private). </div> </div> @@ -764,7 +764,7 @@ base?: '' | `/${string}`; </div> -A root-relative path that must start, but not end with `/` (e.g. `/base-path`), unless it is the empty string. This specifies where your app is served from and allows the app to live on a non-root path. Note that you need to prepend all your root-relative links with the base value or they will point to the root of your domain, not your `base` (this is how the browser works). You can use [`base` from `$app/paths`](/docs/kit/reference/$app-paths#base) for that: `<a href="{base}/your-page">Link</a>`. If you find yourself writing this often, it may make sense to extract this into a reusable component. +A root-relative path that must start, but not end with `/` (e.g. `/base-path`), unless it is the empty string. This specifies where your app is served from and allows the app to live on a non-root path. Note that you need to prepend all your root-relative links with the base value or they will point to the root of your domain, not your `base` (this is how the browser works). You can use [`base` from `$app/paths`](https://kit.svelte.dev/docs/modules#$app-paths-base) for that: `<a href="{base}/your-page">Link</a>`. If you find yourself writing this often, it may make sense to extract this into a reusable component. </div> </div> @@ -1097,7 +1097,7 @@ Not all navigations will result in an error though, for example if the JavaScrip </script> ``` -If you set `pollInterval` to a non-zero value, SvelteKit will poll for new versions in the background and set the value of the [`updated`](/docs/kit/reference/$app-stores#updated) store to `true` when it detects one. +If you set `pollInterval` to a non-zero value, SvelteKit will poll for new versions in the background and set the value of the [`updated`](https://kit.svelte.dev/docs/modules#$app-stores-updated) store to `true` when it detects one. <div class="ts-block-property-children"> diff --git a/apps/svelte.dev/content/docs/kit/98-reference/54-types.md b/apps/svelte.dev/content/docs/kit/98-reference/54-types.md index 174e98eda8..353beca223 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/54-types.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/54-types.md @@ -142,11 +142,11 @@ Others are required for SvelteKit to work properly, and should also be left unto ## $lib -This is a simple alias to `src/lib`, or whatever directory is specified as [`config.kit.files.lib`](/docs/kit/reference/configuration#files). It allows you to access common components and utility modules without `../../../../` nonsense. +This is a simple alias to `src/lib`, or whatever directory is specified as [`config.kit.files.lib`](configuration#files). It allows you to access common components and utility modules without `../../../../` nonsense. ### $lib/server -A subdirectory of `$lib`. SvelteKit will prevent you from importing any modules in `$lib/server` into client-side code. See [server-only modules](/docs/server-only-modules). +A subdirectory of `$lib`. SvelteKit will prevent you from importing any modules in `$lib/server` into client-side code. See [server-only modules](server-only-modules). ## app.d.ts @@ -187,7 +187,7 @@ interface Locals {} ## PageData -Defines the common shape of the [$page.data store](/docs/kit/reference/$app-stores#page) - that is, the data that is shared between all pages. +Defines the common shape of the [$page.data store](https://kit.svelte.dev/docs/modules#$app-stores-page) - that is, the data that is shared between all pages. The `Load` and `ServerLoad` functions in `./$types` will be narrowed accordingly. Use optional properties for data that is only present on specific pages. Do not add an index signature (`[key: string]: any`). @@ -201,7 +201,7 @@ interface PageData {} ## PageState -The shape of the `$page.state` object, which can be manipulated using the [`pushState`](/docs/kit/reference/$app-navigation#pushstate) and [`replaceState`](/docs/kit/reference/$app-navigation#replacestate) functions from `$app/navigation`. +The shape of the `$page.state` object, which can be manipulated using the [`pushState`](https://kit.svelte.dev/docs/modules#$app-navigation-pushstate) and [`replaceState`](https://kit.svelte.dev/docs/modules#$app-navigation-replacestate) functions from `$app/navigation`. <div class="ts-block"> diff --git a/apps/svelte.dev/content/docs/svelte/01-introduction/01-overview.md b/apps/svelte.dev/content/docs/svelte/01-introduction/01-overview.md index a0901b9518..b1218232db 100644 --- a/apps/svelte.dev/content/docs/svelte/01-introduction/01-overview.md +++ b/apps/svelte.dev/content/docs/svelte/01-introduction/01-overview.md @@ -25,6 +25,6 @@ Svelte is a web UI framework that uses a compiler to turn declarative component ...into tightly optimized JavaScript that updates the document when state like count changes. Because the compiler can 'see' where count is referenced, the generated code is highly efficient, and because we're hijacking syntax like `$state(...)` and `=` instead of using cumbersome APIs, you can write less code. -Besides being fun to work with, Svelte offers a lot of features built-in, such as animations and transitions. Once you've written your first components you can reach for our batteries included metaframework [SvelteKit](/docs/kit) which provides you with an opinionated router, data loading and more. +Besides being fun to work with, Svelte offers a lot of features built-in, such as animations and transitions. Once you've written your first components you can reach for our batteries included metaframework [SvelteKit](../kit) which provides you with an opinionated router, data loading and more. If you're new to Svelte, visit the [interactive tutorial](/tutorial) before consulting this documentation. You can try Svelte online using the [REPL](/repl). Alternatively, if you'd like a more fully-featured environment, you can try Svelte on [StackBlitz](https://sveltekit.new). diff --git a/apps/svelte.dev/content/docs/svelte/01-introduction/03-reactivity-fundamentals.md b/apps/svelte.dev/content/docs/svelte/01-introduction/03-reactivity-fundamentals.md index e2f2f4309c..fd884d22dc 100644 --- a/apps/svelte.dev/content/docs/svelte/01-introduction/03-reactivity-fundamentals.md +++ b/apps/svelte.dev/content/docs/svelte/01-introduction/03-reactivity-fundamentals.md @@ -10,7 +10,7 @@ Svelte 5 uses _runes_, a powerful set of primitives for controlling reactivity i Runes are function-like symbols that provide instructions to the Svelte compiler. You don't need to import them from anywhere — when you use Svelte, they're part of the language. -The following sections introduce the most important runes for declare state, derived state and side effects at a high level. For more details refer to the later sections on [state](/docs/svelte/runes/state) and [side effects](/docs/svelte/runes/side-effects). +The following sections introduce the most important runes for declare state, derived state and side effects at a high level. For more details refer to the later sections on [state](state) and [side effects](side-effects). ## `$state` diff --git a/apps/svelte.dev/content/docs/svelte/02-template-syntax/01-component-fundamentals.md b/apps/svelte.dev/content/docs/svelte/02-template-syntax/01-component-fundamentals.md index fc81bb24bd..47c691a560 100644 --- a/apps/svelte.dev/content/docs/svelte/02-template-syntax/01-component-fundamentals.md +++ b/apps/svelte.dev/content/docs/svelte/02-template-syntax/01-component-fundamentals.md @@ -112,7 +112,7 @@ If you export a `const`, `class` or `function`, it is readonly from outside the </script> ``` -Readonly props can be accessed as properties on the element, tied to the component using [`bind:this` syntax](/docs/component-directives#bind-this). +Readonly props can be accessed as properties on the element, tied to the component using [`bind:this` syntax](bindings#bind-this). ### Reactive variables diff --git a/apps/svelte.dev/content/docs/svelte/02-template-syntax/06-transitions-and-animations.md b/apps/svelte.dev/content/docs/svelte/02-template-syntax/06-transitions-and-animations.md index 753c07e86a..a82e40928c 100644 --- a/apps/svelte.dev/content/docs/svelte/02-template-syntax/06-transitions-and-animations.md +++ b/apps/svelte.dev/content/docs/svelte/02-template-syntax/06-transitions-and-animations.md @@ -79,7 +79,7 @@ Transitions are local by default. Local transitions only play when the block the {/if} ``` -> By default intro transitions will not play on first render. You can modify this behaviour by setting `intro: true` when you [create a component](/docs/runtime/imperative-component-api) and marking the transition as `global`. +> By default intro transitions will not play on first render. You can modify this behaviour by setting `intro: true` when you [create a component](imperative-component-api) and marking the transition as `global`. ## Transition parameters @@ -312,7 +312,7 @@ DOMRect { An animation is triggered when the contents of a [keyed each block](control-flow#each) are re-ordered. Animations do not run when an element is added or removed, only when the index of an existing data item within the each block changes. Animate directives must be on an element that is an _immediate_ child of a keyed each block. -Animations can be used with Svelte's [built-in animation functions](/docs/svelte/reference/svelte-animate) or [custom animation functions](#custom-animation-functions). +Animations can be used with Svelte's [built-in animation functions](svelte-animate) or [custom animation functions](#custom-animation-functions). ```svelte <!-- When `list` is reordered the animation will run--> diff --git a/apps/svelte.dev/content/docs/svelte/02-template-syntax/09-special-elements.md b/apps/svelte.dev/content/docs/svelte/02-template-syntax/09-special-elements.md index 86fad4fa18..2b41d55fe4 100644 --- a/apps/svelte.dev/content/docs/svelte/02-template-syntax/09-special-elements.md +++ b/apps/svelte.dev/content/docs/svelte/02-template-syntax/09-special-elements.md @@ -122,7 +122,7 @@ All except `scrollX` and `scrollY` are readonly. <svelte:document bind:prop={value} /> ``` -Similarly to `<svelte:window>`, this element allows you to add listeners to events on `document`, such as `visibilitychange`, which don't fire on `window`. It also lets you use [actions](/docs/element-directives#use-action) on `document`. +Similarly to `<svelte:window>`, this element allows you to add listeners to events on `document`, such as `visibilitychange`, which don't fire on `window`. It also lets you use [actions](actions) on `document`. As with `<svelte:window>`, this element may only appear the top level of your component and must never be inside a block or element. @@ -145,7 +145,7 @@ All are readonly. <svelte:body onevent={handler} /> ``` -Similarly to `<svelte:window>`, this element allows you to add listeners to events on `document.body`, such as `mouseenter` and `mouseleave`, which don't fire on `window`. It also lets you use [actions](/docs/element-directives#use-action) on the `<body>` element. +Similarly to `<svelte:window>`, this element allows you to add listeners to events on `document.body`, such as `mouseenter` and `mouseleave`, which don't fire on `window`. It also lets you use [actions](actions) on the `<body>` element. As with `<svelte:window>` and `<svelte:document>`, this element may only appear the top level of your component and must never be inside a block or element. @@ -176,14 +176,14 @@ As with `<svelte:window>`, `<svelte:document>` and `<svelte:body>`, this element <svelte:options option={value} /> ``` -The `<svelte:options>` element provides a place to specify per-component compiler options, which are detailed in the [compiler section](/docs/svelte-compiler#compile). The possible options are: +The `<svelte:options>` element provides a place to specify per-component compiler options, which are detailed in the [compiler section](svelte-compiler#compile). The possible options are: - `immutable={true}` — you never use mutable data, so the compiler can do simple referential equality checks to determine if values have changed - `immutable={false}` — the default. Svelte will be more conservative about whether or not mutable objects have changed - `accessors={true}` — adds getters and setters for the component's props - `accessors={false}` — the default - `namespace="..."` — the namespace where this component will be used, most commonly "svg"; use the "foreign" namespace to opt out of case-insensitive attribute names and HTML-specific warnings -- `customElement={...}` — the [options](/docs/custom-elements-api#component-options) to use when compiling this component as a custom element. If a string is passed, it is used as the `tag` option +- `customElement={...}` — the [options](custom-elements#component-options) to use when compiling this component as a custom element. If a string is passed, it is used as the `tag` option ```svelte <svelte:options customElement="my-custom-element" /> diff --git a/apps/svelte.dev/content/docs/svelte/02-template-syntax/10-data-fetching.md b/apps/svelte.dev/content/docs/svelte/02-template-syntax/10-data-fetching.md index 4116772f7b..ba424e1721 100644 --- a/apps/svelte.dev/content/docs/svelte/02-template-syntax/10-data-fetching.md +++ b/apps/svelte.dev/content/docs/svelte/02-template-syntax/10-data-fetching.md @@ -82,4 +82,4 @@ Similarly, if you only want to show the error state, you can omit the `then` blo ## SvelteKit loaders -Fetching inside your components is great for simple use cases, but it's prone to data loading waterfalls and makes code harder to work with because of the promise handling. SvelteKit solves this problem by providing a opinionated data loading story that is coupled to its router. Learn more about it [in the docs](/docs/kit). +Fetching inside your components is great for simple use cases, but it's prone to data loading waterfalls and makes code harder to work with because of the promise handling. SvelteKit solves this problem by providing a opinionated data loading story that is coupled to its router. Learn more about it [in the docs](../kit). diff --git a/apps/svelte.dev/content/docs/svelte/03-runes/02-side-effects.md b/apps/svelte.dev/content/docs/svelte/03-runes/02-side-effects.md index 4cef5228ca..3d425f8ee3 100644 --- a/apps/svelte.dev/content/docs/svelte/03-runes/02-side-effects.md +++ b/apps/svelte.dev/content/docs/svelte/03-runes/02-side-effects.md @@ -94,7 +94,7 @@ $effect(() => { }); ``` -An effect only reruns when the object it reads changes, not when a property inside it changes. (If you want to observe changes _inside_ an object at dev time, you can use [`$inspect`](/docs/svelte/misc/debugging#$inspect).) +An effect only reruns when the object it reads changes, not when a property inside it changes. (If you want to observe changes _inside_ an object at dev time, you can use [`$inspect`](debugging#$inspect).) ```svelte <script> @@ -252,7 +252,7 @@ If you need to use bindings, for whatever reason (for example when you want some </label> ``` -If you absolutely have to update `$state` within an effect and run into an infinite loop because you read and write to the same `$state`, use [untrack](functions#untrack). +If you absolutely have to update `$state` within an effect and run into an infinite loop because you read and write to the same `$state`, use [untrack](svelte#untrack). ## `$effect.pre` diff --git a/apps/svelte.dev/content/docs/svelte/04-runtime/01-stores.md b/apps/svelte.dev/content/docs/svelte/04-runtime/01-stores.md index 46174f8ac6..a6c3be06c3 100644 --- a/apps/svelte.dev/content/docs/svelte/04-runtime/01-stores.md +++ b/apps/svelte.dev/content/docs/svelte/04-runtime/01-stores.md @@ -6,7 +6,7 @@ title: Stores - how to write - TODO should the details for the store methods belong to the reference section? -A _store_ is an object that allows reactive access to a value via a simple _store contract_. The [`svelte/store` module](/docs/svelte-store) contains minimal store implementations which fulfil this contract. +A _store_ is an object that allows reactive access to a value via a simple _store contract_. The [`svelte/store` module](../svelte-store) contains minimal store implementations which fulfil this contract. Any time you have a reference to a store, you can access its value inside a component by prefixing it with the `$` character. This causes Svelte to declare the prefixed variable, subscribe to the store at component initialisation and unsubscribe when appropriate. @@ -276,7 +276,7 @@ const value = get(store); store = { subscribe: (subscription: (value: any) => void) => (() => void), set?: (value: any) => void } ``` -You can create your own stores without relying on [`svelte/store`](/docs/svelte-store), by implementing the _store contract_: +You can create your own stores without relying on [`svelte/store`](../svelte-store), by implementing the _store contract_: 1. A store must contain a `.subscribe` method, which must accept as its argument a subscription function. This subscription function must be immediately and synchronously called with the store's current value upon calling `.subscribe`. All of a store's active subscription functions must later be synchronously called whenever the store's value changes. 2. The `.subscribe` method must return an unsubscribe function. Calling an unsubscribe function must stop its subscription, and its corresponding subscription function must not be called again by the store. diff --git a/apps/svelte.dev/content/docs/svelte/05-misc/04-custom-elements.md b/apps/svelte.dev/content/docs/svelte/05-misc/04-custom-elements.md index 5cb3bbfbb1..99e04a3bae 100644 --- a/apps/svelte.dev/content/docs/svelte/05-misc/04-custom-elements.md +++ b/apps/svelte.dev/content/docs/svelte/05-misc/04-custom-elements.md @@ -4,7 +4,7 @@ title: Custom elements - [basically what we have today](https://svelte.dev/docs/custom-elements-api) -Svelte components can also be compiled to custom elements (aka web components) using the `customElement: true` compiler option. You should specify a tag name for the component using the `<svelte:options>` [element](/docs/special-elements#svelte-options). +Svelte components can also be compiled to custom elements (aka web components) using the `customElement: true` compiler option. You should specify a tag name for the component using the `<svelte:options>` [element](special-elements#svelte-options). ```svelte <svelte:options customElement="my-element" /> @@ -36,7 +36,7 @@ document.body.innerHTML = ` `; ``` -Any [props](/docs/svelte/template-syntax/basic-markup#attributes-and-props) are exposed as properties of the DOM element (as well as being readable/writable as attributes, where possible). +Any [props](basic-markup#attributes-and-props) are exposed as properties of the DOM element (as well as being readable/writable as attributes, where possible). ```js // @noErrors diff --git a/apps/svelte.dev/content/docs/svelte/05-misc/06-v4-migration-guide.md b/apps/svelte.dev/content/docs/svelte/05-misc/06-v4-migration-guide.md new file mode 100644 index 0000000000..e4b6210c4f --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/05-misc/06-v4-migration-guide.md @@ -0,0 +1,5 @@ +--- +title: Svelte 4 migration guide +--- + +TODO copy over existing https://svelte.dev/docs/v4-migration-guide diff --git a/apps/svelte.dev/content/docs/svelte/05-misc/06-svelte-5-migration-guide.md b/apps/svelte.dev/content/docs/svelte/05-misc/07-v5-migration-guide.md similarity index 100% rename from apps/svelte.dev/content/docs/svelte/05-misc/06-svelte-5-migration-guide.md rename to apps/svelte.dev/content/docs/svelte/05-misc/07-v5-migration-guide.md diff --git a/apps/svelte.dev/content/docs/svelte/05-misc/99-faq.md b/apps/svelte.dev/content/docs/svelte/05-misc/99-faq.md new file mode 100644 index 0000000000..cdb6e38459 --- /dev/null +++ b/apps/svelte.dev/content/docs/svelte/05-misc/99-faq.md @@ -0,0 +1,5 @@ +--- +title: Frequently asked questions +--- + +TODO diff --git a/apps/svelte.dev/content/tutorial/02-advanced-svelte/05-bindings/05-bind-this/index.md b/apps/svelte.dev/content/tutorial/02-advanced-svelte/05-bindings/05-bind-this/index.md index 7a6a102bd8..401714fec3 100644 --- a/apps/svelte.dev/content/tutorial/02-advanced-svelte/05-bindings/05-bind-this/index.md +++ b/apps/svelte.dev/content/tutorial/02-advanced-svelte/05-bindings/05-bind-this/index.md @@ -2,7 +2,9 @@ title: This --- -In a [previous exercise](onmount), we learned how to use the `onMount` lifecycle function to paint to a canvas. +> TODO the next sentence is no longer true + +In a previous exercise, we learned how to use the `onMount` lifecycle function to paint to a canvas. But the example is buggy — it's using `document.querySelector('canvas')`, which will always return the first `<canvas>` found on the page, which might not be the one belonging to our component. diff --git a/apps/svelte.dev/content/tutorial/02-advanced-svelte/08-context/01-context-api/index.md b/apps/svelte.dev/content/tutorial/02-advanced-svelte/08-context/01-context-api/index.md index a8cb4c000e..fb32e71416 100644 --- a/apps/svelte.dev/content/tutorial/02-advanced-svelte/08-context/01-context-api/index.md +++ b/apps/svelte.dev/content/tutorial/02-advanced-svelte/08-context/01-context-api/index.md @@ -65,7 +65,7 @@ So far, so... boring. Let's add some randomness to the grid: </div> ``` -Like [lifecycle functions](/tutorial/onmount), `setContext` and `getContext` must be called during component initialisation. (The context key (`'canvas'` in this case) can be anything you like, including non-strings, which is useful for controlling who can access the context.) +Like lifecycle functions such as `onMount`, `setContext` and `getContext` must be called during component initialisation. (The context key (`'canvas'` in this case) can be anything you like, including non-strings, which is useful for controlling who can access the context.) Your context object can include anything, including stores. This allows you to pass values that change over time to child components: diff --git a/apps/svelte.dev/content/tutorial/03-sveltekit/08-stores/01-page-store/index.md b/apps/svelte.dev/content/tutorial/03-sveltekit/08-stores/01-page-store/index.md index 582c0ec682..1ab9016523 100644 --- a/apps/svelte.dev/content/tutorial/03-sveltekit/08-stores/01-page-store/index.md +++ b/apps/svelte.dev/content/tutorial/03-sveltekit/08-stores/01-page-store/index.md @@ -2,7 +2,9 @@ title: page --- -As we learned [earlier](writable-stores), Svelte stores are a place to put data that doesn't belong to an individual component. +> TODO link to stores exercise + +As we learned earlier, Svelte stores are a place to put data that doesn't belong to an individual component. SvelteKit makes three readonly stores available via the `$app/stores` module — `page`, `navigating` and `updated`. The one you'll use most often is [`page`](https://kit.svelte.dev/docs/types#public-types-page), which provides information about the current page: diff --git a/apps/svelte.dev/content/tutorial/04-advanced-sveltekit/05-advanced-loading/04-invalidation/index.md b/apps/svelte.dev/content/tutorial/04-advanced-sveltekit/05-advanced-loading/04-invalidation/index.md index bf1257a466..1cd1051705 100644 --- a/apps/svelte.dev/content/tutorial/04-advanced-sveltekit/05-advanced-loading/04-invalidation/index.md +++ b/apps/svelte.dev/content/tutorial/04-advanced-sveltekit/05-advanced-loading/04-invalidation/index.md @@ -7,7 +7,7 @@ When the user navigates from one page to another, SvelteKit calls your `load` fu In this example, navigating between timezones causes the `load` function in `src/routes/[...timezone]/+page.js` to re-run because `params.timezone` is invalid. But the `load` function in `src/routes/+layout.js` does _not_ re-run, because as far as SvelteKit is concerned it wasn't invalidated by the navigation. -We can fix that by manually invalidating it using the [`invalidate(...)`](https://kit.svelte.dev/docs/modules#$app-navigation-invalidate) function, which takes a URL and re-runs any `load` functions that depend on it. Because the `load` function in `src/routes/+layout.js` calls `fetch('/api/now')`, it depends on `/api/now`. +We can fix that by manually invalidating it using the [`invalidate(...)`](https://kit.svelte.dev/docs/$app-navigation#invalidate) function, which takes a URL and re-runs any `load` functions that depend on it. Because the `load` function in `src/routes/+layout.js` calls `fetch('/api/now')`, it depends on `/api/now`. In `src/routes/[...timezone]/+page.svelte`, add an `onMount` callback that calls `invalidate('/api/now')` once a second: diff --git a/apps/svelte.dev/scripts/sync-docs/index.ts b/apps/svelte.dev/scripts/sync-docs/index.ts index 1690c2e26f..aff8615e09 100644 --- a/apps/svelte.dev/scripts/sync-docs/index.ts +++ b/apps/svelte.dev/scripts/sync-docs/index.ts @@ -27,7 +27,7 @@ const packages: Package[] = [ name: 'svelte', local: `${REPOS}/svelte`, repo: 'sveltejs/svelte', - branch: 'main', + branch: 'docs-fixes', pkg: 'packages/svelte', docs: 'documentation/docs', process_modules: async (modules: Modules) => { @@ -84,29 +84,6 @@ const packages: Package[] = [ }); } - // TODO JSdoc points to kit.svelte.dev structure, rewrite those for now - for (const module of modules) { - replace_strings(module, (str) => - str - .replace(/(https:\/\/kit.svelte.dev)?\/docs\/([^#)]+)/g, (_, __, slug) => - slug === 'cli' || slug === 'modules' || slug === 'types' || slug === 'configuration' - ? `/docs/kit/reference/${slug}` - : _ - ) - .replace( - /\/docs\/kit\/reference\/modules#([^-]+)-([^-]+)-([^-)]+)/g, - (_, p1, p2, p3) => { - if (p1 === '$env') { - return `/docs/kit/reference/$env-all#${p1}-${p2}-${p3}`; - } else { - return `/docs/kit/reference/${p1 === 'sveltejs' ? '@sveltejs' : p1}-${p2}#${p3}`; - } - } - ) - .replace(/\/docs\/cli/g, '/docs/kit/reference/cli') - ); - } - const svelte_kit_module = modules.find((m) => m.name === '@sveltejs/kit'); const svelte_kit_types = svelte_kit_module!.types!; const config = svelte_kit_types.find((t) => t.name === 'Config')!; diff --git a/apps/svelte.dev/scripts/sync-docs/utils.ts b/apps/svelte.dev/scripts/sync-docs/utils.ts index 3162a7663b..3597db7e1b 100644 --- a/apps/svelte.dev/scripts/sync-docs/utils.ts +++ b/apps/svelte.dev/scripts/sync-docs/utils.ts @@ -65,5 +65,5 @@ export function migrate_meta_json(path: string) { * deployments and when developing locally */ export function strip_origin(str: string) { - return str.replace(/https:\/\/(kit\.)?svelte\.dev/g, ''); + return str.replaceAll('https://svelte.dev', ''); } diff --git a/apps/svelte.dev/src/hooks.server.js b/apps/svelte.dev/src/hooks.server.js index f897d286ae..6b194ed65e 100644 --- a/apps/svelte.dev/src/hooks.server.js +++ b/apps/svelte.dev/src/hooks.server.js @@ -1,25 +1,12 @@ import { redirect } from '@sveltejs/kit'; const mappings = new Map([ - ['/docs/getting-started', '/docs/svelte/getting-started'], ['/docs/svelte-components', '/docs/svelte/component-fundamentals'], - ['/docs/basic-markup', '/docs/svelte/basic-markup'], ['/docs/logic-blocks', '/docs/svelte/control-flow'], ['/docs/special-tags', '/docs/svelte/basic-markup'], // TODO: find a new home for some of these? ['/docs/element-directives', '/docs/svelte/basic-markup'], ['/docs/component-directives', '/docs/svelte/component-fundamentals'], - ['/docs/special-elements', '/docs/svelte/special-elements'], - ['/docs/svelte-action', '/docs/svelte/svelte-action'], - ['/docs/svelte-motion', '/docs/svelte/svelte-motion'], - ['/docs/svelte-store', '/docs/svelte/svelte-store'], - ['/docs/svelte-transition', '/docs/svelte/svelte-transition'], - ['/docs/svelte-animate', '/docs/svelte/svelte-animate'], - ['/docs/svelte-easing', '/docs/svelte/svelte-easing'], - ['/docs/faq', '/docs/svelte/faq'], - ['/docs/accessibility-warnings', '/docs/svelte/accessibility-warnings'], // TODO: this doesn't exist yet - ['/docs/typescript', '/docs/svelte/typescript'], - ['/docs/custom-elements-api', '/docs/svelte/custom-elements'], - ['/docs/typescript', '/docs/svelte/typescript'] + ['/docs/custom-elements-api', '/docs/svelte/custom-elements'] ]); /** @type {import('@sveltejs/kit').Handle} */ diff --git a/apps/svelte.dev/src/routes/docs/+page.svelte b/apps/svelte.dev/src/routes/docs/+page.svelte index ebead4145f..6f00a685e0 100644 --- a/apps/svelte.dev/src/routes/docs/+page.svelte +++ b/apps/svelte.dev/src/routes/docs/+page.svelte @@ -72,7 +72,7 @@ </p> </a> - <a href="/docs/svelte/migrating"> + <a href="/docs/svelte/v5-migration-guide"> <h2>I’m migrating an app from Svelte 4</h2> <p> If you’re already experienced with an older version of Svelte, the migration guide diff --git a/apps/svelte.dev/src/routes/docs/[...path]/+layout.server.ts b/apps/svelte.dev/src/routes/docs/[...path]/+layout.server.ts index 739c6e5d25..944232c32e 100644 --- a/apps/svelte.dev/src/routes/docs/[...path]/+layout.server.ts +++ b/apps/svelte.dev/src/routes/docs/[...path]/+layout.server.ts @@ -9,6 +9,11 @@ export async function load({ params }) { const document = docs.topics[`docs/${topic}`]; if (!document) { + // in many cases, https://svelte.dev/docs/foo is now https://svelte.dev/docs/svelte/foo + if (docs.pages[`docs/svelte/${params.path}`]) { + redirect(308, `/docs/svelte/${params.path}`); + } + error(404, 'Not found'); } diff --git a/apps/svelte.dev/svelte.config.js b/apps/svelte.dev/svelte.config.js index 596da2d75f..c9e821eb79 100644 --- a/apps/svelte.dev/svelte.config.js +++ b/apps/svelte.dev/svelte.config.js @@ -8,14 +8,6 @@ const config = { // See https://kit.svelte.dev/docs/adapters for more information about adapters. adapter: adapter(), prerender: { - handleHttpError(error) { - if (error.status === 500) { - throw new Error(error.message); - } - - // TODO fail the build - console.error(`404 ${error.path}`); - }, handleMissingId(warning) { if (warning.id.startsWith('H4sIA')) { // playground link — do nothing