Hono + React SPA Project Template

モダンなフルスタックWebアプリケーション開発のための包括的なプロジェクトテンプレートです。Hono（バックエンド）、React（フロントエンド）、Bun、Tailwind CSS 4、shadcn/uiを組み合わせ、開発効率と保守性を両立させた環境を提供します。

📖 目次

プロジェクト概要
技術スタック
セットアップ
テンプレート利用時の初期設定
利用可能なコマンド
アーキテクチャ
開発ワークフロー
CI/CD
トラブルシューティング
関連リソース

🎯 プロジェクト概要

Hono（バックエンド）+ React（フロントエンド）+ Bun + Vite + Tailwind CSS 4 + shadcn/uiを使用したフルスタックWebアプリケーションテンプレート。

主な特徴:

React SPAとHono APIの明確な分離
型安全性とコード品質管理が標準装備
Cloudflare Pages/Workersへのデプロイ対応
Git Hooks、テスト、CI/CDを含む完全な開発環境

🚀 技術スタック

バックエンド

Hono - 軽量で高速なWebフレームワーク
Bun - JavaScriptランタイム

フロントエンド

React 19 - UIライブラリ
Vite - 高速ビルドツール・開発サーバー
Tailwind CSS v4 - CSSフレームワーク
shadcn/ui - 再利用可能なUIコンポーネント

開発ツール

TypeScript - 静的型付け
Biome - リント・フォーマットツール
Playwright - E2Eテスト
Storybook - UIコンポーネント開発環境
Lefthook - Git Hooks管理

デプロイ

Cloudflare Pages/Workers - エッジコンピューティング

📦 セットアップ

前提条件

Bun v1.1.44以上

# Bunのインストール（未インストールの場合）
curl -fsSL https://bun.sh/install | bash

インストール

# 依存関係のインストール
bun install

# 開発サーバーの起動
bun run dev

サーバーは http://localhost:5173 で起動します。

初期セットアップの確認

# コード品質チェック
bun run lint

# テスト実行
bun run test

# ビルド確認
bun run build

⚙️ テンプレート利用時の初期設定

このテンプレートを使って新規プロジェクトを作成する際は、以下の設定を必ず更新してください。

1. プロジェクト名の変更

package.json

{
  "name": "init-project",  // ← あなたのプロジェクト名に変更
  ...
}

wrangler設定ファイル

このプロジェクトでは、React SPAとHono APIを分離してデプロイするため、2つの設定ファイルがあります:

apps/frontend/wrangler.jsonc（Cloudflare Pages用 - React SPA）:

{
  "name": "hono-react-pages",  // ← Pagesプロジェクト名に変更
  "pages_build_output_dir": "dist"
}

apps/backend/wrangler.jsonc（Cloudflare Workers用 - Hono API）:

{
  "name": "hono-api-worker",  // ← Worker名に変更
  "main": "src/index.ts",
  "compatibility_date": "2024-09-23",
  "compatibility_flags": ["nodejs_compat"]
}

2. .gitignoreファイルのセットアップ

# .gitignore.example をコピー
cp .gitignore.example .gitignore

3. 環境変数の設定

バックエンド開発用の環境変数を設定します（wrangler dev が自動的に読み込みます）:

# apps/backend/.dev.vars を編集
# すでにテンプレート実装例の環境変数が含まれています

必須の環境変数 (使用する場合):

SESSION_SECRET - セッション暗号化キー

# 生成方法
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

注意: apps/backend/.dev.varsファイルは.gitignoreに含まれており、Gitにコミットされません。

4. GitHub Secrets の設定（CI/CD用）

自動デプロイを有効にする場合は、GitHubリポジトリに以下のシークレットを設定してください:

リポジトリ設定: Settings → Secrets and variables → Actions → New repository secret

シークレット名	説明	取得方法
`CLOUDFLARE_API_TOKEN`	Cloudflare APIトークン	Cloudflare Dashboard → `Create Token` → "Edit Cloudflare Workers" テンプレート
`CLOUDFLARE_ACCOUNT_ID`	CloudflareアカウントID	Cloudflare Dashboard → Workers & Pages → URLから確認
`CLOUDFLARE_PAGES_PROJECT_NAME`	Cloudflare Pagesプロジェクト名	`apps/frontend/wrangler.jsonc`の`name`と同じ値
`CLOUDFLARE_WORKERS_PROJECT_NAME`	Cloudflare Workersプロジェクト名	`apps/backend/wrangler.jsonc`の`name`と同じ値

5. Cloudflareへのデプロイ

# Cloudflareにログイン（初回のみ）
bunx wrangler login

# React SPAをCloudflare Pagesにデプロイ
bun run deploy:pages

# Hono APIをCloudflare Workersにデプロイ
bun run deploy:workers

# 両方をまとめてデプロイ
bun run deploy

チェックリスト

新規プロジェクト作成時に以下を確認してください:

🛠️ 利用可能なコマンド

開発コマンド

# Vite開発サーバー起動（React SPA、ホットリロード有効）
bun run dev

# Cloudflare Workers ローカル環境で Hono サーバー起動（wrangler dev）
bun run dev:backend

# プロダクションビルド
bun run build

# ビルド結果のプレビュー
bun run preview

コード品質

# Biomeでコードをチェック
bun run lint

# Biomeで自動修正（安全な修正+unsafe修正）
bun run lint:fix

# Biomeでコードをフォーマット
bun run format

テスト

# E2Eテストを実行（ヘッドレスモード）
bun run test

# Playwright UIモードで実行（インタラクティブ）
bun run test:ui

# ブラウザ表示ありでテスト実行（デバッグ用）
bun run test:headed

Storybook

# Storybookを起動（http://localhost:6006）
bun run storybook

# Storybookを静的ビルド
bun run build-storybook

shadcn/uiコンポーネント

# コンポーネントを追加
bunx shadcn add button
bunx shadcn add card
bunx shadcn add form

# 利用可能なコンポーネント一覧を確認
bunx shadcn add

Cloudflareデプロイ

# React SPAをCloudflare Pagesにデプロイ
bun run deploy:pages

# Hono APIをCloudflare Workersにデプロイ
bun run deploy:workers

# 両方をまとめてデプロイ
bun run deploy

🏗️ アーキテクチャ

ディレクトリ構造（モノレポ構成）

.
├── apps/
│   ├── frontend/              # React SPA
│   │   ├── src/
│   │   │   ├── client/       # App entry point
│   │   │   ├── components/   # UI components
│   │   │   │   ├── ui/       # shadcn/ui components
│   │   │   │   └── app/      # App-specific components
│   │   │   ├── lib/          # Frontend utilities
│   │   │   └── styles/       # Global styles
│   │   ├── e2e/              # Playwright tests
│   │   ├── public/           # Static assets
│   │   ├── index.html
│   │   ├── package.json
│   │   ├── vite.config.ts
│   │   └── tsconfig.json
│   │
│   └── backend/               # Hono API
│       ├── src/
│       │   └── index.ts      # Server entry (AppType export)
│       ├── package.json
│       ├── tsconfig.json
│       └── wrangler.jsonc
│
├── packages/
│   └── types/                 # 共有型定義
│       ├── src/
│       │   ├── index.ts      # Main export
│       │   ├── env.ts        # Environment types
│       │   └── api.ts        # API types
│       ├── package.json
│       └── tsconfig.json
│
├── package.json               # Root (workspaces設定)
├── tsconfig.base.json         # Base TypeScript config
└── tsconfig.json              # TypeScript Project References

アーキテクチャ概要

フロントエンド開発（bun run dev）:

Viteがapps/frontend/index.htmlを配信
apps/frontend/src/client/index.tsxをエントリーポイントとしてReact SPAをレンダリング
HMR（Hot Module Replacement）が有効で高速な開発体験
ポート: http://localhost:5173

バックエンド開発（bun run dev:backend）:

wrangler dev で Cloudflare Workers ローカル環境を起動
apps/backend/src/index.ts をエントリーポイント
ポート: http://localhost:8787（wrangler dev のデフォルト）

本番ビルド（bun run build）:

Viteがapps/frontend/dist/にバンドル済みファイルを出力
Cloudflare Pagesにデプロイして静的ファイルとして配信

Hono APIサーバー（apps/backend/src/index.ts）:

開発時は wrangler dev でローカル実行
APIエンドポイントの追加が可能
Cloudflare Workersとして動作（プロダクション時）

レンダリングフロー

開発時: Vite → apps/frontend/index.html → React SPAレンダリング
本番時: Cloudflare Pages → apps/frontend/dist/index.html（ビルド済み）

ルーティング

現在はシンプルな単一ページSPA構成
クライアントサイドルーティングが必要な場合は、React Routerなどを追加可能
Honoでサーバーサイドのルート定義が可能（apps/backend/src/index.ts）

スタイリング

Tailwind CSS 4を使用
cn()ヘルパー関数（src/lib/utils.ts）でクラス名の結合
shadcn/uiコンポーネントはsrc/components/ui/に配置

TypeScript設定

厳格モード: 有効（strict: true）
モジュール解決: Bundlerモード（moduleResolution: "bundler"）
JSX: react-jsx
パスエイリアス: @/ → src/
Cloudflare Workers型: @cloudflare/workers-typesを使用

環境変数の型定義（`src/types/env.ts`）

Cloudflare Workers環境変数とバインディングの型を定義:

export interface Env {
  // 環境変数（必要に応じて追加）
  SESSION_SECRET?: string;
  API_KEY?: string;

  // Cloudflareバインディング（使用する場合はコメント解除）
  // MY_KV?: KVNamespace;
  // MY_BUCKET?: R2Bucket;
  // DB?: D1Database;
}

Honoでの使用例:

import { Hono } from 'hono'
import type { Env } from '../types/env'

const app = new Hono<{ Bindings: Env }>()

app.get('/api/data', (c) => {
  const secret = c.env.SESSION_SECRET  // 型安全
  // KV、R2、D1などのバインディングも型安全に利用可能
  return c.json({ message: 'Success' })
})

コード品質管理（Biome）

このプロジェクトではBiomeをlinter・formatterとして使用しています。

重要なルール

button要素のtype属性: 必須（useButtonType: error）
配列indexをkeyに使用: 禁止（noArrayIndexKey: error）
any型の使用: 警告（テストファイルは例外）

フォーマット

セミコロン: 常に付与
引用符: ダブルクォート
末尾カンマ: 常に付与
行幅: 100文字

既知の制限

CSSファイル（src/styles/globals.css）はTailwind CSSのディレクティブ（@tailwind、@apply）を含むため、Biomeでパースエラーが表示されますが、実際の動作には影響ありません。

👨‍💻 開発ワークフロー

Git Hooks（Lefthook）

以下のGit Hooksが自動実行されます:

pre-commit: Biomeでリント・フォーマット（自動修正）
pre-push: リントチェック、テスト実行、ビルド確認

詳細はlefthook.ymlを参照してください。

フックのスキップ（緊急時のみ）:

LEFTHOOK=0 git commit -m "fix: urgent hotfix"

Hono APIの追加方法

src/server/index.tsでAPIエンドポイントを追加:

// JSONレスポンス
app.get('/api/hello', (c) => {
  return c.json({ message: 'Hello from Hono!' })
})

// 環境変数の利用
app.get('/api/config', (c) => {
  const secret = c.env.SESSION_SECRET
  return c.json({ hasSecret: !!secret })
})

// ミドルウェアの使用例
import { cors } from 'hono/cors'
import { logger } from 'hono/logger'

app.use('*', logger())
app.use('/api/*', cors())

🧪 テスト & 開発

E2Eテスト（Playwright）

テストファイルはe2e/配下に配置します。実行コマンドは「利用可能なコマンド」セクションを参照してください。

Storybook

UIコンポーネントの開発・ドキュメント化に使用します。

bun run storybook  # http://localhost:6006 で起動

🚢 CI/CD

GitHub Actions

CI: .github/workflows/ci.yml - リント、ビルド、テストを自動実行
CD: .github/workflows/deploy.yml - mainブランチへのマージ時にCloudflare Pagesへ自動デプロイ

必要なGitHub Secrets:

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID
CLOUDFLARE_PROJECT_NAME

詳細は「テンプレート利用時の初期設定」セクションを参照してください。

🐛 トラブルシューティング

ポートが既に使用されている

# プロセスを確認
lsof -i :5173

# プロセスを終了
kill -9 <PID>

キャッシュのクリア

# Bunキャッシュをクリア
bun pm cache rm

# node_modulesを削除して再インストール
rm -rf node_modules bun.lockb
bun install

Playwrightブラウザのインストール

bunx playwright install

Git Hooksが動作しない

# Lefthookを再インストール
bunx lefthook install

# フックの実行を確認
bunx lefthook run pre-commit

📚 関連リソース

📝 ライセンス

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.claude		.claude
.gemini		.gemini
.github		.github
.vscode		.vscode
__docs__		__docs__
apps		apps
packages/types		packages/types
.biomeignore		.biomeignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
GEMINI.md		GEMINI.md
README.md		README.md
biome.json		biome.json
bun.lock		bun.lock
lefthook.yml		lefthook.yml
package.json		package.json
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json

naoto24kawa/hono-react-template

Folders and files

Latest commit

History

Repository files navigation

Hono + React SPA Project Template

📖 目次

🎯 プロジェクト概要

🚀 技術スタック

バックエンド

フロントエンド

開発ツール

デプロイ

📦 セットアップ

前提条件

インストール

初期セットアップの確認

⚙️ テンプレート利用時の初期設定

1. プロジェクト名の変更

package.json

wrangler設定ファイル

2. .gitignoreファイルのセットアップ

3. 環境変数の設定

4. GitHub Secrets の設定（CI/CD用）

5. Cloudflareへのデプロイ

チェックリスト

🛠️ 利用可能なコマンド

開発コマンド

コード品質

テスト

Storybook

shadcn/uiコンポーネント

Cloudflareデプロイ

🏗️ アーキテクチャ

ディレクトリ構造（モノレポ構成）

アーキテクチャ概要

レンダリングフロー

ルーティング

スタイリング

TypeScript設定

環境変数の型定義（src/types/env.ts）

コード品質管理（Biome）

重要なルール

フォーマット

既知の制限

👨‍💻 開発ワークフロー

Git Hooks（Lefthook）

Hono APIの追加方法

🧪 テスト & 開発

E2Eテスト（Playwright）

Storybook

🚢 CI/CD

GitHub Actions

🐛 トラブルシューティング

ポートが既に使用されている

キャッシュのクリア

Playwrightブラウザのインストール

Git Hooksが動作しない

📚 関連リソース

📝 ライセンス

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

環境変数の型定義（`src/types/env.ts`）

Packages