logoNext.js Español
DocumentaciónBlogAprender
Introducción/Referencia de API/Funciones/NextRequest y NextResponse

NextRequest y NextResponse

next/server proporciona ayudantes exclusivos del servidor para usar en Middleware y Rutas API Edge.

NextRequest

El objeto NextRequest es una extensión de la interfaz nativa Request, con los siguientes métodos y propiedades añadidos:

  • cookies - Una instancia de RequestCookies con las cookies de la Request. Lee/modifica la cabecera Cookie de la solicitud. Consulte también Uso de cookies en Middleware.

    • get - Un método que toma un nombre de cookie y devuelve un objeto con name y value. Si no se encuentra una cookie con ese nombre, devuelve undefined. Si hay múltiples cookies coincidentes, solo devuelve la primera coincidencia.
    • getAll - Similar a get, pero devuelve una lista de todas las cookies con un nombre coincidente. Si no se especifica nombre, devuelve todas las cookies disponibles.
    • set - Un método que toma un objeto con propiedades de CookieListItem como se define en la especificación W3C CookieStore API.
    • delete - Un método que toma un nombre de cookie o una lista de nombres y elimina las cookies coincidentes. Devuelve true para cookies eliminadas y false para no eliminadas.
    • has - Un método que toma un nombre de cookie y devuelve un boolean indicando si la cookie existe (true) o no (false).
    • clear - Un método sin argumentos que elimina efectivamente la cabecera Cookie.

  • nextUrl: Incluye un objeto URL extendido y analizado que proporciona acceso a propiedades específicas de Next.js como pathname, basePath, trailingSlash e i18n. Incluye las siguientes propiedades:

    • basePath (string)
    • buildId (string || undefined)
    • defaultLocale (string || undefined)
    • domainLocale
      • defaultLocale: (string)
      • domain: (string)
      • http: (boolean || undefined)
      • locales: (string[] || undefined)
    • locale (string || undefined)
    • url (URL)

  • ip: (string || undefined) - Contiene la dirección IP de la Request. Esta información es proporcionada por su plataforma de hosting.

  • geo - Contiene la ubicación geográfica de la Request. Esta información es proporcionada por su plataforma de hosting. Incluye las siguientes propiedades:

    • city (string || undefined)
    • country (string || undefined)
    • region (string || undefined)
    • latitude (string || undefined)
    • longitude (string || undefined)

Puede usar el objeto NextRequest como reemplazo directo de la interfaz nativa Request, dándole más control sobre cómo manipular la solicitud.

NextRequest se puede importar desde next/server:

import type { NextRequest } from 'next/server'

NextFetchEvent

El objeto NextFetchEvent extiende el objeto nativo FetchEvent e incluye el método waitUntil().

El método waitUntil() se puede usar para prolongar la ejecución de la función si tiene otro trabajo en segundo plano que realizar.

import { NextResponse } from 'next/server'
import type { NextFetchEvent, NextRequest } from 'next/server'

export function middleware(req: NextRequest, event: NextFetchEvent) {
  event.waitUntil(
    fetch('https://my-analytics-platform.com', {
      method: 'POST',
      body: JSON.stringify({ pathname: req.nextUrl.pathname }),
    })
  )

  return NextResponse.next()
}

El objeto NextFetchEvent se puede importar desde next/server:

import type { NextFetchEvent } from 'next/server'

NextResponse

La clase NextResponse extiende la interfaz nativa Response con lo siguiente:

Métodos públicos

Los métodos públicos están disponibles en una instancia de la clase NextResponse. Dependiendo de su caso de uso, puede crear una instancia y asignarla a una variable, luego acceder a los siguientes métodos públicos:

  • cookies - Una instancia de ResponseCookies con las cookies de la Response. Lee/modifica la cabecera Set-Cookie de la respuesta. Consulte también Uso de cookies en Middleware.
    • get - Un método que toma un nombre de cookie y devuelve un objeto con name y value. Si no se encuentra una cookie con ese nombre, devuelve undefined. Si hay múltiples cookies coincidentes, solo devuelve la primera coincidencia.
    • getAll - Similar a get, pero devuelve una lista de todas las cookies con un nombre coincidente. Si no se especifica nombre, devuelve todas las cookies disponibles.
    • set - Un método que toma un objeto con propiedades de CookieListItem como se define en la especificación W3C CookieStore API.
    • delete - Un método que toma un nombre de cookie o una lista de nombres y elimina las cookies coincidentes. Devuelve true para cookies eliminadas y false para no eliminadas.

Métodos estáticos

Los siguientes métodos estáticos están disponibles directamente en la clase NextResponse:

  • redirect() - Devuelve una NextResponse con una redirección configurada
  • rewrite() - Devuelve una NextResponse con una reescritura configurada
  • next() - Devuelve una NextResponse que continuará la cadena de middleware

Para usar los métodos anteriores, debe devolver el objeto NextResponse devuelto. NextResponse se puede importar desde next/server:

import { NextResponse } from 'next/server'

userAgent

El ayudante userAgent le permite interactuar con el objeto user agent de la solicitud. Está abstraído del objeto nativo Request y es una función opcional. Tiene las siguientes propiedades:

  • isBot: (boolean) Indica si la solicitud proviene de un bot conocido
  • browser
    • name: (string || undefined) Nombre del navegador
    • version: (string || undefined) Versión del navegador, determinada dinámicamente
  • device
    • model: (string || undefined) Modelo del dispositivo, determinado dinámicamente
    • type: (string || undefined) Tipo de navegador, puede ser uno de: console, mobile, tablet, smarttv, wearable, embedded, o undefined
    • vendor: (string || undefined) Fabricante del dispositivo, determinado dinámicamente
  • engine
    • name: (string || undefined) Nombre del motor del navegador, puede ser: Amaya, Blink, EdgeHTML, Flow, Gecko, Goanna, iCab, KHTML, Links, Lynx, NetFront, NetSurf, Presto, Tasman, Trident, w3m, WebKit o undefined
    • version: (string || undefined) Versión del motor, determinada dinámicamente, o undefined
  • os
    • name: (string || undefined) Nombre del SO, puede ser undefined
    • version: (string || undefined) Versión del SO, determinada dinámicamente, o undefined
  • cpu
    • architecture: (string || undefined) Arquitectura de la CPU, puede ser: 68k, amd64, arm, arm64, armhf, avr, ia32, ia64, irix, irix64, mips, mips64, pa-risc, ppc, sparc, sparc64 o undefined

userAgent se puede importar desde next/server:

import { userAgent } from 'next/server'
import { NextRequest, NextResponse, userAgent } from 'next/server'

export function middleware(request: NextRequest) {
  const url = request.nextUrl
  const { device } = userAgent(request)
  const viewport = device.type === 'mobile' ? 'mobile' : 'desktop'
  url.searchParams.set('viewport', viewport)
  return NextResponse.rewrite(url)
}

Preguntas frecuentes

¿Por qué redirect usa 307 y 308?

Al usar redirect() puede notar que los códigos de estado utilizados son 307 para redirección temporal y 308 para redirección permanente. Tradicionalmente se usaba 302 para redirección temporal y 301 para permanente, pero muchos navegadores cambiaban el método de solicitud de la redirección, de POST a GET al usar 302, independientemente del método original.

Tomando el ejemplo de una redirección de /users a /people, si hace una solicitud POST a /users para crear un nuevo usuario y se conforma con un 302 temporal, el método de solicitud cambiará de POST a GET. Esto no tiene sentido, ya que para crear un nuevo usuario debería hacer una solicitud POST a /people, no GET.

La introducción del código de estado 307 significa que el método de solicitud se conserva como POST.

  • 302 - Redirección temporal, cambia el método de solicitud de POST a GET
  • 307 - Redirección temporal, conserva el método de solicitud como POST

El método redirect() usa 307 por defecto, en lugar de 302, lo que significa que sus solicitudes siempre se conservarán como POST.

Si desea causar una respuesta GET a una solicitud POST, use 303.

Aprenda más sobre Redirecciones HTTP.

¿Cómo accedo a Variables de Entorno?

process.env se puede usar para acceder a Variables de Entorno desde Edge Middleware. Se evalúan durante next build:

FuncionaNo funciona
console.log(process.env.MY_ENV_VARIABLE)const getEnv = name => process.env[name]
const { MY_ENV_VARIABLE } = process.env
const { "MY-ENV-VARIABLE": MY_ENV_VARIABLE } = process.env

getStaticProps

Referencia de API para `getStaticProps`. Aprende a usar `getStaticProps` para generar páginas estáticas con Next.js.

useAmp

Habilita AMP en una página y controla cómo Next.js agrega AMP a la página mediante la configuración AMP.