フロントエンド開発ガイドライン
目的
React 19を採用したモダンなNext.js 15開発のための包括的なガイド。サーバーコンポーネント、クライアントコンポーネント、App Routerパターン、Shadcn/uiコンポーネント、適切なファイル構成、パフォーマンス最適化を重視します。
このスキルを使用する場面
- 新しいコンポーネントやページの作成
- 新機能の構築
- データフェッチ(サーバーコンポーネント、サーバーアクション)
- Next.js App Routerを使用したルーティング設定
- Tailwind CSSとShadcn/uiによるコンポーネントのスタイリング
- パフォーマンス最適化
- フロントエンドコードの整理
- TypeScriptのベストプラクティス
クイックスタート
新規コンポーネント用チェックリスト
コンポーネントを作成しますか?以下のチェックリストに従ってください:
- サーバーコンポーネントとクライアントコンポーネントのどちらを使うか決定(デフォルトはサーバーコンポーネント)
- 必要な場合のみ
"use client"ディレクティブを追加(インタラクティブ性、フック、ブラウザAPI) - 明示的なプロップ型を持つTypeScriptを使用
- Shadcn/uiコンポーネントを
@/components/uiからインポート - スタイリングにTailwind CSSクラスを使用
- エイリアスインポート:
@/components、@/lib、@/hooks - 条件付きクラスに
cn()ユーティリティを使用 - デフォルトエクスポートをファイルの下部に配置
- データフェッチには可能な限りサーバーコンポーネントを使用
新規ページ用チェックリスト
ページを作成しますか?以下の構造を設定してください:
- ルート用に
app/{route-name}/page.tsxを作成 - デフォルトでサーバーコンポーネントを使用
- サーバーコンポーネント内で直接データをフェッチ
- ページ固有のコンポーネント用に
components/ディレクトリを作成 - ローディング状態に
loading.tsxを使用 - エラーバウンダリに
error.tsxを使用 - SEO用のメタデータをエクスポート
インポートエイリアスクイックリファレンス
| エイリアス | 解決先 | 例 |
|---|---|---|
@/ | プロジェクトルート | import { cn } from '@/lib/utils' |
@/components | components/ | import { Button } from '@/components/ui/button' |
@/lib | lib/ | import { cn } from '@/lib/utils' |
@/hooks | hooks/ | import { useMobile } from '@/hooks/use-mobile' |
@/app | app/ | import { Metadata } from 'next' |
定義場所:tsconfig.json paths構成
よく使うインポートのチートシート
// Next.js
import { Metadata } from 'next'
import { Suspense } from 'react'
import { notFound, redirect } from 'next/navigation'
// React(クライアントコンポーネントのみ)
;('use client')
import { useState, useCallback, useMemo } from 'react'
// Shadcn/uiコンポーネント
import { Button } from '@/components/ui/button'
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
import { Input } from '@/components/ui/input'
// ユーティリティ
import { cn } from '@/lib/utils'
// フック(クライアントコンポーネントのみ)
import { useMobile } from '@/hooks/use-mobile'
// 型
import type { ComponentProps } from 'react'
トピックガイド
🎨 コンポーネントパターン
サーバーコンポーネント vs クライアントコンポーネント:
- サーバーコンポーネント(デフォルト):
"use client"なし、直接データフェッチ可能、バンドルが小さい - クライアントコンポーネント:インタラクティブ性、フック、ブラウザAPIのために
"use client"を追加
重要な概念:
- デフォルトでサーバーコンポーネントを使用
- 必要な場合のみクライアントコンポーネントを使用
- Shadcn/uiコンポーネント(既にクライアントコンポーネント)を使用
- コンポーネント構造:Props → データフェッチ → レンダリング → エクスポート
サーバーコンポーネントの例:
// app/features/posts/components/PostList.tsx
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
interface PostListProps {
posts: Post[]
}
export function PostList({ posts }: PostListProps) {
return (
<div className='grid gap-4'>
{posts.map((post) => (
<Card key={post.id}>
<CardHeader>
<CardTitle>{post.title}</CardTitle>
</CardHeader>
<CardContent>{post.content}</CardContent>
</Card>
))}
</div>
)
}
クライアントコンポーネントの例:
// app/features/posts/components/PostForm.tsx
'use client'
import { useState } from 'react'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
export function PostForm() {
const [title, setTitle] = useState('')
return (
<form>
<Input value={title} onChange={(e) => setTitle(e.target.value)} />
<Button type='submit'>送信</Button>
</form>
)
}
📊 データフェッチ
主要パターン:サーバーコンポーネント
- サーバーコンポーネント内で直接データをフェッチ
- サーバーコンポーネントで
async/awaitを使用 useEffectやデータフェッチライブラリは不要- 自動的なリクエスト重複排除
サーバーアクション:
- ミューテーション(フォーム、更新)に使用
app/actions/ディレクトリを作成"use server"ディレクティブでマーク
データフェッチを含むサーバーコンポーネントの例:
// app/posts/page.tsx
import { PostList } from '@/components/PostList'
async function getPosts() {
const res = await fetch('https://api.example.com/posts', {
cache: 'no-store', // または 'force-cache'、'revalidate'
})
return res.json()
}
export default async function PostsPage() {
const posts = await getPosts()
return <PostList posts={posts} />
}
サーバーアクションの例:
// app/actions/posts.ts
'use server'
export async function createPost(formData: FormData) {
const title = formData.get('title')
// ... バリデーションと作成ロジック
redirect('/posts')
}
📁 ファイル構成
App Routerの構造:
app/
(routes)/
page.tsx # ルートページ
layout.tsx # ルートレイアウト
loading.tsx # ローディングUI
error.tsx # エラーUI
components/ # 共有コンポーネント
ui/ # Shadcn/uiコンポーネント
features/ # 機能固有のコード
posts/
components/ # 機能コンポーネント
actions/ # サーバーアクション
types/ # TypeScript型
lib/
utils.ts # ユーティリティ(cnなど)
hooks/
use-mobile.ts # カスタムフック(クライアントのみ)
機能の構成:
app/features/{feature}/:機能固有のページ・ルートcomponents/:真に再利用可能なコンポーネントcomponents/ui/:Shadcn/uiコンポーネント(直接変更しない)
🎨 スタイリング
Tailwind CSS + Shadcn/ui:
- Tailwindのユーティリティクラスを使用
- 条件付きクラスに
cn()ユーティリティを使用 - Shadcn/uiコンポーネントはCSS変数でテーマ設定
app/globals.cssでテーマをカスタマイズ
スタイリングパターン:
import { cn } from '@/lib/utils'
interface ButtonProps {
variant?: 'primary' | 'secondary'
className?: string
}
export function Button({ variant = 'primary', className }: ButtonProps) {
return (
<button
className={cn(
'rounded-md px-4 py-2',
variant === 'primary' && 'bg-primary text-primary-foreground',
variant === 'secondary' && 'bg-secondary text-secondary-foreground',
className,
)}
>
クリック
</button>
)
}
Shadcn/uiコンポーネント:
@/components/ui/{component-name}からインポート- コンポーネントは既にスタイル設定済みでアクセシブル
classNameプロップまたはCSS変数でカスタマイズ
🛣️ ルーティング
Next.js App Router - ファイルベース:
- ディレクトリ:
app/{route-name}/page.tsx - ネストされたルート:
app/{parent}/{child}/page.tsx - 動的ルート:
app/posts/[id]/page.tsx - ルートグループ:
app/(marketing)/about/page.tsx
ルートの例:
// app/posts/page.tsx
import { Metadata } from 'next'
import { PostList } from '@/components/PostList'
export const metadata: Metadata = {
title: '投稿',
description: '全投稿のリスト',
}
export default async function PostsPage() {
const posts = await getPosts()
return (
<div className='container mx-auto py-8'>
<h1 className='text-3xl font-bold mb-6'>投稿</h1>
<PostList posts={posts} />
</div>
)
}
動的ルート:
// app/posts/[id]/page.tsx
interface PostPageProps {
params: Promise<{ id: string }>
}
export default async function PostPage({ params }: PostPageProps) {
const { id } = await params
const post = await getPost(id)
if (!post) {
notFound()
}
return <PostDetail post={post} />
}
⏳ ローディングとエラー状態
ローディング状態:
- ルートディレクトリに
loading.tsxを作成 - 自動的にページをSuspenseでラップ
- ルートレベルのローディングに使用
エラーバウンダリ:
- ルートディレクトリに
error.tsxを作成 - ルートのエラーを自動的にキャッチ
- エラー状態をリセット可能
ローディングUIの例:
// app/posts/loading.tsx
export default function Loading() {
return (
<div className='flex items-center justify-center min-h-screen'>
<div className='animate-spin rounded-full h-8 w-8 border-b-2 border-primary' />
</div>
)
}
エラーUIの例:
// app/posts/error.tsx
'use client'
import { useEffect } from 'react'
import { Button } from '@/components/ui/button'
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
useEffect(() => {
console.error(error)
}, [error])
return (
<div className='flex flex-col items-center justify-center min-h-screen'>
<h2 className='text-2xl font-bold mb-4'>エラーが発生しました!</h2>
<Button onClick={reset}>再試行</Button>
</div>
)
}
⚡ パフォーマンス
最適化パターン:
- サーバーコンポーネントを使用(バンドルが小さい)
- 画像に
next/imageを使用 - フォントに
next/fontを使用 - 可能な場合はクライアントコンポーネントを遅延読み込み
- クライアントコンポーネントで
useMemoとuseCallbackを使用 - Suspenseバウンダリでデータをストリーミング
画像最適化:
import Image from 'next/image'
export function Avatar({ src, alt }: { src: string; alt: string }) {
return (
<Image
src={src}
alt={alt}
width={40}
height={40}
className='rounded-full'
/>
)
}
Suspenseを使ったストリーミング:
import { Suspense } from 'react'
import { PostList } from '@/components/PostList'
import { Loading } from '@/components/Loading'
export default function Page() {
return (
<div>
<Suspense fallback={<Loading />}>
<PostList />
</Suspense>
</div>
)
}
📘 TypeScript
標準:
- Strictモード有効
any型は使用しない- 関数の明示的な戻り値型
- 型のインポート:
import type { Post } from '@/types/post' - JSDoc付きのコンポーネントプロップインターフェース
例:
import type { ComponentProps } from 'react'
import { Button } from '@/components/ui/button'
/**
* ローディング状態を持つカスタムボタンコンポーネント
*/
interface CustomButtonProps extends ComponentProps<typeof Button> {
isLoading?: boolean
}
export function CustomButton({
isLoading,
children,
...props
}: CustomButtonProps) {
return (
<Button disabled={isLoading} {...props}>
{isLoading ? '読み込み中...' : children}
</Button>
)
}
🔧 よく使うパターン
フォーム処理:
- フォーム送信にサーバーアクションを使用
- バリデーションには
react-hook-formとzodを使用(クライアントコンポーネント) - Shadcn/uiのフォームコンポーネントを使用
サーバーアクションを使ったフォームの例:
// app/actions/posts.ts
'use server'
import { z } from 'zod'
const createPostSchema = z.object({
title: z.string().min(1),
content: z.string().min(1),
})
export async function createPost(formData: FormData) {
const rawData = {
title: formData.get('title'),
content: formData.get('content'),
}
const validated = createPostSchema.parse(rawData)
// ... 投稿作成ロジック
redirect('/posts')
}
メタデータ:
import { Metadata } from 'next'
export const metadata: Metadata = {
title: '投稿',
description: '全投稿のリスト',
openGraph: {
title: '投稿',
description: '全投稿のリスト',
},
}
基本原則
- サーバーコンポーネント優先:デフォルトでサーバーコンポーネントを使用し、必要な場合のみクライアントコンポーネントを使用
- App Router構造:
app/ディレクトリを使ったファイルベースルーティング - Shadcn/uiコンポーネント:事前構築済みのアクセシブルなコンポーネントを使用
- Tailwind CSS:
cn()ヘルパーを使ったユーティリティファーストのスタイリング - TypeScript Strict:
anyは使用せず、明示的な型付け - パフォーマンス:サーバーコンポーネントを使用し、画像を最適化し、必要に応じて遅延読み込み
- ファイル構成:機能は
app/features/、共有はcomponents/ - インポートエイリアス:クリーンなインポートに
@/プレフィックスを使用
クイックリファレンス:ファイル構造
app/
layout.tsx # ルートレイアウト
page.tsx # ホームページ
globals.css # グローバルスタイル
(routes)/
posts/
page.tsx # 投稿一覧ページ
[id]/
page.tsx # 投稿詳細ページ
loading.tsx # ローディングUI
error.tsx # エラーUI
features/
posts/
components/
PostList.tsx # 機能コンポーネント
actions/
posts.ts # サーバーアクション
components/
ui/ # Shadcn/uiコンポーネント
button.tsx
card.tsx
lib/
utils.ts # ユーティリティ(cnなど)
hooks/
use-mobile.ts # カスタムフック
モダンコンポーネントテンプレート(クイックコピー)
サーバーコンポーネント:
// app/components/PostCard.tsx
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
import type { Post } from '@/types/post'
interface PostCardProps {
post: Post
}
export function PostCard({ post }: PostCardProps) {
return (
<Card>
<CardHeader>
<CardTitle>{post.title}</CardTitle>
</CardHeader>
<CardContent>
<p>{post.content}</p>
</CardContent>
</Card>
)
}
クライアントコンポーネント:
// app/components/PostForm.tsx
'use client'
import { useState } from 'react'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
export function PostForm() {
const [title, setTitle] = useState('')
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault()
// ... 送信ロジック
}
return (
<form onSubmit={handleSubmit}>
<Input
value={title}
onChange={(e) => setTitle(e.target.value)}
placeholder='タイトル'
/>
<Button type='submit'>送信</Button>
</form>
)
}
まとめ
これらのガイドラインは、Next.js 15とReact 19を使用したプロジェクトで一貫性のある保守しやすいコードを書くためのベストプラクティスを提供します。以下の原則に従うことで、クリーンで効率的なコードを実現できます。