nuxt-feathers-zod 0.2.4 → 0.2.5

package/README.md

@@ -1,166 +1,193 @@
-# nuxt-feathers-zod
+# nuxt-feathers-zod 
+[guide](https://vevedh.github.io/nuxt-feathers-zod/)
 
-> **Nuxt 4 (Nitro) + FeathersJS v5 (Dove) + Zod** — un module “tout‑en‑un” (site + API) avec **CLI**.
+### Guide officiel d’initialisation – Nuxt 4 (Bun, Feathers v5, Zod)
 
-`nuxt-feathers-zod` embarque un **backend Feathers** dans une app **Nuxt 4**. Tu construis une app web **et** une API dans le même projet, avec :
+Ce guide décrit **la seule procédure valide et supportée** pour initialiser correctement **nuxt-feathers-zod** dans un projet **Nuxt 4**, en se basant **strictement sur le comportement réel du module**.
 
-- ✅ Services **Zod-first** (validation `data`/`query` + types)
-- ✅ REST sous un préfixe (par défaut `/feathers`) via **Koa** ou **Express**
-- ✅ Client DX : `useService()` + stores Pinia (via `feathers-pinia`)
-- ✅ Swagger legacy (optionnel)
-- ✅ **Keycloak-only SSO** (optionnel) : `check-sso` ou `login-required` via `onLoad`
-- ✅ Composable unifié **`useAuth()`** (optimisation) : même API en Keycloak-only ou auth locale
+Il évite volontairement toute “magie implicite” ou création manuelle non supportée.
 
 ---
 
-## TL;DR (Nuxt 4)
+## 1. Objectif du module
 
-1. Installer :
+`nuxt-feathers-zod` permet d’embarquer un **backend FeathersJS v5 (Dove)** directement dans **Nitro**, avec :
 
-```bash
-bun add nuxt-feathers-zod feathers-pinia
-```
-
-2. Configurer Nuxt :
-
-```ts
-export default defineNuxtConfig({
-  modules: ['nuxt-feathers-zod'],
+* API REST (`/feathers/*`)
+* WebSocket (Socket.IO)
+* Validation **Zod-first**
+* Authentification **Local + JWT**
+* Adapters (MongoDB, Memory, etc.)
+* Swagger legacy (optionnel)
+* Composables client (`useService`, `useAuth`, stores Pinia)
 
-  feathers: {
-    // RÈGLE D’OR : le module scanne uniquement ces dossiers
-    servicesDirs: ['services'],
+👉 Il **n’y a pas de backend séparé** : Feathers est monté **dans Nuxt**.
 
-    transports: {
-      rest: { path: '/feathers', framework: 'koa' },
-      websocket: true,
-    },
+---
 
-    database: {
-      mongo: { url: 'mongodb://127.0.0.1:27017/my-site' },
-    },
+## 2. Pré-requis
 
-    // Auth locale (JWT) — OU Keycloak-only (voir plus bas)
-    auth: true,
+* **Bun** (recommandé et supporté)
+* **Node.js ≥ 18**
+* **Nuxt 4**
+* MongoDB (optionnel mais recommandé)
 
-    // Swagger legacy (optionnel)
-    swagger: { enabled: false },
-  },
-})
-```
+---
 
-3. Générer les services **via la CLI** (ne pas créer à la main) :
+## 3. Création du projet Nuxt 4
 
 ```bash
-bunx nuxt-feathers-zod add service users --adapter mongodb --auth --idField _id --docs
-bunx nuxt-feathers-zod add service articles --adapter mongodb --auth --idField _id --docs
+bunx nuxi@latest init my-site
+cd my-site
+bun install
+bun run dev
 ```
 
----
-
-## Prérequis
-
-- **Bun** (recommandé)
-- Node.js ≥ 18
-- Nuxt 4
+➡️ Vérifie que Nuxt démarre **avant toute intégration Feathers**.
 
 ---
 
-## Installation
+## 4. Installation des dépendances
+
+### 4.1 Module principal
 
 ```bash
 bun add nuxt-feathers-zod feathers-pinia
 ```
 
-### Swagger legacy (optionnel)
+### 4.2 (Optionnel) Swagger legacy
 
 ```bash
 bun add feathers-swagger swagger-ui-dist
 ```
 
-> Si `feathers.swagger.enabled = true` mais que `feathers-swagger` n’est pas installé dans l’app Nuxt, le module affiche un warning DX au démarrage.
+> ⚠️ `swagger-ui-dist` est requis si `feathers.swagger = true`
 
 ---
 
-## Règle fondamentale : services générés uniquement via CLI
+## 5. Configuration **obligatoire** (`nuxt.config.ts`)
 
-✅ Toujours :
+> ⚠️ **Cette configuration est critique**.
+> Une mauvaise initialisation provoque des erreurs bloquantes au démarrage.
 
-```bash
-bunx nuxt-feathers-zod add service <name> ...
-```
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-feathers-zod'],
+
+  feathers: {
+    /**
+     * RÈGLE D’OR :
+     * Le module scanne UNIQUEMENT ces dossiers
+     */
+    servicesDirs: ['services'],
+
+    /**
+     * Transports
+     */
+    transports: {
+      rest: {
+        path: '/feathers',
+        framework: 'koa',
+      },
+      websocket: true,
+    },
 
-❌ Ne pas créer manuellement `services/<name>`.
+    /**
+     * Base de données (MongoDB recommandé)
+     */
+    database: {
+      mongo: {
+        url: 'mongodb://127.0.0.1:27017/my-site',
+      },
+    },
 
-Pourquoi : le module génère les imports/types à partir de `servicesDirs`. Si un service n’est pas généré selon la structure attendue, tu peux déclencher des erreurs du type :
+    /**
+     * Authentification
+     */
+    auth: true,
 
-- `Services typeExports []`
-- `Entity class User not found`
+    /**
+     * Swagger legacy (optionnel)
+     */
+    swagger: false,
+  },
+})
+```
 
 ---
 
-## Configuration Nuxt
+## 6. RÈGLE FONDAMENTALE – À NE JAMAIS VIOLER
 
-### Options essentielles
+> ❌ **Ne jamais créer un service manuellement**
+> ✅ **Toujours utiliser la CLI officielle**
 
-- `feathers.servicesDirs` : **obligatoire**
-- `feathers.transports.rest.path` : préfixe REST (ex `/feathers`)
-- `feathers.database.mongo.url` : MongoDB (si adapter mongodb)
+Cette règle est **imposée par le code interne du module**.
 
 ---
 
-## Auth : concept important (ne pas mélanger)
+## 7. Création du premier service : `users` (OBLIGATOIRE)
 
-Le module supporte 2 approches :
-
-1. **Auth locale Feathers (JWT)** : `feathers.auth = true` + service `users` + endpoint `/feathers/authentication`.
-2. **Keycloak-only SSO** : `feathers.keycloak = { ... }` + plugin client `keycloak-js`, pas de login Feathers.
+```bash
+bunx nuxt-feathers-zod add service users \
+  --adapter mongodb \
+  --auth \
+  --idField _id \
+  --docs
+```
 
-👉 Ces deux providers ne partagent pas le même token ni la même session. C’est la raison pour laquelle on a ajouté **`useAuth()`** : une seule API côté frontend.
+### Structure générée (attendue)
 
----
+```
+services/users/
+  users.ts
+  users.class.ts
+  users.schema.ts
+  users.shared.ts
+```
 
-## `useAuth()` : API unifiée (recommandé)
+### Pourquoi `users` est obligatoire ?
 
-### Pourquoi ?
+* Le module **résout l’authentification** via une `entityClass` nommée **`User`**
+* Cette classe est **recherchée dynamiquement** dans les exports scannés
+* Sans ce service :
 
-- En Keycloak-only, `useAuthStore()` (auth locale) n’est pas initialisé.
-- En auth locale, `$keycloak` n’existe pas.
-- Mélanger les deux dans la même page revient à avoir **deux sources de vérité** et des headers `Authorization` concurrents.
+  * `Services typeExports []`
+  * `Entity class User not found in services imports`
+  * **Boot impossible**
 
-### Usage
+👉 Le service `users` est la **clé de voûte** de tout projet `nuxt-feathers-zod`.
 
-```ts
-const auth = useAuth()
-await auth.init()
+---
 
-if (!auth.isAuthenticated.value) {
-  await auth.login()
-}
+## 8. Création d’un service métier (exemple : `articles`)
 
-console.log(auth.provider.value) // 'keycloak' | 'local' | 'none'
-console.log(auth.user.value)
+```bash
+bunx nuxt-feathers-zod add service articles \
+  --adapter mongodb \
+  --auth \
+  --idField _id \
+  --docs
 ```
 
-> ⚠️ Attention : `feathers-pinia` expose aussi un `useAuth`. Évite d’importer `useAuth` depuis `feathers-pinia` dans une app Nuxt utilisant `nuxt-feathers-zod`. Si tu en as besoin, importe-le avec alias :
->
-> ```ts
-> import { useAuth as useFeathersAuth } from 'feathers-pinia'
-> ```
+Structure :
 
----
+```
+services/articles/
+  articles.ts
+  articles.class.ts
+  articles.schema.ts
+  articles.shared.ts
+```
 
-## Auth locale (Local + JWT)
+---
 
-### 1) Générer `users` (obligatoire)
+## 9. Démarrage et tests REST
 
 ```bash
-bunx nuxt-feathers-zod add service users --adapter mongodb --auth --idField _id --docs
+bun run dev
 ```
 
-### 2) Tests REST
-
-Créer un utilisateur :
+### 9.1 Création d’un utilisateur
 
 ```bash
 curl -X POST http://localhost:3000/feathers/users \
@@ -168,7 +195,7 @@ curl -X POST http://localhost:3000/feathers/users \
   -d '{"userId":"demo","password":"demo123"}'
 ```
 
-Login :
+### 9.2 Authentification
 
 ```bash
 curl -X POST http://localhost:3000/feathers/authentication \
@@ -176,7 +203,7 @@ curl -X POST http://localhost:3000/feathers/authentication \
   -d '{"strategy":"local","userId":"demo","password":"demo123"}'
 ```
 
-Appel protégé :
+### 9.3 Accès à un service protégé
 
 ```bash
 curl http://localhost:3000/feathers/articles \
@@ -185,134 +212,101 @@ curl http://localhost:3000/feathers/articles \
 
 ---
 
-## Keycloak-only SSO (Option A)
-
-### Objectif
+## 10. Swagger legacy (optionnel)
 
-- Au démarrage : `check-sso` (pas de redirection forcée)
-- Routes protégées : middleware Nuxt qui appelle `login()` seulement quand nécessaire
-
-### Configuration Nuxt
+### 10.1 Activer Swagger
 
 ```ts
-export default defineNuxtConfig({
-  feathers: {
-    // active le mode Keycloak-only
-    keycloak: {
-      serverUrl: 'https://svrkeycloak.agglo.local:8443',
-      realm: 'AGGLO',
-      clientId: 'nuxt4app',
-
-      // Option ajoutée : onLoad
-      onLoad: 'check-sso', // ou 'login-required'
-
-      // bridge service Feathers (whoami)
-      authServicePath: '/_keycloak',
-
-      // si tu veux une persistance user : userService + serviceIdField
-      userService: 'users',
-      serviceIdField: 'keycloakId',
-
-      permissions: false,
-    },
-  },
-})
+feathers: {
+  swagger: true,
+}
 ```
 
-### Fichier requis pour `check-sso`
+### 10.2 Accès
 
-Créer : `public/silent-check-sso.html`
+* UI :
+  `http://localhost:3000/feathers/docs/`
+* Spec :
+  `http://localhost:3000/feathers/swagger.json`
 
-```html
-<!doctype html>
-<html>
-  <body>
-    <script>
-      parent.postMessage(location.href, location.origin)
-    </script>
-  </body>
-</html>
-```
+### ⚠️ Important
 
-### Les services Feathers protégés fonctionnent-ils ?
+Dans l’UI Swagger, la spec doit être définie manuellement à :
 
-✅ Oui, si :
+```
+../swagger.json
+```
 
-- côté client, le plugin Keycloak injecte `Authorization: Bearer <kc_token>` dans les appels Feathers
-- côté serveur, le hook Keycloak valide le JWT (JWKS) et remplit `context.params.user`
+(C’est un comportement connu et assumé du module.)
 
 ---
 
-## Frontend : `useService()` (feathers-pinia)
+## 11. Plugins serveur Feathers (seed, hooks globaux)
 
-Exemple : liste d’articles :
+### Exemple : `server/feathers/dummy.ts`
 
-```vue
-<script setup lang="ts">
-import { useService } from 'feathers-pinia'
-
-const { data, find, isPending } = useService('articles')
-
-await find({ query: { $limit: 10 } })
-</script>
-
-<template>
-  <div>
-    <div v-if="isPending">
-      Chargement…
-    </div>
-    <pre v-else>{{ data }}</pre>
-  </div>
-</template>
+```ts
+import { defineFeathersServerPlugin } from 'nuxt-feathers-zod/server'
+
+export default defineFeathersServerPlugin((app) => {
+  app.hooks({
+    setup: [
+      async (context, next) => {
+        await context.app.service('users').create({
+          userId: 'admin',
+          password: 'admin123',
+        })
+        await next()
+      },
+    ],
+  })
+})
 ```
 
----
-
-## Swagger legacy
-
-- UI : `/feathers/docs/`
-- Spec : `/feathers/swagger.json` (souvent consommée via `../swagger.json` depuis l’UI)
+➡️ Ces fichiers sont des **plugins Feathers**, pas des services.
 
 ---
 
-## Playground (monorepo)
+## 12. Erreurs courantes et causes réelles
 
-### Windows / ESM
+### ❌ `Services typeExports []`
 
-Référencer toujours le module avec extension :
+Causes :
 
-```ts
-modules: ['../src/module.ts']
-```
+* `servicesDirs` incorrect
+* services créés manuellement
+* fichiers mal nommés (`users.ts` manquant)
 
-### vue-tsc / vite-plugin-checker
+### ❌ `Entity class User not found in services imports`
 
-Si tu vois :
+Cause exacte :
 
-- `Cannot find global type 'Array'` / `lib.dom.d.ts not found`
+* le service `users` n’existe pas ou n’a pas été généré via la CLI
 
-Alors désactive le typecheck dans le playground :
+✅ Solution universelle :
 
-```ts
-typescript: { typeCheck: false }
+```bash
+bunx nuxt-feathers-zod add service users
 ```
 
-Et garde le typecheck au root via un script dédié.
-
 ---
 
-## Documentation (VitePress)
-
-Lancer la doc :
+## 13. Bonnes pratiques figées
 
-```bash
-bun run docs:dev
-```
+* ✅ **Toujours** générer les services avec la CLI
+* ✅ `services/<name>/<name>.ts` obligatoire
+* ✅ Zod-first (`*.schema.ts`)
+* ❌ Pas de création manuelle
+* ❌ Pas de renommage arbitraire de `User`
+* ❌ Pas de déplacement hors `servicesDirs`
 
 ---
 
-## Scripts utiles
+## 14. Résumé express (checklist)
 
-- `bun run dev` : lance le playground
-- `bun run prepare` : build du module (`nuxt-module-build prepare && build`)
-- `bun run docs:dev` : doc VitePress
+1. `bunx nuxi init`
+2. `bun add nuxt-feathers-zod feathers-pinia`
+3. `servicesDirs: ['services']`
+4. `bunx nuxt-feathers-zod add service users`
+5. `bunx nuxt-feathers-zod add service <business>`
+6. `bun run dev`

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^4.0.0"
   },
-  "version": "0.2.4",
+  "version": "0.2.5",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-feathers-zod",
   "type": "module",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "packageManager": "bun@1.3.6",
   "description": "Feathers API integration for Nuxt",
   "author": "Herve de CHAVIGNY",