a b c

``` # Service workers Service Worker は、アプリ内部でネットワークリクエストを処理するプロキシサーバーとして機能します。これによりアプリをオフラインで動作させることが可能になります。もしオフラインサポートが不要な場合（または構築するアプリの種類によって現実的に実装できない場合）でも、ビルドした JS と CSS を事前にキャッシュしてナビゲーションを高速化するために Service Worker を使用する価値はあります。 SvelteKit では、`src/service-worker.js` ファイル (や `src/service-worker/index.js`) がある場合、バンドルされ、自動的に登録されます。必要に応じて、[service worker の ロケーション](configuration#files) を変更することができます。 service worker を独自のロジックで登録する必要がある場合や、その他のソリューションを使う場合は、[自動登録を無効化](configuration#serviceWorker) することができます。デフォルトの登録方法は次のようなものです: ```js if ('serviceWorker' in navigator) { addEventListener('load', function () { navigator.serviceWorker.register('./path/to/service-worker.js'); }); } ``` ## service worker の内部では service worker の内部では、[`$service-worker` モジュール]($service-worker) にアクセスでき、これによって全ての静的なアセット、ビルドファイル、プリレンダリングページへのパスが提供されます。また、アプリのバージョン文字列 (一意なキャッシュ名を作成するのに使用できます) と、デプロイメントの `base` パスが提供されます。Vite の設定に `define` (グローバル変数の置換に使用) を指定している場合、それはサーバー/クライアントのビルドだけでなく、service worker にも適用されます。 次の例では、ビルドされたアプリと `static` にあるファイルをすぐに(eagerly)キャッシュし、その他全てのリクエストはそれらの発生時にキャッシュします。これにより、各ページは一度アクセスするとオフラインで動作するようになります。 ```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()); }); ``` > [!NOTE] キャッシュにはご注意ください！ 場合によっては、オフラインでは利用できないデータよりも古くなったデータのほうが悪いことがあります。ブラウザはキャッシュが一杯になると空にするため、ビデオファイルのような大きなアセットをキャッシュする場合にもご注意ください。 ## 開発中は(During development) service worker はプロダクション向けにはバンドルされますが、開発中はバンドルされません。そのため、[modules in service workers](https://web.dev/es-modules-in-sw) をサポートするブラウザのみ、開発時にもそれを使用することができます。service worker を手動で登録する場合、開発時に `{ type: 'module' }` オプションを渡す必要があります: ```js import { dev } from '$app/environment'; navigator.serviceWorker.register('/service-worker.js', { type: dev ? 'module' : 'classic' }); ``` > [!NOTE] `build` と `prerendered` は開発中は空配列です ## 型安全性(Type safety) service worker に適切な型を設定するには、マニュアルで設定が必要です。`service-worker.js` の中で、ファイルの先頭に以下を追加してください: ```original-js /// /// /// /// const sw = /** @type {ServiceWorkerGlobalScope} */ (/** @type {unknown} */ (self)); ``` ```generated-ts /// /// /// /// const sw = self as unknown as ServiceWorkerGlobalScope; ``` これにより、`HTMLElement` のような service worker の中では使用できない DOM の型付けへのアクセスが無効になり、正しい global が初期化されます。`self` を `sw` に再代入することで、プロセス内で型をキャストすることができます (いくつか方法がありますが、これが追加のファイルを必要としない最も簡単な方法です)。ファイルの残りの部分では、`self` の代わりに `sw` を使用します。SvelteKit の型を参照することで、`$service-worker` import に適切な型定義があることを保証することができます。もし `$env/static/public` をインポートする場合は、そのインポートに `// @ts-ignore` を追加するか、`/// ` を reference types に追加する必要があります。 ## その他のソリューション SvelteKit の service worker 実装は意図的に低レベル(low-level)です。より本格的な、よりこだわりが強い(opinionated)ソリューションが必要な場合は、[Vite PWA plugin](https://vite-pwa-org.netlify.app/frameworks/sveltekit.html) のようなソリューションをご覧になることをおすすめしております、こちらは [Workbox](https://web.dev/learn/pwa/workbox) を使用しています。service worker に関する一般的な情報をもっとお探しであれば、[MDN web docs](https://developer.mozilla.org/ja/docs/Web/API/Service_Worker_API/Using_Service_Workers) をおすすめします。 # Server-only modules 良き友人のように、SvelteKit はあなたの秘密を守ります。バックエンドとフロントエンドが同じリポジトリにある場合、機密データをフロントエンドのコードに誤ってインポートしてしまうことが簡単に起こってしまいます (例えば、API キーを持つ環境変数など)。SvelteKit はこれを完全に防ぐ方法を提供します: サーバー専用のモジュール(server-only modules)です ## Private environment variables [`$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) のようなサーバー上でのみ実行されるモジュールにのみインポートすることが可能です。 ## Server-only utilities The [`$app/server`]($app-server) module, which contains a [`read`]($app-server#read) function for reading assets from the filesystem, can likewise only be imported by code that runs on the server. ## Your modules モジュールをサーバー専用にするには2通りの方法があります: - ファイル名に `.server` を付けます。例: `secrets.server.js` - モジュールを `$lib/server` に置きます。例: `$lib/server/secrets.js` ## How it works パブリックに公開されるコード (public-facing code) にサーバー専用のコードを (直接的かまたは間接的かにかかわらず) インポートすると… ```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 にシークレットなコードが残ってしまう可能性があり、このインポートチェーンは安全ではないと考えられます。 この機能は動的なインポート(dynamic imports)でも動作し、``await import(`./${foo}.js`)`` のような補完されたインポートに対しても有効ですが、小さい注意点があります。もしパブリックに公開されるコードとサーバー専用のモジュールの間に2つ以上の dynamic imports がある場合、コードが最初にロードされるときに不正なインポートが検出されない可能性があります。 > [!NOTE] Vitest のようなユニットテストフレームワークはサーバー専用のコードと公開されるコードを区別しません。そのため、テストの実行中、つまり `process.env.TEST === 'true'` となっているときは、不正なインポートの検出は無効化されます。 ## その他の参考資料 - [Tutorial: Environment variables](/tutorial/kit/env-static-private) # Snapshots 例えばサイドバーのスクロールポジションや、`` 要素の中身などの、一時的な DOM の状態(state)は、あるページから別のページに移動するときに破棄されます。 例えば、ユーザーがフォームに入力し、それを送信する前に別のページに移動してからまた戻ってきた場合や、ページをリフレッシュした場合、フォームに入力されていた値は失われます。入力内容を保持しておくことが重要な場合、DOM の状態を _スナップショット(snapshot)_ として記録することができ、ユーザーが戻ってきたときに復元することができます。 これを行うには、`+page.svelte` や `+layout.svelte` で、`capture` メソッドと `restore` メソッドを持つ `snapshot` オブジェクトをエクスポートします: ```svelte

Comment <button>Post comment</button> </form> ``` このページから離れるとき、ページが更新される直前に `capture` 関数が呼ばれ、戻り値がブラウザの history スタックの現在のエントリーに関連付けられます。もしこのページに戻ってきた場合、ページが更新されるとすぐに保存された値とともに `restore` 関数が呼ばれます。 データは `sessionStorage` に永続化できるように、JSON としてシリアライズ可能でなければなりません。これにより、ページがリロードされたときや、ユーザーが別のサイトから戻ってきたときにも、状態を復元することができます。 > [!NOTE] 大きすぎるオブジェクトを `capture` から返さないようにしてください。一度 capture されたオブジェクトは、そのセッションの間はメモリ上に保持されるので、極端な場合には、大きすぎて `sessionStorage` に永続化できない可能性があります。 # Shallow routing As you navigate around a SvelteKit app, you create _history entries_. Clicking the back and forward buttons traverses through this list of entries, re-running any `load` functions and replacing page components as necessary. Sometimes, it's useful to create history entries _without_ navigating. For example, you might want to show a modal dialog that the user can dismiss by navigating back. This is particularly valuable on mobile devices, where swipe gestures are often more natural than interacting directly with the UI. In these cases, a modal that is _not_ associated with a history entry can be a source of frustration, as a user may swipe backwards in an attempt to dismiss it and find themselves on the wrong page. SvelteKit makes this possible with the [`pushState`]($app-navigation#pushState) and [`replaceState`]($app-navigation#replaceState) functions, which allow you to associate state with a history entry without navigating. For example, to implement a history-driven modal: ```svelte <!--- file: +page.svelte ---> <script> import { pushState } from '$app/navigation'; import { page } from '$app/state'; import Modal from './Modal.svelte'; function showModal() { pushState('', { showModal: true }); } </script> {#if page.state.showModal} <Modal close={() => history.back()} /> {/if} ``` The modal can be dismissed by navigating back (unsetting `page.state.showModal`) or by interacting with it in a way that causes the `close` callback to run, which will navigate back programmatically. ## API The first argument to `pushState` is the URL, relative to the current URL. To stay on the current URL, use `''`. The second argument is the new page state, which can be accessed via the [page object]($app-state#page) as `page.state`. You can make page state type-safe by declaring an [`App.PageState`](types#PageState) interface (usually in `src/app.d.ts`). To set page state without creating a new history entry, use `replaceState` instead of `pushState`. > [!LEGACY] > `page.state` from `$app/state` was added in SvelteKit 2.12. If you're using an earlier version or are using Svelte 4, use `$page.state` from `$app/stores` instead. ## Loading data for a route When shallow routing, you may want to render another `+page.svelte` inside the current page. For example, clicking on a photo thumbnail could pop up the detail view without navigating to the photo page. For this to work, you need to load the data that the `+page.svelte` expects. A convenient way to do this is to use [`preloadData`]($app-navigation#preloadData) inside the `click` handler of an `<a>` element. If the element (or a parent) uses [`data-sveltekit-preload-data`](link-options#data-sveltekit-preload-data), the data will have already been requested, and `preloadData` will reuse that request. ```svelte <!--- file: src/routes/photos/+page.svelte ---> <script> import { preloadData, pushState, goto } from '$app/navigation'; import { page } from '$app/state'; import Modal from './Modal.svelte'; import PhotoPage from './[id]/+page.svelte'; let { data } = $props(); </script> {#each data.thumbnails as thumbnail} <a href="/photos/{thumbnail.id}" onclick={async (e) => { 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); } }} > <img alt={thumbnail.alt} src={thumbnail.src} /> </a> {/each} {#if page.state.selected} <Modal onclose={() => history.back()}> <!-- pass page data to the +page.svelte component, just like SvelteKit would on navigation --> <PhotoPage data={page.state.selected} /> </Modal> {/if} ``` ## Caveats During server-side rendering, `page.state` is always an empty object. The same is true for the first page the user lands on — if the user reloads the page (or returns from another document), state will _not_ be applied until they navigate. Shallow routing is a feature that requires JavaScript to work. Be mindful when using it and try to think of sensible fallback behavior in case JavaScript isn't available. # Packaging SvelteKit では、アプリを構築するだけでなく、`@sveltejs/package` パッケージを使用してコンポーネントライブラリを構築することもできます (`npx sv create` にはこれを設定するためのオプションがあります)。 アプリを作成するとき、`src/routes` のコンテンツが公開される部分となります。[`src/lib`]($lib) にはアプリの内部ライブラリが含まれます。 コンポーネントライブラリは SvelteKit アプリと同じ構造ですが、`src/lib` が公開される部分である点が異なります。パッケージの公開にはプロジェクトの最上位(root)の `package.json` が使用されます。`src/routes` を、ライブラリに付属するドキュメントやデモサイト、または開発中に使用するサンドボックスにすることもあるでしょう。 `@sveltejs/package` の `svelte-package` コマンドを実行すると、`src/lib` の中身を取り込み、以下を含む `dist` ([設定で変更](#Options)できます) ディレクトリを生成します: - `src/lib` にある全てのファイル。Svelte コンポーネントはプリプロセスされ、TypeScript ファイルは JavaScript にトランスパイルされます。 - Svelte、JavaScript、TypeScript ファイル向けに生成される型定義 (`d.ts` ファイル)。このために、`typescript >= 4.0.0` をインストールする必要があります。型定義はその実装と同じ場所に配置され、手書きの `d.ts` ファイルはそのままコピーされます。[生成を無効](#Options)にすることもできますが、それはおすすめできません。あなたのライブラリを使用する人は TypeScript を使用しているかもしれません。その場合、この型定義ファイルが必要になります。 > [!NOTE] `@sveltejs/package` バージョン1は `package.json` を生成していましたが、この仕様は変更され、現在はプロジェクトの `package.json` を使用しそれが正しいか検証するようになりました。もしまだバージョン1を使用している場合は、[この PR](https://github.com/sveltejs/kit/pull/8922) にある移行手順(Migration instructions)をご覧ください。 ## package.json の構造 <!--Anatomy-of-a-package.json--> 公開するライブラリをビルドするのであれば、`package.json` の内容がとても重要になります。これを通して、パッケージのエントリーポイントや、どのファイルを npm に公開するか、そしてあなたのライブラリの依存関係を設定することができます。それでは、重要なフィールドをひとつずつ見ていきましょう。 ### name これはパッケージの名前です。他の人はこの名前を使用してインストールすることになります。そして `https://npmjs.com/package/<name>` のように表示されるようになります。 ```json { "name": "your-library" } ``` 詳細については[こちら](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#name)をお読みください。 ### license すべてのパッケージにはライセンスフィールドがあるべきです。なぜなら、人々はこれによってどのように使用することが許可されているのか知ることができるからです。配布や保証なしの再利用に関してとても寛容で、非常にポピュラーなライセンスとして、`MIT` があります。 ```json { "license": "MIT" } ``` 詳細については[こちら](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#license)をお読みください。`LICENSE` ファイルもパッケージに含めるとよいでしょう。 ### files ここではどのファイルを npm にアップロードするかを設定します。出力先フォルダ (デフォルトは `dist`) も含める必要があります。`package.json` と `README` と `LICENSE` は常に含まれるようになっているため、指定する必要はありません。 ```json { "files": ["dist"] } ``` 不要なファイル (例えば単体テストや、`src/routes` からのみインポートされているモジュールなど) を除外するには、`.npmignore` ファイルにそれらを追加します。これによってより小さいパッケージとなり、インストールも速くなります。 詳細については[こちら](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#files)をお読みください。 ### exports `"exports"` フィールドにはパッケージのエントリーポイントを含めます。`npx sv create` を使用して新しいライブラリプロジェクトをセットアップした場合、単一の export として、パッケージの最上位(root)が設定されています: ```json { "exports": { ".": { "types": "./dist/index.d.ts", "svelte": "./dist/index.js" } } } ``` これにより、あなたのパッケージにはエントリーポイントが1つだけで、それは最上位(root)で、(以下のように)すべてここを通してインポートされるべきである、ということをバンドラーやツール類に伝えます: ```js // @errors: 2307 import { Something } from 'your-library'; ``` `types` と `svelte` キーは [export conditions](https://nodejs.org/api/packages.html#conditional-exports) です。これはツール類に、`your-library` インポートを検索する際にどのファイルをインポートするかを伝えるものです: - TypeScript は `types` condition を見て、型定義ファイルを検索します。型定義を公開しない場合は、この condition を省略します。 - Svelte を認識するツール類は `svelte` condition を見て、これが Svelte コンポーネントライブラリであることを認識します。Svelte コンポーネントをエクスポートせず、Svelte 以外のプロジェクトでも使用できるライブラリ (例えば Svelte store ライブラリ) を公開する場合、この condition を `default` に置き換えることができます。 > [!NOTE] 以前のバージョンの `@sveltejs/package` は `package.json` export も追加していましたが、現在は違います。すべてのツール類が明示的にエクスポートされていない `package.json` を扱うことができるようになったからです。 `exports` を好みに合わせて調整し、より多くのエントリーポイントを提供することができます。例えば、コンポーネントを再エクスポートする `src/lib/index.js` ファイルの代わりに、`src/lib/Foo.svelte` コンポーネントを直接公開したい場合、以下のような export map を作成できます… ```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'; ``` > [!NOTE] 型定義を提供している場合、これを行う際にさらなる注意が必要となることにお気をつけください。注意事項については[こちら](#TypeScript)をお読みください。 一般的に、exports map の各キーはユーザーがあなたのパッケージからなにかインポートするときに使用すべきパスであり、その値はインポートされるファイルへのパスか、またはそのファイルパスを含む export condition の map です。 `exports` の詳細については[こちら](https://nodejs.org/docs/latest-v18.x/api/packages.html#package-entry-points)をお読みください。 ### svelte これはツール類に Svelte コンポーネントライブラリを認識できるようにするレガシーなフィールドです。`svelte` [export condition](#Anatomy-of-a-package.json-exports) を使用している場合は必要ありませんが、まだ export condition を認識しない古いツールとの後方互換性のために残しておくとよいでしょう。あなたの最上位(root)のエントリーポイントを指しているはずです。 ```json { "svelte": "./dist/index.js" } ``` ### sideEffects The `sideEffects` field in `package.json` is used by bundlers to determine if a module may contain code that has side effects. A module is considered to have side effects if it makes changes that are observable from other scripts outside the module when it's imported. For example, side effects include modifying global variables or the prototype of built-in JavaScript objects. Because a side effect could potentially affect the behavior of other parts of the application, these files/modules will be included in the final bundle regardless of whether their exports are used in the application. It is a best practice to avoid side effects in your code. Setting the `sideEffects` field in `package.json` can help the bundler to be more aggressive in eliminating unused exports from the final bundle, a process known as tree-shaking. This results in smaller and more efficient bundles. Different bundlers handle `sideEffects` in various manners. While not necessary for Vite, we recommend that libraries state that all CSS files have side effects so that your library will be [compatible with webpack](https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free). This is the configuration that comes with newly created projects: ```json /// file: package.json { "sideEffects": ["**/*.css"] } ``` > If the scripts in your library have side effects, ensure that you update the `sideEffects` field. All scripts are marked as side effect free by default in newly created projects. If a file with side effects is incorrectly marked as having no side effects, it can result in broken functionality. If your package has files with side effects, you can specify them in an array: ```json /// file: package.json { "sideEffects": [ "**/*.css", "./dist/sideEffectfulFile.js" ] } ``` This will treat only the specified files as having side effects. ## TypeScript あなたが TypeScript を使用していないとしても、あなたのライブラリの型定義を公開したほうがよいでしょう。あなたのライブラリを使用する人が、適切なインテリセンスを得られるようになるからです。`@sveltejs/package` は型生成のプロセスをほとんど隠ぺい(opaque)してくれます。デフォルトでは、ライブラリをパッケージングする際、JavaScript、TypeScript、Svelte ファイル向けに型定義を自動生成します。あなたは [exports](#Anatomy-of-a-package.json-exports) map の `types` condition が正しいファイルを指しているか確認するだけです。`npx sv create` でライブラリプロジェクトを初期化すると、root export に `types` condition が設定されます。 しかし、root export 以外のもの、例えば `your-library/foo` インポートを提供する場合などは、型定義を提供する上でさらなる注意が必要です。残念ながら、TypeScript はデフォルトでは `{ "./foo": { "types": "./dist/foo.d.ts", ... }}` のような export に対して `types` condition を解決しません。代わりに、ライブラリの root からの相対で `foo.d.ts` を探します (つまり、`your-library/dist/foo.d.ts` ではなく `your-library/foo.d.ts` です)。これを修正する方法として、選択肢が2つあります: 1つ目の選択肢は、あなたのライブラリを使用する人に対し、`tsconfig.json` (または `jsconfig.json`) の `moduleResolution` オプション に `bundler` (TypeScript 5 から利用可能で、将来的にもベストかつ推奨のオプション) か `node16` か `nodenext` を設定してもらうように要求することです。これによって TypeScript が実際に exports map を見て正しく型を解決してくれるようになります。 2つ目の選択肢は、TypeScript の `typesVersions` 機能を使用(乱用)して、型を紐付けます。これは、TypeScript が TypeScript のバージョンによって異なる型定義をチェックするために使用している `package.json` 内のフィールドで、このためにパスマッピング機能があります。このパスマッピング機能を利用して、やりたいことを実現できます。上述の `foo` export の場合、対応する `typesVersions` はこのようになります: ```json { "exports": { "./foo": { "types": "./dist/foo.d.ts", "svelte": "./dist/foo.js" } }, "typesVersions": { ">4.0": { "foo": ["./dist/foo.d.ts"] } } } ``` `>4.0` は、TypeScript のバージョンが 4 より大きい場合、内側の map をチェックするよう TypeScript に伝えるものです (実際には常に true となるべきものです)。内側の map は TypeScript に `your-library/foo` に対する型付けが `./dist/foo.d.ts` にあることを伝えるためのもので、実質 `exports` condition を置き換えています。また、ワイルドカードとして `*` を自由に使用できるので、同じことを繰り返すことなくたくさんの型定義を一度で使用可能にすることができます。もし `typesVersions` を選択した場合、(`"index.d.ts": [..]` と定義されている) root import を含む全ての型のインポートを、これを通して宣言しなければならないことにご注意ください。 この機能についてより詳しい情報は[こちら](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html#version-selection-with-typesversions)でお読み頂けます。 ## ベストプラクティス <!--Best-practices--> 他の SvelteKit プロジェクトからのみ使用されることを想定しているのでなければ、`$app/environment` などの SvelteKit 固有のモジュールをあなたのパッケージで使用するのは避けたほうがよいでしょう。例えば、`import { browser } from '$app/environment'` を使用するのではなく、`import { BROWSER } from 'esm-env'` ([esm-env ドキュメント参照](https://github.com/benmccann/esm-env)) を使用します。また、`$app/state` や `$app/navigation` などに直接頼るのではなく、現在の URL や navigation action をプロパティとして渡すこともできます。より一般的な方法でアプリを書くことによって、テストや UI デモなどのツールのセットアップも簡単になります。 [エイリアス](configuration#alias) は `svelte.config.js` (`vite.config.js` や `tsconfig.json` ではなく) を経由して追加するようにしてください。`svelte-package` で処理されるからです。. パッケージに加えた変更がバグフィックスなのか、新機能なのか、それとも破壊的変更(breaking change)なのかをよく考えて、それに応じてパッケージのバージョンを更新する必要があります。もし既存のライブラリから `exports` やその中の `export` condition のパスを削除した場合、breaking change とみなされることにご注意ください。 ```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" }+++ } } ``` ## Options `svelte-package` は以下のオプションを受け付けます: - `-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 を検索します。 ## 公開(Publishing) 生成されたパッケージを公開するには: ```sh npm publish ``` ## 注意事項 <!--Caveats--> すべての相対ファイルインポートは、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 ファイル (プロプロセスされる) と TypeScript ファイル (JavaScript にトランスパイルされる) を覗いて、全てのファイルはそのままコピーされます。 # Auth Auth refers to authentication and authorization, which are common needs when building a web application. Authentication means verifying that the user is who they say they are based on their provided credentials. Authorization means determining which actions they are allowed to take. ## Sessions vs tokens After the user has provided their credentials such as a username and password, we want to allow them to use the application without needing to provide their credentials again for future requests. Users are commonly authenticated on subsequent requests with either a session identifier or signed token such as a JSON Web Token (JWT). Session IDs are most commonly stored in a database. They can be immediately revoked, but require a database query to be made on each request. In contrast, JWT generally are not checked against a datastore, which means they cannot be immediately revoked. The advantage of this method is improved latency and reduced load on your datastore. ## Integration points Auth [cookies](@sveltejs-kit#Cookies) can be checked inside [server hooks](hooks#Server-hooks). If a user is found matching the provided credentials, the user information can be stored in [`locals`](hooks#Server-hooks-handle). ## Guides [Lucia](https://lucia-auth.com/) is a reference for session-based web app auth. It contains example code snippets and projects for implementing session-based auth within SvelteKit and other JS projects. You can add code which follows the Lucia guide to your project with `npx sv create` when creating a new project or `npx sv add lucia` for an existing project. An auth system is tightly coupled to a web framework because most of the code lies in validating user input, handling errors, and directing users to the appropriate next page. As a result, many of the generic JS auth libraries include one or more web frameworks within them. For this reason, many users will find it preferrable to follow a SvelteKit-specific guide such as the examples found in [Lucia](https://lucia-auth.com/) rather than having multiple web frameworks inside their project. # Performance Out of the box, SvelteKit does a lot of work to make your applications as performant as possible: - Code-splitting, so that only the code you need for the current page is loaded - Asset preloading, so that 'waterfalls' (of files requesting other files) are prevented - File hashing, so that your assets can be cached forever - Request coalescing, so that data fetched from separate server `load` functions is grouped into a single HTTP request - Parallel loading, so that separate universal `load` functions fetch data simultaneously - Data inlining, so that requests made with `fetch` during server rendering can be replayed in the browser without issuing a new request - Conservative invalidation, so that `load` functions are only re-run when necessary - Prerendering (configurable on a per-route basis, if necessary) so that pages without dynamic data can be served instantaneously - Link preloading, so that data and code requirements for a client-side navigation are eagerly anticipated Nevertheless, we can't (yet) eliminate all sources of slowness. To eke out maximum performance, you should be mindful of the following tips. ## Diagnosing issues Google's [PageSpeed Insights](https://pagespeed.web.dev/) and (for more advanced analysis) [WebPageTest](https://www.webpagetest.org/) are excellent ways to understand the performance characteristics of a site that is already deployed to the internet. Your browser also includes useful developer tools for analysing your site, whether deployed or running locally: * Chrome - [Lighthouse](https://developer.chrome.com/docs/lighthouse/overview#devtools), [Network](https://developer.chrome.com/docs/devtools/network), and [Performance](https://developer.chrome.com/docs/devtools/performance) devtools * Edge - [Lighthouse](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/lighthouse/lighthouse-tool), [Network](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/network/), and [Performance](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/evaluate-performance/) devtools * Firefox - [Network](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/) and [Performance](https://hacks.mozilla.org/2022/03/performance-tool-in-firefox-devtools-reloaded/) devtools * Safari - [enhancing the performance of your webpage](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/Web_Inspector_Tutorial/EnhancingyourWebpagesPerformance/EnhancingyourWebpagesPerformance.html) Note that your site running locally in `dev` mode will exhibit different behaviour than your production app, so you should do performance testing in [preview](building-your-app#Preview-your-app) mode after building. ### Instrumenting If you see in the network tab of your browser that an API call is taking a long time and you'd like to understand why, you may consider instrumenting your backend with a tool like [OpenTelemetry](https://opentelemetry.io/) or [Server-Timing headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing). ## Optimizing assets ### Images Reducing the size of image files is often one of the most impactful changes you can make to a site's performance. Svelte provides the `@sveltejs/enhanced-img` package, detailed on the [images](images) page, for making this easier. Additionally, Lighthouse is useful for identifying the worst offenders. ### Videos Video files can be very large, so extra care should be taken to ensure that they're optimized: - Compress videos with tools such as [Handbrake](https://handbrake.fr/). Consider converting the videos to web-friendly formats such as `.webm` or `.mp4`. - You can [lazy-load videos](https://web.dev/articles/lazy-loading-video) located below the fold with `preload="none"` (though note that this will slow down playback when the user _does_ initiate it). - Strip the audio track out of muted videos using a tool like [FFmpeg](https://ffmpeg.org/). ### Fonts SvelteKit automatically preloads critical `.js` and `.css` files when the user visits a page, but it does _not_ preload fonts by default, since this may cause unnecessary files (such as font weights that are referenced by your CSS but not actually used on the current page) to be downloaded. Having said that, preloading fonts correctly can make a big difference to how fast your site feels. In your [`handle`](hooks#Server-hooks-handle) hook, you can call `resolve` with a `preload` filter that includes your fonts. You can reduce the size of font files by [subsetting](https://web.dev/learn/performance/optimize-web-fonts#subset_your_web_fonts) your fonts. ## Reducing code size ### Svelte version We recommend running the latest version of Svelte. Svelte 5 is smaller and faster than Svelte 4, which is smaller and faster than Svelte 3. ### Packages [`rollup-plugin-visualizer`](https://www.npmjs.com/package/rollup-plugin-visualizer) can be helpful for identifying which packages are contributing the most to the size of your site. You may also find opportunities to remove code by manually inspecting the build output (use `build: { minify: false }` in your [Vite config](https://vitejs.dev/config/build-options.html#build-minify) to make the output readable, but remember to undo that before deploying your app), or via the network tab of your browser's devtools. ### External scripts Try to minimize the number of third-party scripts running in the browser. For example, instead of using JavaScript-based analytics consider using server-side implementations, such as those offered by many platforms with SvelteKit adapters including [Cloudflare](https://www.cloudflare.com/web-analytics/), [Netlify](https://docs.netlify.com/monitor-sites/site-analytics/), and [Vercel](https://vercel.com/docs/analytics). To run third party scripts in a web worker (which avoids blocking the main thread), use [Partytown's SvelteKit integration](https://partytown.builder.io/sveltekit). ### Selective loading Code imported with static `import` declarations will be automatically bundled with the rest of your page. If there is a piece of code you need only when some condition is met, use the dynamic `import(...)` form to selectively lazy-load the component. ## Navigation ### Preloading You can speed up client-side navigations by eagerly preloading the necessary code and data, using [link options](link-options). This is configured by default on the `<body>` element when you create a new SvelteKit app. ### Non-essential data For slow-loading data that isn't needed immediately, the object returned from your `load` function can contain promises rather than the data itself. For server `load` functions, this will cause the data to [stream](load#Streaming-with-promises) in after the navigation (or initial page load). ### Preventing waterfalls One of the biggest performance killers is what is referred to as a _waterfall_, which is a series of requests that is made sequentially. This can happen on the server or in the browser. - Asset waterfalls can occur in the browser when your HTML requests JS which requests CSS which requests a background image and web font. SvelteKit will largely solve this class of problems for you by adding [`modulepreload`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/modulepreload) tags or headers, but you should view [the network tab in your devtools](#Diagnosing-issues) to check whether additional resources need to be preloaded. Pay special attention to this if you use web [fonts](#Optimizing-assets-Fonts) since they need to be handled manually. - If a universal `load` function makes an API call to fetch the current user, then uses the details from that response to fetch a list of saved items, and then uses _that_ response to fetch the details for each item, the browser will end up making multiple sequential requests. This is deadly for performance, especially for users that are physically located far from your backend. Avoid this issue by using [server `load` functions](load#Universal-vs-server) where possible. - Server `load` functions are also not immune to waterfalls (though they are much less costly since they rarely involve roundtrips with high latency). For example if you query a database to get the current user and then use that data to make a second query for a list of saved items, it will typically be more performant to issue a single query with a database join. ## Hosting Your frontend should be located in the same data center as your backend to minimize latency. For sites with no central backend, many SvelteKit adapters support deploying to the _edge_, which means handling each user's requests from a nearby server. This can reduce load times significantly. Some adapters even support [configuring deployment on a per-route basis](page-options#config). You should also consider serving images from a CDN (which are typically edge networks) — the hosts for many SvelteKit adapters will do this automatically. Ensure your host uses HTTP/2 or newer. Vite's code splitting creates numerous small files for improved cacheability, which results in excellent performance, but this does assume that your files can be loaded in parallel with HTTP/2. ## Further reading For the most part, building a performant SvelteKit app is the same as building any performant web app. You should be able to apply information from general performance resources such as [Core Web Vitals](https://web.dev/explore/learn-core-web-vitals) to any web experience you build. # Images Images can have a big impact on your app's performance. For best results, you should optimize them by doing the following: - generate optimal formats like `.avif` and `.webp` - create different sizes for different screens - ensure that assets can be cached effectively Doing this manually is tedious. There are a variety of techniques you can use, depending on your needs and preferences. ## Vite's built-in handling [Vite will automatically process imported assets](https://vitejs.dev/guide/assets.html) for improved performance. This includes assets referenced via the CSS `url()` function. Hashes will be added to the filenames so that they can be cached, and assets smaller than `assetsInlineLimit` will be inlined. Vite's asset handling is most often used for images, but is also useful for video, audio, etc. ```svelte <script> import logo from '$lib/assets/logo.png'; </script> <img alt="The project logo" src={logo} /> ``` ## @sveltejs/enhanced-img `@sveltejs/enhanced-img` is a plugin offered on top of Vite's built-in asset handling. It provides plug and play image processing that serves smaller file formats like `avif` or `webp`, automatically sets the intrinsic `width` and `height` of the image to avoid layout shift, creates images of multiple sizes for various devices, and strips EXIF data for privacy. It will work in any Vite-based project including, but not limited to, SvelteKit projects. > [!NOTE] As a build plugin, `@sveltejs/enhanced-img` can only optimize files located on your machine during the build process. If you have an image located elsewhere (such as a path served from your database, CMS, or backend), please read about [loading images dynamically from a CDN](#Loading-images-dynamically-from-a-CDN). > > **WARNING**: The `@sveltejs/enhanced-img` package is experimental. It uses pre-1.0 versioning and may introduce breaking changes with every minor version release. ### Setup Install: ```bash npm install --save-dev @sveltejs/enhanced-img ``` Adjust `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(),+++ sveltekit() ] }); ``` Building will take longer on the first build due to the computational expense of transforming images. However, the build output will be cached in `./node_modules/.cache/imagetools` so that subsequent builds will be fast. ### Basic usage Use in your `.svelte` components by using `<enhanced:img>` rather than `<img>` and referencing the image file with a [Vite asset import](https://vitejs.dev/guide/assets.html#static-asset-handling) path: ```svelte <enhanced:img src="./path/to/your/image.jpg" alt="An alt text" /> ``` At build time, your `<enhanced:img>` tag will be replaced with an `<img>` wrapped by a `<picture>` providing multiple image types and sizes. It's only possible to downscale images without losing quality, which means that you should provide the highest resolution image that you need — smaller versions will be generated for the various device types that may request an image. You should provide your image at 2x resolution for HiDPI displays (a.k.a. retina displays). `<enhanced:img>` will automatically take care of serving smaller versions to smaller devices. If you wish to add styles to your `<enhanced:img>`, you should add a `class` and target that. ### Dynamically choosing an image You can also manually import an image asset and pass it to an `<enhanced:img>`. This is useful when you have a collection of static images and would like to dynamically choose one or [iterate over them](https://github.com/sveltejs/kit/blob/0ab1733e394b6310895a1d3bf0f126ce34531170/sites/kit.svelte.dev/src/routes/home/Showcase.svelte). In this case you will need to update both the `import` statement and `<img>` element as shown below to indicate you'd like process them. ```svelte <script> import MyImage from './path/to/your/image.jpg?enhanced'; </script> <enhanced:img src={MyImage} alt="some alt text" /> ``` You can also use [Vite's `import.meta.glob`](https://vitejs.dev/guide/features.html#glob-import). Note that you will have to specify `enhanced` via a [custom query](https://vitejs.dev/guide/features.html#custom-queries): ```svelte <script> const imageModules = import.meta.glob( '/path/to/assets/*.{avif,gif,heif,jpeg,jpg,png,tiff,webp,svg}', { eager: true, query: { enhanced: true } } ) </script> {#each Object.entries(imageModules) as [_path, module]} <enhanced:img src={module.default} alt="some alt text" /> {/each} ``` ### Intrinsic Dimensions `width` and `height` are optional as they can be inferred from the source image and will be automatically added when the `<enhanced:img>` tag is preprocessed. With these attributes, the browser can reserve the correct amount of space, preventing [layout shift](https://web.dev/articles/cls). If you'd like to use a different `width` and `height` you can style the image with CSS. Because the preprocessor adds a `width` and `height` for you, if you'd like one of the dimensions to be automatically calculated then you will need to specify that: ```svelte <style> .hero-image img { width: var(--size); height: auto; } </style> ``` ### `srcset` and `sizes` If you have a large image, such as a hero image taking the width of the design, you should specify `sizes` so that smaller versions are requested on smaller devices. E.g. if you have a 1280px image you may want to specify something like: ```svelte <enhanced:img src="./image.png" sizes="min(1280px, 100vw)"/> ``` If `sizes` is specified, `<enhanced:img>` will generate small images for smaller devices and populate the `srcset` attribute. The smallest picture generated automatically will have a width of 540px. If you'd like smaller images or would otherwise like to specify custom widths, you can do that with the `w` query parameter: ```svelte <enhanced:img src="./image.png?w=1280;640;400" sizes="(min-width:1920px) 1280px, (min-width:1080px) 640px, (min-width:768px) 400px" /> ``` If `sizes` is not provided, then a HiDPI/Retina image and a standard resolution image will be generated. The image you provide should be 2x the resolution you wish to display so that the browser can display that image on devices with a high [device pixel ratio](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio). ### Per-image transforms By default, enhanced images will be transformed to more efficient formats. However, you may wish to apply other transforms such as a blur, quality, flatten, or rotate operation. You can run per-image transforms by appending a query string: ```svelte <enhanced:img src="./path/to/your/image.jpg?blur=15" alt="An alt text" /> ``` [See the imagetools repo for the full list of directives](https://github.com/JonasKruckenberg/imagetools/blob/main/docs/directives.md). ## Loading images dynamically from a CDN In some cases, the images may not be accessible at build time — e.g. they may live inside a content management system or elsewhere. Using a content delivery network (CDN) can allow you to optimize these images dynamically, and provides more flexibility with regards to sizes, but it may involve some setup overhead and usage costs. Depending on caching strategy, the browser may not be able to use a cached copy of the asset until a [304 response](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304) is received from the CDN. Building HTML to target CDNs allows using an `<img>` tag since the CDN can serve the appropriate format based on the `User-Agent` header, whereas build-time optimizations must produce `<picture>` tags with multiple sources. Finally, some CDNs may generate images lazily, which could have a negative performance impact for sites with low traffic and frequently changing images. CDNs can generally be used without any need for a library. However, there are a number of libraries with Svelte support that make it easier. [`@unpic/svelte`](https://unpic.pics/img/svelte/) is a CDN-agnostic library with support for a large number of providers. You may also find that specific CDNs like [Cloudinary](https://svelte.cloudinary.dev/) have Svelte support. Finally, some content management systems (CMS) which support Svelte (such as [Contentful](https://www.contentful.com/sveltekit-starter-guide/), [Storyblok](https://github.com/storyblok/storyblok-svelte), and [Contentstack](https://www.contentstack.com/docs/developers/sample-apps/build-a-starter-website-with-sveltekit-and-contentstack)) have built-in support for image handling. ## Best practices - For each image type, use the appropriate solution from those discussed above. You can mix and match all three solutions in one project. For example, you may use Vite's built-in handling to provide images for `<meta>` tags, display images on your homepage with `@sveltejs/enhanced-img`, and display user-submitted content with a dynamic approach. - Consider serving all images via CDN regardless of the image optimization types you use. CDNs reduce latency by distributing copies of static assets globally. - Your original images should have a good quality/resolution and should have 2x the width it will be displayed at to serve HiDPI devices. Image processing can size images down to save bandwidth when serving smaller screens, but it would be a waste of bandwidth to invent pixels to size images up. - For images which are much larger than the width of a mobile device (roughly 400px), such as a hero image taking the width of the page design, specify `sizes` so that smaller images can be served on smaller devices. - For important images, such as the [largest contentful paint (LCP)](https://web.dev/articles/lcp) image, set `fetchpriority="high"` and avoid `loading="lazy"` to prioritize loading as early as possible. - Give the image a container or styling so that it is constrained and does not jump around while the page is loading affecting your [cumulative layout shift (CLS)](https://web.dev/articles/cls). `width` and `height` help the browser to reserve space while the image is still loading, so `@sveltejs/enhanced-img` will add a `width` and `height` for you. - Always provide a good `alt` text. The Svelte compiler will warn you if you don't do this. - Do not use `em` or `rem` in `sizes` and change the default size of these measures. When used in `sizes` or `@media` queries, `em` and `rem` are both defined to mean the user's default `font-size`. For a `sizes` declaration like `sizes="(min-width: 768px) min(100vw, 108rem), 64rem"`, the actual `em` or `rem` that controls how the image is laid out on the page can be different if changed by CSS. For example, do not do something like `html { font-size: 62.5%; }` as the slot reserved by the browser preloader will now end up being larger than the actual slot of the CSS object model once it has been created. # Accessibility SvelteKit は、アプリにアクセシブルなプラットフォームをデフォルトで提供するよう努めています。Svelte の [コンパイル時のアクセシビリティチェック(compile-time accessibility checks)](../svelte/compiler-warnings) は、あなたがビルドする SvelteKit アプリケーションにも適用されます。 ここでは、SvelteKit の組み込みのアクセシビリティ(accessibility)機能がどのように動作するか、そしてこれらの機能が可能な限りうまく動作するようにするために必要なことについて説明します。SvelteKit はアクセシブルな基盤を提供しますが、アプリケーションのコードをアクセシブルにするのはあなたの責任であることを覚えておいてください。もし、アクセシビリティ(accessibility)についてよく知らないのであれば、このガイドの ["参考文献"](accessibility#Further-reading) セクションで、その他のリソースを参照してください。 私たちは、アクセシビリティ(accessibility)を正しく行うのは難しいことだと認識しています。SvelteKit のアクセシビリティ対応について改善を提案したい方は、[GitHub issue を作成](https://github.com/sveltejs/kit/issues) してください。 ## Route announcements 旧来のサーバーレンダリングアプリケーションでは、全てのナビゲーション (例えば、`<a>` タグをクリックするなど) で、ページのフルリロードを引き起こします。これが起こると、スクリーンリーダーやその他の支援技術が新しいページのタイトルを読み上げ、それによってユーザーはページが変更されたことを理解します。 SvelteKit では、ページ間のナビゲーションではページのリロードが発生しないため ([クライアントサイドルーティング](glossary#Routing)として知られる)、SvelteKit はナビゲーションごとに新しいページ名が読み上げられるように[ライブリージョン](https://developer.mozilla.org/ja/docs/Web/Accessibility/ARIA/ARIA_Live_Regions)をページに注入します。これは、`<title>` 要素を検査することで、アナウンスするページ名を決定します。 この動作のために、アプリの全ページにユニークで説明的なタイトルを付けるべきです。SvelteKit では、各ページに `<svelte:head>` 要素を配置することでこれを行うことができます: ```svelte <!--- file: src/routes/+page.svelte ---> <svelte:head> <title>Todo List</title> </svelte:head> ``` これにより、スクリーンリーダーやその他の支援技術が、ナビゲーション後に新しいページを識別することができるようになります。説明的なタイトルを提供することは、[SEO](seo#Manual-setup-title-and-meta) にとっても重要なことです。 ## フォーカス管理 <!--Focus-management--> 旧来のサーバーレンダリングアプリケーションでは、ナビゲーションでフォーカスがページのトップにリセットされます。これによって、キーボードやスクリーンリーダーを使用して web をブラウジングする方が、ページの先頭からやり取りできるようになります。 クライアントサイドルーティング中にこの挙動をシミュレートするために、SvelteKit は各ナビゲーションや [強化されたフォーム送信(enhanced form submission)](https://kit.svelte.jp/docs/form-actions#Progressive-enhancement) の後、`<body>` 要素にフォーカスを合わせます。1つ例外があります - [`autofocus`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus) 属性が付いている要素が存在する場合、SvelteKit はその要素にフォーカスを合わせます。この属性を使用するときは、[支援技術(assistive technology)に対する影響を必ず考慮](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus#accessibility_considerations)してください。 SvelteKit のフォーカス管理をカスタマイズしたい場合は、`afterNavigate` hook を使います: ```js /// <reference types="@sveltejs/kit" /> // ---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` オプション を受け付けます。このオプションは、フォーカスをリセットする代わりに、現在フォーカスされている要素にフォーカスを保持したままにします。このオプションを有効にする場合は、現在フォーカスされている要素がナビゲーション後にもまだ存在することを確かめてください。もしその要素が存在しなければ、ユーザーのフォーカスは失われ、支援技術のユーザーにとって混乱した体験になります。 ## The "lang" attribute デフォルトでは、SvelteKit のページテンプレートには、ドキュメントのデフォルト言語に英語が設定されています。もしコンテンツが英語でない場合、`src/app.html` の `<html>` 要素を更新し、正しい [`lang`](https://developer.mozilla.org/ja/docs/Web/HTML/Global_attributes/lang#accessibility) 属性を持たせる必要があります。これによって、ドキュメントを読む支援技術が正しい発音を使えるようになります。例えば、コンテンツがドイツ語の場合、`app.html` を以下のように更新してください: ```html /// file: src/app.html <html lang="de"> ``` コンテンツが複数の言語で使用可能な場合、開いているページの言語に基づいて `lang` 属性を設定できるようにする必要があります。これは、SvelteKit の [handle hook](hooks#Server-hooks-handle) を使用して行うことができます: ```html /// file: src/app.html <html lang="%lang%"> ``` ```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)) }); } ``` ## その他の参考情報 <!--Further-reading--> ほとんどの場合、アクセシブルな SvelteKit アプリを構築するのはアクセシブルな Web アプリを構築するのと同じです。以下の一般的なアクセシビリティ(accessibility)に関するリソースから得られる情報は、どんな Web エクスペリエンスを構築する場合でも適用できるはずです - [MDN Web Docs: Accessibility](https://developer.mozilla.org/en-US/docs/Learn/Accessibility) - [The A11y Project](https://www.a11yproject.com/) - [How to Meet WCAG (Quick Reference)](https://www.w3.org/WAI/WCAG21/quickref/) # SEO SEO で最も重要なのは、高品質なコンテンツを作ること、そしてそれが web 上で広くリンクされることです。しかし、ランクが高いサイトを構築するためにいくつか技術的に考慮すべきこともあります。 ## Out of the box ### SSR 近年、検索エンジンはクライアントサイドの JavaScript でレンダリングされたコンテンツのインデックスを改善してきましたが、サーバーサイドレンダリングされたコンテンツのほうがより頻繁に、より確実にインデックスされます。SvelteKit はデフォルトで SSR を採用しています。[`handle`](hooks#Server-hooks-handle) で無効にすることもできますが、適切な理由がない場合はそのままにしておきましょう。 > [!NOTE] SvelteKit のレンダリングは高度な設定が可能です。必要であれば、[動的なレンダリング(dynamic rendering)](https://developers.google.com/search/docs/advanced/javascript/dynamic-rendering) を実装することも可能です。一般的には推奨されません、SSR には SEO 以外のメリットもあるからです。 ### パフォーマンス <!--Performance--> [Core Web Vitals](https://web.dev/vitals/#core-web-vitals) のような指標は検索エンジンのランクに影響を与えます。Svelte と SvelteKit はオーバーヘッドが最小限であるため、ハイパフォーマンスなサイトを簡単に構築できです。Google の [PageSpeed Insights](https://pagespeed.web.dev/) や [Lighthouse](https://developers.google.com/web/tools/lighthouse) で、ご自身のサイトをテストすることができます。詳細は [パフォーマンスのページ](performance) をお読みください。 ### URLの正規化 <!--Normalized-urls--> SvelteKit は、末尾のスラッシュ(trailing slash)付きのパス名から、末尾のスラッシュが無いパス名にリダイレクトします ([設定](page-options#trailingSlash) で逆にできます)。URLの重複は、SEOに悪影響を与えます。 ## Manual setup ### <title> と <meta> <!--title-and-meta--> 全てのページで、よく練られたユニークな `<title>` と `<meta name="description">` を [`<svelte:head>`](../svelte/svelte-head) の内側に置くべきです。説明的な title と description の書き方に関するガイダンスと、検索エンジンにとってわかりやすいコンテンツを作るためのその他の方法については、Google の [Lighthouse SEO audits](https://web.dev/lighthouse-seo/) のドキュメントで見つけることができます。 > [!NOTE] よくあるパターンとしては、ページの [`load`](load) 関数から SEO 関連の `data` を返し、それを最上位の[レイアウト](routing#layout)の `<svelte:head>` で ([`page.data`]($app-state) として) 使用することです。 ### サイトマップ <!--Sitemaps--> [サイトマップ](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 現代の web 開発における不幸な現実として、サイトの [Accelerated Mobile Pages (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; ``` …最上位(root)の `+layout.js`/`+layout.server.js` の `csr` を無効にします… ```js /// file: src/routes/+layout.server.js export const csr = false; ``` …`amp` を `app.html` に追加します ```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>`); } } }); } ``` > [!NOTE] `amphtml-validator` を使用して変換された HTML を検証するのに、`handle` hook を利用するのは良いアイデアですが、非常に遅くなってしまうので、ページをプリレンダリングするときだけにしてください。 # Frequently asked questions ## Other resources [Svelte FAQ](../svelte/faq) と [`vite-plugin-svelte` FAQ](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md) も、これらのライブラリに起因する疑問点には役立ちますのでご参照ください。 ## What can I make with SvelteKit? SvelteKit can be used to create most kinds of applications. Out of the box, SvelteKit supports many features including: - Dynamic page content with [load](load) functions and [API routes](routing#server). - SEO-friendly dynamic content with [server-side rendering (SSR)](glossary#SSR). - User-friendly progressively-enhanced interactive pages with SSR and [Form Actions](form-actions). - Static pages with [prerendering](page-options#prerender). SvelteKit can also be deployed to a wide spectrum of hosted architectures via [adapters](adapters). In cases where SSR is used (or server-side logic is added without prerendering), those functions will be adapted to the target backend. Some examples include: - Self-hosted dynamic web applications with a [Node.js backend](adapter-node). - Serverless web applications with backend loaders and APIs deployed as remote functions. See [zero-config deployments](adapter-auto) for popular deployment options. - [Static pre-rendered sites](adapter-static) such as a blog or multi-page site hosted on a CDN or static host. Statically-generated sites are shipped without a backend. - [Single-page Applications (SPAs)](single-page-apps) with client-side routing and rendering for API-driven dynamic content. SPAs are shipped without a backend and are not server-rendered. This option is commonly chosen when bundling SvelteKit with an app written in PHP, .Net, Java, C, Golang, Rust, etc. - A mix of the above; some routes can be static, and some routes can use backend functions to fetch dynamic information. This can be configured with [page options](page-options) that includes the option to opt out of SSR. In order to support SSR, a JS backend — such as Node.js or Deno-based server, serverless function, or edge function — is required. It is also possible to write custom adapters or leverage community adapters to deploy SvelteKit to more platforms such as specialized server environments, browser extensions, or native applications. See [integrations](./integrations) for more examples and integrations. ## package.json の詳細をアプリケーションに含めるにはどうすればよいですか？ <!--How-do-I-include-details-from-package.json-in-my-application--> SvelteKit では [`svelte.config.js`](./configuration) が ES module であることを想定しているため、JSON ファイルを直接要求することはできません。アプリケーションに、アプリケーションのバージョン番号やその他の情報を `package.json` から読み込みたい場合は、このように JSON を読み込むことができます: ```js /// file: svelte.config.js // @filename: index.js /// <reference types="@types/node" /> import { URL } from 'node:url'; // ---cut--- import { readFileSync } from 'node:fs'; import { fileURLToPath } from 'node:url'; const path = fileURLToPath(new URL('package.json', import.meta.url)); const pkg = JSON.parse(readFileSync(path, 'utf8')); ``` ## パッケージをインクルードしようとするとエラーが発生するのですが、どうすれば直せますか？ <!--How-do-I-fix-the-error-I-m-getting-trying-to-include-a-package--> ライブラリのインクルードに関する問題は、ほとんどが不適切なパッケージングによるものです。ライブラリのパッケージングが Node.js に対応しているかどうかは、[publint の web サイト](https://publint.dev/) でチェックできます。 以下は、ライブラリが正しくパッケージングされているかどうかをチェックする際に気を付けるべき点です: - `exports` は `main` や `module` などの他のエントリーポイントのフィールドよりも優先されます。`exports` フィールドを追加すると、deep import を妨げることになるため、後方互換性が失われる場合があります。 - `"type": "module"` が指定されていない限り、ESM ファイルは `.mjs` で終わる必要があり、CommonJS ファイルは `.cjs` で終わる必要があります。 - `exports` が定義されていない場合、`main` を定義する必要があり、それは CommonJS ファイル か ESM ファイル でなければならず、前項に従わなければなりません。`module` フィールドが定義されている場合、ESM ファイルを参照している必要があります。 - Svelte コンポーネントは、コンパイルされていない `.svelte` ファイルとして配布し、パッケージに含まれる JS は ESM のみとして記述していなければなりません。TypeScript などのカスタムスクリプトや SCSS などのスタイル言語は、それぞれ vanilla JS と CSS にするために前処理(preprocess)をしなければなりません。Svelte ライブラリのパッケージングには、[`svelte-package`](./packaging) を使用することを推奨しています。このパッケージによって、これらの作業が行われます。 ライブラリが ESM バージョンを配布している場合、特に Svelte コンポーネントライブラリがその依存関係に含まれている場合、Vite を使用するとブラウザ上で最適に動作します。ライブラリの作者に ESM バージョンを提供するよう提案すると良いでしょう。しかし、CommonJS (CJS) の依存関係も上手く扱えるようにするため、デフォルトで、[`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)。Vite は `esbuild` を使ってそれらを ESM に変換します。 それでもまだ問題が解消されない場合は、[Vite の issue tracker](https://github.com/vitejs/vite/issues) と 該当のライブラリの issue tracker を検索することを推奨します。[`optimizeDeps`](https://vitejs.dev/config/#dep-optimization-options) や [`ssr`](https://vitejs.dev/config/#ssr-options) の設定値をいじることで問題を回避できる場合もありますが、これはあくまで一時的な回避策とし、問題のあるライブラリの修正を優先したほうが良いでしょう。 ## SvelteKit で view transitions API を使うにはどうすればよいですか？ <!--How-do-I-use-the-view-transitions-API-with-SvelteKit--> SvelteKit では [view transitions](https://developer.chrome.com/docs/web-platform/view-transitions/) 向けの特別なインテグレーションはありませんが、[`onNavigate`]($app-navigation#onNavigate) の中で `document.startViewTransition` を呼び出すことにより、クライアントサイドナビゲーション毎に view transition をトリガーすることができます。 ```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 ブログの ["Unlocking view transitions"](/blog/view-transitions) をご参照ください。 ## SvelteKit で X を使うにはどうすればよいですか？ <!--How-do-I-use-X-with-SvelteKit--> [ドキュメントのインテグレーションのセクション](./integrations) をしっかり読み込んでください。それでも問題が解決しない場合のために、よくある問題の解決策を以下に示します。 ### データベースのセットアップはどう行えばよいですか？ <!--How-do-I-setup-a-database--> データベースにクエリするコードを [サーバールート(server route)](./routing#server) に置いてください。.svelte ファイルの中でデータベースにクエリしないでください。コネクションをすぐにセットアップし、シングルトンとしてアプリ全体からクライアントにアクセスできるように `db.js` のようなものを作ると良いでしょう。`hooks.server.js` で1回セットアップするコードを実行し、データベースヘルパーを必要とするすべてのエンドポイントにインポートできます。 ### `document` や `window` に依存しているクライアントサイドオンリーなライブラリはどう使えばよいですか？ <!--How-do-I-use-a-client-side-only-library-that-depends-on-document-or-window--> もし `document` や `window` 変数にアクセスする必要があったり、クライアントサイドだけで実行するコードが必要な場合は、`browser` チェックでラップしてください: ```js /// <reference types="@sveltejs/kit" /> // ---cut--- import { browser } from '$app/environment'; if (browser) { // client-only code here } ``` コンポーネントが最初に DOM にレンダリングされた後にコードを実行したい場合は、`onMount` で実行することもできます: ```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` が自動的に no-op に置き換えられます: ```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 サーバーを使用するにはどうすれば良いですか？ <!--How-do-I-use-a-different-backend-API-server--> 外部の API サーバーにデータをリクエストするのに [`event.fetch`](./load#Making-fetch-requests) を使用することができますが、[CORS](https://developer.mozilla.org/ja/docs/Web/HTTP/CORS) に対応しなければならず、一般的にはリクエストのプリフライトが必要になり、結果として高レイテンシーになるなど、複雑になることにご注意ください。別のサブドメインへのリクエストも、追加の DNS ルックアップや TLS セットアップなどのためにレイテンシーが増加する可能性があります。この方法を使いたい場合は、[`handleFetch`](./hooks#Server-hooks-handleFetch) が参考になるかもしれません。 別の方法は、頭痛の種である CORS をバイパスするためのプロキシーをセットアップすることです。本番環境では、`/api` などのパスを API サーバーに書き換えます(rewrite)。ローカルの開発環境では、Vite の [`server.proxy`](https://vitejs.dev/config/server-options.html#server-proxy) オプションを使用します。 本番環境で書き換え(rewrite)をセットアップする方法は、デプロイ先のプラットフォームに依存します。もし、書き換える方法がなければ、代わりに [API route](./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` も転送(forward)する必要があることにご注意ください) ### ミドルウェア(middleware)を使うにはどうすればよいですか？ <!--How-do-I-use-middleware--> `adapter-node` は、プロダクションモードで使用するためのミドルウェアを自分のサーバで構築します。開発モードでは、Vite プラグインを使用して Vite にミドルウェア(middleware) を追加することができます。例えば: ```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 2 で動作しますか？ <!--Does-it-work-with-Yarn-2--> 多少は。Plug'n'Play 機能、通称 'pnp' は動きません (Node のモジュール解決アルゴリズムから逸脱しており、SvelteKitが[数多くのライブラリ](https://blog.sindresorhus.com/get-ready-for-esm-aa53530b3f77)とともに使用している[ネイティブの JavaScript モジュールではまだ動作しません](https://github.com/yarnpkg/berry/issues/638))。[`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc#nodeLinker) で `nodeLinker: 'node-modules'` を使用して pnp を無効にできますが、おそらく npm や [pnpm](https://pnpm.io/) を使用するほうが簡単でしょう。同じように高速で効率的ですが、互換性に頭を悩ませることはありません。 ### Yarn 3 を使用するにはどうすれば良いですか？ <!--How-do-I-use-with-Yarn-3--> 現時点の、最新の Yarn (version 3) の ESM サポート は [experimental](https://github.com/yarnpkg/berry/pull/2161) であるようです。 結果は異なるかもしれませんが、下記が有効なようです。 最初に新しいアプリケーションを作成します: ```sh yarn create svelte myapp cd myapp ``` And enable Yarn Berry: ```sh yarn set version berry yarn install ``` #### Yarn 3 global cache Yarn Berry の興味深い機能の1つに、ディスク上のプロジェクトごとに複数のコピーを持つのではなく、パッケージ用に単一のグローバルキャッシュを持つことができる、というのがあります。しかし、`enableGlobalCache` の設定を true にするとビルドが失敗するため、`.yarnrc.yml` ファイルに以下を追加することを推奨します: ```yaml nodeLinker: node-modules ``` これによってパッケージはローカルの node_modules ディレクトリにダウンロードされますが、上記の問題は回避され、現時点では Yarn の version 3 を使用するベストな方法となります。 # Integrations ## `vitePreprocess` プロジェクトに [`vitePreprocess`](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/preprocess.md) を含めることで、Vite がサポートする様々な CSS のフレーバー (PostCSS、SCSS、Less、Stylus、SugarSS) を使用することができます。プロジェクトを TypeScript でセットアップすると、TypeScript はデフォルトで含まれるようになります: ```js // svelte.config.js import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'; export default { preprocess: [vitePreprocess()] }; ``` You will also need to use a preprocessor if you're using TypeScript with Svelte 4. TypeScript is supported natively in Svelte 5 if you're using only the type syntax. To use more complex TypeScript syntax in Svelte 5, you will need still need a preprocessor and can use `vitePreprocess({ script: true })`. ## Adders `npx sv add` によって、様々な複雑なインテグレーションを単一のコマンドでセットアップすることができます: - prettier (formatting) - eslint (linting) - vitest (unit testing) - playwright (e2e testing) - lucia (auth) - tailwind (CSS) - drizzle (DB) - paraglide (i18n) - mdsvex (markdown) - storybook (frontend workshop) ## Directory Svelte と SvelteKit で使用できる [パッケージ](https://sveltesociety.dev/packages) や [テンプレート](https://sveltesociety.dev/templates) のリストは [sveltesociety.dev](https://sveltesociety.dev/) でご覧いただけます。 ## Additional integrations ### `svelte-preprocess` `svelte-preprocess` は、Pug、Babel、global styles のサポートなど、`vitePreprocess` には無い機能があります。しかし、`vitePreprocess` はより速く、設定が少ないため、デフォルトでは `vitePreprocess` が使用されます。SvelteKit は CoffeeScript を [サポートしていない](https://github.com/sveltejs/kit/issues/2920#issuecomment-996469815) ことにご注意ください。 `svelte-preprocess` をインストールするには `npm install --save-dev svelte-preprocess` を実行し、ご自身で [`svelte.config.js` に追加する](https://github.com/sveltejs/svelte-preprocess/blob/main/docs/usage.md#with-svelte-config) 必要があります。その後、`npm install -D sass` や `npm install -D less` など、[対応するライブラリのインストール](https://github.com/sveltejs/svelte-preprocess/blob/main/docs/getting-started.md) が必要になることが多いようです。 ## Vite plugins SvelteKit プロジェクトは Vite で構築されているため、Vite plugin を使用してプロジェクトを拡張することができます。利用可能な plugin のリストは [`vitejs/awesome-vite`](https://github.com/vitejs/awesome-vite?tab=readme-ov-file#plugins) をご覧ください。 ## Integration FAQs SvelteKit FAQ に [SvelteKit で X をする方法](./faq#How-do-I-use-X-with-SvelteKit) があるので、もしまだ不明点があるようでしたら役に立つかもしれません。 # Breakpoint Debugging In addition to the [`@debug`](../svelte/@debug) tag, you can also debug Svelte and SvelteKit projects using breakpoints within various tools and development environments. This includes both frontend and backend code. The following guides assume your JavaScript runtime environment is Node.js. ## Visual Studio Code With the built-in debug terminal, you can set up breakpoints in source files within VSCode. 1. Open the command palette: `CMD/Ctrl` + `Shift` + `P`. 2. Find and launch "Debug: JavaScript Debug Terminal". 3. Start your project using the debug terminal. For example: `npm run dev`. 4. Set some breakpoints in your client or server-side source code. 5. Trigger the breakpoint. ### Launch via debug pane You may alternatively set up a `.vscode/launch.json` in your project. To set one up automatically: 1. Go to the "Run and Debug" pane. 2. In the "Run" select menu, choose "Node.js...". 3. Select the "run script" that corresponds to your project, such as "Run script: dev". 4. Press the "Start debugging" play button, or hit `F5` to begin breakpoint debugging. Here's an example `launch.json`: ```json { "version": "0.2.0", "configurations": [ { "command": "npm run dev", "name": "Run development server", "request": "launch", "type": "node-terminal" } ] } ``` Further reading: <https://code.visualstudio.com/docs/editor/debugging>. ## Other Editors If you use a different editor, these community guides might be useful for you: - [WebStorm Svelte: Debug Your Application](https://www.jetbrains.com/help/webstorm/svelte.html#ws_svelte_debug) - [Debugging JavaScript Frameworks in Neovim](https://theosteiner.de/debugging-javascript-frameworks-in-neovim) ## Google Chrome and Microsoft Edge Developer Tools It's possible to debug Node.js applications using a browser-based debugger. > [!NOTE] Note this only works with debugging client-side SvelteKit source maps. 1. Run the `--inspect` flag when starting the Vite server with Node.js. For instance: `NODE_OPTIONS="--inspect" npm run dev` 2. Open your site in a new tab. Typically at `localhost:5173`. 3. Open your browser's dev tools, and click on the "Open dedicated DevTools for Node.js" icon near the top-left. It should display the Node.js logo. 4. Set up breakpoints and debug your application. You may alternatively open the debugger devtools by navigating to `chrome://inspect` in Google Chrome, or `edge://inspect` in Microsoft Edge. ## References - [Debugging Node.js](https://nodejs.org/en/learn/getting-started/debugging) # Migrating to SvelteKit v2 Upgrading from SvelteKit version 1 to version 2 should be mostly seamless. There are a few breaking changes to note, which are listed here. You can use `npx sv migrate sveltekit-2` to migrate some of these changes automatically. We highly recommend upgrading to the most recent 1.x version before upgrading to 2.0, so that you can take advantage of targeted deprecation warnings. We also recommend [updating to Svelte 4](../svelte/v4-migration-guide) first: Later versions of SvelteKit 1.x support it, and SvelteKit 2.0 requires it. ## `redirect` and `error` are no longer thrown by you Previously, you had to `throw` the values returned from `error(...)` and `redirect(...)` yourself. In SvelteKit 2 this is no longer the case — calling the functions is sufficient. ```js import { error } from '@sveltejs/kit' // ... ---throw error(500, 'something went wrong');--- +++error(500, 'something went wrong');+++ ``` `svelte-migrate` will do these changes automatically for you. If the error or redirect is thrown inside a `try {...}` block (hint: don't do this!), you can distinguish them from unexpected errors using [`isHttpError`](@sveltejs-kit#isHttpError) and [`isRedirect`](@sveltejs-kit#isRedirect) imported from `@sveltejs/kit`. ## path is required when setting cookies When receiving a `Set-Cookie` header that doesn't specify a `path`, browsers will [set the cookie path](https://www.rfc-editor.org/rfc/rfc6265#section-5.1.4) to the parent of the resource in question. This behaviour isn't particularly helpful or intuitive, and frequently results in bugs because the developer expected the cookie to apply to the domain as a whole. As of SvelteKit 2.0, you need to set a `path` when calling `cookies.set(...)`, `cookies.delete(...)` or `cookies.serialize(...)` so that there's no ambiguity. Most of the time, you probably want to use `path: '/'`, but you can set it to whatever you like, including relative paths — `''` means 'the current path', `'.'` means 'the current directory'. ```js /** @type {import('./$types').PageServerLoad} */ export function load({ cookies }) { cookies.set(name, value, +++{ path: '/' }+++); return { response } } ``` `svelte-migrate` will add comments highlighting the locations that need to be adjusted. ## Top-level promises are no longer awaited In SvelteKit version 1, if the top-level properties of the object returned from a `load` function were promises, they were automatically awaited. With the introduction of [streaming](/blog/streaming-snapshots-sveltekit) this behavior became a bit awkward as it forces you to nest your streamed data one level deep. As of version 2, SvelteKit no longer differentiates between top-level and non-top-level promises. To get back the blocking behavior, use `await` (with `Promise.all` to prevent waterfalls, where appropriate): ```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(...) changes `goto(...)` no longer accepts external URLs. To navigate to an external URL, use `window.location.href = url`. The `state` object now determines `$page.state` and must adhere to the `App.PageState` interface, if declared. See [shallow routing](shallow-routing) for more details. ## paths are now relative by default In SvelteKit 1, `%sveltekit.assets%` in your `app.html` was replaced with a relative path by default (i.e. `.` or `..` or `../..` etc, depending on the path being rendered) during server-side rendering unless the [`paths.relative`](configuration#paths) config option was explicitly set to `false`. The same was true for `base` and `assets` imported from `$app/paths`, but only if the `paths.relative` option was explicitly set to `true`. This inconsistency is fixed in version 2. Paths are either always relative or always absolute, depending on the value of [`paths.relative`](configuration#paths). It defaults to `true` as this results in more portable apps: if the `base` is something other than the app expected (as is the case when viewed on the [Internet Archive](https://archive.org/), for example) or unknown at build time (as is the case when deploying to [IPFS](https://ipfs.tech/) and so on), fewer things are likely to break. ## Server fetches are not trackable anymore Previously it was possible to track URLs from `fetch`es on the server in order to rerun load functions. This poses a possible security risk (private URLs leaking), and as such it was behind the `dangerZone.trackServerFetches` setting, which is now removed. ## `preloadCode` arguments must be prefixed with `base` SvelteKit exposes two functions, [`preloadCode`]($app-navigation#preloadCode) and [`preloadData`]($app-navigation#preloadData), for programmatically loading the code and data associated with a particular path. In version 1, there was a subtle inconsistency — the path passed to `preloadCode` did not need to be prefixed with the `base` path (if set), while the path passed to `preloadData` did. This is fixed in SvelteKit 2 — in both cases, the path should be prefixed with `base` if it is set. Additionally, `preloadCode` now takes a single argument rather than _n_ arguments. ## `resolvePath` has been removed SvelteKit 1 included a function called `resolvePath` which allows you to resolve a route ID (like `/blog/[slug]`) and a set of parameters (like `{ slug: 'hello' }`) to a pathname. Unfortunately the return value didn't include the `base` path, limiting its usefulness in cases where `base` was set. As such, SvelteKit 2 replaces `resolvePath` with a (slightly better named) function called `resolveRoute`, which is imported from `$app/paths` and which takes `base` into account. ```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 });+++ ``` `svelte-migrate` will do the method replacement for you, though if you later prepend the result with `base`, you need to remove that yourself. ## Improved error handling Errors are handled inconsistently in SvelteKit 1. Some errors trigger the `handleError` hook but there is no good way to discern their status (for example, the only way to tell a 404 from a 500 is by seeing if `event.route.id` is `null`), while others (such as 405 errors for `POST` requests to pages without actions) don't trigger `handleError` at all, but should. In the latter case, the resulting `$page.error` will deviate from the [`App.Error`](types#Error) type, if it is specified. SvelteKit 2 cleans this up by calling `handleError` hooks with two new properties: `status` and `message`. For errors thrown from your code (or library code called by your code) the status will be `500` and the message will be `Internal Error`. While `error.message` may contain sensitive information that should not be exposed to users, `message` is safe. ## Dynamic environment variables cannot be used during prerendering The `$env/dynamic/public` and `$env/dynamic/private` modules provide access to _run time_ environment variables, as opposed to the _build time_ environment variables exposed by `$env/static/public` and `$env/static/private`. During prerendering in SvelteKit 1, they are one and the same. As such, prerendered pages that make use of 'dynamic' environment variables are really 'baking in' build time values, which is incorrect. Worse, `$env/dynamic/public` is populated in the browser with these stale values if the user happens to land on a prerendered page before navigating to dynamically-rendered pages. Because of this, dynamic environment variables can no longer be read during prerendering in SvelteKit 2 — you should use the `static` modules instead. If the user lands on a prerendered page, SvelteKit will request up-to-date values for `$env/dynamic/public` from the server (by default from a module called `_env.js` — this can be configured with `config.kit.env.publicModule`) instead of reading them from the server-rendered HTML. ## `form` and `data` have been removed from `use:enhance` callbacks If you provide a callback to [`use:enhance`](form-actions#Progressive-enhancement-use:enhance), it will be called with an object containing various useful properties. In SvelteKit 1, those properties included `form` and `data`. These were deprecated some time ago in favour of `formElement` and `formData`, and have been removed altogether in SvelteKit 2. ## Forms containing file inputs must use `multipart/form-data` If a form contains an `<input type="file">` but does not have an `enctype="multipart/form-data"` attribute, non-JS submissions will omit the file. SvelteKit 2 will throw an error if it encounters a form like this during a `use:enhance` submission to ensure that your forms work correctly when JavaScript is not present. ## Generated `tsconfig.json` is more strict Previously, the generated `tsconfig.json` was trying its best to still produce a somewhat valid config when your `tsconfig.json` included `paths` or `baseUrl`. In SvelteKit 2, the validation is more strict and will warn when you use either `paths` or `baseUrl` in your `tsconfig.json`. These settings are used to generate path aliases and you should use [the `alias` config](configuration#alias) option in your `svelte.config.js` instead, to also create a corresponding alias for the bundler. ## `getRequest` no longer throws errors The `@sveltejs/kit/node` module exports helper functions for use in Node environments, including `getRequest` which turns a Node [`ClientRequest`](https://nodejs.org/api/http.html#class-httpclientrequest) into a standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. In SvelteKit 1, `getRequest` could throw if the `Content-Length` header exceeded the specified size limit. In SvelteKit 2, the error will not be thrown until later, when the request body (if any) is being read. This enables better diagnostics and simpler code. ## `vitePreprocess` is no longer exported from `@sveltejs/kit/vite` Since `@sveltejs/vite-plugin-svelte` is now a peer dependency, SvelteKit 2 no longer re-exports `vitePreprocess`. You should import it directly from `@sveltejs/vite-plugin-svelte`. ## Updated dependency requirements SvelteKit 2 requires Node `18.13` or higher, and the following minimum dependency versions: - `svelte@4` - `vite@5` - `typescript@5` - `@sveltejs/vite-plugin-svelte@3` (this is now required as a `peerDependency` of SvelteKit — previously it was directly depended upon) - `@sveltejs/adapter-cloudflare@3` (if you're using these adapters) - `@sveltejs/adapter-cloudflare-workers@2` - `@sveltejs/adapter-netlify@3` - `@sveltejs/adapter-node@2` - `@sveltejs/adapter-static@3` - `@sveltejs/adapter-vercel@4` `svelte-migrate` will update your `package.json` for you. As part of the TypeScript upgrade, the generated `tsconfig.json` (the one your `tsconfig.json` extends from) now uses `"moduleResolution": "bundler"` (which is recommended by the TypeScript team, as it properly resolves types from packages with an `exports` map in package.json) and `verbatimModuleSyntax` (which replaces the existing `importsNotUsedAsValues ` and `preserveValueImports` flags — if you have those in your `tsconfig.json`, remove them. `svelte-migrate` will do this for you). ## SvelteKit 2.12: $app/stores deprecated SvelteKit 2.12 introduced `$app/state` based on the [Svelte 5 runes API](/docs/svelte/what-are-runes). `$app/state` provides everything that `$app/stores` provides but with more flexibility as to where and how you use it. Most importantly, the `page` object is now fine-grained, e.g. updates to `page.state` will not invalidate `page.data` and vice-versa. As a consequence, `$app/stores` is deprecated and subject to be removed in SvelteKit 3. We recommend [upgrading to Svelte 5](/docs/svelte/v5-migration-guide), if you haven't already, and then migrate away from `$app/stores`. Most of the replacements should be pretty simple: Replace the `$app/stores` import with `$app/state` and remove the `$` prefixes from the usage sites. ```svelte <script> ---import { page } from '$app/stores';--- +++import { page } from '$app/state';+++ </script> ---{$page.data}--- +++{page.data}+++ ``` Use `npx sv migrate app-state` to auto-migrate most of your `$app/stores` usages inside `.svelte` components. # Sapper からの移行 SvelteKit は Sapper の後継であり、その設計の多くの要素を共有しています。 もし、既存の Sapper アプリを SvelteKit に移行する予定がある場合、いくつかの変更が必要になります。移行する際には、[examples](additional-resources#Examples) を見ていただくと参考になると思います。 ## package.json ### type: "module" `package.json` に `"type": "module"` を追加します。もし Sapper 0.29.3 以降を使用している場合は、インクリメンタルマイグレーションの一部として、このステップを他のステップとは別に行うことができます。 ### dependencies `polka` や `express` を使用している場合はそれを削除し、`sirv` や `compression` などのミドルウェア(middleware)も削除します。 ### devDependencies `devDependencies` から `sapper` を削除し、`@sveltejs/kit` と使用予定の [adapter](adapters)に置き換えます([次のセクション](migrating#Project-files-Configuration)をご覧ください)。 ### scripts `sapper` を参照しているスクリプトを全て更新します: - `sapper build` は、Node [adapter](adapters) を使用した `vite build` に更新します - `sapper export` は、static [adapter](adapters) を使用した `vite build` に更新します - `sapper dev` は `vite dev` に更新します - `node __sapper__/build` は `node build` に更新します ## プロジェクトファイル <!--Project-files--> アプリの大部分を占める `src/routes` の中はそのままで大丈夫ですが、いくつかのプロジェクトファイルを移動または更新する必要があります。 ### Configuration [こちら](configuration)に記載されている通り、`webpack.config.js` または `rollup.config.js` を `svelte.config.js` に置き換えてください。Svelte の preprocessor オプション は `config.preprocess` に移動してください。 [adapter](adapters) を追加する必要があります。`sapper build` は [adapter-node](https://github.com/sveltejs/kit/tree/main/packages/adapter-node) とおおよそ同じで、`sapper export` は [adapter-static](https://github.com/sveltejs/kit/tree/main/packages/adapter-static) とおおよそ同じですが、デプロイ先のプラットフォーム向けにデザインされた adapter を使用するのも良いでしょう。 [Vite](https://vitejs.dev) では自動的に処理されないファイルタイプのプラグインを使用している場合は、Vite において同等なことを行う方法を探し、[Vite config](project-structure#Project-files-vite.config.js) に追加する必要があります。 ### src/client.js SvelteKit にはこのファイルに相当するものはありません。カスタムロジック(`sapper.start(...)` 以降) は、`+layout.svelte` ファイルで、`onMount` コールバック内に記述してくさい。 ### src/server.js `adapter-node` を使用する場合は、[custom server](adapter-node#Custom-server) がこれと同等のものです。それ以外の場合は、同等のものに該当するものはありません。なぜなら SvelteKit アプリはサーバーレス環境でも実行可能だからです。 ### src/service-worker.js `@sapper/service-worker` からインポートするほとんどのものは、[`$service-worker`]($service-worker) に同等なものがあります: - `files` は変更されていません - `routes` は削除されました - `shell` は現在 `build` になりました - `timestamp` は現在 `version` になりました ### 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/node_modules Sapper アプリでよくあるパターンとして、内部ライブラリを `src/node_modules` 内のディレクトリに配置する、というものがあります。これは Vite だと動作しないため、代わりに [`src/lib`]($lib) を使用します。 ## ページとレイアウト <!--Pages-and-layouts--> ### 名前が変わったファイル <!--Renamed-files--> ルート(Routes)は曖昧さをなくすためフォルダ名のみで構成されるようになり、`+page.svelte` までのフォルダ名がルート(route)に対応するようになりました。概要は [ルーティングのドキュメント](routing) をご参照ください。以下は 新/旧 の比較です: | Old | New | | ------------------------- | ------------------------- | | routes/about/index.svelte | routes/about/+page.svelte | | routes/about.svelte | routes/about/+page.svelte | カスタムのエラーページコンポーネントは `_error.svelte` から `+error.svelte` にリネームしてください。また、どの `_layout.svelte` ファイルも、同様に `+layout.svelte` にリネームしてください。[その他のファイルは無視されます](routing#Other-files). ### Imports `@sapper/app` からインポートしていた `goto`、`prefetch`、`prefetchRoutes` は、[`$app/navigation`]($app-navigation) からインポートする `goto`、`preloadData`、`preloadCode` にそれぞれ置き換えてください。 `@sapper/app` からインポートしていた `stores` については置き換える必要があります — 以下の [Stores](migrating#Pages-and-layouts-Stores) をご覧ください。 `src/node_modules` にあるディレクトリからインポートしてたファイルは、[`$lib`]($lib) からのインポートに置き換えてください。 ### Preload 以前と同様に、ページやレイアウトではレンダリングが行われる前にデータをロードできる関数をエクスポートすることができます。 This function has been renamed from `preload` to [`load`](load), it now lives in a `+page.js` (or `+layout.js`) next to its `+page.svelte` (or `+layout.svelte`), and its API has changed. Instead of two arguments — `page` and `session` — there is a single `event` argument. There is no more `this` object, and consequently no `this.fetch`, `this.error` or `this.redirect`. Instead, you can get [`fetch`](load#Making-fetch-requests) from the input methods, and both [`error`](load#Errors) and [`redirect`](load#Redirects) are now thrown. ### Stores Sapper では、提供されるストアをこのように参照していたかと思います: ```js // @filename: ambient.d.ts declare module '@sapper/app'; // @filename: index.js // ---cut--- import { stores } from '@sapper/app'; const { preloading, page, session } = stores(); ``` `page` と `session` ストアはまだ存在しています。`preloading` は、`from` プロパティと `to` プロパティを含む `navigating` ストアに置き換えられました。`page` は `url`、`params` を持つようになりましたが、`path` と `query` はありません。 SvelteKit では、それらにアクセスする方法が異なります。`stores` は `getStores` になりましたが、[`$app/stores`]($app-stores) から直接 `navigating`、`page`、`session` をインポートできるので、ほとんどの場合は必要ありません。もしあなたが Svelte 5 と SvelteKit 2.12 以上をお使いなら、代わりに [`$app/state`]($app-state) の使用を検討してみてください。 ### ルーティング <!--Routing--> ルート(routes) の正規表現はもうサポートされていません。代わりに、[advanced route matching](advanced-routing#Matching) をお使いください。 ### Segments 以前までは、レイアウトコンポーネントは子のセグメントを表す `segment` プロパティを受け取っていましたが、この機能は削除されました。より柔軟な `$page.url.pathname` (や `page.url.pathname`) の値を使用し、お望みのセグメントを取得してください。 ### URLs Sapper では、相対 URL は、現在のページに対してではなく、base URL (`basepath` オプションが使用されていない限り、大抵の場合は `/`) に対して解決されていました。 これによって問題が発生していましたが、SvelteKit ではもうそのようなことはありません。相対 URL が現在のページ (または `load` 関数の `fetch` URL の場合は移動先のページ) に対して解決されるようになりました。多くの場合、(例えば、`/` 始まるような) ルート相対な URL を使用するほうが簡単です。なぜなら、それらの意図がコンテキストに依存しないからです。 ### <a> attributes - `sapper:prefetch` は `data-sveltekit-preload-data` になりました - `sapper:noscroll` は `data-sveltekit-noscroll` になりました ## Endpoints Sapper では、[サーバールート(server routes)](routing#server) は、Node の `http` モジュール によって公開される `req` と `res` オブジェクト(または Polka や Express などのフレームワークが提供するその拡張版) を受け取っていました。 SvelteKit は、アプリが動作する場所に依存しないように設計されています(Node サーバーで動作し、サーバーレスプラットフォームや Cloudflare Worker でも同様に動作します)。そのため、もう `req` と `res` を直接扱いません。エンドポイントを、新しいシグネチャに合わせて更新する必要があります。 環境非依存な動作をサポートするため、グローバルコンテキストで `fetch` が利用できるようになり、`node-fetch` や `cross-fetch` などのサーバーサイドの fetch 実装をインポートする必要がなくなりました。 ## インテグレーション <!--Integrations--> インテグレーションに関する詳細情報については [インテグレーション](./integrations) をご参照ください。 ### HTML minifier Sapper はデフォルトで `html-minifier` を含んでいました。SvelteKit はこれを含まないのですが、本番環境向けの依存関係(prod dependency)としてこれを追加し、[hook](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; } } }); } ``` サイトのプロダクションビルドをテストするのに `vite preview` を使用しているときは、`prerendering` が `false` となることにご注意ください。そのため、minify の結果を検証するには、ビルド済の HTML を直接確認する必要があります。 # Additional resources ## FAQs よくある問題の解決方法や役に立つ tips や tricks については、[SvelteKit FAQ](faq) をご覧ください。 [Svelte FAQ](../svelte/faq) と [`vite-plugin-svelte` FAQ](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md) も、これらのライブラリに起因する疑問点には役立つでしょう。 ## Examples 例として、数種類 SvelteKit サイトを作成し、公開しています: - [`sveltejs/realworld`](https://github.com/sveltejs/realworld) contains an example blog site - [A HackerNews clone](https://github.com/sveltejs/sites/tree/master/sites/hn.svelte.dev) - [`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) にも例が公開されています。なお、これらはメンテナーによって検証されておらず、最新ではない可能性もありますのでご注意ください。 ## サポート <!--Support--> [Discord](/chat) や [StackOverflow](https://stackoverflow.com/questions/tagged/sveltekit) でヘルプを求めることができます。他の方の時間を尊重するため、まずは FAQ、Googleまたは他の検索エンジン、issue tracker、Discord のチャット履歴などから、問題に関連する情報を検索してください。回答する方より質問する方のほうが多いので、こうすることでコミュニティをスケーラブルに発展させることができると思います。 > 日本語翻訳版 追記：上記のDiscordはSvelte本体のもので、英語でコミュニケーションが行われています。もし日本語で質問したり交流したいのであれば、[Svelte日本のDiscord](https://discord.com/invite/YTXq3ZtBbx)にどうぞ！ # Glossary SvelteKitのコアは、高度に設定可能(configurable)なレンダリングエンジンを提供します。このセクションでは、レンダリングについてディスカッションする際に使用されるいくつかの用語を説明します。これらのオプションを設定するためのリファレンスは、上記のドキュメントで提供されています。 ## CSR クライアントサイドレンダリング(Client-side rendering (CSR))とは、JavaScriptを使用してWebブラウザ上でページコンテンツを生成することです。 SvelteKit では、デフォルトでクライアントサイドレンダリングが使用されますが、[`csr = false` ページオプション](page-options#csr)で JavaScript をオフにすることができます。 ## ハイドレーション <!--Hydration--> Svelte コンポーネントは、何らかの状態を保存し、状態が更新されると DOM を更新します。SSR 中にデータをフェッチするとき、デフォルトでは SvelteKit はこのデータを保存し、サーバーレンダリングされた HTML と一緒にクライアントに送信します。それからコンポーネントは、同じ API エンドポイントを再度呼び出すことなく、クライアント側でそのデータを使用して初期化されます。そして Svelte はハイドレーション(Hydration)と呼ばれるプロセスで DOM が想定通りの状態にあることをチェックしてイベントリスナーをアタッチします。コンポーネントが完全にハイドレートされると、新しく作成された Svelte コンポーネントと同じように、プロパティの変更に反応(react)することができます。 SvelteKit では、デフォルトでページがハイドレーションされますが、[`csr = false` ページオプション](page-options#csr)で JavaScript をオフにすることができます。 ## プリレンダリング <!--Prerendering--> プリレンダリング(Prerendering)とは、ビルド時にページのコンテンツを計算し、表示のために HTML を保存しておくことを意味します。このアプローチは旧来のサーバーレンダリングページと同じ利点を持ちつつ、訪問者ごとにページを再計算する必要がないため、訪問者数の増加に対してほぼ無償でスケールします。トレードオフとしては、ビルドプロセスのコストがより高くなり、プリレンダリングされたコンテンツはアプリケーションの新しいバージョンをデプロイすることでしか更新できなくなります。 全てのページがプリレンダリングできるわけではありません。基本的なルールは次の通りです: コンテンツがプリレンダリング可能であると言うためには、それを直接表示する2人のユーザーが、サーバーから同じコンテンツを取得できなけれならず、かつ、そのページには [actions](form-actions) が含まれていてはいけません。全てのユーザーが同じプリレンダリングコンテンツを見ることができるのであれば、ページのパラメータに基づいてロードされるコンテンツはプリレンダリングが可能である点にご注意ください。 プリレンダリングされるページは静的なコンテンツに限りません。クライアントサイドでユーザ固有のデータをフェッチしてレンダリングする場合は、パーソナライズされたページを構築することができます。ただし、前述の通り、そのコンテンツに対して SSR を行わないことによるデメリットが発生することにご注意ください。 SvelteKit では、[`prerender` ページオプション](page-options#prerender) と、`svelte.config.js` の [`prerender` コンフィグ](configuration#prerender) によってプリレンダリングをコントロールできます。 ## ルーティング <!--Routing--> デフォルトでは、(リンクをクリックしたりブラウザの 進む または 戻る ボタンを使って)新しいページにナビゲートするとき、SvelteKit はナビゲーションをインターセプトし、ブラウザが移動先のページのリクエストをサーバーにリクエストする代わりに、それを処理します。それから SvelteKit は新しいページのコンポーネントをレンダリングし、そのときに順番に必要な API エンドポイントをコールし、クライアントの表示コンテンツを更新します。このような、ナビゲーションが行われる際にそれに応じてクライアント側でページを更新するプロセスのことを、クライアントサイドルーティングと呼びます。 SvelteKit では、デフォルトでクライアントサイドルーティングが使用されますが、[`data-sveltekit-reload`](link-options#data-sveltekit-reload) でこれをスキップすることができます。 ## SPA シングルページアプリ(single-page app (SPA))とは、サーバーへの全てのリクエストで単一のHTMLをロードし、コンテンツのクライアントサイドレンダリングをリクエストされたURLに基づいて行うアプリケーションのことです。全てのナビゲーションはクライアントサイドで(クライアントサイドルーティングと呼ばれるプロセスで)処理され、ページごとのコンテンツは更新されるが共通のレイアウト要素はほとんど更新されません。SPA は SSR を提供しないため、上記のような欠点があります。しかし、SEOが重要ではない、ユーザーが一貫したコンピューティング環境からアプリケーションにアクセスすることがわかっているような、ログインの背後にある複雑なビジネスアプリケーションなどの場合は、これらの欠点による大きな影響を受けません。 SvelteKit では、[`adapter-static` を使って SPA を構築](single-page-apps) することができます。 ## SSG 静的サイト生成(Static Site Generation (SSG))とは、全てのページがプリレンダリングされているサイトを指す用語です。SvelteKit は 静的サイト生成だけを行うために作られたわけではないので、その目的のために特別に作られたツールが非常に多くのページを効率的にレンダリングするのと同じようにはスケールしないかもしれません。しかし、目的に特化した SSG とは対照的に、SvelteKit はページごとに異なるレンダリングタイプをミックスしたりマッチさせたりすることができます。サイトを完全にプリレンダリングすることの利点の1つは、SSRを実行するためのサーバーを維持したり費用を払ったりする必要がないことです。一度生成すれば、そのサイトは CDN から提供することができ、"time to first byte" の優れたパフォーマンスにつながります。このデリバリーモデルはしばしば JAMstack と呼ばれます。 SvelteKit では、[`adapter-static`](adapter-static) を使用したり、[`prerender` ページオプション](page-options#prerender) や `svelte.config.js` の [`prerender` コンフィグ](configuration#prerender) で全ページをプリレンダリングするようにしたりすることで SSG を行うことができます。 ## SSR サーバーサイドレンダリング(Server-side rendering (SSR))とは、サーバー上でページコンテンツを生成することです。SSR は一般的に SEO の観点で好まれます。クライアントサイドで生成される動的なコンテンツをインデックスできる検索エンジンもありますが、その場合でもそれに時間がかかることがあります。知覚的なパフォーマンスも改善される傾向にあり、もしJavaScriptが失敗したり無効になっている場合でも([あなたが思うより頻繁に](https://kryogenix.org/code/browser/everyonehasjs.html)発生しています)、ユーザーがアプリにアクセスできるようになります。 SvelteKit では、デフォルトでページがサーバーサイドレンダリングされます。[`ssr` ページオプション](page-options#ssr) で SSR を無効化できます。 # @sveltejs/kit ```js // @noErrors import { Server, VERSION, error, fail, isActionFailure, isHttpError, isRedirect, json, 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. <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> ## 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"> - `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 - `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.js`. </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) a `fetch` request that happens inside a `load` function that runs on the server (or during pre-rendering) <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]` </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: { id: string | null }; ``` <div class="ts-block-property-details"> Info about the target route </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 - `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]`. </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]` </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 }) => 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"></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 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) => ReadableStream; ``` <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>; }) => 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'; ``` ## browser `true` if the app is running in the browser. <div class="ts-block"> ```dts const browser: boolean; ``` </div> ## building SvelteKit analyses your app during the `build` step by running it. During this process, `building` is `true`. This also applies during prerendering. <div class="ts-block"> ```dts const building: boolean; ``` </div> ## dev Whether the dev server is running. This is not guaranteed to correspond to `NODE_ENV` or `MODE`. <div class="ts-block"> ```dts const dev: boolean; ``` </div> ## version The value of `config.kit.version.name`. <div class="ts-block"> ```dts const version: string; ``` </div> # $app/forms ```js // @noErrors import { applyAction, deserialize, enhance } from '$app/forms'; ``` ## applyAction This action updates the `form` property of the current page with the given data and updates `page.status`. In case of an error, it redirects to the nearest error page. <div class="ts-block"> ```dts function applyAction< Success extends Record<string, unknown> | undefined, Failure extends Record<string, unknown> | undefined >( result: import('@sveltejs/kit').ActionResult< Success, Failure > ): Promise<void>; ``` </div> ## deserialize Use this function to deserialize the response from a form submission. Usage: ```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()); // ... } ``` <div class="ts-block"> ```dts function deserialize< Success extends Record<string, unknown> | undefined, Failure extends Record<string, unknown> | undefined >( result: string ): import('@sveltejs/kit').ActionResult<Success, Failure>; ``` </div> ## enhance This action enhances a `<form>` element that otherwise would work without JavaScript. The `submit` function is called upon submission with the given FormData and the `action` that should be triggered. If `cancel` is called, the form will not be submitted. You can use the abort `controller` to cancel the submission in case another one starts. If a function is returned, that function is called with the response from the server. If nothing is returned, the fallback will be used. If this function or its return value isn't set, it - falls back to updating the `form` prop with the returned data if the action is on the same page as the form - updates `page.status` - resets the `<form>` element and invalidates all data in case of successful submission with no redirect response - redirects in case of a redirect response - redirects to the nearest error page in case of an unexpected error If you provide a custom function with a callback and want to use the default behavior, invoke `update` in your callback. It accepts an options object - `reset: false` if you don't want the `<form>` values to be reset after a successful submission - `invalidateAll: false` if you don't want the action to call `invalidateAll` after submission <div class="ts-block"> ```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; }; ``` </div> # $app/navigation ```js // @noErrors import { afterNavigate, beforeNavigate, disableScrollHandling, goto, invalidate, invalidateAll, onNavigate, preloadCode, preloadData, pushState, replaceState } from '$app/navigation'; ``` ## afterNavigate A lifecycle function that runs the supplied `callback` when the current component mounts, and also whenever we navigate to a URL. `afterNavigate` must be called during a component initialization. It remains active as long as the component is mounted. <div class="ts-block"> ```dts function afterNavigate( callback: ( navigation: import('@sveltejs/kit').AfterNavigate ) => void ): void; ``` </div> ## beforeNavigate A navigation interceptor that triggers before we navigate to a URL, whether by clicking a link, calling `goto(...)`, or using the browser back/forward controls. Calling `cancel()` will prevent the navigation from completing. If `navigation.type === 'leave'` — meaning the user is navigating away from the app (or closing the tab) — calling `cancel` will trigger the native browser unload confirmation dialog. In this case, the navigation may or may not be cancelled depending on the user's response. When a navigation isn't to a SvelteKit-owned route (and therefore controlled by SvelteKit's client-side router), `navigation.to.route.id` will be `null`. If the navigation will (if not cancelled) cause the document to unload — in other words `'leave'` navigations and `'link'` navigations where `navigation.to.route === null` — `navigation.willUnload` is `true`. `beforeNavigate` must be called during a component initialization. It remains active as long as the component is mounted. <div class="ts-block"> ```dts function beforeNavigate( callback: ( navigation: import('@sveltejs/kit').BeforeNavigate ) => void ): void; ``` </div> ## disableScrollHandling If called when the page is being updated following a navigation (in `onMount` or `afterNavigate` or an action, for example), this disables SvelteKit's built-in scroll handling. This is generally discouraged, since it breaks user expectations. <div class="ts-block"> ```dts function disableScrollHandling(): void; ``` </div> ## goto Allows you to navigate programmatically to a given route, with options such as keeping the current element focused. Returns a Promise that resolves when SvelteKit navigates (or fails to navigate, in which case the promise rejects) to the specified `url`. For external URLs, use `window.location = url` instead of calling `goto(url)`. <div class="ts-block"> ```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>; ``` </div> ## invalidate Causes any `load` functions belonging to the currently active page to re-run if they depend on the `url` in question, via `fetch` or `depends`. Returns a `Promise` that resolves when the page is subsequently updated. If the argument is given as a `string` or `URL`, it must resolve to the same URL that was passed to `fetch` or `depends` (including query parameters). To create a custom identifier, use a string beginning with `[a-z]+:` (e.g. `custom:state`) — this is a valid URL. The `function` argument can be used 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 a exact match. ```ts // Example: Match '/path' regardless of the query parameters import { invalidate } from '$app/navigation'; invalidate((url) => url.pathname === '/path'); ``` <div class="ts-block"> ```dts function invalidate( resource: string | URL | ((url: URL) => boolean) ): Promise<void>; ``` </div> ## invalidateAll Causes all `load` functions belonging to the currently active page to re-run. Returns a `Promise` that resolves when the page is subsequently updated. <div class="ts-block"> ```dts function invalidateAll(): Promise<void>; ``` </div> ## onNavigate A lifecycle function that runs the supplied `callback` immediately before we navigate to a new URL except during full-page navigations. If you return a `Promise`, SvelteKit will wait for it to resolve before completing the navigation. This allows you to — for example — use `document.startViewTransition`. Avoid promises that are slow to resolve, since navigation will appear stalled to the user. If a function (or a `Promise` that resolves to a function) is returned from the callback, it will be called once the DOM has updated. `onNavigate` must be called during a component initialization. It remains active as long as the component is mounted. <div class="ts-block"> ```dts function onNavigate( callback: ( navigation: import('@sveltejs/kit').OnNavigate ) => MaybePromise<(() => void) | void> ): void; ``` </div> ## preloadCode Programmatically imports the code for routes that haven't yet been fetched. Typically, you might call this to speed up subsequent navigation. You can specify routes by any matching pathname such as `/about` (to match `src/routes/about/+page.svelte`) or `/blog/*` (to match `src/routes/blog/[slug]/+page.svelte`). Unlike `preloadData`, this won't call `load` functions. Returns a Promise that resolves when the modules have been imported. <div class="ts-block"> ```dts function preloadCode(pathname: string): Promise<void>; ``` </div> ## preloadData Programmatically preloads the given page, which means 1. ensuring that the code for the page is loaded, and 2. calling the page's load function with the appropriate options. This is the same behaviour that SvelteKit triggers when the user taps or mouses over an `<a>` element with `data-sveltekit-preload-data`. If the next navigation is to `href`, the values returned from load will be used, making navigation instantaneous. Returns a Promise that resolves with the result of running the new route's `load` functions once the preload is complete. <div class="ts-block"> ```dts function preloadData(href: string): Promise< | { type: 'loaded'; status: number; data: Record<string, any>; } | { type: 'redirect'; location: string; } >; ``` </div> ## pushState Programmatically create a new history entry with the given `page.state`. To use the current URL, you can pass `''` as the first argument. Used for [shallow routing](/docs/kit/shallow-routing). <div class="ts-block"> ```dts function pushState( url: string | URL, state: App.PageState ): void; ``` </div> ## replaceState Programmatically replace the current history entry with the given `page.state`. To use the current URL, you can pass `''` as the first argument. Used for [shallow routing](/docs/kit/shallow-routing). <div class="ts-block"> ```dts function replaceState( url: string | URL, state: App.PageState ): void; ``` </div> # $app/paths ```js // @noErrors import { assets, base, resolveRoute } from '$app/paths'; ``` ## assets An absolute path that matches [`config.kit.paths.assets`](/docs/kit/configuration#paths). > [!NOTE] If a value for `config.kit.paths.assets` is specified, it will be replaced with `'/_svelte_kit_assets'` during `vite dev` or `vite preview`, since the assets don't yet live at their eventual URL. <div class="ts-block"> ```dts let assets: | '' | `https://${string}` | `http://${string}` | '/_svelte_kit_assets'; ``` </div> ## base A string that matches [`config.kit.paths.base`](/docs/kit/configuration#paths). Example usage: `<a href="{base}/your-page">Link</a>` <div class="ts-block"> ```dts let base: '' | `/${string}`; ``` </div> ## resolveRoute Populate a route ID with params to resolve a pathname. ```js // @errors: 7031 import { resolveRoute } from '$app/paths'; resolveRoute( `/blog/[slug]/[...somethingElse]`, { slug: 'hello-world', somethingElse: 'something/else' } ); // `/blog/hello-world/something/else` ``` <div class="ts-block"> ```dts function resolveRoute( id: string, params: Record<string, string | undefined> ): string; ``` </div> # $app/server ```js // @noErrors import { read } from '$app/server'; ``` ## read <blockquote class="since note"> Available since 2.4.0 </blockquote> Read the contents of an imported asset from the filesystem ```js // @errors: 7031 import { read } from '$app/server'; import somefile from './somefile.txt'; const asset = read(somefile); const text = await asset.text(); ``` <div class="ts-block"> ```dts function read(asset: string): Response; ``` </div> # $app/state SvelteKit makes three read-only state objects available via the `$app/state` module — `page`, `navigating` and `updated`. > [!NOTE] > This module was added in 2.12. If you're using an earlier version of SvelteKit, use [`$app/stores`]($app-stores) instead. ```js // @noErrors import { navigating, page, updated } from '$app/state'; ``` ## navigating A read-only object representing an in-progress navigation, with `from`, `to`, `type` and (if `type === 'popstate'`) `delta` properties. Values are `null` when no navigation is occurring, or during server rendering. <div class="ts-block"> ```dts const navigating: | import('@sveltejs/kit').Navigation | { from: null; to: null; type: null; willUnload: null; delta: null; complete: null; }; ``` </div> ## page A read-only reactive object with information about the current page, serving several use cases: - retrieving the combined `data` of all pages/layouts anywhere in your component tree (also see [loading data](/docs/kit/load)) - retrieving the current value of the `form` prop anywhere in your component tree (also see [form actions](/docs/kit/form-actions)) - retrieving the page state that was set through `goto`, `pushState` or `replaceState` (also see [goto](/docs/kit/$app-navigation#goto) and [shallow routing](/docs/kit/shallow-routing)) - retrieving metadata such as the URL you're on, the current route and its parameters, and whether or not there was an error ```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} ``` Changes to `page` are available exclusively with runes. (The legacy reactivity syntax will not reflect any changes) ```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> ``` On the server, values can only be read during rendering (in other words _not_ in e.g. `load` functions). In the browser, the values can be read at any time. <div class="ts-block"> ```dts const page: import('@sveltejs/kit').Page; ``` </div> ## updated A read-only reactive value that's initially `false`. If [`version.pollInterval`](/docs/kit/configuration#version) is a non-zero value, SvelteKit will poll for new versions of the app and update `current` to `true` when it detects one. `updated.check()` will force an immediate check, regardless of polling. <div class="ts-block"> ```dts const updated: { get current(): boolean; check(): Promise<boolean>; }; ``` </div> # $app/stores This module contains store-based equivalents of the exports from [`$app/state`]($app-state). If you're using SvelteKit 2.12 or later, use that module instead. ```js // @noErrors import { getStores, navigating, page, updated } from '$app/stores'; ``` ## getStores <div class="ts-block"> ```dts function getStores(): { page: typeof page; navigating: typeof navigating; updated: typeof updated; }; ``` </div> ## navigating <blockquote class="tag deprecated note"> Use `navigating` from `$app/state` instead (requires Svelte 5, [see docs for more info](/docs/kit/migrating-to-sveltekit-2#SvelteKit-2.12:-$app-stores-deprecated)) </blockquote> A readable store. When navigating starts, its value is a `Navigation` object with `from`, `to`, `type` and (if `type === 'popstate'`) `delta` properties. When navigating finishes, its value reverts to `null`. On the server, this store can only be subscribed to during component initialization. In the browser, it can be subscribed to at any time. <div class="ts-block"> ```dts const navigating: import('svelte/store').Readable< import('@sveltejs/kit').Navigation | null >; ``` </div> ## page <blockquote class="tag deprecated note"> Use `page` from `$app/state` instead (requires Svelte 5, [see docs for more info](/docs/kit/migrating-to-sveltekit-2#SvelteKit-2.12:-$app-stores-deprecated)) </blockquote> A readable store whose value contains page data. On the server, this store can only be subscribed to during component initialization. In the browser, it can be subscribed to at any time. <div class="ts-block"> ```dts const page: import('svelte/store').Readable< import('@sveltejs/kit').Page >; ``` </div> ## updated <blockquote class="tag deprecated note"> Use `updated` from `$app/state` instead (requires Svelte 5, [see docs for more info](/docs/kit/migrating-to-sveltekit-2#SvelteKit-2.12:-$app-stores-deprecated)) </blockquote> A readable store whose initial value is `false`. If [`version.pollInterval`](/docs/kit/configuration#version) is a non-zero value, SvelteKit will poll for new versions of the app and update the store value to `true` when it detects one. `updated.check()` will force an immediate check, regardless of polling. On the server, this store can only be subscribed to during component initialization. In the browser, it can be subscribed to at any time. <div class="ts-block"> ```dts const updated: import('svelte/store').Readable<boolean> & { check(): Promise<boolean>; }; ``` </div> # $env/dynamic/private This module provides access to runtime environment variables, as defined by the platform you're running on. For example if you're using [`adapter-node`](https://github.com/sveltejs/kit/tree/main/packages/adapter-node) (or running [`vite preview`](/docs/kit/cli)), this is equivalent to `process.env`. This module only includes variables that _do not_ begin with [`config.kit.env.publicPrefix`](/docs/kit/configuration#env) _and do_ start with [`config.kit.env.privatePrefix`](/docs/kit/configuration#env) (if configured). This module cannot be imported into client-side code. Dynamic environment variables cannot be used during prerendering. ```ts import { env } from '$env/dynamic/private'; console.log(env.DEPLOYMENT_SPECIFIC_VARIABLE); ``` > In `dev`, `$env/dynamic` always includes environment variables from `.env`. In `prod`, this behavior will depend on your adapter. # $env/dynamic/public Similar to [`$env/dynamic/private`](/docs/kit/$env-dynamic-private), but only includes variables that begin with [`config.kit.env.publicPrefix`](/docs/kit/configuration#env) (which defaults to `PUBLIC_`), and can therefore safely be exposed to client-side code. Note that public dynamic environment variables must all be sent from the server to the client, causing larger network requests — when possible, use `$env/static/public` instead. Dynamic environment variables cannot be used during prerendering. ```ts import { env } from '$env/dynamic/public'; console.log(env.PUBLIC_DEPLOYMENT_SPECIFIC_VARIABLE); ``` # $env/static/private Environment variables [loaded by Vite](https://vitejs.dev/guide/env-and-mode.html#env-files) from `.env` files and `process.env`. Like [`$env/dynamic/private`](/docs/kit/$env-dynamic-private), this module cannot be imported into client-side code. This module only includes variables that _do not_ begin with [`config.kit.env.publicPrefix`](/docs/kit/configuration#env) _and do_ start with [`config.kit.env.privatePrefix`](/docs/kit/configuration#env) (if configured). _Unlike_ [`$env/dynamic/private`](/docs/kit/$env-dynamic-private), the values exported from this module are statically injected into your bundle at build time, enabling optimisations like dead code elimination. ```ts import { API_KEY } from '$env/static/private'; ``` Note that all environment variables referenced in your code should be declared (for example in an `.env` file), even if they don't have a value until the app is deployed: ``` MY_FEATURE_FLAG="" ``` You can override `.env` values from the command line like so: ```bash MY_FEATURE_FLAG="enabled" npm run dev ``` # $env/static/public Similar to [`$env/static/private`](/docs/kit/$env-static-private), except that it only includes environment variables that begin with [`config.kit.env.publicPrefix`](/docs/kit/configuration#env) (which defaults to `PUBLIC_`), and can therefore safely be exposed to client-side code. Values are replaced statically at build time. ```ts import { PUBLIC_BASE_URL } from '$env/static/public'; ``` # $lib SvelteKit automatically makes files under `src/lib` available using the `$lib` import alias. You can change which directory this alias points to in your [config file](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'; ``` This module is only available to [service workers](/docs/kit/service-workers). ## base The `base` path of the deployment. Typically this is equivalent to `config.kit.paths.base`, but it is calculated from `location.pathname` meaning that it will continue to work correctly if the site is deployed to a subdirectory. Note that there is a `base` but no `assets`, since service workers cannot be used if `config.kit.paths.assets` is specified. <div class="ts-block"> ```dts const base: string; ``` </div> ## build An array of URL strings representing the files generated by Vite, suitable for caching with `cache.addAll(build)`. During development, this is an empty array. <div class="ts-block"> ```dts const build: string[]; ``` </div> ## files An array of URL strings representing the files in your static directory, or whatever directory is specified by `config.kit.files.assets`. You can customize which files are included from `static` directory using [`config.kit.serviceWorker.files`](/docs/kit/configuration) <div class="ts-block"> ```dts const files: string[]; ``` </div> ## prerendered An array of pathnames corresponding to prerendered pages and endpoints. During development, this is an empty array. <div class="ts-block"> ```dts const prerendered: string[]; ``` </div> ## version See [`config.kit.version`](/docs/kit/configuration#version). It's useful for generating unique cache names inside your service worker, so that a later deployment of your app can invalidate old caches. <div class="ts-block"> ```dts const version: string; ``` </div> # Configuration Your project's configuration lives in a `svelte.config.js` file at the root of your project. As well as SvelteKit, this config object is used by other tooling that integrates with Svelte such as editor extensions. ```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; ``` ## Config <div class="ts-block"> ```dts interface Config {/*…*/} ``` <div class="ts-block-property"> ```dts compilerOptions?: CompileOptions; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `{}` </div> Options passed to [`svelte.compile`](/docs/svelte/svelte-compiler#CompileOptions). </div> </div> <div class="ts-block-property"> ```dts extensions?: string[]; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `[".svelte"]` </div> List of file extensions that should be treated as Svelte files. </div> </div> <div class="ts-block-property"> ```dts kit?: KitConfig; ``` <div class="ts-block-property-details"> SvelteKit options </div> </div> <div class="ts-block-property"> ```dts preprocess?: any; ``` <div class="ts-block-property-details"> Preprocessor options, if any. Preprocessing can alternatively also be done through Vite's preprocessor capabilities. </div> </div> <div class="ts-block-property"> ```dts vitePlugin?: PluginOptions; ``` <div class="ts-block-property-details"> `vite-plugin-svelte` plugin options. </div> </div> <div class="ts-block-property"> ```dts [key: string]: any; ``` <div class="ts-block-property-details"> Any additional options required by tooling that integrates with Svelte. </div> </div></div> ## KitConfig The `kit` property configures SvelteKit, and can have the following properties: ## adapter <div class="ts-block-property-bullets"> - <span class="tag">default</span> `undefined` </div> Your [adapter](/docs/kit/adapters) is run when executing `vite build`. It determines how the output is converted for different platforms. <div class="ts-block-property-children"> </div> ## alias <div class="ts-block-property-bullets"> - <span class="tag">default</span> `{}` </div> An object containing zero or more aliases used to replace values in `import` statements. These aliases are automatically passed to Vite and 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/*' } } }; ``` > [!NOTE] The built-in `$lib` alias is controlled by `config.kit.files.lib` as it is used for packaging. > [!NOTE] You will need to run `npm run dev` to have SvelteKit automatically generate the required alias configuration in `jsconfig.json` or `tsconfig.json`. <div class="ts-block-property-children"> </div> ## appDir <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"_app"` </div> The directory where SvelteKit keeps its stuff, including static assets (such as JS and CSS) and internally-used routes. If `paths.assets` is specified, there will be two app directories — `${paths.assets}/${appDir}` and `${paths.base}/${appDir}`. <div class="ts-block-property-children"> </div> ## csp <div class="ts-block-property-bullets"> </div> [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) configuration. CSP helps to protect your users against cross-site scripting (XSS) attacks, by limiting the places resources can be loaded from. For example, a configuration like this... ```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; ``` ...would prevent scripts loading from external sites. SvelteKit will augment the specified directives with nonces or hashes (depending on `mode`) for any inline styles and scripts it generates. To add a nonce for scripts and links manually included in `src/app.html`, you may use the placeholder `%sveltekit.nonce%` (for example `<script nonce="%sveltekit.nonce%">`). When pages are prerendered, the CSP header is added via a `<meta http-equiv>` tag (note that in this case, `frame-ancestors`, `report-uri` and `sandbox` directives will be ignored). > [!NOTE] When `mode` is `'auto'`, SvelteKit will use nonces for dynamically rendered pages and hashes for prerendered pages. Using nonces with prerendered pages is insecure and therefore forbidden. > [!NOTE] Note that most [Svelte transitions](/tutorial/svelte/transition) work by creating an inline `<style>` element. If you use these in your app, you must either leave the `style-src` directive unspecified or add `unsafe-inline`. If this level of configuration is insufficient and you have more dynamic requirements, you can use the [`handle` hook](/docs/kit/hooks#Server-hooks-handle) to roll your own CSP. <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors mode?: 'hash' | 'nonce' | 'auto'; ``` <div class="ts-block-property-details"> Whether to use hashes or nonces to restrict `<script>` and `<style>` elements. `'auto'` will use hashes for prerendered pages, and nonces for dynamically rendered pages. </div> </div> <div class="ts-block-property"> ```ts // @noErrors directives?: CspDirectives; ``` <div class="ts-block-property-details"> Directives that will be added to `Content-Security-Policy` headers. </div> </div> <div class="ts-block-property"> ```ts // @noErrors reportOnly?: CspDirectives; ``` <div class="ts-block-property-details"> Directives that will be added to `Content-Security-Policy-Report-Only` headers. </div> </div> </div> ## csrf <div class="ts-block-property-bullets"> </div> Protection against [cross-site request forgery (CSRF)](https://owasp.org/www-community/attacks/csrf) attacks. <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors checkOrigin?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `true` </div> Whether to check the incoming `origin` header for `POST`, `PUT`, `PATCH`, or `DELETE` form submissions and verify that it matches the server's origin. To allow people to make `POST`, `PUT`, `PATCH`, or `DELETE` requests with a `Content-Type` of `application/x-www-form-urlencoded`, `multipart/form-data`, or `text/plain` to your app from other origins, you will need to disable this option. Be careful! </div> </div> </div> ## embedded <div class="ts-block-property-bullets"> - <span class="tag">default</span> `false` </div> Whether or not the app is embedded inside a larger app. If `true`, SvelteKit will add its event listeners related to navigation etc on the parent of `%sveltekit.body%` instead of `window`, and will pass `params` from the server rather than inferring them from `location.pathname`. Note that it is generally not supported to embed multiple SvelteKit apps on the same page and use client-side SvelteKit features within them (things such as pushing to the history state assume a single instance). <div class="ts-block-property-children"> </div> ## env <div class="ts-block-property-bullets"> </div> Environment variable configuration <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors dir?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"."` </div> The directory to search for `.env` files. </div> </div> <div class="ts-block-property"> ```ts // @noErrors publicPrefix?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"PUBLIC_"` </div> A prefix that signals that an environment variable is safe to expose to client-side code. See [`$env/static/public`](/docs/kit/$env-static-public) and [`$env/dynamic/public`](/docs/kit/$env-dynamic-public). Note that Vite's [`envPrefix`](https://vitejs.dev/config/shared-options.html#envprefix) must be set separately if you are using Vite's environment variable handling - though use of that feature should generally be unnecessary. </div> </div> <div class="ts-block-property"> ```ts // @noErrors privatePrefix?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `""` - <span class="tag since">available since</span> v1.21.0 </div> A prefix that signals that an environment variable is unsafe to expose to client-side code. Environment variables matching neither the public nor the private prefix will be discarded completely. See [`$env/static/private`](/docs/kit/$env-static-private) and [`$env/dynamic/private`](/docs/kit/$env-dynamic-private). </div> </div> </div> ## files <div class="ts-block-property-bullets"> </div> Where to find various files within your project. <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors assets?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"static"` </div> a place to put static files that should have stable URLs and undergo no processing, such as `favicon.ico` or `manifest.json` </div> </div> <div class="ts-block-property"> ```ts // @noErrors hooks?: {/*…*/} ``` <div class="ts-block-property-details"> <div class="ts-block-property-children"><div class="ts-block-property"> ```ts // @noErrors client?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"src/hooks.client"` </div> The location of your client [hooks](/docs/kit/hooks). </div> </div> <div class="ts-block-property"> ```ts // @noErrors server?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"src/hooks.server"` </div> The location of your server [hooks](/docs/kit/hooks). </div> </div> <div class="ts-block-property"> ```ts // @noErrors universal?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"src/hooks"` - <span class="tag since">available since</span> v2.3.0 </div> The location of your universal [hooks](/docs/kit/hooks). </div> </div></div> </div> </div> <div class="ts-block-property"> ```ts // @noErrors lib?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"src/lib"` </div> your app's internal library, accessible throughout the codebase as `$lib` </div> </div> <div class="ts-block-property"> ```ts // @noErrors params?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"src/params"` </div> a directory containing [parameter matchers](/docs/kit/advanced-routing#Matching) </div> </div> <div class="ts-block-property"> ```ts // @noErrors routes?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"src/routes"` </div> the files that define the structure of your app (see [Routing](/docs/kit/routing)) </div> </div> <div class="ts-block-property"> ```ts // @noErrors serviceWorker?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"src/service-worker"` </div> the location of your service worker's entry point (see [Service workers](/docs/kit/service-workers)) </div> </div> <div class="ts-block-property"> ```ts // @noErrors appTemplate?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"src/app.html"` </div> the location of the template for HTML responses </div> </div> <div class="ts-block-property"> ```ts // @noErrors errorTemplate?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"src/error.html"` </div> the location of the template for fallback error responses </div> </div> </div> ## inlineStyleThreshold <div class="ts-block-property-bullets"> - <span class="tag">default</span> `0` </div> Inline CSS inside a `<style>` block at the head of the HTML. This option is a number that specifies the maximum length of a CSS file in UTF-16 code units, as specified by the [String.length](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length) property, to be inlined. All CSS files needed for the page and smaller than this value are merged and inlined in a `<style>` block. > [!NOTE] This results in fewer initial requests and can improve your [First Contentful Paint](https://web.dev/first-contentful-paint) score. However, it generates larger HTML output and reduces the effectiveness of browser caches. Use it advisedly. <div class="ts-block-property-children"> </div> ## moduleExtensions <div class="ts-block-property-bullets"> - <span class="tag">default</span> `[".js", ".ts"]` </div> An array of file extensions that SvelteKit will treat as modules. Files with extensions that match neither `config.extensions` nor `config.kit.moduleExtensions` will be ignored by the router. <div class="ts-block-property-children"> </div> ## outDir <div class="ts-block-property-bullets"> - <span class="tag">default</span> `".svelte-kit"` </div> The directory that SvelteKit writes files to during `dev` and `build`. You should exclude this directory from version control. <div class="ts-block-property-children"> </div> ## output <div class="ts-block-property-bullets"> </div> Options related to the build output format <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors preloadStrategy?: 'modulepreload' | 'preload-js' | 'preload-mjs'; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"modulepreload"` - <span class="tag since">available since</span> v1.8.4 </div> SvelteKit will preload the JavaScript modules needed for the initial page to avoid import 'waterfalls', resulting in faster application startup. There are three strategies with different trade-offs: - `modulepreload` - uses `<link rel="modulepreload">`. This delivers the best results in Chromium-based browsers, in Firefox 115+, and Safari 17+. It is ignored in older browsers. - `preload-js` - uses `<link rel="preload">`. Prevents waterfalls in Chromium and Safari, but Chromium will parse each module twice (once as a script, once as a module). Causes modules to be requested twice in Firefox. This is a good setting if you want to maximise performance for users on iOS devices at the cost of a very slight degradation for Chromium users. - `preload-mjs` - uses `<link rel="preload">` but with the `.mjs` extension which prevents double-parsing in Chromium. Some static webservers will fail to serve .mjs files with a `Content-Type: application/javascript` header, which will cause your application to break. If that doesn't apply to you, this is the option that will deliver the best performance for the largest number of users, until `modulepreload` is more widely supported. </div> </div> <div class="ts-block-property"> ```ts // @noErrors bundleStrategy?: 'split' | 'single' | 'inline'; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `'split'` - <span class="tag since">available since</span> v2.13.0 </div> The bundle strategy option affects how your app's JavaScript and CSS files are loaded. - If `'split'`, splits the app up into multiple .js/.css files so that they are loaded lazily as the user navigates around the app. This is the default, and is recommended for most scenarios. - If `'single'`, creates just one .js bundle and one .css file containing code for the entire app. - If `'inline'`, inlines all JavaScript and CSS of the entire app into the HTML. The result is usable without a server (i.e. you can just open the file in your browser). When using `'split'`, you can also adjust the bundling behaviour by setting [`output.experimentalMinChunkSize`](https://rollupjs.org/configuration-options/#output-experimentalminchunksize) and [`output.manualChunks`](https://rollupjs.org/configuration-options/#output-manualchunks) inside your Vite config's [`build.rollupOptions`](https://vite.dev/config/build-options.html#build-rollupoptions). If you want to inline your assets, you'll need to set Vite's [`build.assetsInlineLimit`](https://vite.dev/config/build-options.html#build-assetsinlinelimit) option to an appropriate size then import your assets through 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> ``` </div> </div> </div> ## paths <div class="ts-block-property-bullets"> </div> <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors assets?: '' | `http://${string}` | `https://${string}`; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `""` </div> An absolute path that your app's files are served from. This is useful if your files are served from a storage bucket of some kind. </div> </div> <div class="ts-block-property"> ```ts // @noErrors base?: '' | `/${string}`; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `""` </div> A root-relative path that must start, but not end with `/` (e.g. `/base-path`), unless it is the empty string. This specifies where your app is served from and allows the app to live on a non-root path. Note that you need to prepend all your root-relative links with the base value or they will point to the root of your domain, not your `base` (this is how the browser works). You can use [`base` from `$app/paths`](/docs/kit/$app-paths#base) for that: `<a href="{base}/your-page">Link</a>`. If you find yourself writing this often, it may make sense to extract this into a reusable component. </div> </div> <div class="ts-block-property"> ```ts // @noErrors relative?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `true` - <span class="tag since">available since</span> v1.9.0 </div> Whether to use relative asset paths. If `true`, `base` and `assets` imported from `$app/paths` will be replaced with relative asset paths during server-side rendering, resulting in more portable HTML. If `false`, `%sveltekit.assets%` and references to build artifacts will always be root-relative paths, unless `paths.assets` is an external URL [Single-page app](/docs/kit/single-page-apps) fallback pages will always use absolute paths, regardless of this setting. If your app uses a `<base>` element, you should set this to `false`, otherwise asset URLs will incorrectly be resolved against the `<base>` URL rather than the current page. In 1.0, `undefined` was a valid value, which was set by default. In that case, if `paths.assets` was not external, SvelteKit would replace `%sveltekit.assets%` with a relative path and use relative paths to reference build artifacts, but `base` and `assets` imported from `$app/paths` would be as specified in your config. </div> </div> </div> ## prerender <div class="ts-block-property-bullets"> </div> See [Prerendering](/docs/kit/page-options#prerender). <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors concurrency?: number; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `1` </div> How many pages can be prerendered simultaneously. JS is single-threaded, but in cases where prerendering performance is network-bound (for example loading content from a remote CMS) this can speed things up by processing other tasks while waiting on the network response. </div> </div> <div class="ts-block-property"> ```ts // @noErrors crawl?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `true` </div> Whether SvelteKit should find pages to prerender by following links from `entries`. </div> </div> <div class="ts-block-property"> ```ts // @noErrors entries?: Array<'*' | `/${string}`>; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `["*"]` </div> An array of pages to prerender, or start crawling from (if `crawl: true`). The `*` string includes all routes containing no required `[parameters]` with optional parameters included as being empty (since SvelteKit doesn't know what value any parameters should have). </div> </div> <div class="ts-block-property"> ```ts // @noErrors handleHttpError?: PrerenderHttpErrorHandlerValue; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"fail"` - <span class="tag since">available since</span> v1.15.7 </div> How to respond to HTTP errors encountered while prerendering the app. - `'fail'` — fail the build - `'ignore'` - silently ignore the failure and continue - `'warn'` — continue, but print a warning - `(details) => void` — a custom error handler that takes a `details` object with `status`, `path`, `referrer`, `referenceType` and `message` properties. If you `throw` from this function, the build will fail ```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); } } } }; ``` </div> </div> <div class="ts-block-property"> ```ts // @noErrors handleMissingId?: PrerenderMissingIdHandlerValue; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"fail"` - <span class="tag since">available since</span> v1.15.7 </div> How to respond when hash links from one prerendered page to another don't correspond to an `id` on the destination page. - `'fail'` — fail the build - `'ignore'` - silently ignore the failure and continue - `'warn'` — continue, but print a warning - `(details) => void` — a custom error handler that takes a `details` object with `path`, `id`, `referrers` and `message` properties. If you `throw` from this function, the build will fail </div> </div> <div class="ts-block-property"> ```ts // @noErrors handleEntryGeneratorMismatch?: PrerenderEntryGeneratorMismatchHandlerValue; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"fail"` - <span class="tag since">available since</span> v1.16.0 </div> How to respond when an entry generated by the `entries` export doesn't match the route it was generated from. - `'fail'` — fail the build - `'ignore'` - silently ignore the failure and continue - `'warn'` — continue, but print a warning - `(details) => void` — a custom error handler that takes a `details` object with `generatedFromId`, `entry`, `matchedId` and `message` properties. If you `throw` from this function, the build will fail </div> </div> <div class="ts-block-property"> ```ts // @noErrors origin?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"http://sveltekit-prerender"` </div> The value of `url.origin` during prerendering; useful if it is included in rendered content. </div> </div> </div> ## router <div class="ts-block-property-bullets"> </div> <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors type?: 'pathname' | 'hash'; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `"pathname"` - <span class="tag since">available since</span> v2.14.0 </div> What type of client-side router to use. - `'pathname'` is the default and means the current URL pathname determines the route - `'hash'` means the route is determined by `location.hash`. In this case, SSR and prerendering are disabled. This is only recommended if `pathname` is not an option, for example because you don't control the webserver where your app is deployed. It comes with some caveats: you can't use server-side rendering (or indeed any server logic), and you have to make sure that the links in your app all start with #/, or they won't work. Beyond that, everything works exactly like a normal SvelteKit app. </div> </div> </div> ## serviceWorker <div class="ts-block-property-bullets"> </div> <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors register?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `true` </div> Whether to automatically register the service worker, if it exists. </div> </div> <div class="ts-block-property"> ```ts // @noErrors files?(filepath: string): boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `(filename) => !/\.DS_Store/.test(filename)` </div> Determine which files in your `static` directory will be available in `$service-worker.files`. </div> </div> </div> ## typescript <div class="ts-block-property-bullets"> </div> <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors config?: (config: Record<string, any>) => Record<string, any> | void; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `(config) => config` - <span class="tag since">available since</span> v1.3.0 </div> A function that allows you to edit the generated `tsconfig.json`. You can mutate the config (recommended) or return a new one. This is useful for extending a shared `tsconfig.json` in a monorepo root, for example. </div> </div> </div> ## version <div class="ts-block-property-bullets"> </div> Client-side navigation can be buggy if you deploy a new version of your app while people are using it. If the code for the new page is already loaded, it may have stale content; if it isn't, the app's route manifest may point to a JavaScript file that no longer exists. SvelteKit helps you solve this problem through version management. If SvelteKit encounters an error while loading the page and detects that a new version has been deployed (using the `name` specified here, which defaults to a timestamp of the build) it will fall back to traditional full-page navigation. Not all navigations will result in an error though, for example if the JavaScript for the next page is already loaded. If you still want to force a full-page navigation in these cases, use techniques such as setting the `pollInterval` and then using `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> ``` If you set `pollInterval` to a non-zero value, SvelteKit will poll for new versions in the background and set the value of [`updated.current`](/docs/kit/$app-state#updated) `true` when it detects one. <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors name?: string; ``` <div class="ts-block-property-details"> The current app version string. If specified, this must be deterministic (e.g. a commit ref rather than `Math.random()` or `Date.now().toString()`), otherwise defaults to a timestamp of the build. For example, to use the current commit hash, you could do use `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() } } }; ``` </div> </div> <div class="ts-block-property"> ```ts // @noErrors pollInterval?: number; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">default</span> `0` </div> The interval in milliseconds to poll for version changes. If this is `0`, no polling occurs. </div> </div> </div> # Command Line Interface SvelteKit projects use [Vite](https://vitejs.dev), meaning you'll mostly use its CLI (albeit via `npm run dev/build/preview` scripts): - `vite dev` — start a development server - `vite build` — build a production version of your app - `vite preview` — run the production version locally However SvelteKit includes its own CLI for initialising your project: ## svelte-kit sync `svelte-kit sync` creates the `tsconfig.json` and all generated types (which you can import as `./$types` inside routing files) for your project. When you create a new project, it is listed as the `prepare` script and will be run automatically as part of the npm lifecycle, so you should not ordinarily have to run this command. # Types ## Generated types The `RequestHandler` and `Load` types both accept a `Params` argument allowing you to type the `params` object. For example this endpoint expects `foo`, `bar` and `baz` params: ```js /// file: src/routes/[foo]/[bar]/[baz]/+page.server.js // @errors: 2355 2322 1360 /** @type {import('@sveltejs/kit').RequestHandler<{ foo: string; bar: string; baz: string }>} */ export async function GET({ params }) { // ... } ``` Needless to say, this is cumbersome to write out, and less portable (if you were to rename the `[foo]` directory to `[qux]`, the type would no longer reflect reality). To solve this problem, SvelteKit generates `.d.ts` files for each of your endpoints and pages: ```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 PageServerLoad = Kit.ServerLoad<RouteParams>; export type PageLoad = Kit.Load<RouteParams>; ``` These files can be imported into your endpoints and pages as siblings, thanks to the [`rootDirs`](https://www.typescriptlang.org/tsconfig#rootDirs) option in your TypeScript configuration: ```js /// file: src/routes/[foo]/[bar]/[baz]/+page.server.js // @filename: $types.d.ts import type * as Kit from '@sveltejs/kit'; type RouteParams = { foo: string; bar: string; baz: string; } export type PageServerLoad = Kit.ServerLoad<RouteParams>; // @filename: index.js // @errors: 2355 // ---cut--- /** @type {import('./$types').PageServerLoad} */ 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 }) { // ... } ``` The return types of the load functions are then available through the `$types` module as `PageData` and `LayoutData` respectively, while the union of the return values of all `Actions` is available as `ActionData`. Starting with version 2.16.0, two additional helper types are provided. `PageProps` defines `data: PageData`, as well as `form: ActionData`, when there are actions defined. `LayoutProps` defines `data: LayoutData`, as well as `children: Snippet`: ```svelte <!--- file: src/routes/+page.svelte ---> <script> /** @type {import('./$types').PageProps} */ let { data, form } = $props(); </script> ``` > [!LEGACY] > Before 2.16.0: > ```svelte > <!--- file: src/routes/+page.svelte ---> > <script> > /** @type {{ data: import('./$types').PageData, form: import('./$types').ActionData }} */ > let { data, form } = $props(); > </script> > ``` > > Using Svelte 4: > ```svelte > <!--- file: src/routes/+page.svelte ---> > <script> > /** @type {import('./$types').PageData} */ > export let data; > /** @type {import('./$types').ActionData} */ > export let form; > </script> > ``` > [!NOTE] For this to work, your own `tsconfig.json` or `jsconfig.json` should extend from the generated `.svelte-kit/tsconfig.json` (where `.svelte-kit` is your [`outDir`](configuration#outDir)): > > `{ "extends": "./.svelte-kit/tsconfig.json" }` ### Default tsconfig.json The generated `.svelte-kit/tsconfig.json` file contains a mixture of options. Some are generated programmatically based on your project configuration, and should generally not be overridden without good reason: ```json /// file: .svelte-kit/tsconfig.json { "compilerOptions": { "baseUrl": "..", "paths": { "$lib": "src/lib", "$lib/*": "src/lib/*" }, "rootDirs": ["..", "./types"] }, "include": ["../src/**/*.js", "../src/**/*.ts", "../src/**/*.svelte"], "exclude": ["../node_modules/**", "./**"] } ``` Others are required for SvelteKit to work properly, and should also be left untouched unless you know what you're doing: ```json /// file: .svelte-kit/tsconfig.json { "compilerOptions": { // this ensures that types are explicitly // imported with `import type`, which is // necessary as svelte-preprocess cannot // otherwise compile components correctly "importsNotUsedAsValues": "error", // Vite compiles one TypeScript module // at a time, rather than compiling // the entire module graph "isolatedModules": true, // TypeScript cannot 'see' when you // use an imported value in your // markup, so we need this "preserveValueImports": true, // This ensures both `vite build` // and `svelte-package` work correctly "lib": ["esnext", "DOM", "DOM.Iterable"], "moduleResolution": "node", "module": "esnext", "target": "esnext" } } ``` ## $lib This is a simple alias to `src/lib`, or whatever directory is specified as [`config.kit.files.lib`](configuration#files). It allows you to access common components and utility modules without `../../../../` nonsense. ### $lib/server A subdirectory of `$lib`. SvelteKit will prevent you from importing any modules in `$lib/server` into client-side code. See [server-only modules](server-only-modules). ## app.d.ts The `app.d.ts` file is home to the ambient types of your apps, i.e. types that are available without explicitly importing them. Always part of this file is the `App` namespace. This namespace contains several types that influence the shape of certain SvelteKit features you interact with. ## Error Defines the common shape of expected and unexpected errors. Expected errors are thrown using the `error` function. Unexpected errors are handled by the `handleError` hooks which should return this shape. <div class="ts-block"> ```dts interface Error {/*…*/} ``` <div class="ts-block-property"> ```dts message: string; ``` <div class="ts-block-property-details"></div> </div></div> ## Locals The interface that defines `event.locals`, which can be accessed in server [hooks](/docs/kit/hooks) (`handle`, and `handleError`), server-only `load` functions, and `+server.js` files. <div class="ts-block"> ```dts interface Locals {} ``` </div> ## PageData Defines the common shape of the [page.data state](/docs/kit/$app-state#page) and [$page.data store](/docs/kit/$app-stores#page) - that is, the data that is shared between all pages. The `Load` and `ServerLoad` functions in `./$types` will be narrowed accordingly. Use optional properties for data that is only present on specific pages. Do not add an index signature (`[key: string]: any`). <div class="ts-block"> ```dts interface PageData {} ``` </div> ## PageState The shape of the `page.state` object, which can be manipulated using the [`pushState`](/docs/kit/$app-navigation#pushState) and [`replaceState`](/docs/kit/$app-navigation#replaceState) functions from `$app/navigation`. <div class="ts-block"> ```dts interface PageState {} ``` </div> ## Platform If your adapter provides [platform-specific context](/docs/kit/adapters#Platform-specific-context) via `event.platform`, you can specify it here. <div class="ts-block"> ```dts interface Platform {} ``` </div>