logoNext.js Français
DocumentationBlogApprendre
Introduction/Référence API/Fonctions/NextRequest et NextResponse

NextRequest et NextResponse

next/server fournit des utilitaires réservés au serveur pour une utilisation dans le Middleware et les routes API Edge.

NextRequest

L'objet NextRequest est une extension de l'interface native Request, avec les méthodes et propriétés supplémentaires suivantes :

  • cookies - Une instance RequestCookies avec les cookies de la Request. Elle lit/modifie l'en-tête Cookie de la requête. Voir aussi Utilisation des cookies dans le Middleware.

    • get - Une méthode qui prend un nom de cookie et renvoie un objet avec name et value. Si aucun cookie avec ce nom n'est trouvé, elle renvoie undefined. Si plusieurs cookies correspondent, elle ne renvoie que le premier.
    • getAll - Similaire à get, mais renvoie une liste de tous les cookies correspondant au nom. Si nom n'est pas spécifié, renvoie tous les cookies disponibles.
    • set - Une méthode qui prend un objet avec les propriétés de CookieListItem telles que définies dans la spécification W3C CookieStore API.
    • delete - Une méthode qui prend un nom de cookie ou une liste de noms, et supprime les cookies correspondants. Renvoie true pour les cookies supprimés et false pour les non supprimés.
    • has - Une méthode qui prend un nom de cookie et renvoie un boolean selon que le cookie existe (true) ou non (false).
    • clear - Une méthode sans argument qui supprime effectivement l'en-tête Cookie.

  • nextUrl: Inclut un objet URL étendu et analysé qui donne accès à des propriétés spécifiques à Next.js comme pathname, basePath, trailingSlash et i18n. Inclut les propriétés suivantes :

    • 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) - Contient l'adresse IP de la Request. Cette information est fournie par votre plateforme d'hébergement.

  • geo - Contient la localisation géographique de la Request. Cette information est fournie par votre plateforme d'hébergement. Inclut les propriétés suivantes :

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

Vous pouvez utiliser l'objet NextRequest comme remplacement direct de l'interface native Request, vous offrant plus de contrôle sur la manipulation de la requête.

NextRequest peut être importé depuis next/server :

import type { NextRequest } from 'next/server'

NextFetchEvent

L'objet NextFetchEvent étend l'objet natif FetchEvent et inclut la méthode waitUntil().

La méthode waitUntil() peut être utilisée pour prolonger l'exécution de la fonction si vous avez d'autres tâches en arrière-plan à effectuer.

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()
}

L'objet NextFetchEvent peut être importé depuis next/server :

import type { NextFetchEvent } from 'next/server'

NextResponse

La classe NextResponse étend l'interface native Response, avec les éléments suivants :

Méthodes publiques

Les méthodes publiques sont disponibles sur une instance de la classe NextResponse. Selon votre cas d'utilisation, vous pouvez créer une instance et l'assigner à une variable, puis accéder aux méthodes publiques suivantes :

  • cookies - Une instance ResponseCookies avec les cookies de la Response. Elle lit/modifie l'en-tête Set-Cookie de la réponse. Voir aussi Utilisation des cookies dans le Middleware.
    • get - Une méthode qui prend un nom de cookie et renvoie un objet avec name et value. Si aucun cookie avec ce nom n'est trouvé, elle renvoie undefined. Si plusieurs cookies correspondent, elle ne renvoie que le premier.
    • getAll - Similaire à get, mais renvoie une liste de tous les cookies correspondant au nom. Si nom n'est pas spécifié, renvoie tous les cookies disponibles.
    • set - Une méthode qui prend un objet avec les propriétés de CookieListItem telles que définies dans la spécification W3C CookieStore API.
    • delete - Une méthode qui prend un nom de cookie ou une liste de noms, et supprime les cookies correspondants. Renvoie true pour les cookies supprimés et false pour les non supprimés.

Méthodes statiques

Les méthodes statiques suivantes sont disponibles directement sur la classe NextResponse :

  • redirect() - Renvoie une NextResponse avec une redirection configurée
  • rewrite() - Renvoie une NextResponse avec une réécriture configurée
  • next() - Renvoie une NextResponse qui continuera la chaîne de middleware

Pour utiliser les méthodes ci-dessus, vous devez renvoyer l'objet NextResponse retourné. NextResponse peut être importé depuis next/server :

import { NextResponse } from 'next/server'

userAgent

L'utilitaire userAgent vous permet d'interagir avec l'objet user agent de la requête. Il est abstrait de l'objet natif Request et est une fonctionnalité optionnelle. Il possède les propriétés suivantes :

  • isBot: (boolean) Indique si la requête provient d'un bot connu
  • browser
    • name: (string || undefined) Le nom du navigateur
    • version: (string || undefined) La version du navigateur, déterminée dynamiquement
  • device
    • model: (string || undefined) Le modèle de l'appareil, déterminé dynamiquement
    • type: (string || undefined) Le type de navigateur, peut être l'une des valeurs suivantes : console, mobile, tablet, smarttv, wearable, embedded, ou undefined
    • vendor: (string || undefined) Le fabricant de l'appareil, déterminé dynamiquement
  • engine
    • name: (string || undefined) Le nom du moteur de rendu, peut être l'une des valeurs suivantes : Amaya, Blink, EdgeHTML, Flow, Gecko, Goanna, iCab, KHTML, Links, Lynx, NetFront, NetSurf, Presto, Tasman, Trident, w3m, WebKit ou undefined
    • version: (string || undefined) La version du moteur de rendu, déterminée dynamiquement, ou undefined
  • os
    • name: (string || undefined) Le nom du système d'exploitation, peut être undefined
    • version: (string || undefined) La version du système d'exploitation, déterminée dynamiquement, ou undefined
  • cpu
    • architecture: (string || undefined) L'architecture du CPU, peut être l'une des valeurs suivantes : 68k, amd64, arm, arm64, armhf, avr, ia32, ia64, irix, irix64, mips, mips64, pa-risc, ppc, sparc, sparc64 ou undefined

userAgent peut être importé depuis 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)
}

FAQ

Pourquoi redirect utilise-t-il 307 et 308 ?

Lors de l'utilisation de redirect(), vous remarquerez peut-être que les codes d'état utilisés sont 307 pour une redirection temporaire et 308 pour une redirection permanente. Traditionnellement, un 302 était utilisé pour une redirection temporaire et un 301 pour une redirection permanente, mais de nombreux navigateurs ont modifié la méthode de requête de la redirection, passant d'une POST à une GET lors de l'utilisation d'un 302, quelle que soit la méthode de requête d'origine.

Prenons l'exemple d'une redirection de /users vers /people : si vous effectuez une requête POST vers /users pour créer un nouvel utilisateur et que vous êtes confronté à une redirection temporaire 302, la méthode de requête sera changée de POST à GET. Cela n'a pas de sens, car pour créer un nouvel utilisateur, vous devriez effectuer une requête POST vers /people, et non une GET.

L'introduction du code d'état 307 signifie que la méthode de requête est préservée en tant que POST.

  • 302 - Redirection temporaire, changera la méthode de requête de POST à GET
  • 307 - Redirection temporaire, préservera la méthode de requête en tant que POST

La méthode redirect() utilise par défaut un 307 au lieu d'une redirection temporaire 302, ce qui signifie que vos requêtes seront toujours préservées en tant que requêtes POST.

Si vous souhaitez provoquer une réponse GET à une requête POST, utilisez 303.

En savoir plus sur les redirections HTTP.

Comment accéder aux variables d'environnement ?

process.env peut être utilisé pour accéder aux variables d'environnement depuis le Middleware Edge. Elles sont évaluées lors de next build :

FonctionneNe fonctionne pas
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

Référence API pour `getStaticProps`. Apprenez à utiliser `getStaticProps` pour générer des pages statiques avec Next.js.

useAmp

Activez AMP dans une page et contrôlez la manière dont Next.js ajoute AMP à la page avec la configuration AMP.