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 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	-	TypeScript project 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 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
• vite.config.ts Configuration pour Vitest
• eslint.config.mjs Configuration pour ESLint

Astuce

Notez qu’aucun fichier package.json n’est créé pour ce projet ! Vous pouvez comprendre 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 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';

Note

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';

Note

Les alias pour vos projets TypeScript commencent par : plutôt que le @ traditionnel, évitant ainsi 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 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.

Les projets TypeScript sont configurés avec le générateur Nx TypeScript Sync par défaut, vous évitant de configurer manuellement les références de projet. 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

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

Astuce

Vous pouvez aussi simplement builder votre projet et vous verrez un message tel que :

[@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 être surprenant 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 est 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 Rolldown pour empaqueter votre projet, car cela permet un tree-shaking pour n’inclure que les dépendances réellement utilisées.

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,
    },
  },
]);

Note

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.

Astuce

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.

Publication sur NPM

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

Celui-ci doit déclarer les dépendances utilisées par votre projet. Comme au moment du build votre projet résoudra les dépendances installées via le package.json racine du workspace, il est recommandé de configurer le plugin ESLint Nx Dependency Checks pour s’assurer que le package.json de votre projet publié inclut toutes les dépendances utilisées.

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 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

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 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 individuel ou une suite de tests 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, qui permet d’exécuter, surveiller ou déboguer les tests depuis votre IDE.

Linting

Les projets TypeScript utilisent ESLint pour le linting, ainsi que Prettier pour le formatage.

Nous recommandons de configurer ESLint dans le fichier racine eslint.config.mjs du workspace, car les modifications s’appliqueront à tous les projets TypeScript et assureront la cohérence.

De même, vous pouvez configurer Prettier dans le fichier racine .prettierrc.

Exécution du linter

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

Correction des problèmes de lint

La majorité des problèmes de lint ou de formatage peuvent être corrigés automatiquement. Vous pouvez demander à ESLint de corriger les problèmes avec l’argument --configuration=fix :

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

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