OUTPUTYUTAHHH
【Cloudflare Pages】Astro + Svelte 環境を静的ページでデプロイ

【Cloudflare Pages】Astro + Svelte 環境を静的ページでデプロイ

今回は、最近取り組んだ Astro + Svelte 5 + TailwindCSS 4 で構築したプロジェクトを Cloudflare Pages にデプロイした際の詳細な手順について、備忘録も兼ねてまとめてみることにしました。

Cloudflare #Astro#Svelte#Cloudflare

【Cloudflare Pages】Astro + Svelte 環境を静的ページでデプロイ

サムネイル

今回は、最近取り組んだ Astro + Svelte 5 + TailwindCSS 4 で構築したプロジェクトを Cloudflare Pages にデプロイした際の詳細な手順について、備忘録も兼ねてまとめてみることにしました。

更新日: 6/16/2025

実際に作業したリポジトリはこちらで公開しています。

Wrangler CLI を使ったデプロイ方法を中心に、ローカルでの開発環境についても触れていきますので、同様の構成で開発されている方の参考になれば幸いです。

なぜCloudflare Pagesなのか

個人開発や小規模なプロジェクトでフロントエンドをホスティングする際、手軽さとパフォーマンスが重要になります。Cloudflare Pagesは、静的サイトのホスティングサービスとして非常に強力で、グローバルなCDN配信や簡単なデプロイフローを提供してくれます。

今回は、AstroとSvelteを使ったモダンな構成のプロジェクトを、コマンドライン（Wrangler CLI）ベースで効率的にデプロイする手順を確立したいと考え、検証を行いました。

デプロイ手順について

最終的には、以下の3つのデプロイ方法をスムーズに使い分けられる状態を目指しました。

  1. Wrangler CLIによる手動デプロイ: ローカルからコマンド一つで本番・プレビュー環境へデプロイします。
  2. GitHub連携による自動デプロイ: mainブランチへのプッシュをトリガーに自動でデプロイします。
  3. ローカルでの互換環境テスト: デプロイ前に、Cloudflare Pagesの実行環境をローカルで再現して確認します。

この記事では、特に Wrangler CLI を使ったセットアップとデプロイフローに焦点を当てて解説します。

デプロイに向けた設定変更

まず、AstroプロジェクトをCloudflare Pagesにデプロイするために、いくつかの設定ファイルを追加・変更しました。変更後の最終的なファイルは以下の通りです。

1. astro.config.mjs の設定

Cloudflare Pagesは静的サイトホスティングなので、Astroの出力をstaticに指定し、サイトURLなどを設定しました。

import { defineConfig } from "astro/config";
import svelte from "@astrojs/svelte";
import tailwindcss from "@tailwindcss/vite";

// https://astro.build/config
export default defineConfig({
  integrations: [svelte()],
  output: "static",

  build: {
    format: "file",
    inlineStylesheets: "auto",
  },

  site: "https://svelte-study-frontend.pages.dev",

  vite: {
    plugins: [tailwindcss()],
    build: {
      target: "es2020",
      cssCodeSplit: true,
      rollupOptions: {
        output: {
          manualChunks: {
            vendor: ["svelte"],
          },
        },
      },
    },
  },
});

2. package.json の設定

Wrangler CLIを使ったデプロイ操作を簡単にするためのスクリプトを追加しました。また、wranglerパッケージ自体もdevDependenciesに含めています。

{
  "name": "frontend",
  "type": "module",
  "version": "0.0.1",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro",
    "deploy": "wrangler pages deploy dist",
    "deploy:preview": "wrangler pages deploy dist --branch preview",
    "cf:dev": "wrangler pages dev dist"
  },
  "dependencies": {
    "@astrojs/svelte": "^7.1.0",
    "astro": "^4.14.0",
    "svelte": "^5.0.0-next.203",
    "tailwindcss": "^4.0.0-alpha.17",
    "typescript": "^5.8.3"
  },
  "devDependencies": {
    "sass": "^1.89.2",
    "wrangler": "^4.20.0"
  }
}

3. wrangler.toml の作成

Wranglerがプロジェクトを認識するための設定ファイルです。プロジェクト名やビルド出力先ディレクトリを指定します。

name = "svelte-study-frontend"
compatibility_date = "2024-06-15"
pages_build_output_dir = "dist"

4. _headers ファイルでキャッシュ設定を最適化

Cloudflare Pagesでは、_headersというファイルをpublicディレクトリに配置することで、配信されるファイルにHTTPヘッダーを付与できます。今回は、静的アセットに長期間のブラウザキャッシュを設定し、パフォーマンス向上を図りました。

# Cloudflare Pages Headers Configuration

# Basic security and performance headers
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Cache-Control: public, max-age=3600

# Static assets - longer cache
/assets/*
  Cache-Control: public, max-age=31536000, immutable

# JavaScript and CSS files
/*.js
  Cache-Control: public, max-age=31536000, immutable

/*.css
  Cache-control: public, max-age=31536000, immutable

Wrangler CLIによるデプロイ手順

ここからは、実際にWrangler CLIを使ってプロジェクトをデプロイする手順をステップバイステップで解説します。

1. 前提条件

作業を始める前に、ローカル環境に以下のツールがインストールされていることを確認しましょう。

  • Node.js (v18以上)
  • pnpm
  • Cloudflare アカウント

2. Wrangler CLI操作

まず、プロジェクトにWrangler CLIをインストールし、Cloudflareアカウントにログインします。

# プロジェクトのフロントエンドディレクトリに移動
cd frontend

# 依存関係をインストール
pnpm install

# Wrangler CLIをローカルにインストール（推奨）
pnpm add -D wrangler

# Wrangler CLI経由でCloudflareにログイン
npx wrangler login

npx wrangler login を実行すると、ブラウザが自動で開き、Cloudflareへのログインと認証を求められます。認証が成功すると、ターミナルに「Successfully logged in.」と表示されました。

⛅️ wrangler 4.20.0
───────────────────
Attempting to login via OAuth...
Opening a link in your default browser: https://dash.cloudflare.com/oauth2/auth?response_type=code&client_id=xxxxx...
Successfully logged in.

3. Cloudflare Pagesプロジェクトの作成

次に、デプロイ先となるCloudflare Pagesのプロジェクトをコマンドで作成します。

npx wrangler pages project create svelte-study-frontend

実行すると、PRDのブランチ名を聞かれます。今回はmainブランチを本番環境としたかったので、mainと入力しました。

⛅️ wrangler 4.20.0
───────────────────
✔ Enter the production branch name: … main
✨ Successfully created the 'svelte-study-frontend' project.
It will be available at https://svelte-study-frontend.pages.dev/ once you create your first deployment.

これで、Cloudflare上にデプロイを受け付けるためのプロジェクトが作成されました。

4. プロジェクトのビルドとデプロイ

いよいよデプロイです。まずAstroプロジェクトをビルドし、distディレクトリに静的ファイルを生成します。その後、package.jsonに定義したスクリプトを実行してデプロイします。

# プロジェクトをビルド
pnpm run build

# 本番環境へデプロイ
pnpm run deploy

pnpm run deploy を実行すると、wrangler pages deploy distが実行され、ビルド結果がアップロードされます。

> [email protected] deploy /path/to/frontend
> wrangler pages deploy dist

⛅️ wrangler 4.20.0
───────────────────
✨ Success! Uploaded 12 files (1.64 sec)
🌎 Deploying...
✨ Deployment complete! Take a peek over at https://xxxxxxxx.svelte-study-frontend.pages.dev
✨ Deployment alias URL: https://branch-name.svelte-study-frontend.pages.dev

成功すると、2種類のURLが表示されました。これが少し分かりにくかったので、以下に整理します。

プレビューURL

https://xxxxxxxx.svelte-study-frontend.pages.dev

  • xxxxxxxx の部分はデプロイごとに生成されるランダムなハッシュ値です。
  • このURLは、その特定のデプロイバージョンを指し示す固定のURLとなります。

エイリアスURL

https://branch-name.svelte-study-frontend.pages.dev

  • 現在のgitブランチ名（今回はfeature-cloudflare）が付与されたURLです。
  • このURLにアクセスすると、そのブランチの 最新のデプロイ が表示されます。CI/CDなどで非常に便利だと感じました。

本番URL

https://svelte-study-frontend.pages.dev

  • これは、プロジェクト作成時に指定したPRDブランチ（main）からデプロイした場合にのみ、コンテンツが反映されるURLです。

その他のデプロイ・開発手法

Wrangler CLIを使った手動デプロイ以外にも、いくつかの便利な使い方がありましたので紹介します。

プレビュー環境へのデプロイ

本番とは別の環境で動作確認をしたい場合、--branchオプションを使うことで、独立したプレビュー環境を簡単に作成できました。

# プレビュー用のデプロイスクリプトを実行
pnpm run deploy:preview

このコマンドは wrangler pages deploy dist --branch preview を実行し、preview という名前のブランチとしてデプロイします。結果として、https://preview.svelte-study-frontend.pages.dev のような専用のエイリアスURLが生成され、本番環境に影響を与えることなくテストができました。

ローカル開発サーバー（Cloudflare互換）

デプロイ前に、Cloudflare Pagesのランタイム環境をローカルでシミュレートすることも可能です。

# ビルド成果物を元にCloudflare互換サーバーを起動
pnpm run cf:dev

このコマンド (wrangler pages dev dist) を実行すると、http://localhost:8788 でサーバーが起動します。これはAstroのプレビューサーバー (pnpm run preview) とは異なり、_headers ファイルや、もしあればPages Functionsの動作も再現してくれるため、より本番に近い環境での最終確認に役立ちました。

トラブルシューティング

作業中、いくつか躓いた点もありましたので共有します。

ISSUE - 課題

pnpm install 後にビルドすると、依存関係のエラーが発生することがありました。

SOLUTION - 解決策

pnpm store prune でpnpmのローカルキャッシュをクリアした後、pnpm install --frozen-lockfile を実行することで、依存関係がクリーンな状態になり、解決しました。

まとめ

今回の一連の作業を通して、Wrangler CLI を活用することで、AstroプロジェクトをCloudflare Pagesへ非常に効率的にデプロイできることが分かりました。特に、package.jsonにスクリプトをまとめておくことで、誰でも簡単にビルドからデプロイまでを実行できるようになった点は大きな収穫でした。

また、プレビューデプロイやローカルでの互換サーバーなど、開発サイクルをサポートする機能が充実している点もCloudflare Pagesの魅力だと改めて感じました。

参考リンク

検索

検索条件に一致する記事が見つかりませんでした