Next.js Docs (11) Route Handlers

Route Handlers

Route Handlers를 사용하면 Web Request 및 Response API를 사용하여 지정된 route에 대한 커스텀 request handlers(사용자 지정 요청 handler)를 만들 수 있다.

* 알아두면 좋은것 : Route Handler는 app 디렉토리 내부에서만 사용할 수 있다. page 디렉토리 내부의 API Routes와 동일하므로 API Routes와 Route Handler를 같이 사용할 필요는 없다.

Convention

Route Handlers는 app 디렉토리 내의 route.js 파일안에 정의된다.

// app/api/route.ts
export async function GET(request: Request) {}

Route Handlers는 page.js 및 layout.js와 유사하게 app 디렉토리 내부에 중첩될 수 있다. 그러나 page.js와 동일한 레벨의 route 세그먼트에는 route.js 파일이 있으면 안된다.

Supported HTTP Methods

다음과 같은 HTTP Method를 지원한다 : GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

지원하지 않는 method를 사용하면 Next.js는 405 Method Not Allowed 응답을 보낸다.

Extended NextRequest and NextResponse APIs

native Request와 Response를 지원한다. Next.js는 좀 더 발전된 사용 사례에 편리한 helper를 제공하기 위해 native Request와 Response를 확장한 NextRequest 및 NextResponse를 제공한다.

Behavior

Static Route Handlers

Route Handlers는 GET 메서드를 Response 객체와 함께 사용할 때 기본적으로 정적(Static)으로 평가된다.

// app/items/route.ts

import { NextResponse } from 'next/server'
 
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 NextResponse.json({ data })
}

* Typescript 사용시 주의할 점 : Response.json()은 여전히 유효하다. 타입이 표시된 response 대신 NextResponse.json()을 사용할 수 있다. 이 때 native Typescript 타입은 에러를 표시한다.

Dynamic Route Handlers

Route handlers는 다음과 같을 때 동적으로 평가된다.

- Request 객체와 함께 GET 메서드를 사용할 때

- GET 이외의 HTTP 메서드를 사용할 때

- cookies나 headers 같은 Dynamic Function을 사용할 때 (* Dynamic Function은 아래 Example 부분 설명 참조)

- Segment Config Option을 수동으로 dynamic mode로 지정할 때

예시)

// app/products/api/route.ts

import { NextResponse } from 'next/server'
 
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const id = searchParams.get('id')
  const res = await fetch(`https://data.mongodb-api.com/product/${id}`, {
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY,
    },
  })
  const product = await res.json()
 
  return NextResponse.json({ product })
}

위와 비슷하게 POST 메서드를 사용해도 Route Handler를 동적으로 평가한다.

// app/items/route.ts

import { NextResponse } from 'next/server'
 
export async function POST() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY,
    },
    body: JSON.stringify({ time: new Date().toISOString() }),
  })
 
  const data = await res.json()
 
  return NextResponse.json(data)
}

* 알아두면 좋은것 : 이전에는 form 제출처리와 같은 case에 API Route를 사용할 수 있었다. Route Handlers는 이러한 case에 대한 솔루션은 아니다. 나중에 준비가 된다면 이것의 mutations에 대한 추천을 할 것이다. (아직 준비중인듯?하다.)

Route Resolution

Route를 가장 낮은 레벨의 routing primitive로 생각할 수 있다.

- 페이지 같은 것은 레이아웃이나 클라이언트 탐색에 참여하지 않는다.

- page.js와 동일한 route의 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 파일은 해당 route에 대한 모든 HTTP verbs를 인계한다.

// 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 Static Data

next.revalidate 옵션을 사용하여 정적 데이터 fetch의 갱신을 할 수 있다.

// app/items/route.ts

import { NextResponse } from 'next/server'
 
export async function GET() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    next: { revalidate: 60 }, // Revalidate every 60 seconds
  })
  const data = await res.json()
 
  return NextResponse.json(data)
}

또는, 세그먼드 갱신(revalidate) config 옵션을 사용할 수 있다.

export const revalidate = 60

Dynamic Functions

Route Handlers는 cookies나 headers같은 Next.js의 동적 함수(dynamic functions)과 함께 사용할 수 있다.

Cookies

next/headers 로 부터 cookies 를 import해서 cookie를 읽을 수 있다. 이 서버 함수는 Route Handler에서 직접 호출하거나 다른 함수 내부에 중첩할 수 있다.

이 cookie 인스턴스는 읽기 전용이다. 쿠키를 설정하려면 Set-Cookie 헤더를 사용하여 새로운 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}` },
  })
}

혹은 기본 Web API에 있는 추상화를 사용하여 cookies(NextRequest)를 읽을 수 있다:

// app/api/route.ts

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

Headers

next/headers 로 부터 headers 를 import해서 headers를 읽을 수 있다. 이 서버 함수는 Route Handlers에서 직접 호출하거나 다른 함수 내부에 중첩될 수 있다.

이 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 },
  })
}

혹은 기본 Web API에 있는 추상화를 사용하여 headers(NextRequest)를 읽을 수 있다:

// app/api/route.ts

import { type NextRequest } from 'next/server'
 
export async function GET(request: NextRequest) {
  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/')
}

Dynamic Route Segments

* Defining Routes 페이지를 읽고 오는것을 추천한다.

Route Handlers는 동적 세그먼트를 사용하여 동적 데이터에서 request handler를 만들 수 있다.

// app/items/[slug]/route.ts

export async function GET(
  request: Request,
  { params }: { params: { slug: string } }
) {
  const slug = params.slug // 'a', 'b', or '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' }

Streaming

Streaming은 일반적으로 AI-generated 컨텐츠를 위해 OpenAI인 LLM(Large Language Model)과 함께 사용된다.

* AI SDK 알아보기 - https://sdk.vercel.ai/docs

// app/api/conmletion/route.ts

import { Configuration, OpenAIApi } from 'openai-edge'
import { OpenAIStream, StreamingTextResponse } from 'ai'
 
const config = new Configuration({
  apiKey: process.env.OPENAI_API_KEY,
})
const openai = new OpenAIApi(config)
 
export const runtime = 'edge'
 
export async function POST(req: Request) {
  const { prompt } = await req.json()
  const response = await openai.createCompletion({
    model: 'text-davinci-003',
    stream: true,
    temperature: 0.6,
    prompt: 'What is Next.js?',
  })
 
  const stream = OpenAIStream(response)
  return new StreamingTextResponse(stream)
}

이러한 추상화는 Web API를 사용하여 stream을 만든다. 기본 Web API를 직접 사용할 수도 있다.

// app/api/route.ts

// https://developer.mozilla.org/en-US/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)
}

Request Body

표준 Web API 메서드를 사용하여 Request body를 읽을 수 있다.

// app/items/route.ts

import { NextResponse } from 'next/server'
 
export async function POST(request: Request) {
  const res = await request.json()
  return NextResponse.json({ res })
}

CORS

표준 Web API 메서드를 사용하여 Response에 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',
    },
  })
}

Edge and Node.js Runtimes

Route Handler에는 스트리밍 지원을 포함하여 Edge 및 Node.js 런타임을 모두 원활하게 지원하는 Isomorphic(동형) Web API가 있다. Route Handler는 페이지 및 레이아웃과 동일한 route 세그먼트 구성을 사용하므로 범용목적의 정적으로 재생성된 Route Handler와 같은 오래 기다려온 기능을 지원한다.

런타임 세그먼트 config 옵션을 사용하여 런타임을 지정할 수 있다:

export const runtime = 'edge' // 'nodejs' is the default

Non-UI Responses

Route Handler를 사용하여 non-UI 컨텐츠를 반환할 수 있다. sitemap.xml, robots.txt, app 아이콘, open graph 이미지는 모두 기본 제공된다.

// 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>`)
}

Segment Config Options

Route Handler는 페이지 및 레이아웃과 동일한 route 세그먼트 구성을 사용한다.

// 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'

자세한 사항은 API reference 참조.

Reference

- https://nextjs.org/docs/app/building-your-application/routing/router-handlers

Routing: Route Handlers | Next.js

Using App Router Features available in /app

nextjs.org

'개인공부' 카테고리의 다른 글

Next.js Docs (13) Project Organization and File Colocation (0)	2023.07.14
Next.js Docs (12) Middleware (0)	2023.07.11
Next.js Docs (10) Intercepting Routes (0)	2023.07.05
Next.js Docs (9) Parallel Routes (0)	2023.07.02
Next.js Docs (8) Error Handling (0)	2023.06.28

공부기록

Next.js Docs (11) Route Handlers

Route Handlers

Convention

Supported HTTP Methods

Extended NextRequest and NextResponse APIs

Behavior

Static Route Handlers

Dynamic Route Handlers

Route Resolution

Examples

Revalidating Static Data

Dynamic Functions

Redirects

Dynamic Route Segments

Streaming

Request Body

CORS

Edge and Node.js Runtimes

Non-UI Responses

Segment Config Options

Reference

'개인공부' 카테고리의 다른 글

댓글

티스토리툴바

Next.js Docs (11) Route Handlers

Route Handlers

Convention

Supported HTTP Methods

Extended NextRequest and NextResponse APIs

Behavior

Static Route Handlers

Dynamic Route Handlers

Route Resolution

Examples

Revalidating Static Data

Dynamic Functions

Redirects

Dynamic Route Segments

Streaming

Request Body

CORS

Edge and Node.js Runtimes

Non-UI Responses

Segment Config Options

Reference

'개인공부' 카테고리의 다른 글

관련글

댓글

티스토리툴바

Next.js Docs (11) Route Handlers