Variables d'environnement
Catalogue des variables lues par @fraza/core, valeur par défaut, module qui les lit, effet quand elles sont absentes.
Toutes les variables lues par @fraza/core. La source de vérité est le catalogue src/core/doctor/env.js, où le core déclare ce qu'il sait lire, comme un module le fait dans son manifest.envVars. Une variable lue par le code sans y figurer fait échouer npm run build, et l'inverse aussi.
Le fichier .env.example est autre chose : le modèle de démarrage copié par @fraza/start dans un nouveau projet, réduit à ce qu'il faut remplir pour que le site tourne. Une variable peut donc exister ici sans figurer au modèle, et c'est le cas de tout ce qui a une valeur par défaut satisfaisante. Cette page les liste toutes.
Les valeurs se lisent dans plusieurs fichiers : le .env suivi par git, et .env.development.local pour ce qui est propre à une machine. L'ordre de priorité est celui de Next.js, décrit dans Fichiers d'environnement. Les variables de cette page s'écrivent sans suffixe de mode : la même clé sert en développement et en production, et c'est le fichier qui change.
Variables requises
Trois seulement. Leur absence fait sortir fraza-doctor en erreur, parce qu'aucune configuration légitime ne s'en passe :
| Variable | Sans elle |
|---|---|
FRAZA_DATABASE_URL | Aucun chemin de démarrage n'échappe à la base. |
FRAZA_ENCRYPTION_KEY | Le chiffrement applicatif lève à la première écriture. Remplie par npx @fraza/start. |
NEXT_PUBLIC_URL | La vérification CSRF refuse toute requête mutante, en silence. |
Le stockage, le courriel et les paiements restent optionnels : un projet sans téléversement, sans courriel transactionnel ou sans paiement est une configuration valide, et le diagnostic ne doit pas contredire la tuile de santé de l'admin, qui les affiche en avertissement et jamais en erreur.
Les variables FRAZA_* sont serveur uniquement. Seules les NEXT_PUBLIC_* existent dans le bundle navigateur. Un composant client qui lit une variable FRAZA_* reçoit undefined sans erreur, et le flag se comporte comme désactivé en silence. Voir Configuration de l'app.
Général
| Variable | Défaut | Lu par | Effet |
|---|---|---|---|
NEXT_PUBLIC_URL | — | appConfig, core/api | Requise. Origine publique du site. Base des liens de courriel, du canonical SEO, des assets de PDF, et de la vérification CSRF. |
FRAZA_NAME | Fraza | appConfig, core/email, SEO | Nom de l'application. Sert de %sitename% et de repli dans BaseLayout. |
FRAZA_LOGO_URL | — | appConfig | Logo affiché sur les pages publiques des modules et dans la barre de l'admin, en thème clair. URL absolue ou chemin servi depuis public/. Sans lui, l'admin affiche FRAZA_NAME. |
FRAZA_LOGO_URL_DARK | FRAZA_LOGO_URL | appConfig | Variante du logo en thème sombre, et sur la barre de l'admin quand le thème la garde foncée (chrome: 'dark'). Obligatoire pour un logo noir, qui disparaîtrait sinon. |
FRAZA_SITE_URL | — | appConfig | Destination du lien posé autour du logo. Sans elle, le logo n'est pas cliquable. |
Sans URL publique configurée, la vérification CSRF refuse les requêtes mutantes.
Les trois variables de marque sont lues par getPublicBrand() et servent de repli à tous les modules qui servent une page publique : un site qui signe partout sous la même enseigne les déclare une fois ici, un site qui partage ou facture sous une autre enseigne surcharge le module concerné. FRAZA_LOGO_URL est l'image du logo, à ne pas confondre avec FRAZA_EMAIL_LOGO_URL, qui est la destination du lien posé autour du logo des courriels. Sur une page publique, getPublicBrand().name ne retombe pas sur le défaut Fraza : sans FRAZA_NAME, la ligne de marque du pied de page ne s'affiche pas plutôt que de signer le site d'un nom inventé.
Régional
| Variable | Défaut | Lu par | Effet |
|---|---|---|---|
FRAZA_TIMEZONE | America/Toronto | appConfig, core/cron | Fuseau de l'application et des tâches planifiées. |
FRAZA_DATE_FORMAT | YYYY-MM-DD | appConfig | Format de date de l'application. |
FRAZA_CURRENCY | CAD | appConfig, core/payments | Devise par défaut, y compris pour les PaymentIntents. |
FRAZA_CURRENCY_SYMBOL | $ | appConfig | Symbole affiché. |
FRAZA_SUPPORT_EMAIL | — | core/email | Adresse affichée dans le pied de BaseLayout quand supportSection est actif. |
Proxy
| Variable | Défaut | Lu par | Effet |
|---|---|---|---|
FRAZA_TRUST_PROXY | false | shared/rate-limit | Nombre de reverse proxys de confiance devant l'application. Autorise la lecture des en-têtes de proxy pour déterminer l'IP du client. true vaut 1. |
À activer uniquement derrière un reverse proxy vérifié. Sans cette précaution, un client pourrait forger un X-Forwarded-For et contourner la limitation de débit. Quand l'IP reste inconnue, la limitation est suspendue et un avertissement est émis une fois.
La valeur doit correspondre au nombre exact de proxys traversés : true ou 1 derrière un seul proxy, 2 derrière Cloudflare puis nginx. Le core lit dans X-Forwarded-For l'entrée située à ce rang en partant de la droite, la seule que le client ne peut pas écrire. Toute autre valeur qu'un entier positif ou true laisse les en-têtes ignorés. Voir Rate limit.
Base de données
| Variable | Défaut | Lu par | Effet |
|---|---|---|---|
FRAZA_DATABASE_URL | — | core/database | Requise. URL de connexion PostgreSQL. |
FRAZA_DB_SSL_DISABLED | false | core/database | true désactive TLS entièrement. |
FRAZA_DB_SSL_NO_VERIFY | false | core/database | true garde TLS mais ne vérifie pas le certificat. |
FRAZA_DB_SSL_CA | — | core/database | Autorité de certification à épingler : PEM inline, ou chemin vers un fichier. |
L'ordre de résolution TLS est détaillé dans Base de données.
Les paramètres TLS portés par l'URL de connexion, ?sslmode=… en tête, sont retirés avant la connexion : ces trois variables restent la source de vérité. Le sslmode sert de valeur par défaut quand aucune n'est posée. Voir Paramètres TLS dans l'URL.
Chiffrement
| Variable | Défaut | Lu par | Effet |
|---|---|---|---|
FRAZA_ENCRYPTION_KEY | — | core/crypto | Requise. Clé maîtresse AES-256-GCM, 64 caractères hexadécimaux. Remplie par npx @fraza/start. |
Sur un projet monté à la main, générer la clé :
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"Changer cette clé rend illisible tout ce qui a été chiffré avec l'ancienne. Voir Chiffrement.
Stockage
| Variable | Défaut | Lu par | Effet |
|---|---|---|---|
FRAZA_STORAGE_PROVIDER | backblaze | core/storage | backblaze ou r2. |
FRAZA_STORAGE_ENDPOINT | — | core/storage | Backblaze : s3.<region>.backblazeb2.com. R2 : <accountId>.r2.cloudflarestorage.com. |
FRAZA_STORAGE_REGION | auto pour R2 | core/storage | Obligatoire pour Backblaze, optionnelle pour R2. |
FRAZA_STORAGE_BUCKET | — | core/storage | Nom du bucket. |
FRAZA_STORAGE_ACCESS_KEY | — | core/storage | Clé d'accès. |
FRAZA_STORAGE_SECRET_KEY | — | core/storage | Clé secrète. |
Un seul jeu de variables sert les deux providers.
Courriel
| Variable | Défaut | Lu par | Effet |
|---|---|---|---|
FRAZA_EMAIL_PROVIDER | resend | core/email | resend ou smtp. Toute autre valeur fait échouer l'envoi. |
FRAZA_EMAIL_FROM_ADDRESS | — | core/email | Adresse expéditeur par défaut. Nécessaire dès que le projet envoie des courriels. |
FRAZA_EMAIL_FROM_NAME | — | core/email | Nom affiché de l'expéditeur. |
FRAZA_EMAIL_LOGO | — | core/email | URL du logo dans BaseLayout. |
FRAZA_EMAIL_LOGO_URL | — | core/email | Destination du lien autour du logo. |
FRAZA_EMAIL_RESEND_APIKEY | — | core/email | Clé API Resend. Obligatoire quand le fournisseur est resend. |
FRAZA_EMAIL_SMTP_HOST | — | core/email | Hôte du relais. Obligatoire quand le fournisseur est smtp. |
FRAZA_EMAIL_SMTP_PORT | 587 | core/email | Port du relais. |
FRAZA_EMAIL_SMTP_USER | — | core/email | Identifiant. Vide pour un relais sans authentification. |
FRAZA_EMAIL_SMTP_PASSWORD | — | core/email | Mot de passe. Vide pour un relais sans authentification. |
FRAZA_EMAIL_SMTP_SECURE | déduit du port | core/email | true : TLS implicite dès la connexion. Sans valeur : true sur le port 465, false ailleurs. |
FRAZA_EMAIL_SMTP_TLS_NO_VERIFY | false | core/email | true : TLS actif, certificat non vérifié. |
Les variables FRAZA_EMAIL_FROM_* et FRAZA_EMAIL_LOGO* servent les deux fournisseurs. Le fournisseur actif est choisi par FRAZA_EMAIL_PROVIDER, et seules les variables de ce fournisseur sont lues.
Paiements
| Variable | Défaut | Lu par | Effet |
|---|---|---|---|
STRIPE_SECRET_KEY | — | core/payments | Clé secrète. Requise pour toute opération. |
STRIPE_PUBLISHABLE_KEY | — | core/payments | Clé publique, transmise au client. |
STRIPE_WEBHOOK_SECRET | — | core/payments | Secret de signature des webhooks. |
isEnabled() retourne false tant que les deux premières ne sont pas définies, ce qui permet de masquer l'UI de paiement plutôt que de laisser un appel échouer.
Authentification
| Variable | Défaut | Lu par | Effet |
|---|---|---|---|
FRAZA_AUTH_SESSION_COOKIE_NAME | fraza_session | appConfig | Nom du cookie de session. |
FRAZA_AUTH_REDIRECT_AFTER_LOGIN | / | features/auth | Destination après connexion. Le .env.example la fixe à /admin, qui est donc la valeur d'un projet généré ; sans la variable, le code retombe sur la racine du site. |
FRAZA_AUTH_REGISTRATION | true | appConfig, features/auth | false ferme les inscriptions publiques. Contrairement aux autres drapeaux, celui-ci est en opt-out : toute autre valeur, y compris l'absence de variable, laisse les inscriptions ouvertes. Voir Fermer les inscriptions. |
SEO
| Variable | Défaut | Lu par | Effet |
|---|---|---|---|
FRAZA_SEO | false | appConfig, @fraza/core/seo | true active la zone SEO des éditeurs et la génération des balises <head>. Absente du modèle de démarrage : un projet généré n'a donc pas de SEO tant que la variable n'est pas posée. |
FRAZA_SEO_SEPARATOR | - | SEO | Valeur du token %sep%. |
FRAZA_SEO_TITLE_TEMPLATE | %title% %sep% %sitename% | SEO | Gabarit appliqué quand un contenu n'a pas de titre SEO explicite. |
Admin
| Variable | Défaut | Lu par | Effet |
|---|---|---|---|
FRAZA_ADMIN_SITE_LINK | auto | appConfig, AdminLayout | true affiche toujours le bouton « Voir le site » de l'en-tête de l'admin, false le masque. Absente : affiché dès qu'un module de contenu public (Pages, Posts) est actif. |
C'est la seule variable du core à trois états. Sa lecture teste === 'true' puis === 'false', et toute autre valeur laisse la détection automatique décider : sans @fraza/module-pages ni @fraza/module-posts, le projet n'a pas de site public et le bouton reste masqué. Voir features/admin.
Développement
| Variable | Défaut | Lu par | Effet |
|---|---|---|---|
FRAZA_DEVKIT | false | appConfig | true expose /admin/devkit/components et /admin/devkit/icons, et affiche la tuile Liens rapides du tableau de bord. |
NEXT_TELEMETRY_DISABLED | — | Next.js | 1 désactive la télémétrie. |
Le devkit n'est jamais rendu quand le flag est absent ou différent de true.
Mises à jour et compatibilité
| Variable | Défaut | Lu par | Effet |
|---|---|---|---|
FRAZA_UPDATE_CHECK | true | fraza-modules sync, tuile update de l'admin | false éteint le rappel de mise à jour affiché au démarrage, et l'appel au registre de la tuile du tableau de bord. |
FRAZA_COMPAT_STRICT | false | initializeFraza | true fait échouer le boot sur toute incompatibilité de version core / module, et pas seulement quand le core est sous le plancher exigé. |
Le rappel de mise à jour est déjà muet hors terminal interactif et quand CI est définie : la variable ne sert qu'à l'éteindre sur un poste de développement. Voir fraza-update.
La tuile update du tableau de bord lit la même variable, mais elle n'a aucune de ces gardes : elle tourne précisément là où il n'y a pas de terminal. C'est donc le seul moyen d'empêcher le serveur de contacter le registre. Voir features/admin.
FRAZA_UPDATE_CHECK est la seule variable du core dont le défaut est actif. Sa lecture teste donc !== 'false', à l'inverse de FRAZA_DEVKIT ou FRAZA_SEO qui testent === 'true' : un projet dont le .env ne porte pas encore la variable garde le comportement par défaut.
FRAZA_COMPAT_STRICT ne change rien au comportement par défaut, qui reste d'avertir. Un core sous le plancher exigé par un module fait échouer le boot dans les deux cas : cette combinaison est réellement inexécutable.
Variables d'un module
Chaque module, @fraza/module-* ou @fraza-pro/module-*, déclare ses propres variables dans manifest.envVars. Leur effet est documenté module par module : Pages, Posts, Médias, Formulaires, Facturation, Fichiers, Rendez-vous. Une variable required: true absente produit un avertissement au boot, sans faire tomber le serveur : le module gère son propre repli. fraza-doctor, lui, la signale comme bloquante ; il reste muet sur les optionnelles absentes, dont la valeur par défaut suffit.
Un module porte en plus une variable d'activation de la forme FRAZA_MODULE_<NOM>, où <NOM> est le nom du paquet sans son préfixe : @fraza-pro/module-billing s'active par FRAZA_MODULE_BILLING. Installé mais non activé, il n'enregistre rien.
FRAZA_MODULE_MEDIAS=true