Aide-mémoire Nest CLI

Les commandes de @nestjs/cli dont vous aurez besoin pendant le parcours et après, vérifiées sur la version 12.0.8 (celle de TaskFlow) : chaque option citée figure dans nest <commande> --help, et les exemples de génération ont été exécutés en --dry-run dans TaskFlow. En cas de doute sur une autre version, nest <commande> --help fait foi.

Pour comprendre ce que produit le CLI (modules, providers, injection), voir J1 · Nest CLI et J3 · Modules.

Installer et s'informer

bash

npm i -g @nestjs/cli                # installation globale : commande nest
npx @nestjs/cli@latest new mon-api  # sans installation globale
nest --version                      # version du CLI
nest --help                         # liste des commandes et des schematics
nest generate --help                # options d'une commande
nest info                           # versions de Node, du CLI et des paquets @nestjs/* du projet

Dans un projet, npx nest … ou les scripts npm utilisent le CLI installé en devDependencies, ce qui évite un écart entre la version globale et celle du projet.

Créer un projet : nest new

bash

nest new mon-api                    # questions interactives (voir ci-dessous)
nest new mon-api -p npm             # gestionnaire de paquets : npm, yarn, pnpm…
nest new mon-api -g -s              # sans dépôt git (-g), sans npm install (-s)
nest new mon-api -d                 # dry run : liste les fichiers sans rien écrire
nest new mon-api --no-observe       # ne propose pas @nestjs/observe

Option	Raccourci	Effet
`--package-manager <pm>`	`-p`	Gestionnaire de paquets, sans question
`--skip-git`	`-g`	Pas de `git init`
`--skip-install`	`-s`	Pas d'installation des dépendances
`--dry-run`	`-d`	Affiche les fichiers qui seraient créés
`--language <lang>`	`-l`	`TypeScript` (défaut) ou `JavaScript`
`--skip-tests`	`-t`	Pas de fichiers de test
`--strict`		Mode strict TypeScript : activé par défaut dans le CLI 12
`--format`		Formate les fichiers générés avec Prettier
`--directory <dir>`		Dossier de destination différent du nom
`--observe` / `--no-observe`		Configure ou écarte `@nestjs/observe` sans poser la question

Les questions du CLI 12

Gestionnaire de paquets (sauf avec -p).
Système de modules : ESM (ES Modules) [ with vitest ] (proposé par défaut) ou CJS (CommonJS) [ with jest ]. Le plan et TaskFlow utilisent CJS + Jest : choisissez-le. Il n'existe pas d'option en ligne de commande pour ce choix : nest new --type cjs est refusé (unknown option).
NestJS Observe (télémétrie, service payant), sauf avec --observe / --no-observe.

Sans terminal interactif, c'est ESM + Vitest

Lancé sans TTY (script, CI, < /dev/null), nest new ne pose aucune question et prend les valeurs par défaut : le projet généré contient vitest.config.ts et pas de configuration Jest. Créez le projet à la main, dans un terminal, pour obtenir la variante CommonJS + Jest.

Fichiers générés (variante CJS + Jest, celle de TaskFlow) : src/ (main.ts, app.module.ts, app.controller.ts, app.service.ts, app.controller.spec.ts), test/ (app.e2e-spec.ts, jest-e2e.json), nest-cli.json, tsconfig.json, tsconfig.build.json, jest.config.ts, .oxlintrc.json (le lint du starter 12 est oxlint), .prettierrc, package.json. Détail et rôle de chacun : J1 · Structure d'un projet Nest.

Générer du code : nest g

bash

nest g <schematic> <nom> [chemin] [options]     # nest generate, alias g
nest g service users                           # src/users/users.service.ts + spec
nest g module users/admin                      # src/users/admin/admin.module.ts

Le nom peut contenir un chemin : users/admin crée src/users/admin/. Les fichiers prennent le suffixe du schematic (.service.ts, .guard.ts, .dto.ts…) en kebab-case : ce sont les conventions décrites dans Structure du repo.

Schematics et alias

Schematic	Alias	Produit	Enregistré dans un module ?
`module`	`mo`	Module	Oui, dans les `imports` du module parent
`controller`	`co`	Contrôleur + spec	Oui, `controllers` du module le plus proche
`service`	`s`	Service + spec	Oui, `providers` du module le plus proche
`provider`	`pr`	Provider (fichier sans suffixe) + spec	Oui, `providers`
`resource`	`res`	Module, contrôleur, service, DTO, entité	Oui, module importé dans le parent
`gateway`	`ga`	Gateway WebSocket	Oui, `providers`
`resolver`	`r`	Resolver GraphQL	Oui, `providers`
`guard`	`gu`	Guard + spec	Non : `@UseGuards()` ou `APP_GUARD`
`interceptor`	`itc`	Intercepteur + spec	Non : `@UseInterceptors()` ou `APP_INTERCEPTOR`
`pipe`	`pi`	Pipe + spec	Non : dans `@Param()`, `@Body()` ou `APP_PIPE`
`filter`	`f`	Exception filter + spec	Non : `@UseFilters()` ou `APP_FILTER`
`middleware`	`mi`	Middleware + spec	Non : `configure(consumer)`
`decorator`	`d`	Décorateur de métadonnées `Reflector.createDecorator()` (lu par `reflector.get()`)	Non
`class`	`cl`	Classe	Non
`interface`	`itf`	Interface (`.interface.ts`)	Non
`sub-app`	`app`	Application dans un monorepo	Voir monorepo
`library`	`lib`	Bibliothèque dans un monorepo	Voir monorepo
`configuration`	`config`	Fichier `nest-cli.json`	—
`application`	`application`	Nouvel espace de travail (utilisé par `nest new`)	—

TaskFlow écrit ses décorateurs avec SetMetadata et createParamDecorator (J8 · Routes publiques) ; Reflector.createDecorator(), que génère le CLI, en est la forme typée pour les métadonnées.

« Le module le plus proche » : le CLI remonte l'arborescence depuis le dossier cible. Dans TaskFlow, nest g mo users/admin ajoute AdminModule aux imports de UsersModule, pas d'AppModule ; un nest g co orders sans module orders existant est enregistré dans AppModule.

Options de génération

Option	Raccourci	Effet
`--dry-run`	`-d`	Affiche `CREATE` / `UPDATE` sans rien écrire : à utiliser avant toute génération
`--flat` / `--no-flat`		Sans / avec sous-dossier dédié
`--spec` / `--no-spec`		Avec / sans fichier `.spec.ts`
`--spec-file-suffix <s>`		Autre suffixe que `spec` pour les tests
`--skip-import`		N'enregistre pas l'élément dans un module
`--project <nom>`	`-p`	Projet cible dans un monorepo
`--collection <nom>`	`-c`	Autre collection de schematics
`--format`		Formate avec Prettier
`--type <type>`		`resource` : couche de transport (`rest`, `graphql`, `microservice`…)
`--crud`		`resource` : génère les points d'entrée CRUD

Une ressource CRUD complète

bash

nest g resource orders                      # questions : transport, puis points d'entrée CRUD
nest g resource orders --type rest --crud   # sans question (vérifié)

Résultat dans TaskFlow (dry run) :

text

CREATE src/orders/orders.controller.spec.ts
CREATE src/orders/orders.controller.ts
CREATE src/orders/orders.module.ts
CREATE src/orders/orders.service.spec.ts
CREATE src/orders/orders.service.ts
CREATE src/orders/dto/create-order.dto.ts
CREATE src/orders/dto/update-order.dto.ts
CREATE src/orders/entities/order.entity.ts
UPDATE src/app.module.ts

update-order.dto.ts étend PartialType(CreateOrderDto), l'entité est une classe vide : ajoutez les décorateurs TypeORM et la validation vous-même. La suite du travail sur une ressource générée est le sujet de J2 · Générer la ressource.

Le squelette de TaskFlow avec le CLI

Ces commandes produisent les fichiers et les noms de TaskFlow (le dry run des filtres et middlewares tombe sur les fichiers existants, preuve que les noms sont identiques) :

bash

nest g resource projects --type rest --crud
nest g resource tasks --type rest --crud
nest g mo users && nest g s users && nest g co users
nest g mo auth && nest g s auth && nest g co auth
nest g mo notifications
nest g mo health && nest g co health
nest g mo common
nest g f common/filters/all-exceptions --flat
nest g itc common/interceptors/logging --flat
nest g mi common/middleware/correlation-id --flat

Quelques fichiers de TaskFlow sont regroupés à la main plutôt que générés : les deux guards dans auth/guards.ts, les décorateurs dans common/decorators/auth.decorators.ts, le contrôleur et le module de santé dans health/health.controller.ts. Voir Structure du repo.

Lancer, construire, déboguer

bash

nest start                          # compile puis lance dist/main.js
nest start --watch                  # recompile et relance à chaque modification (-w)
nest start -w --preserveWatchOutput # garde la sortie de la console entre deux relances
nest start --debug --watch          # débogueur Node (--inspect), port 9229 par défaut
nest start --debug 0.0.0.0:9230     # hôte:port du débogueur
nest start --env-file .env.local    # charge un fichier .env avant le démarrage
nest build                          # compile dans dist/ (vide dist/ si deleteOutDir)
nest build --watch                  # compilation continue, sans lancer

Les scripts npm de TaskFlow reprennent ceux du starter : build (nest build), start, start:dev (nest start --watch), start:prod (node dist/main), plus les scripts de test et de migration décrits en J10 et J5.

Choisir le compilateur

Option	Effet
`--builder tsc` (`-b`)	Compilateur TypeScript, par défaut ; c'est avec lui que le plugin Swagger de TaskFlow a été vérifié
`--builder swc`	Compilation plus rapide, sans contrôle de types sauf avec `--type-check` (les plugins CLI demandent ce réglage, voir la doc officielle SWC)
`--builder webpack` / `--builder rspack`	Bundle unique, avec `--webpackPath` / `--rspackPath`
`--webpack`	Ancienne forme de `--builder webpack`, marquée dépréciée

Monorepo et bibliothèques

Il n'y a pas d'option --monorepo à nest new : un projet standard devient un monorepo à la première application ajoutée.

bash

nest g app admin-api        # déplace src/ et test/ vers apps/<projet>/, ajoute apps/admin-api
nest g lib shared           # libs/shared ; demande le préfixe d'import (@app par défaut → @app/shared)
nest start admin-api --watch
nest build --all --parallel # toutes les applications et bibliothèques
nest g s orders -p admin-api

Le dry run de nest g app admin-api dans TaskFlow montre DELETE src, DELETE test puis CREATE apps/taskflow/src/… : la conversion déplace tout le code existant. Faites-la sur une branche, et seulement si plusieurs applications doivent vraiment partager du code. nest g lib met à jour nest-cli.json, tsconfig.json (chemins d'import), package.json et test/jest-e2e.json.

Ajouter et mettre à jour

bash

nest add @nestjs/swagger    # installe le paquet et lance son schematic d'intégration s'il en a un
nest add <paquet> -d        # dry run
nest upgrade                # alias : nest update ; migre vers la dernière version majeure de NestJS
nest upgrade -d             # voir les changements avant de les appliquer
nest upgrade -t next        # utiliser un dist-tag npm
nest deploy                 # déploiement sur le cloud Mau (service de l'équipe NestJS)

TaskFlow n'utilise pas nest add : ses dépendances sont fixées à des versions précises dans package.json pour que le site cite exactement le code qui tourne.

nest-cli.json

Le fichier de TaskFlow :

json

{
  "$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "deleteOutDir": true,
    "plugins": [
      {
        "name": "@nestjs/swagger",
        "options": { "classValidatorShim": true, "introspectComments": true }
      }
    ]
  }
}

Clé	Rôle
`collection`	Collection de schematics utilisée par `nest g` (`@nestjs/schematics`)
`sourceRoot`	Dossier des sources (`src`)
`entryFile`	Fichier lancé par `nest start` (`main` par défaut)
`compilerOptions.deleteOutDir`	Vide `dist/` avant chaque build
`compilerOptions.plugins`	Plugins de compilation ; ici `@nestjs/swagger`, qui ne lit que les fichiers `.dto.ts` et `.entity.ts` (J11)
`compilerOptions.assets`, `watchAssets`	Copie des fichiers non TypeScript (`.graphql`, `.hbs`…) dans `dist/`
`compilerOptions.builder`	Compilateur par défaut (`tsc`, `swc`, `webpack`, `rspack`)
`generateOptions`	Options par défaut de `nest g`, par exemple `{ "spec": false }`
`monorepo`, `projects`	Renseignés par `nest g app` et `nest g lib`

Pièges

ESM sans le vouloir : sans terminal interactif, nest new crée un projet ESM + Vitest (questions).
Fichier déjà présent : le CLI ne propose pas d'écraser, il échoue avec A merge conflicted on path "…". Vérifiez avec -d avant de générer.
Guard, pipe, filter, interceptor, middleware non enregistrés : le fichier est créé, mais rien ne l'active. Branchez-le vous-même (schematics, J6 · Ordre d'exécution).
Mauvais module parent : un élément généré dans un sous-dossier rejoint le module le plus proche, pas forcément celui que vous visiez ; --skip-import n'enregistre rien du tout. Relisez le UPDATE du dry run.
nest start sans --watch ne recompile pas après une modification : utilisez npm run start:dev.
Port de débogage occupé : nest start --debug 0.0.0.0:9230.
Plugin Swagger ignoré : il ne lit que les fichiers *.dto.ts / *.entity.ts, et il agit à la compilation par nest build / nest start : tsc seul ou ts-jest ne l'appliquent pas (pièges vérifiés).
Versions désalignées : gardez @nestjs/core, @nestjs/common et @nestjs/cli sur la même version majeure ; nest info les affiche, nest upgrade -d prépare la migration.

Aide-mémoire Nest CLI ​

Installer et s'informer ​

Créer un projet : nest new ​

Les questions du CLI 12 ​

Générer du code : nest g ​

Schematics et alias ​

Options de génération ​

Une ressource CRUD complète ​

Le squelette de TaskFlow avec le CLI ​

Lancer, construire, déboguer ​

Choisir le compilateur ​

Monorepo et bibliothèques ​

Ajouter et mettre à jour ​

nest-cli.json ​

Pièges ​

Aide-mémoire Nest CLI

Installer et s'informer

Créer un projet : nest new

Les questions du CLI 12

Générer du code : nest g

Schematics et alias

Options de génération

Une ressource CRUD complète

Le squelette de TaskFlow avec le CLI

Lancer, construire, déboguer

Choisir le compilateur

Monorepo et bibliothèques

Ajouter et mettre à jour

nest-cli.json

Pièges