Nicolas
e2d7207237
- Outillage complet : pnpm workspaces (catalog), Biome, TypeScript (project references, CommonJS/Node10), Vitest, TypeDoc (validation bloquante en CI), Changesets. - Organisation des packages en catégories client/common/server. - Migration de @lightweight-sdk/web-component (packages/client/) depuis l'ancien repo lightweight-sdk-web-component : code source copié à l'identique, aucune modification. package.json/tsconfig.json/README.md adaptés autour. Exclu de la validation TypeDoc stricte et de quelques règles Biome (formatage, noShadowRestrictedNames) puisque le code ne peut pas être édité pour s'y conformer - détails dans spec/packages.md. - Workflows Forgejo Actions (.forgejo/workflows/) : ci.yml (lint, build, test, docs:check) et release.yml (publication sur le registre npm privé via Changesets). - Script pnpm create-package <client|common|server> <nom> pour scaffolder les futurs packages. - Documentation dans /spec (architecture, conventions, ci-cd, packages). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
39 lines
3.2 KiB
Markdown
39 lines
3.2 KiB
Markdown
# Architecture
|
|
|
|
## Objectif
|
|
|
|
`lightweight-sdk` est un monorepo pnpm destiné à héberger, au fil du temps, des packages TypeScript réutilisables développés par l'auteur pour ses projets personnels. Chaque package est publié indépendamment sur le registre npm privé hébergé sur l'instance Forgejo personnelle (`git.dev.kyuno.fr`), sous le scope `@lightweight-sdk`.
|
|
|
|
## Organisation des packages
|
|
|
|
Les packages sont répartis en trois catégories sous `packages/`, qui reflètent la distinction Frontend/Backend du [CLAUDE.md](../CLAUDE.md) du projet :
|
|
|
|
- **`client/`** — packages destinés au navigateur (DOM, composants UI). Peuvent dépendre de `lib: DOM` dans leur `tsconfig.json`.
|
|
- **`common/`** — code isomorphe partagé entre `client` et `server` (types, utilitaires purs, constantes). Convention : ne doit dépendre d'aucune API exclusivement DOM ou exclusivement Node, pour rester portable des deux côtés.
|
|
- **`server/`** — packages Node/backend. Chaque package doit être structuré comme un service modulaire autonome exposant sa propre API (règle "Architecture Backend" du CLAUDE.md).
|
|
|
|
Le nom npm d'un package ne reprend pas le préfixe de catégorie (`@lightweight-sdk/web-component`, pas `@lightweight-sdk/client-web-component`) — la catégorie est une convention d'organisation du dépôt, pas une convention de nommage public.
|
|
|
|
Un nouveau package se crée avec `pnpm create-package <client|common|server> <nom>` (voir `scripts/create-package.mjs`).
|
|
|
|
## Choix d'outillage
|
|
|
|
| Aspect | Choix | Pourquoi |
|
|
|---|---|---|
|
|
| Gestionnaire de packages | pnpm workspaces + `catalog:` | Centralise les versions des devDependencies partagées dans `pnpm-workspace.yaml` |
|
|
| Orchestrateur de build | Aucun (pas de Turborepo/Nx) | Un seul package réel au démarrage ; à reconsidérer si le temps de build devient un problème |
|
|
| Build | `tsc -b` (project references), pas de bundler | Les packages sont consommés via pnpm par d'autres projets Node/TS de l'auteur ; pas besoin de bundle |
|
|
| Modules | **CommonJS**, résolution `Node10` | Décision explicite : pas d'extension `.js` requise dans les imports relatifs, et le code migré depuis l'ancien repo `web-component` compile sans modification |
|
|
| Lint + format | [Biome.js](https://biomejs.dev/) | Imposé par le CLAUDE.md du projet |
|
|
| Documentation de code | [TypeDoc](https://typedoc.org/) en mode validation | Génère la doc API et fait échouer la CI si un export n'a pas de TSDoc (voir `conventions.md`) |
|
|
| Tests | [Vitest](https://vitest.dev/) | ESM natif, bon support monorepo |
|
|
| Versioning/publish | [Changesets](https://github.com/changesets/changesets) | Gère des versions indépendantes par package + changelogs, comprend nativement `workspace:*` |
|
|
| Node cible | 24 (Active LTS) en CI, `engines: ">=22"` | Node 20 est end-of-life depuis avril 2026 |
|
|
|
|
## Dépendances entre packages
|
|
|
|
Les dépendances internes entre packages du monorepo utilisent le protocole `workspace:*` (résolu localement par pnpm, jamais via le registre distant). Le registre npm privé n'est utilisé que pour la publication et pour la consommation depuis des projets *externes* à ce monorepo.
|
|
|
|
## Registre npm privé
|
|
|
|
`https://git.dev.kyuno.fr/api/packages/kyuno/npm/` — voir `ci-cd.md` pour le détail de la publication et de l'authentification.
|