Projets TypeScript

Le générateur de projet TypeScript peut être utilisé pour créer une bibliothèque ou une application TypeScript moderne configurée avec les meilleures pratiques telles que les modules ECMAScript (ESM), les références de projet TypeScript, Vitest pour exécuter les tests et Biome pour le linting et le formatage.

Utilisation

Générer un projet TypeScript

Vous pouvez générer un nouveau projet TypeScript de deux manières :

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#project

yarn

yarn nx g @aws/nx-plugin:ts#project

npm

npx nx g @aws/nx-plugin:ts#project

bun

bunx nx g @aws/nx-plugin:ts#project

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

pnpm

pnpm nx g @aws/nx-plugin:ts#project --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#project --dry-run

npm

npx nx g @aws/nx-plugin:ts#project --dry-run

bun

bunx nx g @aws/nx-plugin:ts#project --dry-run

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - ts#project
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Options

Paramètre	Type	Par défaut	Description
name Requis	string	-	Nom du projet TypeScript
directory	string	packages	Répertoire parent où la bibliothèque est placée.
subDirectory	string	-	Le sous-répertoire dans lequel la bibliothèque est placée. Par défaut, il s'agit du nom de la bibliothèque.
preferInstallDependencies	boolean	true	Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir à false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du générateur

Le générateur créera la structure de projet suivante dans le répertoire <directory>/<name> :

• Répertoiresrc Code source TypeScript

  • index.ts
• package.json Manifeste du projet définissant le nom du package et les dépendances du projet
• project.json Configuration du projet et cibles de build
• tsconfig.json Configuration TypeScript de base pour ce projet (étend tsconfig.base.json à la racine de l’espace de travail)
• tsconfig.lib.json Configuration TypeScript pour votre bibliothèque (votre source d’exécution ou empaquetée)
• tsconfig.spec.json Configuration TypeScript pour vos tests
• vitest.config.mts Configuration pour Vitest

Package.json du projet

Le package.json du projet commence de manière minimale. Au fur et à mesure que vous ajoutez des dépendances d’exécution, elles sont déclarées ici (les outils de build/test partagés restent à la racine de l’espace de travail) — vous pouvez en savoir plus ci-dessous.

Vous remarquerez également quelques modifications apportées aux fichiers suivants à la racine de votre espace de travail :

• nx.json La configuration Nx est mise à jour pour configurer le plugin @nx/js/typescript pour votre projet
• tsconfig.base.json un alias TypeScript est configuré pour votre projet afin qu’il puisse être importé par d’autres projets dans votre espace de travail
• tsconfig.json une référence de projet TypeScript est ajoutée pour votre projet

Écrire du code source TypeScript

Ajoutez votre code TypeScript dans le répertoire src.

Syntaxe d’importation ESM

Puisque votre projet TypeScript est un module ES, assurez-vous d’écrire vos instructions d’importation avec la syntaxe ESM correcte, en référençant explicitement l’extension de fichier :

index.ts

import { sayHello } from './hello.js';

Références TypeScript

Même si nous utilisons TypeScript, et que sayHello est défini dans hello.ts, nous utilisons l’extension de fichier .js dans notre importation. Vous pouvez en savoir plus à ce sujet ici.

Exporter pour d’autres projets TypeScript

Le point d’entrée de votre projet TypeScript est src/index.ts. Vous pouvez ajouter des exports ici pour tout ce que vous souhaitez que d’autres projets puissent importer :

src/index.ts

export { sayHello } from './hello.js';
export * from './algorithms/index.js';

Importer le code de votre bibliothèque dans d’autres projets

Les alias TypeScript pour votre projet sont configurés dans le tsconfig.base.json de votre espace de travail, ce qui vous permet de référencer votre projet TypeScript depuis d’autres projets TypeScript :

packages/my-other-project/src/index.ts

import { sayHello } from '@my-scope/my-library';

Lorsque vous ajoutez une instruction d’importation pour un nouveau projet dans votre espace de travail pour la première fois, vous verrez probablement une erreur dans votre IDE similaire à celle ci-dessous :

Erreur d’importation

File '/path/to/my/workspace/packages/my-library/src/index.ts' is not under 'rootDir' '/path/to/my/workspace/packages/my-consumer'. 'rootDir' is expected to contain all source files.
  File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6059)
File '/path/to/my/workspace/packages/my-library/src/index.ts' is not listed within the file list of project '/path/to/my/workspace/packages/my-consumer/tsconfig.lib.json'. Projects must list all files or use an 'include' pattern.
  File is ECMAScript module because '/path/to/my/workspace/package.json' has field "type" with value "module" ts(6307)

C’est parce qu’une référence de projet n’a pas encore été configurée, et que le projet importé n’a pas encore été déclaré comme dépendance d’espace de travail dans le package.json de votre projet.

Votre espace de travail est configuré avec des générateurs de synchronisation qui gèrent les deux pour vous, vous n’avez donc pas besoin de les configurer manuellement. Exécutez simplement la commande suivante et Nx ajoutera la configuration requise :

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

 NX   The workspace is out of sync

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on, contain stale project references, or have duplicate project references.
[@aws/nx-plugin:ts#sync]: Local project dependencies are out of sync. The following workspace dependencies will be declared:
packages/my-other-project/package.json:
- @my-scope/my-library: workspace:*

Syncing the workspace...
The workspace was synced successfully!

Le générateur de synchronisation TypeScript de Nx ajoute la référence de projet, et le générateur ts#sync du plugin déclare le projet importé dans le package.json de votre projet (workspace:* lorsque le gestionnaire de packages prend en charge le protocole workspace, * sur npm et yarn classic), de sorte que le gestionnaire de packages lie le projet local lors de l’installation. Après cela, l’erreur dans votre IDE devrait disparaître et vous êtes prêt à utiliser votre bibliothèque.

Raccourci de build

Vous pouvez également simplement construire votre projet — les générateurs de synchronisation s’exécutent en premier et vous serez invité à appliquer les modifications en attente :

 NX   The workspace is out of sync

...

? Would you like to sync the identified changes to get your workspace up to date? …
Yes, sync the changes and run the tasks
No, run the tasks without syncing the changes

Sélectionnez Yes pour permettre à Nx de synchroniser votre espace de travail.

Maintenir les alias de chemin synchronisés

Si vous ajoutez des entrées compilerOptions.paths personnalisées dans le tsconfig.json d’un projet, TypeScript cesse d’hériter des alias d’espace de travail définis dans tsconfig.base.json. Le générateur caché ts#sync s’exécute avant la cible compile (configurée dans nx.json) pour copier tous les alias de base manquants dans les fichiers tsconfig.json, tsconfig.lib.json et tsconfig.app.json qui déclarent déjà paths. Pour désactiver cette fonctionnalité, supprimez @aws/nx-plugin:ts#sync de targetDefaults.compile.syncGenerators dans nx.json.

Dépendances

Chaque projet TypeScript déclare ses dépendances d’exécution tierces dans son propre package.json. Les outils de build et de test partagés entre les projets sont définis dans le package.json racine.

Pour ajouter une dépendance d’exécution à un projet, installez-la dans ce projet :

pnpm

pnpm add some-npm-package --filter my-library

yarn

yarn workspace @my-scope/my-library add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package -w packages/my-library

bun

bun add some-npm-package --cwd packages/my-library

Vous pouvez également exécuter la commande add/install simple de votre gestionnaire de packages depuis le répertoire du projet.

Pour ajouter un outil de développement partagé, installez-le à la racine de l’espace de travail :

pnpm

pnpm add -Dw some-dev-tool

yarn

yarn add -D some-dev-tool

npm

npm install --legacy-peer-deps -D some-dev-tool

bun

bun add -D some-dev-tool

Note

La règle de lint noUndeclaredDependencies de Biome impose que la source d’un projet n’importe que des packages déclarés dans son propre package.json. Les fichiers de configuration, les scripts de build et les tests sont exemptés, de sorte que les outils partagés peuvent rester à la racine.

Catalogues

Pour les gestionnaires de packages qui prennent en charge les catalogues (pnpm, yarn et bun), les générateurs enregistrent chaque version dans le catalogue et la référencent avec le protocole catalog: (par exemple "zod": "catalog:"), de sorte que le catalogue est la source unique de vérité pour les versions, quel que soit le projet qui déclare la dépendance. Cela vous aide à suivre une politique de version unique, en évitant les conflits de types et les copies multiples de packages dans les bundles de déploiement.

Lorsque vous ajoutez vous-même une nouvelle dépendance, conservez-la également dans le catalogue :

pnpm

L’espace de travail définit catalogMode: strict, donc pnpm add enregistre la version dans le catalogue et la référence automatiquement — aucune étape supplémentaire.

pnpm add some-npm-package --filter my-library

yarn

Le protocole catalog: de yarn ne fait que référencer une entrée de catalogue existante — il ne peut pas en créer une — donc enregistrez d’abord la version.

1. Ajoutez la version sous catalog dans .yarnrc.yml :

   .yarnrc.yml

   catalog:
     some-npm-package: ^1.0.0

2. Référencez-la depuis le projet :

   yarn workspace @my-scope/my-library add some-npm-package@catalog:

bun

Le protocole catalog: de bun ne fait que référencer une entrée de catalogue existante — il ne peut pas en créer une — donc enregistrez d’abord la version.

1. Ajoutez la version sous catalog dans le package.json racine :

   package.json

   {
     "catalog": {
       "some-npm-package": "^1.0.0"
     }
   }

2. Référencez-la depuis le projet :

   bun add some-npm-package@catalog: --cwd packages/my-library

Aligner les versions sur npm

npm n’a pas de fonctionnalité de catalogue, donc les versions sont déclarées directement dans chaque package.json. Pour les maintenir cohérentes entre les projets, nous recommandons syncpack (npx syncpack lint).

Désactiver les catalogues

Les catalogues sont activés par défaut. Pour les désactiver, créez votre espace de travail avec --catalog false :

pnpm

pnpm create @aws/nx-workspace my-project --catalog false

yarn

yarn create @aws/nx-workspace my-project --catalog false

npm

npm create @aws/nx-workspace -- my-project --catalog false

bun

bun create @aws/nx-workspace my-project --catalog false

Ou définissez-le dans aws-nx-plugin.config.mts à tout moment :

aws-nx-plugin.config.mts

export default {
  packageManager: {
    catalogs: false,
  },
} satisfies AwsNxPluginConfig;

Avec les catalogues désactivés, les générateurs écrivent les versions de dépendances directement dans le package.json de chaque projet, et maintenir les versions alignées entre les projets est de votre responsabilité.

Déclarer toutes les dépendances à la racine

Si vous préférez déclarer chaque dépendance uniquement dans le package.json racine (pas de déclarations de dépendances par projet), désactivez la règle de lint dans le biome.json de l’espace de travail :

biome.json

{
  "linter": {
    "rules": {
      "correctness": {
        "noUndeclaredDependencies": "off"
      }
    }
  }
}

Les projets résolvent les packages installés à la racine au moment du build, donc tout se construit toujours — vous renoncez aux manifestes par projet comme enregistrement précis des dépendances de chaque projet (ce qui importe si vous publiez ultérieurement un projet ou divisez le dépôt).

Code d’exécution

Lorsque vous utilisez votre projet TypeScript comme code d’exécution (par exemple comme gestionnaire pour une fonction AWS Lambda), il est recommandé d’utiliser un outil tel que Rolldown pour regrouper votre projet, car cela peut effectuer un tree-shaking pour garantir que seules les dépendances que votre projet référence réellement sont incluses.

Vous pouvez y parvenir en ajoutant une cible telle que la suivante à votre fichier project.json :

{
  ...
  "targets": {
    ...
    "bundle": {
      "cache": true,
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/packages/my-library/bundle"],
      "options": {
        "command": "rolldown -c rolldown.config.ts"
      }
    },
  },
}

Et en ajoutant le fichier rolldown.config.ts comme suit :

rolldown.config.ts

import { defineConfig } from 'rolldown';

export default defineConfig([
  {
    input: 'src/index.ts',
    output: {
      file: '../../dist/packages/my-library/bundle/index.js',
      format: 'cjs',
      codeSplitting: false,
    },
  },
]);

Configuration du bundle

Notez que dans la cible ci-dessus, nous avons choisi src/index.ts comme point d’entrée pour le bundle, ce qui signifie que le code exporté depuis ce fichier sera inclus dans le bundle, ainsi que toutes ses dépendances.

Fonctions Lambda

Si vous construisez une fonction AWS Lambda, consultez le générateur ts#lambda-function car il configure le bundling pour vous, ainsi que la génération d’infrastructure et l’ajout d’observabilité et de sécurité des types.

Construction

Votre projet TypeScript est configuré avec une cible build (définie dans project.json), que vous pouvez exécuter via :

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

Où <project-name> est le nom complet de votre projet.

La cible build compilera, lintera et testera votre projet.

La sortie de build se trouve dans le dossier dist racine de votre espace de travail, à l’intérieur d’un répertoire pour votre package et votre cible, par exemple dist/packages/<my-library>/tsc

Pour construire tous les projets de votre espace de travail, exécutez :

pnpm

pnpm nx run-many --target build

yarn

yarn nx run-many --target build

npm

npx nx run-many --target build

bun

bunx nx run-many --target build

Ou utilisez la commande raccourcie :

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Tests

Vitest est configuré pour tester votre projet.

Écrire des tests

Les tests doivent être écrits dans des fichiers .spec.ts ou .test.ts, co-localisés dans le dossier src de votre projet.

Par exemple :

• Répertoiresrc

  • hello.ts Code source de la bibliothèque
  • hello.spec.ts Tests pour hello.ts

Vitest fournit une syntaxe similaire à Jest pour définir les tests, avec des utilitaires tels que describe, it, test et expect.

hello.spec.ts

import { sayHello } from './hello.js';

describe('sayHello', () => {

  it('should greet the caller', () => {
    expect(sayHello('Darth Vader')).toBe('Hello, Darth Vader!');
  });

});

Pour plus de détails sur la façon d’écrire des tests et des fonctionnalités telles que le mocking de dépendances, consultez la documentation Vitest

Exécuter les tests

Les tests s’exécuteront dans le cadre de la cible build pour votre projet, mais vous pouvez également les exécuter séparément en exécutant la cible test :

pnpm

pnpm nx test <project-name>

yarn

yarn nx test <project-name>

npm

npx nx test <project-name>

bun

bunx nx test <project-name>

Vous pouvez exécuter un test individuel ou une suite de tests en utilisant le flag -t de Vitest. Passez-le après un séparateur -- pour que Nx le transmette à Vitest plutôt que de le consommer comme sa propre option --target :

pnpm

pnpm nx test <project-name> -- -t 'sayHello'

yarn

yarn nx test <project-name> -- -t 'sayHello'

npm

npx nx test <project-name> -- -t 'sayHello'

bun

bunx nx test <project-name> -- -t 'sayHello'

Intégration VSCode

Si vous êtes un utilisateur de VSCode, nous recommandons d’installer l’extension Vitest Runner for VSCode that actually works, qui vous permet d’exécuter, surveiller ou déboguer des tests depuis votre IDE.

Linting

Les projets TypeScript utilisent Biome pour le linting et le formatage. Biome est configuré dans le fichier biome.json à la racine de l’espace de travail — les modifications apportées à celui-ci s’appliquent à tous les projets TypeScript de votre espace de travail et garantissent la cohérence.

Exécuter le linter

Pour invoquer le linter pour vérifier votre projet, vous pouvez exécuter la cible lint.

pnpm

pnpm nx lint <project-name>

yarn

yarn nx lint <project-name>

npm

npx nx lint <project-name>

bun

bunx nx lint <project-name>

Corriger les problèmes de lint

La majorité des problèmes de linting ou de formatage peuvent être corrigés automatiquement en exécutant avec l’argument --configuration=fix.

pnpm

pnpm nx lint <project-name> --configuration=fix

yarn

yarn nx lint <project-name> --configuration=fix

npm

npx nx lint <project-name> --configuration=fix

bun

bunx nx lint <project-name> --configuration=fix

De même, si vous souhaitez corriger tous les problèmes de lint dans tous les packages de votre espace de travail, vous pouvez exécuter :

pnpm

pnpm nx run-many --target lint --all --configuration=fix

yarn

yarn nx run-many --target lint --all --configuration=fix

npm

npx nx run-many --target lint --all --configuration=fix

bun

bunx nx run-many --target lint --all --configuration=fix

Commande raccourcie

Cela a une commande raccourcie depuis la racine de votre espace de travail :

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Ignorer les problèmes de lint

Pour éviter que les problèmes de linting ne vous ralentissent pendant le développement (en particulier si vous avez des problèmes non corrigeables automatiquement dans votre projet), vous pouvez exécuter un build avec la configuration skip-lint :

pnpm

pnpm nx run-many --target build --configuration=skip-lint

yarn

yarn nx run-many --target build --configuration=skip-lint

npm

npx nx run-many --target build --configuration=skip-lint

bun

bunx nx run-many --target build --configuration=skip-lint

Cela ignore entièrement la cible lint pendant le build.

Commande raccourcie

Cela a une commande raccourcie depuis la racine de votre espace de travail :

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint