Webアプリの環境構築

8分 47秒

概要

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

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

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

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

pnpx shadcn@latest init -t next-monorepo -y

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

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

my-app/
├── apps/
│   └── web/                 # Next.jsアプリケーション
├── packages/
│   ├── auth/               # Better Auth認証パッケージ
│   ├── db/                 # Drizzle ORM + Tursoデータベース
│   ├── eslint-config/      # 共有ESLint設定
│   ├── lib/                # 共有ライブラリ
│   ├── typescript-config/  # 共有TypeScript設定
│   └── ui/                 # shadcn/uiコンポーネント
└── turbo.json              # Turborepo設定

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

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

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

{
  "name": "@workspace/db",
  "version": "0.0.0",
  "type": "module",
  "private": true,
  "scripts": {
    "dev": "turso dev -f local/local.db",
    "generate": "pnpm drizzle-kit generate",
    "migrate": "pnpm drizzle-kit migrate",
    "gm": "pnpm drizzle-kit generate && pnpm drizzle-kit migrate",
    "studio": "pnpm drizzle-kit studio",
    "generate:types": "drizzle-kit introspect --out=./types",
    "generate:zod": "drizzle-zod --out=./zod --schema=./schemas"
  },
  "dependencies": {
    "@libsql/client": "^0.15.15",
    "dotenv": "^17.2.3",
    "drizzle-orm": "^0.44.6",
    "drizzle-zod": "^0.8.3",
    "nanoid": "^5.1.6",
    "zod": "^4.1.12"
  },
  "devDependencies": {
    "@workspace/typescript-config": "workspace:*",
    "drizzle-kit": "^0.31.5"
  }
}

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

pnpm install

2.3 Tursoのセットアップ

# Turso CLIのインストール
brew install tursodatabase/tap/turso

# ローカルデータベースの作成
touch packages/db/local/local.db

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

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

TURSO_DATABASE_URL=http://127.0.0.1:8080
TURSO_AUTH_TOKEN=local

2.5 Drizzle設定ファイルの作成

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

import 'dotenv/config'
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  schema: "./schemas/*.ts",
  out: "./migrations",
  dialect: "turso",
  dbCredentials: {
    url: process.env.TURSO_DATABASE_URL!,
    authToken: process.env.TURSO_AUTH_TOKEN || "dev",
  },
});

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

packages/db/index.tsを作成：

import "dotenv/config";
import { drizzle } from "drizzle-orm/libsql/web";

export const db = drizzle({
  connection: {
    url: process.env.TURSO_DATABASE_URL!,
    authToken: process.env.TURSO_AUTH_TOKEN!,
  },
  schema: {
    // 後で追加
  },
});

2.7 型とZodスキーマの生成

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

import { InferSelectModel, InferInsertModel } from "drizzle-orm";
import { users, sessions } from "../schemas/auth";

export type User = InferSelectModel<typeof users>;
export type NewUser = InferInsertModel<typeof users>;
export type Session = InferSelectModel<typeof sessions>;
export type NewSession = InferInsertModel<typeof sessions>;

import { z } from "zod";
import { createInsertSchema, createSelectSchema } from "drizzle-zod";
import { users, sessions } from "../schemas/auth";

export const insertUserSchema = createInsertSchema(users);
export const selectUserSchema = createSelectSchema(users);
export const insertSessionSchema = createInsertSchema(sessions);
export const selectSessionSchema = createSelectSchema(sessions);

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

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

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

{
  "name": "@workspace/auth",
  "version": "0.0.0",
  "type": "module",
  "private": true,
  "scripts": {
    "generate": "pnpx @better-auth/cli generate --output ../db/schemas/auth.ts --yes"
  },
  "exports": {
    ".": "./index.ts",
    "./client": "./client.ts",
    "./handler": "./handler.ts"
  },
  "dependencies": {
    "@workspace/db": "workspace:*",
    "better-auth": "^1.3.27",
    "nanoid": "^5.1.6"
  },
  "devDependencies": {
    "@workspace/typescript-config": "workspace:*"
  }
}

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

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

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

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

TURSO_DATABASE_URL=http://127.0.0.1:8080

3.4 認証スキーマの作成

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

cd packages/auth

pnpm generate

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

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

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

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

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

import "dotenv/config";
import { drizzle } from "drizzle-orm/libsql/web";
import * as auth from "./schemas/auth";

export const db = drizzle({
  connection: {
    url: process.env.TURSO_DATABASE_URL!,
    authToken: process.env.TURSO_AUTH_TOKEN!,
  },
  schema: {
    ...auth, 
  },
});

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

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

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

3.7 Better Authの設定

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

import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { db } from "@workspace/db";
import { nextCookies } from "better-auth/next-js";
import { anonymous } from "better-auth/plugins";

export const auth = betterAuth({
  baseURL: process.env.BETTER_AUTH_URL || "http://localhost:3000",
  secret: process.env.BETTER_AUTH_SECRET!,
  database: drizzleAdapter(db, {
    provider: "sqlite",
    usePlural: true,
  }),
  plugins: [nextCookies(), anonymous()],
});

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

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

# ルートディレクトリから
pnpm dev

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

5.1 Sentryの設定

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

@sentry/wizard@latest -i nextjs

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