Comment utiliser les variables d'environnement dans Next.js

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

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

Avertissement : Le modèle par défaut de create-next-app garantit que tous les fichiers .env sont ajoutés à votre .gitignore. Vous ne devez presque jamais commettre ces fichiers dans votre dépôt.

Chargement des variables d'environnement

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

DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword

Remarque : Next.js prend également en charge les variables multilignes dans vos fichiers .env* :

# .env

# vous pouvez écrire avec des sauts de ligne
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"

# ou avec `\n` entre guillemets doubles
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nKh9NV...\n-----END DSA PRIVATE KEY-----\n"

Remarque : Si vous utilisez un dossier /src, notez que Next.js chargera les fichiers .env uniquement depuis le dossier parent et pas depuis le dossier /src. 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 Route Handlers.

Par exemple :

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

Chargement des variables d'environnement avec @next/env

Si vous devez charger des variables d'environnement en dehors de l'exécution de Next.js, comme dans un fichier de configuration racine pour un ORM ou un outil de test, vous pouvez utiliser le package @next/env.

Ce package est utilisé en interne par Next.js pour charger les variables d'environnement depuis les fichiers .env*.

Pour l'utiliser, installez le package et utilisez la fonction loadEnvConfig pour charger les variables d'environnement :

npm install @next/env

import { loadEnvConfig } from '@next/env'

const projectDir = process.cwd()
loadEnvConfig(projectDir)

Ensuite, vous pouvez importer la configuration là où vous en avez besoin. Par exemple :

import './envConfig.ts'

export default defineConfig({
  dbCredentials: {
    connectionString: process.env.DATABASE_URL!,
  },
})

Référencement d'autres variables

Next.js étendra automatiquement les variables qui utilisent $ 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://x.com/$TWITTER_USER

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

Bon à savoir : Si vous devez utiliser une variable avec un $ dans la valeur réelle, elle doit être échappée, 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 la valeur d'une variable d'environnement accessible dans le navigateur, Next.js peut "intégrer" une valeur, au moment de la construction, dans le bundle JavaScript qui est livré au client, remplaçant toutes les références à process.env.[variable] par une valeur codée en dur. Pour cela, vous devez simplement 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 dans lequel vous exécutez next build, vous permettant de l'utiliser n'importe où dans votre code. Elle sera intégrée 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 de manière appropriée lors de la construction du projet. Si vous avez besoin d'accéder à des valeurs d'environnement au runtime, vous devrez configurer 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 intégrées, comme :

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

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

Variables d'environnement au runtime

Next.js peut prendre en charge à la fois les variables d'environnement au moment de la construction et au runtime.

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 intégrées dans le bundle JavaScript lors de next build.

Vous pouvez lire en toute sécurité les variables d'environnement sur le serveur pendant le rendu dynamique :

import { connection } from 'next/server'

export default async function Component() {
  await connection()
  // les cookies, en-têtes et autres APIs dynamiques
  // opteront également pour le rendu dynamique, ce qui signifie
  // que cette variable d'environnement est évaluée au runtime
  const value = process.env.MY_VALUE
  // ...
}

Cela vous permet d'utiliser une seule image Docker qui peut être promue à travers plusieurs environnements avec différentes valeurs.

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 cela ne fonctionne pas avec le mode de sortie autonome. Nous recommandons plutôt d'adopter progressivement le routeur App si vous avez besoin de cette fonctionnalité.

Variables d'environnement de test

En plus des environnements development et production, il existe une 3ème option disponible : 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 faire de même avec un fichier .env.test pour l'environnement de test (bien que celui-ci ne soit pas aussi courant que les deux précédents). 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 pour vous.

Il y a une petite différence entre l'environnement de test, et les environnements development et production que vous devez 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 d'environnement par défaut en ignorant votre .env.local (qui est destiné à remplacer l'ensemble 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 sont destinés à être ignorés via .gitignore.

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

// Ce qui suit 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