🚀 SvelteKit Monorepo + Cloudflare ワンクリックデプロイ＆自動セットアップ詳細説明書

本プロジェクトは SvelteKit モノレポ環境を基盤としており、サーバーレスデータベースである Cloudflare D1 と KV Namespace、そして Cloudflare Pages デプロイインフラを有機的に使用しています。

モノレポのマルチアプリケーション構造で発生しがちな、データベース接続情報の紛失、環境変数の不一致、手動 CLI によるバインディング設定の複雑さを最小限に抑えるため、ワンクリック自動セットアップスクリプトが標準で内蔵されています。このマニュアルでは、スクリプト実行前に準備すべきローカル環境設定から、実行中に表示されるターミナル選択プロンプトの意味とモード別の活用方法まで詳しく紹介します。

📂 1. スクリプト実行前の事前準備事項

セットアップスクリプトは、実行中の予期せぬエラーによる強制終了を防ぐため、Step 0 段階で必須のローカル環境変数（.dev.vars）が正しく用意されているか事前に検証します。スクリプトを実行する前に、必ず以下の準備を完了させてください。

🔑 1-1. `.dev.vars` ファイルの作成と必須値の設定

プロジェクトのルートディレクトリを基準に、ブログアプリと管理（Admin）アプリそれぞれのパスにある .dev.vars.example ファイルをコピーして .dev.vars ファイルを作成し、適切な値を記入します。

ブログアプリ用環境変数
- 場所: apps/blog/.dev.vars
- 必須設定項目:
```
BETTER_AUTH_SECRET="任意の長いランダムな文字列"
```
  (認証セッションとトークンを暗号化するために使用される、固有かつ複雑な秘密文字列を記入します。空のままにしたり、ダブルクォーテーションのみの場合は検証に失敗します。)
管理（Admin）アプリ用環境変数
- 場所: apps/admin/.dev.vars
- 必須設定項目:
```
ADMIN_PASSWORD="管理者ログインパスワード"
```
  (管理者ダッシュボードへのログイン時に使用するパスワードを記入します。)
- Google Analytics 4 (GA4) ＆ Google AdSense のダミーデータ表示について:
  もし管理者ダッシュボードのメイン画面で、GA4 アクセス統計や AdSense 実績レポートの**ダミーデータ（シミュレーション用の表示例）を確認して動作テストをしたい場合は、ローカルの .dev.vars ファイルおよび Cloudflare Pages のリモート設定から、Google 連携関連の環境変数（GA4_PROPERTY_ID, ADSENSE_ACCOUNT_ID など）の項目を空にするか、完全に削除（またはコメントアウト）**してください。連携に必要なキーが1つでも不足している場合、システムは自動的にダミーデータ表示モードを有効にします。

[!WARNING]
これらのファイルが存在しない、あるいは必須値が空の場合は、ターミナルに以下のような警告メッセージが表示され、セットアップが強制中断されます。
❌ apps/admin/.dev.vars ファイルが存在しません。
   (apps/admin/.dev.vars.example ファイルをコピーして作成し、ADMIN_PASSWORDを設定してください。)

🛠️ 2. コマンドの種類と実行方法

コマンド	実行目的	特徴
`npm run setup`	基本全自動インストール＆デプロイ	初期の基本言語を選択するだけで、リソースの生成から最終ビルド・デプロイまでノンストップで自動進行します。
`npm run setup:select`	カスタム対話型セットアップ	デプロイプロジェクト名、データの維持/初期化、リソース名の変更、CDN キャッシュパージ連携などを細かく調整できます。
`npm run restore`	バックアップからの復元・同期	`wrangler.backup.json` バックアップファイルを参照して、既存のテーブルデータを保護したまま安全にインフラを再構築してデプロイします。

💬 3. 実行段階別ターミナルプロンプトガイド (Prompt Guide)

スクリプト実行中にターミナル画面に表示される実際の日本語・英語プロンプトと、各選択肢がインフラに与える影響について解説します。

🌐 3-1. 共通初期プロンプト (npm run setup & setup:select 共通)

Q1. デフォルトブログ言語の選択 (初期シードデータの言語設定)

D1 データベースに最初に注入される初期のガイド記事および基本設定の言語を決定します。

  [EN] Select default blog language:
  [KO] 기본 블로그 언어를 선택하세요:
  1) Korean / 한국어 (ko) [Default]
  2) English / 영어 (en)
  3) Japanese / 日本語 (ja)
  [EN] Choose option (1/2/3) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2/3) [기본값: 1]
  >

ガイド: デフォルト値である 1 を選択すると韓国語の初期データが生成されます。2 を入力すると英語、3 を入力すると日本語に翻訳された初期ガイドデータがデータベースに登録されます。

Q2. 進行モードの選択

残りのセットアッププロセスを完全に自動で実行するか、カスタマイズしながら手動で入力するかを決定します。

  [EN] Choose setup mode for the remaining steps:
  [KO] 나머지 설정의 진행 방식을 선택하세요:
  1) Full Auto Setup & Deploy / 풀 자동 설정 및 배포 [Default]
  2) Custom Interactive Setup / 사용자 지정 직접 선택 설정
  [EN] Choose option (1/2) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2) [기본값: 1]
  >

1) Full Auto Setup & Deploy (デフォルト値): ブログおよび管理画面の Pages プロジェクト名を基本規格（svelteblog, svelteadmin）で自動生成し、Cloudflare ログイン状態を検証後、すべてのマイグレーションとデプロイを自動で完了させます。
2) Custom Interactive Setup: 詳細カスタム設定モードに移行し、後述する追加質問（Q3〜Q8）が順次表示されます。 (npm run setup:select コマンドを実行した場合は、最初からこのモードで開始されます。)

🎨 3-2. カスタム対話型プロンプト (`npm run setup:select` 専用)

[!TIP]
カスタム対話型セットアップで表示されるすべての質問プロンプトは、値を入力せずにそのままエンターキー（Enter）を押すだけで、角括弧 [Default: ...] に表示されている安全なデフォルト値が自動で適用されます。そのため、複雑な入力を行わずエンターを連打して進行しても全く問題ありません。

Q3. デプロイプロジェクト名のカスタム

Cloudflare Pages 上に新規作成するデプロイプロジェクトの名前を指定します。 (デフォルトのアクセス URL は https://[プロジェクト名].pages.dev になります。)

  [EN] Enter Blog project name [Default: svelteblog]
  [KO] 블로그 배포명을 입력하세요
  > 

  [EN] Enter Admin project name [Default: svelteadmin]
  [KO] 어드민 배포명을 입력하세요
  >

ガイド: 空欄のままエンターキーを押すとデフォルト名が使用されます。Cloudflare アカウント内で他のプロジェクト名と重複しないように固有の名前をつけたい場合は、手動で入力してください。 (入力すると、package.json 内のビルド・デプロイスクリプトも自動でそのプロジェクト名に書き換わります。)

Q4. Cloudflare アカウントのログイン実行可否

Cloudflare API 制御のための認証処理を判定します。

  [EN] Run wrangler login?
  [KO] Wrangler 로그인을 진행할까요?
  [EN] (Y/n) [Default: Y]
  [KO] (Y/n) [기본값: Y]
  >

ガイド: ログインが完了していない場合はブラウザが立ち上がり、認証ページに案内されます。既にログイン済みのセッションが検知された場合は自動的にスキップされますが、別のアカウントで再ログインしたい場合は Y を入力してください。

Q5. データ初期化モードの設定 (Fresh vs Keep)

既存の Cloudflare 上のリソース（D1 データベースや KV）のデータを初期化するかどうかを選択します。

  [EN] Select Initialization Mode:
    1: Fresh Install (DELETE existing Cloudflare D1/KV databases and start clean)
    2: Keep Existing Data (Use existing Cloudflare databases to preserve your posts/data)
  [KO] 초기화 모드 선택:
    1: 완전 초기화 (기존 클라우드플레어의 D1/KV 데이터베이스를 모두 삭제하고 새로 생성합니다. 데이터 유실 주의!)
    2: 기존 데이터 유지 (기존에 구축된 클라우드플레어 리소스를 그대로 유지하고 연동합니다.)

  [EN] Choose an option (1/2) [Default: 2]
  [KO] 옵션을 선택하세요 (1/2) [기본값: 2]
  >

Fresh Install (1): 既存の D1 データベースと KV Namespace を完全に削除して新規作成します。テスト環境の構築など、まっさらな状態から再開したい場合以外は選択しないでください。
Keep Existing Data (2, 推奨/デフォルト値): 既に登録されている記事やユーザー情報などのデータを維持したまま、バインディング情報（接続先ID）のみを同期します。

Q6. Cloudflare リソース名の指定

Cloudflare のダッシュボード上で実際に表示される D1 インスタンス名および KV インスタンス名を指定します。

  [EN] Enter Blog DB name [Default: blog-db-xxxxxx]
  [KO] 블로그 DB 이름을 입력하세요
  > 

  [EN] Enter User DB name [Default: user-db-xxxxxx]
  [KO] 유저 DB 이름을 입력하세요
  > 

  [EN] Enter Images KV name [Default: blog-images-kv-xxxxxx]
  [KO] 이미지 KV 이름을 입력하세요
  >

ガイド: 明示的に管理したい特定のデータベース名がある場合は手動入力し、そうでない場合はそのままエンターを押してランダムサフィックス（xxxxxx）が付与されたユニークな名前で自動生成されるようにします。

Q7. Cloudflare CDN キャッシュパージ設定の登録

ブログの記事を追加・修正した際に、エッジサーバー上のキャッシュを即時クリアし、読者に最新の記事内容が即座に反映されるようにするためのパージ用認証情報を登録します。

  [EN] Configure Cloudflare CDN cache purge credentials?
  [KO] CDN 캐시 퍼지 설정을 등록하시겠습니까?
  [EN] (y/N) [Default: N]
  [KO] (y/N) [기본값: N]
  >

ガイド: y を押すと、Cloudflare ダッシュボードの Overview 画面右下で確認できる Zone ID と、APIトークン設定から取得した API Token の入力プロンプトが始まります。入力された資格情報は、ローカルの .dev.vars および Cloudflare Pages 上に安全に同期されます。

Q8. 即時デプロイの実行確認

セットアップ完了後、その場ですぐにアプリケーションのビルドおよび Cloudflare Pages へのデプロイを実行するかどうかを選択します。

  [EN] Deploy directly?
  [KO] 지금 바로 배포하시겠습니까?
  [EN] (Y/n) [Default: Y]
  [KO] (Y/n) [기본값: Y]
  >

ガイド: リソースの接続設定（wrangler.json への書き込み）完了後、すぐに実際の Web サーバーへ反映したい場合は Y を押します。ビルド完了後、最終的に生成されたサービスURLが出力されます。接続設定のみを行いたい場合は n を入力してください。

🔒 3-3. デプロイ同期時の条件付き追加プロンプト (IP & 翻訳辞書)

ビルドおよびデプロイ処理（sync-secrets.js）へ進むと、管理者ページのセキュリティや多言語辞書の保護を判定するためのプロンプトが追加で発生します。

Q9. 管理画面アクセス IP の不一致検知時の処理

管理者ダッシュボードは、不正アクセスを防ぐためにホワイトリスト形式の IP 制限（ALLOWED_IP）を採用しています。スク립トは現在のデプロイマシンのパブリック IP を自動で特定し、保存されている許可リストに含まれていない場合に以下の質問を表示します。

  1) Keep existing allowed IPs / 기존 목록 유지 (현재 기기 미등록) [Default]
  2) Add current machine IP to list / 현재 기기 IP를 목록에 추가 (복수 허용)
  3) Replace with current machine IP / 현재 기기 IP로만 갱신 (기존 목록 제거)

  [EN] Select option (1/2/3) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2/3) [기본값: 1]
  >

1) Keep existing allowed IPs (デフォルト値): 現在のホワイトリストを変更せず維持します。 (現在のネットワーク環境が登録済みの許可 IP と異なる場合、デプロイ完了後に管理画面へアクセスできなくなる可能性があります。)
2) Add current machine IP to list: 既存の許可 IP リストを残したまま、現在デプロイを実行しているネットワークの IP アドレスをカンマ（,）区切りで追加します。自宅や職場など、複数の場所からアクセスを想定している場合はこちらを選択してください。
3) Replace with current machine IP: 登録されていた他の許可 IP をすべて削除し、現在のマシンのパブリック IP アドレスのみをホワイトリストに登録します。

Q10. データベース内多言語翻訳辞書の更新処理

Admin アプリのデプロイ時、モノレポの共通翻訳定義ファイル（packages/shared/src/i18n/index.ts）に開発者が定義した初期翻訳構造（fallbackDictionary）を、リモート D1 データベースの blog_settings テーブルに上書き保存するかどうかを確認します。

[EN] Force sync remote D1 ui_dictionary with local index.ts? (Web changes will be lost)
[KO] D1 DB의 ui_dictionary를 로컬 index.ts 기준으로 강제 덮어쓰시겠습니까? (웹 수정본 유실 주의)
  [EN] Select option (y/N) [Default: N]
  [KO] 옵션을 선택하세요 (y/N) [기본값: N]
  >

ガイド: もし既に管理画面の『設定ダッシュボード』等からユーザー自ら翻訳文を直接書き直している場合は、上書きによりその編集内容が消去されてしまうため、N（デフォルト）を推奨します。ローカルコードで編集した新規翻訳辞書を強制的にサーバーへ同期したい場合のみ y を入力してください。 (なお、初期セットアップ時には整合性を保つため自動で強制同期が行われます。)

🔄 4. バックアップと復元メカニズム (`npm run restore`)

セットアップが正常に完了すると、プロジェクトルートに wrangler.backup.json ファイルが自動生成されます。

{
    "d1": {
        "BLOG_DB": { "name": "blog-db-xxxxxx", "id": "d1-uuid-value" },
        "USER_DB": { "name": "user-db-xxxxxx", "id": "d1-uuid-value" }
    },
    "kv": {
        "IMAGES_KV": "kv-namespace-id"
    },
    "blogProjectName": "svelteblog",
    "adminProjectName": "svelteadmin"
}

このバックアップファイルがあることで、将来的にPCを変更したり環境を再構築する際に npm run restore コマンドを使用して安全に復旧することができます。

復元モードでは、プロジェクト名やデータベース等のリソースIDのバインディングが完全に自動で固定・適用されます。
稼働中のデータを上書きしないよう、初期シード（Seeding）データの投入プロセスが安全にスキップされるため、既存の投稿や会員情報を失うことなくデプロイ環境のリンク関係のみを復元できます。

❓ 5. トラブルシューティング

🚨 1. Wrangler Whoami セッションおよび権限エラー

現象: D1 や KV などのリソース生成コマンド実行時に、認証エラーやセッションなしのエラーが表示される。
解決: npm run setup:select を動かし、Q4. Wrangler ログインの段階で Y を入力してブラウザによる再認証を行ってください。スクリプトはアカウントセキュリティのために最小限の権限（account:read, user:read, workers:write, pages:write, d1:write, workers_kv:write）のみを要求します。

🚨 2. Windows 環境でのスクリプト実行制限エラー

現象: Windows の PowerShell などでスクリプトの実行ポリシーにより動作がブロックされる。
解決: スクリプトは Windows を検知すると自動的に npx の代わりに npx.cmd を呼び出して回避するように設計されていますが、基本的には通常の PowerShell よりも Git Bash または **コマンドプロンプト（CMD）**を使用して実行することをお勧めします。

SvelteKit Monorepo + Cloudflare ワンクリックデプロイ＆自動セットアップ詳細説明書

🚀 SvelteKit Monorepo + Cloudflare ワンクリックデプロイ＆自動セットアップ詳細説明書

📂 1. スクリプト実行前の事前準備事項

🔑 1-1. `.dev.vars` ファイルの作成と必須値の設定

🛠️ 2. コマンドの種類と実行方法

💬 3. 実行段階別ターミナルプロンプトガイド (Prompt Guide)

🌐 3-1. 共通初期プロンプト (npm run setup & setup:select 共通)

Q1. デフォルトブログ言語の選択 (初期シードデータの言語設定)

Q2. 進行モードの選択

🎨 3-2. カスタム対話型プロンプト (`npm run setup:select` 専用)

Q3. デプロイプロジェクト名のカスタム

Q4. Cloudflare アカウントのログイン実行可否

Q5. データ初期化モードの設定 (Fresh vs Keep)

Q6. Cloudflare リソース名の指定

Q7. Cloudflare CDN キャッシュパージ設定の登録

Q8. 即時デプロイの実行確認

🔒 3-3. デプロイ同期時の条件付き追加プロンプト (IP & 翻訳辞書)

Q9. 管理画面アクセス IP の不一致検知時の処理

Q10. データベース内多言語翻訳辞書の更新処理

🔄 4. バックアップと復元メカニズム (`npm run restore`)

❓ 5. トラブルシューティング

🚨 1. Wrangler Whoami セッションおよび権限エラー

🚨 2. Windows 環境でのスクリプト実行制限エラー

ソーシャルネットワークで投稿を共有する

コメント 0件

인기 포스트

태그

후원

🚀 SvelteKit Monorepo + Cloudflare ワンクリックデプロイ＆自動セットアップ詳細説明書

📂 1. スクリプト実行前の事前準備事項

🔑 1-1. .dev.vars ファイルの作成と必須値の設定

🛠️ 2. コマンドの種類と実行方法

💬 3. 実行段階別ターミナルプロンプトガイド (Prompt Guide)

🌐 3-1. 共通初期プロンプト (npm run setup & setup:select 共通)

Q1. デフォルトブログ言語の選択 (初期シードデータの言語設定)

Q2. 進行モードの選択

🎨 3-2. カスタム対話型プロンプト (npm run setup:select 専用)

Q3. デプロイプロジェクト名のカスタム

Q4. Cloudflare アカウントのログイン実行可否

Q5. データ初期化モードの設定 (Fresh vs Keep)

Q6. Cloudflare リソース名の指定

Q7. Cloudflare CDN キャッシュパージ設定の登録

Q8. 即時デプロイの実行確認

🔒 3-3. デプロイ同期時の条件付き追加プロンプト (IP & 翻訳辞書)

Q9. 管理画面アクセス IP の不一致検知時の処理

Q10. データベース内多言語翻訳辞書の更新処理

🔄 4. バックアップと復元メカニズム (npm run restore)

❓ 5. トラブルシューティング

🚨 1. Wrangler Whoami セッションおよび権限エラー

🚨 2. Windows 環境でのスクリプト実行制限エラー

ソーシャルネットワークで投稿を共有する

コメント 0件

인기 포스트

태그

후원

🔑 1-1. `.dev.vars` ファイルの作成と必須値の設定

🎨 3-2. カスタム対話型プロンプト (`npm run setup:select` 専用)

🔄 4. バックアップと復元メカニズム (`npm run restore`)