テンプレートから新しい Webアプリを作る
——Cloudflare Workers + D1、10手順

0最初に読む——この手順で一番危険なこと

理由は3つが重なるためです。

1前提と検証済みの組み合わせ

• Cloudflare アカウント
• GitHub アカウント
• ローカルに Node は不要。すべてブラウザと Claude Code のクラウド実行環境で完結します

2026年8月8日に、この組み合わせで実際にデプロイまで通しています。

各ステップの「場所」は、ブラウザでやるか、Claude Code に頼むか、人が決めるかの区別です。

2手順1–3

1. リポジトリを複製する — ブラウザ

GitHub で Use this template（テンプレート設定済みの場合）または Fork / 複製して、新しいリポジトリを作る。

2. 作るものを決める — 人

Claude Code に推測させない項目です。先に決めて渡します。

3. 前のアプリの値を消す — Claude Code

複製先のリポジトリで Claude Code に 「テンプレートをリセットして」 と伝える。

node bin/reset-to-template.mjs          # 何が変わるかと残存を表示するだけ
node bin/reset-to-template.mjs --write  # 実際に書き換える

機械が戻すもの

機械が「報告するだけ」のもの

スクリプトは書き換え前の値を覚えておき、リポジトリ全体を走査して残っている箇所を file:line で報告します。設定ファイルは直せても、文章の中の値は機械に判断できないためです。残存があると終了コード 1 を返します。

実際に残るのは、たとえば次のような箇所です。すべて潰してから次に進んでください。

• README.md の設定表 … 複製元の Worker 名・D1 名・database_id が実値で残る
• README.md から、削除された docs/SETUP.md へのリンク
• 手順書や CLAUDE.md の中の、複製元リポジトリ名への言及

人が決めて Claude Code が書き換えるもの

• README.md … このアプリの説明に
• src/index.ts … 雛形の items アプリを、作るものに合わせて
• schema.sql … テーブル定義を作るものに合わせて

3手順4–6

4. D1 を作り、その場で schema.sql を実行する — ブラウザ

1. ダッシュボード → ストレージとデータベース → D1 SQLite データベース → 作成
   （データ ロケーションは「位置情報」＝自動配置のままでよい）
2. 同じ画面の「コンソール」タブに schema.sql の中身を貼って実行
3. 「概要」タブのテーブル数が 1 以上になっていることを確認 ← ここが確認の目印
4. 「概要」タブの Database ID をコピー

5. wrangler.jsonc に実値を入れる — Claude Code

手順2と手順4で決まった値を渡す。change-me は3か所。

grep -rn 'change-me' wrangler.jsonc   # 何も出ないこと
npm install                           # package-lock.json の name を同期
npm run check                         # 通ること

6. main にマージする — Claude Code

作業ブランチで開発 → npm run check が通ることを確認 → main へマージ。

4手順7–10

7. リポジトリを Workers Builds に接続する — ブラウザ

コンピュート → Workers & Pages からリポジトリをインポートする。

GitHub App の認可では Only select repositories を選び、対象リポジトリだけに絞る。

8. バインディングを目視で確認する — ブラウザ【必須】

Workers & Pages → 対象の Worker → 「バインディング」タブを開き、DB の値が手順4で作った新しい D1 の名前になっていることを確認する。

9. 読み書きを確認する — ブラウザ

https://<アプリ名>.<サブドメイン>.workers.dev を開く。

• 見出しと入力フォームが出る → GET / と D1 の読み取りが通っている
• 何か入力して追加 → 一覧に出る → 書き込みも通っている

10. main を保護する — ブラウザ

GitHub の Settings → Branches で main を保護し、build チェックの通過を必須にする。

5落とし穴（5件）

実際に踏んだものだけを挙げます。どれもログや画面を素直に読むと原因が分かりにくい失敗です。

落とし穴1 — 複製元の本番 D1 に接続された Worker が公開される【最も危険】

落とし穴2 — Node のバージョン（デプロイ段だけが落ちる）

npm warn EBADENGINE package: 'wrangler@4.120.0',
npm warn EBADENGINE required: { node: '>=22.0.0' },
npm warn EBADENGINE current: { node: 'v20.20.2' }

症状：「ビルド中」まで緑で、「デプロイ中」だけが数秒で赤くなる。

原因：wrangler 4.120.0 は Node 22 以上を要求する。.nvmrc が 20 だと Cloudflare のビルド環境が Node 20 を入れる。インストールは EBADENGINE 警告で通ってしまうので、ビルドが成功しているように見える。

対処：.nvmrc を 22、package.json の engines.node を >=22 に。このリポジトリでは修正済みなので、複製すれば踏みません。

落とし穴3 — assets.directory エラー

[ERROR] The directory specified by the "assets.directory" field in your ...
   /opt/buildhome/repo/dist

症状：クローン・インストール・ビルドは緑なのに、デプロイだけ失敗する。

原因：assets.directory は静的サイト版の wrangler.jsonc にしかない設定。main が古い構成のままの状態で接続すると、そちらを読んでしまう。

対処：main に正しい構成をマージする（手順6）。落とし穴1と同じ根っこです。

落とし穴4 — refusing to merge unrelated histories

Claude Code のクラウド実行環境で、ローカルの main が origin/main と無関係な履歴になっていることがある。

git checkout -B main origin/main
git merge --ff-only <作業ブランチ>

落とし穴5 — @cloudflare/workers-types のメジャー

^4 を指定すると wrangler 4系の peer 依存と衝突して npm ci が落ちます。^5 のままにしてください。

6ビルドが失敗したときの読み方

ビルドログは5段階（初期化 / クローン / インストール / ビルド / デプロイ）に分かれます。どこが赤いかで原因の範囲が決まります。

7手元の検証で分かることの限界

npm run check は tsc --noEmit と wrangler deploy --dry-run です。--dry-run は認証情報なしで動く代わりに、Cloudflare に問い合わせません。

8確かめていないこと

9最初に設計すること

アプリの中身を書き換えるときに、必ず一緒に決めてください。

• 認証を付けるか
• レート制限を入れるか
• 書き込み量に上限を設けるか

「とりあえず公開して後で塞ぐ」はしない、というのが CLAUDE.md の約束です。

あわせて CLAUDE.md の「セキュリティ上の約束」も読んでください。要点は3つです。

10時刻は UTC で保存される

雛形の schema.sql は created_at の既定値に datetime('now') を使っています。SQLite の datetime('now') は UTC を返すので、保存される時刻は UTC です。日本時間の表示と9時間ずれますが、これは仕様であってバグではありません。

11ファイルの役割

12テンプレートを更新するとき

S情報ソース

H更新履歴