Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Compiler un projet NestJS pour la production (nest build)

Cette leçon prépare une application NestJS pour la production. Elle explique ce que fait nest build, le contenu du dossier dist et la différence entre dépendances de développement et de production (33...

0 chapitres 0 QCM Accès gratuit
Compiler un projet NestJS pour la production (nest build)

À propos de ce cours

Cette leçon prépare une application NestJS pour la production. Elle explique ce que fait nest build, le contenu du dossier dist et la différence entre dépendances de développement et de production (331 Mo contre 152 Mo, mesurés sur le projet). Elle construit un dossier de production, démarre réellement l'API avec NODE_ENV=production, analyse l'erreur obtenue sans migration, exécute les migrations compilées et crée le premier administrateur avec un script. Elle montre l'intérêt des source maps pour lire les erreurs. Activités corrigées.

Objectifs de la leçon

  • Comprendre ce que produit nest build et ce qui part en production.
  • Distinguer dépendances de développement et de production.
  • Démarrer l'API compilée avec la configuration de production.
  • Exécuter les migrations et créer le premier administrateur sans outil de développement.
  • Lire une erreur de production grâce aux source maps.

Versions: NestJS 12.5 (projet CommonJS), Node.js 24, npm 11, PM2 7.1, nginx 1.24 (Ubuntu 24.04 LTS), Docker 29 avec Compose 5, MariaDB 10.11. Toutes les commandes de ce chapitre ont été réellement exécutées sur un serveur de test Ubuntu 24.04 (adresse 192.0.2.2, utilisateur deploy), avec le projet api-securisee du chapitre 19, complété pour la production. Les sorties sont reproduites telles quelles ; seuls les secrets sont masqués.

Pourquoi compiler ?

En développement, npm run start:dev lance nest start --watch: le Nest CLI compile le TypeScript à chaque modification et redémarre l'application. C'est pratique, mais lent au démarrage, gourmand en mémoire, et cela suppose que TypeScript et le CLI sont installés.

En production, on compile une seule fois le TypeScript en JavaScript, puis Node.js exécute directement ce JavaScript. Le serveur n'a besoin ni des fichiers source, ni des outils de développement.

Du code source à la production

Le chemin du code : src → dist → dossier de production (tailles mesurées sur le projet).

nest build

Le script build de package.json appelle nest build. Il compile avec tsconfig.build.json, qui reprend tsconfig.json en excluant les tests :

📄 tsconfig.build.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "rootDir": "./src"
  },
  "include": ["src"],
  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
}

📄 nest-cli.json

{
  "$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "deleteOutDir": true
  }
}

deleteOutDir: true vide dist avant chaque compilation : aucun ancien fichier (une migration supprimée, un contrôleur renommé) ne peut traîner dans la version livrée.

Résultat réellement obtenu :

$ npm run build
> api-securisee@0.0.1 build
> nest build
$ find dist -maxdepth 2 -not -name "*.map" -not -name "*.d.ts" | sort
dist
dist/app.module.js
dist/auth
dist/auth/auth.controller.js
dist/auth/auth.guard.js
dist/auth/auth.module.js
dist/auth/auth.service.js
dist/auth/decorateurs.js
dist/auth/dto
dist/commun
dist/commun/creer-logger.js
dist/commun/journal-http.middleware.js
dist/config
dist/config/environnement.js
dist/configurer-app.js
dist/data-source.js
dist/demandes
dist/demandes/demande.entity.js
dist/demandes/demandes.controller.js
dist/demandes/demandes.module.js
dist/demandes/demandes.service.js
dist/demandes/dto
dist/main.js
dist/migrations
dist/migrations/1794763018768-Initialisation.js
dist/sante
dist/sante/sante.controller.js
dist/scripts
dist/scripts/creer-admin.js
dist/swagger.js
dist/utilisateurs
dist/utilisateurs/utilisateur.entity.js
dist/utilisateurs/utilisateurs.controller.js
dist/utilisateurs/utilisateurs.module.js
dist/utilisateurs/utilisateurs.service.js
$ du -sh dist src
384K	dist
156K	src

Chaque fichier .ts de src devient un .js dans dist, au même emplacement, avec un .map (source map) et un .d.ts (types). Le point d'entrée est dist/main.js. Les migrations et les scripts sont compilés eux aussi : c'est important pour la suite. Voici le début d'un service compilé :

Extrait réel :

$ head -25 dist/demandes/demandes.service.js
"use strict";
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
    return c > 3 && r && Object.defineProperty(target, key, r), r;
};
var __metadata = (this && this.__metadata) || function (k, v) {
    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
};
var __param = (this && this.__param) || function (paramIndex, decorator) {
    return function (target, key) { decorator(target, key, paramIndex); }
};
var DemandesService_1;
Object.defineProperty(exports, "__esModule", { value: true });
exports.DemandesService = void 0;
const common_1 = require("@nestjs/common");
const typeorm_1 = require("@nestjs/typeorm");
const typeorm_2 = require("typeorm");
const demande_entity_1 = require("./demande.entity");
let DemandesService = DemandesService_1 = class DemandesService {
    repo;
    logger = new common_1.Logger(DemandesService_1.name);
    constructor(repo) {
        this.repo = repo;

Les décorateurs sont devenus des appels de fonctions (__decorate, __metadata) et les import des require (projet CommonJS). Inutile de lire ce code : on travaille toujours sur src, et les source maps font le lien (fin de la leçon).

Fichiers qui ne sont pas du TypeScript: nest build ne copie que ce qu'il compile. Des modèles d'e-mails (chapitre 15), des fichiers JSON de données ou des certificats placés dans src doivent être déclarés dans nest-cli.json: "compilerOptions": { "assets": ["mails/**/*.hbs"], "watchAssets": true }. Sinon l'application fonctionne en développement… et plante en production.

Dépendances de développement et de production

package.json sépare dependencies (nécessaires à l'exécution : NestJS, TypeORM, bcrypt…) et devDependencies (nécessaires pour développer : TypeScript, Nest CLI, Jest, Oxlint…). Sur le poste de développement, npm ci installe tout :

Résultat réellement obtenu :

$ npm ci
added 657 packages, and audited 658 packages in 10s
25 vulnerabilities (6 low, 17 moderate, 2 high)
$ du -sh node_modules
331M	node_modules

Préparons un dossier de production : le JavaScript compilé, package.json et package-lock.json, puis une installation sans les dépendances de développement :

Résultat réellement obtenu :

$ cp -r dist package.json package-lock.json ../release/api-securisee/ && ls ../release/api-securisee
dist
package-lock.json
package.json
$ npm ci --omit=dev
added 188 packages, and audited 189 packages in 6s

64 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
$ du -sh node_modules
152M	node_modules
$ ls node_modules/.bin | grep -E "^(nest|jest|tsc|typeorm)$"
tsc
typeorm

152 Mo au lieu de 331 Mo, aucune faille connue au lieu de 25 : les failles signalées au chapitre 19 concernaient des outils de développement. Le CLI nest et jest ont disparu. tsc (TypeScript) reste, car @nestjs/swagger et TypeORM en dépendent : npm ls typescript --omit=dev l'explique.

  • npm ci plutôt que npm install: il installe exactement les versions de package-lock.json (le lock doit donc être versionné) et échoue si les deux fichiers ne correspondent pas.
  • Attention à ne pas placer dans devDependencies un paquet utilisé à l'exécution : tout fonctionne sur votre poste, puis Cannot find module en production.
Les scripts du projet pour la production

📄 package.json (extrait des scripts)

{
  "build": "nest build",
  "start:prod": "node --enable-source-maps dist/main",
  "typeorm": "typeorm -d dist/data-source.js",
  "migration:generate": "nest build && typeorm -d dist/data-source.js migration:generate src/migrations/$npm_config_name",
  "migration:run": "typeorm -d dist/data-source.js migration:run",
  "admin:creer": "node dist/scripts/creer-admin.js"
}
  • start:prod lance directement node sur le code compilé, avec --enable-source-maps.
  • migration:run appelle la CLI TypeORM sur dist/data-source.js: elle fonctionne sans TypeScript, uniquement avec les migrations compilées. migration:generate sert en développement (il recompile d'abord).
  • admin:creer exécute un script compilé qui crée le premier compte administrateur.

📄 src/data-source.ts

import 'dotenv/config';
import { DataSource } from 'typeorm';

// Utilisée par la CLI TypeORM (migrations) et les scripts ; l'application utilise TypeOrmModule.
// Chemins en .js : on travaille sur le code compilé (dist/), comme en production.
export default new DataSource({
  type: 'mysql',
  host: process.env.DB_HOTE,
  port: Number(process.env.DB_PORT ?? 3306),
  username: process.env.DB_UTILISATEUR,
  password: process.env.DB_MOT_DE_PASSE,
  database: process.env.DB_NOM,
  entities: [__dirname + '/**/*.entity.js'],
  migrations: [__dirname + '/migrations/*.js'],
});
Premier démarrage en production

Le dossier de production reçoit son propre .env, avec NODE_ENV=production, des identifiants de base dédiés, un secret JWT neuf et des journaux JSON (chapitre 19). Ses droits sont restreints au seul propriétaire :

📄 ~/release/api-securisee/.env (secrets masqués)

NODE_ENV=production
PORT=3000
DB_HOTE=localhost
DB_PORT=3306
DB_UTILISATEUR=api_prod
DB_MOT_DE_PASSE=Pr0d-Base-2026!
DB_NOM=api_prod
JWT_SECRET=••••••••
CORS_ORIGINES=https://stagiaires.exemple.tn
TRUST_PROXY=loopback
LOG_FORMAT=json
LOG_NIVEAUX=log

Avec NODE_ENV=production, notre code change de comportement : synchronize est désactivé (le schéma ne vient que des migrations), Swagger n'est pas publié, les données de démonstration ne sont pas créées, et le niveau de journal par défaut est log. Démarrons avec node dist/main et testons :

Résultat réellement obtenu :

$ curl -s http://localhost:3000/api/sante
{"statut":"ok","disponibleDepuis":"6 s"}
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/api/docs
404
$ curl -s -X POST http://localhost:3000/api/auth/connexion -H 'Content-Type: application/json' -d '{"email":"admin@exemple.tn","motDePasse":"Admin2026!"}'
{"statusCode":500,"message":"Internal server error"}

L'API démarre et répond, Swagger est bien absent (404)… mais la connexion échoue (500). Le journal (JSON, une ligne par message) donne la raison :

{"level": "error", "message": "Table 'api_prod.utilisateurs' doesn't exist", "context": "ExceptionsHandler"}

La base de production est vide : aucune table n'existe. C'est normal : en production, synchronize est désactivé et le schéma doit être créé par les migrations (chapitre 12).

Migrations et premier administrateur

Résultat réellement obtenu :

$ npm run migration:run
> api-securisee@0.0.1 migration:run
> typeorm -d dist/data-source.js migration:run

query: SELECT version() as version
query: SELECT * FROM `INFORMATION_SCHEMA`.`COLUMNS` WHERE `TABLE_SCHEMA` = ? AND `TABLE_NAME` = ? -- PARAMETERS: ["api_prod","migrations"]
query: CREATE TABLE `migrations` (`id` int NOT NULL AUTO_INCREMENT, `timestamp` bigint NOT NULL, `name` varchar(255) NOT NULL, PRIMARY KEY (`id`)) ENGINE=InnoDB
query: SELECT * FROM `api_prod`.`migrations` `migrations` ORDER BY `id` DESC
0 migrations are already loaded in the database.
1 migrations were found in the source code.
1 migrations are new migrations must be executed.
query: START TRANSACTION
query: CREATE TABLE `utilisateurs` (`id` int NOT NULL AUTO_INCREMENT, `email` varchar(120) NOT NULL, `nom` varchar(80) NOT NULL, `mot_de_passe_hash` varchar(100) NOT NULL, `role` varchar(20) NOT NULL DEFAULT 'stagiaire', `cree_le` datetime(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6), UNIQUE INDEX `IDX_6b14325a486fe68d16aa889e4d` (`email`), PRIMARY KEY (`id`)) ENGINE=InnoDB
query: CREATE TABLE `demandes` (`id` int NOT NULL AUTO_INCREMENT, `objet` varchar(150) NOT NULL, `statut` varchar(20) NOT NULL DEFAULT 'en_attente', `cree_le` datetime(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6), `proprietaireId` int NOT NULL, PRIMARY KEY (`id`)) ENGINE=InnoDB
query: ALTER TABLE `demandes` ADD CONSTRAINT `FK_9a6e39ae79d4cc0de7d5fd6e798` FOREIGN KEY (`proprietaireId`) REFERENCES `utilisateurs`(`id`) ON DELETE CASCADE ON UPDATE NO ACTION
query: INSERT INTO `api_prod`.`migrations`(`timestamp`, `name`) VALUES (?, ?) -- PARAMETERS: [1794763018768,"Initialisation1794763018768"]
Migration Initialisation1794763018768 has been executed successfully.
query: COMMIT
$ ADMIN_EMAIL=direction@exemple.tn ADMIN_MOT_DE_PASSE='Direction-2026-Prod' npm run admin:creer
> api-securisee@0.0.1 admin:creer
> node dist/scripts/creer-admin.js

Compte administrateur direction@exemple.tn créé
$ ADMIN_EMAIL=direction@exemple.tn ADMIN_MOT_DE_PASSE='Direction-2026-Prod' npm run admin:creer
> api-securisee@0.0.1 admin:creer
> node dist/scripts/creer-admin.js

Le compte direction@exemple.tn existe déjà : rien à faire

Le script de création de l'administrateur est volontairement idempotent (le relancer ne fait rien) et prend ses informations dans des variables d'environnement : aucun mot de passe connu n'est écrit dans le code, contrairement au jeu de démonstration.

📄 src/scripts/creer-admin.ts

import * as bcrypt from 'bcrypt';
import source from '../data-source';
import { Utilisateur } from '../utilisateurs/utilisateur.entity';

// Crée le premier compte administrateur en production :
//   ADMIN_EMAIL=... ADMIN_MOT_DE_PASSE=... npm run admin:creer
async function creerAdmin() {
  const email = process.env.ADMIN_EMAIL?.toLowerCase();
  const motDePasse = process.env.ADMIN_MOT_DE_PASSE ?? '';
  if (!email || motDePasse.length < 12) {
    console.error('ADMIN_EMAIL et ADMIN_MOT_DE_PASSE (12 caractères minimum) sont obligatoires');
    process.exit(1);
  }
  await source.initialize();
  const repo = source.getRepository(Utilisateur);
  if (await repo.existsBy({ email })) {
    console.log(`Le compte ${email} existe déjà : rien à faire`);
  } else {
    await repo.save(repo.create({ email, nom: 'Administration', role: 'admin', motDePasseHash: await bcrypt.hash(motDePasse, 12) }));
    console.log(`Compte administrateur ${email} créé`);
  }
  await source.destroy();
}
void creerAdmin();

Vérification dans la base :

$ mysql api_prod -e "SHOW TABLES; SELECT id, email, role FROM utilisateurs;"
Tables_in_api_prod
demandes
migrations
utilisateurs
id	email	role
1	direction@exemple.tn	admin

Mot de passe dans la commande: une commande tapée dans le terminal est enregistrée dans l'historique (~/.bash_history). Sur un serveur partagé, faites précéder la commande d'une espace (elle n'est alors pas enregistrée avec HISTCONTROL=ignoreboth, réglage par défaut du .bashrc d'Ubuntu) ou supprimez la ligne de l'historique.

Lire une erreur de production : les source maps

Revenons à l'erreur 500 du premier démarrage. Sans source maps, la pile d'appels désigne le JavaScript compilé :

at async AuthService.connecter (~/release/api-securisee/dist/auth/auth.service.js:61:19)

Avec npm run start:prod, qui ajoute --enable-source-maps, la même erreur désigne directement la ligne du fichier TypeScript :

at async AuthService.connecter (~/release/api-securisee/src/auth/auth.service.ts:17:15)

Les fichiers .map (option sourceMap du tsconfig.json) contiennent la correspondance entre le JavaScript et le TypeScript. Le coût est faible (un peu de mémoire au démarrage) et le gain énorme quand il faut corriger vite.

Récapitulatif
npm ci                        # toutes les dépendances (pour compiler)
npm run build                 # src/ → dist/
npm ci --omit=dev             # (dossier de production) dépendances d'exécution seulement
npm run migration:run         # schéma de la base
npm run admin:creer           # premier compte (variables ADMIN_EMAIL, ADMIN_MOT_DE_PASSE)
npm run start:prod            # node --enable-source-maps dist/main

Ces étapes vont être exécutées sur un serveur et maintenues en marche par PM2 (leçon 20.2), puis empaquetées dans une image Docker (20.3) et vérifiées automatiquement par GitHub Actions (20.4).

Activités

Activité 1 Développement ou production ?

Classez ces paquets en dependencies ou devDependencies: @nestjs/core, @nestjs/cli, typescript, bcrypt, @types/bcrypt, jest, mysql2, helmet, dotenv, prettier.

Voir le corrigé

dependencies: @nestjs/core, bcrypt, mysql2, helmet, dotenv (utilisé par data-source.ts à l'exécution). devDependencies: @nestjs/cli, typescript, @types/bcrypt (les types ne servent qu'à la compilation), jest, prettier.

Activité 2 Votre dossier de production

Dans votre projet (TP 8 ou 12) : compilez, créez un dossier release à côté, copiez-y dist, package.json et package-lock.json, lancez npm ci --omit=dev et comparez la taille de node_modules avec celle du projet (du -sh sous Linux et macOS, propriétés du dossier sous Windows). Créez une base vide, un .env de production, puis démarrez l'API et exécutez les migrations.

Voir le corrigé

Sous Windows (PowerShell) : $env:NODE_ENV="production"; node dist/main. Si l'API refuse de démarrer, lisez le message : c'est souvent une variable absente du .env (validation du chapitre 19) ou un paquet en devDependencies à tort. N'ajoutez pas release/ au dépôt Git : ajoutez-le au .gitignore.

Activité 3 Un modèle d'e-mail introuvable

Votre API du TP 9 envoie des e-mails avec des modèles src/mail/modeles/*.hbs. En production : Error: ENOENT: no such file or directory, open '/var/www/api/dist/mail/modeles/bienvenue.hbs'. Expliquez et corrigez.

Voir le corrigé

nest build ne compile que le TypeScript : les .hbs ne sont pas copiés dans dist. Dans nest-cli.json: "compilerOptions": { "deleteOutDir": true, "assets": ["mail/modeles/**/*.hbs"], "watchAssets": true } (chemins relatifs à sourceRoot, ici src). Recompilez et vérifiez la présence des fichiers dans dist/mail/modeles.

Activité 4 Lire une pile d'appels

Un collègue vous envoie : at async StagiairesService.creer (/var/www/api/dist/stagiaires/stagiaires.service.js:58:21). Que proposez-vous pour que la prochaine erreur soit plus facile à localiser ? Que faut-il vérifier dans tsconfig.json?

Voir le corrigé

Lancer l'API avec node --enable-source-maps dist/main (script start:prod, ou node_args dans PM2, leçon 20.2) ; la pile désignera alors src/stagiaires/stagiaires.service.ts et la bonne ligne. Vérifier que "sourceMap": true est présent dans tsconfig.json (c'est le cas avec nest new) et que les fichiers .map sont bien livrés avec dist.

À retenir

  • nest build compile src en JavaScript dans dist (vidé à chaque fois), migrations et scripts compris.
  • Les fichiers non TypeScript se déclarent dans assets (nest-cli.json).
  • En production : npm ci --omit=dev, sans outils de développement (152 Mo au lieu de 331 Mo ici).
  • NODE_ENV=production: pas de synchronize, schéma créé par migration:run sur le code compilé.
  • Premier administrateur par un script et des variables d'environnement, jamais par un mot de passe écrit dans le code.
  • node --enable-source-maps dist/main: des erreurs qui désignent le TypeScript.

Cet article vous a-t-il aidé ?