Accelerating Next.js Full-Stack Development: Claude Code 활용 가이드

Next.js × Claude Code로풀스택개발

Next.jsのApp Routerは、프론트엔드と백엔드を통합的に개발できる프레임워크です。Claude Code와組み合わせることで、페이지、APIルート、데이터베이스연동までを一気に구축할 수 있습니다。

프로젝트の初期セットアップ

> Next.js 14 + TypeScript + Tailwind CSS + Prismaの
> 프로젝트를 생성해줘。App Routerを使用。
> 다음의구성で：
> - src/app: 페이지・레이아웃
> - src/components: 共通컴포넌트
> - src/lib: ユーティリティ・DB接続
> - prisma: 스키마・마이그레이션

Server Componentsの활용

데이터フェッチングをServer Componentsで行うパターンを생성させます。

> ブ로그글목록페이지をServer Componentで생성して。
> Prismaから데이터취득。페이지네이션대응。

// src/app/posts/page.tsx
import { prisma } from "@/lib/prisma";
import { PostCard } from "@/components/PostCard";
import { Pagination } from "@/components/Pagination";

interface Props {
  searchParams: Promise<{ page?: string }>;
}

export default async function PostsPage({ searchParams }: Props) {
  const { page: pageParam } = await searchParams;
  const page = Number(pageParam) || 1;
  const perPage = 12;

  const [posts, total] = await Promise.all([
    prisma.post.findMany({
      take: perPage,
      skip: (page - 1) * perPage,
      orderBy: { createdAt: "desc" },
      include: { author: { select: { name: true, avatar: true } } },
    }),
    prisma.post.count(),
  ]);

  return (
    <main className="container mx-auto px-4 py-8">
      <h1 className="mb-8 text-3xl font-bold">記事一覧</h1>
      <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
        {posts.map((post) => (
          <PostCard key={post.id} post={post} />
        ))}
      </div>
      <Pagination
        currentPage={page}
        totalPages={Math.ceil(total / perPage)}
        basePath="/posts"
      />
    </main>
  );
}

export const metadata = {
  title: "記事一覧",
  description: "すべての記事を表示します",
};

Server Actionsの활용

폼処理をServer Actionsで구현します。

> 글생성폼をServer Actionsで구현して。
> 유효성 검사はzod、에러 핸들링も含めて。

// src/app/posts/new/actions.ts
"use server";

import { prisma } from "@/lib/prisma";
import { redirect } from "next/navigation";
import { z } from "zod";

const CreatePostSchema = z.object({
  title: z.string().min(1, "タイトルは必須です").max(200),
  content: z.string().min(10, "本文は10文字以上必要です"),
  published: z.boolean().default(false),
});

export type FormState = {
  errors?: Record<string, string[]>;
  message?: string;
};

export async function createPost(
  prevState: FormState,
  formData: FormData
): Promise<FormState> {
  const parsed = CreatePostSchema.safeParse({
    title: formData.get("title"),
    content: formData.get("content"),
    published: formData.get("published") === "on",
  });

  if (!parsed.success) {
    return { errors: parsed.error.flatten().fieldErrors };
  }

  await prisma.post.create({
    data: { ...parsed.data, authorId: "current-user-id" },
  });

  redirect("/posts");
}

API Routeの생성

外部연동用のAPI Routeも同時に생성할 수 있습니다。

> /api/posts のRoute Handler를 생성해줘。
> GET（목록・검색・페이지네이션）と POST（생성）。
> 인증チェックも含めて。

// src/app/api/posts/route.ts
import { NextRequest, NextResponse } from "next/server";
import { prisma } from "@/lib/prisma";
import { auth } from "@/lib/auth";

export async function GET(request: NextRequest) {
  const { searchParams } = request.nextUrl;
  const page = Number(searchParams.get("page")) || 1;
  const q = searchParams.get("q") || "";
  const limit = 20;

  const where = q
    ? { title: { contains: q, mode: "insensitive" as const } }
    : {};

  const [posts, total] = await Promise.all([
    prisma.post.findMany({
      where,
      take: limit,
      skip: (page - 1) * limit,
      orderBy: { createdAt: "desc" },
    }),
    prisma.post.count({ where }),
  ]);

  return NextResponse.json({
    data: posts,
    meta: { page, limit, total },
  });
}

export async function POST(request: NextRequest) {
  const session = await auth();
  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const body = await request.json();
  const post = await prisma.post.create({
    data: { ...body, authorId: session.user.id },
  });

  return NextResponse.json({ data: post }, { status: 201 });
}

미들웨어の설정

인증라우팅を미들웨어で制御します。

> 인증が必要なルートを미들웨어で保護して。
> /dashboard, /posts/new, /api/posts(POST) は인증必須。

DB연동의 상세 정보는DB마이그레이션자동화を、React컴포넌트の설계はReact개발を爆速にする方法를 참고하세요.日々の개발効率を上げるコツは生産性を3倍にする10のTips도 함께 확인하세요.

정리

Claude Code와Next.jsの組み合わせは、풀스택개발を劇的に加速します。Server Components、Server Actions、API Routeを一貫して생성できるため、프론트엔드から백엔드までシームレスに개발を進められます。

Next.js의 상세 정보는Next.js공식 문서、Claude Code에ついてはAnthropic공식 문서를 참고하세요.