Starter API

Ce starter est un socle d’API REST prêt pour la production, construit sur NestJS 11 et TypeScript. Il rassemble les fondations que je pose systématiquement en début de projet — authentification, gestion des droits, logging, infrastructure Docker — pour ne pas les reconstruire à chaque fois.

Pourquoi NestJS

Le choix de NestJS vient d’abord d’une habitude de travail prise chez Mobicoop, où nous l’avions adopté pour nos développements backend. L’objectif était d’avoir un framework en TypeScript qui partage le même langage que le front — supprimer la rupture entre un back PHP et un front TypeScript. NestJS impose une structure modulaire, un système d’injection de dépendances et des décorateurs qui rappellent l’écosystème Symfony, ce qui a facilité la transition. Côté front, nous utilisions déjà Vue.js, et c’est ce qui a guidé le choix — même si, pour coller parfaitement à l’architecture de NestJS, Angular aurait été le candidat naturel, les deux frameworks partageant la même philosophie (modules, décorateurs, injection de dépendances).

Architecture

Le starter suit une architecture hexagonale couplée au pattern CQRS. Le domaine métier est isolé de l’infrastructure : la base de données, le système de notifications, le logger sont des adaptateurs interchangeables. En pratique, cela signifie qu’on peut remplacer Prisma par un autre ORM ou changer de base de données sans toucher à la logique métier.

La base de données est PostgreSQL 16, pilotée par Prisma 7 pour les migrations et les requêtes typées.

Authentification et droits

L’authentification repose sur des JSON Web Tokens avec mécanisme de refresh token. La gestion des droits utilise CASL, une librairie qui permet de définir des permissions granulaires par rôle — ce que tel profil peut lire, créer, modifier ou supprimer, sur quelle ressource.

Outillage intégré

Le starter embarque tout ce qui entoure le code métier et qui, sans socle prêt à l’emploi, consomme un temps considérable en début de projet :

• Logging structuré via Pino, avec identifiant de requête pour tracer les appels de bout en bout.
• Health checks compatibles Kubernetes, pour les sondes de disponibilité et de vivacité.
• Documentation API générée automatiquement via Swagger.
• Notifications multi-canal — le système est conçu pour envoyer par email, avec Mailhog en développement pour intercepter les envois.
• Gestion des secrets via SOPS et age — les fichiers sensibles sont chiffrés dans le dépôt, pas stockés en clair.

Infrastructure Docker

L’ensemble tourne dans des conteneurs Docker orchestrés par Docker Compose. Un Makefile centralise les commandes courantes — make start, make migrate, make seed, make logs-api — pour que l’onboarding d’un nouveau développeur se résume à trois commandes.

Une documentation complète est incluse dans le dépôt.

Lien vers le dépôt : https://codeberg.org/olifil/starter-api