Projets TypeScript

Le générateur de projet TypeScript permet de créer une bibliothèque ou une application moderne TypeScript 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 :

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

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

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.

Résultat 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 de projet définissant le nom du package du projet et les dépendances
• project.json Configuration du projet et cibles de build
• tsconfig.json Configuration TypeScript de base pour ce projet (étend le tsconfig.base.json racine du workspace)
• tsconfig.lib.json Configuration TypeScript pour votre bibliothèque (code d’exécution ou source 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 minimal. 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 du workspace) — vous pouvez en savoir plus ci-dessous.

Vous remarquerez également des modifications dans les fichiers suivants à la racine de votre workspace :

• 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 de votre workspace
• tsconfig.json Une référence de projet TypeScript est ajoutée pour votre projet

Écriture du code source TypeScript

Ajoutez votre code TypeScript dans le répertoire src.

Syntaxe d’import ESM

Comme votre projet TypeScript est un module ES, assurez-vous d’écrire vos instructions d’import 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 .js dans notre import. Vous pouvez en savoir plus ici.

Export pour d’autres projets TypeScript

Le point d’entrée de votre projet TypeScript est src/index.ts. Vous pouvez ajouter ici des exports pour tout élément que vous souhaitez rendre importable par d’autres projets :

src/index.ts

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

Importation de votre bibliothèque dans d’autres projets

Les alias TypeScript pour votre projet sont configurés dans le tsconfig.base.json de votre workspace, ce qui 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’import pour un nouveau projet dans votre workspace pour la première fois, vous verrez probablement une erreur dans votre IDE similaire à celle-ci :

Erreur d’import

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)

Cela est dû à l’absence de configuration d’une référence de projet, et le projet importé n’a pas encore été déclaré comme dépendance de workspace dans le package.json de votre projet.

Votre workspace 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 nécessaire :

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 pourrez utiliser votre bibliothèque.

Raccourci de compilation

Vous pouvez aussi simplement builder 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 workspace.

Maintenir les alias de chemins synchronisés

Si vous ajoutez des entrées compilerOptions.paths personnalisées dans le tsconfig.json d’un projet, TypeScript cesse d’hériter les alias du workspace 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 du workspace :

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 garantit que le code 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, évitant ainsi 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

Le workspace définit catalogMode: strict, de sorte que 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ésactivation des catalogues

Les catalogues sont activés par défaut. Pour les désactiver, créez votre workspace 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 configurez-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 il est de votre responsabilité de maintenir les versions alignées entre les projets.

Déclarer toutes les dépendances à la racine

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

biome.json

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

Les projets résolvent les packages installés à la racine au moment du build, donc tout se compile 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 comme Rolldown pour empaqueter votre projet, car cela permet un tree-shaking pour n’inclure que les dépendances réellement référencées par votre projet.

Vous pouvez y parvenir en ajoutant une cible comme celle-ci dans 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',
      inlineDynamicImports: true,
    },
  },
]);

Configuration du bundle

Notez que dans la cible ci-dessus, nous avons choisi src/index.ts comme point d’entrée du 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 développez une fonction AWS Lambda, consultez le générateur ts#lambda-function qui configure l’empaquetage pour vous, ainsi que la génération d’infrastructure et l’ajout d’observabilité et de type-safety.

Build

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 qualifié complet de votre projet.

La cible build compilera, linttera et testera votre projet.

Le résultat du build se trouve dans le dossier dist racine de votre workspace, dans un répertoire spécifique à votre package et à la cible, par exemple dist/packages/<my-library>/tsc

Pour builder tous les projets de votre workspace, 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.

Écriture 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 comme 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 l’écriture de tests et des fonctionnalités comme le mocking de dépendances, consultez la documentation Vitest

Exécution des tests

Les tests s’exécuteront dans le cadre de la cible build de votre projet, mais vous pouvez aussi les exécuter séparément via 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 utilisez VSCode, nous recommandons d’installer l’extension Vitest Runner for VSCode that actually works, qui permet d’exécuter, surveiller ou déboguer les tests depuis votre IDE.

Linting

Les projets TypeScript utilisent Biome pour le linting et le formatage. Biome est configuré dans le fichier racine biome.json du workspace — les modifications s’appliquent à tous les projets TypeScript du workspace et assurent la cohérence.

Exécution du linter

Pour invoquer le linter et vérifier votre projet, exécutez 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>

Correction des problèmes de lint

La majorité des problèmes de lint 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, pour corriger tous les problèmes de lint dans tous les packages de votre workspace, exécutez :

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 abrégée

Ceci a une commande raccourcie depuis la racine de votre workspace :

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 lint 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 complètement la cible lint pendant le build.

Commande abrégée

Ceci a une commande raccourcie depuis la racine de votre workspace :

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint