Installation

Un projet Fraza se génère par une seule commande. Cette page couvre l'accès au registre, la génération et le premier démarrage.

PrérequisCopier le lien de la section

• Node.js 20 ou plus, imposé par le SDK Resend v6, livré quel que soit le fournisseur de courriel actif.
• PostgreSQL 14 ou plus, accessible depuis la machine.
• Un compte sur le registre https://registry.fraza.ca/, seulement pour les modules Pro.
• Un terminal bash, zsh ou PowerShell. Sous Windows, les commandes de cette documentation sont écrites pour PowerShell, pas pour l'invite cmd.exe.

1. Configurer le registreCopier le lien de la section

Le scope @fraza n'est pas sur npm public. Le pointer vers le registre Fraza, une seule fois par machine :

npm config set "@fraza:registry" https://registry.fraza.ca/

Le core, @fraza/start et les modules gratuits se lisent sans compte : aucune connexion n'est demandée. Seuls les modules Pro en exigent une, voir Modules Pro.

2. Générer le projetCopier le lien de la section

npx @fraza/start

La commande ne prend aucun argument : elle génère toujours dans le dossier courant. Se placer dans le dossier destiné au projet avant de la lancer, et le laisser vide. Le nom du dossier devient le nom du projet dans le package.json et dans le README.md.

La commande enchaîne :

1. create-next-app en JavaScript, avec Tailwind et l'App Router, puis suppression du app/ par défaut.
2. L'écriture d'un README.md au nom du projet et l'ajout des scripts dev, build, postinstall et audit. Les trois premiers sont préfixés par fraza-modules sync.
3. La copie des fichiers de gabarit : app/, components/, styles/, instrumentation.js, theme.js, jsconfig.json. Le next.config.mjs de create-next-app est conservé, car c'est lui qui branche Tailwind : seul devIndicators: false y est ajouté.
4. L'ajout de app/.fraza/ au .gitignore, et la mise en commentaire des règles .env et .npmrc : les deux fichiers sont suivis par git.
5. L'écriture du .npmrc du projet : les scopes @fraza et @fraza-pro vers le registre, et le token repris de ~/.npmrc s'il existe. Sans token, la commande l'indique (no token: free packages only) et poursuit : le token ne sert qu'aux modules Pro.
6. L'installation de @fraza/core.
7. La création du .env à partir du modèle du package, s'il n'existe pas déjà.

3. Configurer l'environnementCopier le lien de la section

Le .env généré vient de node_modules/@fraza/core/.env.example. Il faut le remplir avant de démarrer.

Le minimum pour lancer l'application :

NEXT_PUBLIC_URL=http://localhost:3000
FRAZA_NAME=Mon site
FRAZA_DATABASE_URL=postgres://user:password@localhost:5432/mon_projet

Le détail de chaque variable est dans Configuration.

Le .env est suivi par git par défaut, comme le .npmrc. Voir Secrets et git.

4. Initialiser la baseCopier le lien de la section

npx fraza-db test   # vérifier la connexion
npx fraza-db init   # créer les tables

  ◆ Initializing database...
  ✓ DB ready — 7 tables created, 0 skipped

La commande est idempotente : la relancer après chaque ajout de module ne casse rien.

5. DémarrerCopier le lien de la section

npm run dev

Tant qu'aucun compte n'existe, /auth affiche le formulaire de première configuration. Le compte qu'il crée reçoit le rôle admin et arrive connecté sur /admin. Créer ce compte immédiatement.

Modules ProCopier le lien de la section

Les modules Pro (@fraza-pro/module-billing, @fraza-pro/module-booking, @fraza-pro/module-drive) sont publiés sous le scope @fraza-pro, dont la lecture demande un compte sur le registre. Pointer ce scope vers le registre et se connecter, une seule fois par machine :

npm config set "@fraza-pro:registry" https://registry.fraza.ca/
npm login --registry=https://registry.fraza.ca/

Le token est déposé dans ~/.npmrc, le .npmrc du dossier personnel : %USERPROFILE%\.npmrc sous Windows. Il est lié à l'hôte du registre, pas au scope : la même ligne sert à @fraza et à @fraza-pro. Il n'expire pas dans le temps : il cesse de fonctionner seulement si le secret du serveur change, si le mot de passe est modifié, ou si le compte est révoqué.

Reprendre ensuite le token dans le .npmrc du projet. La commande se relance après chaque nouveau npm login :

npx fraza-key          # reprend le token de ~/.npmrc dans .npmrc
npx fraza-key status   # vérifie, token masqué

fraza-key ajoute aussi au .npmrc les lignes de scope qui lui manquent. Voir fraza-key.

Secrets et gitCopier le lien de la section

Le CLI laisse .env et .npmrc suivis par git : il commente leurs règles dans le .gitignore au lieu de les poser.

Le .npmrc en est la raison principale. Il pointe les scopes @fraza et @fraza-pro vers https://registry.fraza.ca/ : sans lui, npm ci cherche ces paquets sur npm public et échoue avec un 404. Si le CLI a trouvé un token dans ~/.npmrc (ou si npx fraza-key l'a ajouté), il le porte aussi en clair, même dans un projet sans module Pro. Avec des modules Pro, ce token est nécessaire au build. Sans token, le fichier ne contient aucun secret. Le token ne sert qu'à l'installation : aucun code d'exécution n'en a besoin (la tuile de mise à jour l'envoie s'il existe, mais s'en passe). En gardant le fichier dans le dépôt, la machine de build n'a rien à configurer : elle clone et lance npm ci. Le .env suit la même logique, ce qui évite de recopier les variables sur chaque environnement.

Cela suppose un dépôt privé. Les secrets applicatifs, et le token du registre s'il y en a un, sont en clair dans l'historique git, et un historique ne se nettoie pas facilement. Un dépôt qui deviendrait public, ou un accès en lecture accordé à un tiers, expose les deux.

Pour sortir ces fichiers de git, retirer le # des lignes correspondantes du .gitignore :

.env*
.npmrc

Il faut alors les fournir à la main sur chaque machine qui installe ou build le projet. La procédure est dans Déploiement.

DiagnostiquerCopier le lien de la section

Le site porte les correctifs de sécuritéCopier le lien de la section

C'est le package.json du site, et lui seul, qui peut épingler une version dans l'arbre de dépendances. npm n'honore le champ overrides que depuis la racine du projet installé : ni @fraza/core ni les modules ne peuvent le faire à la place du site. C'est pourquoi aucun package Fraza n'en déclare.

Le projet généré n'a pas de bloc overrides, et c'est l'état normal. Il ne s'en ajoute un que pour une faille qu'aucune mise à jour amont ne corrige. Le suivi se fait avec le script généré :

npm run audit   # npm audit --omit=dev

La première correction à tenter est toujours npm update next. La plupart des alertes d'un site Fraza viennent de l'arbre de Next.js et disparaissent avec une montée de version. Voir Sécurité.

Mettre à jour, plus tardCopier le lien de la section

npx fraza-update

Une seule commande pour le core, les modules et l'enchaînement qui suit. Voir Mettre à jour un projet.

Étape suivanteCopier le lien de la section

Le tour du propriétaire crée le premier compte, parcourt l'admin et met une première page en ligne.