Variables d'environnement

Next.js inclut un support natif pour les variables d'environnement, ce qui vous permet de :

• Utiliser .env.local pour charger des variables d'environnement
• Inclure des variables d'environnement pour le navigateur en les préfixant avec NEXT_PUBLIC_

Chargement des variables d'environnement

Next.js prend en charge nativement le chargement des variables d'environnement depuis .env.local vers process.env.

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

Cela charge automatiquement process.env.DB_HOST, process.env.DB_USER, et process.env.DB_PASS dans l'environnement Node.js, vous permettant de les utiliser dans les méthodes de récupération de données Next.js et les routes API.

Par exemple, avec getStaticProps :

export async function getStaticProps() {
  const db = await myDB.connect({
    host: process.env.DB_HOST,
    username: process.env.DB_USER,
    password: process.env.DB_PASS,
  })
  // ...
}

Référencement d'autres variables

Next.js étendra automatiquement les variables utilisant $ pour référencer d'autres variables, par exemple $VARIABLE dans vos fichiers .env*. Cela vous permet de référencer d'autres secrets. Par exemple :

TWITTER_USER=nextjs
TWITTER_URL=https://twitter.com/$TWITTER_USER

Dans l'exemple ci-dessus, process.env.TWITTER_URL sera défini sur https://twitter.com/nextjs.

Bon à savoir : Si vous avez besoin d'utiliser un $ dans la valeur réelle, il doit être échappé avec \, par exemple \$.

Inclusion des variables d'environnement pour le navigateur

Les variables d'environnement non préfixées par NEXT_PUBLIC_ ne sont disponibles que dans l'environnement Node.js, ce qui signifie qu'elles ne sont pas accessibles depuis le navigateur (le client s'exécute dans un environnement différent).

Pour rendre une variable d'environnement accessible dans le navigateur, Next.js peut "inline" une valeur, au moment de la construction, dans le bundle js livré au client, remplaçant toutes les références à process.env.[variable] par une valeur codée en dur. Pour cela, il suffit de préfixer la variable avec NEXT_PUBLIC_. Par exemple :

NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk

Cela indiquera à Next.js de remplacer toutes les références à process.env.NEXT_PUBLIC_ANALYTICS_ID dans l'environnement Node.js par la valeur de l'environnement lors de l'exécution de next build, vous permettant de l'utiliser n'importe où dans votre code. Elle sera incluse dans tout JavaScript envoyé au navigateur.

Remarque : Après la construction, votre application ne répondra plus aux changements de ces variables d'environnement. Par exemple, si vous utilisez un pipeline Heroku pour promouvoir des slugs construits dans un environnement vers un autre, ou si vous construisez et déployez une seule image Docker dans plusieurs environnements, toutes les variables NEXT_PUBLIC_ seront figées avec la valeur évaluée au moment de la construction. Ces valeurs doivent donc être définies correctement lors de la construction du projet. Si vous avez besoin d'accéder à des valeurs d'environnement à l'exécution, vous devrez mettre en place votre propre API pour les fournir au client (soit à la demande, soit lors de l'initialisation).

import setupAnalyticsService from '../lib/my-analytics-service'

// 'NEXT_PUBLIC_ANALYTICS_ID' peut être utilisé ici car il est préfixé par 'NEXT_PUBLIC_'.
// Il sera transformé au moment de la construction en `setupAnalyticsService('abcdefghijk')`.
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)

function HomePage() {
  return <h1>Hello World</h1>
}

export default HomePage

Notez que les recherches dynamiques ne seront pas incluses, comme :

// Ceci ne sera PAS inclus, car il utilise une variable
const varName = 'NEXT_PUBLIC_ANALYTICS_ID'
setupAnalyticsService(process.env[varName])

// Ceci ne sera PAS inclus, car il utilise une variable
const env = process.env
setupAnalyticsService(env.NEXT_PUBLIC_ANALYTICS_ID)

Variables d'environnement à l'exécution

Next.js peut prendre en charge à la fois les variables d'environnement de construction et d'exécution.

Par défaut, les variables d'environnement ne sont disponibles que sur le serveur. Pour exposer une variable d'environnement au navigateur, elle doit être préfixée par NEXT_PUBLIC_. Cependant, ces variables publiques seront incluses dans le bundle JavaScript lors de next build.

Pour lire les variables d'environnement à l'exécution, nous recommandons d'utiliser getServerSideProps ou d'adopter progressivement le routeur App. Avec le routeur App, nous pouvons lire en toute sécurité les variables d'environnement sur le serveur pendant le rendu dynamique. Cela vous permet d'utiliser une seule image Docker pouvant être promue à travers plusieurs environnements avec différentes valeurs.

import { unstable_noStore as noStore } from 'next/cache'

export default function Component() {
  noStore()
  // cookies(), headers(), et autres fonctions dynamiques
  // activeront également le rendu dynamique, ce qui signifie
  // que cette variable d'environnement est évaluée à l'exécution
  const value = process.env.MY_VALUE
  // ...
}

Bon à savoir :

• Vous pouvez exécuter du code au démarrage du serveur en utilisant la fonction register.
• Nous ne recommandons pas d'utiliser l'option runtimeConfig, car elle ne fonctionne pas avec le mode de sortie standalone. Nous recommandons plutôt d'adopter progressivement le routeur App.

Variables d'environnement par défaut

En général, un seul fichier .env.local est nécessaire. Cependant, il peut être utile de définir des valeurs par défaut pour l'environnement de development (next dev) ou de production (next start).

Next.js vous permet de définir des valeurs par défaut dans .env (tous les environnements), .env.development (environnement de développement), et .env.production (environnement de production).

.env.local remplace toujours les valeurs par défaut.

Bon à savoir : Les fichiers .env, .env.development, et .env.production doivent être inclus dans votre dépôt car ils définissent des valeurs par défaut. .env*.local doit être ajouté à .gitignore, car ces fichiers sont destinés à être ignorés. .env.local est l'endroit où les secrets peuvent être stockés.

Variables d'environnement sur Vercel

Lors du déploiement de votre application Next.js sur Vercel, les variables d'environnement peuvent être configurées dans les paramètres du projet.

Tous les types de variables d'environnement doivent y être configurés. Même les variables utilisées en développement – qui peuvent être téléchargées sur votre appareil local par la suite.

Si vous avez configuré des variables d'environnement de développement, vous pouvez les récupérer dans un .env.local pour une utilisation locale avec la commande suivante :

vercel env pull .env.local

Bon à savoir : Lors du déploiement de votre application Next.js sur Vercel, vos variables d'environnement dans les fichiers .env* ne seront pas disponibles pour Edge Runtime, sauf si leur nom est préfixé par NEXT_PUBLIC_. Nous recommandons fortement de gérer vos variables d'environnement dans les paramètres du projet, où toutes les variables sont disponibles.

Variables d'environnement de test

En plus des environnements development et production, il existe une 3ème option : test. De la même manière que vous pouvez définir des valeurs par défaut pour les environnements de développement ou de production, vous pouvez le faire avec un fichier .env.test pour l'environnement de test (bien que ce soit moins courant que les deux premiers). Next.js ne chargera pas les variables d'environnement depuis .env.development ou .env.production dans l'environnement de test.

Cela est utile lors de l'exécution de tests avec des outils comme jest ou cypress où vous devez définir des variables d'environnement spécifiques uniquement pour les tests. Les valeurs par défaut de test seront chargées si NODE_ENV est défini sur test, bien que vous n'ayez généralement pas besoin de le faire manuellement, car les outils de test s'en chargeront.

Il y a une petite différence entre l'environnement test, et les environnements development et production à garder à l'esprit : .env.local ne sera pas chargé, car vous attendez que les tests produisent les mêmes résultats pour tout le monde. Ainsi, chaque exécution de test utilisera les mêmes valeurs par défaut d'environnement en ignorant votre .env.local (qui est destiné à remplacer les valeurs par défaut).

Bon à savoir : comme pour les variables d'environnement par défaut, le fichier .env.test doit être inclus dans votre dépôt, mais .env.test.local ne doit pas l'être, car .env*.local est destiné à être ignoré via .gitignore.

Lors de l'exécution de tests unitaires, vous pouvez vous assurer que vos variables d'environnement sont chargées de la même manière que Next.js en utilisant la fonction loadEnvConfig du package @next/env.

// Ceci peut être utilisé dans un fichier de configuration global Jest ou similaire pour votre configuration de test
import { loadEnvConfig } from '@next/env'

export default async () => {
  const projectDir = process.cwd()
  loadEnvConfig(projectDir)
}

Ordre de chargement des variables d'environnement

Les variables d'environnement sont recherchées dans les emplacements suivants, dans l'ordre, en s'arrêtant dès que la variable est trouvée.

1. process.env
2. .env.$(NODE_ENV).local
3. .env.local (Non vérifié lorsque NODE_ENV est test.)
4. .env.$(NODE_ENV)
5. .env

Par exemple, si NODE_ENV est development et que vous définissez une variable à la fois dans .env.development.local et .env, la valeur dans .env.development.local sera utilisée.

Bon à savoir : Les valeurs autorisées pour NODE_ENV sont production, development et test.

Bon à savoir

• Si vous utilisez un dossier /src, les fichiers .env.* doivent rester à la racine de votre projet.
• Si la variable d'environnement NODE_ENV n'est pas définie, Next.js l'attribue automatiquement à development lors de l'exécution de la commande next dev, ou à production pour toutes les autres commandes.

Historique des versions