@fraza/start 0.3.4 → 0.3.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +13 -1
- package/README.md +53 -121
- package/bin/version.js +1 -1
- package/changelog.json +44 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,7 +4,19 @@ Historique des versions publiées de `@fraza/start`.
|
|
|
4
4
|
|
|
5
5
|
Ce fichier est généré par `fraza-module changelog` à partir des messages de commit. Ne pas le modifier à la main.
|
|
6
6
|
|
|
7
|
-
## 0.3.
|
|
7
|
+
## 0.3.6 (2026-10-25)
|
|
8
|
+
|
|
9
|
+
### Documentation
|
|
10
|
+
|
|
11
|
+
- add command to start project (5edd2f6)
|
|
12
|
+
|
|
13
|
+
## 0.3.5 (2026-10-25)
|
|
14
|
+
|
|
15
|
+
### Ajouts
|
|
16
|
+
|
|
17
|
+
- **README** : overhaul documentation and add installation instructions (e1f31df)
|
|
18
|
+
|
|
19
|
+
## 0.3.4 (2026-10-24)
|
|
8
20
|
|
|
9
21
|
### Documentation
|
|
10
22
|
|
package/README.md
CHANGED
|
@@ -1,170 +1,102 @@
|
|
|
1
|
-
|
|
1
|
+
<img src="https://docs.fraza.ca/readme/start.png" alt="Fraza, un projet en une commande" width="100%">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
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.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
5
|
+
```sh
|
|
6
|
+
npx @fraza/start
|
|
7
|
+
```
|
|
7
8
|
|
|
8
|
-
|
|
9
|
+
[Documentation](https://docs.fraza.ca/docs) · [Installation](https://docs.fraza.ca/docs/demarrage/installation) · [Structure du projet](https://docs.fraza.ca/docs/demarrage/structure-du-projet)
|
|
9
10
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
- Le registre npm joignable, sans compte : `@fraza/core` est publié sur npmjs.
|
|
11
|
+
> [!WARNING]
|
|
12
|
+
> Fraza est en version `0.x`. La structure des projets générés peut encore changer d'une version mineure à l'autre.
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## Points forts
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
- **Aucune question.** Le CLI lance `create-next-app` avec toutes ses options : JavaScript, Tailwind CSS, ESLint, App Router, alias `@/*`.
|
|
17
|
+
- **Rien à configurer pour commencer.** `@fraza/core` vient de npmjs, sans compte, et `.env.local` sort avec sa clé de chiffrement déjà générée.
|
|
18
|
+
- **Sans dégât.** Les prérequis sont vérifiés avant toute écriture : un échec laisse le dossier tel qu'il était.
|
|
19
|
+
- **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.
|
|
17
20
|
|
|
18
|
-
|
|
21
|
+
## Prérequis
|
|
19
22
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
4. masque l'indicateur de développement de Next dans `next.config.mjs` ;
|
|
24
|
-
5. ajoute au `.gitignore` les lignes `!.env.example` et `app/.fraza/`, en gardant la règle `.env*` de Next ;
|
|
25
|
-
6. ajoute un bloc Fraza à l'`AGENTS.md` du projet ;
|
|
26
|
-
7. écrit le `.npmrc` du projet : le scope `@fraza-pro` vers `https://registry.fraza.ca/`, sans jeton ;
|
|
27
|
-
8. installe `@fraza/core` ;
|
|
28
|
-
9. crée `.env.example`, copie du modèle du core suivie par git, et `.env.local`, la même copie remplie pour cette machine (`FRAZA_ENCRYPTION_KEY` générée, `NEXT_PUBLIC_URL` locale), ignorée par git. L'en-tête de `.env.local` est réécrit pour ce fichier : celui du modèle décrit `.env.example`.
|
|
23
|
+
- Node.js 20.12 ou plus.
|
|
24
|
+
- Une base PostgreSQL 14 ou plus.
|
|
25
|
+
- Un dossier vide. Seules les métadonnées d'éditeur ou de git y sont tolérées : `.git`, `.vscode`, `.idea`, `.DS_Store`, `LICENSE`.
|
|
29
26
|
|
|
30
27
|
## Utilisation
|
|
31
28
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
Les paquets `@fraza` sont publiés sur npmjs : aucune configuration ni connexion n'est demandée. Dans le dossier du nouveau projet :
|
|
29
|
+
Dans le dossier du nouveau projet :
|
|
35
30
|
|
|
36
31
|
```bash
|
|
37
32
|
npx @fraza/start
|
|
38
33
|
```
|
|
39
34
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
Le CLI écrit deux fichiers à partir du modèle du core, qui ne porte que le nécessaire au démarrage :
|
|
35
|
+
Renseignez au moins `FRAZA_DATABASE_URL` dans `.env.local`. `npx fraza-doctor` liste les variables qui manquent vraiment. Créez ensuite les tables et démarrez :
|
|
43
36
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
Remplissez `.env.local`. `FRAZA_ENCRYPTION_KEY` y est déjà : le CLI génère 32 octets aléatoires en hexadécimal. Next.js et les CLI `fraza-*` lisent `.env.local` d'eux-mêmes.
|
|
37
|
+
```bash
|
|
38
|
+
npx fraza-db init
|
|
39
|
+
npm run dev
|
|
40
|
+
```
|
|
50
41
|
|
|
51
|
-
|
|
42
|
+
Ouvrez `http://localhost:3000/auth` pour créer le premier compte, qui reçoit le rôle `admin`.
|
|
52
43
|
|
|
53
|
-
|
|
44
|
+
## Ce que fait le CLI
|
|
54
45
|
|
|
55
|
-
|
|
46
|
+
1. Crée le projet avec `create-next-app` 16.3.8, la version de Next contre laquelle le core est validé.
|
|
47
|
+
2. 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.js` et `jsconfig.json`.
|
|
48
|
+
3. Ajoute les scripts `dev`, `build` et `postinstall`, qui lancent `fraza-modules sync`.
|
|
49
|
+
4. Masque l'indicateur de développement de Next dans `next.config.mjs`.
|
|
50
|
+
5. Ajoute `!.env.example` et `app/.fraza/` au `.gitignore`, en gardant la règle `.env*` de Next.
|
|
51
|
+
6. Ajoute un bloc Fraza à l'`AGENTS.md`, qui renvoie un agent à la documentation livrée dans `node_modules/@fraza/core/dist/docs/`.
|
|
52
|
+
7. Écrit le `.npmrc` du projet, sans jeton.
|
|
53
|
+
8. Installe `@fraza/core`.
|
|
54
|
+
9. Crée `.env.example`, suivi par git, et `.env.local`, ignoré par git, avec `FRAZA_ENCRYPTION_KEY` générée et `NEXT_PUBLIC_URL` locale.
|
|
56
55
|
|
|
57
|
-
|
|
56
|
+
## Variables d'environnement
|
|
58
57
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
58
|
+
| Fichier | Contenu | Suivi par git |
|
|
59
|
+
|---|---|---|
|
|
60
|
+
| `.env.example` | La liste des variables, sans aucune valeur secrète. Une variable ajoutée par le projet y entre aussi. | Oui |
|
|
61
|
+
| `.env.local` | Les valeurs de cette machine : base de données, stockage, courriel, clés. | Non |
|
|
62
62
|
|
|
63
|
-
|
|
63
|
+
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.
|
|
64
64
|
|
|
65
|
-
|
|
65
|
+
**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 hors du serveur.
|
|
66
66
|
|
|
67
|
-
|
|
67
|
+
La liste complète est dans [Variables d'environnement](https://docs.fraza.ca/docs/reference/configuration/variables-d-environnement).
|
|
68
68
|
|
|
69
|
-
##
|
|
69
|
+
## Modules Pro
|
|
70
70
|
|
|
71
|
-
Le
|
|
71
|
+
Le `.npmrc` écrit par le CLI ne contient qu'une ligne :
|
|
72
72
|
|
|
73
73
|
```ini
|
|
74
74
|
@fraza-pro:registry=https://registry.fraza.ca/
|
|
75
75
|
```
|
|
76
76
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
Chaque version gratuite est aussi publiée sur `https://registry.fraza.ca/`, en copie de secours. Si npmjs devient indisponible, la page « Registre de secours » de la documentation du core explique comment y basculer.
|
|
80
|
-
|
|
81
|
-
Les modules Pro (`@fraza-pro/module-*`) demandent un jeton. Connectez-vous au registre, puis lancez `fraza-key`, qui écrit le jeton dans le `.npmrc` du projet :
|
|
77
|
+
Sans secret, il reste suivi par git, et la machine de build sait où chercher les modules Pro. Pour en installer un, connectez-vous au registre puis lancez `fraza-key`, qui ajoute le jeton au `.npmrc` :
|
|
82
78
|
|
|
83
79
|
```bash
|
|
84
80
|
npm login --registry=https://registry.fraza.ca/
|
|
85
81
|
npx fraza-key
|
|
86
82
|
```
|
|
87
83
|
|
|
88
|
-
Le jeton est alors en clair dans un fichier suivi par git : traitez-le comme une clé de licence propre au projet
|
|
84
|
+
Le jeton est alors en clair dans un fichier suivi par git : traitez-le comme une clé de licence propre au projet. Voir [fraza-key](https://docs.fraza.ca/docs/reference/cli/fraza-key).
|
|
89
85
|
|
|
90
|
-
## Pages d'erreur
|
|
86
|
+
## Pages d'erreur et de chargement
|
|
91
87
|
|
|
92
|
-
|
|
88
|
+
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.
|
|
93
89
|
|
|
94
|
-
|
|
95
|
-
|---|---|---|
|
|
96
|
-
| `app/(admin)/admin/error.js` | `@fraza/core/features/admin/error` | Erreur au rendu d'une page de l'administration. |
|
|
97
|
-
| `app/(admin)/admin/not-found.js` | `@fraza/core/features/admin/not-found` | Page introuvable de l'administration, dans la coquille. |
|
|
98
|
-
| `app/(admin)/admin/[...admin]/layout.js` | `@fraza/core/features/admin/page-layout` | Vérifie la fiche et la permission d'une page d'admin avant que la réponse parte. |
|
|
99
|
-
| `app/(admin)/admin/[...admin]/loading.js` | `@fraza/core/features/admin/loading` | Chargement d'une page de l'administration. |
|
|
100
|
-
| `app/(public)/error.js` | `@fraza/core/shared/public/error` | Erreur au rendu d'une page du site public. |
|
|
101
|
-
| `app/global-error.js` | `@fraza/core/shared/global-error` | Erreur du layout racine lui-même. |
|
|
102
|
-
|
|
103
|
-
Ceux de l'administration suivent le core et n'ont pas à changer. Ceux du site public sont des gabarits, comme la page 404 : remplacez le réexport par un composant du projet pour leur donner l'allure du site.
|
|
104
|
-
|
|
105
|
-
Le site public n'a pas de `loading.js`, et ne doit pas en recevoir : il entourerait la page attrape-tout d'un `Suspense`, la réponse partirait avec le statut 200 avant que la page sache si le contenu existe, et 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()`.
|
|
106
|
-
|
|
107
|
-
Pour la même raison, le `loading.js` de l'administration vit sous `app/(admin)/admin/[...admin]/`, et non dans `app/(admin)/admin/` : à ce niveau, son `Suspense` entourerait aussi le layout de `[...admin]`, qui décide du 404 d'une page inconnue ou refusée. Un projet généré avant ce changement lance `npx fraza-doctor --fix`, qui déplace le fichier et ajoute les deux autres.
|
|
90
|
+
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()`.
|
|
108
91
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
Le CLI ajoute un bloc `fraza-agent-rules` à l'`AGENTS.md` créé par Next.js. Il indique qu'il s'agit d'un projet Fraza et renvoie à la documentation livrée dans le paquet, sous `node_modules/@fraza/core/dist/docs/`. Un agent qui ouvre le dépôt lit ainsi la documentation de la version exacte installée, sans accès réseau.
|
|
112
|
-
|
|
113
|
-
Le contenu du bloc est dans [`bin/agents-block.md`](./bin/agents-block.md). Il est délimité par ses propres marqueurs : `next dev` ne réécrit que le bloc `nextjs-agent-rules` et laisse celui-ci intact.
|
|
92
|
+
Un projet généré par une version plus ancienne remet ces fichiers à jour avec `npx fraza-doctor --fix`.
|
|
114
93
|
|
|
115
94
|
## Contribuer
|
|
116
95
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
La variable `FRAZA_START_CORE_SPEC` remplace la cible du `npm install` du core. Elle vaut `@fraza/core` par défaut. Elle sert aux tests de bout en bout, pour installer un core local au lieu de la version publiée :
|
|
120
|
-
|
|
121
|
-
```bash
|
|
122
|
-
cd ../core
|
|
123
|
-
npm pack
|
|
124
|
-
cd ../projet-test
|
|
125
|
-
FRAZA_START_CORE_SPEC=../core/fraza-core-0.1.0.tgz npx ../start
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
En PowerShell, définissez la variable avant de lancer le CLI :
|
|
129
|
-
|
|
130
|
-
```powershell
|
|
131
|
-
$env:FRAZA_START_CORE_SPEC = "../core/fraza-core-0.1.0.tgz"
|
|
132
|
-
npx ../start
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
Toute cible acceptée par `npm install` convient : une archive `.tgz`, un dossier ou une version précise. Cette variable sert au développement de Fraza. Un projet normal n'en a pas besoin.
|
|
136
|
-
|
|
137
|
-
### Vérifier les gabarits
|
|
138
|
-
|
|
139
|
-
`npm run check:contract` vérifie que `templates/` suit le contrat d'amorçage déclaré par le core, et que la version de `create-next-app` épinglée dans `bin/project.js` est un correctif de la version mineure `packages.next.tested` du `supported.json` du core, au moins égal à celle-ci. Le script cherche un core buildé dans `../core`, puis dans `node_modules/@fraza/core`.
|
|
140
|
-
|
|
141
|
-
`npm run build` lance cette vérification, puis régénère `THIRD-PARTY-NOTICES.md`.
|
|
142
|
-
|
|
143
|
-
### Lancer les tests
|
|
144
|
-
|
|
145
|
-
```bash
|
|
146
|
-
npm test
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
Les étapes de génération vivent dans `bin/project.js`, sans effet de bord à l'import. Les tests de `test/` les appellent une par une sur un dossier temporaire, avec `node:test` : aucune dépendance à installer.
|
|
150
|
-
|
|
151
|
-
`test/templates.test.js` lit les imports des gabarits, sans core installé. Le projet atteint `@fraza/core` par ses sous-chemins, jamais par la racine, et `instrumentation.js` démarre par `@fraza/core/init`. Les pages du site public, les gabarits de page et les `render.js` des blocs importent chaque composant et chaque icône par son propre sous-chemin (`@fraza/core/shared/components/Button`, `@fraza/icons/CheckIcon`) : les barrels `shared/components` et `@fraza/icons` tireraient tout le jeu dans le code envoyé au visiteur.
|
|
152
|
-
|
|
153
|
-
### Publier
|
|
154
|
-
|
|
155
|
-
Le paquet suit la procédure de publication du core : voir [Publication](https://docs.fraza.ca/docs/contribution/publication). Ses outils sont ceux de `fraza-module`, lancés par `scripts/fraza-module.js` sur le core buildé de `../core`, puis de `node_modules/@fraza/core`. Le paquet n'installe pas le core : le déclarer en dépendance figerait dans le lockfile un core publié, qui peut ne pas encore porter ces outils.
|
|
156
|
-
|
|
157
|
-
| Script | Rôle |
|
|
158
|
-
|---|---|
|
|
159
|
-
| `npm run sync:version` | Recopie `package.json#version` dans `bin/version.js`, que le CLI affiche au lancement. |
|
|
160
|
-
| `npm run build:changelog` | Régénère `CHANGELOG.md`, `changelog.json` et `package.json#fraza`, avec les gabarits changés (`templateChanged`). |
|
|
161
|
-
| `npm run release` | Vérifie le paquet, monte sa version (`patch` par défaut), committe `chore: bump version to X.Y.Z`, le publie sur npmjs puis sur `registry.fraza.ca`, puis pose l'étiquette `v<version>` et la pousse (`fraza-module release`). |
|
|
162
|
-
| `npm run release:publish` | Publie la version actuelle sur chaque registre où elle manque (`fraza-module publish`). Sert à terminer une publication interrompue. |
|
|
163
|
-
|
|
164
|
-
Comme pour le core, `npm run release -- minor` monte la version mineure, pour un changement cassant en `0.x`. La commande liste les ruptures en attente depuis la dernière version et avertit si `patch` ne les annonce pas, puis publie quand même le niveau demandé. Avant toute écriture, elle fait aussi un `git fetch` et refuse une branche en retard sur le dépôt distant. `npm run release -- --dry-run` fait ces vérifications et affiche la version calculée sans rien écrire ni publier. `scripts/fraza-module.js` transmet ces arguments au core buildé de `../core`, qui doit donc porter la commande `release`.
|
|
96
|
+
Les tests, l'installation d'un core local et la publication sont décrits dans [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
165
97
|
|
|
166
98
|
## Licence
|
|
167
99
|
|
|
168
|
-
|
|
100
|
+
MIT. Copyright (c) 2026 HYKO. Voir [LICENSE](./LICENSE). Les dépendances tierces sont listées dans [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md).
|
|
169
101
|
|
|
170
|
-
Ce paquet fait partie de Fraza Libre.
|
|
102
|
+
Ce paquet fait partie de Fraza Libre.
|
package/bin/version.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
// AUTO-GÉNÉRÉ par `fraza-module sync-version`, ne pas modifier à la main.
|
|
2
|
-
export const STARTER_VERSION = '0.3.
|
|
2
|
+
export const STARTER_VERSION = '0.3.6';
|
package/changelog.json
CHANGED
|
@@ -2,13 +2,56 @@
|
|
|
2
2
|
"name": "@fraza/start",
|
|
3
3
|
"versions": [
|
|
4
4
|
{
|
|
5
|
-
"version": "0.3.
|
|
5
|
+
"version": "0.3.6",
|
|
6
|
+
"date": "2026-10-25",
|
|
7
|
+
"breaking": [],
|
|
8
|
+
"envAdded": [],
|
|
9
|
+
"envRemoved": [],
|
|
10
|
+
"templateChanged": [],
|
|
11
|
+
"action": [],
|
|
12
|
+
"entries": [
|
|
13
|
+
{
|
|
14
|
+
"type": "docs",
|
|
15
|
+
"scope": null,
|
|
16
|
+
"subject": "add command to start project",
|
|
17
|
+
"hash": "5edd2f6",
|
|
18
|
+
"breaking": false
|
|
19
|
+
}
|
|
20
|
+
]
|
|
21
|
+
},
|
|
22
|
+
{
|
|
23
|
+
"version": "0.3.5",
|
|
6
24
|
"date": "2026-10-25",
|
|
7
25
|
"breaking": [],
|
|
8
26
|
"envAdded": [],
|
|
9
27
|
"envRemoved": [],
|
|
10
28
|
"templateChanged": [],
|
|
11
29
|
"action": [],
|
|
30
|
+
"entries": [
|
|
31
|
+
{
|
|
32
|
+
"type": "chore",
|
|
33
|
+
"scope": "README",
|
|
34
|
+
"subject": "update description and remove redundant package reference",
|
|
35
|
+
"hash": "6851666",
|
|
36
|
+
"breaking": false
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
"type": "feat",
|
|
40
|
+
"scope": "README",
|
|
41
|
+
"subject": "overhaul documentation and add installation instructions",
|
|
42
|
+
"hash": "e1f31df",
|
|
43
|
+
"breaking": false
|
|
44
|
+
}
|
|
45
|
+
]
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
"version": "0.3.4",
|
|
49
|
+
"date": "2026-10-24",
|
|
50
|
+
"breaking": [],
|
|
51
|
+
"envAdded": [],
|
|
52
|
+
"envRemoved": [],
|
|
53
|
+
"templateChanged": [],
|
|
54
|
+
"action": [],
|
|
12
55
|
"entries": [
|
|
13
56
|
{
|
|
14
57
|
"type": "docs",
|