Espaces de travail

Nest dispose de deux modes pour organiser le code :

mode standard : utile pour construire des applications individuelles axées sur un projet, avec leurs propres dépendances et paramètres, sans avoir besoin d’optimiser le partage de modules ou d’optimiser des constructions complexes. C’est le mode par défaut.
mode monorepo : ce mode traite les artefacts de code comme faisant partie d’un léger monorepo, et peut être plus approprié pour des équipes de développeurs et/ou des environnements multi-projets. Il automatise certaines parties du processus de construction pour faciliter la création et la composition de composants modulaires, promouvoir la réutilisation du code, faciliter les tests d’intégration, rendre plus facile le partage d’artefacts à l’échelle du projet comme les règles eslint et d’autres politiques de configuration, et est plus facile à utiliser que des alternatives comme les sous-modules GitHub. Le mode monorepo utilise le concept d’un espace de travail, représenté dans le fichier nest-cli.json, pour coordonner la relation entre les composants du monorepo.

Il est important de noter que pratiquement toutes les fonctionnalités de Nest sont indépendantes de votre mode d’organisation du code. Le seul effet de ce choix est la manière dont vos projets sont composés et comment les artefacts de construction sont générés. Toutes les autres fonctionnalités, de la CLI aux modules principaux en passant par les modules d’extension, fonctionnent de la même manière dans les deux modes.

De plus, vous pouvez facilement passer du mode standard au mode monorepo à tout moment, vous pouvez donc différer cette décision jusqu’à ce que les avantages de l’un ou l’autre des approches deviennent plus clairs.

Mode standard

Lorsque vous exécutez nest new, un nouveau projet est créé pour vous en utilisant un schéma intégré. Nest effectue les opérations suivantes :

Crée un nouveau dossier, correspondant à l’argument name que vous fournissez à nest new.
Remplit ce dossier avec des fichiers par défaut correspondant à une application Nest minimale. Vous pouvez examiner ces fichiers dans le dépôt typescript-starter.
Fournit des fichiers supplémentaires tels que nest-cli.json, package.json et tsconfig.json qui configurent et activent divers outils pour compiler, tester et servir votre application.

À partir de là, vous pouvez modifier les fichiers de démarrage, ajouter de nouveaux composants, ajouter des dépendances (par exemple, npm install), et autrement développer votre application comme couvert dans le reste de cette documentation.

Mode monorepo

Pour activer le mode monorepo, vous commencez avec une structure en mode standard, et ajoutez des projets. Un projet peut être une application complète (que vous ajoutez à l’espace de travail avec la commande nest generate app) ou une bibliothèque (que vous ajoutez à l’espace de travail avec la commande nest generate library). Nous discuterons des détails de ces types de composants de projet spécifiques ci-dessous. Le point clé à noter maintenant est que c’est l’acte d’ajouter un projet à une structure en mode standard existante qui la convertit en mode monorepo. Regardons un exemple.

Si nous exécutons :

$ nest new my-project

Nous avons construit une structure en mode standard, avec une structure de dossiers qui ressemble à ceci :

node_modules
Répertoiresrc
- app.controller.ts
- app.module.ts
- app.service.ts
- main.ts
nest-cli.json
package.json
tsconfig.json
.eslintrc.js

Nous pouvons convertir cela en structure de mode monorepo comme suit :

$ cd my-project
$ nest generate app my-app

À ce stade, nest convertit la structure existante en une structure en mode monorepo. Cela entraîne quelques changements importants. La structure de dossiers ressemble maintenant à ceci :

Répertoireapps
- Répertoiremy-app
  - Répertoiresrc
    app.controller.ts
    app.module.ts
    app.service.ts
    main.ts
  - tsconfig.app.json
- Répertoiremy-project
  - Répertoiresrc
    app.controller.ts
    app.module.ts
    app.service.ts
    main.ts
  - tsconfig.app.json
nest-cli.json
package.json
tsconfig.json
.eslintrc.js

Le schéma generate app a réorganisé le code - déplaçant chaque projet d’application sous le dossier apps, et ajoutant un fichier tsconfig.app.json spécifique au projet dans le dossier racine de chaque projet. Notre application originale my-project est devenue le projet par défaut pour le monorepo, et est maintenant un pair avec le my-app nouvellement ajouté, situé sous le dossier apps.

Projets d’espace de travail

Un monorepo utilise le concept d’un espace de travail pour gérer ses entités membres. Les espaces de travail sont composés de projets. Un projet peut être soit :

une application : une application Nest complète comprenant un fichier main.ts pour démarrer l’application. En dehors des considérations de compilation et de construction, un projet de type application au sein d’un espace de travail est fonctionnellement identique à une application dans une structure en mode standard.
une bibliothèque : une bibliothèque est un moyen de regrouper un ensemble de fonctionnalités généralistes (modules, fournisseurs, contrôleurs, etc.) qui peuvent être utilisés dans d’autres projets. Une bibliothèque ne peut pas s’exécuter seule et n’a pas de fichier main.ts. Lisez-en plus sur les bibliothèques ici.

Tous les espaces de travail ont un projet par défaut (qui devrait être un projet de type application). Celui-ci est défini par la propriété de niveau supérieur "root" dans le fichier nest-cli.json, qui pointe vers la racine du projet par défaut (voir les propriétés CLI pour plus de détails). En général, c’est l’application en mode standard avec laquelle vous avez commencé, puis convertie en monorepo en utilisant nest generate app. Lorsque vous suivez ces étapes, cette propriété est remplie automatiquement.

Les projets par défaut sont utilisés par les commandes nest comme nest build et nest start lorsqu’un nom de projet n’est pas fourni.

Par exemple, dans la structure de monorepo ci-dessus, l’exécution de :

$ nest start

démarrera l’application my-project. Pour démarrer my-app, nous utiliserions :

$ nest start my-app

Applications

Les projets de type application, ou ce que nous pourrions informellement appeler simplement “applications”, sont des applications Nest complètes que vous pouvez exécuter et déployer. Vous générez un projet de type application avec nest generate app.

Cette commande génère automatiquement un squelette de projet, y compris les dossiers standards src et test du dépôt typescript-starter. Contrairement au mode standard, un projet d’application dans un monorepo n’a pas de dépendances de paquet (package.json) ni d’autres artefacts de configuration de projet comme .prettierrc et .eslintrc.js. Au lieu de cela, les dépendances et les fichiers de configuration à l’échelle du monorepo sont utilisés.

Cependant, le schéma génère un fichier de configuration de projet spécifique tsconfig.app.json dans le dossier racine du projet. Ce fichier de configuration définit automatiquement les options de construction appropriées, y compris le paramètre de dossier de sortie de la compilation. Le fichier prolonge le fichier de configuration tsconfig.json (monorepo), vous pouvez donc gérer les paramètres globaux à l’échelle du monorepo, mais les remplacer si nécessaire au niveau du projet.

Bibliothèques

Comme mentionné, les projets de type bibliothèque, ou simplement “bibliothèques”, sont des packages de composants Nest qui doivent être composés dans des applications pour s’exécuter. Vous générez un projet de type bibliothèque avec nest generate library. Décider ce qui appartient à une bibliothèque est une décision de conception architecturale. Nous discutons des bibliothèques en profondeur dans le chapitre bibliothèques.

Propriétés de la CLI

Nest conserve les métadonnées nécessaires pour organiser, construire et déployer des projets structurés en standard et en monorepo dans le fichier nest-cli.json. Nest ajoute et met à jour automatiquement ce fichier lorsque vous ajoutez des projets, donc vous n’avez généralement pas à y penser ou à éditer son contenu. Cependant, il y a quelques paramètres que vous pouvez souhaiter modifier manuellement, il est donc utile d’avoir une compréhension d’ensemble du fichier.

Après avoir exécuté les étapes ci-dessus pour créer un monorepo, notre fichier nest-cli.json ressemble à ceci :

{
  "collection": "@nestjs/schematics",
  "sourceRoot": "apps/my-project/src",
  "monorepo": true,
  "root": "apps/my-project",
  "compilerOptions": {
    "webpack": true,
    "tsConfigPath": "apps/my-project/tsconfig.app.json"
  },
  "projects": {
    "my-project": {
      "type": "application",
      "root": "apps/my-project",
      "entryFile": "main",
      "sourceRoot": "apps/my-project/src",
      "compilerOptions": {
        "tsConfigPath": "apps/my-project/tsconfig.app.json"
      }
    },
    "my-app": {
      "type": "application",
      "root": "apps/my-app",
      "entryFile": "main",
      "sourceRoot": "apps/my-app/src",
      "compilerOptions": {
        "tsConfigPath": "apps/my-app/tsconfig.app.json"
      }
    }
  }
}

Le fichier est divisé en sections :

une section globale avec des propriétés de niveau supérieur contrôlant les paramètres standards et les paramètres de monorepo
une propriété de niveau supérieur ("projects") avec des métadonnées sur chaque projet. Cette section n’est présente que pour les structures en mode monorepo.

Les propriétés de niveau supérieur sont les suivantes :

"collection" : pointe vers la collection de schémas utilisée pour générer des composants ; vous ne devez généralement pas changer cette valeur.
"sourceRoot" : pointe vers la racine du code source pour le projet unique dans les structures en mode standard, ou le projet par défaut dans les structures en mode monorepo.
"compilerOptions" : une carte avec des clés spécifiant les options du compilateur et des valeurs spécifiant le paramètre de l’option ; voir détails ci-dessous.
"generateOptions" : une carte avec des clés spécifiant les options de génération globales et des valeurs spécifiant le paramètre de l’option ; voir détails ci-dessous.
"monorepo" : (monorepo uniquement) pour une structure en mode monorepo, cette valeur est toujours true.
"root" : (monorepo uniquement) pointe vers la racine du projet par défaut.

Options du compilateur global

Ces propriétés spécifient le compilateur à utiliser ainsi que diverses options qui affectent toute étape de compilation, que ce soit dans le cadre de nest build ou nest start, et quel que soit le compilateur, que ce soit tsc ou webpack.

Nom de la propriété	Type de valeur de la propriété	Description
`webpack`	boolean	Si `true`, utilisez le compilateur webpack. Si `false` ou non présent, utilisez `tsc`. En mode monorepo, la valeur par défaut est `true`.
`tsConfigPath`	string	(monorepo uniquement) Pointe vers le fichier contenant les paramètres `tsconfig.json` qui seront utilisés lorsque `nest build` ou `nest start` est appelé sans une option `project`.
`webpackConfigPath`	string	Pointe vers un fichier d’options webpack. Si non spécifié, Nest recherche le fichier `webpack.config.js`.
`deleteOutDir`	boolean	Si `true`, chaque fois que le compilateur est invoqué, il supprime d’abord le répertoire de sortie de compilation.
`assets`	array	Permet de distribuer automatiquement des actifs non-TypeScript chaque fois qu’une étape de compilation commence.
`watchAssets`	boolean	Si `true`, exécutez en mode veille, surveillant tous les actifs non-TypeScript.
`manualRestart`	boolean	Si `true`, active le raccourci `rs` pour redémarrer manuellement le serveur. Valeur par défaut `false`.
`builder`	string/object	Indique à la CLI quel `builder` utiliser pour compiler le projet (`tsc`, `swc` ou `webpack`).
`typeCheck`	boolean	Si `true`, active la vérification de type pour les projets basés sur SWC (lorsque `builder` est `swc`).

Options de génération globales

Ces propriétés spécifient les options de génération par défaut à utiliser avec la commande nest generate.

Nom de la propriété	Type de valeur de la propriété	Description
`spec`	boolean ou objet	Si la valeur est un booléen, une valeur de `true` active la génération de `spec` par défaut et une valeur de `false` la désactive. Un drapeau passé sur la ligne de commande de la CLI remplace ce paramètre.
`flat`	boolean	Si vrai, toutes les commandes de génération généreront une structure plate.

L’exemple suivant utilise une valeur booléenne pour spécifier que la génération de fichiers de spécification doit être désactivée par défaut pour tous les projets :

{
  "generateOptions": {
    "spec": false
  }
}

L’exemple suivant utilise une valeur booléenne pour spécifier que la génération de fichiers plats doit être la valeur par défaut pour tous les projets :

{
  "generateOptions": {
    "flat": true
  }
}

Dans l’exemple suivant, la génération de fichiers de spécification est désactivée uniquement pour les schémas de service :

{
  "generateOptions": {
    "spec": {
      "service": false
    }
  }
}

Warning Lorsque vous spécifiez le spec en tant qu’objet, la clé pour le schéma de génération ne prend actuellement pas en charge la gestion automatisée des alias. Cela signifie que la spécification d’une clé par exemple service: false et l’essai de générer un service via l’alias s, le spécifierait toujours. Pour vous assurer que les deux fonctionnent comme prévu, spécifiez à la fois le nom normal de la commande ainsi que l’alias.

Options de génération spécifiques au projet

En plus de fournir des options de génération globales, vous pouvez également spécifier des options de génération spécifiques au projet. Les options de génération spécifiques au projet suivent le même format que les options de génération globales, mais sont spécifiées directement sur chaque projet.

Les options de génération spécifiques à un projet remplacent les options de génération globales.

{
  "projects": {
    "cats-project": {
      "generateOptions": {
        "spec": {
          "service": false
        }
      }
    }
  }
}

Warning L’ordre de priorité pour les options de génération est le suivant. Les options spécifiées sur la ligne de commande de la CLI ont la priorité sur les options spécifiques au projet. Les options spécifiques au projet remplacent les options globales.

Compilateur spécifié

La raison des différents compilateurs par défaut est que pour les projets plus importants (par exemple, plus typiques dans un monorepo), webpack peut avoir des avantages significatifs en termes de temps de construction et de production d’un seul fichier regroupant tous les composants du projet. Si vous souhaitez générer des fichiers individuels, définissez webpack sur false, ce qui amènera le processus de construction à utiliser tsc (ou swc).

Options Webpack

Le fichier d’options webpack peut contenir des options de configuration webpack standards. Par exemple, pour indiquer à webpack de regrouper node_modules (qui sont exclus par défaut), ajoutez ce qui suit à webpack.config.js :

module.exports = {
  externals: [],
};

Comme le fichier de configuration webpack est un fichier JavaScript, vous pouvez même exposer une fonction qui prend des options par défaut et retourne un objet modifié :

module.exports = function(options) {
  return {
    ...options,
    externals: [],
  };
};

Actifs

La compilation TypeScript distribue automatiquement la sortie du compilateur (.js et .d.ts files) vers le répertoire de sortie spécifié. Il peut également être pratique de distribuer des fichiers non-TypeScript, comme des fichiers .graphql, des images, des fichiers .html et d’autres actifs. Cela vous permet de traiter nest build (et toute étape de compilation initiale) comme une étape de développement légère, où vous pouvez modifier des fichiers non TypeScript et compiler/tester de manière itérative.

Les actifs doivent être situés dans le dossier src sinon ils ne seront pas copiés.

La valeur de la clé assets doit être un tableau d’éléments spécifiant les fichiers à distribuer. Les éléments peuvent être des chaînes simples avec des spécifications de fichiers de type glob, par exemple :

"assets": [
  "**/*.graphql"
],
"watchAssets": true,

Pour un contrôle plus fin, les éléments peuvent être des objets avec les clés suivantes :

include : spécifications de fichiers de type glob pour les actifs à distribuer
exclude : spécifications de fichiers de type glob pour les actifs à exclure de la liste include
outDir : une chaîne spécifiant le chemin (relatif au dossier racine) où les actifs doivent être distribués. Par défaut, cela correspond au même répertoire de sortie configuré pour la sortie du compilateur.
watchAssets : booléen ; si true, exécute en mode veille surveillant les actifs spécifiés

Par exemple :

"assets": [
  {
    "include": "**/*.graphql",
    "exclude": "**/omitted.graphql",
    "watchAssets": true
  }
],

Warning La définition de watchAssets dans une propriété de compilerOptions de niveau supérieur remplace tous les paramètres watchAssets dans la propriété assets.

Propriétés de projet

Cet élément n’existe que pour les structures en mode monorepo. Vous ne devez généralement pas modifier ces propriétés, car elles sont utilisées par Nest pour localiser les projets et leurs options de configuration au sein du monorepo.