Jump to content

Variables d'environnement

Create T3 App utilise Zod↗ pour valider votre variables d’environnement a l’exĂ©cution et a la gĂ©nĂ©ration de l’application en fournissant des fichiers supplĂ©mentaires dans le rĂ©pertoire env:

📁 src/env

┣ 📄 client.mjs

┣ 📄 schema.mjs

┣ 📄 server.mjs

Le contenu de ses fichiers peut sembler terrifiant de prime abord, mais ne vous inquiĂ©tez pas, ce n’est pas aussi compliquĂ© qu’il y paraĂźt. Examinons-les un par un et parcourons le processus d’ajout de variables d’environnement.

TLDR; Si vous dĂ©sirez ajouter une nouvelle variable d’environnement, vous devez l’ajouter autant dans votre fichier .env et la dĂ©finir dans le validateur: env/schema.mjs.

schema.mjs

C’est le fichier que vous allez modifier. Il contient deux schĂ©mas, l’un est pour les variables d’environnement cĂŽtĂ© serveur et le second est pour le cĂŽtĂ© client connu sous l’objet clientEnv.

env/schema.mjs
export const serverSchema = z.object({
  // DATABASE_URL: z.string().url(),
});

export const serverEnv = {
  // DATABASE_URL: process.env.DATABASE_URL,
};

export const clientSchema = z.object({
  // NEXT_PUBLIC_WS_KEY: z.string(),
});

export const clientEnv = {
  // NEXT_PUBLIC_WS_KEY: process.env.NEXT_PUBLIC_WS_KEY,
};

Schéma Serveur

DĂ©finissez votre schĂ©ma de variables d’environnement du cĂŽtĂ© serveur ici.

Faites attention à ne pas préfixer vos clefs avec NEXT_PUBLIC. La validation échouera si vous le faites, afin de vous aider à détecter une configuration non valide.

Schéma Client

DĂ©finissez votre schĂ©ma de variables d’environnement du cĂŽtĂ© client ici.

Pour les exposer au client, vous devez les préfixer avec NEXT_PUBLIC. La validation échouera si vous ne le faites pas, afin de vous aider à détecter une configuration non valide.

Objet clientEnv

DĂ©structurez process.env ici.

Nous avons besoin d’un objet JavaScript avec lequel nous pouvons analyser nos schĂ©mas Zod et en raison de la façon dont Next.js gĂšre les variables d’environnement, vous ne pouvez pas dĂ©structurez process.env comme un objet rĂ©gulier. Du coup nous devons le faire manuellement.

TypeScript vous aidera à vous assurer que vous avez entré les clés dans clientEnv ainsi que clientSchema.

// ❌ Cela ne fonctionne pas, nous devons le dĂ©structurer manuellement
const schema = z.object({
  NEXT_PUBLIC_WS_KEY: z.string(),
});

const validated = schema.parse(process.env);

server.mjs & client.mjs

C’est ici que la validation se fait et l’export des objets valider. Vous ne devriez pas avoir besoin de modifier ces fichiers.

Utilisation de variables d’environnement

Lorsque vous souhaitez utiliser vos variables d’environnement, vous pouvez les importer depuis env/client.mjs ou env/server.mjs selon l’endroit oĂč vous souhaitez les utiliser :

pages/api/hello.ts
import { env } from "../../env/server.mjs";

// `env` est totalement typesafe et fournit une autocomplétion
const dbUrl = env.DATABASE_URL;

.env.example

Vu que par dĂ©faut le fichier .env n’est pas commiter dans votre dĂ©pĂŽt de version, nous avons inclus le fichier .env.example, dans lequel vous pouvez ajouter une copie du contenu de votre .env avec les informations secrĂštes retirĂ©es. Ce n’est pas obligatoire, mais nous recommandons de garder le fichier example a jour, et ce, afin de rendre le dĂ©marrage des contributeurs Ă  votre projet, facile.

Certains frameworks et outils de conception, comme Next.js, suggĂšre que vous gardez vos secret dans un fichier .env.local et de commiter votre fichier .env dans votre projet. Ce n’est pas recommandĂ©, car vous pourriez accidentellement commiter les secret de votre projet. A la place, nous recommandons que vous gardiez vos secret dans le fichier .env, et surtout d’etre sur que le fichier .env se retrouve dans votre .gitignore et de seulement commiter le .env.example de votre projet.

Ajout des variables d’environnement

Pour ĂȘtre sur que la gĂ©nĂ©ration de l’application ne puisse jamais finir sans les variables d’environnements nĂ©cessaire Ă  votre projet, vous devez les ajouter dans deux fichiers :

📄 .env: Entrez votre variable d’environnement comme vous le feriez normalement dans un fichier .env, c’est-à-dire CLEF=VALEUR

📄 schema.mjsAjoutez la logique de validation appropriĂ©e pour la variable d’environnement en dĂ©finissant un schĂ©ma Zod, par ex. CLEF: z.string()

Facultativement, vous pouvez Ă©galement garder .env.example Ă  jour :

📄 .env.example: Entrez votre variable d’environnement,assurez-vous de ne pas inclure la valeur si elle est secrùte, par ex. CLEF=VALEUR ou CLEF=

Exemple

Je veux ajouter le jeton de l’API Twitter en tant que variable d’environnement cĂŽtĂ© serveur

  1. Ajouter la variable d’environnement dans .env:
TWITTER_API_TOKEN=1234567890
  1. Ajouter la variable d’environnement dans schema.mjs:
export const serverSchema = z.object({
  // ...
  TWITTER_API_TOKEN: z.string(),
});

export const serverEnv = {
  // ...
  TWITTER_API_TOKEN: process.env.TWITTER_API_TOKEN,
};

NOTE: Une chaüne vide est toujours une chaüne, donc z.string() acceptera une chaüne vide comme valeur valide. Si vous voulez vous assurer que la variable d’environnement n’est pas vide, vous pouvez utiliser z.string().min(1).

  1. facultatif : ajoutez la variable d’environnement à .env.example, mais n’incluez pas le jeton
TWITTER_API_TOKEN=