Skip to main content

Reference

Configuration

Edit this page on GitHub

プロジェクトの設定は、プロジェクトの root にある svelte.config.js ファイルに保存されています。SvelteKit だけでなく、エディタ拡張(editor extensions)など Svelte とインテグレーションする他のツールでもこれが使用されます。

svelte.config.js
ts
import adapter from '@sveltejs/adapter-auto';
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
adapter: adapter()
}
};
export default config;
ts
interface Config {}
ts
compilerOptions?: CompileOptions;
  • default {}

svelte.compile に渡されるオプションです。

ts
extensions?: string[];
  • default [".svelte"]

Svelte ファイルとして扱うべきファイルの拡張子のリストです。

ts
kit?: KitConfig;

SvelteKit オプション

ts
package?: {
source?: string;
dir?: string;
emitTypes?: boolean;
exports?(filepath: string): boolean;
files?(filepath: string): boolean;
};

@sveltejs/package オプション。

ts
preprocess?: any;

プリプロセッサ のオプション (もしあれば)。プリプロセスは Vite のプリプロセッサによって行うこともできます。

ts
vitePlugin?: PluginOptions;

vite-plugin-svelte プラグインオプション。

ts
[key: string]: any;

Svelte とインテグレートするツールに必要な追加のオプション。

kit プロパティは SvelteKit を設定し、以下のプロパティを持つことができます:

adapter

  • default undefined

adapter は、vite build の実行中に実行されます。これによってどのプラットフォーム向けにアウトプットを変換するか決定します。

alias

  • default {}

import 文の値を置き換えるのに使用されるエイリアスを0個以上含むオブジェクトです。これらのエイリアスは自動的に Vite と TypeScript に渡されます。

svelte.config.js
ts
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
alias: {
// this will match a file
'my-file': 'path/to/my-file.js',
// this will match a directory and its contents
// (`my-directory/x` resolves to `path/to/my-directory/x`)
'my-directory': 'path/to/my-directory',
// an alias ending /* will only match
// the contents of a directory, not the directory itself
'my-directory/*': 'path/to/my-directory/*'
}
}
};

ビルトインの $lib エイリアスはパッケージングに使用されるため、config.kit.files.lib でコントロールされます。

jsconfig.jsontsconfig.json に必要なエイリアス設定を、SvelteKit に自動的に生成させるためには、npm run dev を実行する必要があります。

appDir

  • default "_app"

ビルドされた JS と CSS (とインポートされたアセット) が提供されるディレクトリで、paths.assets との相対です。(ファイル名にはそれ自体にコンテンツベースのハッシュが含まれるため、無期限にキャッシュすることができます)。先頭と末尾を / にすることはできません。

csp

Content Security Policy の設定です。CSP は、読み込むことができるリソースを、そのリソースの場所(ドメインなど)で制限することによって、クロスサイトスクリプティング(XSS)攻撃からユーザーを守るのに役立ちます。例えば、このような設定の場合…

svelte.config.js
ts
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
csp: {
directives: {
'script-src': ['self']
},
reportOnly: {
'script-src': ['self']
}
}
}
};
export default config;

…外部サイトのスクリプトの読み込みを防ぐことができます。SvelteKit は、生成されるインラインスタイルとスクリプトに対し、指定したディレクティブを nonce または hash (mode の設定による) で補強します。

src/app.html の script や link に nonce を追加するには、%sveltekit.nonce% プレースホルダーをお使いください (例えば <script nonce="%sveltekit.nonce%">)。

ページがプリレンダリングされる場合、CSP ヘッダーは <meta http-equiv> タグで追加されます (この場合、frame-ancestorsreport-urisandbox ディレクティブは無視されることにご注意ください)。

mode'auto' の場合、SvelteKit は動的にレンダリングされるページには nonce を使用し、プリレンダリングされたページには hash を使用します。プリレンダリングされたページに nonce を使用するのは安全ではないため、禁止されています。

多くの Svelte transitions はインラインの <style> 要素を作成することで動作することにご注意ください。アプリでこれらを使用する場合は、style-src ディレクティブを指定しないようにするか、unsafe-inline を追加する必要があります。

もしこのレベルの設定では不十分で、より動的な要件がある場合は、handle hook を使用して独自の CSP を動かすことができます。

ts
mode?: 'hash' | 'nonce' | 'auto';

<script><style> 要素の制限に hash と nonce のどちらを使用するか。'auto' の場合、プリレンダリングされたページには hash を、動的にレンダリングされるページには nonce が使用されます。

ts
directives?: CspDirectives;

Content-Security-Policy ヘッダーに追加されるディレクティブです。

ts
reportOnly?: CspDirectives;

Content-Security-Policy-Report-Only ヘッダーに追加されるディレクティブです。

csrf

cross-site request forgery (CSRF) 攻撃からの防御の設定です。

ts
checkOrigin?: boolean;
  • default true

POSTPUTPATCHDELETE でのフォーム送信時、受信した origin ヘッダーをチェックしてサーバーのオリジン(origin)と一致するか検証することを行うかどうか。

あなたのアプリに対し、別のオリジンから POSTPUTPATCHDELETE のリクエスト (Content-Typeapplication/x-www-form-urlencodedmultipart/form-datatext/plain のいずれか) をできるようにするには、このオプションを無効にする必要があります。ご注意を!

dangerZone

Here be dragons. Enable at your peril.

ts
trackServerFetches?: boolean;

Automatically add server-side fetched URLs to the dependencies map of load functions. This will expose secrets to the client if your URL contains them.

embedded

  • default false

アプリが別の大規模なアプリに埋め込まれているかどうか。もし true の場合、SvelteKit はナビゲーションなどに関係するイベントリスナーを、window の代わりに %sveltekit.body% の親に追加し、paramslocation.pathname から導くのではなく、サーバーから取得して渡します。

env

環境変数設定

ts
dir?: string;
  • default "."

.env ファイルを探すディレクトリです。

ts
publicPrefix?: string;
  • default "PUBLIC_"

クライアントサイドコードに公開されても安全な環境変数に付与される接頭辞です。$env/static/public$env/dynamic/public をご覧ください。Vite の環境変数ハンドリングを使用する場合は、別途 Vite の envPrefix を設定する必要があることにご注意ください - ただし、通常この機能を使う必要はありません。

ts
privatePrefix?: string;
  • default ""

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 and $env/dynamic/private.

files

プロジェクト内の各種ファイルの場所。

ts
assets?: string;
  • default "static"

favicon.icomanifest.json のように、不変の URL を持つ、何も処理されない静的なファイルを置く場所です

ts
hooks?: {}
ts
client?: string;
  • default "src/hooks.client"

クライアントの hooks のロケーションです。

ts
server?: string;
  • default "src/hooks.server"

サーバーの hooks のロケーションです。

ts
lib?: string;
  • default "src/lib"

コードベース全体から $lib としてアクセスできる、アプリの内部ライブラリ

ts
params?: string;
  • default "src/params"

parameter matchers を置くディレクトリ

ts
routes?: string;
  • default "src/routes"

アプリの構造を定義するファイル (Routing をご覧ください)

ts
serviceWorker?: string;
  • default "src/service-worker"

service worker のエントリーポイントのロケーション (Service workers をご覧ください)

ts
appTemplate?: string;
  • default "src/app.html"

HTML レスポンスのテンプレートのロケーション

ts
errorTemplate?: string;
  • default "src/error.html"

フォールバックエラーレスポンスのテンプレートのロケーション

inlineStyleThreshold

  • default 0

HTML の head の <style> ブロックの CSS をインライン化します。このオプションには、インライン化される CSS ファイルの最大長を、UTF-16 コード単位、つまり String.length プロパティで定める数値を指定します。ページに必要な CSS ファイルで、この数値より小さいものは全てマージされ、<style> ブロックにインライン化されます。

これによって初期リクエストが減り、First Contentful Paint スコアを改善することができます。しかし、より大きな HTML が生成され、ブラウザのキャッシュの有効性を低下させます。慎重にお使いください。

moduleExtensions

  • default [".js", ".ts"]

SvelteKit がモジュールとして扱うファイルの拡張子の配列です。config.extensionsconfig.kit.moduleExtensions のいずれにもマッチしない拡張子のファイルは、ルーターから無視されます。

outDir

  • default ".svelte-kit"

SvelteKit が devbuild 中にファイルを書き込むディレクトリです。このディレクトリはバージョンコントロールから除外すると良いでしょう。

output

ビルドの出力フォーマットに関するオプション

ts
preloadStrategy?: 'modulepreload' | 'preload-js' | 'preload-mjs';
  • default "modulepreload"

SvelteKit は初期ページに必要な JavaScript モジュールをプリロードすることで、インポートの 'ウォーターフォール' を回避し、アプリケーションの起動を高速化します。 異なるトレードオフを持つ3つの戦略があります:

  • modulepreload - <link rel="modulepreload"> を使用します。これは Chromium ベースのブラウザ、Firefox 115 以上、Safari 17 以上ではベストな結果をもたらします。古いブラウザでは無視されます。
  • preload-js - <link rel="preload"> を使用します。Chromium と Safari でウォーターフォールを防ぎますが、Chromium は書くモジュールを2回パースします (script として1回、module として1回)。Firefox ではモジュールが2回リクエストされるようになります。これは、Chromium ユーザーのパフォーマンスをわずかに低下させるのと引き換えに、iOS デバイスのユーザーのパフォーマンスを最大化したい場合には有効な設定です。
  • preload-mjs - <link rel="preload"> を使用しますが、.mjs 拡張子であるため、Chromium が二重でパースすることを防ぎます。一部の静的 Web サーバーでは、.mjs ファイルを Content-Type: application/javascript ヘッダーとともに提供すると失敗となり、アプリケーションを壊すことになります。それがもしあなたにあてはまらないのなら、modulepreload がより広くサポートされるまで、これが多くのユーザーにベストなパフォーマンスをもたらすオプションです。

paths

ts
assets?: '' | `http://${string}` | `https://${string}`;
  • default ""

アプリのファイルが提供される絶対パス(absolute path)です。これは、何らかのストレージバケットからファイルを提供する場合に有用です。

ts
base?: '' | `/${string}`;
  • default ""

ルート相対なパス(root-relative path)です。空文字(empty string)以外を指定する場合、先頭は / を付ける必要があり、末尾には / を付けてはいけません (例: /base-path)。アプリがどこから提供されるかを指定することで、アプリをルートではないパス(non-root path)で動作させることができます。ルート相対(root-relative)なリンクには、先頭に base の値を追加しなければなりません。そうしないとリンクが base ではなくドメインのルート(root)を指してしまいます(これはブラウザの動作によるものです)。これを行うには、base from $app/paths をインポートして <a href="{base}/your-page">Link</a> のようにします。もし、これを頻繁に書くようであれば、再利用可能なコンポーネントに抽出するのも良いでしょう。

ts
relative?: boolean | undefined;
  • default undefined

相対アセットパスを使うかどうか。デフォルトでは、paths.assets が外部ではない場合、SvelteKit は %sveltekit.assets% を相対パスに置き換え、ビルド成果物の参照に対する相対パスを使用しますが、$app/paths からインポートする baseassets は、あなたの設定で指定された通りになります。

true の場合、$app/paths からインポートする baseassets は、サーバーサイドレンダリング中に相対アセットパスに置き換えられ、ポータブルな HTML になります。 false の場合、%sveltekit.assets% とビルド成果物への参照は、paths.assets が外部 URL でない限り、常にルート相対(root-relative)なパスとなります。

もしアプリで <base> 要素を使用している場合、これを false に設定してください。そうしないとアセットの URL が誤って現在のページではなく <base> URL に対して解決されてしまいます。

prerender

プリレンダリング をご覧ください。

ts
concurrency?: number;
  • default 1

同時にいくつのページをプリレンダリングできるか。JS はシングルスレッドですが、プリレンダリングのパフォーマンスがネットワークに縛られている場合(例えば、リモートの CMS からコンテンツをロードしている場合)、ネットワークの応答を待っている間に他のタスクを処理することで高速化することができます。

ts
crawl?: boolean;
  • default true

SvelteKit が entries からリンクをたどってプリレダリングするページを探すかどうか。

ts
entries?: Array<'*' | `/${string}`>;
  • default ["*"]

プリレンダリングするページ、または (crawl: true の場合は) クローリングを開始するページの配列。* 文字列は、全ての動的でないルート(route) (つまり、[parameters] がないページです。なぜなら、SvelteKit は その parameters がどんな値を持つかわからないからです) が含まれます。

ts
handleHttpError?: PrerenderHttpErrorHandlerValue;
  • default "fail"

アプリのプリレンダリング中に発生した HTTP エラーに対する応答方法。

  • 'fail' — ビルドを失敗させます
  • 'ignore' - 失敗(failure)を無視して継続させます
  • 'warn' — 継続しますが、警告(warning)をプリントします
  • (details) => voidstatuspathreferrerreferenceTypemessage プロパティを持つ details オブジェクトを引数に取るカスタムのエラーハンドラです。この関数から throw されると、ビルドが失敗します
svelte.config.js
ts
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
prerender: {
handleHttpError: ({ path, referrer, message }) => {
// ignore deliberate link to shiny 404 page
if (path === '/not-found' && referrer === '/blog/how-we-built-our-404-page') {
return;
}
// otherwise fail the build
throw new Error(message);
}
}
}
};
ts
handleMissingId?: PrerenderMissingIdHandlerValue;
  • default "fail"

あるプリレンダリングページから別のプリレンダリングページへのハッシュリンクが、リンク先ページの id に対応していない場合の応答方法

  • 'fail' — ビルドを失敗させます
  • 'ignore' - 失敗(failure)を無視して継続させます
  • 'warn' — 継続しますが、警告(warning)をプリントします
  • (details) => voidpathidreferrersmessage プロパティを持つ details オブジェクトを引数に取るカスタムのエラーハンドラです。この関数から throw されると、ビルドが失敗します
ts
handleEntryGeneratorMismatch?: PrerenderEntryGeneratorMismatchHandlerValue;
  • default "fail"

entries エクスポートで生成されたエントリーが、生成されたルート(route)とマッチしない場合の応答方法。

  • 'fail' — ビルドを失敗させます
  • 'ignore' - 失敗(failure)を無視して継続させます
  • 'warn' — 継続しますが、警告(warning)をプリントします
  • (details) => voidgeneratedFromIdentrymatchedIdmessage プロパティを持つ details オブジェクトを引数に取るカスタムのエラーハンドラです。この関数から throw されると、ビルドが失敗します
ts
origin?: string;
  • default "http://sveltekit-prerender"

origin — プリレンダリング時の url.origin の値です。レンダリングされたコンテンツに含まれていると有用な場合があります。

serviceWorker

ts
register?: boolean;
  • default true

service worker が存在する場合、自動的に登録するかどうか。

ts
files?(filepath: string): boolean;
  • default (filename) => !/\.DS_Store/.test(filename)

static ディレクトリにあるどのファイルを $service-worker.files で利用可能にするかを決定します。

typescript

ts
config?: (config: Record<string, any>) => Record<string, any> | void;
  • default (config) => config

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.

version

アプリが使用されているときにアプリの新しいバージョンをデプロイするとクライアントサイドのナビゲーションにバグが発生することがあります。次に開くページのコードがすでにロードされている場合、そこに古いコンテンツがある可能性があります。そうでなくとも、アプリのルートマニフェスト(route manifest)が、もう存在しない JavaScript ファイルを指している可能性があります。 SvelteKit はバージョン管理によってこの問題を解決します。 SvelteKit がページの読込中にエラーに遭遇し、新しいバージョンがデプロイされていることを検知した場合 (ここで指定される name を使用します。デフォルトはビルドのタイムスタンプです)、従来のフルページナビゲーションにフォールバックされます。 しかし、すべてのナビゲーションがエラーとなるわけではありません。例えば次のページの JavaScript がすでに読み込まれている場合です。このような場合でもフルページナビゲーションを強制したい場合は、pollInterval を設定してから beforeNavigate を使用する、などのテクニックを使用します:

+layout.svelte
<script>
	import { beforeNavigate } from '$app/navigation';
	import { updated } from '$app/stores';

	beforeNavigate(({ willUnload, to }) => {
		if ($updated && !willUnload && to?.url) {
			location.href = to.url.href;
		}
	});
</script>

pollInterval を 0 以外の値に設定した場合、SvelteKit はバックグラウンドで新しいバージョンをポーリングし、それを検知すると updated ストアの値を true にします。

ts
name?: string;

アプリの現在のバージョンの文字列です。これを指定する場合は、決定論的なものでないといけません (例えば Math.random()Date.now().toString() ではなく commit ref )。指定しない場合は、ビルドのタイムスタンプがデフォルトとなります

例えば、現在のコミットハッシュを使用するには、git rev-parse HEAD を使用することができます:

svelte.config.js
ts
import * as child_process from 'node:child_process';
export default {
kit: {
version: {
name: child_process.execSync('git rev-parse HEAD').toString().trim()
}
}
};
ts
pollInterval?: number;
  • default 0

バージョンの変更をポーリングするインターバル(ミリ秒)です。これが 0 の場合、ポーリングは発生しません。