route.js

Route Handlers는 특정 경로(route)에 대해 커스텀 요청 처리기를 만들 수 있게 해주는 기능이에요. 즉, 내가 원하는 경로에 맞춰서 요청(Request)과 응답(Response)을 직접 다룰 수 있게 해주죠. 이때 Web Request와 Response API를 활용해요.

예를 들어, 아래처럼 GET 요청을 받았을 때 JSON 형태로 간단한 메시지를 응답하는 코드를 작성할 수 있어요:

export async function GET() {
  return Response.json({ message: 'Hello World' });
}

이 코드는 "/route" 같은 경로로 GET 요청이 들어오면 { message: 'Hello World' }라는 JSON 데이터를 클라이언트에게 보내주는 역할을 해요.

추가로 알아두면 좋은 점 몇 가지 알려드릴게요!

Method별 함수 지원: GET뿐 아니라 POST, PUT, DELETE 등 HTTP 메서드에 맞춰서 함수들을 만들 수 있어요.
내장 Response 객체 활용: 위 예시처럼 Response.json() 메서드는 JSON 응답을 쉽게 만들어 주기 때문에 정말 편리해요.
비동기 처리 가능: 데이터베이스 조회나 외부 API 호출처럼 비동기가 필요한 작업도 async/await 패턴으로 자연스럽게 처리할 수 있어요.
라우팅과 별개로 작동: Next.js 같은 프레임워크에서는 보통 페이지 라우팅과 별개로 API 응답을 여기서 따로 관리할 수 있답니다!

만약 좀 더 복잡한 요청 처리(예: 요청 본문 읽기, 헤더 조작 등)를 하고 싶다면, Request 객체를 받아 쓰면 됩니다. 예를 들어:

export async function POST(request) {
  const body = await request.json();
  return Response.json({ youSent: body });
}

이렇게 하면 클라이언트가 보낸 데이터를 받아서 다시 돌려주는 간단한 POST 처리도 가능해요.

참고 자료

공식 MDN 문서 - Web Request and Response APIs
Next.js API Routes 공식 문서 (비슷한 개념으로 활용 가능)
Response 객체 관련 문서: JSON 응답 생성 등 다양한 메서드 지원

간단하지만 강력한 route.js의 Route Handlers, 여러분의 서버 로직 구현에 꼭 활용해보세요!

HTTP 메서드

라우트 파일에서는 특정 경로(route)에 대해 커스텀 요청 핸들러를 만들 수 있어요. 즉, 클라이언트가 어떤 요청을 했는지에 따라 다르게 동작하도록 코드를 작성할 수 있다는 뜻이죠. 여기서 지원하는 HTTP 메서드는 GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS 이렇게 총 7가지에요.

export async function GET(request: Request) {}
 
export async function HEAD(request: Request) {}
 
export async function POST(request: Request) {}
 
export async function PUT(request: Request) {}
 
export async function DELETE(request: Request) {}
 
export async function PATCH(request: Request) {}
 
// 만약 `OPTIONS` 메서드를 직접 정의하지 않으면,
// Next.js가 자동으로 `OPTIONS` 메서드를 구현해주고,
// Route Handler에 정의된 다른 메서드들을 기준으로 `Allow` 헤더를 설정해줍니다.
export async function OPTIONS(request: Request) {}

각 함수는 Request 객체를 받아서 비동기적으로 처리할 수 있는 함수예요. Request 객체를 통해 요청과 관련된 다양한 정보를 얻을 수 있답니다.

간단히 정리한 HTTP 메서드 역할

메서드	설명
GET	서버에서 데이터를 읽어올 때 사용해요. 가장 기본적인 요청이죠.
POST	서버에 데이터를 새로 생성할 때 쓰여요. 예를 들어 회원가입 같은 요청이죠.
PUT	데이터를 통째로 수정할 때 사용해요. 기존 데이터를 전부 교체할 때 유용합니다.
PATCH	데이터의 일부만 수정할 때 사용해요. 수정할 부분만 보내면 되어서 효율적이죠.
DELETE	서버에서 데이터를 삭제할 때 쓰여요.
HEAD	GET 요청과 비슷하지만 응답 본문(body)은 안 내려줘서 응답 헤더만 받고 싶을 때 유용해요.
OPTIONS	클라이언트가 해당 경로에서 어떤 메서드를 사용할 수 있는지 미리 물어볼 때 사용합니다.

팁! 실제 API 설계할 때는 각 메서드가 어떤 동작을 하는지 명확하게 구분해서 사용하는 게 좋아요. 그래야 클라이언트가 어떤 요청을 보내야 할지 헷갈리지 않고, 유지보수도 훨씬 쉬워집니다.

다음에는 Parameters(매개변수) 부분에 대해 자세히 알아볼게요!

Next.js에서 NextRequest 활용하기 (feat. request 객체 이해하기)

Next.js에서 API 라우트나 미들웨어를 만들 때, request 객체를 자주 다루게 되죠. 그런데 그냥 기본 Web Request API와는 조금 다른, Next.js만의 확장판인 NextRequest라는 객체가 있다고 해요.

NextRequest란?

NextRequest는 기본 Web Request 객체를 상속해서, 더 쉽고 편하게 쓸 수 있게 만든 Next.js 전용 객체입니다. 예를 들어, 쿠키를 꺼내거나, URL 정보를 다룰 때 훨씬 직관적이고 편리해요. nextUrl이라는 확장된 URL 객체가 포함되어 있어서, 이걸 활용하면 URL 조작도 손쉽답니다.

간단한 예제

import type { NextRequest } from 'next/server'

export async function GET(request: NextRequest) {
  // nextUrl을 통해 URL을 쉽게 접근 가능
  const url = request.nextUrl

  // 예: 쿼리 파라미터 출력해보기
  console.log(url.searchParams.get('id'))

  return new Response('Hello World')
}

위 코드에서 request.nextUrl을 이용하면 URL 전체를 분석할 수 있고, searchParams로 쿼리도 쉽게 읽을 수 있어요. 만약 그냥 request.url을 쓰면 문자열 형태라, 직접 파싱을 해야 하니까 귀찮죠.

NextRequest만의 꿀팁!

쿠키 꺼내기: request.cookies.get('cookieName')으로 바로 쿠키 값 꺼낼 수 있어요.
헤더 접근: request.headers.get('headerName') 작성법은 동일하지만, 실제로 다루기 더 깔끔해요.
POST Body 읽기: 비동기로 request.json() 같은 메서드를 사용해 JSON 본문을 바로 파싱할 수 있습니다.

마무리

Next.js 13부터 등장한 이 NextRequest 객체는 서버 컴포넌트나 API 라우트, 미들웨어를 작성할 때 훨씬 편리하고 강력한 도구입니다. 기존의 Web Request 객체보다 기능이 많고, 특히 URL이나 쿠키 처리에 도움을 주니 꼭 활용해 보세요!

궁금하면 Next.js 공식 문서에서 NextRequest도 참고해보시면 좋습니다.

필요하다면 다음에는 NextResponse 활용법도 소개할게요. 이걸로 응답을 쉽게 제어할 수 있답니다!

아래는 Next.js의 동적 라우트에서 params가 어떻게 사용되는지 보여주는 코드 예제입니다. 이 때 params는 현재 라우트의 동적 경로 파라미터들을 담은 객체를 비동기적으로 반환하는 Promise입니다.

export async function GET(
  request: Request,
  { params }: { params: Promise<{ team: string }> }
) {
  const { team } = await params
  // 이제 team 변수에 URL에서 전달된 동적 경로 파라미터가 들어있어요.
}

예를 들어, 다음과 같은 라우트 구조와 URL 요청이 있을 때 params는 이렇게 들어옵니다:

Example	URL	params
`app/dashboard/[team]/route.js`	`/dashboard/1`	`Promise<{ team: '1' }>`
`app/shop/[tag]/[item]/route.js`	`/shop/1/2`	`Promise<{ tag: '1', item: '2' }>`
`app/blog/[...slug]/route.js`	`/blog/1/2`	`Promise<{ slug: ['1', '2'] }>`

여기서 [team], [tag], [item] 같은 부분이 동적 경로 파라미터를 나타내고, [...,slug]는 여러 경로 세그먼트를 배열 형태로 받을 때 사용합니다.

덧붙여서

params가 Promise인 이유는 Next.js가 라우트의 데이터 패칭 시점에 비동기 처리를 하기 때문이에요. 그래서 항상 await을 사용해 값을 꺼내주어야 해요.
동적 라우트를 사용할 땐, params에서 기대하는 속성명이 URL 안 동적 경로 이름과 정확히 일치하는지 꼭 확인해야 합니다.
여러 개의 동적 파라미터가 있다면, 그 만큼 프로퍼티를 비동기로 받아서 처리할 수 있어요.
다중 세그먼트 캡쳐([...slug])는 블로그 포스트나 검색 결과처럼 URL 계층이 다양하게 바뀌는 경우에 유용합니다.

이런 기본 개념만 잘 이해하면 Next.js의 동적 라우트는 크게 어렵지 않으니, 직접 여러가지 라우트를 만들어보면서 경험을 쌓아보세요!

쿠키 다루기

import { cookies } from 'next/headers'

export async function GET(request: NextRequest) {
  const cookieStore = await cookies()

  const a = cookieStore.get('a')       // 쿠키 'a' 값을 가져오기
  const b = cookieStore.set('b', '1')  // 쿠키 'b'를 '1'로 설정하기
  const c = cookieStore.delete('c')    // 쿠키 'c' 삭제하기
}

Next.js의 cookies() 함수로 쉽게 쿠키를 가져오고 설정하고 삭제할 수 있어요. 여기서 중요한 건 cookies()가 비동기 함수라는 점인데, 그래서 await를 붙여줘야 제대로 값을 받을 수 있답니다.

cookieStore.get()은 해당 이름의 쿠키 정보를 객체 형태로 줘요. 없으면 undefined를 반환하고요. cookieStore.set()은 새로운 쿠키를 추가하거나 기존 쿠키를 덮어씁니다. cookieStore.delete()는 지정한 쿠키를 삭제할 때 씁니다.

클라이언트와 서버 모두 쿠키를 다루지만, Next.js API Route 혹은 Route Handler에서는 이렇게 next/headers에서 제공하는 함수를 활용하면 훨씬 간단해져서 좋아요!

버전 히스토리

Version	Changes
`v15.0.0-RC`	`context.params`가 이제 프로미스 형태로 바뀌었어요. codemod 도 제공됩니다.
`v15.0.0-RC`	`GET` 핸들러의 기본 캐싱 정책이 static에서 dynamic으로 변경됐습니다.
`v13.2.0`	Route Handlers가 처음 소개되었습니다.

Next.js는 계속 발전 중이라 버전마다 큰 변화가 있는데, 특히 Route Handler와 쿠키, 캐시 다루는 방식도 바뀌니 공식 문서를 챙겨보시는 걸 추천해요! 혹시 기존 코드를 15버전 이상으로 올리려면 codemod를 꼭 활용해보세요. 작업할 때 시간 많이 절약됩니다.

Next.js 15에서 route.js 파일 설정하는 방법