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
.
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 :
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.mjs
Ajoutez 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
- Ajouter la variable dâenvironnement dans
.env
:
TWITTER_API_TOKEN=1234567890
- 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)
.
- facultatif : ajoutez la variable dâenvironnement Ă
.env.example
, mais nâincluez pas le jeton
TWITTER_API_TOKEN=