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 sans préfixe 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 ce faire, 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 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 développement (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 les 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 d'environnement 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 les utiliser sur votre machine locale avec la commande suivante :

vercel env pull .env.local

Variables d'environnement de test

Outre les environnements de développement et de production, il existe une troisiè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 de test et les environnements de développement et de 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 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 pas .env.test.local, car .env*.local sont destinés à être ignorés 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.

// 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 répertoire /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 attribue automatiquement development lors de l'exécution de la commande next dev, ou production pour toutes les autres commandes.