Le CLI crée un projet Next.js avec @fraza/core déjà branché : administration, comptes, site public et variables d'environnement prêtes à remplir.
npx @fraza/start
Documentation · Installation · Structure du projet
[!WARNING] Fraza est en version
0.x. La structure des projets générés peut encore changer d'une version mineure à l'autre.
Points forts
- Aucune question. Le CLI lance
create-next-appavec toutes ses options : JavaScript, Tailwind CSS, ESLint, App Router, alias@/*. - Rien à configurer pour commencer.
@fraza/corevient de npmjs, sans compte, et.env.localsort avec sa clé de chiffrement déjà générée. - Sans dégât. Les prérequis sont vérifiés avant toute écriture : un échec laisse le dossier tel qu'il était.
- Un projet qui reste le vôtre. Pages publiques, pages d'erreur, thème et blocs sont des gabarits copiés dans le projet, à modifier librement.
Prérequis
- Node.js 20.12 ou plus.
- Docker, pour les services locaux du
compose.yaml: PostgreSQL, S3 et boîte de réception. Sans Docker, une base PostgreSQL 14 ou plus. - Un dossier vide. Seules les métadonnées d'éditeur ou de git y sont tolérées :
.git,.vscode,.idea,.DS_Store,LICENSE.
Utilisation
Dans le dossier du nouveau projet :
npx @fraza/start
Puis démarrez les services locaux, créez les tables et lancez le site :
npm run services
npx fraza-db init
npm run dev
.env.local est déjà rempli pour les services du compose.yaml : il n'y a rien à saisir. npm run services choisit des ports libres pour cette machine et les y écrit. Ouvrez l'adresse affichée par npm run dev, d'habitude http://localhost:3000/auth, pour créer le premier compte, qui reçoit le rôle admin. Les courriels du site arrivent dans la boîte de réception affichée par npm run services.
Sans Docker, faites viser FRAZA_DATABASE_URL vers votre PostgreSQL dans .env.local, et posez FRAZA_EMAIL_PROVIDER=log pour lire les courriels dans le terminal. Voir Développer en local.
Un collègue qui clone le projet lance les mêmes trois commandes : npm run dev crée son .env.local depuis .env.example.
Ce que fait le CLI
- Crée le projet avec
create-next-app16.4.3, la version de Next contre laquelle le core est validé. - Remplace le dossier
app/de Next par les gabarits Fraza : administration, authentification, API, page d'accueil, pages d'erreur, gabarits de page, exemples de blocs,theme.js,instrumentation.jsetjsconfig.json. - Ajoute les scripts
dev(fraza-dev, qui lancefraza-modules syncpuisnext dev),buildetpostinstall(fraza-modules sync). - Masque l'indicateur de développement de Next dans
next.config.mjs. - Ajoute
!.env.exampleetapp/.fraza/au.gitignore, en gardant la règle.env*de Next. - Ajoute un bloc Fraza à l'
AGENTS.md, qui renvoie un agent à la documentation livrée dansnode_modules/@fraza/core/dist/docs/. - Écrit le
.npmrcdu projet, sans jeton. - Installe
@fraza/core. - Crée
.env.example, suivi par git, avec les valeurs locales ducompose.yaml, et.env.local, ignoré par git, la même copie avecFRAZA_ENCRYPTION_KEYgénérée. - Lance
npx fraza-dev initdu core, qui ajoute le développement local : lecompose.yamldes services, les scriptsservices,services:stop,services:resetettest, un premier test danstest/, et ledistDirdu serveur de test dansnext.config.mjs. La même commande sert à un projet créé par une version antérieure.
Variables d'environnement
| Fichier | Contenu | Suivi par git |
|---|---|---|
.env.example | La liste des variables, avec les valeurs locales du compose.yaml et aucune valeur secrète. Une variable ajoutée par le projet y entre aussi. | Oui |
.env.local | Les valeurs de cette machine : ports locaux, clé de chiffrement, clés de test. | Non |
En production, les variables se saisissent dans la plateforme d'hébergement, jamais dans un fichier suivi par git. Partez de .env.example pour la liste.
Copiez FRAZA_ENCRYPTION_KEY telle quelle depuis .env.local, et ne la changez jamais. Tout ce que le site chiffre en base l'est avec cette clé : une nouvelle clé rend ces données illisibles. Gardez-en une copie dans le coffre de l'équipe, hors du serveur.
La liste complète est dans Variables d'environnement.
Modules Pro
Le .npmrc écrit par le CLI ne contient qu'une ligne :
@fraza-pro:registry=https://registry.fraza.ca/
Il reste suivi par git, et la machine de build sait où chercher les modules Pro. Pour en installer un, créez le projet dans la section « Projets » de votre espace client sur compte.fraza.ca, puis collez dans le .npmrc la ligne de sa clé, montrée une seule fois :
@fraza-pro:registry=https://registry.fraza.ca/
//registry.fraza.ca/:_authToken=fzk_…
Pas de npm login : la clé suffit, et comme le .npmrc est suivi par git, la machine de build installe les modules Pro elle aussi. La clé est en clair dans le dépôt : traitez-la comme une clé de licence propre au projet. Une clé régénérée depuis l'espace client coupe l'ancienne.
Pages d'erreur et de chargement
Les pages d'erreur et de chargement réexportent chacune un composant du core. Celles de l'administration suivent le core et n'ont pas à changer. Celles du site public (app/(public)/error.js, la page 404) sont des gabarits : remplacez le réexport par un composant du projet.
Le site public n'a pas de loading.js, et ne doit pas en recevoir. Son Suspense enverrait la réponse avec le statut 200 avant que la page sache si le contenu existe : toute URL inconnue répondrait 200 au lieu de 404. Une page qui veut un état de chargement pose son propre Suspense, après l'appel éventuel à notFound().
Un projet généré par une version plus ancienne remet ces fichiers à jour avec npx fraza-doctor --fix.
Contribuer
Les tests, l'installation d'un core local et la publication sont décrits dans CONTRIBUTING.md.
Licence
MIT. Copyright (c) 2026 Fraza. Voir LICENSE. Les dépendances tierces sont listées dans THIRD-PARTY-NOTICES.md.
Ce paquet fait partie de Fraza Libre.