Manejadores de Ruta
Los Manejadores de Ruta (Route Handlers) le permiten crear manejadores de solicitud personalizados para una ruta determinada utilizando las APIs de Request y Response de la Web.

Nota importante: Los Manejadores de Ruta solo están disponibles dentro del directorio
app
. Son equivalentes a las Rutas API dentro del directoriopages
, lo que significa que no necesita usar Rutas API y Manejadores de Ruta juntos.
Convención
Los Manejadores de Ruta se definen en un archivo route.js|ts
dentro del directorio app
:
export async function GET(request: Request) {}
export async function GET(request) {}
Los Manejadores de Ruta pueden anidarse en cualquier lugar dentro del directorio app
, similar a page.js
y layout.js
. Pero no puede haber un archivo route.js
en el mismo segmento de ruta que page.js
.
Métodos HTTP soportados
Se admiten los siguientes métodos HTTP: GET
, POST
, PUT
, PATCH
, DELETE
, HEAD
y OPTIONS
. Si se llama a un método no admitido, Next.js devolverá una respuesta 405 Método No Permitido
.
APIs extendidas NextRequest
y NextResponse
Además de admitir las APIs nativas Request y Response, Next.js las extiende con NextRequest
y NextResponse
para proporcionar ayudantes convenientes para casos de uso avanzados.
Comportamiento
Almacenamiento en caché
Los Manejadores de Ruta no se almacenan en caché por defecto. Sin embargo, puede optar por el almacenamiento en caché para métodos GET
. Otros métodos HTTP admitidos no se almacenan en caché. Para almacenar en caché un método GET
, use una opción de configuración de ruta como export const dynamic = 'force-static'
en su archivo de Manejador de Ruta.
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 })
}
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 })
}
Nota importante: Otros métodos HTTP admitidos no se almacenan en caché, incluso si se colocan junto a un método
GET
que sí lo está, en el mismo archivo.
Manejadores de Ruta especiales
Los Manejadores de Ruta especiales como sitemap.ts
, opengraph-image.tsx
, icon.tsx
y otros archivos de metadatos permanecen estáticos por defecto a menos que utilicen APIs dinámicas u opciones de configuración dinámica.
Resolución de Rutas
Puede considerar un route
como la primitiva de enrutamiento de nivel más bajo.
- No participan en diseños (layouts) o navegaciones del lado del cliente como
page
. - No puede haber un archivo
route.js
en la misma ruta quepage.js
.
Página | Ruta | Resultado |
---|---|---|
app/page.js | app/route.js | Conflicto |
app/page.js | app/api/route.js | Válido |
app/[user]/page.js | app/api/route.js | Válido |
Cada archivo route.js
o page.js
toma todos los verbos HTTP para esa ruta.
export default function Page() {
return <h1>Hello, Next.js!</h1>
}
// ❌ Conflicto
// `app/route.ts`
export async function POST(request: Request) {}
export default function Page() {
return <h1>Hello, Next.js!</h1>
}
// ❌ Conflicto
// `app/route.js`
export async function POST(request) {}
Ejemplos
Los siguientes ejemplos muestran cómo combinar Manejadores de Ruta con otras APIs y características de Next.js.
Revalidación de datos en caché
Puede revalidar datos en caché usando Regeneración Estática Incremental (ISR):
export const revalidate = 60
export async function GET() {
const data = await fetch('https://api.vercel.app/blog')
const posts = await data.json()
return Response.json(posts)
}
export const revalidate = 60
export async function GET() {
const data = await fetch('https://api.vercel.app/blog')
const posts = await data.json()
return Response.json(posts)
}
Cookies
Puede leer o establecer cookies con cookies
de next/headers
. Esta función de servidor se puede llamar directamente en un Manejador de Ruta o anidarse dentro de otra función.
Alternativamente, puede devolver una nueva Response
usando la cabecera Set-Cookie
.
import { cookies } from 'next/headers'
export async function GET(request: Request) {
const cookieStore = await cookies()
const token = cookieStore.get('token')
return new Response('Hello, Next.js!', {
status: 200,
headers: { 'Set-Cookie': `token=${token.value}` },
})
}
import { cookies } from 'next/headers'
export async function GET(request) {
const cookieStore = await cookies()
const token = cookieStore.get('token')
return new Response('Hello, Next.js!', {
status: 200,
headers: { 'Set-Cookie': `token=${token}` },
})
}
También puede usar las APIs web subyacentes para leer cookies de la solicitud (NextRequest
):
import { type NextRequest } from 'next/server'
export async function GET(request: NextRequest) {
const token = request.cookies.get('token')
}
export async function GET(request) {
const token = request.cookies.get('token')
}
Cabeceras
Puede leer cabeceras con headers
de next/headers
. Esta función de servidor se puede llamar directamente en un Manejador de Ruta o anidarse dentro de otra función.
Esta instancia de headers
es de solo lectura. Para establecer cabeceras, debe devolver una nueva Response
con nuevas headers
.
import { headers } from 'next/headers'
export async function GET(request: Request) {
const headersList = await headers()
const referer = headersList.get('referer')
return new Response('Hello, Next.js!', {
status: 200,
headers: { referer: referer },
})
}
import { headers } from 'next/headers'
export async function GET(request) {
const headersList = await headers()
const referer = headersList.get('referer')
return new Response('Hello, Next.js!', {
status: 200,
headers: { referer: referer },
})
}
También puede usar las APIs web subyacentes para leer cabeceras de la solicitud (NextRequest
):
import { type NextRequest } from 'next/server'
export async function GET(request: NextRequest) {
const requestHeaders = new Headers(request.headers)
}
export async function GET(request) {
const requestHeaders = new Headers(request.headers)
}
Redirecciones
import { redirect } from 'next/navigation'
export async function GET(request: Request) {
redirect('https://nextjs.org/')
}
import { redirect } from 'next/navigation'
export async function GET(request) {
redirect('https://nextjs.org/')
}
Segmentos de Ruta Dinámicos
Los Manejadores de Ruta pueden usar Segmentos Dinámicos para crear manejadores de solicitud a partir de datos dinámicos.
export async function GET(
request: Request,
{ params }: { params: Promise<{ slug: string }> }
) {
const { slug } = await params // 'a', 'b', o 'c'
}
export async function GET(request, { params }) {
const { slug } = await params // 'a', 'b', o 'c'
}
Ruta | URL ejemplo | params |
---|---|---|
app/items/[slug]/route.js | /items/a | Promise<{ slug: 'a' }> |
app/items/[slug]/route.js | /items/b | Promise<{ slug: 'b' }> |
app/items/[slug]/route.js | /items/c | Promise<{ slug: 'c' }> |
Parámetros de consulta URL
El objeto de solicitud pasado al Manejador de Ruta es una instancia de NextRequest
, que incluye algunos métodos adicionales convenientes, como aquellos para manejar más fácilmente los parámetros de consulta.
import { type NextRequest } from 'next/server'
export function GET(request: NextRequest) {
const searchParams = request.nextUrl.searchParams
const query = searchParams.get('query')
// query es "hello" para /api/search?query=hello
}
export function GET(request) {
const searchParams = request.nextUrl.searchParams
const query = searchParams.get('query')
// query es "hello" para /api/search?query=hello
}
Streaming
El streaming se usa comúnmente en combinación con Modelos de Lenguaje Grande (LLMs), como OpenAI, para contenido generado por IA. Aprenda más sobre el AI SDK.
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())
}
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())
}
Estas abstracciones utilizan las APIs web para crear un flujo. También puede usar las APIs web subyacentes directamente.
// 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)
}
// 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)
}
Cuerpo de la solicitud
Puede leer el cuerpo de la Request
utilizando los métodos estándar de la API web:
export async function POST(request: Request) {
const res = await request.json()
return Response.json({ res })
}
export async function POST(request) {
const res = await request.json()
return Response.json({ res })
}
Cuerpo de la solicitud FormData
Puede leer FormData
usando la función request.formData()
:
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 })
}
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 })
}
Dado que los datos de formData
son todos strings, es posible que desee usar zod-form-data
para validar la solicitud y recuperar los datos en el formato que prefiera (por ejemplo, number
).
CORS
Puede establecer cabeceras CORS para un Manejador de Ruta específico utilizando los métodos estándar de la API web:
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',
},
})
}
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',
},
})
}
Nota importante:
- Para agregar cabeceras CORS a múltiples Manejadores de Ruta, puede usar Middleware o el archivo
next.config.js
.- Alternativamente, consulte nuestro paquete de ejemplo CORS.
Webhooks
Puede utilizar un Manejador de Ruta (Route Handler) para recibir webhooks de servicios de terceros:
export async function POST(request: Request) {
try {
const text = await request.text()
// Procesar el payload del webhook
} catch (error) {
return new Response(`Webhook error: ${error.message}`, {
status: 400,
})
}
return new Response('Success!', {
status: 200,
})
}
export async function POST(request) {
try {
const text = await request.text()
// Procesar el payload del webhook
} catch (error) {
return new Response(`Webhook error: ${error.message}`, {
status: 400,
})
}
return new Response('Success!', {
status: 200,
})
}
Cabe destacar que, a diferencia de las Rutas API con el Enrutador de Páginas (Pages Router), no es necesario usar bodyParser
ni ninguna configuración adicional.
Respuestas sin Interfaz de Usuario
Puede utilizar Manejadores de Ruta para devolver contenido que no sea de interfaz de usuario. Tenga en cuenta que sitemap.xml
, robots.txt
, íconos de la aplicación
e imágenes para open graph tienen soporte incorporado.
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',
},
}
)
}
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>`)
}
Opciones de Configuración de Segmento
Los Manejadores de Ruta utilizan la misma configuración de segmento de ruta que las páginas y diseños.
export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'
export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'
Consulte la referencia de API para más detalles.