fraza-dev

fraza-dev sert au poste de développement, et à lui seul : un site déployé lance next build puis next start, jamais cette commande. Elle porte le script dev d'un projet créé par @fraza/start, et ses scripts services.

npm run dev               # fraza-dev
npm run services          # fraza-dev services up
npm run services:stop     # fraza-dev services down
npm run services:reset    # fraza-dev services reset

CommandesCopier le lien de la section

.env.local créé depuis .env.exampleCopier le lien de la section

Quand .env.local manque, fraza-dev le crée en copiant .env.example, avec un en-tête propre au fichier local et une FRAZA_ENCRYPTION_KEY neuve, en mode 0600. Un fichier existant n'est jamais remplacé. Une ligne FRAZA_ENCRYPTION_KEY= vide reçoit une clé ; une clé déjà posée n'est jamais touchée, puisque la changer rendrait illisible ce qui a été chiffré avec elle.

C'est ce qui permet à un collègue de cloner un projet et de le lancer sans rien saisir : .env.example porte les valeurs locales du compose.yaml. Voir Partager les variables d'un projet.

La création n'a lieu qu'ici, jamais dans fraza-modules sync ni au postinstall : sur la machine de build d'un site déployé, un .env.local tiré du modèle remplirait en silence, avec des valeurs locales, toute variable que la plateforme ne définit pas.

Les ports de la machineCopier le lien de la section

Chaque service reçoit un port libre au premier lancement, à partir de sa valeur habituelle, puis le garde. Deux projets tournent ainsi côte à côte, et les adresses de .env.local restent valides d'un démarrage à l'autre.

Un port choisi s'écrit dans .env.local, avec les adresses qui le portent : FRAZA_DATABASE_URL, FRAZA_TEST_DATABASE_URL, FRAZA_STORAGE_ENDPOINT, FRAZA_EMAIL_SMTP_PORT et NEXT_PUBLIC_URL. Seule une adresse locale change (localhost, 127.0.0.1, [::1]) : une variable qui vise un serveur partagé garde sa valeur.

NEXT_PUBLIC_URL suit le port du site parce que la vérification CSRF compare l'origine des requêtes à cette adresse : un next dev passé sur 3001 avec une adresse restée sur 3000 refuserait toutes les écritures. Une ligne NEXT_PUBLIC_URL vide reçoit http://localhost:<port>, pour la même raison. Si le port gardé est pris par un autre programme au démarrage, fraza-dev en choisit un autre et le dit. Un .env.development.local qui fixe NEXT_PUBLIC_URL passe avant .env.local : la commande avertit qu'il faut retirer la ligne.

Le cookie de sessionCopier le lien de la section

Les cookies ne dépendent pas du port : deux projets ouverts sur localhost sous le même fraza_session se déconnectent l'un l'autre. fraza-dev passe donc à next dev un nom propre au projet, tiré du nom du paquet : fraza_session_mon_site pour "name": "mon-site".

Il ne le fait que si aucun fichier d'environnement ne nomme le cookie (FRAZA_AUTH_SESSION_COOKIE_NAME), et seulement pour next dev. Une ligne vide ne nomme rien : le core la lit comme une variable absente. En production, le cookie reste fraza_session : chaque site y a son domaine, et le nom du projet n'a pas à se lire dans le navigateur.

Données hors du posteCopier le lien de la section

.env.local peut porter les valeurs de production : voir Développer avec les données de production. Au démarrage, fraza-dev lit les valeurs que verra next dev et avertit :

Rien n'est bloqué : travailler sur la production reste possible, il est seulement dit à voix haute.

Modifier un moduleCopier le lien de la section

Le core charge les modules une seule fois, au démarrage de next dev. Une route ou un menu modifié garde son ancienne version tant que le serveur tourne. fraza-dev le redémarre donc lui-même :

• Modules liés. Chaque module activé installé par file: ou npm link, dont le dossier réel est hors de node_modules, a son dist/ surveillé. Quand il change, next dev redémarre après une demi-seconde sans nouvelle écriture. Les premières secondes ne comptent pas : un tsup --watch qui démarre recompile tout, ce qui ne doit pas relancer un serveur qui vient de partir.
• Modules locaux. Les modules du dossier modules/ du projet sont compilés au démarrage, puis surveillés par un tsup --watch chacun. Une modification les recompile, ce qui redémarre le serveur. Voir fraza-modules.

Un module publié, installé depuis un registre, ne change pas pendant le développement : il n'est pas surveillé.

Un module lié dont le dossier réel est hors du projet demande turbopack.root dans next.config.mjs : voir Développer en local.

Les servicesCopier le lien de la section

services up lance docker compose --env-file .env.local up -d --wait : le compose.yaml lit ses ports dans .env.local, et la commande attend que PostgreSQL réponde. Elle crée ensuite le bucket de FRAZA_STORAGE_BUCKET sur le S3 local, par une requête signée comme celles du core, puis affiche les adresses.

Tout n'écoute que sur 127.0.0.1. Un mot de passe de base ou des clés de stockage n'auraient rien à protéger : rien n'est joignable depuis une autre machine. Pour la même raison, ces valeurs peuvent vivre dans .env.example, suivi par git, sans que fraza-doctor les compte comme des secrets.

Sans compose.yaml ou sans Docker, la commande s'arrête avec un message qui renvoie au guide Développer en local.

Ajouter le développement local à un projet existantCopier le lien de la section

npx fraza-dev init

Un projet créé par une version antérieure de @fraza/start n'a ni compose.yaml ni scripts services. fraza-update ne les ajoute pas : ils changent la façon de travailler du projet, qui peut avoir ses propres services. init les ajoute à la demande, et ne remplace jamais ce que le projet a déjà.

La commande dit ce qu'elle a fait, ligne par ligne. Relancée, elle n'a plus rien à faire. Ensuite : npm run services, npx fraza-db init, npm run dev.

NotesCopier le lien de la section

La commande ne charge pas les fichiers d'environnement dans son propre processus, contrairement aux autres CLI. Elle modifie .env.local, et les processus qu'elle lance (next dev, fraza-modules sync, fraza-db) lisent le fichier une fois écrit.

Ctrl+C arrête next dev, et la commande se termine avec lui.