Aller au contenu

Créer un service NestJS

Vue d'ensemble

Ce guide explique comment créer un nouveau service backend NestJS dans le monorepo Feelbat.

Les services backend sont créés dans apps/api et sont gérés par Nx.

Objectif

À la fin de ce guide, vous serez capable de :

  • Générer un nouveau service NestJS.
  • Adapter sa configuration Nx.
  • Configurer ses scripts de build.
  • Supprimer la configuration Webpack inutile.
  • Typer et valider les variables d'environnement.

Créer le service

Utilisez la commande suivante :

pnpm nest:app apps/api/<service-name>

Exemple :

pnpm nest:app apps/api/my-service

Cette commande génère une nouvelle application NestJS dans apps/api.

Supprimer la configuration Webpack

Par défaut, la génération du service crée un fichier webpack.config.js.

Ce fichier n'est pas utilisé dans la configuration Feelbat et peut être supprimé.

rm apps/api/<service-name>/webpack.config.js

Warning

Ne conservez pas le fichier webpack.config.js si le service utilise la configuration standard décrite dans ce guide.

Configurer le projet Nx

Ouvrez le fichier project.json du service généré.

apps/api/<service-name>/project.json

Modifiez le champ name pour utiliser le nom Nx du projet :

{
  "name": "@feelbat/<service-name>"
}

Remplacez ensuite la section targets par la configuration suivante.

{
  "targets": {
    "build": {
      "executor": "nx:run-commands",
      "outputs": ["{projectRoot}/dist/"],
      "dependsOn": ["^build"],
      "options": {
        "cwd": "apps/api/<service-name>",
        "command": "pnpm build:prod"
      },
      "configurations": {
        "development": {
          "command": "pnpm build:dev"
        }
      }
    },
    "serve": {
      "executor": "@nx/js:node",
      "defaultConfiguration": "development",
      "continuous": true,
      "options": {
        "buildTarget": "@feelbat/<service-name>:build",
        "runBuildTargetDependencies": false
      },
      "configurations": {
        "development": {
          "buildTarget": "@feelbat/<service-name>:build:development"
        },
        "production": {
          "buildTarget": "@feelbat/<service-name>:build:production"
        }
      }
    }
  }
}

Tip

Remplacez toutes les occurrences de <service-name> par le nom réel du service.

Configurer le package.json

Ouvrez le fichier package.json du service.

apps/api/<service-name>/package.json

Modifiez le champ name pour utiliser le même nom que dans project.json.

{
  "name": "@feelbat/<service-name>"
}

Ajoutez ensuite les scripts de build suivants :

{
  "scripts": {
    "build:dev": "nest build -p tsconfig.app.json",
    "build:prod": "nest build -p tsconfig.app.json"
  }
}

Ajouter les dépendances nécessaires

La validation des variables d'environnement repose sur Zod. Si la dépendance n'est pas déjà présente dans le projet, ajoutez-la au package.json.

Comme les versions des dépendances externes sont centralisées dans le monorepo, utilisez catalog:*.

{
  "dependencies": {
    "zod": "catalog:*"
  }
}

Tip

Consultez le guide Gestion des dépendances pour comprendre la différence entre catalog:* et workspace:*, ainsi que les bonnes pratiques d'utilisation de pnpm dans le monorepo.

Typer les variables d'environnement

Créez le fichier suivant :

apps/api/<service-name>/src/env.d.ts

Ce fichier permet de déclarer la shape de process.env côté TypeScript.

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      // Container Configuration
      CONTAINER_NAME: string;
      MS_REMOTE_ACTION_PORT: string;
      MS_ENV: string;

      // Database rs-manager
      RS_MANAGER_DB_HOST: string;
      RS_MANAGER_DB_PORT: string;
      RS_MANAGER_DB_USERNAME: string;
      RS_MANAGER_DB_PASSWORD: string;

      // Kafka
      BROKER_HOST: string;
      BROKER_PORT: string;
      CONSUMER_ID: string;
      PRODUCER_ID: string;
    }
  }
}

export {};

Note

Ce fichier améliore le typage TypeScript, mais il ne valide pas les variables à l'exécution. La validation runtime est faite avec Zod dans l'étape suivante.

Valider les variables d'environnement

Créez le fichier suivant :

apps/api/<service-name>/src/shared/utils/env.ts

Ce fichier valide les variables d'environnement avec Zod au démarrage du service.

import { z } from "zod";

const EnvSchema = z.object({
  // Container Configuration
  CONTAINER_NAME: z.string(),
  MS_REMOTE_ACTION_PORT: z.coerce.number().min(1).max(65535),
  MS_ENV: z.string(),

  // Database rs-manager
  RS_MANAGER_DB_HOST: z.string(),
  RS_MANAGER_DB_PORT: z.coerce.number().min(1).max(65535),
  RS_MANAGER_DB_USERNAME: z.string(),
  RS_MANAGER_DB_PASSWORD: z.string(),

  // Kafka
  BROKER_HOST: z.string(),
  BROKER_PORT: z.coerce.number().min(1).max(65535),
  CONSUMER_ID: z.string(),
  PRODUCER_ID: z.string(),
});

export const env = EnvSchema.parse(process.env);

Créez ensuite un fichier d'export :

apps/api/<service-name>/src/shared/utils/index.ts

export * from "./env";

Utiliser les variables validées

Une fois le fichier env.ts créé, le service ne doit plus utiliser directement process.env.

Préférez :

import { env } from "./shared/utils";

const port = env.MS_REMOTE_ACTION_PORT;

Au lieu de :

const port = process.env.MS_REMOTE_ACTION_PORT;

Warning

Utiliser directement process.env contourne la validation Zod et peut introduire des erreurs difficiles à détecter.

Vérifier le service

Lancez le service en développement :

pnpm nx run @feelbat/<service-name>:serve:development

Si la configuration est correcte, Nx construit puis lance le service.

À retenir

  • Les services NestJS sont créés dans apps/api.
  • Le fichier webpack.config.js généré par défaut doit être supprimé.
  • Le nom du projet doit être identique dans project.json et package.json.
  • Les targets Nx doivent utiliser la configuration standard du monorepo.
  • Les variables d'environnement doivent être typées avec env.d.ts et validées avec Zod.
  • Le code applicatif doit utiliser env.<VARIABLE> plutôt que process.env.<VARIABLE>.