Webアプリの環境構築

8m 47s

概要

以下の技術スタックで環境構築していきます。

Next.js / フレームワーク
shadcn/ui / UIキット
Turso / データベース
Drizzle / ORM
Better Auth / 認証ライブラリ
Turborepo / モノリポ
Sentry / 監視ツール
Vitest / テストライブラリ
Playwright / E2Eテストライブラリ
AGENTS.md / エージェントドキュメント

1. プロジェクトの初期化

1.1 リポジトリのクローンとセットアップ

1.2 ワークスペース構成の確認

このプロジェクトはTurborepoを使用したモノレポ構成です。このドキュメント通りに進めると、最終的に以下のようになります。

2. データベースパッケージ（db）の作成

2.1 データベースパッケージの初期化

以下の内容で packages/db/package.json を作成します：

2.2 必要な依存関係のインストール

2.3 Tursoのセットアップ

2.4 データベースパッケージの環境変数設定

packages/db/.envファイルを作成：

2.5 Drizzle設定ファイルの作成

packages/db/drizzle.config.tsを作成：

2.6 データベース接続の設定

packages/db/index.tsを作成：

2.7 型とZodスキーマの生成

Drizzleスキーマから型とZodスキーマを作成し、各アプリケーションで使用できるようにします：

3. 認証パッケージ（auth）の作成

3.1 認証パッケージの初期化

以下の内容で packages/auth/package.json を作成します：

3.2 必要な依存関係のインストール

3.3 認証パッケージの環境変数設定

packages/auth/.envファイルを作成：

3.4 認証スキーマの作成

コマンドを実行して認証スキーマを作成します：

packages/db/schemas/auth.tsが作成されたら、マイグレーションを実行します：

3.5 データベース接続の更新

packages/db/index.tsを更新して認証スキーマを含めます：

3.6 マイグレーションの実行

3.7 Better Authの設定

packages/auth/index.ts で認証設定を作成：

4. Next.jsアプリケーションの設定

4.1 アプリケーションの起動

5. 監視・ログ設定（Sentry）

5.1 Sentryの設定

公式ドキュメントのコマンドでSentryを設定してください。

6. アプリケーション（web）の環境変数設定

6.1 Webアプリケーションの環境変数設定

apps/web/.env.localファイルを作成：

# データベース設定
TURSO_DATABASE_URL=libsql://your-database-url

# 認証設定
BETTER_AUTH_SECRET=your-secret-key-here
BETTER_AUTH_URL=http://localhost:3000

BETTER_AUTH_SECRET は以下のコマンドで生成できます。

pnpx @better-auth/cli@latest secret

6.2 本番環境の環境変数設定

本番環境では以下の環境変数を設定してください：

TURSO_DATABASE_URL
TURSO_AUTH_TOKEN
BETTER_AUTH_SECRET
SENTRY_AUTH_TOKEN

7. 開発ワークフロー

7.1 基本的なコマンド

# 開発サーバーの起動
pnpm dev

# ビルド
pnpm build

# リンター
pnpm lint

# 型チェック
pnpm typecheck

# フォーマット
pnpm format

7.2 TurborepoとStudioタスクの設定

このプロジェクトでは、Turborepoを使用してモノレポ全体のタスクを効率的に管理しています。Drizzle Studioを起動するためのタスクや、依存する環境変数を設定します。

turbo.jsonの設定

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": [".next/**", "!.next/cache/**"],
      "env": ["TURSO_DATABASE_URL", "TURSO_AUTH_TOKEN", "BETTER_AUTH_SECRET", "SENTRY_AUTH_TOKEN"]
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "typecheck": {
      "dependsOn": ["^typecheck"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "studio": { 
      "cache": false, 
      "persistent": true
    } 
  }
}

次に、ルートのpackage.jsonに以下を追加します。

{
  "scripts": {
    "dev": "turbo dev studio"
  }
}

ルートでpnpm devまたはturbo dev studioを実行すると：

turbo dev: 全てのパッケージでdevタスクが並行実行される
turbo studio: 全てのパッケージでstudioタスクが並行実行される

具体的には：

webアプリケーション: Next.js開発サーバーが起動（通常localhost:3000）
dbパッケージ: Turso ローカルデータベースが起動
dbパッケージ: Drizzle Studioが起動

この構成により、開発者は1つのコマンドでWebアプリケーションとデータベース管理ツールの両方を同時に起動でき、効率的な開発環境を構築できます。

Drizzle Studioは、データベーススキーマの可視化、データの確認・編集、SQLクエリの実行などができるWebベースの管理ツールです。

それぞれターミナルに表示されるURLをブラウザで開くことでアクセスできます。

7.3 データベース操作

# マイグレーション生成
cd packages/db
pnpm generate

# マイグレーション実行
pnpm migrate

# Drizzle Studio起動
pnpm studio

7.4 実装フローに従った開発手順

たとえばペットに関する機能を開発する場合、以下の順序で開発を進めてください：

Drizzleスキーマの作成 (/packages/db/schemas/)

# スキーマファイルを編集（例：認証スキーマ）
touch packages/db/schemas/pet.ts

マイグレーションの実行 (/packages/db)
cd packages/db pnpm gm # generate + migrate
Loading...

型の作成

import { InferSelectModel, InferInsertModel } from "drizzle-orm";
import { pets } from "../schemas/pet";

export type Pet = InferSelectModel<typeof pets>;
export type NewPet = InferInsertModel<typeof pets>;

Zodスキーマの作成

import { z } from "zod";
import { createInsertSchema, createSelectSchema } from "drizzle-zod";
import { pets } from "../schemas/pet";

export const insertPetSchema = createInsertSchema(pets);
export const selectPetSchema = createSelectSchema(pets);

各アプリケーションで使用

// アプリケーションで型とZodスキーマを使用
import { User, NewUser } from "@workspace/db";
import { insertUserSchema, selectUserSchema } from "@workspace/db";
import { auth } from "@workspace/auth";

7.5 環境変数を追加する場合

いずれかのアプリ（/apps/web など）に環境変数を追加する場合、必ず turbo.json に定義を追加してください。

{
  "tasks": {
    "dev": {
      "env": ["TURSO_DATABASE_URL", "TURSO_AUTH_TOKEN", "BETTER_AUTH_SECRET", "CRON_SECRET", "AI_GATEWAY_API_KEY", "SENTRY_AUTH_TOKEN"] 
    }
  }
}

8. トラブルシューティング

8.1 よくある問題

パッケージのバージョンを揃える方法

以下のコマンドで、すべてのアプリ（パッケージ）でバージョンを揃えることができます。バージョンの組み合わせは繊細なので、Next.js や React、TypeScript など基盤となる技術を段階的に揃えていくことをお勧めします。（全部ライブラリをまとめてアップデート&揃える、とするとエラーが発生する可能性があります。）
# nextバージョンを揃える pnpm up next@latest -r
Loading...

9. 最終Tips

9.1 .env.exampleファイルの作成

各アプリ、パッケージに.env.exampleファイルを作成して、必要な環境変数のテンプレートを提供することをお勧めします：

# データベース設定
TURSO_DATABASE_URL=

# 認証設定
BETTER_AUTH_SECRET=

# Sentry設定
SENTRY_AUTH_TOKEN=

# データベース設定
TURSO_DATABASE_URL=

# 認証設定
BETTER_AUTH_SECRET=

# データベース設定
TURSO_DATABASE_URL=

10. 追加リソース

このガイドに従って環境を構築することで、このリポジトリの構成を再現できます。問題が発生した場合は、各ツールの公式ドキュメントを参照してください。

Discord で質問する

何か気になったこと、分からないことがあれば気軽に質問してください！

Discordで質問する

Command Palette