Route Handlers를 사용하면 웹 Request (opens in a new tab)와 Response (opens in a new tab) API를 사용하여 특정 라우트에 대한 사용자 정의 요청 핸들러를 만들 수 있습니다.

Route Handlers

알아두면 좋은 점: Route Handlers는 app 디렉토리 내에서만 사용할 수 있습니다. 이는 pages 디렉토리 내의 API Routes와 동일한 기능을 하므로, API Routes와 Route Handlers를 함께 사용할 필요가 없습니다.

Convention

Route Handlers는 app 디렉토리 내의 route.js|ts 파일로 정의됩니다:

app/api/route.ts

export async function GET(request: Request) {}

app/api/route.js

export async function GET(request) {}

Route Handlers는 page.js 및 layout.js와 유사하게 app 디렉토리 내 어디에나 중첩될 수 있습니다. 하지만 page.js와 동일한 라우트 세그먼트 레벨에 route.js 파일이 있을 수 없습니다.

Supported HTTP Methods

다음 HTTP 메서드 (opens in a new tab)를 지원합니다: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. 지원되지 않는 메서드가 호출되면 Next.js는 405 Method Not Allowed 응답을 반환합니다.

Extended `NextRequest` and `NextResponse` APIs

Next.js는 기본 Request (opens in a new tab) 및 Response (opens in a new tab) API를 지원하는 것 외에도, NextRequest와 NextResponse를 확장하여 고급 사용 사례를 위한 편리한 헬퍼를 제공합니다.

Behavior

Caching

Route Handlers는 기본적으로 캐시되지 않습니다. 그러나 GET 메서드에 대해 캐시를 선택할 수 있습니다. 이를 위해 Route Handler 파일에 export const dynamic = 'force-static'과 같은 route config option을 사용합니다.

app/items/route.ts

export const dynamic = 'force-static'
 
export async function GET() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY,
    },
  })
  const data = await res.json()
 
  return Response.json({ data })
}

app/items/route.js

export const dynamic = 'force-static'
 
export async function GET() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY,
    },
  })
  const data = await res.json()
 
  return Response.json({ data })
}

Special Route Handlers

sitemap.ts, opengraph-image.tsx, icon.tsx 및 기타 메타데이터 파일과 같은 특별한 Route Handlers는 동적 함수나 동적 구성 옵션을 사용하지 않는 한 기본적으로 정적입니다.

Route Resolution

route는 가장 낮은 레벨의 라우팅 원시 형태로 간주할 수 있습니다.

page와 같은 레이아웃이나 클라이언트 측 탐색에 참여하지 않습니다.
page.js와 동일한 라우트에 route.js 파일이 있을 수 없습니다.

Page	Route	Result
`app/page.js`	`app/route.js`	Conflict
`app/page.js`	`app/api/route.js`	Valid
`app/[user]/page.js`	`app/api/route.js`	Valid

각 route.js 또는 page.js 파일은 해당 라우트에 대한 모든 HTTP 메서드를 처리합니다.

app/page.js

export default function Page() {
  return <h1>Hello, Next.js!</h1>
}
 
// ❌ Conflict
// `app/route.js`
export async function POST(request) {}

Examples

다음 예제는 Route Handlers를 다른 Next.js API 및 기능과 결합하는 방법을 보여줍니다.

Revalidating Cached Data

next.revalidate 옵션을 사용하여 캐시된 데이터를 재검증할 수 있습니다:

app/items/route.ts

export async function GET() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    next: { revalidate: 60 }, // 60초마다 재검증
  })
  const data = await res.json()
 
  return Response.json(data)
}

app/items/route.js

export async function GET() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    next: { revalidate: 60 }, // 60초마다 재검증
  })
  const data = await res.json()
 
  return Response.json(data)
}

또는 revalidate 세그먼트 구성 옵션을 사용할 수 있습니다:

export const revalidate = 60

Dynamic Functions

Route Handlers는 Next.js의 cookies 및 headers와 같은 동적 함수와 함께 사용할 수 있습니다.

Cookies

next/headers에서 cookies를 사용하여 쿠키를 읽거나 설정할 수 있습니다. 이 서버 함수는 Route Handler에서 직접 호출되거나 다른 함수 내에서 중첩될 수 있습니다.

또는 Set-Cookie (opens in a new tab) 헤더를 사용하여 새 Response를 반환할 수 있습니다.

app/api/route.ts

import { cookies } from 'next/headers'
 
export async function GET(request: Request) {
  const cookieStore = cookies()
  const token = cookieStore.get('token')
 
  return new Response('Hello, Next.js!', {
    status: 200,
    headers: { 'Set-Cookie': `token=${token.value}` },
  })
}

app/api/route.js

import { cookies } from 'next/headers'
 
export async function GET(request) {
  const cookieStore = cookies()
  const token = cookieStore.get('token')
 
  return new Response('Hello, Next.js!', {
    status: 200,
    headers: { 'Set-Cookie': `token=${token}` },
  })
}

기본 웹 API를 사용하여 요청에서 쿠키를 읽을 수도 있습니다 (NextRequest):

app/api/route.ts

import { type NextRequest } from 'next/server'
 
export async function GET(request: NextRequest) {
  const token = request.cookies.get('token')
}

app/api/route.js

export async function GET(request) {
  const token = request.cookies.get('token')
}

Headers

next/headers에서 headers를 사용하여 헤더를 읽을 수 있습니다. 이 서버 함수는 Route Handler에서 직접 호출되거나 다른 함수 내에서 중첩될 수 있습니다.

이 headers 인스턴스는 읽기 전용입니다. 헤더를 설정하려면 새 headers와 함께 새 Response를 반환해야 합니다.

app/api/route.ts

import { headers } from 'next/headers'
 
export async function GET(request: Request) {
  const headersList = headers()
  const referer = headersList.get('referer')
 
  return new Response('Hello, Next.js!', {
    status: 200,
    headers: { referer: referer },
  })
}

app/api/route.js

import { headers } from 'next/headers'
 
export async function GET(request) {
  const headersList = headers()
  const referer = headersList.get('referer')
 
  return new Response('Hello, Next.js!', {
    status: 200,
    headers: { referer: referer },
  })
}

기본 웹 API를 사용하여 요청에서 헤더를 읽을 수도 있습니다 (NextRequest):

app/api/route.ts

import { type NextRequest } from 'next/server'
 
export async function GET(request: NextRequest) {
  const requestHeaders = new Headers(request.headers)
}

app/api/route.js

export async function GET(request) {
  const requestHeaders = new Headers(request.headers)
}

Redirects

app/api/route.ts

import { redirect } from 'next/navigation'
 
export async function GET(request: Request) {
  redirect('https://nextjs.org/')
}

app/api/route.js

import { redirect } from 'next/navigation'
 
export async function GET(request) {
  redirect('https://nextjs.org/')
}

Dynamic Route Segments

계속하기 전에 Defining Routes 페이지를 읽어보는 것을 권장합니다.

Route Handlers는 Dynamic Segments를 사용하여 동적 데이터를 기반으로 요청 핸들러를 생성할 수 있습니다.

app/items/[slug]/route.ts

export async function GET(
  request: Request,
  { params }: { params: { slug: string } },
) {
  const slug = params.slug // 'a', 'b', 또는 'c'
}

app/items/[slug]/route.js

export async function GET(request, { params }) {
  const slug = params.slug // 'a', 'b', 또는 'c'
}

Route	Example URL	`params`
`app/items/[slug]/route.js`	`/items/a`	`{ slug: 'a' }`
`app/items/[slug]/route.js`	`/items/b`	`{ slug: 'b' }`
`app/items/[slug]/route.js`	`/items/c`	`{ slug: 'c' }`

URL Query Parameters

Route Handler에 전달되는 요청 객체는 NextRequest 인스턴스로, 쿼리 매개변수를 보다 쉽게 처리할 수 있는 편리한 추가 메서드를 제공합니다.

app/api/search/route.ts

import { type NextRequest } from 'next/server'
 
export function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams
  const query = searchParams.get('query')
  // query는 /api/search?query=hello일 때 "hello"입니다.
}

app/api/search/route.js

export function GET(request) {
  const searchParams = request.nextUrl.searchParams
  const query = searchParams.get('query')
  // query는 /api/search?query=hello일 때 "hello"입니다.
}

Streaming

스트리밍은 OpenAI와 같은 대형 언어 모델(LLM)과 함께 AI 생성 콘텐츠를 위해 일반적으로 사용됩니다. AI SDK (opens in a new tab)에서 자세히 알아보세요.

app/api/chat/route.ts

import { openai } from '@ai-sdk/openai'
import { StreamingTextResponse, streamText } from 'ai'
 
export async function POST(req) {
  const { messages } = await req.json()
  const result = await streamText({
    model: openai('gpt-4-turbo'),
    messages,
  })
 
  return new StreamingTextResponse(result.toAIStream())
}

app/api/chat/route.js

import { openai } from "@ai-sdk/openai";
import { StreamingTextResponse, streamText } from "ai";
 
export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = await streamText({
    model: openai("gpt-4-turbo"),
    messages,
  });
 
  return new StreamingTextResponse(result.toAIStream());
}

이러한 추상화는 스트림을 생성하기 위해 웹 API를 사용합니다. 기본 웹 API를 직접 사용할 수도 있습니다.

app/api/route.ts

// https://developer.mozilla.org/docs/Web/API/ReadableStream#convert_async_iterator_to_stream
function iteratorToStream(iterator: any) {
  return new ReadableStream({
    async pull(controller) {
      const { value, done } = await iterator.next()
 
      if (done) {
        controller.close()
      } else {
        controller.enqueue(value)
      }
    },
  })
}
 
function sleep(time: number) {
  return new Promise((resolve) => {
    setTimeout(resolve, time)
  })
}
 
const encoder = new TextEncoder()
 
async function* makeIterator() {
  yield encoder.encode('<p>One</p>')
  await sleep(200)
  yield encoder.encode('<p>Two</p>')
  await sleep(200)
  yield encoder.encode('<p>Three</p>')
}
 
export async function GET() {
  const iterator = makeIterator()
  const stream = iteratorToStream(iterator)
 
  return new Response(stream)
}

app/api/route.js

// https://developer.mozilla.org/docs/Web/API/ReadableStream#convert_async_iterator_to_stream
function iteratorToStream(iterator) {
  return new ReadableStream({
    async pull(controller) {
      const { value, done } = await iterator.next()
 
      if (done) {
        controller.close()
      } else {
        controller.enqueue(value)
      }
    },
  })
}
 
function sleep(time) {
  return new Promise((resolve) => {
    setTimeout(resolve, time)
  })
}
 
const encoder = new TextEncoder()
 
async function* makeIterator() {
  yield encoder.encode('<p>One</p>')
  await sleep(200)
  yield encoder.encode('<p>Two</p>')
  await sleep(200)
  yield encoder.encode('<p>Three</p>')
}
 
export async function GET() {
  const iterator = makeIterator()
  const stream = iteratorToStream(iterator)
 
  return new Response(stream)
}

Request Body

기본 웹 API 메서드를 사용하여 Request 본문을 읽을 수 있습니다:

app/items/route.ts

export async function POST(request: Request) {
  const res = await request.json()
  return Response.json({ res })
}

app/items/route.js

export async function POST(request) {
  const res = await request.json()
  return Response.json({ res })
}

Request Body FormData

request.formData() 함수를 사용하여 FormData를 읽을 수 있습니다:

app/items/route.ts

export async function POST(request: Request) {
  const formData = await request.formData()
  const name = formData.get('name')
  const email = formData.get('email')
  return Response.json({ name, email })
}

app/items/route.js

export async function POST(request) {
  const formData = await request.formData()
  const name = formData.get('name')
  const email = formData.get('email')
  return Response.json({ name, email })
}

formData 데이터는 모두 문자열이므로 zod-form-data (opens in a new tab)를 사용하여 요청을 검증하고 원하는 형식(예: number)으로 데이터를 가져올 수 있습니다.

CORS

기본 웹 API 메서드를 사용하여 특정 Route Handler에 대한 CORS 헤더를 설정할 수 있습니다:

app/api/route.ts

export async function GET(request: Request) {
  return new Response('Hello, Next.js!', {
    status: 200,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  })
}

app/api/route.js

export async function GET(request) {
  return new Response('Hello, Next.js!', {
    status: 200,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  })
}

알아두면 좋은 점:

여러 Route Handlers에 CORS 헤더를 추가하려면 Middleware 또는 next.config.js 파일을 사용할 수 있습니다.

또는 CORS 예제 (opens in a new tab) 패키지를 참조하세요.

Webhooks

Route Handler를 사용하여 타사 서비스의 웹훅을 수신할 수 있습니다:

app/api/route.ts

export async function POST(request: Request) {
  try {
    const text = await request.text()
    // 웹훅 페이로드 처리
  } catch (error) {
    return new Response(`Webhook error: ${error.message}`, {
      status: 400,
    })
  }
 
  return new Response('Success!', {
    status: 200,
  })
}

app/api/route.js

export async function POST(request) {
  try {
    const text = await request.text()
    // 웹훅 페이로드 처리
  } catch (error) {
    return new Response(`Webhook error: ${error.message}`, {
      status: 400,
    })
  }
 
  return new Response('Success!', {
    status: 200,
  })
}

특히, Pages Router의 API Routes와 달리 bodyParser를 사용하여 추가 구성을 할 필요가 없습니다.

Non-UI Responses

Route Handlers를 사용하여 UI가 아닌 콘텐츠를 반환할 수 있습니다. sitemap.xml, robots.txt, app icons, open graph images 등은 모두 기본적으로 지원됩니다.

app/rss.xml/route.ts

export async function GET() {
  return new Response(
    `<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
 
<channel>
  <title>Next.js Documentation</title>
  <link>https://nextjs.org/docs</link>
  <description>The React Framework for the Web</description>
</channel>
 
</rss>`,
    {
      headers: {
        'Content-Type': 'text/xml',
      },
    },
  )
}

app/rss.xml/route.js

export async function GET() {
  return new Response(`<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
 
<channel>
  <title>Next.js Documentation</title>
  <link>https://nextjs.org/docs</link>
  <description>The React Framework for the Web</description>
</channel>
 
</rss>`)
}

Segment Config Options

Route Handlers는 페이지 및 레이아웃과 동일한 route segment configuration을 사용합니다.

app/items/route.ts

export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'

app/items/route.js

export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'

자세한 내용은 API 참조를 참조하세요.

Intercepting Routes Middleware

Route Handlers

Convention

Supported HTTP Methods

Extended NextRequest and NextResponse APIs

Behavior

Caching

Special Route Handlers

Route Resolution

Examples

Revalidating Cached Data

Dynamic Functions

Cookies

Headers

Redirects

Dynamic Route Segments

URL Query Parameters

Streaming

Request Body

Request Body FormData

CORS

Webhooks

Non-UI Responses

Segment Config Options

Extended `NextRequest` and `NextResponse` APIs