Claude Code로 Next.js 풀스택 개발 가속화하기

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에서 데이터를 fetch하는 패턴을 생성해 봅시다.

> 블로그 글 목록 페이지를 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가지 팁에서 확인할 수 있습니다.

정리

Claude Code와 Next.js의 조합은 풀스택 개발을 극적으로 가속합니다. Server Components, Server Actions, API Route를 일관되게 생성할 수 있어 프론트엔드부터 백엔드까지 매끄럽게 개발을 이어 갈 수 있죠.

자세한 내용은 Next.js 공식 문서와 Anthropic 공식 문서를 참고하세요.