TypeScript設定

TypeScriptを使用したSvelte 5プロジェクトのセットアップ方法と、最適な設定について解説します。プロジェクトの作成から、tsconfig.jsonの設定、VSCodeの設定まで、実践的な環境構築を行います。

プロジェクトのセットアップ

新規プロジェクトの作成

最新のSvelteKit CLIを使用してTypeScript対応のプロジェクトを作成します。sv createコマンドにより、必要な設定が自動的に最適化され、すぐに型安全な開発を始めることができます。

# npm
npx sv create my-app

# pnpm（高速・推奨）
pnpm dlx sv create my-app
# または、ローカルにバイナリがある場合
pnpm exec sv create my-app

# yarn
yarn dlx sv create my-app

# bun
bunx sv create my-app

# deno
deno run npm:sv create my-app

プロンプトでは以下のオプションを選択します。

┌ Welcome to SvelteKit!
│
◇ Which template would you like?
│ ● SvelteKit minimal （最小構成）
│ ○ SvelteKit demo app （デモアプリ）
│ ○ Library project （ライブラリプロジェクト）
│
◇ Add type checking with TypeScript?
│ ● Yes, using TypeScript syntax （TypeScript構文を使用）
│
◇ Select additional options (スペースで選択、複数可）
│ ◻ Add ESLint for code linting （コードの品質チェック）
│ ◻ Add Prettier for code formatting （コードフォーマット）
│ ◻ Add Playwright for browser testing （E2Eテスト）
│ ◻ Add Vitest for unit testing （ユニットテスト）
│
└ Your project is ready!

推奨オプション

TypeScript syntax: 必須。型安全な開発のため
ESLint: 推奨。コード品質の維持
Prettier: 推奨。一貫したコードスタイル
Vitest: テストを書く場合は推奨

パッケージマネージャの選択

プロジェクトで使用するパッケージマネージャは、チーム全体で統一することが重要です。

# pnpm（推奨 - 高速で効率的）
cd my-app
pnpm install
pnpm dev

# npm（標準）
cd my-app
npm install
npm run dev

# yarn
cd my-app
yarn
yarn dev

# bun（最新・実験的）
cd my-app
bun install
bun dev

パッケージマネージャの違い

pnpm: ディスク容量を節約し、高速。モノレポに最適
npm: Node.js標準。最も広くサポート
yarn: npmの改良版。ワークスペース機能が充実
bun: 最新のランタイム。非常に高速だが成熟度は低い

プロジェクト構造の確認

作成されたプロジェクトの構造を理解しておきましょう。

my-app/
├── src/
│   ├── routes/          # ページとレイアウト
│   │   └── +page.svelte # ホームページ
│   ├── lib/             # 共有コンポーネント・ユーティリティ
│   │   └── index.ts     # $lib エクスポート
│   ├── app.d.ts         # グローバル型定義
│   └── app.html         # HTMLテンプレート
├── static/              # 静的ファイル（画像、フォントなど）
├── tests/               # テストファイル（オプション）
├── .svelte-kit/         # 自動生成される型定義（Git無視）
├── svelte.config.js     # Svelte/SvelteKit設定
├── tsconfig.json        # TypeScript設定
├── vite.config.ts       # Vite設定
└── package.json         # 依存関係とスクリプト

既存プロジェクトへのTypeScript追加

既存のJavaScriptプロジェクトをTypeScriptに移行する場合の手順です。段階的な移行により、既存のコードを壊さずにTypeScriptの恩恵を受けられます。

# 必要なパッケージをインストール
pnpm add -D typescript tslib @tsconfig/svelte svelte-check

# tsconfig.jsonを作成（SvelteKit用に最適化）
cat > tsconfig.json << 'EOF'
{
  "extends": "./.svelte-kit/tsconfig.json",
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "sourceMap": true,
    "strict": true
  }
}
EOF

# 型定義の生成
pnpm exec svelte-kit sync

# 段階的な移行
# 1. .jsファイルを.tsに変更
# 2. .svelteファイルに lang="ts" を追加
# 3. 型エラーを修正

tsconfig.json の設定

TypeScriptプロジェクトの心臓部となるtsconfig.jsonは、コンパイラの動作を制御する重要な設定ファイルです。適切な設定により、型チェックの厳密さ、モジュール解決の方法、出力されるJavaScriptのバージョンなどを細かく制御できます。

推奨設定

Svelte 5プロジェクトに最適化されたtsconfig.jsonの推奨設定を以下に示します。

// tsconfig.json
{
  "extends": "./.svelte-kit/tsconfig.json",
  "compilerOptions": {
    // 厳密な型チェック
    "strict": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "alwaysStrict": true,

    // 追加の型チェック
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,

    // モジュール解決
    "moduleResolution": "bundler",
    "target": "ESNext",
    "module": "ESNext",

    // TypeScript 6 系で重要なモジュール／構文関連オプション
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "erasableSyntaxOnly": true,

    // パスエイリアス
    "paths": {
      "$lib": ["./src/lib"],
      "$lib/*": ["./src/lib/*"]
    }
  },
  "include": ["src/**/*.ts", "src/**/*.svelte"]
}

設定オプションの詳細

厳密な型チェックオプション

strict: すべての厳密な型チェックオプションを有効化
strictNullChecks: null/undefinedの厳密なチェック
strictFunctionTypes: 関数型の厳密なチェック
noImplicitAny: 暗黙的なany型を禁止

追加の型チェックオプション

noUnusedLocals: 未使用のローカル変数を検出
noUnusedParameters: 未使用のパラメータを検出
noImplicitReturns: 暗黙的なreturnを禁止
noUncheckedIndexedAccess: インデックスアクセスの安全性を強化

TypeScript 6 系の新しいモジュール／構文オプション

TypeScript 6 系では、ESM 中心のバンドラ／ランタイム環境（Vite・SvelteKit・Node.js 22+ の直接 TS 実行など）を前提としたオプションが整備されています。SvelteKit プロジェクトでは以下を有効化することが推奨されます。

verbatimModuleSyntax: 型のみ import/export を明示する import type / export type の使用を強制し、コンパイル時に「型だけのインポート」と「ランタイムで残るインポート」を書いたとおりにファイルから消去するか残すかを決定するオプションです。これにより、バンドラ・トランスパイラ（Vite / esbuild / swc など）が単一ファイル単位で正しく不要 import を除去でき、副作用付き import の意図しない削除も防げます。SvelteKit プロジェクトでは true を推奨します。
- 推奨値: true
- 効果: import { type Foo, bar } from '...' のような混在 import を書くと警告。型だけのものは import type { Foo } from '...' に分離する。
isolatedModules: 各ファイルを単一の独立したモジュールとしてトランスパイル可能な構文だけに制限するオプションです。Vite / esbuild / swc など、ファイル単位で TypeScript を JavaScript にトランスパイルするツールチェーンとの相性のために必要です。const enum のような「他ファイルの型情報がないと正しく出力できない」構文を禁止します。SvelteKit が内部で利用する Vite のトランスパイル前提と一致するため、true 必須相当です。
- 推奨値: true
- 効果: const enum や型を再 export する曖昧な構文がエラーになり、export type { ... } への書き換えが必要になります。
erasableSyntaxOnly: TypeScript 専用構文のうち、コンパイル時に単純に消去できる構文だけを許可するオプションです（TS 5.8 で追加、TS 6 系で挙動が安定化）。enum・namespace を伴う値・class のパラメータプロパティ（constructor(private foo: string) 形式）・import = / export = などのランタイム挙動を変える TS 構文を禁止します。Node.js 22+ の --experimental-strip-types（および将来の標準実装）で TypeScript ファイルをそのまま実行する場合に必須です。SvelteKit 本体のソース／設定ファイルを Node から直接実行するパス（vite.config.ts、svelte.config.js から呼ばれるサーバスクリプト等）の互換性を担保できます。
- 推奨値: true（Node 22+ で TS 直接実行を視野に入れる場合）
- 効果: enum・namespace・パラメータプロパティが禁止され、代わりに as const オブジェクト・通常の class フィールド初期化を使うスタイルに統一されます。

SvelteKit と TS 6 系オプションのベストプラクティス

SvelteKit の .svelte-kit/tsconfig.json は既に isolatedModules: true 等を有効化していますが、自分の tsconfig.json 側でも明示的に書くことを推奨します。理由は次の通りです。

verbatimModuleSyntax: true を有効にすると、<script lang="ts"> 内での import type / import の使い分けが矯正され、Svelte コンパイラ・Vite による tree-shaking と整合します。
erasableSyntaxOnly: true を入れておくと、hooks.server.ts や vite.config.ts を将来 Node 22+ で直接実行する際の互換性が保たれます。
既存プロジェクトに後から追加する場合、まず verbatimModuleSyntax から段階的に有効化すると影響範囲を把握しやすくなります。

段階的な厳密性の導入

既存プロジェクトにTypeScriptを導入する場合、段階的に厳密性を上げていくアプローチが有効です。

// 段階1: 最小限の設定から始める
{
  "extends": "./.svelte-kit/tsconfig.json",
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "strict": false
  }
}

// 段階2: 基本的な型チェックを有効化
{
  "extends": "./.svelte-kit/tsconfig.json",
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "strict": false,
    "noImplicitAny": true
  }
}

// 段階3: 完全な厳密モード
{
  "extends": "./.svelte-kit/tsconfig.json",
  "compilerOptions": {
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

グローバル型定義（app.d.ts）

SvelteKitアプリケーション全体で使用する型定義は、app.d.tsファイルで管理します。

app.d.tsの基本構造

// src/app.d.ts
declare global {
  namespace App {
    // エラー型
    interface Error {
      message: string;
      code?: string;
    }

    // ローカル変数（サーバーサイドで使用）
    interface Locals {
      user?: {
        id: string;
        name: string;
        role: 'admin' | 'user';
      };
    }

    // ページデータ
    interface PageData {
      flash?: {
        type: 'success' | 'error';
        message: string;
      };
    }

    // ページ状態
    interface PageState {
      selected?: string;
    }

    // プラットフォーム固有の設定
    interface Platform {}
  }
}

export {};

カスタム型の追加

プロジェクト全体で使用する共通の型定義を追加できます。

// src/app.d.ts
declare global {
  // カスタム型定義
  interface User {
    id: string;
    name: string;
    email: string;
    createdAt: Date;
  }

  interface Post {
    id: string;
    title: string;
    content: string;
    authorId: string;
    publishedAt?: Date;
  }

  // 環境変数の型定義
  namespace NodeJS {
    interface ProcessEnv {
      DATABASE_URL: string;
      API_KEY: string;
      NODE_ENV: 'development' | 'production' | 'test';
    }
  }
}

export {};

VSCode設定

VS CodeでSvelteとTypeScriptの開発体験を最適化するための設定を行います。

.vscode/settings.json

プロジェクトルートに.vscode/settings.jsonファイルを作成し、プロジェクト固有の設定を定義します。

// .vscode/settings.json
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "svelte.enable-ts-plugin": true,
  "[svelte]": {
    "editor.defaultFormatter": "svelte.svelte-vscode"
  },
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.preferences.quoteStyle": "single",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

VS Code 1.85+ では文字列リテラル指定が正しい

VS Code 1.85 以降、editor.codeActionsOnSave 配下の各キーは真偽値ではなく 文字列リテラル（"explicit" / "always" / "never"） を取る仕様に変わりました（旧来の true / false は非推奨で警告が出ます）。

"explicit": 明示的な保存（Ctrl/Cmd + S）時にだけ Code Action を実行（推奨）
"always": 自動保存を含むすべての保存で実行
"never": 実行しない

ESLint の自動修正は "explicit" を選ぶことで、自動保存中の意図しない書き換えを避けられます。

推奨拡張機能

.vscode/extensions.jsonに推奨拡張機能を定義します。

// .vscode/extensions.json
{
  "recommendations": [
    "svelte.svelte-vscode",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss"
  ]
}

拡張機能の説明

Svelte for VS Code: Svelteファイルのシンタックスハイライトと補完
ESLint: コード品質チェック
Prettier: コードフォーマッター
Tailwind CSS IntelliSense: Tailwind CSSを使用する場合

パフォーマンスとビルド設定

型チェックの最適化

大規模プロジェクトでの型チェックを高速化する設定です。

// tsconfig.json の追加設定
{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo",
    "skipLibCheck": true,
    "skipDefaultLibCheck": true
  }
}

ビルド時の型チェック

開発中だけでなく、ビルド時にも型チェックを実行することで、本番環境へのデプロイ前に型エラーを検出できます。

// package.json
{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "preview": "vite preview",
    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
    "check:watch": "svelte-check --tsconfig ./tsconfig.json --watch",
    "lint": "eslint .",
    "format": "prettier --write .",
    "test": "vitest",
    "test:unit": "vitest run",
    "prepare": "svelte-kit sync"
  }
}

CI/CDパイプラインでの型チェック

GitHub Actionsなどを使用して、プルリクエスト時に自動的に型チェックを実行します。

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  type-check:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install

      - run: pnpm check

      - run: pnpm lint

      - run: pnpm test:unit

GitHub Actions のメジャーバージョンを最新に揃える

GitHub Actions の公式アクション（actions/checkout・actions/setup-node など）はメジャーバージョンごとに Node.js ランタイムが更新されます。v3 系は古い Node.js ランタイムに依存しており、2026 年現在は v4 系（Node.js 20 ランタイム） が推奨されます。pnpm/action-setup も v4 以降が現行メンテナンスバージョンです。

トラブルシューティング

TypeScriptとSvelteを使用する際に遭遇する可能性のある問題と、その解決方法を紹介します。

よくある問題と解決策

1. 型定義ファイルが見つからない

SvelteKitが生成する型定義ファイルが見つからない場合の対処法です。

# 型定義を再生成（npx 経由でローカルのバイナリを直接呼ぶ）
npx svelte-kit sync

# 推奨: package.json の "prepare" スクリプト経由（"prepare": "svelte-kit sync"）
npm run prepare

# pnpm の場合
pnpm exec svelte-kit sync

2. VS Codeで型エラーが表示されない

VS Codeが正しくTypeScriptを認識していない場合の解決方法です。

# TypeScriptバージョンの確認
npx tsc --version

# VS CodeでワークスペースのTypeScriptを使用
# Cmd/Ctrl + Shift + P → "TypeScript: Select TypeScript Version"
# "Use Workspace Version"を選択

3. $app/pathsなどのインポートエラー

SvelteKitの特殊なモジュールがインポートできない場合の対処法です。

// tsconfig.jsonの確認
// "extends": "./.svelte-kit/tsconfig.json" が必須
// この設定により、SvelteKitの型定義が読み込まれる

4. Svelte 5のRunesが認識されない

最新のSvelte 5とsvelte-checkがインストールされていることを確認します。

# 最新版にアップデート
pnpm update svelte@latest
pnpm update svelte-check@latest

デバッグのヒント

TypeScriptのログを有効化

VS Codeで詳細なTypeScriptログを確認できます。

Cmd/Ctrl + Shift + P → “TypeScript: Open TS Server Log”
ログレベルを”Verbose”に設定
問題の詳細を確認

型定義の確認

型がどのように推論されているか確認する方法

// VS Codeでホバーして型を確認
let value = $state(0); // ホバーで型を表示

// 明示的な型チェック
type Check = typeof value; // number

まとめ

このページでは、Svelte 5プロジェクトのTypeScript環境構築について解説しました。

プロジェクトセットアップ - sv createコマンドでの新規作成
tsconfig.json設定 - 最適な型チェック設定
グローバル型定義 - app.d.tsでの型管理
VSCode設定 - 開発体験の最適化
パフォーマンス最適化 - ビルドとCI/CDの設定
トラブルシューティング - よくある問題の解決

これらの設定により、型安全で生産的なSvelte開発環境が構築できます。

次のステップ

プロジェクトの設定が完了したら、次はSvelteコンポーネントでTypeScriptを使う方法を学びましょう。

なぜTypeScriptが必要か - TypeScriptの重要性を理解
TypeScript統合 - SvelteコンポーネントでのTypeScriptの使い方
TypeScriptパターン - 高度な型定義パターンとベストプラクティス

TypeScript設定

プロジェクトのセットアップ#

新規プロジェクトの作成#

パッケージマネージャの選択#

プロジェクト構造の確認#

既存プロジェクトへのTypeScript追加#

tsconfig.json の設定#

推奨設定#

設定オプションの詳細#

厳密な型チェックオプション#

追加の型チェックオプション#

TypeScript 6 系の新しいモジュール／構文オプション#

段階的な厳密性の導入#

グローバル型定義（app.d.ts）#

app.d.tsの基本構造#

カスタム型の追加#

VSCode設定#

.vscode/settings.json#

推奨拡張機能#

拡張機能の説明#

パフォーマンスとビルド設定#

型チェックの最適化#

ビルド時の型チェック#

CI/CDパイプラインでの型チェック#

トラブルシューティング#

よくある問題と解決策#

1. 型定義ファイルが見つからない#

2. VS Codeで型エラーが表示されない#

3. $app/pathsなどのインポートエラー#

4. Svelte 5のRunesが認識されない#

デバッグのヒント#

TypeScriptのログを有効化#

型定義の確認#

まとめ#

次のステップ#

プロジェクトのセットアップ

新規プロジェクトの作成

パッケージマネージャの選択

プロジェクト構造の確認

既存プロジェクトへのTypeScript追加

tsconfig.json の設定

推奨設定

設定オプションの詳細

厳密な型チェックオプション

追加の型チェックオプション

TypeScript 6 系の新しいモジュール／構文オプション

段階的な厳密性の導入

グローバル型定義（app.d.ts）

app.d.tsの基本構造

カスタム型の追加

VSCode設定

.vscode/settings.json

推奨拡張機能

拡張機能の説明

パフォーマンスとビルド設定

型チェックの最適化

ビルド時の型チェック

CI/CDパイプラインでの型チェック

トラブルシューティング

よくある問題と解決策

1. 型定義ファイルが見つからない

2. VS Codeで型エラーが表示されない

3. $app/pathsなどのインポートエラー

4. Svelte 5のRunesが認識されない

デバッグのヒント

TypeScriptのログを有効化

型定義の確認

まとめ

次のステップ