🚀 SvelteKit Monorepo + Cloudflare: One-Click Deploy & Auto-Setup Detailed Manual

This project is built on top of a SvelteKit monorepo architecture and seamlessly integrates with serverless infrastructures like Cloudflare D1, KV Namespace, and Cloudflare Pages.

To prevent configuration omissions or database connection loss common in multi-app monorepos, a one-click automated setup script is built-in. This manual guides you through the local environment configuration required before running the script, and explains the terminal prompt options for each installation mode.

📂 1. Pre-requisites Before Running the Script

To prevent unexpected runtime halts, the setup script performs a pre-validation check (Step 0) on local secret variables (.dev.vars). You must complete the following configuration steps before triggering the command.

🔑 1-1. Create and Configure .dev.vars Files

Duplicate .dev.vars.example in both app directories to create .dev.vars files and fill in the necessary keys.

1. Blog App Secrets

   • Location: apps/blog/.dev.vars
   • Required Key:

     BETTER_AUTH_SECRET="your_long_random_secret_string"
     

     (Provide a complex, unique secret string to encrypt authorization sessions and tokens. Leaving it empty or just double quotes will fail the validation.)

2. Admin App Secrets

   • Location: apps/admin/.dev.vars

   • Required Key:

     ADMIN_PASSWORD="your_admin_dashboard_password"
     

     (Set the password for accessing the admin panel dashboard.)

   • Google Analytics 4 (GA4) & Google AdSense Dummy Data:
     If you want to test the widgets on the dashboard landing page with dummy (simulated) data instead of a live API connection, you must leave the Google integration variables (GA4_PROPERTY_ID, ADSENSE_ACCOUNT_ID, etc.) blank or completely remove them from both local .dev.vars and the Cloudflare Pages remote environment settings. The dashboard automatically falls back to dummy simulation mode if any of these configuration keys are missing.

[!WARNING]
If these files do not exist or the required credentials are empty, the CLI will output an error and halt immediately:

❌ apps/admin/.dev.vars file does not exist.
   (Please copy apps/admin/.dev.vars.example to create it and configure ADMIN_PASSWORD.)

🛠️ 2. Command Reference

💬 3. Terminal Prompt Step-by-Step Guide

Here is a comprehensive breakdown of the actual prompts (English & Korean) printed during execution and their corresponding impacts.

🌐 3-1. Shared Initial Prompts (Common for both setup & setup:select)

Q1. Select Default Blog Language (Database Seeding Language)

Determines the language of the default guide posts and configurations inserted into your Cloudflare D1 database.

  [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]
  > 

• Guide: Press 1 for Korean, 2 for English, or 3 for Japanese. It seeds the D1 database with translated mock posts and system settings according to the selection.

Q2. Select Setup Mode for Remaining Steps

Decide whether to execute a fully automated pipeline or customize every single bind variable.

  [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 (Default): Automatically provisions Pages projects (svelteblog and svelteadmin), detects active Cloudflare sessions, runs migrations, and triggers a build-and-deploy flow without asking questions.
• 2) Custom Interactive Setup: Transitions to custom configuration mode (equivalent to running npm run setup:select directly) and prompts you with questions Q3 through Q8.

🎨 3-2. Custom Interactive Prompts (npm run setup:select only)

[!TIP]
All prompts during the custom interactive phase can be answered by simply pressing Enter to fall back to the safe, standard defaults displayed inside the brackets [Default: ...]. You do not have to manually fill out every field.

Q3. Custom Deploy Project Names

Specify unique project names to register on Cloudflare Pages. (The service URLs will default to https://[project-name].pages.dev.)

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

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

• Guide: Press enter to use the defaults. If you already have existing projects with these names in your Cloudflare dashboard, type a unique name to avoid conflicts. (This also updates deployment scripts inside package.json dynamically.)

Q4. Cloudflare Wrangler Login

Triggers authorization checks.

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

• Guide: If no active session is detected, it redirects you to the browser. If a valid login exists, the script skips it automatically. Select Y if you wish to switch or re-authenticate Cloudflare accounts.

Q5. Database Initialization Mode (Fresh vs Keep)

Specify whether to keep your remote database tables or clear them.

  [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): Permanently deletes existing D1 databases and KV namespaces on Cloudflare. Do not choose this unless you are setting up a test environment from scratch.
• Keep Existing Data (2, Recommended/Default): Re-uses your active D1 tables and KV records. Your articles and visitor logs will remain intact.

Q6. Custom Cloudflare Resource Labels

Customize the actual names of the D1 databases and KV namespace instances.

  [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 이름을 입력하세요
  > 

• Guide: Leave blank and press enter to generate unique labels with random suffixes (xxxxxx), or type custom names to match your naming guidelines.

Q7. Cloudflare CDN Cache Purge Integration

Configure automatic edge cache invalidation when posts are modified.

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

• Guide: Selecting y triggers prompt inputs for your Cloudflare Zone ID and API Token. These credentials will be written to local .dev.vars files and synchronized as remote secrets automatically.

Q8. Direct Deployment Confirmation

Choose whether to immediately compile the code and ship it to Cloudflare Pages.

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

• Guide: Press Y to trigger immediate builds and deployments. The script will output the resulting live URLs. Press n if you only want to update configuration files (wrangler.json) locally.

🔒 3-3. Post-Build Synchronization Prompts (IP Whitelisting & Translations)

During the compilation stage (sync-secrets.js), you may encounter additional prompts concerning admin security and i18n synchronization.

Q9. Admin IP Mismatch Warning

The admin panel uses a strict IP whitelist (ALLOWED_IP) for security. The script dynamically checks your machine's current public IP address and flags a mismatch if it is not in the whitelist:

  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 (Default): Keeps your whitelist configurations unchanged. You might be blocked from the dashboard if your current network environment differs from the registered one.
• 2) Add current machine IP to list: Appends your current public IP using a comma separator. Recommended for admins managing the blog from multiple locations (e.g., home and office).
• 3) Replace with current machine IP: Clears all registered IPs and sets only your current IP as the sole allowed address.

Q10. Force Sync i18n Translations to D1 Database

Decide whether to overwrite remote translation tables with local code definitions:

[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]
  > 

• Guide: Select N if you have edited translations directly in the admin dashboard settings page to prevent losing changes. Select y if you want to overwrite database values with local source code files (packages/shared/src/i18n/index.ts).

🔄 4. Backup & Restore Mechanism (npm run restore)

Once a setup finishes successfully, a wrangler.backup.json configuration backup file is automatically generated in your root directory.

{
    "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"
}

If you relocate or switch development environments:

• Running npm run restore reads this backup file to lock project names and restore exact resource bindings automatically.
• It safely skips database seeding to prevent overwriting or wiping your operational articles and visitor data.

❓ 5. Troubleshooting

🚨 1. Wrangler Whoami Session or Authorization Failure

• Symptom: CLI prints authentication or access errors when provisioning D1/KV resources.
• Solution: Run npm run setup:select and enter Y at the Q4. Run wrangler login prompt to trigger a fresh browser authentication. The script only requests minimal account permissions (account:read, user:read, workers:write, pages:write, d1:write, workers_kv:write) for security.

🚨 2. Windows Script Execution Policy Blocked

• Symptom: PowerShell restricts script executions due to authorization policies.
• Solution: The setup script automatically overrides paths and uses npx.cmd on Windows. We recommend running commands via Git Bash or CMD (Command Prompt) rather than standard PowerShell.