[프로젝트 TypeBoy] 5. 서버 구축하기: Next.js Route Handler + Prisma + Neon

Taehee_Hwang·2025년 2월 14일

Type Boy

목록 보기

6/6

Next.js는 프론트엔드뿐만 아니라 백엔드 기능까지 제공하는 풀스택 프레임워크로 자리 잡았습니다. 특히, Route Handler(App Router를 사용 중이라면 API Routes)를 활용하면 API 서버를 간편하게 구축할 수 있으며, Prisma와 Neon을 함께 사용하면 확장성과 유지보수성이 뛰어난 데이터베이스 연동이 가능합니다. 이번 글에서는 Route Handler와 Prisma를 활용하여 Neon에 연결하는 방법을 소개합니다.

Neon 데이터베이스 생성

Neon은 서버리스 PostgreSQL 솔루션입니다.
db를 위한 서버를 구축하지 않아도 된다는 점에서 매우 간편하게 세팅할 수 있습니다.

create db

create neon

Vercel 의 Storage 탭에서 neon db를 생성합니다.

select free

무료 옵션으로 생성해주었습니다.

Prisma 설정 및 데이터베이스 연결

먼저, Next.js 프로젝트에 Prisma를 설치합니다.

npm install prisma --save-dev
npx prisma init

schema.prisma

schema.prisma 파일이 자동으로 생성됩니다.

미리 생성해두었던 Neon을 보면 환경변수가 안내되어 있습니다.
.env

로컬 개발 환경을 위해 .env.local 항목을 적용하겠습니다. (Copy Snippet 버튼을 클릭!)

배포 시의 환경변수는 Vercel에서 자동으로 적용해줍니다.👏👏👏

Prisma 스키마 정의 및 마이그레이션

Prisma의 schema.prisma 파일에서 데이터 모델을 정의한 후, prisma migrate dev 명령어를 실행하여 데이터베이스에 반영합니다.

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model user {
  id                Int        @id @default(autoincrement())
 // 기타 속성...
}

npx prisma migrate dev

개발 환경에서는 migrate dev 실제 배포할 환경이라면 migrate deploy를 사용합니다.

Route Handler로 API 구현

Route Handler를 활용하여 CRUD API를 구축합니다. Next.js의 app/api 디렉토리 내에서 각 엔드포인트를 정의하며, lib/prisma.ts를 별도로 생성하여 Prisma Client를 관리합니다.

Prisma Client 최적화

import { PrismaClient } from "@prisma/client";

let prisma: PrismaClient | undefined = undefined;

export function getPrismaClient() {
  if (process.env.NODE_ENV === "production") {
    return new PrismaClient();
  } else {
    if (!prisma) {
      prisma = new PrismaClient();
    }
    return prisma;
  }
}

Next.js의 핫 리로딩으로 인해 Prisma Client가 여러 번 생성되지 않도록 글로벌 변수를 활용하여 인스턴스를 재사용하도록 설정합니다.

Route Handler 구현

route handler

app/api 디렉토리 내에서 각 엔드포인트를 정의합니다.

import { getPrismaClient } from "../../../../lib";

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const prisma = getPrismaClient();

  const sentence = await prisma.sentence.findUnique({
    where: {
      id: parseInt(id),
    },
  });
  return Response.json(sentence);
}

테스트를 위해 조회 api만 구현해보았습니다.

API 테스트 및 배포

API 요청 테스트

간단하게 브라우저를 통해서 API의 응답을 확인합니다.

API 응답

Vercel 및 Neon을 활용한 배포

Vercel을 이용하여 Next.js 애플리케이션을 배포하고, 배포된 환경에서도 DB 및 API가 정상 작동하는지 확인합니다!

마무리

이 글에서는 Next.js의 Route Handler와 Prisma를 활용하여 Neon과 연결하는 방법을 다루었습니다.

이전 회사에서 프론트엔드 CI/CD 업무를 맡았던 적이 있었는데, 당시 고생했었던 것을 생각해보면 Vercel을 칭찬할 수 밖에 없어집니다.

물론 프로젝트 규모가 커진다면 Vercel만으로 모든 요구 사항을 충족할 수 없겠지만, 초기 개발 단계에서는 매우 유용한 플랫폼이라고 생각합니다.

앞으로 이 서버를 기반으로 다양한 기능을 추가해나갈 예정입니다! 지켜봐주세요🐢

Taehee_Hwang

이전 포스트