vercel

SaaS 向け Vercel

核心となる洞察： 3 つの軸を最適化します。運用の制御（CLI 優先）、コストの制御（意図しないビルドを回避）、正確性（SSR を損なわないキャッシュと認証）。

目次

• 正確なプロンプト
• アーキテクチャの決定
• クイックスタート
• ビルドクレジットの消費を止める
• 環境変数
• ワークフローのチェックリスト
• 重要な落とし穴
• 主要なコマンド
• AGENTS.md の説明文
• 参考資料

---

正確なプロンプト

Set up [Next.js app / SaaS] on Vercel with:
1. Cloudflare DNS at: [domain.com]
2. Supabase project: [project-ref]
3. Build control: [manual deploys only / CI-triggered / default]
4. Cost offload: [R2 for assets / Cloudflare Pages for marketing / none]

Follow vercel-for-saas skill patterns.

アーキテクチャの決定

Where should traffic go?
│
├─ Authenticated app (SSR/RSC) ─────► Vercel (app.example.com)
│  • DNS-only in Cloudflare (no proxy)
│  • Manual deploys, prebuilt artifacts
│
├─ Marketing/docs (static) ─────────► Cloudflare Pages (www.example.com)
│  • Direct Upload for deploy control
│  • Aggressive caching, cheap bandwidth
│
└─ Uploads/assets (storage) ────────► Cloudflare R2 (assets.example.com)
   • Worker-signed URLs
   • No egress fees

この分割を行う理由： Vercel はリバースプロキシを推奨していません。ホスト名を分割すれば、Vercel のエッジを損なわずに Cloudflare のメリットを活用できます。

クイックスタート：手動デプロイ

# 1. Pull settings + env (creates .vercel/)
vercel pull --yes --token $VERCEL_TOKEN

# 2. Build locally (skips Vercel build minutes)
vercel build --prod

# 3. Upload prebuilt artifact
vercel deploy --prebuilt --prod --token $VERCEL_TOKEN

これは、コスト制御において最も効果の大きいパターンです。

ビルドクレジットの消費を止める

方法	手順	効果
自動デプロイを無効にする	vercel.json："git": { "deploymentEnabled": false }	★★★★★
ビルド済みワークフロー	Vercel の外部でビルドし、--prebuilt でアップロードする	★★★★☆
ビルドステップの無視	終了コード 0 = スキップ、終了コード 1 = ビルド（逆だと勘違いされがちです！）	★★☆☆☆
デプロイフック	HTTP でトリガーするデプロイのみ	★★★☆☆

設定をコードで管理（推奨）：

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "git": { "deploymentEnabled": false }
}

詳細：BUILD-CONTROL.md

環境変数

# List
vercel env ls

# Add secret (interactive)
vercel env add SECRET_NAME production

# Pull to local .env
vercel env pull .env.local

# Bulk sync via REST (for agents)
curl -X POST "https://api.vercel.com/v10/projects/$PROJECT/env?upsert=true" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -d '{"key":"VAR","value":"val","target":["production"]}'

OIDC + Vault については、TOKEN-AND-KEY-MANAGEMENT.md を参照してください。

ドメインの設定

# Add domain to Vercel
vercel domains add example.com --token $VERCEL_TOKEN

# Then in Cloudflare DNS (DNS-only, not proxied):
# A record → Vercel IP  OR
# CNAME → cname.vercel-dns.com

ワークフローのチェックリスト

フェーズ 1：初期設定

• CLI をインストールする：vercel、supabase、wrangler、jq
• トークンを設定する：VERCEL_TOKEN、CLOUDFLARE_API_TOKEN
• プロジェクトをリンクする：vercel link --yes
• 環境変数を取得する：vercel pull --yes

フェーズ 2：コストの最適化

• vercel.json に "git": { "deploymentEnabled": false } を追加する
• CI にビルド済みデプロイのワークフローを設定する
• マーケティングサイトを Cloudflare Pages に移行する — CLOUDFLARE-OFFLOAD.md
• アセットを R2 に移行する — CLOUDFLARE-OFFLOAD.md

フェーズ 3：シークレットと認証

• vercel env add または REST API を使ってシークレットを保存する
• クラウド認証情報の OIDC を設定する — TOKEN-AND-KEY-MANAGEMENT.md
• Supabase 認証の統合を設定する

フェーズ 4：データベース

• マイグレーションを作成する：supabase migration new
• 適用する：supabase migration up（ローカル）／supabase db push（CI）
• 型を生成する：supabase gen types typescript

2 ボタンでデプロイ（エージェント向け）

# Marketing (Cloudflare Pages)
pnpm -C apps/marketing build
npx wrangler pages deploy apps/marketing/dist --branch=main

# App (Vercel prebuilt)
vercel pull --yes && vercel build --prod && vercel deploy --prebuilt --prod

重要な落とし穴

落とし穴	対処法
ビルドステップの無視の終了コードが直感と逆	0 = スキップ、1 = ビルド（直感に反します）
無視されたビルドもクォータにカウントされる	代わりに git.deploymentEnabled: false を使う
Cloudflare プロキシと Vercel の併用で問題が発生する	Vercel のドメインでは DNS のみを使用する
.vercel/ フォルダーをコミットしてしまう	.gitignore に追加する
設定ファイルにシークレットを記述する	vercel env または wrangler secret put を使う

一覧：FOOTGUNS.md

主要なコマンド

作業	コマンド
プレビューをデプロイする	vercel
本番環境にデプロイする	vercel --prod
設定を取得する	vercel pull
ローカルでビルドする	vercel build
ビルド済みの成果物をデプロイする	vercel deploy --prebuilt
環境変数を一覧表示する	vercel env ls
環境変数を追加する	vercel env add NAME target
環境変数をファイルに取得する	vercel env pull

CLI の完全なリファレンス：CLI-COMMANDS.md

---

AGENTS.md の説明文

以下をプロジェクトの AGENTS.md にコピーしてください。

### Vercel

Vercel CLI is installed and authenticated.

Project: `<PROJECT_NAME>`

Common commands:

\`\`\`bash
vercel pull --yes         # Fetch settings + env
vercel build --prod       # Build locally (saves build minutes)
vercel deploy --prebuilt --prod  # Deploy prebuilt artifact
vercel env ls             # List env vars
vercel env add SECRET production  # Add secret
\`\`\`

**Cost tip:** Use prebuilt workflow to avoid burning build credits.

リファレンス

トピック	リファレンス
アーキテクチャとコストモデル	ARCHITECTURE.md
ビルドコストの浪費を防ぐ	BUILD-CONTROL.md
API ベースのビルド制御	API-BUILD-CONTROL.md
CLI コマンド一覧	CLI-COMMANDS.md
シークレット、環境変数、OIDC、Vault	TOKEN-AND-KEY-MANAGEMENT.md
R2 + Pages によるコスト削減	CLOUDFLARE-OFFLOAD.md
自動化の完全な設計図	AUTOMATION-BLUEPRINT.md
よくある間違い	FOOTGUNS.md

トークンの設定（非対話型認証）

# Vercel: https://vercel.com/account/tokens
export VERCEL_TOKEN=xxx

# Cloudflare: https://dash.cloudflare.com/profile/api-tokens
export CLOUDFLARE_API_TOKEN=xxx

# Supabase: project settings → API
export SUPABASE_ACCESS_TOKEN=xxx

すべての CLI がこれらを自動的に読み取ります。対話型ログインは不要です。