Déployez plus sereinement : Comment la validation des variables d'environnement prévient les catastrophes (cas de NextJs) !

Les variables d’environnement sont le socle de configuration de nos applications : des URLs d’API critiques aux tokens de sécurité sensibles, en passant par les chaînes de connexion aux bases de données. Une seule variable mal configurée peut provoquer des conséquences désastreuses : crashs imprévus, comportements imprévisibles, ou même corruption de données.

Est-ce que cela vous est déjà arrivé ?
Vous venez de terminer une fonctionnalité, vous la déployez pour que vos utilisateurs, PO ou collègue puisse la tester… et boum : une erreur surgit ou une partie de votre application ne fonctionne pas. Vous perdez de précieuses minutes (voire des heures) à chercher la cause, pour finalement découvrir qu’il s’agissait simplement… d’une variable d’environnement manquante ou mal configurée.

Frustrant, n’est-ce pas ? 😤

Et si je vous disais que ce genre de mésaventure est parfaitement évitable ?

🎯 La solution : valider vos variables d’environnement avant même que votre application ne démarre

Le principe est simple :

1. Écrire un validateur pour vos variables d’environnement. Il s’assurera que toutes les variables nécessaires sont bien définies et conformes.

2. Déterminer le bon moment pour exécuter cette validation : lors du push (via un hook Git), au démarrage du serveur, ou encore juste avant le build.

Dans cet article, nous allons voir un exemple concret avec Next.js, en utilisant la bibliothèque envalid.

Notre objectif : faire échouer le build automatiquement si une variable critique est absente ou invalide.

De cette manière, vos erreurs de config seront détectées immédiatement lors du déploiement sur un serveur comme Coolify ou Vercel — et non en prod, face à vos utilisateurs.

Let’s go 🚀
On va commencer par installer la lib envalid

npm install envalid
# ou
pnpm add envalid

Étape 1 : Créer un fichier env.mjs

C’est ici qu’on validera et exposera toutes les variables d’environnement :

// env.mjs
import { cleanEnv, str, url, port } from 'envalid';

export const env = cleanEnv(process.env, {
  NEXT_PUBLIC_API_URL: url(),
  NEXT_PUBLIC_ANALYTICS_ID: str(),
  DATABASE_URL: str(),
  PORT: port({ default: 3000 }),
  NODE_ENV: str({ choices: ['development', 'production', 'test'] }) // listez vos envorenements
});

✅ Si une variable est absente ou invalide, une erreur est levée immédiatement.

Étape 2 : Importer env.mjs dans next.config.mjs

// next.config.mjs
import './env.mjs';

const nextConfig = {
  reactStrictMode: true,
  images: {
    domains: [
      'images.unsplash.com',
      'example.com'
    ]
  }
};

export default nextConfig;

✅ La validation est exécutée très tôt, avant même le build de l’app.

Lorsqu’une variable d’environnement manquera ce genre d’erreur sera levée

Conclusion

Les bugs liés aux variables d’environnement sont pénibles, mais totalement évitables. En les validant proprement avec envalid, tu rends ton app plus robuste et tes déploiements bien plus sereins.

Happy coding ! 🚀