Projets TypeScript

Le générateur de projets TypeScript permet de créer une bibliothèque ou une application moderne TypeScript configurée avec les meilleures pratiques comme les Modules ECMAScript (ESM), les références de projet TypeScript, Vitest pour exécuter les tests et ESLint pour l’analyse statique.

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	-	Library name.
directory	string	packages	Parent directory where the library is placed.
subDirectory	string	-	The sub directory the lib is placed in. By default this is the library name.

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
• project.json Configuration du projet et cibles de build
• tsconfig.json Configuration TypeScript de base pour ce projet (étend tsconfig.base.json à la 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
• vite.config.ts Configuration pour Vitest
• eslint.config.mjs Configuration pour ESLint

Astuce

Remarquez qu’aucun fichier package.json n’est créé pour ce projet ! Vous pouvez découvrir pourquoi 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
• tsconfig.json Une référence de projet TypeScript est ajoutée pour votre projet

Écrire du code 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’utiliser la syntaxe ESM correcte dans vos imports, en spécifiant explicitement l’extension de fichier :

index.ts

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

Note

Bien que nous utilisions TypeScript et que sayHello soit défini dans hello.ts, nous utilisons l’extension .js dans notre import. Vous pouvez en savoir plus ici.

Exporter pour d’autres projets TypeScript

Le point d’entrée de votre projet TypeScript est src/index.ts. Vous pouvez y ajouter des exports pour tous les éléments que d’autres projets devraient pouvoir importer :

src/index.ts

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

Importer votre bibliothèque dans d’autres projets

Les alias TypeScript pour votre projet sont configurés dans tsconfig.base.json à la racine du workspace, ce qui permet de référencer votre projet TypeScript depuis d’autres projets :

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

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

Note

Les alias pour vos projets TypeScript commencent par : plutôt que le @ traditionnel, pour éviter les conflits de noms entre les packages locaux de votre workspace et les packages distants sur NPM.

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

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)

Cela signifie qu’une référence de projet n’a pas encore été configurée.

Les projets TypeScript sont préconfigurés avec le générateur Nx TypeScript Sync, vous évitant de configurer manuellement les références. Exécutez simplement la commande suivante pour ajouter la configuration requise :

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Après cela, l’erreur dans votre IDE devrait disparaître et vous pourrez utiliser votre bibliothèque.

Astuce

Vous pouvez aussi simplement build votre projet et vous verrez un message comme :

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on or contain outdated project references.

This will result in an error in CI.

? 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 mettre à jour vos références de projet.

Dépendances

Vous remarquerez que votre projet TypeScript n’a pas de fichier package.json, ce qui peut surprendre si vous avez l’habitude des monorepos TypeScript traditionnels.

Pour ajouter une dépendance à un package TypeScript dans votre monorepo, ajoutez-la simplement au package.json à la racine de votre workspace. Vous pouvez le faire via la ligne de commande de votre gestionnaire de packages :

pnpm

pnpm add -w some-npm-package

yarn

yarn add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package

bun

bun install some-npm-package

La dépendance devient alors disponible pour tous les projets TypeScript de votre workspace.

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 esbuild pour empaqueter votre projet, car il permet le tree-shaking pour n’inclure que les dépendances réellement utilisées.

Vous pouvez configurer cela 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": "esbuild packages/my-library/src/index.ts --bundle --outfile=dist/packages/my-library/bundle/index.js --platform=node --format=cjs"
      }
    },
  },
}

Note

Dans cet exemple, nous avons choisi src/index.ts comme point d’entrée, ce qui signifie que le code exporté depuis ce fichier sera inclus dans le bundle avec toutes ses dépendances.

Publication sur NPM

Si vous publiez votre projet TypeScript sur NPM, vous devez créer un fichier package.json pour celui-ci.

Ce fichier doit déclarer toutes les dépendances utilisées. Comme les dépendances sont résolues via le package.json racine au moment du build, il est recommandé d’utiliser le plugin ESLint Nx Dependency Checks pour vérifier que votre package.json inclut bien toutes les dépendances nécessaires.

Build

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

pnpm

pnpm nx run <project-name>:build

yarn

yarn nx run <project-name>:build

npm

npx nx run <project-name>:build

bun

bunx nx run <project-name>:build

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

La cible build compilera, linttera et testera votre projet.

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

Tests

Vitest est configuré pour tester votre projet.

Écrire des tests

Écrivez vos tests dans des fichiers .spec.ts ou .test.ts, placés dans le dossier src de votre projet.

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 des 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, consultez la documentation Vitest

Exécuter les tests

Les tests s’exécutent lors de la cible build, mais vous pouvez aussi les lancer séparément via la cible test :

pnpm

pnpm nx run <project-name>:test

yarn

yarn nx run <project-name>:test

npm

npx nx run <project-name>:test

bun

bunx nx run <project-name>:test

Vous pouvez exécuter un test ou un groupe de tests spécifique avec le flag -t :

pnpm

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

yarn

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

npm

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

bun

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

Astuce

Si vous utilisez VSCode, nous recommandons d’installer l’extension Vitest Runner for VSCode that actually works pour exécuter, surveiller ou déboguer vos tests directement depuis l’IDE.

Linting

Les projets TypeScript utilisent ESLint pour le linting et Prettier pour le formatage.

Nous recommandons de configurer ESLint dans le fichier eslint.config.mjs à la racine du workspace, afin que les modifications s’appliquent à tous les projets et garantissent une cohérence.

Configurez Prettier dans le fichier .prettierrc racine.

Exécuter le linter

Pour vérifier votre projet avec le linter, exécutez la cible lint :

pnpm

pnpm nx run <project-name>:lint

yarn

yarn nx run <project-name>:lint

npm

npx nx run <project-name>:lint

bun

bunx nx run <project-name>:lint

Corriger les problèmes de lint

La plupart des problèmes de lint ou de formatage peuvent être corrigés automatiquement. Utilisez l’argument --configuration=fix pour corriger automatiquement :

pnpm

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

yarn

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

npm

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

bun

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

Pour corriger tous les problèmes dans l’ensemble du 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