```
# Service workers
服务工作者充当代理服务器，处理您应用内的网络请求。这使得您的应用能够在离线状态下运行，即使您不需要离线支持（或者由于您正在构建的应用类型而无法实际实现），通常也值得使用服务工作者通过预缓存您的 JS 和 CSS 来加速导航。
在 SvelteKit 中，如果您有一个`src/service-worker.js`文件（或`src/service-worker/index.js`），它将被打包并自动注册。如果您需要，可以更改[您的服务工作者位置](configuration#files)。
您可以根据需要禁用自动注册[，如果您需要使用自己的逻辑或另一个解决方案来注册服务工作者。默认注册看起来可能像这样：](configuration#serviceWorker)
```js
if ('serviceWorker' in navigator) {
addEventListener('load', function () {
navigator.serviceWorker.register('./path/to/service-worker.js');
});
}
```
##
服务工作者内部
在服务工作者内部，您可以访问 [`$service-worker` 模块]($service-worker)，该模块为您提供了所有静态资源、构建文件和预渲染页面的路径。您还提供了一个应用程序版本字符串，您可以使用它来创建唯一的缓存名称，以及部署的 `base` 路径。如果您的 Vite 配置指定了 `define`（用于全局变量替换），这将应用于服务工作者以及您的服务器/客户端构建。
以下示例会预先缓存构建的应用程序以及`static`中的任何文件，并且会按发生顺序缓存所有其他请求。这样，一旦访问过每个页面，就可以离线工作。
```js
// @errors: 2339
///
import { build, files, version } from '$service-worker';
// Create a unique cache name for this deployment
const CACHE = `cache-${version}`;
const ASSETS = [
...build, // the app itself
...files // everything in `static`
];
self.addEventListener('install', (event) => {
// Create a new cache and add all files to it
async function addFilesToCache() {
const cache = await caches.open(CACHE);
await cache.addAll(ASSETS);
}
event.waitUntil(addFilesToCache());
});
self.addEventListener('activate', (event) => {
// Remove previous cached data from disk
async function deleteOldCaches() {
for (const key of await caches.keys()) {
if (key !== CACHE) await caches.delete(key);
}
}
event.waitUntil(deleteOldCaches());
});
self.addEventListener('fetch', (event) => {
// ignore POST requests etc
if (event.request.method !== 'GET') return;
async function respond() {
const url = new URL(event.request.url);
const cache = await caches.open(CACHE);
// `build`/`files` can always be served from the cache
if (ASSETS.includes(url.pathname)) {
const response = await cache.match(url.pathname);
if (response) {
return response;
}
}
// for everything else, try the network first, but
// fall back to the cache if we're offline
try {
const response = await fetch(event.request);
// if we're offline, fetch can return a value that is not a Response
// instead of throwing - and we can't pass this non-Response to respondWith
if (!(response instanceof Response)) {
throw new Error('invalid response from fetch');
}
if (response.status === 200) {
cache.put(event.request, response.clone());
}
return response;
} catch (err) {
const response = await cache.match(event.request);
if (response) {
return response;
}
// if there's no cache, then just error out
// as there is nothing we can do to respond to this request
throw err;
}
}
event.respondWith(respond());
});
```
> \[注意\] 缓存时请小心！在某些情况下，过时的数据可能比离线时不可用的数据更糟。由于浏览器会在缓存太满时清空缓存，因此您还应注意缓存大型资产，如视频文件。
##
开发期间
服务工作者在生产环境中被打包，但在开发期间不会。因此，只有支持在服务工作者中使用[模块](https://web.dev/es-modules-in-sw)的浏览器才能在开发时间使用它们。如果您手动注册服务工作者，您需要在开发时传递`{ type: 'module' }`选项：
```js
import { dev } from '$app/environment';
navigator.serviceWorker.register('/service-worker.js', {
type: dev ? 'module' : 'classic'
});
```
> \[!注意\] `build` 和 `prerendered` 在开发期间为空数组
##
类型安全
设置服务工作者适当类型需要一些手动设置。在您的 `service-worker.js` 文件中，将以下内容添加到文件顶部：
```original-js
///
///
///
///
const sw = /** @type {ServiceWorkerGlobalScope} */ (/** @type {unknown} */ (self));
```
```generated-ts
///
///
///
///
const sw = self as unknown as ServiceWorkerGlobalScope;
```
此操作禁用了对 DOM 类型定义的访问，例如`HTMLElement`，这些在服务工作者内部不可用，并实例化了正确的全局变量。将`self`重新赋值为`sw`允许你在过程中进行类型转换（有几种方法可以做到这一点，但这是最简单的一种，不需要额外的文件）。在文件的其他部分使用`sw`代替`self`。对 SvelteKit 类型的引用确保了`$service-worker`导入有正确的类型定义。如果你导入`$env/static/public`，你必须使用`// @ts-ignore`忽略导入或添加 `///
` 到引用类型。
##
其他解决方案
SvelteKit 的服务工作者实现旨在易于使用，可能是大多数用户的良好解决方案。然而，在 SvelteKit 之外，许多 PWA 应用程序利用了[Workbox](https://web.dev/learn/pwa/workbox)库。如果您习惯使用 Workbox，您可能更喜欢[Vite PWA 插件](https://vite-pwa-org.netlify.app/frameworks/sveltekit.html)。
##
参考文献
关于服务工作者更一般的信息，我们推荐[MDN 网络文档](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers)。
# Server-only modules
像一位好朋友一样，SvelteKit 保护你的秘密。当你在同一个仓库中编写后端和前端时，很容易不小心将敏感数据导入到前端代码中（例如包含 API 密钥的环境变量）。SvelteKit 提供了一种完全防止这种情况的方法：仅服务器模块。
##
私有环境变量
The [`$env/static/private`]($env-static-private) 和 [`$env/dynamic/private`]($env-dynamic-private) 模块只能导入到仅在服务器上运行的模块中，例如 [`hooks.server.js`](hooks#Server-hooks) 或 [`+page.server.js`](routing#page-page.server.js)。
##
服务器专用工具
该 [`$app/server`]($app-server) 模块，其中包含一个用于从文件系统中读取资源的 [`read`]($app-server#read) 函数，同样只能由在服务器上运行的代码导入。
##
您的模块
您可以通过两种方式将您的模块设置为仅服务器端：
* 添加 `.server` 到文件名中，例如 `secrets.server.js`
* 将它们放置在`$lib/server`中，例如`$lib/server/secrets.js`
##
如何工作
任何时间当你有面向公众的代码导入仅服务器端代码（无论是直接还是间接）...
```js
// @errors: 7005
/// file: $lib/server/secrets.js
export const atlantisCoordinates = [/* redacted */];
```
```js
// @errors: 2307 7006 7005
/// file: src/routes/utils.js
export { atlantisCoordinates } from '$lib/server/secrets.js';
export const add = (a, b) => a + b;
```
```html
/// file: src/routes/+page.svelte
```
...SvelteKit 将报错：
```
Cannot import $lib/server/secrets.js into public-facing code:
- src/routes/+page.svelte
- src/routes/utils.js
- $lib/server/secrets.js
```
尽管面向公众的代码 — `src/routes/+page.svelte` — 只使用了 `add` 导出，而没有使用秘密的 `atlantisCoordinates` 导出，但秘密代码可能会出现在浏览器下载的 JavaScript 中，因此导入链被认为是不可信的。
此功能也支持动态导入，包括像``await import(`./${foo}.js`)``这样的插值导入，但有一个小限制：在开发过程中，如果公共代码和仅服务器模块之间存在两个或更多动态导入，则在首次加载代码时，将无法检测到非法导入。
> \[!注意\] 单元测试框架如 Vitest 不区分服务器端代码和面向公众的代码。因此，当运行测试时，非法导入检测被禁用，由`process.env.TEST === 'true'`确定。
##
进一步阅读
* [
教程：环境变量](/tutorial/kit/env-static-private)
# Snapshots
临时 DOM 状态——如侧边栏的滚动位置、`
`元素的内容等——在您从一个页面导航到另一个页面时会被丢弃。
例如，如果用户填写了表单但在提交前离开并返回，或者如果用户刷新了页面，他们填写的值将会丢失。在需要保留输入的情况下，您可以对 DOM 状态进行*快照*，这样在用户返回时可以恢复。
为此，从`snapshot`对象中导出具有`capture`和`restore`方法的`+page.svelte`或`+layout.svelte`：
```svelte
```
当你离开此页面时，页面更新之前立即调用 `捕获` 函数，返回的值与浏览器历史记录栈中的当前条目相关联。如果你返回，页面更新后立即使用存储的值调用 `恢复` 函数。
数据必须可序列化为 JSON，以便持久化到`sessionStorage`。这允许在页面重新加载或用户从不同网站返回时恢复状态。
> \[!注意\] 避免从 `capture` 返回非常大的对象 — 一旦捕获，对象将在会话期间保留在内存中，在极端情况下可能太大而无法持久化到 `sessionStorage`。
# Shallow routing
当你浏览 SvelteKit 应用时，你会创建历史记录条目。点击后退和前进按钮会遍历此条目列表，重新运行任何 `加载` 函数，并在必要时替换页面组件。
有时，在不导航的情况下创建历史记录条目很有用。*无需*导航。例如，您可能希望显示一个用户可以通过导航返回来关闭的模态对话框。这在移动设备上尤其有价值，因为在移动设备上，滑动手势通常比直接与 UI 交互更自然。在这些情况下，一个与历史记录条目*不相关*的模态可能会引起用户的挫败感，因为用户可能会尝试向后滑动以关闭它，却发现自己在错误的页面上。
SvelteKit 通过`pushState`和`replaceState`函数实现这一点，这些函数允许您在不进行导航的情况下将状态与历史记录条目关联。例如，要实现由历史记录驱动的模态：
```svelte
{#if page.state.showModal}
history.back()} />
{/if}
```
模态窗口可以通过返回操作（取消设置 `page.state.showModal`）或通过与之交互以触发 `close` 回调的方式来关闭，这将程序化地返回上一页。
## API
第一个参数是相对于当前 URL 的 URL，要保持在当前 URL，请使用`''`。
第二个参数是新的页面状态，可以通过[页面对象]($app-state#page)作为`page.state`访问。您可以通过声明一个[`App.PageState`](types#PageState)接口（通常在`src/app.d.ts`中）来使页面状态类型安全。
为设置页面状态而不创建新的历史记录条目，请使用`replaceState`代替`pushState`。
> \[!旧版\] 从 `$app/state` 添加了 `page.state` 到 SvelteKit 2.12。如果您使用的是更早的版本或使用 Svelte 4，请使用从 `$app/stores` 的 `$page.state` 代替。
##
加载数据以供路线使用
当进行浅层路由时，您可能希望在当前页面内渲染另一个 `+page.svelte`。例如，点击照片缩略图可以弹出详细视图，而无需导航到照片页面。
为此工作，您需要加载 `+page.svelte` 所期望的数据。一种方便的方法是在一个 `` 元素的 `click` 处理器中使用 [`preloadData`]($app-navigation#preloadData)。如果该元素（或其父元素）使用了 [`data-sveltekit-preload-data`](link-options#data-sveltekit-preload-data)，则数据已经被请求，并且 `preloadData` 将重用该请求。
```svelte
{#each data.thumbnails as thumbnail}
{
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
) return;
// prevent navigation
e.preventDefault();
const { href } = e.currentTarget;
// run `load` functions (or rather, get the result of the `load` functions
// that are already running because of `data-sveltekit-preload-data`)
const result = await preloadData(href);
if (result.type === 'loaded' && result.status === 200) {
pushState(href, { selected: result.data });
} else {
// something bad happened! try navigating
goto(href);
}
}}
>
{/each}
{#if page.state.selected}
history.back()}>
{/if}
```
##
注意事项
在服务器端渲染期间，`page.state`始终是一个空对象。对于用户首次访问的页面也是如此——如果用户刷新页面（或从另一个文档返回），状态将*不会*应用，直到他们进行导航。
浅层路由是一个需要 JavaScript 才能工作的功能。使用时请谨慎，并尝试考虑在 JavaScript 不可用时的合理回退行为。
# Packaging
您可以使用 SvelteKit 构建应用程序以及组件库，使用`@sveltejs/package`包（`npx sv create`有一个选项为您设置此配置）。
当你创建一个应用程序时，`src/routes`的内容是面向公众的部分；[`src/lib`]($lib)包含你的应用程序的内部库。
组件库的结构与 SvelteKit 应用完全相同，只是`src/lib`是面向公众的部分，而你的根`package.json`用于发布包。`src/routes`可能是一个伴随库的文档或演示网站，或者它可能只是你在开发过程中使用的沙盒。
运行来自 `@sveltejs/package` 的 `svelte-package` 命令将 `src/lib` 的内容生成一个包含以下内容的 `dist` 目录（可以 [配置](#Options)）：
* 所有位于 `src/lib` 的文件都将被预处理，Svelte 组件将被预编译，TypeScript 文件将被转换为 JavaScript。
* 类型定义（`d.ts` 文件）是为 Svelte、JavaScript 和 TypeScript 文件生成的。您需要安装 `typescript >= 4.0.0` 才能使用此功能。类型定义放置在其实现旁边，手写的 `d.ts` 文件直接复制。您可以[禁用生成](#Options)，但我们强烈建议不要这样做——使用您库的人可能会使用 TypeScript，他们需要这些类型定义文件。
> \[!注意\] `@sveltejs/package` 版本 1 生成了一个 `package.json`。现在不再是这样，它将现在使用您项目中的 `package.json` 并验证其正确性。如果您仍在使用版本 1，请参阅 [此 PR](https://github.com/sveltejs/kit/pull/8922) 了解迁移说明。
##
包.json 结构
由于你现在正在为公众构建一个库，你的`package.json`的内容将变得更加重要。通过它，你可以配置你的包的入口点，哪些文件发布到 npm，以及你的库有哪些依赖。让我们逐一查看最重要的字段。
###
姓名
这是您包的名称。它将可以使用该名称供其他人安装，并在 `https://npmjs.com/package/` 上可见。
`{ "name": "你的库" }`
了解更多信息 [这里](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#name)。
###
授权
每个软件包都应该有一个许可字段，这样人们就知道如何使用它。一个非常流行的许可，它在分发和重用方面非常宽松，不提供任何保证，是`MIT`。
`{ "license": "MIT" }`
阅读更多关于它的信息 [这里](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#license)。请注意，您还应在您的包中包含一个 `LICENSE` 文件。
###
文件
这告诉 npm 它将打包哪些文件并上传到 npm。它应该包含您的输出文件夹（默认为`dist`）。您的`package.json`、`README`和`LICENSE`文件始终会被包含，因此您不需要指定它们。
`{ "files": ["dist"] }`
要排除不必要的文件（例如单元测试或仅从 `src/routes` 等导入的模块等），可以将它们添加到 `.npmignore` 文件中。这将导致生成的包更小，安装速度更快。
了解更多信息 [这里](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#files)。
###
出口
The `"exports"` 字段包含包的入口点。如果您通过 `npx sv create` 创建一个新的库项目，它被设置为单个导出，即包的根目录：
```json
{
"exports": {
".": {
"types": "./dist/index.d.ts",
"svelte": "./dist/index.js"
}
}
}
```
这告诉打包器和工具，您的包只有一个入口点，即根目录，所有内容都应通过该入口点导入，如下所示：
```js
// @errors: 2307
import { Something } from 'your-library';
```
The `types` 和 `svelte` 键是 [导出条件](https://nodejs.org/api/packages.html#conditional-exports)。它们告诉工具在查找 `your-library` 导入时应该导入哪个文件。
* TypeScript 看到`类型`条件并查找类型定义文件。如果您不发布类型定义，请省略此条件。
* Svelte-aware 工具看到 `svelte` 条件并知道这是一个 Svelte 组件库。如果您发布了一个不导出任何 Svelte 组件且也可以在非 Svelte 项目中工作的库（例如 Svelte 存储库），则可以将此条件替换为 `default`。
> \[注意\] 之前版本的 `@sveltejs/package` 也添加了 `package.json` 导出。由于现在所有工具都可以处理未明确导出的 `package.json`，这不再是模板的一部分。
您可以根据喜好调整`exports`并提供更多入口点。例如，如果您想直接暴露一个`src/lib/Foo.svelte`组件，而不是使用一个重新导出组件的`src/lib/index.js`文件，您可以创建以下导出映射...
```json
{
"exports": {
"./Foo.svelte": {
"types": "./dist/Foo.svelte.d.ts",
"svelte": "./dist/Foo.svelte"
}
}
}
```
...并且您的库的消费者可以像这样导入组件：
```js
// @filename: ambient.d.ts
declare module 'your-library/Foo.svelte';
// @filename: index.js
// ---cut---
import Foo from 'your-library/Foo.svelte';
```
> \[!注意\] 如果您提供类型定义，进行此操作将需要额外小心。有关注意事项的更多信息，请参阅[此处](#TypeScript)
通常，导出映射的每个键是用户导入您的包中内容的路径，值是导入的文件路径或包含这些文件路径的导出条件映射。
阅读更多关于`exports`[这里](https://nodejs.org/docs/latest-v18.x/api/packages.html#package-entry-points)的信息。
### svelte
这是一个遗留字段，它使工具能够识别 Svelte 组件库。在使用`svelte`[导出条件](#Anatomy-of-a-package.json-exports)时不再需要，但为了与尚未了解导出条件的旧工具保持向后兼容，保留它是好的。它应指向您的根入口点。
```json
{
"svelte": "./dist/index.js"
}
```
###
副作用
代码`sideEffects`字段在`package.json`中，由打包器用来确定一个模块是否可能包含具有副作用代码。如果一个模块在导入时对其他脚本（模块外部）产生了可观察的变化，则认为该模块具有副作用。例如，副作用包括修改全局变量或内置 JavaScript 对象的原型。由于副作用可能会影响应用程序其他部分的行为，因此无论这些文件/模块的导出是否在应用程序中使用，这些文件/模块都将包含在最终的包中。避免在代码中产生副作用是一种最佳实践。
设置 `sideEffects` 字段在 `package.json` 中可以帮助打包器更积极地消除最终包中未使用的导出，这个过程称为摇树优化。这导致包更小、更高效。不同的打包器以不同的方式处理 `sideEffects`。虽然对于 Vite 不是必需的，但我们建议库声明所有 CSS 文件都有副作用，以便您的库与 [webpack](https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free) 兼容。这是新创建项目附带的自定义配置：
```json
/// file: package.json
{
"sideEffects": ["**/*.css"]
}
```
> 如果您的库中的脚本有副作用，请确保更新 `sideEffects` 字段。所有脚本在新创建的项目中默认标记为无副作用。如果一个有副作用的文件被错误地标记为无副作用，可能会导致功能损坏。
如果您的包包含具有副作用文件，您可以在数组中指定它们：
```json
/// file: package.json
{
"sideEffects": [
"**/*.css",
"./dist/sideEffectfulFile.js"
]
}
```
这只会将指定的文件视为具有副作用。
## TypeScript
您应该为您的库提供类型定义，即使您自己不使用 TypeScript，以便使用您库的人在使用时能够获得适当的智能感知。`@sveltejs/package`使生成类型的流程对您来说大部分是透明的。默认情况下，当打包您的库时，类型定义会自动为 JavaScript、TypeScript 和 Svelte 文件生成。您需要确保的是，在 [exports](#Anatomy-of-a-package.json-exports) 映射中，`types` 条件指向正确的文件。通过 `npx sv create` 初始化库项目时，这会自动设置根导出。
如果您有除了根导出之外的内容——例如提供`your-library/foo`导入——您需要提供类型定义时格外小心。不幸的是，TypeScript 默认情况下将不会解析类似于 `{ "./foo": { "types": "./dist/foo.d.ts", ... }}` 的导出的`类型`条件。相反，它将在您的库根目录中搜索`foo.d.ts`（即`your-library/foo.d.ts`而不是`your-library/dist/foo.d.ts`）。为了解决这个问题，您有两个选择：
第一种选项是要求使用您库的人将 `moduleResolution` 选项设置在他们的 `tsconfig.json`（或 `jsconfig.json`）中为 `bundler`（自 TypeScript 5 起可用，未来最佳和推荐选项），`node16` 或 `nodenext`。这将使 TypeScript 真正查看导出映射并正确解析类型。
第二种选项是（滥用）TypeScript 中的`typesVersions`功能来连接类型。这是 TypeScript 在`package.json`中使用的字段，用于根据 TypeScript 版本检查不同的类型定义，并且还包含路径映射功能。我们利用这个路径映射功能来获取我们想要的内容。对于上面提到的`foo`导出，相应的`typesVersions`看起来像这样：
```json
{
"exports": {
"./foo": {
"types": "./dist/foo.d.ts",
"svelte": "./dist/foo.js"
}
},
"typesVersions": {
">4.0": {
"foo": ["./dist/foo.d.ts"]
}
}
}
```
`>4.0` 告诉 TypeScript 检查内部映射，如果使用的 TypeScript 版本大于 4（实际上始终应该是这样）。内部映射告诉 TypeScript，`your-library/foo` 的类型定义位于 `./dist/foo.d.ts` 中，这本质上复制了 `exports` 条件。您还可以使用 `*` 作为通配符，一次提供多个类型定义，而不必重复。请注意，如果您选择使用 `typesVersions`，则必须通过它声明所有类型导入，包括根导入（定义为 `"index.d.ts": [...]`）。
您可以在[这里](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html#version-selection-with-typesversions)了解更多关于该功能的信息。
##
最佳实践
您应避免在您的包中使用 SvelteKit 特定的模块，如`$app/environment`，除非您打算仅让其他 SvelteKit 项目使用它们。例如，您可以使用 `import { BROWSER } from 'esm-env'` 而不是 `import { browser } from '$app/environment'` （[查看 esm-env 文档](https://github.com/benmccann/esm-env)）。您还可以选择将当前 URL 或导航操作作为属性传递，而不是直接依赖`$app/state`、`$app/navigation`等，以这种方式编写您的应用程序将使设置测试工具、UI 演示等变得更加容易。
确保通过`svelte.config.js`（而不是`vite.config.js`或`tsconfig.json`）添加[别名](configuration#alias)，以便它们能被`svelte-package`处理。
您应该仔细考虑您对包所做的更改是错误修复、新功能还是破坏性更改，并相应地更新包版本。请注意，如果您从现有库中删除了任何路径从 `exports` 或其内部的任何 `export` 条件，这应被视为破坏性更改。
```json
{
"exports": {
".": {
"types": "./dist/index.d.ts",
// changing `svelte` to `default` is a breaking change:
--- "svelte": "./dist/index.js"---
+++ "default": "./dist/index.js"+++
},
// removing this is a breaking change:
--- "./foo": {
"types": "./dist/foo.d.ts",
"svelte": "./dist/foo.js",
"default": "./dist/foo.js"
},---
// adding this is ok:
+++ "./bar": {
"types": "./dist/bar.d.ts",
"svelte": "./dist/bar.js",
"default": "./dist/bar.js"
}+++
}
}
```
##
源映射
您可以通过在您的 `tsconfig.json` 中设置 `"declarationMap": true` 来创建所谓的声明映射（`d.ts.map` 文件）。这将允许编辑器如 VS Code 在使用如 *转到定义* 等功能时访问原始的 `.ts` 或 `.svelte` 文件。这意味着您还需要以使声明文件中的相对路径指向磁盘上的文件的方式，将源文件与 dist 文件夹一起发布。假设您像 Svelte 的 CLI 建议的那样，将所有库代码放在 `src/lib` 中，那么只需在您的 `package.json` 中将 `src/lib` 添加到 `files` 即可：
```json
{
"files": [
"dist",
"!dist/**/*.test.*",
"!dist/**/*.spec.*",
+++"src/lib",
"!src/lib/**/*.test.*",
"!src/lib/**/*.spec.*"+++
]
}
```
##
选项
`سلت-پکج` 接受以下选项：
* `-w`/`--watch` — 监视 `src/lib` 目录中的文件变化并重新构建软件包
* `-i`/`--input` — 包含所有文件输入目录。默认为 `src/lib`
* `-o`/`--output` — 存储处理后的文件的输出目录。您的 `package.json` 的 `exports` 应指向该目录内的文件，并且 `files` 数组应包含该文件夹。默认为 `dist`
* `-t`/`--types` — 是否创建类型定义（`d.ts` 文件）。我们强烈建议这样做，因为它有助于提升生态系统库的质量。默认为 `true`
* `--tsconfig` - tsconfig 或 jsconfig 的路径。当未提供时，在工作区路径中搜索下一个 tsconfig/jsconfig。
##
发布
发布生成的包：
`npm 发布`
##
注意事项
所有相关文件导入必须完全指定，遵循 Node 的 ESM 算法。这意味着对于像`src/lib/something/index.js`这样的文件，你必须包含带有扩展名的文件名：
```js
// @errors: 2307
import { something } from './something+++/index.js+++';
```
如果您正在使用 TypeScript，则需要以相同的方式导入 `.ts` 文件，但使用 `.js` 文件扩展名，*而不是* `.ts` 文件扩展名。（这是 TypeScript 的设计决策，我们无法控制。）在您的 `tsconfig.json` 或 `jsconfig.json` 中设置 `"moduleResolution": "NodeNext"` 将有助于您完成此操作。
所有文件（除了预处理的 Svelte 文件和转换为 JavaScript 的 TypeScript 文件）都按原样复制。
# Auth
认证指的是身份验证和授权，这是构建 Web 应用程序时的常见需求。身份验证意味着根据用户提供的凭据验证用户是否是他们所说的那个人。授权意味着确定他们被允许执行哪些操作。
##
会话与令牌
在用户提供了他们的凭据，如用户名和密码之后，我们希望允许他们无需再次提供凭据即可使用应用程序。用户通常在后续请求中使用会话标识符或签名令牌，如 JSON Web Token（JWT）进行身份验证。
会话 ID 通常存储在数据库中。它们可以立即撤销，但需要在每个请求上进行数据库查询。
与 JWT 通常不与数据存储进行校验相比，这意味着它们不能立即被撤销。这种方法的优势是提高了延迟并减少了您数据存储的负载。
##
集成点
认证[cookies](@sveltejs-kit#Cookies)可以在[服务器钩子](hooks#Server-hooks)内部进行检查。如果找到与提供的凭据匹配的用户，则可以将用户信息存储在[`locals`](hooks#Server-hooks-locals)中。
##
指南
[Lucia](https://lucia-auth.com/) 是基于会话的 Web 应用程序身份验证的良好参考。它包含在 SvelteKit 和其他 JS 项目中实现基于会话的身份验证的示例代码片段和项目。您可以在创建新项目时使用 `npx sv create` 将遵循 Lucia 指引的代码添加到您的项目中，或者在使用现有项目时使用 `npx sv add lucia`。
一个认证系统与 Web 框架紧密耦合，因为大部分代码都用于验证用户输入、处理错误并将用户导向适当的下一页。因此，许多通用的 JS 认证库都包含一个或多个 Web 框架。正因为如此，许多用户可能会更倾向于遵循 SvelteKit 特定的指南，例如在[Lucia](https://lucia-auth.com/)中找到的示例，而不是在他们的项目中包含多个 Web 框架。
# Performance
开箱即用，SvelteKit 会做很多工作来确保您的应用程序尽可能高效：
* 代码拆分，以便只加载当前页面所需的代码
* 资产预加载，以防止'瀑布'（请求其他文件的文件请求）
* 文件哈希，以便您的资产可以永久缓存
* 请求合并，以便从单独的服务器中获取的 `load` 函数的数据被组合成一个单独的 HTTP 请求
* 并行加载，以便单独的通用`load`函数同时获取数据
* 数据内联，以便在服务器渲染期间使用 `fetch` 发出的请求可以在浏览器中重放，而无需发出新的请求
* 保守失效，以便只有在必要时才重新运行 `load` 函数
* 预渲染（如有必要，可按路由进行配置）以便在没有动态数据的情况下即时提供页面
* 链接预加载，以便客户端导航所需的数据和代码需求被积极期待
尽管如此，我们（目前）还不能消除所有导致缓慢的来源。为了获得最佳性能，您应该注意以下提示。
##
诊断问题
谷歌的[PageSpeed Insights](https://pagespeed.web.dev/)和（用于更深入的分析）[WebPageTest](https://www.webpagetest.org/)是了解已部署到互联网的网站性能特性的绝佳方式。
您的浏览器还包含用于分析您的网站（无论是已部署还是本地运行）的有用开发者工具：
* Chrome - [灯塔](https://developer.chrome.com/docs/lighthouse/overview#devtools)，[网络](https://developer.chrome.com/docs/devtools/network)和[性能](https://developer.chrome.com/docs/devtools/performance)开发者工具
* Edge - [灯塔](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/lighthouse/lighthouse-tool)，[网络](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/network/)和[性能](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/evaluate-performance/)开发工具
* Firefox - [网络](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/) 和 [性能](https://hacks.mozilla.org/2022/03/performance-tool-in-firefox-devtools-reloaded/) 开发者工具
* Safari - [提升您网页的性能](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/Web_Inspector_Tutorial/EnhancingyourWebpagesPerformance/EnhancingyourWebpagesPerformance.html)
请注意，您的网站在本地以`开发`模式运行时，其行为将与您的生产应用不同，因此在构建后，您应该在[预览](building-your-app#Preview-your-app)模式下进行性能测试。
###
仪表化
如果您在浏览器的网络标签页中看到 API 调用耗时较长，并且想了解原因，您可以考虑使用像[OpenTelemetry](https://opentelemetry.io/)或[Server-Timing 头](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing)这样的工具来对您的后端进行监控。
##
优化资产
###
图片
减小图像文件的大小通常是您可以对网站性能产生最显著影响的更改之一。Svelte 提供了`@sveltejs/enhanced-img`包，该包在[图像](images)页面上有详细说明，以使这一过程更加简便。此外，Lighthouse 工具有助于识别最严重的违规行为。
###
视频
视频文件可能非常大，因此应特别注意确保它们已优化：
* 使用如[Handbrake](https://handbrake.fr/)等工具压缩视频。考虑将视频转换为适合网页的格式，如`.webm`或`.mp4`。
* 您可以使用`preload="none"`（尽管请注意，当用户*启动*时，这将减慢播放速度）来懒加载位于页面底部的`lazy-load videos`。
* 从静音视频中提取音频轨道，使用类似[FFmpeg](https://ffmpeg.org/)的工具。
###
字体
SvelteKit 在用户访问页面时自动预加载关键的`.js`和`.css`文件，但默认情况下它不会预加载字体，因为这可能会导致下载不必要的文件（例如，CSS 中引用但当前页面实际未使用的字体粗细），因此，正确地预加载字体可以大大提高网站的感觉速度。在您的[`handle`](hooks#Server-hooks-handle)钩子中，您可以调用带有包含您的字体的`preload`过滤器的`resolve`。
您可以通过[子集化](https://web.dev/learn/performance/optimize-web-fonts#subset_your_web_fonts)字体来减小字体文件的大小。
##
减小代码大小
###
Svelte 版本
我们推荐运行最新的 Svelte 版本。Svelte 5 比 Svelte 4 更小、更快，而 Svelte 4 比 Svelte 3 更小、更快。
###
包
[`rollup-plugin-visualizer`](https://www.npmjs.com/package/rollup-plugin-visualizer) 可帮助您识别哪些包对您网站大小的贡献最大。您还可以通过手动检查构建输出（在您的 [Vite 配置](https://vitejs.dev/config/build-options.html#build-minify) 中使用 `build: { minify: false }` 使输出可读）或通过浏览器开发者工具的网络标签来找到移除代码的机会，但请记住在部署您的应用程序之前撤销该操作。
###
外部脚本
尝试最小化在浏览器中运行的第三方脚本数量。例如，与其使用基于 JavaScript 的分析，不如考虑使用服务器端实现，例如许多平台提供的带有 SvelteKit 适配器的那些，包括[Cloudflare](https://www.cloudflare.com/web-analytics/)、[Netlify](https://docs.netlify.com/monitor-sites/site-analytics/)和[Vercel](https://vercel.com/docs/analytics)。
要在一个 Web Worker 中运行第三方脚本（这可以避免阻塞主线程），请使用[Partytown 的 SvelteKit 集成](https://partytown.builder.io/sveltekit)。
###
选择加载
代码使用静态`import`声明导入时，将自动与页面其余部分捆绑。如果只有当某些条件满足时才需要某段代码，请使用动态`import(...)`形式来选择性地懒加载组件。
##
导航
###
预加载
您可以通过预先加载必要的代码和数据来加快客户端导航，使用[链接选项](link-options)。这在新创建的 SvelteKit 应用中默认配置在``元素上。
###
非必要数据
对于需要延迟加载且不需要立即使用的数据，您从 `load` 函数返回的对象可以包含承诺而不是数据本身。对于服务器的 `load` 函数，这将导致数据在导航（或初始页面加载）后 [流式传输](load#Streaming-with-promises)。
###
防止瀑布
最大的性能杀手之一被称为“瀑布”，它是一系列按顺序发出的请求。这可能在服务器或浏览器中发生。
* 资产瀑布可能在浏览器中发生，当您的 HTML 请求 JS，JS 请求 CSS，CSS 请求背景图片和 Web 字体时。SvelteKit 将通过添加`modulepreload`标签或头部来在很大程度上解决这类问题，但您应该查看[开发工具中的网络标签](#Diagnosing-issues)，以检查是否需要预加载其他资源。如果您使用 Web[字体](#Optimizing-assets-Fonts)，请特别注意这一点，因为它们需要手动处理。
* 如果通用的`加载`函数调用 API 获取当前用户，然后使用该响应的详细信息获取已保存项的列表，接着使用*该*响应获取每个项的详细信息，浏览器最终将执行多个连续请求。这对性能是致命的，尤其是对于物理位置远离您后端服务的用户。尽可能使用[服务器`加载`函数](load#Universal-vs-server)来避免这个问题。
* 服务器 `加载` 函数也不免受瀑布效应的影响（尽管它们的成本要低得多，因为它们很少涉及与高延迟的往返）。例如，如果您查询数据库以获取当前用户，然后使用该数据对保存的项目列表进行第二次查询，通常使用数据库连接发出单个查询会更高效。
##
托管
您的前端应位于与后端相同的数据中心，以最小化延迟。对于没有中央后端的服务站，许多 SvelteKit 适配器支持部署到边缘，这意味着从附近的服务器处理每个用户的请求。这可以显著减少加载时间。一些适配器甚至支持在每条路由上[配置部署](page-options#config)。您还应考虑从 CDN（通常是边缘网络）提供图片——许多 SvelteKit 适配器的宿主将自动执行此操作。
确保您的服务器使用 HTTP/2 或更高版本。Vite 的代码拆分创建了多个小文件以提高缓存性，从而实现卓越的性能，但这假设您的文件可以在 HTTP/2 下并行加载。
##
进一步阅读
对于大多数情况，构建一个高性能的 SvelteKit 应用与构建任何高性能的 Web 应用相同。你应该能够将来自通用性能资源（如[核心 Web 指标](https://web.dev/explore/learn-core-web-vitals)）的信息应用于你构建的任何 Web 体验。
# Icons
## CSS
一个使用图标的好方法是通过 CSS 纯定义它们。Iconify 支持[许多流行的图标集](https://icon-sets.iconify.design/)，这些图标集[可以通过 CSS 包含](https://iconify.design/docs/usage/css/)。此方法还可以通过利用 Iconify 的[Tailwind CSS 插件](https://iconify.design/docs/usage/css/tailwind/)或[UnoCSS 插件](https://iconify.design/docs/usage/css/unocss/)与流行的 CSS 框架一起使用。与基于 Svelte 组件的库不同，它不需要将每个图标导入到您的`.svelte`文件中。
## Svelte
有许多为 Svelte 的[图标库](https://www.sveltesociety.dev/packages?category=icons)。在选择图标库时，建议避免那些为每个图标提供`.svelte`文件的库，因为这些库可能有数千个`.svelte`文件，这会真正减慢[Vite 的依赖优化](https://vite.dev/guide/dep-pre-bundling.html)。如果图标同时通过伞式导入和子路径导入[如`vite-plugin-svelte` FAQ 中所述](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md#what-is-going-on-with-vite-and-pre-bundling-dependencies)，这可能会变得特别严重。
# Images
图片可以对您的应用性能产生重大影响。为了获得最佳效果，您应该通过以下方式优化它们：
* 生成最优格式，如`.avif`和`.webp`
* 创建不同屏幕尺寸
* 确保资产能够有效缓存
手动做这件事很繁琐。根据您的需求和偏好，您可以使用各种技术。
##
Vite 的内置处理
[Vite 将自动处理导入的资产](https://vitejs.dev/guide/assets.html)以提升性能。这包括通过 CSS `url()` 函数引用的资产。将添加哈希到文件名中以便缓存，并且小于 `assetsInlineLimit` 的资产将被内联。Vite 的资产处理通常用于图像，但也适用于视频、音频等。
```svelte
```
## @sveltejs/enhanced-img
`@sveltejs/enhanced-img` 是基于 Vite 内置资源处理的插件。它提供即插即用的图像处理功能，支持较小的文件格式如 `avif` 或 `webp`，自动设置图像的内在 `width` 和 `height` 以避免布局偏移，为不同设备创建多种尺寸的图像，并移除 EXIF 数据以保护隐私。它将在任何基于 Vite 的项目中工作，包括但不限于 SvelteKit 项目。
> \[!注意\] 作为构建插件，`@sveltejs/enhanced-img`只能在构建过程中优化您机器上的文件。如果您有位于其他位置（例如来自数据库、CMS 或后端的路径）的图片，请阅读有关[从 CDN 动态加载图片](#Loading-images-dynamically-from-a-CDN)的内容。
###
设置
安装：
```bash
npm install --save-dev @sveltejs/enhanced-img
```
调整 `vite.config.js`：
```js
import { sveltekit } from '@sveltejs/kit/vite';
+++import { enhancedImages } from '@sveltejs/enhanced-img';+++
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
+++enhancedImages(), // must come before the SvelteKit plugin+++
sveltekit()
]
});
```
建筑在第一次构建时将花费更长的时间，因为图像转换的计算成本较高。然而，构建输出将被缓存于 `./node_modules/.cache/imagetools` ，以便后续构建将更快。
###
基本用法
使用您的 `.svelte` 组件时，请使用 `` 而不是 `![]()
`，并通过 [Vite 资产导入](https://vitejs.dev/guide/assets.html#static-asset-handling) 路径引用图像文件：
```svelte
```
在构建时，您的 `` 标签将被替换为一个由 `` 包裹的 `![]()
`，提供多种图像类型和尺寸。只能在不损失质量的情况下缩小图像，这意味着您应该提供所需最高分辨率的图像——为可能请求图像的各种设备类型生成较小版本。
您应提供 2 倍分辨率的图片以供 HiDPI 显示器（即视网膜显示器）使用。代码``将自动为较小设备提供更小的版本。
> \[!注意\] 如果您想在 `
```
###
`srcset` 和 `sizes`
如果您有一张大图片，例如占据设计宽度的英雄图片，您应该指定`尺寸`，以便在较小设备上请求较小版本。例如，如果您有一张 1280 像素的图片，您可能希望指定如下：
```svelte
```
如果指定了 `尺寸`，则 `` 将为较小设备生成小图像并填充 `srcset` 属性。
最小的自动生成图片宽度为 540 像素。如果您需要更小的图片或希望指定自定义宽度，可以使用`w`查询参数来实现：
```svelte
```
如果未提供 `尺寸`，则将生成 HiDPI/Retina 图像和标准分辨率图像。您提供的图像应为您希望显示的分辨率的 2 倍，以便浏览器可以在具有高 [设备像素比](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio) 的设备上显示该图像。
###
每张图像的变换
默认情况下，增强的图像将被转换为更高效的格式。然而，您可能希望应用其他转换，如模糊、质量、平整或旋转操作。您可以通过附加查询字符串来运行每个图像的转换：
```svelte
```
[查看 imagetools 仓库以获取指令列表的完整列表](https://github.com/JonasKruckenberg/imagetools/blob/main/docs/directives.md).
##
动态从 CDN 加载图片
在某些情况下，图像可能在构建时不可访问——例如，它们可能位于内容管理系统或其他地方。
使用内容分发网络（CDN）可以允许您动态优化这些图像，并提供更多关于尺寸的灵活性，但可能涉及一些设置开销和使用成本。根据缓存策略，浏览器可能无法使用缓存的资产副本，直到从 CDN 接收到一个[304 响应](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304)。构建针对 CDN 的 HTML 允许使用`![]()
`标签，因为 CDN 可以根据`User-Agent`头部提供适当的格式，而构建时的优化必须生成带有多个源的``标签。最后，一些 CDN 可能会懒加载图像，这可能会对流量低且图像频繁更改的网站产生负面影响。
CDN 通常可以无需任何库即可使用。然而，有许多支持 Svelte 的库，使操作更加简便。[`@unpic/svelte`](https://unpic.pics/img/svelte/)是一个不依赖于 CDN 的库，支持大量提供商。您还可能发现特定 CDN 如[Cloudinary](https://svelte.cloudinary.dev/)支持 Svelte。最后，一些支持 Svelte 的内容管理系统（CMS）（如[Contentful](https://www.contentful.com/sveltekit-starter-guide/)、[Storyblok](https://github.com/storyblok/storyblok-svelte)和[Contentstack](https://www.contentstack.com/docs/developers/sample-apps/build-a-starter-website-with-sveltekit-and-contentstack)）内置了对图像处理的支撑。
##
最佳实践
* 对于每种图像类型，使用上述讨论中适当的方法。在一个项目中，您可以混合使用所有三种解决方案。例如，您可以使用 Vite 的内置处理为``标签提供图像，使用`@sveltejs/enhanced-img`在主页上显示图像，以及使用动态方法显示用户提交的内容。
* 考虑通过 CDN 提供所有图像，无论您使用哪种图像优化类型。CDN 通过在全球范围内分发静态资产的副本来减少延迟。
* 您的原始图像应具有良好的质量/分辨率，并且宽度应为显示宽度的 2 倍，以服务于 HiDPI 设备。图像处理可以将图像尺寸减小以节省带宽，但在为较小屏幕提供服务时，创建像素来放大图像将是带宽的浪费。
* 对于宽度远大于移动设备（约 400px）的图片（例如占据页面设计宽度的英雄图片），请指定`尺寸`，以便在较小设备上提供较小图片。
* 对于重要的图像，例如 [最大内容图像（LCP）](https://web.dev/articles/lcp) 图像，设置 `fetchpriority="high"` 并避免 `loading="lazy"` 以尽早优先加载。
* 给图片添加容器或样式，使其在页面加载时受到约束，不会跳转，从而影响您的[累积布局偏移（CLS）](https://web.dev/articles/cls)。 `宽度`和`高度`帮助浏览器在图片仍在加载时预留空间，因此`@sveltejs/enhanced-img`将为您添加`宽度`和`高度`。
* 始终提供良好的`alt`文本。如果未这样做，Svelte 编译器将警告您。
* 不要在`尺寸`中使用`em`或`rem`并更改这些度量单位的默认大小。当在`尺寸`或`@media`查询中使用时，`em`和`rem`都被定义为表示用户的默认`字体大小`。对于类似于 `sizes="(min-width: 768px) min(100vw, 108rem), 64rem"` 的`尺寸`声明，如果 CSS 更改，控制图像在页面上布局的实际`em`或`rem`可能会有所不同。例如，不要这样做`html { font-size: 62.5%; }`，因为浏览器预加载器保留的槽位现在将比 CSS 对象模型创建后的实际槽位更大。
# Accessibility
SvelteKit 默认致力于为您的应用提供一个可访问的平台。Svelte 的 [编译时访问性检查](../svelte/compiler-warnings) 也将适用于您构建的任何 SvelteKit 应用程序。
这里是如何使用 SvelteKit 内置的辅助功能以及您需要做什么来帮助这些功能尽可能好地工作。请注意，虽然 SvelteKit 提供了一个可访问的基础，但您仍然负责确保您的应用程序代码是可访问的。如果您对可访问性是新手，请参阅本指南的["进一步阅读"](accessibility#Further-reading)部分以获取更多资源。
我们认识到，实现无障碍性可能很难。如果您想建议如何改进 SvelteKit 处理无障碍性的方式，请[在 GitHub 上创建一个问题](https://github.com/sveltejs/kit/issues)。
##
路由公告
在传统的服务器端渲染应用中，每次导航（例如点击一个 `` 标签）都会触发整个页面的刷新。当这种情况发生时，屏幕阅读器和其他辅助技术会读出新页面的标题，以便用户了解页面已更改。
由于在 SvelteKit 中页面间的导航无需重新加载页面（称为[客户端路由](glossary#Routing)），SvelteKit 会在页面中注入一个[实时区域](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions)，在每次导航后读出新页面的名称。这通过检查`元素来确定要宣布的页面名称。`
由于这种行为，您的应用中的每个页面都应该有一个独特且描述性的标题。在 SvelteKit 中，您可以通过在每个页面上放置一个`<svelte:head>`元素来实现：
```svelte
<!--- file: src/routes/+page.svelte --->
<svelte:head>
<title>Todo List
```
这将允许屏幕阅读器和其它辅助技术识别导航后出现的新页面。提供描述性的标题对于[SEO](seo#Manual-setup-title-and-meta)也很重要。
##
聚焦管理
在传统的服务器端渲染应用中，每次导航都会将焦点重置到页面顶部。这确保了使用键盘或屏幕阅读器浏览网页的人将从页面开始进行交互。
为了在客户端路由中模拟此行为，SvelteKit 在每次导航后聚焦于``元素，并在[增强表单提交](form-actions#Progressive-enhancement)后。有一个例外——如果存在具有[`autofocus`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus)属性的元素，SvelteKit 将聚焦该元素。在使用该属性时，请确保[考虑对辅助技术的潜在影响](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus#accessibility_considerations)。
如果您想自定义 SvelteKit 的焦点管理，可以使用`afterNavigate`钩子：
```js
///
// ---cut---
import { afterNavigate } from '$app/navigation';
afterNavigate(() => {
/** @type {HTMLElement | null} */
const to_focus = document.querySelector('.focus-me');
to_focus?.focus();
});
```
您也可以使用`goto`函数以编程方式导航到不同的页面。[默认情况下，这将具有与点击链接相同的客户端路由行为。]($app-navigation#goto)然而，`goto`还接受一个`keepFocus`选项，该选项将保留当前聚焦的元素而不是重置焦点。如果您启用此选项，请确保在导航后当前聚焦的元素仍然存在于页面上。如果该元素不再存在，用户的焦点将会丢失，这将为辅助技术用户带来困惑体验。
##
"lang" 属性
默认情况下，SvelteKit 的页面模板将文档的默认语言设置为英语。如果您的内 容不是英语，您应该更新``元素在`src/app.html`中的正确`lang`属性。这将确保任何辅助技术阅读文档时使用正确的发音。例如，如果您的内 容是德语，您应该更新`app.html`为以下内容：
```html
/// file: src/app.html
```
如果您的内容支持多种语言，应根据当前页面的语言设置 `lang` 属性。您可以使用 SvelteKit 的 [handle 钩子](hooks#Server-hooks-handle) 来实现：
```html
/// file: src/app.html
```
```js
/// file: src/hooks.server.js
/**
* @param {import('@sveltejs/kit').RequestEvent} event
*/
function get_lang(event) {
return 'en';
}
// ---cut---
/** @type {import('@sveltejs/kit').Handle} */
export function handle({ event, resolve }) {
return resolve(event, {
transformPageChunk: ({ html }) => html.replace('%lang%', get_lang(event))
});
}
```
##
进一步阅读
对于大多数情况，构建一个可访问的 SvelteKit 应用与构建一个可访问的 Web 应用相同。您应该能够将以下通用可访问性资源中的信息应用于您构建的任何 Web 体验：
* [
MDN 网络文档：无障碍](https://developer.mozilla.org/en-US/docs/Learn/Accessibility)
* [
A11y 项目](https://www.a11yproject.com/)
* [
如何满足 WCAG（快速参考）](https://www.w3.org/WAI/WCAG21/quickref/)
# SEO
最重要的 SEO 方面是创建高质量的内容，这些内容在网络上被广泛链接。然而，对于构建排名良好的网站，还有一些技术考虑因素。
##
即开即用
### SSR
尽管近年来搜索引擎在索引使用客户端 JavaScript 渲染的内容方面有所改进，但服务器端渲染的内容索引得更频繁且更可靠。SvelteKit 默认采用 SSR（服务器端渲染），尽管你可以在`handle`中禁用它，除非你有充分的理由不这样做，否则你应该保持开启状态。
> \[!注意\] SvelteKit 的渲染高度可配置，您如果需要可以实施 [动态渲染](https://developers.google.com/search/docs/advanced/javascript/dynamic-rendering)。通常不推荐这样做，因为 SSR 除了 SEO 之外还有其他好处。
###
性能
信号如[核心网页关键指标](https://web.dev/vitals/#core-web-vitals)影响搜索引擎排名。由于 Svelte 和 SvelteKit 引入的额外开销最小，因此构建高性能网站更容易。您可以使用 Google 的[页面速度洞察](https://pagespeed.web.dev/)或[灯塔](https://developers.google.com/web/tools/lighthouse)测试您网站的性能。阅读[性能页面](performance)获取更多详细信息。
###
标准化 URL
SvelteKit 将带有尾随斜杠的路径名重定向到不带斜杠的路径名（或反之亦然，具体取决于您的[配置](page-options#trailingSlash)），因为重复的 URL 对 SEO 不利。
##
手动设置
###
<标题> 和 <元数据>
每页都应该包含编写良好且独特的 `` 和 `<meta name="description">` 元素，这些元素位于 [`<svelte:head>`](../svelte/svelte-head) 内。有关如何编写描述性标题和描述的指南，以及如何使内容更容易被搜索引擎理解的其它建议，可以在 Google 的 [Lighthouse SEO audits](https://web.dev/lighthouse-seo/) 文档中找到。
> \[!注意\] 常见的模式是从页面 [`加载`](load) 函数返回与 SEO 相关的 `数据`，然后将其（作为 [`page.data`]($app-state)）用于根 [布局](routing#layout) 中的 `<svelte:head>`。
###
网站地图
[网站地图](https://developers.google.com/search/docs/advanced/sitemaps/build-sitemap)帮助搜索引擎优先处理您网站内的页面，尤其是当您有大量内容时。您可以使用端点动态创建网站地图。
```js
/// file: src/routes/sitemap.xml/+server.js
export async function GET() {
return new Response(
`
<?xml version="1.0" encoding="UTF-8" ?>
<urlset
xmlns="https://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:xhtml="https://www.w3.org/1999/xhtml"
xmlns:mobile="https://www.google.com/schemas/sitemap-mobile/1.0"
xmlns:news="https://www.google.com/schemas/sitemap-news/0.9"
xmlns:image="https://www.google.com/schemas/sitemap-image/1.1"
xmlns:video="https://www.google.com/schemas/sitemap-video/1.1"
>
<!-- <url> elements go here -->
</urlset>`.trim(),
{
headers: {
'Content-Type': 'application/xml'
}
}
);
}
```
### AMP
现代网页开发的一个不幸现实是，有时有必要创建一个[加速移动页面（AMP）](https://amp.dev/)版本的网站。在 SvelteKit 中，可以通过设置[`inlineStyleThreshold`](configuration#inlineStyleThreshold)选项来完成此操作...
```js
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
// since <link rel="stylesheet"> isn't
// allowed, inline all styles
inlineStyleThreshold: Infinity
}
};
export default config;
```
...在您的根目录 `csr` 中禁用 `+layout.js`/`+layout.server.js`...
```js
/// file: src/routes/+layout.server.js
export const csr = false;
```
...将`amp`添加到您的`app.html`中
`＜html amp＞ ...`
...并使用 `transformPageChunk` 和从 `@sveltejs/amp` 导入的 `transform` 对 HTML 进行转换：
```js
/// file: src/hooks.server.js
import * as amp from '@sveltejs/amp';
/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
let buffer = '';
return await resolve(event, {
transformPageChunk: ({ html, done }) => {
buffer += html;
if (done) return amp.transform(buffer);
}
});
}
```
为防止在将页面转换为 amp 时发送任何未使用的 CSS，我们可以使用[`dropcss`](https://www.npmjs.com/package/dropcss)：
```js
// @filename: ambient.d.ts
declare module 'dropcss';
// @filename: index.js
// ---cut---
/// file: src/hooks.server.js
// @errors: 2307
import * as amp from '@sveltejs/amp';
import dropcss from 'dropcss';
/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
let buffer = '';
return await resolve(event, {
transformPageChunk: ({ html, done }) => {
buffer += html;
if (done) {
let css = '';
const markup = amp
.transform(buffer)
.replace('⚡', 'amp') // dropcss can't handle this character
.replace(/<style amp-custom([^>]*?)>([^]+?)<\/style>/, (match, attributes, contents) => {
css = contents;
return `<style amp-custom${attributes}></style>`;
});
css = dropcss({ css, html: markup }).css;
return markup.replace('</style>', `${css}</style>`);
}
}
});
}
```
> \[!注意\] 使用 `handle` 钩子来验证转换后的 HTML 使用 `amphtml-validator` 是一个好主意，但仅当你在预渲染页面时，因为它非常慢。
# Frequently asked questions
##
其他资源
请参阅[的 Svelte FAQ](../svelte/faq)和[`的 vite-plugin-svelte` FAQ](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md)，以获取从这些库中产生的问题的答案。
##
我能用 SvelteKit 做什么？
查看有关项目类型的文档以获取更多详细信息。[文档](project-types)
##
如何在我的应用程序中包含 package.json 的详细信息？
如果您想在您的应用程序中包含应用程序的版本号或其他来自 `package.json` 的信息，您可以如此加载 JSON：
```ts
// @errors: 2732
/// file: svelte.config.js
import pkg from './package.json' with { type: 'json' };
```
##
如何修复尝试包含包时遇到的错误？
大多数与包含库相关的问题都是由于打包不正确造成的。您可以通过将其输入到[publint 网站](https://publint.dev/)来检查库的打包是否与 Node.js 兼容。
以下是一些在检查库是否正确打包时需要注意的事项：
* `exports` 具有比其他入口字段（如 `main` 和 `module`）更高的优先级。添加一个 `exports` 字段可能不向后兼容，因为它会阻止深度导入。
* ESM 文件应以`.mjs`结尾，除非设置了`"type": "module"`，在这种情况下，任何 CommonJS 文件都应以`.cjs`结尾。
* `main` 应当在 `exports` 未定义时进行定义。它应为一个 CommonJS 或 ESM 文件，并遵守前面的项目符号。如果定义了 `module` 字段，则应指向一个 ESM 文件。
* Svelte 组件应作为未编译的 `.svelte` 文件分发，包内任何 JS 代码应仅以 ESM 格式编写。自定义脚本和样式语言，如 TypeScript 和 SCSS，应分别预处理为纯 JS 和 CSS。我们建议使用 [`svelte-package`](./packaging) 对 Svelte 库进行打包，这将为您完成此操作。
库在浏览器中使用 Vite 效果最佳，尤其是在它们分发 ESM 版本时，尤其是当它们是 Svelte 组件库的依赖项时。您可能希望建议库作者提供 ESM 版本。然而，由于默认情况下，[`vite-plugin-svelte` 将会请求 Vite 预打包它们](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md#what-is-going-on-with-vite-and-pre-bundling-dependencies)，使用 `esbuild` 将它们转换为 ESM，因此 CommonJS (CJS) 依赖项也应该可以正常工作。
如果您仍然遇到问题，我们建议您同时搜索[Vite 问题跟踪器](https://github.com/vitejs/vite/issues)和所涉及库的问题跟踪器。有时，通过调整[`optimizeDeps`](https://vitejs.dev/config/#dep-optimization-options)或[`ssr`](https://vitejs.dev/config/#ssr-options)配置值可以解决这些问题，尽管我们建议这仅作为修复所涉及库的短期解决方案。
##
如何使用视图转换 API？
虽然 SvelteKit 没有与 [视图过渡](https://developer.chrome.com/docs/web-platform/view-transitions/) 的特定集成，你可以在 [`onNavigate`]($app-navigation#onNavigate) 中调用 `document.startViewTransition` 来在每次客户端导航时触发视图过渡。
```js
// @errors: 2339 2810
import { onNavigate } from '$app/navigation';
onNavigate((navigation) => {
if (!document.startViewTransition) return;
return new Promise((resolve) => {
document.startViewTransition(async () => {
resolve();
await navigation.complete;
});
});
});
```
更多内容，请参阅 Svelte 博客上的["解锁视图转换"](/blog/view-transitions)。
##
如何设置数据库？
将查询数据库的代码放入[服务器路由](./routing#server)中 - 不要在.svelte 文件中查询数据库。您可以创建一个`db.js`或类似的文件，立即建立连接并使客户端在整个应用程序中作为单例可用。您可以在`hooks.server.js`中执行任何一次性设置代码，并将您的数据库助手导入到需要它们的任何端点。
您可以使用 [Svelte CLI](/docs/cli/overview)自动设置数据库集成。
##
如何使用客户端库访问`document`或`window>？`
如果您需要访问 `文档` 或 `窗口` 变量，或者需要仅在客户端运行的代码，您可以将它包裹在 `浏览器` 检查中：
```js
/// <reference types="@sveltejs/kit" />
// ---cut---
import { browser } from '$app/environment';
if (browser) {
// client-only code here
}
```
您也可以在`onMount`中运行代码，如果您想在组件首次渲染到 DOM 后运行它：
```js
// @filename: ambient.d.ts
// @lib: ES2015
declare module 'some-browser-only-library';
// @filename: index.js
// ---cut---
import { onMount } from 'svelte';
onMount(async () => {
const { method } = await import('some-browser-only-library');
method('hello world');
});
```
如果希望使用的库是无副作用的，您还可以静态导入它，在服务器端构建过程中它将被摇树优化，其中 `onMount` 将自动替换为空操作：
```js
// @filename: ambient.d.ts
// @lib: ES2015
declare module 'some-browser-only-library';
// @filename: index.js
// ---cut---
import { onMount } from 'svelte';
import { method } from 'some-browser-only-library';
onMount(() => {
method('hello world');
});
```
最后，您还可以考虑使用一个 `{#await}` 块：
```svelte
<!--- file: index.svelte --->
<script>
import { browser } from '$app/environment';
const ComponentConstructor = browser ?
import('some-browser-only-library').then((module) => module.Component) :
new Promise(() => {});
</script>
{#await ComponentConstructor}
<p>Loading...</p>
{:then component}
<svelte:component this={component} />
{:catch error}
<p>Something went wrong: {error.message}</p>
{/await}
```
##
如何使用不同的后端 API 服务器？
您可以使用[`event.fetch`](./load#Making-fetch-requests)从外部 API 服务器请求数据，但请注意，您需要处理[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)，这可能会导致一些复杂情况，例如通常需要预先发送请求，从而导致更高的延迟。向不同的子域发送请求也可能由于额外的 DNS 查找、TLS 设置等而增加延迟。如果您想使用这种方法，可能会发现[`handleFetch`](./hooks#Server-hooks-handleFetch)很有帮助。
另一种方法是设置代理以绕过 CORS 问题。在生产环境中，您会将路径如`/api`重写到 API 服务器；对于本地开发，使用 Vite 的[`server.proxy`](https://vitejs.dev/config/server-options.html#server-proxy)选项。
如何在生产环境中设置重写取决于您的部署平台。如果重写不是选项，您可以另加一个[API 路由](./routing#server)：
```js
/// file: src/routes/api/[...path]/+server.js
/** @type {import('./$types').RequestHandler} */
export function GET({ params, url }) {
return fetch(`https://my-api-server.com/${params.path + url.search}`);
}
```
（请注意，您可能还需要代理 `POST`/`PATCH` 等请求，并根据需要转发 `request.headers`。）
##
如何使用中间件？
`适配器节点`构建一个中间件，您可以使用它与自己的服务器一起用于生产模式。在开发中，您可以通过使用 Vite 插件将中间件添加到 Vite。例如：
```js
// @errors: 2322
// @filename: ambient.d.ts
declare module '@sveltejs/kit/vite'; // TODO this feels unnecessary, why can't it 'see' the declarations?
// @filename: index.js
// ---cut---
import { sveltekit } from '@sveltejs/kit/vite';
/** @type {import('vite').Plugin} */
const myPlugin = {
name: 'log-request-middleware',
configureServer(server) {
server.middlewares.use((req, res, next) => {
console.log(`Got request ${req.url}`);
next();
});
}
};
/** @type {import('vite').UserConfig} */
const config = {
plugins: [myPlugin, sveltekit()]
};
export default config;
```
查看[Vite 的`configureServer`文档](https://vitejs.dev/guide/api-plugin.html#configureserver)以获取更多详细信息，包括如何控制排序。
##
如何使用 Yarn？
###
支持 Yarn 2 吗？
有点问题。即插即用功能，即“pnp”，已损坏（它与 Node 模块解析算法不符，并且[不支持与原生 JavaScript 模块一起使用](https://github.com/yarnpkg/berry/issues/638)，而 SvelteKit——以及越来越多的[包](https://blog.sindresorhus.com/get-ready-for-esm-aa53530b3f77)——正是这样使用的）。您可以在您的[`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc#nodeLinker)文件中使用`nodeLinker: 'node-modules'`来禁用 pnp，但可能直接使用 npm 或[pnpm](https://pnpm.io/)更简单，它们同样快速高效，但无需处理兼容性问题。
###
如何使用 Yarn 3？
当前最新版本的 Yarn（版本 3）中的 ESM 支持[被视为实验性的](https://github.com/yarnpkg/berry/pull/2161)。
以下似乎可以工作，尽管您的结果可能会有所不同。首先创建一个新的应用程序：
```bash
yarn create svelte myapp
cd myapp
```
并启用 Yarn Berry：
```bash
yarn set version berry
yarn install
```
Yarn Berry 的一个更有趣的特性是能够拥有单个全局缓存包，而不是在磁盘上为每个项目存储多个副本。然而，将`enableGlobalCache`设置为 true 会导致构建失败，因此建议将以下内容添加到`.yarnrc.yml`文件中：
`nodeLinker: 节点链接`
这会导致包被下载到本地的 node\_modules 目录中，但避免了上述问题，并且是目前使用 Yarn 3 版本的最佳选择。
# Integrations
##
`vitePreprocess`
包括 [`vitePreprocess`](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/preprocess.md) 在您的项目中，将允许您使用 Vite 支持的各种 CSS 风格：PostCSS、SCSS、Less、Stylus 和 SugarSS。如果您使用 TypeScript 设置项目，它将默认包含：
```js
// svelte.config.js
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
export default {
preprocess: [vitePreprocess()]
};
```
您在使用 Svelte 4 与 TypeScript 时也需要使用预处理器。如果仅使用类型语法，Svelte 5 原生支持 TypeScript。要在 Svelte 5 中使用更复杂的 TypeScript 语法，您仍然需要一个预处理器，并可以使用 `vitePreprocess({ script: true })` 。
## Adders
运行 `npx sv add` 以通过单个命令设置许多不同的复杂集成，包括：
* prettier（格式化）
* eslint（代码风格检查）
* vitest（单元测试）
* playwright（端到端测试）
* lucia (认证)
* tailwind (CSS)
* drizzle (DB)
* 滑翔伞（国际化）
* mdsvex（Markdown）
* 故事书（前端工作坊）
##
目录
查看[sveltesociety.dev](https://sveltesociety.dev/)获取 Svelte 和 SvelteKit 可用的[包](https://sveltesociety.dev/packages)和[模板](https://sveltesociety.dev/templates)的完整列表。
##
附加集成
###
`سلتو-پریپرس`
`سلتو-پروسیس` دارای برخی ویژگیهای اضافی است که در `ویت-پروسیس` یافت نمیشود، مانند پشتیبانی از Pug، Babel و استایلهای جهانی. اما `ویت-پروسیس` ممکن است سریعتر باشد و نیاز به تنظیم کمتری داشته باشد، بنابراین به طور پیشفرض استفاده میشود. توجه داشته باشید که CoffeeScript توسط SvelteKit [پشتیبانی نمیشود](https://github.com/sveltejs/kit/issues/2920#issuecomment-996469815).
您需要使用 `npm install --save-dev svelte-preprocess` 安装`svelte-preprocess`，并将其添加到您的`svelte.config.js`中。之后，您通常需要安装相应的库，例如`npm install -D sass`或`npm install -D less`。
##
Vite 插件
由于 SvelteKit 项目是用 Vite 构建的，您可以使用 Vite 插件来增强您的项目。请查看可用的插件列表，见 [`vitejs/awesome-vite`](https://github.com/vitejs/awesome-vite?tab=readme-ov-file#plugins)。
##
集成常见问题解答
[《SvelteKit 常见问题解答》](./faq)回答了关于如何使用 SvelteKit 进行 X 操作的许多问题，如果您还有疑问，这可能很有帮助。
# Breakpoint Debugging
除了 [`@debug`](../svelte/@debug) 标签外，您还可以使用各种工具和开发环境中的断点来调试 Svelte 和 SvelteKit 项目。这包括前端和后端代码。
以下指南假定您的 JavaScript 运行时环境为 Node.js。
## Visual Studio Code
使用内置的调试终端，您可以在 VSCode 中的源文件中设置断点。
1. 打开命令面板：`CMD/Ctrl` + `Shift` + `P`。
2. 查找并启动“调试：JavaScript 调试终端”。
3. 以调试终端开始您的项目。例如：`npm run dev`。
4. 设置客户端或服务器端源代码中的断点。
5. 触发断点。
###
启动调试面板
您还可以在项目中设置一个 `.vscode/launch.json`。要自动设置一个：
1. 进入“运行和调试”面板。
2. 在“运行”选择菜单中，选择“Node.js...”。
3. 选择与您的项目对应的“运行脚本”，例如“运行脚本：dev”。
4. 按“开始调试”播放按钮，或按`F5`键开始断点调试。
这里是一个示例 `launch.json`：
```json
{
"version": "0.2.0",
"configurations": [
{
"command": "npm run dev",
"name": "Run development server",
"request": "launch",
"type": "node-terminal"
}
]
}
```
进一步阅读：[https://code.visualstudio.com/docs/editor/debugging](https://code.visualstudio.com/docs/editor/debugging).
##
其他编辑器
如果您使用不同的编辑器，这些社区指南可能对您有帮助：
* [
WebStorm Svelte：调试您的应用程序](https://www.jetbrains.com/help/webstorm/svelte.html#ws_svelte_debug)
* [
调试 Neovim 中的 JavaScript 框架](https://theosteiner.de/debugging-javascript-frameworks-in-neovim)
##
谷歌 Chrome 和微软 Edge 开发者工具
可以使用基于浏览器的调试器调试 Node.js 应用程序。
> \[!注意\] 注意这仅适用于调试客户端 SvelteKit 源映射。
1. 运行 Vite 服务器时使用 Node.js 启动 `–inspect` 标志。例如： `NODE_OPTIONS="--inspect" npm run dev`
2. 打开您的网站在新标签页中。通常在 `localhost:5173`。
3. 打开浏览器开发者工具，点击顶部左侧的“为 Node.js 打开专用 DevTools”图标。它应该显示 Node.js 标志。
4. 设置断点并调试您的应用程序。
您可以选择通过在 Google Chrome 中导航到`chrome://inspect`或 Microsoft Edge 中的`edge://inspect`来打开调试器开发者工具。
##
参考文献
* [
调试 Node.js](https://nodejs.org/en/learn/getting-started/debugging)
# Migrating to SvelteKit v2
升级从 SvelteKit 版本 1 到版本 2 应该大部分是无缝的。有一些需要注意的重大更改，列在这里。您可以使用 `npx sv migrate sveltekit-2` 自动迁移其中的一些更改。
强烈建议在升级到 2.0 版本之前先升级到最新的 1.x 版本，以便您能够利用有针对性的弃用警告。我们还建议首先[更新到 Svelte 4](../svelte/v4-migration-guide)：SvelteKit 1.x 的后续版本支持它，而 SvelteKit 2.0 则要求必须使用它。
##
`redirect` 和 `error` 已不再由您抛出
之前，您必须自己 `抛出` 由 `error(...)` 和 `redirect(...)` 返回的值。在 SvelteKit 2 中，这种情况不再存在——调用函数就足够了。
```js
import { error } from '@sveltejs/kit'
// ...
---throw error(500, 'something went wrong');---
+++error(500, 'something went wrong');+++
```
`سوفت-مهاجرت`将为您自动执行这些更改。
如果错误或重定向在`try {...}`块内部抛出（提示：不要这样做！），您可以使用从`@sveltejs/kit`导入的`isHttpError`和`isRedirect`来区分它们与意外错误。
##
路径设置 cookie 时是必需的
当接收到未指定 `path` 的 `Set-Cookie` 标头时，浏览器会将 cookie 路径设置为所涉及资源的父路径。这种行为并不特别有用或直观，并且经常导致错误，因为开发者原本期望 cookie 应用于整个域名。
截至 SvelteKit 2.0，调用`cookies.set(...)`、`cookies.delete(...)`或`cookies.serialize(...)`时，您需要设置一个`path`，以便没有歧义。大多数情况下，您可能想使用`path: '/'`，但您可以将其设置为任何您喜欢的路径，包括相对路径——`''`表示'当前路径'，`'.'`表示'当前目录'。
```js
/** @type {import('./$types').PageServerLoad} */
export function load({ cookies }) {
cookies.set(name, value, +++{ path: '/' }+++);
return { response }
}
```
`سلتو-مigrate` 将添加注释以突出需要调整的位置。
##
顶级承诺不再等待
在 SvelteKit 版本 1 中，如果从`load`函数返回的对象的顶级属性是 promises，它们会自动等待。随着[流式传输的引入，这种行为变得有些尴尬，因为它迫使你将流式数据嵌套在一层之内。](/blog/streaming-snapshots-sveltekit)
截至版本 2，SvelteKit 不再区分顶层和非顶层承诺。要恢复阻塞行为，请使用`await`（在适当的情况下，使用`Promise.all`以防止瀑布效果）：
```js
// @filename: ambient.d.ts
declare const url: string;
// @filename: index.js
// ---cut---
// If you have a single promise
/** @type {import('./$types').PageServerLoad} */
export +++async+++ function load({ fetch }) {
const response = +++await+++ fetch(url).then(r => r.json());
return { response }
}
```
```js
// @filename: ambient.d.ts
declare const url1: string;
declare const url2: string;
// @filename: index.js
// ---cut---
// If you have multiple promises
/** @type {import('./$types').PageServerLoad} */
export +++async+++ function load({ fetch }) {
--- const a = fetch(url1).then(r => r.json());---
--- const b = fetch(url2).then(r => r.json());---
+++ const [a, b] = await Promise.all([
fetch(url1).then(r => r.json()),
fetch(url2).then(r => r.json()),
]);+++
return { a, b };
}
```
##
goto(...) 变更
`goto(...)` 不再接受外部 URL。要导航到外部 URL，请使用 `window.location.href = url`。现在 `state` 对象决定 `$page.state`，并且如果已声明，必须遵循 `App.PageState` 接口。有关更多详细信息，请参阅 [浅路由](shallow-routing)。
##
路径现在默认为相对路径
在 SvelteKit 1 中，您的`app.html`中的`%sveltekit.assets%`在服务器端渲染时默认被替换为相对路径（即`.`或`..`或`../..`等，具体取决于渲染的路径），除非显式地将`paths.relative`配置选项设置为`false`。同样，从`$app/paths`导入的`base`和`assets`也是如此，但仅当显式将`paths.relative`选项设置为`true`时。
此不一致性已在版本 2 中修复。路径要么始终是相对的，要么始终是绝对的，具体取决于[`paths.relative`](configuration#paths)的值。默认为`true`，因为这会产生更便携的应用程序：如果`base`不是应用程序期望的（例如在[互联网档案馆](https://archive.org/)查看时）或构建时未知（例如部署到[IPFS](https://ipfs.tech/)等），则出现问题的可能性更小。
##
服务器抓取不再可追踪
之前可以从服务器上的`fetch`es 跟踪 URL 以重新运行加载函数。这可能导致潜在的安全风险（私人 URL 泄露），因此它位于`dangerZone.trackServerFetches`设置之后，该设置现已移除。
##
`preloadCode` 参数必须以 `base` 前缀
SvelteKit 公开了两个函数，[`preloadCode`]($app-navigation#preloadCode) 和 [`preloadData`]($app-navigation#preloadData)，用于以编程方式加载与特定路径关联的代码和数据。在版本 1 中，存在一个微妙的不一致——传递给`preloadCode`的路径不需要（如果已设置）以`base`路径作为前缀，而传递给`preloadData`的路径则需要。
这是在 SvelteKit 2 中修复的——在两种情况下，如果已设置，路径应该以`base`为前缀。
此外，`preloadCode` 现在接受单个参数，而不是 *n* 个参数。
##
`resolvePath` 已被移除
SvelteKit 1 包含了一个名为 `resolvePath` 的函数，该函数允许您将路由 ID（如 `/blog/[slug]`）和一组参数（如 `{ slug: 'hello' }`）解析为路径名。不幸的是，返回值没有包括 `base` 路径，限制了其在 `base` 已设置的情况下的实用性。
因此，SvelteKit 2 将 `resolvePath` 替换为（名称稍好一些的）函数 `resolveRoute`，该函数从 `$app/paths` 导入，并考虑了 `base`。
```js
---import { resolvePath } from '@sveltejs/kit';
import { base } from '$app/paths';---
+++import { resolveRoute } from '$app/paths';+++
---const path = base + resolvePath('/blog/[slug]', { slug });---
+++const path = resolveRoute('/blog/[slug]', { slug });+++
```
`سلتو-مigrate` 将为您执行方法替换，尽管如果您稍后用 `base` 预先添加结果，您需要自己将其删除。
##
改进的错误处理
错误在 SvelteKit 1 中处理不一致。一些错误会触发`handleError`钩子，但没有好的方法来辨别它们的状态（例如，区分 404 和 500 的唯一方法是通过查看`event.route.id`是否为`null`），而其他错误（如对没有操作的页面进行`POST`请求的 405 错误）根本不会触发`handleError`，但应该会。在后一种情况下，结果`$page.error`将与指定的`App.Error`[（](types#Error)如果指定的话[）](types#Error)类型不符。
SvelteKit 2 通过调用 `handleError` 钩子并使用两个新属性：`status` 和 `message` 来清理。对于从您的代码（或由您的代码调用的库代码）抛出的错误，状态将是 `500`，消息将是 `内部错误`。而 `error.message` 可能包含不应向用户暴露的敏感信息，`message` 则是安全的。
##
动态环境变量在预渲染期间无法使用
The `$env/dynamic/public` 和 `$env/dynamic/private` 模块提供对 *运行时* 环境变量的访问，与 `$env/static/public` 和 `$env/static/private` 提供的 *构建时* 环境变量相反。
在 SvelteKit 1 的预渲染期间，它们是相同的。因此，使用 '动态' 环境变量的预渲染页面实际上是在“烘焙”构建时间值，这是不正确的。更糟糕的是，如果用户在导航到动态渲染的页面之前恰好访问了预渲染的页面，`$env/dynamic/public` 将在浏览器中使用这些过时的值进行填充。
由于这个原因，在 SvelteKit 2 的预渲染过程中无法读取动态环境变量 — 您应该使用 `静态` 模块。如果用户访问预渲染的页面，SvelteKit 将从服务器（默认情况下从名为`/_app/env.js`的模块）请求最新的`$env/dynamic/public`值，而不是从服务器渲染的 HTML 中读取它们。
##
`表单` 和 `数据` 已从 `使用：增强` 回调中移除
如果您提供了一个回调到[`使用：增强`](form-actions#Progressive-enhancement-use:enhance)，它将用一个包含各种有用属性的对象被调用。
在 SvelteKit 1 中，这些属性包括`form`和`data`。这些属性在一段时间前已被弃用，转而使用`formElement`和`formData`，并在 SvelteKit 2 中完全删除。
##
表单中包含文件输入时必须使用 `multipart/form-data`
如果一个表单包含一个`<input type="file">`但没有任何`enctype="multipart/form-data"`属性，非 JS 提交将省略文件。SvelteKit 2 在遇到这样的表单进行`use:enhance`提交时将抛出错误，以确保在没有 JavaScript 的情况下您的表单能够正确工作。
##
生成的`tsconfig.json`更严格
之前，生成的`tsconfig.json`在您的`tsconfig.json`包含`paths`或`baseUrl`时，仍在尽力生成一个相对有效的配置。在 SvelteKit 2 中，验证更加严格，当您在`tsconfig.json`中使用`paths`或`baseUrl`时，将会发出警告。这些设置用于生成路径别名，您应该使用`svelte.config.js`中的`alias`配置选项，以创建相应的别名，并为打包器创建相应的别名。
##
`getRequest`不再抛出错误
The `@sveltejs/kit/node` 模块导出用于 Node 环境的辅助函数，包括 `getRequest`，它将 Node [`ClientRequest`](https://nodejs.org/api/http.html#class-httpclientrequest) 转换为标准的 [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) 对象。
在 SvelteKit 1 中，`getRequest` 如果 `Content-Length` 头部超出指定大小限制时可能会抛出异常。在 SvelteKit 2 中，错误将不会立即抛出，而是在读取请求体（如果有）时才会抛出。这有助于更好地进行诊断和编写更简单的代码。
##
`vitепPгeprеss`不再从`@sveltejs/kit/vite`导出
由于 `@sveltejs/vite-plugin-svelte` 现在是一个 peer dependency，SvelteKit 2 不再导出 `vitePreprocess`。您应直接从 `@sveltejs/vite-plugin-svelte` 导入它。
##
更新依赖项要求
SvelteKit 2 需要 Node `18.13` 或更高版本，以及以下最低依赖版本：
* `斯威夫特@4`
* `vit@5`
* `typescript@5`
* `@sveltejs/vite-plugin-svelte@3` (现在作为 SvelteKit 的 `peerDependency` 是必需的 — 之前它是直接依赖的)
* `@sveltejs/adapter-cloudflare@3` （如果您使用这些适配器）
* `@sveltejs/adapter-cloudflare-workers@2`
* `@sveltejs/adapter-netlify@3`
* `@sveltejs/adapter-node@2`
* `@sveltejs/adapter-static@3`
* `@sveltejs/adapter-vercel@4`
`سلتو-مigrate` 将为您更新 `package.json`。
作为 TypeScript 升级的一部分，生成的`tsconfig.json`（你的`tsconfig.json`从中扩展而来）现在使用`"moduleResolution": "bundler"`（TypeScript 团队推荐，因为它可以正确解析具有 package.json 中`exports`映射的包中的类型）和`verbatimModuleSyntax`（它替换了现有的`importsNotUsedAsValues`和`preserveValueImports`标志——如果你在`tsconfig.json`中有这些，请删除它们。`svelte-migrate`会为你完成这项工作）。
##
SvelteKit 2.12: $app/stores 已弃用
SvelteKit 2.12 引入了基于 `$app/state` 的 [Svelte 5 runes API](/docs/svelte/what-are-runes)。`$app/state` 提供了与 `$app/stores` 相同的一切，但在使用方式和位置上提供了更大的灵活性。最重要的是，`page` 对象现在更加精细，例如，对 `page.state` 的更新不会使 `page.data` 无效，反之亦然。
因此，`$app/stores` 已弃用，并将在 SvelteKit 3 中被移除。如果您尚未升级，我们建议[升级到 Svelte 5](/docs/svelte/v5-migration-guide)，然后迁移离开 `$app/stores`。大多数替代方案应该相当简单：将 `$app/stores` 的导入替换为 `$app/state`，并从使用位置删除 `$` 前缀。
```svelte
<script>
---import { page } from '$app/stores';---
+++import { page } from '$app/state';+++
</script>
---{$page.data}---
+++{page.data}+++
```
使用`npx sv migrate app-state`自动迁移大部分在`$app/stores`中使用的`.svelte`组件。
# Migrating from Sapper
SvelteKit 是 Sapper 的继任者，并共享其设计中的许多元素。
如果您已经有一个计划迁移到 SvelteKit 的 Sapper 应用程序，您将需要做出一些更改。在迁移过程中查看一些示例可能会有所帮助。[一些示例](additional-resources#Examples)
## package.json
###
类型: "模块"
添加 `"类型": "模块"` 到您的 `package.json`。如果您使用的是 Sapper 0.29.3 或更高版本，您可以单独执行此步骤，作为增量迁移的一部分。
###
依赖关系
删除 `polka` 或 `express`，如果您使用其中之一，以及任何中间件，如 `sirv` 或 `compression`。
###
开发依赖项
删除您的 `devDependencies` 中的 `sapper`，并用 `@sveltejs/kit` 和您计划使用的任何 [适配器](adapters)（见 [下一节](migrating#Project-files-Configuration)）替换。
###
脚本
任何引用 `sapper` 的脚本都需要更新：
* `` 使用 Node [适配器](adapters)，将 `sapper build` 转换为 `vite build` ``
* `` 使用静态[适配器](adapters)将`将 sapper 导出`转换为`使用 vite 构建` ``
* `سپارک توسعه`应变为`ویت توسعه`
* `node __sapper__/build` 应变为 `node build`
##
项目文件
您的应用程序的大部分代码，在`src/routes`中可以保持不变，但几个项目文件需要移动或更新。
###
配置
您的`webpack.config.js`或`rollup.config.js`应替换为`svelte.config.js`，如文档[此处](configuration)所述。Svelte 预处理器选项应移动到`config.preprocess`。
您需要添加一个[适配器](adapters)。 `sapper build` 大约等同于 [adapter-node](adapter-node)，而 `sapper export` 大约等同于 [adapter-static](adapter-static)，尽管您可能更喜欢使用针对您部署的平台设计的适配器。
如果您正在使用由[Vite](https://vitejs.dev)自动处理的文件类型之外的插件，您将需要找到 Vite 的等效插件并将它们添加到[Vite 配置](project-structure#Project-files-vite.config.js)中。
### src/client.js
此文件在 SvelteKit 中没有等效项。任何超出`sapper.start(...)`的自定义逻辑都应该表达在你的`+layout.svelte`文件中，在`onMount`回调函数内。
### src/server.js
当使用`适配器节点`时，等效的是[自定义服务器](adapter-node#Custom-server)。否则，此文件没有直接等效项，因为 SvelteKit 应用可以在无服务器环境中运行。
### src/service-worker.js
大多数从`@sapper/service-worker`导入的内容在`$service-worker`中有等效项：
* `文件`保持不变
* `路由`已被删除
* `shell` 现在是 `build`
* `时间戳`现在是`版本`
### src/template.html
文件 `src/template.html` 应更名为 `src/app.html`。
删除 `%sapper.base%`，`%sapper.scripts%` 和 `%sapper.styles%`。将 `%sapper.head%` 替换为 `%sveltekit.head%`，并将 `%sapper.html%` 替换为 `%sveltekit.body%`。`<div id="sapper">` 已不再必要。
###
src/节点模块
一个常见的模式是在 Sapper 应用中将您的内部库放在 `src/node_modules` 目录内。这在 Vite 中不适用，所以我们使用 [`src/lib`]($lib) 代替。
##
页面和布局
###
重命名文件
路由现在完全由文件夹名称组成，以消除歧义，直到`+page.svelte`的文件夹名称对应于路由。请参阅[路由文档](routing)以获取概述。以下显示的是新旧比较：
| 旧 | 新 |
| --- | --- |
| routes/about/index.svelte | routes/about/+page.svelte |
| routes/关于.svelte | routes/about/+page.svelte |
您的自定义错误页面组件应从`_error.svelte`重命名为`+error.svelte`。任何`_layout.svelte`文件也应相应重命名为`+layout.svelte`。[其他文件将被忽略](routing#Other-files)。
###
导入
The `goto`、`prefetch` 和 `prefetchRoutes` 从 `@sapper/app` 的导入应分别替换为从 [`$app/navigation`]($app-navigation) 的 `goto`、`preloadData` 和 `preloadCode` 导入。
The `stores` import from `@sapper/app` should be replaced — see the [Stores](migrating#Pages-and-layouts-Stores) section below.
任何您之前从`src/node_modules`目录中导入的文件都需要替换为`$lib`导入。
###
预加载
与之前一样，页面和布局可以导出一个功能，允许在渲染之前加载数据。
此函数已从 `preload` 重命名为 [`load`](load)，现在位于其 `+page.js`（或 `+layout.js`）旁边，紧挨着其 `+page.svelte`（或 `+layout.svelte`），并且其 API 已更改。不再是两个参数——`page` 和 `session`——而是一个 `event` 参数。
没有更多 `此` 对象，因此也没有 `this.fetch`、`this.error` 或 `this.redirect`。相反，您可以从输入方法中获取 [`fetch`](load#Making-fetch-requests)，而 [`error`](load#Errors) 和 [`redirect`](load#Redirects) 现在都会抛出。
###
商店
在 Sapper 中，你会这样获取提供的 store 引用：
```js
// @filename: ambient.d.ts
declare module '@sapper/app';
// @filename: index.js
// ---cut---
import { stores } from '@sapper/app';
const { preloading, page, session } = stores();
```
页面存储仍然存在；`预加载`已被替换为包含`from`和`to`属性的`导航`存储。`页面`现在有`url`和`params`属性，但没有`path`或`query`。
您在 SvelteKit 中访问它们的方式不同。\``stores`\`现在变为\``getStores`\`，但在大多数情况下这是不必要的，因为您可以直接从\`[`$app/stores`]($app-stores)\`导入\``navigating`\`和\``page`\`。如果您使用的是 Svelte 5 和 SvelteKit 2.12 或更高版本，请考虑使用\`[`$app/state`]($app-state)\`代替。
###
路由
正则表达式路由不再受支持。相反，请使用[高级路由匹配](advanced-routing#Matching)。
###
段
之前，布局组件接收一个 `segment` 属性来指示子段。这已被移除；您应使用更灵活的 `$page.url.pathname`（或 `page.url.pathname`）值来获取您感兴趣的段。
### URLs
在 Sapper 中，所有相对 URL 都是相对于基础 URL 解析的——通常是`/`，除非使用了`basepath`选项——而不是相对于当前页面。
这导致了问题，并且在 SvelteKit 中不再是这样。相反，相对 URL 是相对于当前页面（或目标页面，对于在`fetch` URL 中的`load`函数）解析的。在大多数情况下，使用根相对 URL（即以`/`开头）更容易，因为它们的含义不依赖于上下文。
###
<a>属性</a>
* `سپارک:prefetch` 现在是 `data-sveltekit-preload-data`
* `سپارک:noscroll` 现在是 `data-sveltekit-noscroll`
##
端点
在 Sapper 中，[服务器路由](routing#server)接收了 Node 的`http`模块（或 Polka 和 Express 等框架提供的增强版本）暴露的`req`和`res`对象。
SvelteKit 设计为对应用程序运行的位置无感知——它可以在 Node 服务器上运行，但同样也可以在无服务器平台或 Cloudflare Worker 上运行。因此，您不再直接与`req`和`res`交互。您的端点需要更新以匹配新的签名。
为了支持这种环境无关的行为，现在全局上下文中可用 `fetch`，因此您无需导入 `node-fetch`、`cross-fetch` 或类似的服务器端 fetch 实现，即可使用它。
##
集成
查看[集成](./integrations)以获取有关集成的详细信息。
###
HTML 压缩器
Sapper 默认包含 `html-minifier`。SvelteKit 不包含此功能，但您可以将它作为生产依赖项添加，然后通过一个 [钩子](hooks#Server-hooks-handle) 使用它：
```js
// @filename: ambient.d.ts
/// <reference types="@sveltejs/kit" />
declare module 'html-minifier';
// @filename: index.js
// ---cut---
import { minify } from 'html-minifier';
import { building } from '$app/environment';
const minification_options = {
collapseBooleanAttributes: true,
collapseWhitespace: true,
conservativeCollapse: true,
decodeEntities: true,
html5: true,
ignoreCustomComments: [/^#/],
minifyCSS: true,
minifyJS: false,
removeAttributeQuotes: true,
removeComments: false, // some hydration code needs comments, so leave them in
removeOptionalTags: true,
removeRedundantAttributes: true,
removeScriptTypeAttributes: true,
removeStyleLinkTypeAttributes: true,
sortAttributes: true,
sortClassName: true
};
/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
let page = '';
return resolve(event, {
transformPageChunk: ({ html, done }) => {
page += html;
if (done) {
return building ? minify(page, minification_options) : page;
}
}
});
}
```
请注意，当使用 `vit 预览` 测试网站的生成构建时，`预渲染` 为 `false`，因此要验证压缩结果，您需要直接检查构建的 HTML 文件。
# Additional resources
##
常见问题解答
请参阅[SvelteKit 常见问题解答](faq)以获取常见问题的解决方案和有用的技巧。
The [Svelte FAQ](../svelte/faq) 和 [`vite-plugin-svelte` FAQ](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md) 也可能对那些库的问题有所帮助。
##
示例
我们编写并发布了一些不同的 SvelteKit 网站作为示例：
* [`سلتيف`](https://github.com/sveltejs/realworld) 包含一个示例博客网站
* [
黑客新闻克隆](https://github.com/sveltejs/sites/tree/master/sites/hn.svelte.dev)
* [
`https://svelte.dev`](https://github.com/sveltejs/svelte.dev)
SvelteKit 用户还在 GitHub 上发布了大量示例，在[#sveltekit](https://github.com/topics/sveltekit)和[#sveltekit-template](https://github.com/topics/sveltekit-template)主题下，以及[Svelte Society 网站](https://sveltesociety.dev/templates?category=sveltekit)上。请注意，这些示例尚未经过维护者的审核，可能不是最新的。
##
支持
您可以在[Discord](/chat)和[StackOverflow](https://stackoverflow.com/questions/tagged/sveltekit)上寻求帮助。请首先在 FAQ、Google 或另一个搜索引擎、问题跟踪器和 Discord 聊天历史中搜索与您问题相关的信息，以尊重他人的时间。提问的人比回答的人多，这样有助于让社区以可扩展的方式增长。
# Glossary
SvelteKit 的核心提供了一个高度可配置的渲染引擎。本节描述了在讨论渲染时使用的某些术语。上述文档中提供了设置这些选项的参考。
## CSR
客户端渲染（CSR）是使用 JavaScript 在网页浏览器中生成页面内容的过程。
在 SvelteKit 中，默认将使用客户端渲染，但您可以通过[在`csr = false`页面选项](page-options#csr)中关闭 JavaScript。
##
边缘
边缘渲染指的是在靠近用户的内容分发网络（CDN）中运行应用程序。边缘渲染允许页面请求和响应的传输距离更短，从而提高延迟。
##
补水
Svelte 组件存储一些状态，并在状态更新时更新 DOM。在 SSR 期间获取数据时，默认情况下 SvelteKit 会存储这些数据并将其与服务器端渲染的 HTML 一起传输到客户端。然后，组件可以使用这些数据在客户端初始化，而无需再次调用相同的 API 端点。Svelte 将检查 DOM 是否处于预期的状态，并在一个称为“水合”的过程中附加事件监听器。一旦组件完全水合，它们就可以像任何新创建的 Svelte 组件一样对其属性的变化做出反应。
在 SvelteKit 中，页面默认会进行激活，但您可以通过[使用`csr = false`页面选项](page-options#csr)关闭 JavaScript。
## ISR
增量静态再生（ISR）允许您在访客请求页面时生成网站上的静态页面，无需重新部署。这可能与拥有大量页面的[SSG](#SSG)网站相比减少构建时间。您可以使用[ISR 与`adapter-vercel`](adapter-vercel#Incremental-Static-Regeneration)进行。
## MPA
传统应用在服务器上渲染每个页面视图——例如用除 JavaScript 以外的语言编写的应用——通常被称为多页面应用（MPA）。
##
预渲染
预渲染意味着在构建时计算页面内容并保存 HTML 以供显示。这种方法与传统服务器端渲染页面具有相同的优点，但避免了为每位访客重新计算页面，因此随着访客数量的增加，几乎可以免费扩展。代价是构建过程更昂贵，预渲染内容只能通过构建和部署应用程序的新版本来更新。
并非所有页面都可以预渲染。基本规则是：要使内容可预渲染，任何两个直接访问该内容的用户必须从服务器获得相同的内容，并且页面不得包含[操作](form-actions)。请注意，只要所有用户都将看到相同的预渲染内容，您仍然可以预渲染基于页面参数加载的内容。
预渲染页面不仅限于静态内容。如果从客户端获取用户特定数据并渲染，您可以构建个性化页面。但这需要遵守上述讨论的缺点，即不进行服务器端渲染的内容将带来的不利影响。
在 SvelteKit 中，您可以通过[“`prerender`页面选项](page-options#prerender)”和[`prerender`配置](configuration#prerender)在`svelte.config.js`中控制预渲染。
## PWA
一个渐进式 Web 应用（PWA）是一个使用 Web API 和技术构建的应用，但其功能类似于移动或桌面应用。作为 PWA 提供的网站可以被安装，允许您在启动器、主屏幕或开始菜单中添加应用程序的快捷方式。许多 PWA 将利用[服务工作者](service-workers)来构建离线功能。
##
路由
默认情况下，当您导航到新页面（通过点击链接或使用浏览器的前进或后退按钮）时，SvelteKit 将拦截尝试的导航并处理它，而不是允许浏览器向服务器发送请求以获取目标页面。然后，SvelteKit 将通过渲染新页面的组件来更新客户端显示的内容，该组件随后可以调用必要的 API 端点。这种在尝试导航时对客户端页面进行更新的过程称为客户端路由。
在 SvelteKit 中，默认将使用客户端路由，但您可以使用[`data-sveltekit-reload`](link-options#data-sveltekit-reload)来跳过它。
## SPA
单页应用程序（SPA）是一种应用程序，其中所有对服务器的请求都加载单个 HTML 文件，然后根据请求的 URL 在客户端对请求的内容进行渲染。所有导航都在客户端通过称为客户端路由的过程处理，每页内容更新，而常见布局元素基本保持不变。SPA 不提供 SSR，因此性能和 SEO 特性较差。然而，一些应用程序受这些缺点的影响不大，例如登录后的复杂业务应用程序，其中 SEO 可能不是很重要，并且已知用户将从一致的计算环境中访问应用程序。
在 SvelteKit 中，您可以使用[adapter-static](single-page-apps)构建一个 SPA。
## SSG
静态站点生成（SSG）是指每个页面都预先渲染的网站。完全预先渲染站点的优点是您不需要维护或支付服务器以执行 SSR。一旦生成，网站可以从 CDN 提供服务，从而实现出色的“首次字节时间”性能。这种交付模式通常被称为 JAMstack。
在 SvelteKit 中，您可以通过使用`adapter-static`或通过配置每个页面使用`prerender`页面选项或`prerender`配置来预渲染，在`svelte.config.js`中实现静态站点生成。
## SSR
服务器端渲染（SSR）是在服务器上生成页面内容。SSR 通常更受 SEO 青睐。虽然一些搜索引擎可以索引客户端动态生成的内容，即使在这些情况下，也可能需要更长的时间。它还倾向于提高感知性能，并在 JavaScript 失败或禁用时使您的应用对用户可用（这种情况比您可能想象的要常见）。
在 SvelteKit 中，页面默认由服务器端渲染。您可以通过[在`ssr`页面选项](page-options#ssr)中禁用 SSR。
# @sveltejs/kit
```js
// @noErrors
import {
Server,
VERSION,
error,
fail,
isActionFailure,
isHttpError,
isRedirect,
json,
normalizeUrl,
redirect,
text
} from '@sveltejs/kit';
```
## Server
<div class="ts-block">
```dts
class Server {/*…*/}
```
<div class="ts-block-property">
```dts
constructor(manifest: SSRManifest);
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
init(options: ServerInitOptions): Promise<void>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
respond(request: Request, options: RequestOptions): Promise<Response>;
```
<div class="ts-block-property-details"></div>
</div></div>
## VERSION
<div class="ts-block">
```dts
const VERSION: string;
```
</div>
## error
Throws an error with a HTTP status code and an optional message.
When called during request handling, this will cause SvelteKit to
return an error response without invoking `handleError`.
Make sure you're not catching the thrown error, which would prevent SvelteKit from handling it.
<div class="ts-block">
```dts
function error(status: number, body: App.Error): never;
```
</div>
<div class="ts-block">
```dts
function error(
status: number,
body?: {
message: string;
} extends App.Error
? App.Error | string | undefined
: never
): never;
```
</div>
## fail
Create an `ActionFailure` object. Call when form submission fails.
<div class="ts-block">
```dts
function fail(status: number): ActionFailure<undefined>;
```
</div>
<div class="ts-block">
```dts
function fail<
T extends Record<string, unknown> | undefined = undefined
>(status: number, data: T): ActionFailure<T>;
```
</div>
## isActionFailure
Checks whether this is an action failure thrown by `fail`.
<div class="ts-block">
```dts
function isActionFailure(e: unknown): e is ActionFailure;
```
</div>
## isHttpError
Checks whether this is an error thrown by `error`.
<div class="ts-block">
```dts
function isHttpError<T extends number>(
e: unknown,
status?: T | undefined
): e is HttpError_1 & {
status: T extends undefined ? never : T;
};
```
</div>
## isRedirect
Checks whether this is a redirect thrown by `redirect`.
<div class="ts-block">
```dts
function isRedirect(e: unknown): e is Redirect_1;
```
</div>
## json
Create a JSON `Response` object from the supplied data.
<div class="ts-block">
```dts
function json(
data: any,
init?: ResponseInit | undefined
): Response;
```
</div>
## normalizeUrl
<blockquote class="since note">
Available since 2.18.0
</blockquote>
Strips possible SvelteKit-internal suffixes and trailing slashes from the URL pathname.
Returns the normalized URL as well as a method for adding the potential suffix back
based on a new pathname (possibly including search) or URL.
```js
// @errors: 7031
import { normalizeUrl } from '@sveltejs/kit';
const { url, denormalize } = normalizeUrl('/blog/post/__data.json');
console.log(url.pathname); // /blog/post
console.log(denormalize('/blog/post/a')); // /blog/post/a/__data.json
```
<div class="ts-block">
```dts
function normalizeUrl(url: URL | string): {
url: URL;
wasNormalized: boolean;
denormalize: (url?: string | URL) => URL;
};
```
</div>
## redirect
Redirect a request. When called during request handling, SvelteKit will return a redirect response.
Make sure you're not catching the thrown redirect, which would prevent SvelteKit from handling it.
Most common status codes:
* `303 See Other`: redirect as a GET request (often used after a form POST request)
* `307 Temporary Redirect`: redirect will keep the request method
* `308 Permanent Redirect`: redirect will keep the request method, SEO will be transferred to the new page
[See all redirect status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages)
<div class="ts-block">
```dts
function redirect(
status:
| 300
| 301
| 302
| 303
| 304
| 305
| 306
| 307
| 308
| ({} & number),
location: string | URL
): never;
```
</div>
## text
Create a `Response` object from the supplied body.
<div class="ts-block">
```dts
function text(
body: string,
init?: ResponseInit | undefined
): Response;
```
</div>
## Action
Shape of a form action method that is part of `export const actions = {...}` in `+page.server.js`.
See [form actions](/docs/kit/form-actions) for more information.
<div class="ts-block">
```dts
type Action<
Params extends Partial<Record<string, string>> = Partial<
Record<string, string>
>,
OutputData extends Record<string, any> | void = Record<
string,
any
> | void,
RouteId extends string | null = string | null
> = (
event: RequestEvent<Params, RouteId>
) => MaybePromise<OutputData>;
```
</div>
## ActionFailure
<div class="ts-block">
```dts
interface ActionFailure<
T extends Record<string, unknown> | undefined = undefined
> {/*…*/}
```
<div class="ts-block-property">
```dts
status: number;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
data: T;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
[uniqueSymbol]: true;
```
<div class="ts-block-property-details"></div>
</div></div>
## ActionResult
When calling a form action via fetch, the response will be one of these shapes.
```svelte
<form method="post" use:enhance={() => {
return ({ result }) => {
// result is of type ActionResult
};
}}
```
<div class="ts-block">
```dts
type ActionResult<
Success extends
| Record<string, unknown>
| undefined = Record<string, any>,
Failure extends
| Record<string, unknown>
| undefined = Record<string, any>
> =
| { type: 'success'; status: number; data?: Success }
| { type: 'failure'; status: number; data?: Failure }
| { type: 'redirect'; status: number; location: string }
| { type: 'error'; status?: number; error: any };
```
</div>
## Actions
Shape of the `export const actions = {...}` object in `+page.server.js`.
See [form actions](/docs/kit/form-actions) for more information.
<div class="ts-block">
```dts
type Actions<
Params extends Partial<Record<string, string>> = Partial<
Record<string, string>
>,
OutputData extends Record<string, any> | void = Record<
string,
any
> | void,
RouteId extends string | null = string | null
> = Record<string, Action<Params, OutputData, RouteId>>;
```
</div>
## Adapter
[Adapters](/docs/kit/adapters) are responsible for taking the production build and turning it into something that can be deployed to a platform of your choosing.
<div class="ts-block">
```dts
interface Adapter {/*…*/}
```
<div class="ts-block-property">
```dts
name: string;
```
<div class="ts-block-property-details">
The name of the adapter, using for logging. Will typically correspond to the package name.
</div>
</div>
<div class="ts-block-property">
```dts
adapt: (builder: Builder) => MaybePromise<void>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `builder` An object provided by SvelteKit that contains methods for adapting the app
</div>
This function is called after SvelteKit has built your app.
</div>
</div>
<div class="ts-block-property">
```dts
supports?: {/*…*/}
```
<div class="ts-block-property-details">
Checks called during dev and build to determine whether specific features will work in production with this adapter.
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
read?: (details: { config: any; route: { id: string } }) => boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `details.config` The merged route config
</div>
Test support for `read` from `$app/server`.
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```dts
emulate?: () => MaybePromise<Emulator>;
```
<div class="ts-block-property-details">
Creates an `Emulator`, which allows the adapter to influence the environment
during dev, build and prerendering.
</div>
</div></div>
## AfterNavigate
The argument passed to [`afterNavigate`](/docs/kit/$app-navigation#afterNavigate) callbacks.
<div class="ts-block">
```dts
interface AfterNavigate extends Omit<Navigation, 'type'> {/*…*/}
```
<div class="ts-block-property">
```dts
type: Exclude<NavigationType, 'leave'>;
```
<div class="ts-block-property-details">
The type of navigation:
- `enter`: The app has hydrated/started
- `form`: The user submitted a `<form>`
- `link`: Navigation was triggered by a link click
- `goto`: Navigation was triggered by a `goto(...)` call or a redirect
- `popstate`: Navigation was triggered by back/forward navigation
</div>
</div>
<div class="ts-block-property">
```dts
willUnload: false;
```
<div class="ts-block-property-details">
Since `afterNavigate` callbacks are called after a navigation completes, they will never be called with a navigation that unloads the page.
</div>
</div></div>
## AwaitedActions
<div class="ts-block">
```dts
type AwaitedActions<
T extends Record<string, (...args: any) => any>
> = OptionalUnion<
{
[Key in keyof T]: UnpackValidationError<
Awaited<ReturnType<T[Key]>>
>;
}[keyof T]
>;
```
</div>
## BeforeNavigate
The argument passed to [`beforeNavigate`](/docs/kit/$app-navigation#beforeNavigate) callbacks.
<div class="ts-block">
```dts
interface BeforeNavigate extends Navigation {/*…*/}
```
<div class="ts-block-property">
```dts
cancel: () => void;
```
<div class="ts-block-property-details">
Call this to prevent the navigation from starting.
</div>
</div></div>
## Builder
This object is passed to the `adapt` function of adapters.
It contains various methods and properties that are useful for adapting the app.
<div class="ts-block">
```dts
interface Builder {/*…*/}
```
<div class="ts-block-property">
```dts
log: Logger;
```
<div class="ts-block-property-details">
Print messages to the console. `log.info` and `log.minor` are silent unless Vite's `logLevel` is `info`.
</div>
</div>
<div class="ts-block-property">
```dts
rimraf: (dir: string) => void;
```
<div class="ts-block-property-details">
Remove `dir` and all its contents.
</div>
</div>
<div class="ts-block-property">
```dts
mkdirp: (dir: string) => void;
```
<div class="ts-block-property-details">
Create `dir` and any required parent directories.
</div>
</div>
<div class="ts-block-property">
```dts
config: ValidatedConfig;
```
<div class="ts-block-property-details">
The fully resolved Svelte config.
</div>
</div>
<div class="ts-block-property">
```dts
prerendered: Prerendered;
```
<div class="ts-block-property-details">
Information about prerendered pages and assets, if any.
</div>
</div>
<div class="ts-block-property">
```dts
routes: RouteDefinition[];
```
<div class="ts-block-property-details">
An array of all routes (including prerendered)
</div>
</div>
<div class="ts-block-property">
```dts
createEntries: (fn: (route: RouteDefinition) => AdapterEntry) => Promise<void>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `fn` A function that groups a set of routes into an entry point
- <span class="tag deprecated">deprecated</span> Use `builder.routes` instead
</div>
Create separate functions that map to one or more routes of your app.
</div>
</div>
<div class="ts-block-property">
```dts
findServerAssets: (routes: RouteDefinition[]) => string[];
```
<div class="ts-block-property-details">
Find all the assets imported by server files belonging to `routes`
</div>
</div>
<div class="ts-block-property">
```dts
generateFallback: (dest: string) => Promise<void>;
```
<div class="ts-block-property-details">
Generate a fallback page for a static webserver to use when no route is matched. Useful for single-page apps.
</div>
</div>
<div class="ts-block-property">
```dts
generateEnvModule: () => void;
```
<div class="ts-block-property-details">
Generate a module exposing build-time environment variables as `$env/dynamic/public`.
</div>
</div>
<div class="ts-block-property">
```dts
generateManifest: (opts: { relativePath: string; routes?: RouteDefinition[] }) => string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `opts` a relative path to the base directory of the app and optionally in which format (esm or cjs) the manifest should be generated
</div>
Generate a server-side manifest to initialise the SvelteKit [server](/docs/kit/@sveltejs-kit#Server) with.
</div>
</div>
<div class="ts-block-property">
```dts
getBuildDirectory: (name: string) => string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `name` path to the file, relative to the build directory
</div>
Resolve a path to the `name` directory inside `outDir`, e.g. `/path/to/.svelte-kit/my-adapter`.
</div>
</div>
<div class="ts-block-property">
```dts
getClientDirectory: () => string;
```
<div class="ts-block-property-details">
Get the fully resolved path to the directory containing client-side assets, including the contents of your `static` directory.
</div>
</div>
<div class="ts-block-property">
```dts
getServerDirectory: () => string;
```
<div class="ts-block-property-details">
Get the fully resolved path to the directory containing server-side code.
</div>
</div>
<div class="ts-block-property">
```dts
getAppPath: () => string;
```
<div class="ts-block-property-details">
Get the application path including any configured `base` path, e.g. `my-base-path/_app`.
</div>
</div>
<div class="ts-block-property">
```dts
writeClient: (dest: string) => string[];
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `dest` the destination folder
- <span class="tag">returns</span> an array of files written to `dest`
</div>
Write client assets to `dest`.
</div>
</div>
<div class="ts-block-property">
```dts
writePrerendered: (dest: string) => string[];
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `dest` the destination folder
- <span class="tag">returns</span> an array of files written to `dest`
</div>
Write prerendered files to `dest`.
</div>
</div>
<div class="ts-block-property">
```dts
writeServer: (dest: string) => string[];
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `dest` the destination folder
- <span class="tag">returns</span> an array of files written to `dest`
</div>
Write server-side code to `dest`.
</div>
</div>
<div class="ts-block-property">
```dts
copy: (
from: string,
to: string,
opts?: {
filter?(basename: string): boolean;
replace?: Record<string, string>;
}
) => string[];
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `from` the source file or directory
- `to` the destination file or directory
- `opts.filter` a function to determine whether a file or directory should be copied
- `opts.replace` a map of strings to replace
- <span class="tag">returns</span> an array of files that were copied
</div>
Copy a file or directory.
</div>
</div>
<div class="ts-block-property">
```dts
compress: (directory: string) => Promise<void>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `directory` The directory containing the files to be compressed
</div>
Compress files in `directory` with gzip and brotli, where appropriate. Generates `.gz` and `.br` files alongside the originals.
</div>
</div></div>
## ClientInit
<blockquote class="since note">
Available since 2.10.0
</blockquote>
The [`init`](/docs/kit/hooks#Shared-hooks-init) will be invoked once the app starts in the browser
<div class="ts-block">
```dts
type ClientInit = () => MaybePromise<void>;
```
</div>
## Config
See the [configuration reference](/docs/kit/configuration) for details.
## Cookies
<div class="ts-block">
```dts
interface Cookies {/*…*/}
```
<div class="ts-block-property">
```dts
get: (name: string, opts?: import('cookie').CookieParseOptions) => string | undefined;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `name` the name of the cookie
- `opts` the options, passed directly to `cookie.parse`. See documentation [here](https://github.com/jshttp/cookie#cookieparsestr-options)
</div>
Gets a cookie that was previously set with `cookies.set`, or from the request headers.
</div>
</div>
<div class="ts-block-property">
```dts
getAll: (opts?: import('cookie').CookieParseOptions) => Array<{ name: string; value: string }>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `opts` the options, passed directly to `cookie.parse`. See documentation [here](https://github.com/jshttp/cookie#cookieparsestr-options)
</div>
Gets all cookies that were previously set with `cookies.set`, or from the request headers.
</div>
</div>
<div class="ts-block-property">
```dts
set: (
name: string,
value: string,
opts: import('cookie').CookieSerializeOptions & { path: string }
) => void;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `name` the name of the cookie
- `value` the cookie value
- `opts` the options, passed directly to `cookie.serialize`. See documentation [here](https://github.com/jshttp/cookie#cookieserializename-value-options)
</div>
Sets a cookie. This will add a `set-cookie` header to the response, but also make the cookie available via `cookies.get` or `cookies.getAll` during the current request.
The `httpOnly` and `secure` options are `true` by default (except on http://localhost, where `secure` is `false`), and must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP. The `sameSite` option defaults to `lax`.
You must specify a `path` for the cookie. In most cases you should explicitly set `path: '/'` to make the cookie available throughout your app. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children
</div>
</div>
<div class="ts-block-property">
```dts
delete: (name: string, opts: import('cookie').CookieSerializeOptions & { path: string }) => void;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `name` the name of the cookie
- `opts` the options, passed directly to `cookie.serialize`. The `path` must match the path of the cookie you want to delete. See documentation [here](https://github.com/jshttp/cookie#cookieserializename-value-options)
</div>
Deletes a cookie by setting its value to an empty string and setting the expiry date in the past.
You must specify a `path` for the cookie. In most cases you should explicitly set `path: '/'` to make the cookie available throughout your app. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children
</div>
</div>
<div class="ts-block-property">
```dts
serialize: (
name: string,
value: string,
opts: import('cookie').CookieSerializeOptions & { path: string }
) => string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `name` the name of the cookie
- `value` the cookie value
- `opts` the options, passed directly to `cookie.serialize`. See documentation [here](https://github.com/jshttp/cookie#cookieserializename-value-options)
</div>
Serialize a cookie name-value pair into a `Set-Cookie` header string, but don't apply it to the response.
The `httpOnly` and `secure` options are `true` by default (except on http://localhost, where `secure` is `false`), and must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP. The `sameSite` option defaults to `lax`.
You must specify a `path` for the cookie. In most cases you should explicitly set `path: '/'` to make the cookie available throughout your app. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children
</div>
</div></div>
## Emulator
A collection of functions that influence the environment during dev, build and prerendering
<div class="ts-block">
```dts
interface Emulator {/*…*/}
```
<div class="ts-block-property">
```dts
platform?(details: { config: any; prerender: PrerenderOption }): MaybePromise<App.Platform>;
```
<div class="ts-block-property-details">
A function that is called with the current route `config` and `prerender` option
and returns an `App.Platform` object
</div>
</div></div>
## Handle
The [`handle`](/docs/kit/hooks#Server-hooks-handle) hook runs every time the SvelteKit server receives a [request](/docs/kit/web-standards#Fetch-APIs-Request) and
determines the [response](/docs/kit/web-standards#Fetch-APIs-Response).
It receives an `event` object representing the request and a function called `resolve`, which renders the route and generates a `Response`.
This allows you to modify response headers or bodies, or bypass SvelteKit entirely (for implementing routes programmatically, for example).
<div class="ts-block">
```dts
type Handle = (input: {
event: RequestEvent;
resolve: (
event: RequestEvent,
opts?: ResolveOptions
) => MaybePromise<Response>;
}) => MaybePromise<Response>;
```
</div>
## HandleClientError
The client-side [`handleError`](/docs/kit/hooks#Shared-hooks-handleError) hook runs when an unexpected error is thrown while navigating.
If an unexpected error is thrown during loading or the following render, this function will be called with the error and the event.
Make sure that this function _never_ throws an error.
<div class="ts-block">
```dts
type HandleClientError = (input: {
error: unknown;
event: NavigationEvent;
status: number;
message: string;
}) => MaybePromise<void | App.Error>;
```
</div>
## HandleFetch
The [`handleFetch`](/docs/kit/hooks#Server-hooks-handleFetch) hook allows you to modify (or replace) the result of an [`event.fetch`](/docs/kit/load#Making-fetch-requests) call that runs on the server (or during prerendering) inside an endpoint, `load`, `action`, `handle`, `handleError` or `reroute`.
<div class="ts-block">
```dts
type HandleFetch = (input: {
event: RequestEvent;
request: Request;
fetch: typeof fetch;
}) => MaybePromise<Response>;
```
</div>
## HandleServerError
The server-side [`handleError`](/docs/kit/hooks#Shared-hooks-handleError) hook runs when an unexpected error is thrown while responding to a request.
If an unexpected error is thrown during loading or rendering, this function will be called with the error and the event.
Make sure that this function _never_ throws an error.
<div class="ts-block">
```dts
type HandleServerError = (input: {
error: unknown;
event: RequestEvent;
status: number;
message: string;
}) => MaybePromise<void | App.Error>;
```
</div>
## HttpError
The object returned by the [`error`](/docs/kit/@sveltejs-kit#error) function.
<div class="ts-block">
```dts
interface HttpError {/*…*/}
```
<div class="ts-block-property">
```dts
status: number;
```
<div class="ts-block-property-details">
The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses), in the range 400-599.
</div>
</div>
<div class="ts-block-property">
```dts
body: App.Error;
```
<div class="ts-block-property-details">
The content of the error.
</div>
</div></div>
## KitConfig
See the [configuration reference](/docs/kit/configuration) for details.
## LessThan
<div class="ts-block">
```dts
type LessThan<
TNumber extends number,
TArray extends any[] = []
> = TNumber extends TArray['length']
? TArray[number]
: LessThan<TNumber, [...TArray, TArray['length']]>;
```
</div>
## Load
The generic form of `PageLoad` and `LayoutLoad`. You should import those from `./$types` (see [generated types](/docs/kit/types#Generated-types))
rather than using `Load` directly.
<div class="ts-block">
```dts
type Load<
Params extends Partial<Record<string, string>> = Partial<
Record<string, string>
>,
InputData extends Record<string, unknown> | null = Record<
string,
any
> | null,
ParentData extends Record<string, unknown> = Record<
string,
any
>,
OutputData extends Record<
string,
unknown
> | void = Record<string, any> | void,
RouteId extends string | null = string | null
> = (
event: LoadEvent<Params, InputData, ParentData, RouteId>
) => MaybePromise<OutputData>;
```
</div>
## LoadEvent
The generic form of `PageLoadEvent` and `LayoutLoadEvent`. You should import those from `./$types` (see [generated types](/docs/kit/types#Generated-types))
rather than using `LoadEvent` directly.
<div class="ts-block">
```dts
interface LoadEvent<
Params extends Partial<Record<string, string>> = Partial<
Record<string, string>
>,
Data extends Record<string, unknown> | null = Record<
string,
any
> | null,
ParentData extends Record<string, unknown> = Record<
string,
any
>,
RouteId extends string | null = string | null
> extends NavigationEvent<Params, RouteId> {/*…*/}
```
<div class="ts-block-property">
```dts
fetch: typeof fetch;
```
<div class="ts-block-property-details">
`fetch` is equivalent to the [native `fetch` web API](https://developer.mozilla.org/en-US/docs/Web/API/fetch), with a few additional features:
- It can be used to make credentialed requests on the server, as it inherits the `cookie` and `authorization` headers for the page request.
- It can make relative requests on the server (ordinarily, `fetch` requires a URL with an origin when used in a server context).
- Internal requests (e.g. for `+server.js` routes) go directly to the handler function when running on the server, without the overhead of an HTTP call.
- During server-side rendering, the response will be captured and inlined into the rendered HTML by hooking into the `text` and `json` methods of the `Response` object. Note that headers will _not_ be serialized, unless explicitly included via [`filterSerializedResponseHeaders`](/docs/kit/hooks#Server-hooks-handle)
- During hydration, the response will be read from the HTML, guaranteeing consistency and preventing an additional network request.
You can learn more about making credentialed requests with cookies [here](/docs/kit/load#Cookies)
</div>
</div>
<div class="ts-block-property">
```dts
data: Data;
```
<div class="ts-block-property-details">
Contains the data returned by the route's server `load` function (in `+layout.server.js` or `+page.server.js`), if any.
</div>
</div>
<div class="ts-block-property">
```dts
setHeaders: (headers: Record<string, string>) => void;
```
<div class="ts-block-property-details">
If you need to set headers for the response, you can do so using the this method. This is useful if you want the page to be cached, for example:
```js
// @errors: 7031
/// file: src/routes/blog/+page.js
export async function load({ fetch, setHeaders }) {
const url = `https://cms.example.com/articles.json`;
const response = await fetch(url);
setHeaders({
age: response.headers.get('age'),
'cache-control': response.headers.get('cache-control')
});
return response.json();
}
```
Setting the same header multiple times (even in separate `load` functions) is an error — you can only set a given header once.
You cannot add a `set-cookie` header with `setHeaders` — use the [`cookies`](/docs/kit/@sveltejs-kit#Cookies) API in a server-only `load` function instead.
`setHeaders` has no effect when a `load` function runs in the browser.
</div>
</div>
<div class="ts-block-property">
```dts
parent: () => Promise<ParentData>;
```
<div class="ts-block-property-details">
`await parent()` returns data from parent `+layout.js` `load` functions.
Implicitly, a missing `+layout.js` is treated as a `({ data }) => data` function, meaning that it will return and forward data from parent `+layout.server.js` files.
Be careful not to introduce accidental waterfalls when using `await parent()`. If for example you only want to merge parent data into the returned output, call it _after_ fetching your other data.
</div>
</div>
<div class="ts-block-property">
```dts
depends: (...deps: Array<`${string}:${string}`>) => void;
```
<div class="ts-block-property-details">
This function declares that the `load` function has a _dependency_ on one or more URLs or custom identifiers, which can subsequently be used with [`invalidate()`](/docs/kit/$app-navigation#invalidate) to cause `load` to rerun.
Most of the time you won't need this, as `fetch` calls `depends` on your behalf — it's only necessary if you're using a custom API client that bypasses `fetch`.
URLs can be absolute or relative to the page being loaded, and must be [encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding).
Custom identifiers have to be prefixed with one or more lowercase letters followed by a colon to conform to the [URI specification](https://www.rfc-editor.org/rfc/rfc3986.html).
The following example shows how to use `depends` to register a dependency on a custom identifier, which is `invalidate`d after a button click, making the `load` function rerun.
```js
// @errors: 7031
/// file: src/routes/+page.js
let count = 0;
export async function load({ depends }) {
depends('increase:count');
return { count: count++ };
}
```
```html
/// file: src/routes/+page.svelte
<script>
import { invalidate } from '$app/navigation';
let { data } = $props();
const increase = async () => {
await invalidate('increase:count');
}
</script>
<p>{data.count}<p>
<button on:click={increase}>Increase Count</button>
```
</div>
</div>
<div class="ts-block-property">
```dts
untrack: <T>(fn: () => T) => T;
```
<div class="ts-block-property-details">
Use this function to opt out of dependency tracking for everything that is synchronously called within the callback. Example:
```js
// @errors: 7031
/// file: src/routes/+page.server.js
export async function load({ untrack, url }) {
// Untrack url.pathname so that path changes don't trigger a rerun
if (untrack(() => url.pathname === '/')) {
return { message: 'Welcome!' };
}
}
```
</div>
</div></div>
## LoadProperties
<div class="ts-block">
```dts
type LoadProperties<
input extends Record<string, any> | void
> = input extends void
? undefined // needs to be undefined, because void will break intellisense
: input extends Record<string, any>
? input
: unknown;
```
</div>
## Navigation
<div class="ts-block">
```dts
interface Navigation {/*…*/}
```
<div class="ts-block-property">
```dts
from: NavigationTarget | null;
```
<div class="ts-block-property-details">
Where navigation was triggered from
</div>
</div>
<div class="ts-block-property">
```dts
to: NavigationTarget | null;
```
<div class="ts-block-property-details">
Where navigation is going to/has gone to
</div>
</div>
<div class="ts-block-property">
```dts
type: Exclude<NavigationType, 'enter'>;
```
<div class="ts-block-property-details">
The type of navigation:
- `form`: The user submitted a `<form>`
- `leave`: The app is being left either because the tab is being closed or a navigation to a different document is occurring
- `link`: Navigation was triggered by a link click
- `goto`: Navigation was triggered by a `goto(...)` call or a redirect
- `popstate`: Navigation was triggered by back/forward navigation
</div>
</div>
<div class="ts-block-property">
```dts
willUnload: boolean;
```
<div class="ts-block-property-details">
Whether or not the navigation will result in the page being unloaded (i.e. not a client-side navigation)
</div>
</div>
<div class="ts-block-property">
```dts
delta?: number;
```
<div class="ts-block-property-details">
In case of a history back/forward navigation, the number of steps to go back/forward
</div>
</div>
<div class="ts-block-property">
```dts
complete: Promise<void>;
```
<div class="ts-block-property-details">
A promise that resolves once the navigation is complete, and rejects if the navigation
fails or is aborted. In the case of a `willUnload` navigation, the promise will never resolve
</div>
</div></div>
## NavigationEvent
<div class="ts-block">
```dts
interface NavigationEvent<
Params extends Partial<Record<string, string>> = Partial<
Record<string, string>
>,
RouteId extends string | null = string | null
> {/*…*/}
```
<div class="ts-block-property">
```dts
params: Params;
```
<div class="ts-block-property-details">
The parameters of the current page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object
</div>
</div>
<div class="ts-block-property">
```dts
route: {/*…*/}
```
<div class="ts-block-property-details">
Info about the current route
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
id: RouteId;
```
<div class="ts-block-property-details">
The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]`. It is `null` when no route is matched.
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```dts
url: URL;
```
<div class="ts-block-property-details">
The URL of the current page
</div>
</div></div>
## NavigationTarget
Information about the target of a specific navigation.
<div class="ts-block">
```dts
interface NavigationTarget {/*…*/}
```
<div class="ts-block-property">
```dts
params: Record<string, string> | null;
```
<div class="ts-block-property-details">
Parameters of the target page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object.
Is `null` if the target is not part of the SvelteKit app (could not be resolved to a route).
</div>
</div>
<div class="ts-block-property">
```dts
route: {/*…*/}
```
<div class="ts-block-property-details">
Info about the target route
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
id: string | null;
```
<div class="ts-block-property-details">
The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]`. It is `null` when no route is matched.
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```dts
url: URL;
```
<div class="ts-block-property-details">
The URL that is navigated to
</div>
</div></div>
## NavigationType
- `enter`: The app has hydrated/started
- `form`: The user submitted a `<form>` with a GET method
- `leave`: The user is leaving the app by closing the tab or using the back/forward buttons to go to a different document
- `link`: Navigation was triggered by a link click
- `goto`: Navigation was triggered by a `goto(...)` call or a redirect
- `popstate`: Navigation was triggered by back/forward navigation
<div class="ts-block">
```dts
type NavigationType =
| 'enter'
| 'form'
| 'leave'
| 'link'
| 'goto'
| 'popstate';
```
</div>
## NumericRange
<div class="ts-block">
```dts
type NumericRange<
TStart extends number,
TEnd extends number
> = Exclude<TEnd | LessThan<TEnd>, LessThan<TStart>>;
```
</div>
## OnNavigate
The argument passed to [`onNavigate`](/docs/kit/$app-navigation#onNavigate) callbacks.
<div class="ts-block">
```dts
interface OnNavigate extends Navigation {/*…*/}
```
<div class="ts-block-property">
```dts
type: Exclude<NavigationType, 'enter' | 'leave'>;
```
<div class="ts-block-property-details">
The type of navigation:
- `form`: The user submitted a `<form>`
- `link`: Navigation was triggered by a link click
- `goto`: Navigation was triggered by a `goto(...)` call or a redirect
- `popstate`: Navigation was triggered by back/forward navigation
</div>
</div>
<div class="ts-block-property">
```dts
willUnload: false;
```
<div class="ts-block-property-details">
Since `onNavigate` callbacks are called immediately before a client-side navigation, they will never be called with a navigation that unloads the page.
</div>
</div></div>
## Page
The shape of the [`page`](/docs/kit/$app-state#page) reactive object and the [`$page`](/docs/kit/$app-stores) store.
<div class="ts-block">
```dts
interface Page<
Params extends Record<string, string> = Record<
string,
string
>,
RouteId extends string | null = string | null
> {/*…*/}
```
<div class="ts-block-property">
```dts
url: URL;
```
<div class="ts-block-property-details">
The URL of the current page.
</div>
</div>
<div class="ts-block-property">
```dts
params: Params;
```
<div class="ts-block-property-details">
The parameters of the current page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object.
</div>
</div>
<div class="ts-block-property">
```dts
route: {/*…*/}
```
<div class="ts-block-property-details">
Info about the current route.
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
id: RouteId;
```
<div class="ts-block-property-details">
The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]`. It is `null` when no route is matched.
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```dts
status: number;
```
<div class="ts-block-property-details">
HTTP status code of the current page.
</div>
</div>
<div class="ts-block-property">
```dts
error: App.Error | null;
```
<div class="ts-block-property-details">
The error object of the current page, if any. Filled from the `handleError` hooks.
</div>
</div>
<div class="ts-block-property">
```dts
data: App.PageData & Record<string, any>;
```
<div class="ts-block-property-details">
The merged result of all data from all `load` functions on the current page. You can type a common denominator through `App.PageData`.
</div>
</div>
<div class="ts-block-property">
```dts
state: App.PageState;
```
<div class="ts-block-property-details">
The page state, which can be manipulated using the [`pushState`](/docs/kit/$app-navigation#pushState) and [`replaceState`](/docs/kit/$app-navigation#replaceState) functions from `$app/navigation`.
</div>
</div>
<div class="ts-block-property">
```dts
form: any;
```
<div class="ts-block-property-details">
Filled only after a form submission. See [form actions](/docs/kit/form-actions) for more info.
</div>
</div></div>
## ParamMatcher
The shape of a param matcher. See [matching](/docs/kit/advanced-routing#Matching) for more info.
<div class="ts-block">
```dts
type ParamMatcher = (param: string) => boolean;
```
</div>
## PrerenderOption
<div class="ts-block">
```dts
type PrerenderOption = boolean | 'auto';
```
</div>
## Redirect
The object returned by the [`redirect`](/docs/kit/@sveltejs-kit#redirect) function.
<div class="ts-block">
```dts
interface Redirect {/*…*/}
```
<div class="ts-block-property">
```dts
status: 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308;
```
<div class="ts-block-property-details">
The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages), in the range 300-308.
</div>
</div>
<div class="ts-block-property">
```dts
location: string;
```
<div class="ts-block-property-details">
The location to redirect to.
</div>
</div></div>
## RequestEvent
<div class="ts-block">
```dts
interface RequestEvent<
Params extends Partial<Record<string, string>> = Partial<
Record<string, string>
>,
RouteId extends string | null = string | null
> {/*…*/}
```
<div class="ts-block-property">
```dts
cookies: Cookies;
```
<div class="ts-block-property-details">
Get or set cookies related to the current request
</div>
</div>
<div class="ts-block-property">
```dts
fetch: typeof fetch;
```
<div class="ts-block-property-details">
`fetch` is equivalent to the [native `fetch` web API](https://developer.mozilla.org/en-US/docs/Web/API/fetch), with a few additional features:
- It can be used to make credentialed requests on the server, as it inherits the `cookie` and `authorization` headers for the page request.
- It can make relative requests on the server (ordinarily, `fetch` requires a URL with an origin when used in a server context).
- Internal requests (e.g. for `+server.js` routes) go directly to the handler function when running on the server, without the overhead of an HTTP call.
- During server-side rendering, the response will be captured and inlined into the rendered HTML by hooking into the `text` and `json` methods of the `Response` object. Note that headers will _not_ be serialized, unless explicitly included via [`filterSerializedResponseHeaders`](/docs/kit/hooks#Server-hooks-handle)
- During hydration, the response will be read from the HTML, guaranteeing consistency and preventing an additional network request.
You can learn more about making credentialed requests with cookies [here](/docs/kit/load#Cookies).
</div>
</div>
<div class="ts-block-property">
```dts
getClientAddress: () => string;
```
<div class="ts-block-property-details">
The client's IP address, set by the adapter.
</div>
</div>
<div class="ts-block-property">
```dts
locals: App.Locals;
```
<div class="ts-block-property-details">
Contains custom data that was added to the request within the [`server handle hook`](/docs/kit/hooks#Server-hooks-handle).
</div>
</div>
<div class="ts-block-property">
```dts
params: Params;
```
<div class="ts-block-property-details">
The parameters of the current route - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object.
</div>
</div>
<div class="ts-block-property">
```dts
platform: Readonly<App.Platform> | undefined;
```
<div class="ts-block-property-details">
Additional data made available through the adapter.
</div>
</div>
<div class="ts-block-property">
```dts
request: Request;
```
<div class="ts-block-property-details">
The original request object.
</div>
</div>
<div class="ts-block-property">
```dts
route: {/*…*/}
```
<div class="ts-block-property-details">
Info about the current route.
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
id: RouteId;
```
<div class="ts-block-property-details">
The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]`. It is `null` when no route is matched.
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```dts
setHeaders: (headers: Record<string, string>) => void;
```
<div class="ts-block-property-details">
If you need to set headers for the response, you can do so using the this method. This is useful if you want the page to be cached, for example:
```js
// @errors: 7031
/// file: src/routes/blog/+page.js
export async function load({ fetch, setHeaders }) {
const url = `https://cms.example.com/articles.json`;
const response = await fetch(url);
setHeaders({
age: response.headers.get('age'),
'cache-control': response.headers.get('cache-control')
});
return response.json();
}
```
Setting the same header multiple times (even in separate `load` functions) is an error — you can only set a given header once.
You cannot add a `set-cookie` header with `setHeaders` — use the [`cookies`](/docs/kit/@sveltejs-kit#Cookies) API instead.
</div>
</div>
<div class="ts-block-property">
```dts
url: URL;
```
<div class="ts-block-property-details">
The requested URL.
</div>
</div>
<div class="ts-block-property">
```dts
isDataRequest: boolean;
```
<div class="ts-block-property-details">
`true` if the request comes from the client asking for `+page/layout.server.js` data. The `url` property will be stripped of the internal information
related to the data request in this case. Use this property instead if the distinction is important to you.
</div>
</div>
<div class="ts-block-property">
```dts
isSubRequest: boolean;
```
<div class="ts-block-property-details">
`true` for `+server.js` calls coming from SvelteKit without the overhead of actually making an HTTP request. This happens when you make same-origin `fetch` requests on the server.
</div>
</div></div>
## RequestHandler
A `(event: RequestEvent) => Response` function exported from a `+server.js` file that corresponds to an HTTP verb (`GET`, `PUT`, `PATCH`, etc) and handles requests with that method.
It receives `Params` as the first generic argument, which you can skip by using [generated types](/docs/kit/types#Generated-types) instead.
<div class="ts-block">
```dts
type RequestHandler<
Params extends Partial<Record<string, string>> = Partial<
Record<string, string>
>,
RouteId extends string | null = string | null
> = (
event: RequestEvent<Params, RouteId>
) => MaybePromise<Response>;
```
</div>
## Reroute
<blockquote class="since note">
Available since 2.3.0
</blockquote>
The [`reroute`](/docs/kit/hooks#Universal-hooks-reroute) hook allows you to modify the URL before it is used to determine which route to render.
<div class="ts-block">
```dts
type Reroute = (event: {
url: URL;
fetch: typeof fetch;
}) => MaybePromise<void | string>;
```
</div>
## ResolveOptions
<div class="ts-block">
```dts
interface ResolveOptions {/*…*/}
```
<div class="ts-block-property">
```dts
transformPageChunk?: (input: { html: string; done: boolean }) => MaybePromise<string | undefined>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `input` the html chunk and the info if this is the last chunk
</div>
Applies custom transforms to HTML. If `done` is true, it's the final chunk. Chunks are not guaranteed to be well-formed HTML
(they could include an element's opening tag but not its closing tag, for example)
but they will always be split at sensible boundaries such as `%sveltekit.head%` or layout/page components.
</div>
</div>
<div class="ts-block-property">
```dts
filterSerializedResponseHeaders?: (name: string, value: string) => boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `name` header name
- `value` header value
</div>
Determines which headers should be included in serialized responses when a `load` function loads a resource with `fetch`.
By default, none will be included.
</div>
</div>
<div class="ts-block-property">
```dts
preload?: (input: { type: 'font' | 'css' | 'js' | 'asset'; path: string }) => boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `input` the type of the file and its path
</div>
Determines what should be added to the `<head>` tag to preload it.
By default, `js` and `css` files will be preloaded.
</div>
</div></div>
## RouteDefinition
<div class="ts-block">
```dts
interface RouteDefinition<Config = any> {/*…*/}
```
<div class="ts-block-property">
```dts
id: string;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
api: {
methods: Array<HttpMethod | '*'>;
};
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
page: {
methods: Array<Extract<HttpMethod, 'GET' | 'POST'>>;
};
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
pattern: RegExp;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
prerender: PrerenderOption;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
segments: RouteSegment[];
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
methods: Array<HttpMethod | '*'>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
config: Config;
```
<div class="ts-block-property-details"></div>
</div></div>
## SSRManifest
<div class="ts-block">
```dts
interface SSRManifest {/*…*/}
```
<div class="ts-block-property">
```dts
appDir: string;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
appPath: string;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
assets: Set<string>;
```
<div class="ts-block-property-details">
Static files from `kit.config.files.assets` and the service worker (if any).
</div>
</div>
<div class="ts-block-property">
```dts
mimeTypes: Record<string, string>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
_: {/*…*/}
```
<div class="ts-block-property-details">
private fields
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
client: NonNullable<BuildData['client']>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
nodes: SSRNodeLoader[];
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
routes: SSRRoute[];
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
prerendered_routes: Set<string>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
matchers: () => Promise<Record<string, ParamMatcher>>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
server_assets: Record<string, number>;
```
<div class="ts-block-property-details">
A `[file]: size` map of all assets imported by server code.
</div>
</div></div>
</div>
</div></div>
## ServerInit
<blockquote class="since note">
Available since 2.10.0
</blockquote>
The [`init`](/docs/kit/hooks#Shared-hooks-init) will be invoked before the server responds to its first request
<div class="ts-block">
```dts
type ServerInit = () => MaybePromise<void>;
```
</div>
## ServerInitOptions
<div class="ts-block">
```dts
interface ServerInitOptions {/*…*/}
```
<div class="ts-block-property">
```dts
env: Record<string, string>;
```
<div class="ts-block-property-details">
A map of environment variables.
</div>
</div>
<div class="ts-block-property">
```dts
read?: (file: string) => MaybePromise<ReadableStream | null>;
```
<div class="ts-block-property-details">
A function that turns an asset filename into a `ReadableStream`. Required for the `read` export from `$app/server` to work.
</div>
</div></div>
## ServerLoad
The generic form of `PageServerLoad` and `LayoutServerLoad`. You should import those from `./$types` (see [generated types](/docs/kit/types#Generated-types))
rather than using `ServerLoad` directly.
<div class="ts-block">
```dts
type ServerLoad<
Params extends Partial<Record<string, string>> = Partial<
Record<string, string>
>,
ParentData extends Record<string, any> = Record<
string,
any
>,
OutputData extends Record<string, any> | void = Record<
string,
any
> | void,
RouteId extends string | null = string | null
> = (
event: ServerLoadEvent<Params, ParentData, RouteId>
) => MaybePromise<OutputData>;
```
</div>
## ServerLoadEvent
<div class="ts-block">
```dts
interface ServerLoadEvent<
Params extends Partial<Record<string, string>> = Partial<
Record<string, string>
>,
ParentData extends Record<string, any> = Record<
string,
any
>,
RouteId extends string | null = string | null
> extends RequestEvent<Params, RouteId> {/*…*/}
```
<div class="ts-block-property">
```dts
parent: () => Promise<ParentData>;
```
<div class="ts-block-property-details">
`await parent()` returns data from parent `+layout.server.js` `load` functions.
Be careful not to introduce accidental waterfalls when using `await parent()`. If for example you only want to merge parent data into the returned output, call it _after_ fetching your other data.
</div>
</div>
<div class="ts-block-property">
```dts
depends: (...deps: string[]) => void;
```
<div class="ts-block-property-details">
This function declares that the `load` function has a _dependency_ on one or more URLs or custom identifiers, which can subsequently be used with [`invalidate()`](/docs/kit/$app-navigation#invalidate) to cause `load` to rerun.
Most of the time you won't need this, as `fetch` calls `depends` on your behalf — it's only necessary if you're using a custom API client that bypasses `fetch`.
URLs can be absolute or relative to the page being loaded, and must be [encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding).
Custom identifiers have to be prefixed with one or more lowercase letters followed by a colon to conform to the [URI specification](https://www.rfc-editor.org/rfc/rfc3986.html).
The following example shows how to use `depends` to register a dependency on a custom identifier, which is `invalidate`d after a button click, making the `load` function rerun.
```js
// @errors: 7031
/// file: src/routes/+page.js
let count = 0;
export async function load({ depends }) {
depends('increase:count');
return { count: count++ };
}
```
```html
/// file: src/routes/+page.svelte
<script>
import { invalidate } from '$app/navigation';
let { data } = $props();
const increase = async () => {
await invalidate('increase:count');
}
</script>
<p>{data.count}<p>
<button on:click={increase}>Increase Count</button>
```
</div>
</div>
<div class="ts-block-property">
```dts
untrack: <T>(fn: () => T) => T;
```
<div class="ts-block-property-details">
Use this function to opt out of dependency tracking for everything that is synchronously called within the callback. Example:
```js
// @errors: 7031
/// file: src/routes/+page.js
export async function load({ untrack, url }) {
// Untrack url.pathname so that path changes don't trigger a rerun
if (untrack(() => url.pathname === '/')) {
return { message: 'Welcome!' };
}
}
```
</div>
</div></div>
## Snapshot
The type of `export const snapshot` exported from a page or layout component.
<div class="ts-block">
```dts
interface Snapshot<T = any> {/*…*/}
```
<div class="ts-block-property">
```dts
capture: () => T;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
restore: (snapshot: T) => void;
```
<div class="ts-block-property-details"></div>
</div></div>
## SubmitFunction
<div class="ts-block">
```dts
type SubmitFunction<
Success extends
| Record<string, unknown>
| undefined = Record<string, any>,
Failure extends
| Record<string, unknown>
| undefined = Record<string, any>
> = (input: {
action: URL;
formData: FormData;
formElement: HTMLFormElement;
controller: AbortController;
submitter: HTMLElement | null;
cancel: () => void;
}) => MaybePromise<
| void
| ((opts: {
formData: FormData;
formElement: HTMLFormElement;
action: URL;
result: ActionResult<Success, Failure>;
/**
* Call this to get the default behavior of a form submission response.
* @param options Set `reset: false` if you don't want the `<form>` values to be reset after a successful submission.
* @param invalidateAll Set `invalidateAll: false` if you don't want the action to call `invalidateAll` after submission.
*/
update: (options?: {
reset?: boolean;
invalidateAll?: boolean;
}) => Promise<void>;
}) => MaybePromise<void>)
>;
```
</div>
## Transport
<blockquote class="since note">
Available since 2.11.0
</blockquote>
The [`transport`](/docs/kit/hooks#Universal-hooks-transport) hook allows you to transport custom types across the server/client boundary.
Each transporter has a pair of `encode` and `decode` functions. On the server, `encode` determines whether a value is an instance of the custom type and, if so, returns a non-falsy encoding of the value which can be an object or an array (or `false` otherwise).
In the browser, `decode` turns the encoding back into an instance of the custom type.
```ts
import type { Transport } from '@sveltejs/kit';
declare class MyCustomType {
data: any
}
// hooks.js
export const transport: Transport = {
MyCustomType: {
encode: (value) => value instanceof MyCustomType && [value.data],
decode: ([data]) => new MyCustomType(data)
}
};
```
<div class="ts-block">
```dts
type Transport = Record<string, Transporter>;
```
</div>
## Transporter
A member of the [`transport`](/docs/kit/hooks#Universal-hooks-transport) hook.
<div class="ts-block">
```dts
interface Transporter<
T = any,
U = Exclude<
any,
false | 0 | '' | null | undefined | typeof NaN
>
> {/*…*/}
```
<div class="ts-block-property">
```dts
encode: (value: T) => false | U;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
decode: (data: U) => T;
```
<div class="ts-block-property-details"></div>
</div></div>
## Private types
The following are referenced by the public types documented above, but cannot be imported directly:
## AdapterEntry
<div class="ts-block">
```dts
interface AdapterEntry {/*…*/}
```
<div class="ts-block-property">
```dts
id: string;
```
<div class="ts-block-property-details">
A string that uniquely identifies an HTTP service (e.g. serverless function) and is used for deduplication.
For example, `/foo/a-[b]` and `/foo/[c]` are different routes, but would both
be represented in a Netlify _redirects file as `/foo/:param`, so they share an ID
</div>
</div>
<div class="ts-block-property">
```dts
filter(route: RouteDefinition): boolean;
```
<div class="ts-block-property-details">
A function that compares the candidate route with the current route to determine
if it should be grouped with the current route.
Use cases:
- Fallback pages: `/foo/[c]` is a fallback for `/foo/a-[b]`, and `/[...catchall]` is a fallback for all routes
- Grouping routes that share a common `config`: `/foo` should be deployed to the edge, `/bar` and `/baz` should be deployed to a serverless function
</div>
</div>
<div class="ts-block-property">
```dts
complete(entry: { generateManifest(opts: { relativePath: string }): string }): MaybePromise<void>;
```
<div class="ts-block-property-details">
A function that is invoked once the entry has been created. This is where you
should write the function to the filesystem and generate redirect manifests.
</div>
</div></div>
## Csp
<div class="ts-block">
```dts
namespace Csp {
type ActionSource = 'strict-dynamic' | 'report-sample';
type BaseSource =
| 'self'
| 'unsafe-eval'
| 'unsafe-hashes'
| 'unsafe-inline'
| 'wasm-unsafe-eval'
| 'none';
type CryptoSource =
`${'nonce' | 'sha256' | 'sha384' | 'sha512'}-${string}`;
type FrameSource =
| HostSource
| SchemeSource
| 'self'
| 'none';
type HostNameScheme = `${string}.${string}` | 'localhost';
type HostSource =
`${HostProtocolSchemes}${HostNameScheme}${PortScheme}`;
type HostProtocolSchemes = `${string}://` | '';
type HttpDelineator = '/' | '?' | '#' | '\\';
type PortScheme = `:${number}` | '' | ':*';
type SchemeSource =
| 'http:'
| 'https:'
| 'data:'
| 'mediastream:'
| 'blob:'
| 'filesystem:';
type Source =
| HostSource
| SchemeSource
| CryptoSource
| BaseSource;
type Sources = Source[];
}
```
</div>
## CspDirectives
<div class="ts-block">
```dts
interface CspDirectives {/*…*/}
```
<div class="ts-block-property">
```dts
'child-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'default-src'?: Array<Csp.Source | Csp.ActionSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'frame-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'worker-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'connect-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'font-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'img-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'manifest-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'media-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'object-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'prefetch-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'script-src'?: Array<Csp.Source | Csp.ActionSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'script-src-elem'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'script-src-attr'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'style-src'?: Array<Csp.Source | Csp.ActionSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'style-src-elem'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'style-src-attr'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'base-uri'?: Array<Csp.Source | Csp.ActionSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
sandbox?: Array<
| 'allow-downloads-without-user-activation'
| 'allow-forms'
| 'allow-modals'
| 'allow-orientation-lock'
| 'allow-pointer-lock'
| 'allow-popups'
| 'allow-popups-to-escape-sandbox'
| 'allow-presentation'
| 'allow-same-origin'
| 'allow-scripts'
| 'allow-storage-access-by-user-activation'
| 'allow-top-navigation'
| 'allow-top-navigation-by-user-activation'
>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'form-action'?: Array<Csp.Source | Csp.ActionSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'frame-ancestors'?: Array<Csp.HostSource | Csp.SchemeSource | Csp.FrameSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'navigate-to'?: Array<Csp.Source | Csp.ActionSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'report-uri'?: string[];
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'report-to'?: string[];
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'require-trusted-types-for'?: Array<'script'>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'trusted-types'?: Array<'none' | 'allow-duplicates' | '*' | string>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'upgrade-insecure-requests'?: boolean;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'require-sri-for'?: Array<'script' | 'style' | 'script style'>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
</div>
</div>
</div>
<div class="ts-block-property">
```dts
'block-all-mixed-content'?: boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
</div>
</div>
</div>
<div class="ts-block-property">
```dts
'plugin-types'?: Array<`${string}/${string}` | 'none'>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
</div>
</div>
</div>
<div class="ts-block-property">
```dts
referrer?: Array<
| 'no-referrer'
| 'no-referrer-when-downgrade'
| 'origin'
| 'origin-when-cross-origin'
| 'same-origin'
| 'strict-origin'
| 'strict-origin-when-cross-origin'
| 'unsafe-url'
| 'none'
>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
</div>
</div>
</div></div>
## HttpMethod
<div class="ts-block">
```dts
type HttpMethod =
| 'GET'
| 'HEAD'
| 'POST'
| 'PUT'
| 'DELETE'
| 'PATCH'
| 'OPTIONS';
```
</div>
## Logger
<div class="ts-block">
```dts
interface Logger {/*…*/}
```
<div class="ts-block-property">
```dts
(msg: string): void;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
success(msg: string): void;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
error(msg: string): void;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
warn(msg: string): void;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
minor(msg: string): void;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
info(msg: string): void;
```
<div class="ts-block-property-details"></div>
</div></div>
## MaybePromise
<div class="ts-block">
```dts
type MaybePromise<T> = T | Promise<T>;
```
</div>
## PrerenderEntryGeneratorMismatchHandler
<div class="ts-block">
```dts
interface PrerenderEntryGeneratorMismatchHandler {/*…*/}
```
<div class="ts-block-property">
```dts
(details: { generatedFromId: string; entry: string; matchedId: string; message: string }): void;
```
<div class="ts-block-property-details"></div>
</div></div>
## PrerenderEntryGeneratorMismatchHandlerValue
<div class="ts-block">
```dts
type PrerenderEntryGeneratorMismatchHandlerValue =
| 'fail'
| 'warn'
| 'ignore'
| PrerenderEntryGeneratorMismatchHandler;
```
</div>
## PrerenderHttpErrorHandler
<div class="ts-block">
```dts
interface PrerenderHttpErrorHandler {/*…*/}
```
<div class="ts-block-property">
```dts
(details: {
status: number;
path: string;
referrer: string | null;
referenceType: 'linked' | 'fetched';
message: string;
}): void;
```
<div class="ts-block-property-details"></div>
</div></div>
## PrerenderHttpErrorHandlerValue
<div class="ts-block">
```dts
type PrerenderHttpErrorHandlerValue =
| 'fail'
| 'warn'
| 'ignore'
| PrerenderHttpErrorHandler;
```
</div>
## PrerenderMap
<div class="ts-block">
```dts
type PrerenderMap = Map<string, PrerenderOption>;
```
</div>
## PrerenderMissingIdHandler
<div class="ts-block">
```dts
interface PrerenderMissingIdHandler {/*…*/}
```
<div class="ts-block-property">
```dts
(details: { path: string; id: string; referrers: string[]; message: string }): void;
```
<div class="ts-block-property-details"></div>
</div></div>
## PrerenderMissingIdHandlerValue
<div class="ts-block">
```dts
type PrerenderMissingIdHandlerValue =
| 'fail'
| 'warn'
| 'ignore'
| PrerenderMissingIdHandler;
```
</div>
## PrerenderOption
<div class="ts-block">
```dts
type PrerenderOption = boolean | 'auto';
```
</div>
## Prerendered
<div class="ts-block">
```dts
interface Prerendered {/*…*/}
```
<div class="ts-block-property">
```dts
pages: Map<
string,
{
/** The location of the .html file relative to the output directory */
file: string;
}
>;
```
<div class="ts-block-property-details">
A map of `path` to `{ file }` objects, where a path like `/foo` corresponds to `foo.html` and a path like `/bar/` corresponds to `bar/index.html`.
</div>
</div>
<div class="ts-block-property">
```dts
assets: Map<
string,
{
/** The MIME type of the asset */
type: string;
}
>;
```
<div class="ts-block-property-details">
A map of `path` to `{ type }` objects.
</div>
</div>
<div class="ts-block-property">
```dts
redirects: Map<
string,
{
status: number;
location: string;
}
>;
```
<div class="ts-block-property-details">
A map of redirects encountered during prerendering.
</div>
</div>
<div class="ts-block-property">
```dts
paths: string[];
```
<div class="ts-block-property-details">
An array of prerendered paths (without trailing slashes, regardless of the trailingSlash config)
</div>
</div></div>
## RequestOptions
<div class="ts-block">
```dts
interface RequestOptions {/*…*/}
```
<div class="ts-block-property">
```dts
getClientAddress(): string;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
platform?: App.Platform;
```
<div class="ts-block-property-details"></div>
</div></div>
## RouteSegment
<div class="ts-block">
```dts
interface RouteSegment {/*…*/}
```
<div class="ts-block-property">
```dts
content: string;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
dynamic: boolean;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
rest: boolean;
```
<div class="ts-block-property-details"></div>
</div></div>
## TrailingSlash
<div class="ts-block">
```dts
type TrailingSlash = 'never' | 'always' | 'ignore';
```
</div>
# @sveltejs/kit/hooks
```js
// @noErrors
import { sequence } from '@sveltejs/kit/hooks';
```
## sequence
A helper function for sequencing multiple `handle` calls in a middleware-like manner.
The behavior for the `handle` options is as follows:
- `transformPageChunk` is applied in reverse order and merged
- `preload` is applied in forward order, the first option "wins" and no `preload` options after it are called
- `filterSerializedResponseHeaders` behaves the same as `preload`
```js
// @errors: 7031
/// file: src/hooks.server.js
import { sequence } from '@sveltejs/kit/hooks';
/** @type {import('@sveltejs/kit').Handle} */
async function first({ event, resolve }) {
console.log('first pre-processing');
const result = await resolve(event, {
transformPageChunk: ({ html }) => {
// transforms are applied in reverse order
console.log('first transform');
return html;
},
preload: () => {
// this one wins as it's the first defined in the chain
console.log('first preload');
return true;
}
});
console.log('first post-processing');
return result;
}
/** @type {import('@sveltejs/kit').Handle} */
async function second({ event, resolve }) {
console.log('second pre-processing');
const result = await resolve(event, {
transformPageChunk: ({ html }) => {
console.log('second transform');
return html;
},
preload: () => {
console.log('second preload');
return true;
},
filterSerializedResponseHeaders: () => {
// this one wins as it's the first defined in the chain
console.log('second filterSerializedResponseHeaders');
return true;
}
});
console.log('second post-processing');
return result;
}
export const handle = sequence(first, second);
```
The example above would print:
```
first pre-processing
first preload
second pre-processing
second filterSerializedResponseHeaders
second transform
first transform
second post-processing
first post-processing
```
<div class="ts-block">
```dts
function sequence(
...handlers: import('@sveltejs/kit').Handle[]
): import('@sveltejs/kit').Handle;
```
</div>
# @sveltejs/kit/node/polyfills
```js
// @noErrors
import { installPolyfills } from '@sveltejs/kit/node/polyfills';
```
## installPolyfills
Make various web APIs available as globals:
- `crypto`
- `File`
<div class="ts-block">
```dts
function installPolyfills(): void;
```
</div>
# @sveltejs/kit/node
```js
// @noErrors
import {
createReadableStream,
getRequest,
setResponse
} from '@sveltejs/kit/node';
```
## createReadableStream
<blockquote class="since note">
Available since 2.4.0
</blockquote>
Converts a file on disk to a readable stream
<div class="ts-block">
```dts
function createReadableStream(file: string): ReadableStream;
```
</div>
## getRequest
<div class="ts-block">
```dts
function getRequest({
request,
base,
bodySizeLimit
}: {
request: import('http').IncomingMessage;
base: string;
bodySizeLimit?: number;
}): Promise<Request>;
```
</div>
## setResponse
<div class="ts-block">
```dts
function setResponse(
res: import('http').ServerResponse,
response: Response
): Promise<void>;
```
</div>
# @sveltejs/kit/vite
```js
// @noErrors
import { sveltekit } from '@sveltejs/kit/vite';
```
## sveltekit
Returns the SvelteKit Vite plugins.
<div class="ts-block">
```dts
function sveltekit(): Promise<import('vite').Plugin[]>;
```
</div>
# $app/environment
```js
// @noErrors
import { browser, building, dev, version } from '$app/environment';
```
##
浏览器
`如果应用程序在浏览器中运行。`
`const 浏览器: boolean;`
##
建筑
SvelteKit 在构建步骤中通过运行它来分析您的应用程序。在这个过程中，`构建`是`正在进行的`，`true`。这也适用于预渲染期间。
```dts
const building: boolean;
```
## dev
是否开发服务器正在运行。这并不保证与 `NODE_ENV` 或 `MODE` 相对应。
```dts
const dev: boolean;
```
##
版本
值 of `config.kit.version.name`.
`const 版本：string;`
# $app/forms
```js
// @noErrors
import { applyAction, deserialize, enhance } from '$app/forms';
```
##
应用动作
此操作使用给定数据更新当前页面的 `表单` 属性和更新 `page.status`。如果发生错误，将重定向到最近的错误页面。
```dts
function applyAction<
Success extends Record<string, unknown> | undefined,
Failure extends Record<string, unknown> | undefined
>(
result: import('@sveltejs/kit').ActionResult<
Success,
Failure
>
): Promise<void>;
```
##
反序列化
使用此函数反序列化表单提交的响应。用法：
```js
// @errors: 7031
import { deserialize } from '$app/forms';
async function handleSubmit(event) {
const response = await fetch('/form?/action', {
method: 'POST',
body: new FormData(event.target)
});
const result = deserialize(await response.text());
// ...
}
```
```dts
function deserialize<
Success extends Record<string, unknown> | undefined,
Failure extends Record<string, unknown> | undefined
>(
result: string
): import('@sveltejs/kit').ActionResult<Success, Failure>;
```
##
增强
此操作增强了一个`<form>`元素，否则该元素在没有 JavaScript 的情况下也能正常工作。
提交时，将使用给定的 FormData 和应触发的`action`调用`submit`函数。如果调用`cancel`，则表单将不会提交。如果另一个开始，可以使用 abort `controller`取消提交。如果返回一个函数，则该函数将使用来自服务器的响应被调用。如果没有返回任何内容，将使用回退方案。
如果此函数或其返回值未设置，则
* 回退到更新同一页面上表单的 `prop`，如果操作在该表单页面上
* 更新 `page.status`
* 重置 `<form>` 元素，并在无重定向响应的成功提交情况下使所有数据无效
* 重定向情况下的重定向响应
* 重定向到最近的错误页面，以处理意外错误
如果您提供了一个带有回调的自定义函数并希望使用默认行为，请在您的回调中调用`update`。它接受一个选项对象
* `重置：否`如果您不希望在成功提交后重置 `<form>` 的值
* `invalidateAll: false` 如果您不想在提交后调用 `invalidateAll`
```dts
function enhance<
Success extends Record<string, unknown> | undefined,
Failure extends Record<string, unknown> | undefined
>(
form_element: HTMLFormElement,
submit?: import('@sveltejs/kit').SubmitFunction<
Success,
Failure
>
): {
destroy(): void;
};
```
# $app/navigation
```js
// @noErrors
import {
afterNavigate,
beforeNavigate,
disableScrollHandling,
goto,
invalidate,
invalidateAll,
onNavigate,
preloadCode,
preloadData,
pushState,
replaceState
} from '$app/navigation';
```
## afterNavigate
一个在当前组件挂载时运行提供的 `回调` 的生命周期函数，并且每次我们导航到 URL 时也会运行。
`afterNavigate` 必须在组件初始化期间调用。只要组件挂载，它就保持激活状态。
```dts
function afterNavigate(
callback: (
navigation: import('@sveltejs/kit').AfterNavigate
) => void
): void;
```
##
在导航之前
一个在我们导航到 URL 之前触发的导航拦截器，无论是通过点击链接、调用`goto(...)`，还是使用浏览器的后退/前进控件。
调用 `cancel()` 将阻止导航完成。如果 `navigation.type === 'leave'` —— 表示用户正在离开应用（或关闭标签页）—— 调用 `cancel` 将触发原生的浏览器卸载确认对话框。在这种情况下，导航可能会取消，也可能不会取消，具体取决于用户的响应。
當導航不是指向 SvelteKit 擁有的路徑（因此由 SvelteKit 的客戶端路由器控制）時，`navigation.to.route.id`將會是`null`。
如果导航（如果没有取消）会导致文档卸载——换句话说，`'离开'`导航和`'链接'`导航，其中`navigation.to.route === null`——则`navigation.willUnload`为`true`。
`beforeNavigate` 必须在组件初始化期间调用。只要组件挂载，它就保持激活状态。
```dts
function beforeNavigate(
callback: (
navigation: import('@sveltejs/kit').BeforeNavigate
) => void
): void;
```
##
禁用滚动处理
如果页面在导航后更新时被调用（在`onMount`或`afterNavigate`或执行某个操作时，例如），这将禁用 SvelteKit 的内置滚动处理。这通常是不被推荐的，因为它会打破用户的期望。
```dts
function disableScrollHandling(): void;
```
##
转到
允许您以编程方式导航到指定路由，包括保持当前元素聚焦等选项。返回一个当 SvelteKit 导航（或未能导航，此时承诺拒绝）到指定 `url` 时解决的 Promise。
对于外部 URL，请使用`window.location = url`代替调用`goto(url)`。
```dts
function goto(
url: string | URL,
opts?:
| {
replaceState?: boolean | undefined;
noScroll?: boolean | undefined;
keepFocus?: boolean | undefined;
invalidateAll?: boolean | undefined;
invalidate?:
| (string | URL | ((url: URL) => boolean))[]
| undefined;
state?: App.PageState | undefined;
}
| undefined
): Promise<void>;
```
##
无效
导致属于当前活动页面的任何`加载`函数在它们依赖于所涉及的问题`URL`的情况下重新运行，通过`fetch`或`depends`。当页面随后更新时，返回一个`Promise`，该 Promise 将解决。
如果参数以`字符串`或`URL`的形式给出，它必须解析为传递给`fetch`或`depends`（包括查询参数）的相同 URL。要创建自定义标识符，请使用以`[a-z]+:`（例如`custom:state`）开头的字符串——这是一个有效的 URL。
The `function` argument can be used to define a custom predicate. It receives the full `URL` and causes `load` to rerun if `true` is returned. This can be useful if you want to invalidate based on a pattern instead of an exact match.
```ts
// Example: Match '/path' regardless of the query parameters
import { invalidate } from '$app/navigation';
invalidate((url) => url.pathname === '/path');
```
```dts
function invalidate(
resource: string | URL | ((url: URL) => boolean)
): Promise<void>;
```
##
无效所有
导致当前活动页面中属于所有 `load` 函数重新运行。返回一个在页面随后更新时解决的 `Promise`。
```dts
function invalidateAll(): Promise<void>;
```
##
在导航中
一个在导航到新 URL 之前立即运行提供的`回调`的生命周期函数，除了在整页导航期间。
如果您返回一个 `Promise`，SvelteKit 将在完成导航之前等待其解析。这允许您——例如——使用 `document.startViewTransition`。避免解析缓慢的承诺，因为导航将看起来对用户停滞不前。
如果从回调中返回一个函数（或一个解析为函数的 `Promise`），则将在 DOM 更新后调用该函数。
`onNavigate`必须在组件初始化期间调用。只要组件挂载，它就保持激活状态。
```dts
function onNavigate(
callback: (
navigation: import('@sveltejs/kit').OnNavigate
) => MaybePromise<(() => void) | void>
): void;
```
##
预加载代码
程序化导入尚未获取的路由代码。通常，您可能会调用此功能以加快后续导航。
您可以通过任何匹配的路径名来指定路由，例如 `/about`（以匹配 `src/routes/about/+page.svelte`）或 `/blog/*`（以匹配 `src/routes/blog/[slug]/+page.svelte` ）。
不同于 `preloadData`，这不会调用 `load` 函数。返回一个在模块导入完成后解决的 Promise。
```dts
function preloadCode(pathname: string): Promise<void>;
```
##
预载数据
程序预加载指定页面，即
1. 确保页面代码已加载，
2. 调用页面加载函数，使用适当的选项。
这是 SvelteKit 在用户点击或鼠标悬停在具有`<a>`元素和`data-sveltekit-preload-data`的情况下触发的相同行为。如果下一次导航到`href`，将使用加载返回的值，使导航瞬间完成。在预加载完成后，返回一个解析为新路由`load`函数运行结果的 Promise。
```dts
function preloadData(href: string): Promise<
| {
type: 'loaded';
status: number;
data: Record<string, any>;
}
| {
type: 'redirect';
location: string;
}
>;
```
## pushState
程序创建一个新的历史条目，使用给定的 `page.state`。要使用当前 URL，可以将`''`作为第一个参数传递。用于[浅层路由](/docs/kit/shallow-routing)。
```dts
function pushState(
url: string | URL,
state: App.PageState
): void;
```
##
替换状态
程序替换当前历史条目为给定的 `page.state`。要使用当前 URL，可以将 `''` 作为第一个参数传递。用于 [浅层路由](/docs/kit/shallow-routing)。
```dts
function replaceState(
url: string | URL,
state: App.PageState
): void;
```
# $app/paths
```js
// @noErrors
import { assets, base, resolveRoute } from '$app/paths';
```
##
资产
绝对路径匹配 [`config.kit.paths.assets`](/docs/kit/configuration#paths)。
> \[注意\] 如果指定了 `config.kit.paths.assets` 的值，则在 `vite dev` 或 `vite preview` 期间，它将被 `'/_svelte_kit_assets'` 替换，因为资产尚未位于其最终 URL。
```dts
let assets:
| ''
| `https://${string}`
| `http://${string}`
| '/_svelte_kit_assets';
```
##
基础
一个匹配[`config.kit.paths.base`](/docs/kit/configuration#paths)的字符串。
示例用法： `<a href="{base}/your-page">Link</a>`
``let base: '' | `/${字符串}`;``
##
解决路由
填充路由 ID 以解析路径名。
```js
// @errors: 7031
import { resolveRoute } from '$app/paths';
resolveRoute(
`/blog/[slug]/[...somethingElse]`,
{
slug: 'hello-world',
somethingElse: 'something/else'
}
); // `/blog/hello-world/something/else`
```
```dts
function resolveRoute(
id: string,
params: Record<string, string | undefined>
): string;
```
# $app/server
```js
// @noErrors
import { getRequestEvent, read } from '$app/server';
```
## getRequestEvent
> 自 2.20.0 起可用
返回当前 `RequestEvent`。可在服务器钩子、服务器 `load` 函数、操作和端点（以及由它们调用的函数）中使用。
在无`AsyncLocalStorage`的环境下，必须同步调用（即不在`await`之后）。
```dts
function getRequestEvent(): RequestEvent<
Partial<Record<string, string>>,
string | null
>;
```
##
读取
> 自 2.4.0 版本起可用
读取导入资产的文件系统内容
```js
// @errors: 7031
import { read } from '$app/server';
import somefile from './somefile.txt';
const asset = read(somefile);
const text = await asset.text();
```
```dts
function read(asset: string): Response;
```
# $app/state
SvelteKit 通过`$app/state`模块提供三个只读状态对象 —— `page`、`navigating`和`updated`。
> \[注意\] 此模块添加于 2.12 版本。如果您使用的是 SvelteKit 的早期版本，请使用[`$app/stores`]($app-stores)代替。
```js
// @noErrors
import { navigating, page, updated } from '$app/state';
```
##
导航
一个表示正在进行的导航的只读对象，具有 `from`、`to`、`type` 以及（如果 `type === 'popstate'`）`delta` 属性。当没有导航发生或服务器渲染期间，值 `null`。
```dts
const navigating:
| import('@sveltejs/kit').Navigation
| {
from: null;
to: null;
type: null;
willUnload: null;
delta: null;
complete: null;
};
```
##
页
一个只读的响应式对象，包含有关当前页面的信息，服务于多个用例：
* 检索组件树中所有页面/布局的合并`数据`（也见[加载数据](/docs/kit/load)）
* 检索组件树中任何位置的 `表单` 属性的当前值（也参见 [表单操作](/docs/kit/form-actions)）
* 获取通过 `goto`、`pushState` 或 `replaceState` 设置的页面状态（也参见 [goto](/docs/kit/$app-navigation#goto) 和 [浅层路由](/docs/kit/shallow-routing)）
* 检索元数据，例如您所在的 URL、当前路由及其参数，以及是否发生错误
```svelte
<!--- file: +layout.svelte --->
<script>
import { page } from '$app/state';
</script>
<p>Currently at {page.url.pathname}</p>
{#if page.error}
<span class="red">Problem detected</span>
{:else}
<span class="small">All systems operational</span>
{/if}
```
变更 `页面` 仅可通过符文进行。 (旧的反应性语法将不会反映任何变更)
```svelte
<!--- file: +page.svelte --->
<script>
import { page } from '$app/state';
const id = $derived(page.params.id); // This will correctly update id for usage on this page
$: badId = page.params.id; // Do not use; will never update after initial load
</script>
```
在服务器上，值只能在渲染时读取（换句话说，在例如 `加载` 函数中 *不能* 读取）。在浏览器中，值可以在任何时候读取。
```dts
const page: import('@sveltejs/kit').Page;
```
##
更新
一个初始值为`false`的只读响应式值。如果`version.pollInterval`是一个非零值，SvelteKit 将轮询应用的新版本，并在检测到新版本时将`current`更新为`true`。`updated.check()`将强制立即检查，无论是否轮询。
```dts
const updated: {
get current(): boolean;
check(): Promise<boolean>;
};
```
# $app/stores
此模块包含了对从 [`$app/state`]($app-state) 导出的基于存储的等效项。如果您正在使用 SvelteKit 2.12 或更高版本，请使用该模块。
```js
// @noErrors
import { getStores, navigating, page, updated } from '$app/stores';
```
##
获取商店
```dts
function getStores(): {
page: typeof page;
navigating: typeof navigating;
updated: typeof updated;
};
```
##
导航
> 使用从 `$app/state` 的 `navigating` 替代（需要 Svelte 5，[查看文档以获取更多信息](/docs/kit/migrating-to-sveltekit-2#SvelteKit-2.12:-$app-stores-deprecated)）
可读的存储。当开始导航时，其值是一个具有 `Navigation` 对象，包含 `from`、`to`、`type` 和（如果 `type === 'popstate'`）`delta` 属性的 `null`。当导航完成时，其值恢复为 `null`。
在服务器上，此存储只能在组件初始化期间订阅。在浏览器中，可以在任何时候订阅。
```dts
const navigating: import('svelte/store').Readable<
import('@sveltejs/kit').Navigation | null
>;
```
##
页
> 使用 `页面` 从 `$app/state` 中代替（需要 Svelte 5，[查看文档获取更多信息](/docs/kit/migrating-to-sveltekit-2#SvelteKit-2.12:-$app-stores-deprecated)）
一个包含页面数据的可读存储。
在服务器上，此存储只能在组件初始化期间订阅。在浏览器中，可以在任何时候订阅。
```dts
const page: import('svelte/store').Readable<
import('@sveltejs/kit').Page
>;
```
##
更新
> 使用 `updated` 从 `$app/state` 中替换（需要 Svelte 5，[查看文档获取更多信息](/docs/kit/migrating-to-sveltekit-2#SvelteKit-2.12:-$app-stores-deprecated)）
一个初始值为`false`的可读存储。如果`version.pollInterval`是一个非零值，SvelteKit 将轮询应用的新版本，并在检测到新版本时将存储值更新为`true`。`updated.check()`将强制立即检查，无论是否轮询。
在服务器上，此存储只能在组件初始化期间订阅。在浏览器中，可以在任何时候订阅。
```dts
const updated: import('svelte/store').Readable<boolean> & {
check(): Promise<boolean>;
};
```
# $env/dynamic/private
此模块提供对运行时环境变量的访问，这些变量由您运行的平台定义。例如，如果您正在使用[`adapter-node`](https://github.com/sveltejs/kit/tree/main/packages/adapter-node)（或运行[`vite preview`](/docs/kit/cli)），则这相当于`process.env`。此模块仅包括不以[`config.kit.env.publicPrefix`](/docs/kit/configuration#env)开头且以[`config.kit.env.privatePrefix`](/docs/kit/configuration#env)开头（如果已配置）的变量。
此模块无法导入客户端代码。
动态环境变量在预渲染期间无法使用。
```ts
import { env } from '$env/dynamic/private';
console.log(env.DEPLOYMENT_SPECIFIC_VARIABLE);
```
> 在`dev`中，`$env/dynamic`始终包含来自`.env`的环境变量。在`prod`中，此行为将取决于您的适配器。
# $env/dynamic/public
与[`$env/dynamic/private`](/docs/kit/$env-dynamic-private)类似，但仅包括以[`config.kit.env.publicPrefix`](/docs/kit/configuration#env)（默认为`PUBLIC_`）开头的变量，因此可以安全地暴露给客户端代码。
请注意，所有公共动态环境变量都必须从服务器发送到客户端，这会导致更大的网络请求——当可能时，请使用 `$env/static/public` 代替。
动态环境变量在预渲染期间无法使用。
```ts
import { env } from '$env/dynamic/public';
console.log(env.PUBLIC_DEPLOYMENT_SPECIFIC_VARIABLE);
```
# $env/static/private
环境变量由 Vite 加载的 [从](https://vitejs.dev/guide/env-and-mode.html#env-files) `.env` 文件和 `process.env` 中，类似于 [`$env/dynamic/private`](/docs/kit/$env-dynamic-private)，此模块不能导入到客户端代码中。此模块仅包括不以 *不* 以 [`config.kit.env.publicPrefix`](/docs/kit/configuration#env)*和* 以 [`config.kit.env.privatePrefix`](/docs/kit/configuration#env)（如果已配置）开头的变量。
与*不同于*[`$env/dynamic/private`](/docs/kit/$env-dynamic-private)不同，此模块导出的值在构建时静态注入到您的包中，从而启用诸如死代码消除等优化。
```ts
import { API_KEY } from '$env/static/private';
```
请注意，您代码中引用的所有环境变量都应声明（例如在 `.env` 文件中），即使它们在应用部署之前没有值：
```
MY_FEATURE_FLAG=""
```
您可以通过命令行像这样覆盖`.env`的值：
```bash
MY_FEATURE_FLAG="enabled" npm run dev
```
# $env/static/public
与[`$env/static/private`](/docs/kit/$env-static-private)类似，但仅包括以[`config.kit.env.publicPrefix`](/docs/kit/configuration#env)（默认为`PUBLIC_`）开头的环境变量，因此可以安全地暴露给客户端代码。
值在构建时静态替换。
```ts
import { PUBLIC_BASE_URL } from '$env/static/public';
```
# $lib
SvelteKit 自动将 `src/lib` 目录下的文件通过 `$lib` 导入别名使其可用。您可以在您的 [配置文件](configuration#files) 中更改此别名指向的目录。
```svelte
<!--- file: src/lib/Component.svelte --->
A reusable component
```
```svelte
<!--- file: src/routes/+page.svelte --->
<script>
import Component from '$lib/Component.svelte';
</script>
<Component />
```
# $service-worker
```js
// @noErrors
import { base, build, files, prerendered, version } from '$service-worker';
```
此模块仅对[服务工作者](/docs/kit/service-workers)可用。
##
基础
部署的`基本`路径。通常这等同于`config.kit.paths.base`，但它是由`location.pathname`计算得出的，这意味着如果网站部署到子目录中，它仍然可以正确工作。请注意，存在一个`基本`但没有`资源`，因为如果指定了`config.kit.paths.assets`，则无法使用服务工作者。
```dts
const base: string;
```
##
构建
一个表示由 Vite 生成的文件的 URL 字符串数组，适用于与 `cache.addAll(build)` 一起缓存。在开发期间，这是一个空数组。
```dts
const build: string[];
```
##
文件
一个表示您静态目录中文件的 URL 字符串数组，或由`config.kit.files.assets`指定的任何目录。您可以使用 [`config.kit.serviceWorker.files`](/docs/kit/configuration) 自定义从`static`目录中包含哪些文件。
`const 文件: string[];`
##
预渲染
路径名数组，对应预渲染页面和端点。在开发期间，这是一个空数组。
```dts
const prerendered: string[];
```
##
版本
查看 [`config.kit.version`](/docs/kit/configuration#version)。这对于在您的服务工作者内部生成唯一的缓存名称很有用，以便您的应用程序的后续部署可以使旧缓存失效。
`const 版本：string;`
# Configuration
您的项目配置位于项目根目录下的 `svelte.config.js` 文件中。此外，SvelteKit 也使用此配置对象，以及其他与 Svelte 集成的工具，如编辑器扩展。
```js
/// file: svelte.config.js
// @filename: ambient.d.ts
declare module '@sveltejs/adapter-auto' {
const plugin: () => import('@sveltejs/kit').Adapter;
export default plugin;
}
// @filename: index.js
// ---cut---
import adapter from '@sveltejs/adapter-auto';
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
adapter: adapter()
}
};
export default config;
```
##
配置
扩展[`vite-plugin-svelte`的选项](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/config.md#svelte-options)。
```dts
interface Config extends SvelteConfig {/*…*/}
```
```dts
kit?: KitConfig;
```
SvelteKit 选项。
`[键：字符串]: 任何；`
任何需要与 Svelte 集成的工具所需的附加选项。
##
套件配置
The `kit` 属性配置 SvelteKit，并可以具有以下属性：
##
适配器
* 默认`未定义`
您的[适配器](/docs/kit/adapters)在执行`vite build`时运行。它决定了输出如何转换为不同的平台。
##
别名
* 默认`{}`
一个包含零个或多个别名的对象，用于替换 `import` 语句中的值。这些别名将自动传递给 Vite 和 TypeScript。
```js
// @errors: 7031
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
alias: {
// this will match a file
'my-file': 'path/to/my-file.js',
// this will match a directory and its contents
// (`my-directory/x` resolves to `path/to/my-directory/x`)
'my-directory': 'path/to/my-directory',
// an alias ending /* will only match
// the contents of a directory, not the directory itself
'my-directory/*': 'path/to/my-directory/*'
}
}
};
```
> \[!注意\] 内置的 `$lib` 别名由 `config.kit.files.lib` 控制，因为它用于打包。
> \[!注意\] 您需要运行 `npm run dev` 以使 SvelteKit 自动在 `jsconfig.json` 或 `tsconfig.json` 中生成所需的别名配置。
## appDir
* 默认`"_app"`
目录，其中 SvelteKit 存储其内容，包括静态资产（如 JS 和 CSS）以及内部使用的路由。
如果指定了 `paths.assets`，则会有两个应用程序目录 — `${paths.assets}/${appDir}` 和 `${paths.base}/${appDir}`。
## csp
[内容安全策略](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)配置。CSP 有助于保护您的用户免受跨站脚本（XSS）攻击，通过限制资源可以加载的位置。例如，这样的配置...
```js
// @errors: 7031
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
csp: {
directives: {
'script-src': ['self']
},
// must be specified with either the `report-uri` or `report-to` directives, or both
reportOnly: {
'script-src': ['self'],
'report-uri': ['/']
}
}
}
};
export default config;
```
...将阻止从外部站点加载脚本。SvelteKit 将为它生成的任何内联样式和脚本添加非 ces 或散列（取决于`模式`）以增强指定的指令。
要手动为包含在`src/app.html`中的脚本和链接添加 nonce，您可以使用占位符`%sveltekit.nonce%`（例如 `<script nonce="%sveltekit.nonce%">` ）。
当页面预渲染时，通过一个`＜meta http-equiv＞`标签添加 CSP 头部（注意，在这种情况下，`frame-ancestors`、`report-uri`和`sandbox`指令将被忽略）。
> \[!注意\] 当 `模式` 为 `'自动'` 时，SvelteKit 将为动态渲染的页面使用非 ces，为预渲染的页面使用哈希。在预渲染的页面中使用非 ces 是不安全的，因此被禁止。
> \[!注意\] 注意，大多数 [Svelte 过渡](/tutorial/svelte/transition) 通过创建一个内联 `<style>` 元素来工作。如果您在您的应用程序中使用这些，您必须保留 `style-src` 指令未指定，或者添加 `unsafe-inline`。
如果此级别的配置不足，并且您有更多动态需求，可以使用[`handle`钩子](/docs/kit/hooks#Server-hooks-handle)来自定义您的 CSP。
```ts
// @noErrors
mode?: 'hash' | 'nonce' | 'auto';
```
是否使用哈希或 nonce 来限制`<script>`和`<style>`元素。`'auto'`将为预渲染页面使用哈希，为动态渲染页面使用 nonce。
```ts
// @noErrors
directives?: CspDirectives;
```
指令将添加到 `内容安全策略` 头部。
```ts
// @noErrors
reportOnly?: CspDirectives;
```
指令将添加到 `Content-Security-Policy-Report-Only` 头中。
## csrf
防护[跨站请求伪造（CSRF）攻击](https://owasp.org/www-community/attacks/csrf)。
```ts
// @noErrors
checkOrigin?: boolean;
```
* 默认`真`
是否检查 incoming `origin` 标头对于 `POST`、`PUT`、`PATCH` 或 `DELETE` 表单提交，并验证其是否与服务器原点匹配。
为了允许人们从其他来源向您的应用发送具有 `application/x-www-form-urlencoded` `Content-Type`的`POST`、`PUT`、`PATCH`或`DELETE`请求，其中`multipart/form-data`或`text/plain`，您需要禁用此选项。请小心！
##
嵌入式
* 默认`否`
是或否将应用嵌入到更大的应用中。如果 `true`，SvelteKit 将在其父元素 `%sveltekit.body%` 上添加与导航等相关的监听器，而不是添加到 `window`，并且将从服务器传递 `params` 而不是从 `location.pathname` 推断它们。请注意，通常不支持在同一页面上嵌入多个 SvelteKit 应用，并在其中使用客户端 SvelteKit 功能（例如，将历史状态推送到单个实例）。
## env
环境变量配置
`` // @noErrors `没有错误 dir?: 字符串;` ``
* 默认`“.”`
搜索 `.env` 文件的目录。
```ts
// @noErrors
publicPrefix?: string;
```
* 默认`"PUBLIC_"`
前缀表示环境变量可以安全地暴露给客户端代码。请参阅 [`$env/static/public`](/docs/kit/$env-static-public) 和 [`$env/dynamic/public`](/docs/kit/$env-dynamic-public)。请注意，如果您使用 Vite 的环境变量处理，则必须单独设置 Vite 的 [`envPrefix`](https://vitejs.dev/config/shared-options.html#envprefix)，尽管通常不需要使用该功能。
```ts
// @noErrors
privatePrefix?: string;
```
* 默认`""`
* 自 v1.21.0 起可用
前缀表示环境变量不安全，不能暴露给客户端代码。既不匹配公共前缀也不匹配私有前缀的环境变量将被完全丢弃。请参阅[`$env/static/private`](/docs/kit/$env-static-private)和[`$env/dynamic/private`](/docs/kit/$env-dynamic-private)。
##
文件
在哪里可以找到项目中的各种文件。
```ts
// @noErrors
assets?: string;
```
* 默认`"静态"`
一个存放静态文件的地方，这些文件应具有稳定的 URL 且不经过处理，例如 `favicon.ico` 或 `manifest.json`
`` // @noErrors `没有错误 hooks?: {/*…*/}` ``
```ts
// @noErrors
client?: string;
```
* 默认`"src/hooks.client"`
您的客户端[钩子](/docs/kit/hooks)的位置。
```ts
// @noErrors
server?: string;
```
* 默认`"src/hooks.server"`
您的服务器位置 [钩子](/docs/kit/hooks)。
```ts
// @noErrors
universal?: string;
```
* 默认`"src/钩子"`
* 自 v2.3.0 起可用
您的通用[钩子](/docs/kit/hooks)的位置。
`` // @noErrors `没有错误 lib?: 字符串;` ``
* 默认`"src/lib"`
您的应用程序的内部库，在整个代码库中可通过`$lib`访问
```ts
// @noErrors
params?: string;
```
* 默认`"src/params"`
一个包含[参数匹配器](/docs/kit/advanced-routing#Matching)的目录
```ts
// @noErrors
routes?: string;
```
* 默认`"src/路由"`
文件定义您的应用程序结构（见[路由](/docs/kit/routing)）
```ts
// @noErrors
serviceWorker?: string;
```
* 默认`"src/service-worker"`
服务工作者入口点的位置（见[服务工作者](/docs/kit/service-workers)）
```ts
// @noErrors
appTemplate?: string;
```
* 默认`"src/app.html"`
模板的位置，用于 HTML 响应
```ts
// @noErrors
errorTemplate?: string;
```
* 默认`"src/error.html"`
模板的回退错误响应位置
##
行内样式阈值
* 默认`0`
行内 CSS 位于 HTML 头部`<style>`块内。此选项是一个数字，指定 CSS 文件在 UTF-16 代码单元中的最大长度，如[String.length](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length)属性所述，以行内形式存在。所有小于此值的页面所需的 CSS 文件都将合并并内联到`<style>`块中。
> \[注意\] 这会导致初始请求更少，并可以提高您的[首次内容绘制](https://web.dev/first-contentful-paint)得分。然而，它会产生更大的 HTML 输出，并降低浏览器缓存的效率。请谨慎使用。
##
模块扩展
* 默认`[".js", ".ts"]`
文件扩展名数组，SvelteKit 将其视为模块。与 `config.extensions` 或 `config.kit.moduleExtensions` 不匹配的扩展名文件将被路由器忽略。
##
输出目录
* 默认`“.svelte-kit”`
目录是 SvelteKit 在`dev`和`build`期间写入文件的目录。您应该将此目录排除在版本控制之外。
##
输出
与构建输出格式相关的选项
```ts
// @noErrors
preloadStrategy?: 'modulepreload' | 'preload-js' | 'preload-mjs';
```
* 默认`"模块预加载"`
* 自 v1.8.4 起可用
SvelteKit 将预加载初始页面所需的 JavaScript 模块，以避免出现 'waterfalls' 导入，从而实现更快的应用程序启动。这里有三种策略，各有不同的权衡。
* `模块预加载` - 使用 `<link rel="modulepreload">`。在基于 Chromium 的浏览器、Firefox 115+ 和 Safari 17+ 中效果最佳。在较旧浏览器中被忽略。
* `preload-js` - 使用 `<link rel="preload">`。防止 Chromium 和 Safari 中的瀑布效应，但 Chromium 会解析每个模块两次（一次作为脚本，一次作为模块）。在 Firefox 中导致模块被请求两次。如果您想最大限度地提高 iOS 设备用户的性能，而以 Chromium 用户性能的轻微下降为代价，这是一个好的设置。
* `preload-mjs` - 使用 `<link rel="preload">` 但带有 `.mjs` 扩展名，这可以防止在 Chromium 中重复解析。一些静态 Web 服务器可能会因为 `Content-Type: application/javascript` 头部而无法提供 .mjs 文件，这会导致您的应用程序崩溃。如果这不适合您，这是为最大数量的用户提供最佳性能的选项，直到 `modulepreload` 得到更广泛的支持。
```ts
// @noErrors
bundleStrategy?: 'split' | 'single' | 'inline';
```
* 默认`'split'`
* 自 v2.13.0 起可用
捆绑策略选项影响您的应用程序的 JavaScript 和 CSS 文件加载方式。
* 如果 `'split'`，则将应用拆分为多个.js/.css 文件，以便在用户在应用中导航时按需加载。这是默认设置，适用于大多数场景。
* 如果 `'single'`，则仅创建一个包含整个应用代码的 .js 包和一个 .css 文件。
* 如果 `'inline'`，则将整个应用的所有 JavaScript 和 CSS 内联到 HTML 中。结果无需服务器即可使用（即您可以直接在浏览器中打开文件）。
当使用`'split'`时，您还可以通过在您的 Vite 配置的[`build.rollupOptions`](https://vite.dev/config/build-options.html#build-rollupoptions)中设置 [`output.experimentalMinChunkSize`](https://rollupjs.org/configuration-options/#output-experimentalminchunksize) 和[`output.manualChunks`](https://rollupjs.org/configuration-options/#output-manualchunks)来调整捆绑行为。
如果您想内联您的资源，您需要将 Vite 的 [`build.assetsInlineLimit`](https://vite.dev/config/build-options.html#build-assetsinlinelimit) 选项设置为适当的大小，然后通过 Vite 导入您的资源。
```js
// @errors: 7031
/// file: vite.config.js
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [sveltekit()],
build: {
// inline all imported assets
assetsInlineLimit: Infinity
}
});
```
```svelte
/// file: src/routes/+layout.svelte
<script>
// import the asset through Vite
import favicon from './favicon.png';
</script>
<svelte:head>
<!-- this asset will be inlined as a base64 URL -->
<link rel="icon" href={favicon} />
</svelte:head>
```
##
路径
```ts
// @noErrors
assets?: '' | `http://${string}` | `https://${string}`;
```
* 默认`""`
绝对路径，您的应用程序文件从中提供的服务路径。如果您的文件是从某种存储桶中提供服务的，这很有用。
```ts
// @noErrors
base?: '' | `/${string}`;
```
* 默认`""`
根相对路径必须以`/`开头，但不能以`/`结尾（例如：`/base-path`），除非它是空字符串。这指定了您的应用程序从哪里提供服务，并允许应用程序存在于非根路径上。请注意，您需要将所有根相对链接都添加基本值作为前缀，否则它们将指向域的根，而不是您的`基本`（这就是浏览器的工作方式）。您可以使用从`$app/paths`中的`基本`[：](/docs/kit/$app-paths#base)进行此操作： `<a href="{base}/your-page">Link</a>` 。如果您经常编写此内容，将其提取为可重用组件可能是有意义的。
```ts
// @noErrors
relative?: boolean;
```
* 默认`真`
* 自 v1.9.0 起可用
是否使用相对资源路径。
如果 `true`，则从 `$app/paths` 导入的 `base` 和 `assets` 在服务器端渲染期间将被替换为相对资产路径，从而生成更易于携带的 HTML。如果 `false`，则 `%sveltekit.assets%` 和对构建实体的引用将始终是根相关路径，除非 `paths.assets` 是外部 URL。
[单页应用程序](/docs/kit/single-page-apps)回退页面将始终使用绝对路径，无论此设置如何。
如果您的应用使用了`<base>`元素，您应该将其设置为`false`，否则资产 URL 将不正确地相对于`<base>` URL 解析，而不是当前页面。
在 1.0 版本中，`undefined`是一个有效的值，默认设置为该值。在这种情况下，如果`paths.assets`不是外部的，SvelteKit 会将`%sveltekit.assets%`替换为相对路径，并使用相对路径来引用构建工件，但从`$app/paths`导入的`base`和`assets`将按照您的配置指定。
##
预渲染
查看[预渲染](/docs/kit/page-options#prerender)。
```ts
// @noErrors
concurrency?: number;
```
* 默认`1`
一次可以预渲染多少页。JavaScript 是单线程的，但在预渲染性能受网络限制的情况下（例如从远程 CMS 加载内容），这可以通过在等待网络响应时处理其他任务来加快速度。
```ts
// @noErrors
crawl?: boolean;
```
* 默认`真`
是否 SvelteKit 应通过跟随从`entries`的链接来查找需要预渲染的页面。
```ts
// @noErrors
entries?: Array<'*' | `/${string}`>;
```
* 默认`["*"]`
一個待預渲染的頁面數組，或從此開始爬取（如果 `crawl: true`）。`*` 字符串包括所有不包含必需的 `[參數]` 且選項參數為空的路由（因為 SvelteKit 不清楚任何參數應該有何值）。
```ts
// @noErrors
handleHttpError?: PrerenderHttpErrorHandlerValue;
```
* 默认`"失败"`
* 自 v1.15.7 起可用
如何应对在预渲染应用时遇到的 HTTP 错误。
* `失败` — 构建失败
* `忽略` - 静默忽略失败并继续
* `警告` — 继续执行，但打印警告
* `(详细信息) => void` — 一个自定义错误处理器，它接受一个具有`状态`、`路径`、`来源`、`引用类型`和`消息`属性的`详细信息`对象。如果您从这个函数中`抛出异常`，构建将失败
```js
// @errors: 7031
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
prerender: {
handleHttpError: ({ path, referrer, message }) => {
// ignore deliberate link to shiny 404 page
if (path === '/not-found' && referrer === '/blog/how-we-built-our-404-page') {
return;
}
// otherwise fail the build
throw new Error(message);
}
}
}
};
```
```ts
// @noErrors
handleMissingId?: PrerenderMissingIdHandlerValue;
```
* 默认`"失败"`
* 自 v1.15.7 起可用
如何应对从一个预渲染页面到另一个页面时，哈希链接与目标页面上的 `id` 不对应的情况。
* `失败` — 构建失败
* `忽略` - 静默忽略失败并继续
* `警告` — 继续执行，但打印警告
* `(详细信息) => void` — 一个自定义错误处理器，它接受一个具有`路径`、`id`、`引用者`和`消息`属性的`详细信息`对象。如果您从这个函数中`抛出`，构建将失败
```ts
// @noErrors
handleEntryGeneratorMismatch?: PrerenderEntryGeneratorMismatchHandlerValue;
```
* 默认`"失败"`
* 自 v1.16.0 起可用
如何应对由`entries`导出生成的条目与其生成的路由不匹配的情况。
* `失败` — 构建失败
* `忽略` - 静默忽略失败并继续
* `警告` — 继续执行，但打印警告
* `(详细信息) => void` — 一个自定义错误处理器，它接受一个具有 `generatedFromId`、`entry`、`matchedId` 和 `message` 属性的 `details` 对象。如果您从这个函数中 `throw`，构建将失败
```ts
// @noErrors
origin?: string;
```
* 默认`"http://sveltekit-prerender"`
The value of `url.origin` during prerendering; useful if it is included in rendered content.
##
路由器
```ts
// @noErrors
type?: 'pathname' | 'hash';
```
* 默认`"路径名"`
* 自 v2.14.0 起可用
使用哪种客户端路由器。
* `‘pathname’`是默认值，表示当前 URL 的路径名决定路由
* `‘hash’` 表示路由由 `location.hash` 决定。在这种情况下，SSR 和预渲染被禁用。只有在 `pathname` 不可选时才推荐这样做，例如，因为你无法控制部署应用程序的 web 服务器。它带来了一些注意事项：你不能使用服务器端渲染（或者确实任何服务器逻辑），并且你必须确保你的应用程序中的所有链接都以 #/ 开头，否则它们将无法工作。除此之外，一切工作方式都与正常的 SvelteKit 应用程序完全相同。
```ts
// @noErrors
resolution?: 'client' | 'server';
```
* 默认`"客户端"`
* 自 v2.17.0 起可用
如何确定在导航到新页面时加载哪条路由。
默认情况下，SvelteKit 将为浏览器提供路由清单。在导航时，此清单（以及如果存在，则使用`reroute`钩子）用于确定要加载哪些组件以及要运行哪些`load`函数。因为所有操作都在客户端进行，所以这个决定可以立即做出。缺点是必须在第一次导航之前加载和解析清单，如果您的应用程序包含许多路由，这可能会产生影响。
或者，SvelteKit 可以在服务器上确定路由。这意味着对于每个导航到尚未访问的路径，服务器将被要求确定路由。这有几个优点：
* 客户端无需预先加载路由清单，这可以导致页面初始加载更快
* 路由列表对公众隐藏
* 服务器有机会拦截每次导航（例如通过中间件），从而实现（例如）对 SvelteKit 不可见的 A/B 测试
缺点是对于未访问的路径，解析将稍微花费更长的时间（尽管这可以通过[预加载](/docs/kit/link-options#data-sveltekit-preload-data)来缓解）。
> \[注意\] 当使用服务器端路由解析和预渲染时，解析将与路由本身一起预渲染。
##
服务工作者
```ts
// @noErrors
register?: boolean;
```
* 默认`真`
是否自动注册存在的服务工作者。
```ts
// @noErrors
files?(filepath: string): boolean;
```
* 默认 `(filename) => !/\.DS_Store/.test(filename)`
确定你的 `static` 目录中哪些文件将在 `$service-worker.files` 中可用。
## typescript
```ts
// @noErrors
config?: (config: Record<string, any>) => Record<string, any> | void;
```
* 默认`(配置) => 配置`
* 自 v1.3.0 起可用
一个允许您编辑生成的`tsconfig.json`的函数。您可以修改配置（推荐）或返回一个新的配置。这在扩展 monorepo 根目录中的共享`tsconfig.json`时非常有用。
##
版本
客户端导航可能会出现 bug，如果您在用户使用应用时部署新版本，如果新页面的代码已经加载，它可能包含过时内容；如果没有加载，应用的路线清单可能指向一个不再存在的 JavaScript 文件。SvelteKit 通过版本管理帮助您解决这个问题。如果 SvelteKit 在加载页面时遇到错误并检测到已部署新版本（使用此处指定的`name`，默认为构建的时间戳），它将回退到传统的全页导航。并非所有导航都会导致错误，例如，如果下一页的 JavaScript 已经加载。如果您仍然想在这些情况下强制全页导航，请使用设置`pollInterval`然后使用`beforeNavigate`等技术。
```html
/// file: +layout.svelte
<script>
import { beforeNavigate } from '$app/navigation';
import { updated } from '$app/state';
beforeNavigate(({ willUnload, to }) => {
if (updated.current && !willUnload && to?.url) {
location.href = to.url.href;
}
});
</script>
```
如果您将`pollInterval`设置为非零值，SvelteKit 将在后台轮询新版本，并在检测到新版本时将`[updated.current](/docs/kit/$app-state#updated)``true`的值设置为。
`` // @noErrors `没有错误 名称?: 字符串;` ``
当前应用版本字符串。如果指定，则必须是确定的（例如，提交引用而不是 `Math.random()` 或 `Date.now().toString()`），否则默认为构建的时间戳。
例如，要使用当前的提交哈希，您可以这样做：使用 `git rev-parse HEAD`：
```js
// @errors: 7031
/// file: svelte.config.js
import * as child_process from 'node:child_process';
export default {
kit: {
version: {
name: child_process.execSync('git rev-parse HEAD').toString().trim()
}
}
};
```
```ts
// @noErrors
pollInterval?: number;
```
* 默认`0`
毫秒级的轮询版本更改的间隔。如果这是 `0`，则不进行轮询。
# Command Line Interface
SvelteKit 项目使用[Vue](https://vitejs.dev)，这意味着你将主要使用其 CLI（尽管是通过`npm run dev/build/preview`脚本）：
* `vite 开发` — 启动开发服务器
* `使用 vite 构建` — 构建您的应用程序的生产版本
* `vite 预览` — 在本地运行生产版本
然而，SvelteKit 包含用于初始化项目的自带 CLI：
##
svelte-kit 同步
`使用 svelte-kit 同步`会创建`tsconfig.json`以及所有生成的类型（您可以在路由文件中将其导入为`./$types`），供您的项目使用。当您创建一个新项目时，它会被列为`准备`脚本，并作为 npm 生命周期的一部分自动运行，因此您通常不需要运行此命令。
# Types
##
生成类型
请求处理器`RequestHandler`和`Load`类型都接受一个`Params`参数，允许您输入`params`对象。例如，此端点期望`foo`、`bar`和`baz`参数：
```js
/// file: src/routes/[foo]/[bar]/[baz]/+server.js
// @errors: 2355 2322 1360
/** @type {import('@sveltejs/kit').RequestHandler<{
foo: string;
bar: string;
baz: string
}>} */
export async function GET({ params }) {
// ...
}
```
不用说，这写起来很麻烦，而且不太便携（如果你要将`[foo]`目录重命名为`[qux]`，类型将不再反映现实）。
为了解决这个问题，SvelteKit 为您的每个端点和页面生成`.d.ts`文件：
```ts
/// file: .svelte-kit/types/src/routes/[foo]/[bar]/[baz]/$types.d.ts
/// link: true
import type * as Kit from '@sveltejs/kit';
type RouteParams = {
foo: string;
bar: string;
baz: string;
};
export type RequestHandler = Kit.RequestHandler<RouteParams>;
export type PageLoad = Kit.Load<RouteParams>;
```
这些文件可以导入到您的端点和页面中作为同级，多亏了 TypeScript 配置中的[`rootDirs`](https://www.typescriptlang.org/tsconfig#rootDirs)选项：
```js
/// file: src/routes/[foo]/[bar]/[baz]/+server.js
// @filename: $types.d.ts
import type * as Kit from '@sveltejs/kit';
type RouteParams = {
foo: string;
bar: string;
baz: string;
}
export type RequestHandler = Kit.RequestHandler<RouteParams>;
// @filename: index.js
// @errors: 2355 2322
// ---cut---
/** @type {import('./$types').RequestHandler} */
export async function GET({ params }) {
// ...
}
```
```js
/// file: src/routes/[foo]/[bar]/[baz]/+page.js
// @filename: $types.d.ts
import type * as Kit from '@sveltejs/kit';
type RouteParams = {
foo: string;
bar: string;
baz: string;
}
export type PageLoad = Kit.Load<RouteParams>;
// @filename: index.js
// @errors: 2355
// ---cut---
/** @type {import('./$types').PageLoad} */
export async function load({ params, fetch }) {
// ...
}
```
返回类型通过 `$types` 模块分别作为 `PageData` 和 `LayoutData` 可用，而所有 `Actions` 返回值的并集则可用作 `ActionData`。
从版本 2.16.0 开始，提供了两种额外的辅助类型：\``PageProps`\`定义了\``data: PageData`\`，以及当定义了操作时，\``form: ActionData`\`，而\``LayoutProps`\`定义了\``data: LayoutData`\`，以及\``children: Snippet`\`。
```svelte
<!--- file: src/routes/+page.svelte --->
<script>
/** @type {import('./$types').PageProps} */
let { data, form } = $props();
</script>
```
> \[!旧版\] 在 2.16.0 之前：
>
> ```svelte
> <!--- file: src/routes/+page.svelte --->
> <script>
> /** @type {{ data: import('./$types').PageData, form: import('./$types').ActionData }} */
> let { data, form } = $props();
> </script>
> ```
>
> 使用 Svelte 4：
>
> ```svelte
> <!--- file: src/routes/+page.svelte --->
> <script>
> /** @type {import('./$types').PageData} */
> export let data;
> /** @type {import('./$types').ActionData} */
> export let form;
> </script>
> ```
> \[!注意\] 要使此功能正常工作，您的自己的 `tsconfig.json` 或 `jsconfig.json` 应从生成的 `.svelte-kit/tsconfig.json` 扩展（其中 `.svelte-kit` 是您的 [`outDir`](configuration#outDir)）：
>
> `{ "extends": "./.svelte-kit/tsconfig.json" }`
###
默认 tsconfig.json
生成的 `.svelte-kit/tsconfig.json` 文件包含多种选项。其中一些是根据您的项目配置自动生成的，通常在没有充分理由的情况下不应更改：
```json
/// file: .svelte-kit/tsconfig.json
{
"compilerOptions": {
"paths": {
"$lib": ["../src/lib"],
"$lib/*": ["../src/lib/*"]
},
"rootDirs": ["..", "./types"]
},
"include": [
"ambient.d.ts",
"non-ambient.d.ts",
"./types/**/$types.d.ts",
"../vite.config.js",
"../vite.config.ts",
"../src/**/*.js",
"../src/**/*.ts",
"../src/**/*.svelte",
"../tests/**/*.js",
"../tests/**/*.ts",
"../tests/**/*.svelte"
],
"exclude": [
"../node_modules/**",
"../src/service-worker.js",
"../src/service-worker/**/*.js",
"../src/service-worker.ts",
"../src/service-worker/**/*.ts",
"../src/service-worker.d.ts",
"../src/service-worker/**/*.d.ts"
]
}
```
其他人需要 SvelteKit 正常运行，除非你了解自己在做什么，否则应保持不变：
```json
/// file: .svelte-kit/tsconfig.json
{
"compilerOptions": {
// this ensures that types are explicitly
// imported with `import type`, which is
// necessary as Svelte/Vite cannot
// otherwise compile components correctly
"verbatimModuleSyntax": true,
// Vite compiles one TypeScript module
// at a time, rather than compiling
// the entire module graph
"isolatedModules": true,
// Tell TS it's used only for type-checking
"noEmit": true,
// This ensures both `vite build`
// and `svelte-package` work correctly
"lib": ["esnext", "DOM", "DOM.Iterable"],
"moduleResolution": "bundler",
"module": "esnext",
"target": "esnext"
}
}
```
## $lib
这是一个简单的别名，指向 `src/lib` 或指定的任何目录，例如 [`config.kit.files.lib`](configuration#files)。它允许您在不使用 `../../../../` 无聊的路径的情况下访问常用组件和实用模块。
### $lib/server
子目录位于`$lib`中。SvelteKit 将阻止您将`$lib/server`中的任何模块导入到客户端代码中。请参阅[仅服务器端模块](server-only-modules)。
## app.d.ts
The `app.d.ts` 文件是您应用程序的环境类型所在之处，即无需显式导入即可使用的类型。
始终是此文件的一部分是 `App` 命名空间。此命名空间包含几个影响您交互的某些 SvelteKit 功能的类型的形状。
##
错误
定义了预期和意外错误的通用形状。预期错误通过使用`error`函数抛出。意外错误由`handleError`钩子处理，这些钩子应返回此形状。
`接口 Error {/*…*/}`
`消息：字符串；`
##
本地
接口定义了 `event.locals`，该变量可在服务器 [钩子](/docs/kit/hooks)（`handle` 和 `handleError`）、仅服务器 `load` 函数以及 `+server.js` 文件中访问。
`接口 Locals {}`
##
页面数据
定义了[页面数据状态](/docs/kit/$app-state#page)的通用形状以及\[ $page.data store](/docs/kit/$ app-stores#page) - 即，所有页面之间共享的数据。在`./$types`中的`Load`和`ServerLoad`函数将被相应地缩小。对于仅在特定页面上存在的数据，使用可选属性。不要添加索引签名（`[key: string]: any`）。
`接口 PageData {}`
##
页面状态
页面状态对象 `page.state` 的形状，可以使用来自 `$app/navigation` 的 [`pushState`](/docs/kit/$app-navigation#pushState) 和 [`replaceState`](/docs/kit/$app-navigation#replaceState) 函数进行操作。
`页面状态接口 {}`
##
平台
如果您的适配器通过 [平台特定上下文](/docs/kit/adapters#Platform-specific-context) 通过 `event.platform` 提供，您可以在此指定它。
`平台接口 {}`