Template解説シリーズ③：Cloudflare × Next.js App Routerで構築するフルスタックSaaSキット

# はじめに

https://github.com/Dhravya/cloudflare-saas-stack

このキットは、**Next.js(App Router)**・**Tailwind CSS**・**Shadcn UI**・**Radix UI**などを組み合わせてフロントエンドを構築し、サーバサイドは**Cloudflare Pages** + **D1** をベースにしたサーバレス環境を利用しています。

認証には**next-auth**を採用し、**DrizzleORM**でD1データベースと繋ぐ形です。
さらにWrangler CLIを使うことで、**KV**や**R2**の導入、**AI推論**、**Queue**などのリソースを柔軟に追加できます。

この記事では以下を中心に紹介します:

1. 全体像と主な技術
2. プロジェクト構成とセットアップ(キッティング)
3. 主要機能(認証、DB操作、UI、デプロイ)
4. 独自機能の追加手順(例: 多要素認証、R2活用、AI導入)
5. コードやWrangler CLI活用例

最終的には、**エッジ上で動くフルスタックSaaS**を素早く立ち上げ、柔軟に拡張していくためのスターターとして活用できます。

---

## 1. 全体像と使用技術

このプロジェクトで使われている主な技術要素とポイントは以下の通りです。

- **Next.js(App Router)**  
  ページやAPIルートをappディレクトリに集約し、サーバコンポーネントとクライアントコンポーネントを最適に組み合わせられます。  
- **Tailwind CSS + Shadcn UI + Radix UI**  
  シンプルで高速なデザイン。ShadcnのUIライブラリを導入済みで、多彩なコンポーネントが即利用可能。  
- **Cloudflare Pages + D1**  
  サーバレスな環境とSQLite互換のDB(D1)を組み合わせた軽量かつ高パフォーマンスなホスティング。  
- **DrizzleORM**  
  マイグレーション管理とORMを一体化し、ローカルでも本番でも同じコードでDBを操作。  
- **next-auth**  
  GoogleやGithubなどのOAuth認証が簡単に導入可能。独自のカスタム認証ロジックにも拡張性あり。  
- **Wrangler CLI**  
  KVやR2、QueueなどCloudflareのサービスを追加したいときにも便利。CLI操作で設定反映ができます。  

---

## 2. プロジェクト構成とセットアップ

まず、リポジトリは以下のような構成です(重要フォルダを抜粋):

```
.
├── drizzle.config.ts      // DrizzleORMの設定
├── drizzle               // DBマイグレーション管理フォルダ
├── scripts/setup.ts      // 初期セットアップ(Cloudflare連携など)
├── src
│   ├── app
│   │   ├── api          // Next.jsのAPIルート
│   │   └── ...          // ページコンポーネントなど
│   ├── server
│   │   ├── auth.ts      // next-authのエンドポイント
│   │   └── db
│   │       ├── index.ts // DB接続
│   │       └── schema.ts// テーブル定義(DrizzleORM)
│   └── lib              // テーマやユーティリティ等
...
```

### 初期キッティング手順

1. リポジトリをクローンし、bunをインストール
   ```
   npm i -g bun
   git clone https://github.com/Dhravya/cloudflare-saas-stack
   cd cloudflare-saas-stack
   ```
2. 依存関係を導入
   ```
   bun install
   ```
3. セットアップスクリプトを実行
   ```
   bun run setup
   ```
   - Wranglerでのログイン
   - D1データベース作成とwrangler.tomlへの書き込み
   - Google OAuthクライアントIDとシークレットの入力(.dev.varsに保存)
   - ドメインやPagesプロジェクトの作成
4. ローカル開発サーバ起動
   ```
   bun run dev
   ```
   - http://localhost:3000 で開発中のアプリを確認

### デプロイ手順

- 本番ビルドしてCloudflare Pagesへ
  ```
  bun pages:build
  bun run deploy
  ```
  これでアプリがCloudflare Pages上にホストされます。

---

## 3. 主要機能

### (A) 認証機能: next-auth + Google OAuth

- `src/server/auth.ts`でnext-authの設定を行い、GoogleOAuthを簡単に導入  
- 追加のプロバイダ(Github, Twitterなど)を入れる場合はproviders配列に追記  
- 多要素認証(MFA)への拡張例:  
  - 認証時にD1テーブルで登録済みかをチェックし、OTPやWebAuthnなどを併用  

### (B) DB操作: DrizzleORM + D1

- `drizzle.config.ts` でローカルと本番を切り替え  
- ローカルではSQLiteファイルを操作、本番はD1 HTTP Driverで通信  
- `bun run db:generate` でマイグレーションファイル生成 → `bun run db:migrate:dev` で適用  
- schema.tsにテーブル定義を追加し、TypeScriptベースで型安全なクエリが可能

### (C) UIとテーマ切り替え

- Tailwind CSS + Shadcn UI + Radix UI  
- ライト/ダークモードの切り替えは`src/lib/theme/theme-button.tsx` と `use-theme.ts` で実装  
- Next.js App RouterのServer Components環境でも、ちらつきなくテーマを適用する仕組み

### (D) Cloudflare Pagesへのデプロイ

- `wrangler.toml`でCloudflare Pagesの設定を行い、Wrangler CLIでビルド&アップロード  
- Pagesコンソール上で継続的デプロイを設定可能

---

## 4. 独自機能の追加例

### 多要素認証(MFA)の導入

- WebAuthn(指紋認証やFIDO2キー)を使う場合  
  - authenticatorsテーブルをDrizzleORMで拡張  
  - next-authカスタムコールバックでMFAフラグをチェック  
- TOTP(One Time Password)を導入したい場合  
  - テーブルにシークレットキーを保持し、ログイン時に検証する仕組みを追加

### R2でファイルアップロード

- wrangler.tomlにR2バケットをbinding  
- APIルートでR2にファイルPUT → 画像やドキュメントのホスティングが可能  
- `scripts/setup.ts`内の`createBucketR2()`を参考に、バケット作成やCORS設定を追加

### AI推論の組み込み

- Wrangler CLIを使ってAI primitiveをwrangler.tomlに設定(まだβ機能の可能性あり)  
- APIルートにリクエストを送り、LLMや画像解析などのエンドポイントを呼び出す処理を実装  
- D1と組み合わせてマルチモーダルデータ(画像+テキスト)の管理を行うことも可能

### KVを使ったセッションやキャッシュ

- 大容量データやセッションキャッシュ、設定値保存などをKVで実装  
- workers-devモードでローカルテスト → 本番反映

---

## 5. コードやWrangler CLI活用例

### 主要スクリプト一覧(抜粋)

```jsonc
"scripts": {
  "dev": "next dev",
  "db:generate": "drizzle-kit generate",
  "db:migrate:dev": "drizzle-kit migrate",
  "db:migrate:prod": "NODE_ENV=production drizzle-kit migrate",
  "pages:build": "bunx @cloudflare/next-on-pages",
  "deploy": "bun pages:build && wrangler pages deploy",
  // ... ほか多数
}
```

- db:generate → db:migrate:dev の流れでローカルのD1(実体はSQLiteファイル)を更新  
- db:migrate:prod で本番のD1に即反映(REST APIを経由)

### Wrangler CLIによるリソース追加

- 新しいD1 DBを作りたい場合  
  ```
  wrangler d1 create 新しいDB名
  ```
- R2バケットを追加  
  ```
  wrangler r2 bucket create バケット名
  ```
- KVを追加  
  ```
  wrangler kv:namespace create "MY_KV"
  ```

wrangler.tomlに追記するbinding名と合わせて設定するのがポイントです。

---

## 全体イメージ

以下の簡単なmermaid図に、ブラウザからCloudflare Pages上で動くNext.jsアプリ、D1、さらにWranglerデプロイまでの流れを示しています。

```mermaid
flowchart TB
    A["ユーザー"] --> B["Next.jsアプリ"]
    B["Next.jsアプリ"] --> C["Cloudflare D1"]
    B["Next.jsアプリ"] --> D["Cloudflare Pages"]
    D["Cloudflare Pages"] --> E["wranglerデプロイ"]
```

---

## まとめ

このフルスタックSaaSキットは、**認証・DB操作・UIコンポーネント・エッジホスティング**といった基本要素をすぐに利用でき、**サーバレスでのスケーラビリティ**も十分備えています

。**Google OAuth**などの認証連携をはじめ、**Shadcn UI**による拡張性の高いUI、**DrizzleORM**による型安全なDB操作までが標準搭載。

さらにWrangler CLIで**R2**や**KV**などのリソースを追加すれば、**画像アップロードやキャッシュ**管理、あるいは**AI推論**まで実現できます。

- 最短数分で起動 → クラウド上の本番環境へデプロイが可能
- Next.jsの最新構造(App Router)で、サーバコンポーネントをフル活用
- Cloudflare D1による安価かつ軽快なDB運用(小規模から大規模まで拡張)

本スターターをもとに、自分好みのサービスを作り上げてみてください。サーバーレス、エッジ環境、フロントエンドまでまるっと一貫して構築できるので、開発体験も非常に快適です。

---
### 会社紹介

**株式会社 Mosaica**  
最先端テクノロジーで社会課題を解決し、持続可能な未来を創造する IT カンパニー。
AI ソリューション、クラウド統合、DX 推進、経営コンサルティングなど包括的なサービスでビジネス変革を支援しています。  

詳しくは [公式サイト](https://mosaica.co.jp/) までお気軽にご相談ください。
公式サイト： https://mosaica.co.jp/