Vercel 開発のベストプラクティス

概要

このスキルは、Vercel での アプリケーション開発とデプロイメントの包括的なガイドラインを提供します。Next.js、React Server Components、Edge Functions、Vercel AI SDK に重点を置いています。

コアプリンシパル

• 簡潔で技術的な TypeScript コードと正確な例を書く
• 関数型および宣言型プログラミングパターンを使用。クラスは避ける
• 'use client'、'useEffect'、'setState' を最小化。React Server Components (RSC) を優先する
• Tailwind CSS を使用したモバイルファーストアプローチでレスポンシブデザインを実装する
• Core Web Vitals とパフォーマンスを最適化する

プロジェクト構造

my-app/
├── app/                    # App Router ページとレイアウト
│   ├── (auth)/            # ルートグループ
│   ├── api/               # API ルート
│   ├── layout.tsx         # ルートレイアウト
│   └── page.tsx           # ホームページ
├── components/            # React コンポーネント
│   ├── ui/               # UI プリミティブ
│   └── features/         # 機能コンポーネント
├── lib/                   # ユーティリティ関数
├── hooks/                 # カスタム React フック
├── types/                 # TypeScript 型
├── public/               # 静的アセット
└── vercel.json           # Vercel 設定

Next.js App Router ガイドライン

ファイル命名規則

• ディレクトリには小文字とダッシュを使用 (例：components/auth-wizard)
• コンポーネントと関数には名前付きエクスポートを優先する
• ルートページには page.tsx、レイアウトには layout.tsx を使用する
• ローディング状態には loading.tsx、エラーバウンダリには error.tsx を使用する

サーバーコンポーネント (デフォルト)

// app/users/page.tsx
import { getUsers } from '@/lib/data';

export default async function UsersPage() {
  const users = await getUsers();

  return (
    <main>
      <h1>Users</h1>
      <ul>
        {users.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </main>
  );
}

クライアントコンポーネント (必要な場合)

'use client';

import { useState } from 'react';

export function Counter() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </button>
  );
}

TypeScript 標準

型定義

// オブジェクトの形状には type より interface を使用
interface User {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
}

// ユニオン型と複雑な型には type を使用
type Status = 'pending' | 'active' | 'inactive';

// enum は避ける。代わりに const オブジェクトを使用
const STATUS = {
  PENDING: 'pending',
  ACTIVE: 'active',
  INACTIVE: 'inactive',
} as const;

type StatusValue = typeof STATUS[keyof typeof STATUS];

コンポーネント Props

interface ButtonProps {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  onClick?: () => void;
}

export function Button({
  children,
  variant = 'primary',
  size = 'md',
  disabled = false,
  onClick,
}: ButtonProps) {
  // 実装
}

API ルート

ルートハンドラー

// app/api/users/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const CreateUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});

export async function GET(request: NextRequest) {
  const users = await getUsers();
  return NextResponse.json(users);
}

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const validated = CreateUserSchema.parse(body);

    const user = await createUser(validated);
    return NextResponse.json(user, { status: 201 });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: 'Validation failed', details: error.errors },
        { status: 400 }
      );
    }
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

Edge Runtime

// app/api/edge-function/route.ts
export const runtime = 'edge';

export async function GET(request: Request) {
  return new Response(JSON.stringify({ message: 'Hello from the edge!' }), {
    headers: { 'Content-Type': 'application/json' },
  });
}

Vercel AI SDK 統合

ストリーミングチャット UI

'use client';

import { useChat } from 'ai/react';

export function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
    api: '/api/chat',
  });

  return (
    <div className="flex flex-col h-full">
      <div className="flex-1 overflow-y-auto">
        {messages.map(message => (
          <div key={message.id} className={message.role === 'user' ? 'text-right' : ''}>
            <p>{message.content}</p>
          </div>
        ))}
      </div>

      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Type a message..."
          disabled={isLoading}
        />
      </form>
    </div>
  );
}

AI API ルート

// app/api/chat/route.ts
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';

export async function POST(request: Request) {
  const { messages } = await request.json();

  const result = await streamText({
    model: openai('gpt-4-turbo'),
    messages,
    system: 'You are a helpful assistant.',
  });

  return result.toDataStreamResponse();
}

AI のエラーハンドリング

import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';

export async function POST(request: Request) {
  try {
    const { messages } = await request.json();

    const result = await streamText({
      model: openai('gpt-4-turbo'),
      messages,
    });

    return result.toDataStreamResponse();
  } catch (error) {
    // レート制限を処理
    if (error.message?.includes('rate limit')) {
      return new Response('Rate limit exceeded. Please try again later.', {
        status: 429,
      });
    }

    // クォータ超過を処理
    if (error.message?.includes('quota')) {
      return new Response('API quota exceeded.', { status: 402 });
    }

    // フォールバックから代替モデルへ
    console.error('Primary model failed:', error);
    return new Response('Service temporarily unavailable.', { status: 503 });
  }
}

データフェッチング

サーバー側データフェッチング

// Server Components でデータをフェッチ
async function getData() {
  const res = await fetch('https://api.example.com/data', {
    next: { revalidate: 3600 }, // 1 時間キャッシュ
  });

  if (!res.ok) {
    throw new Error('Failed to fetch data');
  }

  return res.json();
}

export default async function Page() {
  const data = await getData();
  return <div>{/* データをレンダリング */}</div>;
}

URL 状態管理

// サーバー状態に URL クエリパラメータを使用
import { useSearchParams, useRouter } from 'next/navigation';

export function Filters() {
  const searchParams = useSearchParams();
  const router = useRouter();

  const updateFilter = (key: string, value: string) => {
    const params = new URLSearchParams(searchParams);
    params.set(key, value);
    router.push(`?${params.toString()}`);
  };

  return (/* フィルター UI */);
}

パフォーマンス最適化

画像最適化

import Image from 'next/image';

export function Hero() {
  return (
    <Image
      src="/hero.jpg"
      alt="Hero image"
      width={1200}
      height={600}
      priority // LCP のためにすぐに読み込む
      placeholder="blur"
      blurDataURL="data:image/jpeg;base64,..."
    />
  );
}

動的インポート

import dynamic from 'next/dynamic';

// 重いコンポーネントを遅延読み込み
const HeavyChart = dynamic(() => import('@/components/heavy-chart'), {
  loading: () => <div>Loading chart...</div>,
  ssr: false, // 必要に応じて SSR を無効化
});

Suspense 境界

import { Suspense } from 'react';

export default function Page() {
  return (
    <div>
      <h1>Dashboard</h1>
      <Suspense fallback={<Loading />}>
        <AsyncComponent />
      </Suspense>
    </div>
  );
}

エラーハンドリング

エラーバウンダリー

// app/error.tsx
'use client';

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

グローバルエラーハンドラー

// app/global-error.tsx
'use client';

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={reset}>Try again</button>
      </body>
    </html>
  );
}

Vercel 設定

vercel.json

{
  "framework": "nextjs",
  "regions": ["iad1"],
  "crons": [
    {
      "path": "/api/cron/cleanup",
      "schedule": "0 0 * * *"
    }
  ],
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "*" }
      ]
    }
  ]
}

環境変数

// 機密データに環境変数を使用
const apiKey = process.env.API_KEY;
const publicUrl = process.env.NEXT_PUBLIC_APP_URL;

// 必須の環境変数を検証
if (!apiKey) {
  throw new Error('API_KEY environment variable is required');
}

デプロイメント

プレビューデプロイメント

• すべてのプルリクエストはプレビューデプロイメントを取得
• テストとレビューにプレビュー URL を使用
• ステークホルダーとプレビューリンクを共有

本番デプロイメント

# Vercel に repo を接続 (GitHub から ワンクリック)
# または Vercel CLI を使用
vercel --prod

Edge Config

import { get } from '@vercel/edge-config';

export async function getFeatureFlag(flag: string) {
  const flags = await get('featureFlags');
  return flags?.[flag] ?? false;
}

UI とスタイリング

Tailwind CSS セットアップ

// モバイルファーストレスポンシブデザインを使用
export function Card({ children }: { children: React.ReactNode }) {
  return (
    <div className="p-4 md:p-6 lg:p-8 rounded-lg bg-white shadow-sm">
      {children}
    </div>
  );
}

Shadcn UI コンポーネント

import { Button } from '@/components/ui/button';
import { Dialog, DialogContent, DialogTrigger } from '@/components/ui/dialog';

export function ConfirmDialog() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="destructive">Delete</Button>
      </DialogTrigger>
      <DialogContent>
        <p>Are you sure?</p>
      </DialogContent>
    </Dialog>
  );
}

アクセシビリティ

ベストプラクティス

export function AccessibleButton() {
  return (
    <button
      aria-label="Close dialog"
      aria-expanded={isOpen}
      aria-controls="dialog-content"
      className="focus:ring-2 focus:ring-offset-2 focus:ring-blue-500"
    >
      <XIcon aria-hidden="true" />
    </button>
  );
}

避けるべき一般的な落とし穴

1. 不必要に 'use client' を使用する
2. 適切なエラーバウンダリーを実装しない
3. Core Web Vitals の最適化を無視する
4. TypeScript を厳密に使用しない
5. 環境変数をハードコードする
6. 非同期コンポーネントに対して Suspense 境界がない
7. 画像を最適化しない
8. アクセシビリティ要件を無視する