Zenn
📓

Wrangler CLIではじめるPages+Functions+KV

2023/09/26に公開
Cloudflare
Cloudflare Workers
Cloudflare Pages
tech

はじめに

この記事はCloudflareを利用してToDoアプリを構築する記事です。
次のサービスを利用しています。

  • Cloudflare Pages ... JAMstackプラットフォーム。GitHub/GitLabと結合して、ビルドからCloudflareへのデプロイまで自動で行えます。
  • Cloudflare Pages Functions ... Pagesと動的アプリケーションを結合できるサービスです。Cloudflare Workersのインフラを利用しています。
  • Cloudflare Workers KV ... WorkersやFunctionsから利用できるKey-Valueストアです。Cloudflareの全エッジに保存されるため、地理条件を問わず最速でのアクセスが可能です。

これらはCloudflareのダッシュボードからでも設定可能ですが、今回はWrangler CLIを利用して構築します。

アプリの構成

アプリは次の構成で準備しています。

API側

  • JavaScript
  • フレームワーク未使用
  • KVとの通信をするバージョンとダミーの結果のみ返すダミー版の2つを用意

フロント側

  • JavaScript
  • Vue 3+Quasar Framework

準備

Cloudflareのアカウントは作成済みである前提です。

Wrangler CLIの設定

Wrangler CLIの取得と設定を行います。

$ npm install -g wrangler
$ wrangler login

ブラウザで認可画面（未ログインの場合はログイン画面）が開かれるため許可（Allow）します。

Successfully logged in. となった後、次のコマンドで認可情報が出てくれば完了です。

$ wrangler whoami
Getting User settings...
👋 You are logged in with an OAuth Token, associated with the email xxx@xxx.com!
（略）

リソースのダウンロード

次に、API側のスクリプトやフロント側のビルド済み一式といったリソースを取得します。

https://github.com/taiko19xx/cf_pages_functions_kv_sample/actions/runs/6282526291

Artifacts の欄に3つデータがあるので全てダウンロードして展開しておきます。

$ ls
functions_binding/                     functions_dummy/                     pages/
functions_binding.zip                  functions_dummy.zip                  pages.zip

functions_bindingがAPI側でKVとの通信を行うバージョンで、functions_dummyがダミー版となります。
ファイル構成は共通で次のようになっています。

.
└── functions
    ├── _middleware.js
    ├── todo
    │   └── [id].js
    └── todo.js
  • todo.js ... /todo へリクエストした際に実行されるスクリプトです。GETで一覧の取得、POSTで新規ToDoの追加を行います。
  • todo/[id].js ... /todo/(postId)へリクエストした際に実行されます。PUTでToDoの編集、DELETEでToDoの削除を行います。
  • _middleware.js ... 全スクリプトの実行前後に実行されるスクリプトです。Access-Control-Allow-Origin: *のヘッダ付与と、OPTIONリクエストの際にCORSヘッダを返します。

pagesはビルド済みのアプリ本体です。ビルド前のデータはリポジトリにありますので、必要に応じて参照してください。
作業はこのpagesディレクトリを軸に行います。

Pages設定

リソースの準備が整いましたので、Pagesの設定を進めます。Pagesではプロジェクトという単位でWebサイトを管理していますので、これを作成します。
作成はwrangler pages project createコマンドで行います。今回は質問項目はデフォルトのまま進めます。

$ wrangler pages project create todo-sample-app
✔ Enter the production branch name: … production
✨ Successfully created the 'todo-sample-app' project. It will be available at https://todo-sample-app.pages.dev/ once you create your first deployment.
To deploy a folder of assets, run 'wrangler pages deploy [directory]'.

ダッシュボード上からも作成されたことをが確認できます。

動作確認

次に先ほど取得したリソースを利用して動作確認を行います。

単体

まずはアプリ単体で、ローカルで動作確認をしてみます。実行は簡単で、pagesディレクトリにいる状態でwrangler pages dev ./を実行します。

wrangler pages dev ./
 ⛅️ wrangler 3.9.0
------------------
wrangler dev now uses local mode by default, powered by 🔥 Miniflare and 👷 workerd.
To run an edge preview session for your Worker, use wrangler dev --remote
⎔ Starting local server...
[mf:inf] Ready on http://0.0.0.0:8788
[mf:inf] - http://127.0.0.1:8788
[mf:inf] - http://172.26.145.203:8788

この状態で http://127.0.0.1:8788/ にアクセスするとアプリが表示されます。ただし、API側がまだ入っていないため、ToDoの追加が行えません。

コンソールでxキーを押下してサーバーを一旦停止します。

ダミーのFunctionsと組み合わせる

次にダミー版のスクリプトを組み合わせて再度実行します。functions_dummy内のfunctionsディレクトリごとpagesディレクトリにコピーします。
コピー後、再度wrangler pages devを実行します。

$ cp -r ../functions_dummy/functions ./
$ wrangler pages dev ./
Compiling worker to "/tmp/functionsWorker-0.10245082423740892.mjs"...
✨ Compiled Worker successfully
 ⛅️ wrangler 3.9.0
------------------
wrangler dev now uses local mode by default, powered by 🔥 Miniflare and 👷 workerd.
To run an edge preview session for your Worker, use wrangler dev --remote
⎔ Starting local server...
[mf:inf] Ready on http://0.0.0.0:8788
[mf:inf] - http://127.0.0.1:8788
[mf:inf] - http://172.26.145.203:8788

Compiled Worker successfully という文字がログに入っているため、Functionsの構成が行われていることが確認できます。

この状態で http://127.0.0.1:8788/ にアクセスするとダミーのToDoが追加された状態で表示されます。APIのレスポンスは全てダミーですが、一応ローカルでも完結しているため、一通りの動作は実行するコトが可能です。

コンソールでxキーを押下してサーバーを一旦停止します。

デプロイしてみる

次に、先ほど作成したPagesのプロジェクトに対してデプロイしてみます。デプロイはwrangler pages deployで行います。
この際、プロジェクト名を引数として渡すと、そのプロジェクトに対してデプロイされます。未指定の場合は既存のプロジェクトを選択するか新規に作成することができます。

$ wrangler pages deploy --project-name todo-sample-app ./
✨ Compiled Worker successfully
🌎  Uploading... (17/17)

✨ Success! Uploaded 17 files (2.85 sec)

✨ Uploading Functions bundle
✨ Deployment complete! Take a peek over at https://658dc5dc.todo-sample-app.pages.dev

Pages作成時のURLにアクセスすると、ローカルと同様の画面が表示されます。Functionsもデプロイされているため、一通りの操作は可能です。
ただし、永続化されていないため、リロードすると消えます。

もしDNSや証明書のエラーとなってしまった場合は、少し時間を置いてリロードします。

KV設定

KVとの連携版で動作確認をする前に、KV自体の設定を行います。

namespace作成

はじめに、KVのデータを管理するnamespaceを作成します。作成はwrangler kv:namespace createで行います。

$ wrangler kv:namespace create todo_sample_app
 ⛅️ wrangler 3.9.0
------------------
▲ [WARNING] No configured name present, using `worker` as a prefix for the title


🌀 Creating namespace with title "worker-todo_sample_app"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
{ binding = "todo_sample_app", id = "xxxxx" }

プレフィックスが付与されて作成されました。最後に設定ファイルに記述するよう指定がありますが、今回は使用しませんのでこのまま進みます。

ダッシュボードからも作成できたことが確認できます。

Pagesとのバインディング設定

PagesとKVを連携させるには、バインディングの設定が必要です。ここだけはコマンドで行えないため、ダッシュボードを利用して進めます。

Workers & Pagesから先ほど作成したPagesのプロジェクトを選択し、推移先で「設定」を選択します。

サイドバーに「Functions」があるのでそれを選択し、画面が切り替わったら下にある「KV 名前空間のバインディング」の「バインディングを追加」を選択します。


入力フィールドが現れるので、「変数名」にTODOS、「KV 名前空間」に先ほど作成したnamespaceを設定して、保存を押下します。

反映されれば完了です。

本動作版で動作確認

ローカルで

それではKVと組み合わせたスクリプトに入れ替えて動作確認をしてみます。
スクリプトはfunctions_bindingに入っていますので、ダミー版の時と同様、functionsディレクトリごとpagesディレクトリにコピーします。
コピー後はwrangler pages devを実行しますが、この際KVとして動作させる変数名を--kvオプションで定義して実行します。

$ cp -r ../functions_binding/functions ./
$ wrangler pages dev ./ --kv=TODOS
Compiling worker to "/tmp/functionsWorker-0.5784487148252637.mjs"...
✨ Compiled Worker successfully
 ⛅️ wrangler 3.9.0
------------------
wrangler dev now uses local mode by default, powered by 🔥 Miniflare and 👷 workerd.
To run an edge preview session for your Worker, use wrangler dev --remote
Your worker has access to the following bindings:
- KV Namespaces:
  - TODOS: TODOS
⎔ Starting local server...
[mf:inf] Ready on http://0.0.0.0:8788
[mf:inf] - http://127.0.0.1:8788
[mf:inf] - http://172.26.145.203:8788

KV Namespaces のログがあるため、紐付けが行われています。この時点ではローカルで完結しているため、KVに対してリクエストしたデータはローカルに保存されます。
.wrangler/state/v3/kv/{変数名} のディレクトリに保存されているため、初期化の際はディレクトリごと削除します。

この状態でhttp://127.0.0.1:8788/を開き、これまでと変わらず画面が表示されるのを確認します。今回は永続化状態になっているため、リロードしても前の状態が維持されているはずです。

デプロイしてみる

ローカルでのテストも動作したので、Pagesにデプロイします。
ダミーの時と同様、デプロイはwrangler pages deployで行います。

$ wrangler pages deploy --project-name todo-sample-app ./
✨ Compiled Worker successfully
🌎  Uploading... (17/17)

✨ Success! Uploaded 5 files (12 already uploaded) (2.38 sec)

✨ Uploading Functions bundle
✨ Deployment complete! Take a peek over at https://05d884c9.todo-sample-app.pages.dev

無事デプロイされたので、プロジェクトのページを表示してみます。

そして今回は、リロードしても前の状態が維持されているはずです。ただし、KVへは即時反映されるとは限らない（各エッジへの反映に最大60秒かかる）ため、リロードしても古い状態の可能性があります。
その場合は時間を置いてリロードすると反映されています。

Discussion