문서
App Router 사용하기
API 참조
파일 구성 규칙
route.js

route.js

라우트 핸들러를 사용하면 웹 Request와 Response API를 사용하여 주어진 라우트에 대한 사용자 정의 요청 핸들러를 만들 수 있습니다.

HTTP 메서드

라우트 파일을 사용하면 주어진 라우트에 대한 사용자 정의 요청 핸들러를 만들 수 있습니다. 다음 HTTP 메서드가 지원됩니다: GET, POST, PUT, PATCH, DELETE, HEAD, 그리고 OPTIONS.

route.ts
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`를 구현하고
// 라우트 핸들러에 정의된 다른 메서드에 따라 적절한 Response `Allow` 헤더를 설정합니다.
export async function OPTIONS(request: Request) {}
route.js
export async function GET(request) {}
 
export async function HEAD(request) {}
 
export async function POST(request) {}
 
export async function PUT(request) {}
 
export async function DELETE(request) {}
 
export async function PATCH(request) {}
 
// `OPTIONS`가 정의되지 않은 경우, Next.js는 자동으로 `OPTIONS`를 구현하고
// 라우트 핸들러에 정의된 다른 메서드에 따라 적절한 Response `Allow` 헤더를 설정합니다.
export async function OPTIONS(request) {}

알아두면 좋은 점: 라우트 핸들러는 App 라우터 내에서만 사용할 수 있습니다. API 라우트(pages)와 라우트 핸들러(app)를 함께 사용할 필요가 없습니다. 라우트 핸들러는 모든 사용 사례를 처리할 수 있어야 합니다.

매개변수

request (선택사항)

request 객체는 NextRequest 객체로, 웹 Request API의 확장입니다. NextRequest는 들어오는 요청에 대한 추가적인 제어를 제공하며, cookies에 쉽게 접근하고 확장된 파싱된 URL 객체인 nextUrl을 포함합니다.

context (선택사항)

app/dashboard/[team]/route.ts
type Params = {
  team: string;
};
 
export async function GET(request: Request, context: { params: Params }) {
  const team = context.params.team; // '1'
}
 
// 라우트 매개변수에 따라 params 타입을 정의합니다 (아래 표 참조)
app/dashboard/[team]/route.js
 
export async function GET(request, context: { params }) {
  const team = context.params.team // '1'
}

현재 context의 유일한 값은 params로, 현재 라우트의 동적 라우트 매개변수를 포함하는 객체입니다.

예시URLparams
app/dashboard/[team]/route.js/dashboard/1{ team: '1' }
app/shop/[tag]/[item]/route.js/shop/1/2{ tag: '1', item: '2' }
app/blog/[...slug]/route.js/blog/1/2{ slug: ['1', '2'] }

NextResponse

라우트 핸들러는 NextResponse 객체를 반환하여 웹 Response API를 확장할 수 있습니다. 이를 통해 쿠키, 헤더를 쉽게 설정하고, 리다이렉트 및 재작성을 할 수 있습니다. API 참조 보기.

버전 기록

버전변경 사항
v15.0.0GET 핸들러의 기본 캐싱이 정적에서 동적으로 변경되었습니다
v13.2.0라우트 핸들러가 도입되었습니다.
page.js경로 세그먼트 설정