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 comme les modules ECMAScript (ESM), les références de projet TypeScript, Vitest pour l’exécution des 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 construction
• tsconfig.json Configuration TypeScript de base pour ce projet (étend le tsconfig.base.json racine de l’espace de travail)
• tsconfig.lib.json Configuration TypeScript pour votre bibliothèque (code exécuté ou empaqueté)
• 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 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
• 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 exporter les éléments que vous souhaitez rendre disponibles pour d’autres projets :

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 le tsconfig.base.json de l’espace de travail, ce qui permet d’importer votre projet depuis d’autres projets TypeScript :

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

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

Note

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

Lorsque vous ajoutez un import vers un nouveau projet pour la première fois, une erreur peut apparaître 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’est pas encore configurée.

Les projets TypeScript sont préconfigurés avec le générateur Nx TypeScript Sync. Exécutez simplement la commande suivante pour ajouter 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 devrait disparaître et votre bibliothèque sera utilisable.

Astuce

Vous pouvez aussi lancer la construction de votre projet. Un message comme celui-ci apparaîtra :

[@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 les références de projet.

Dépendances

Votre projet TypeScript n’a pas de fichier package.json. Pour ajouter une dépendance, ajoutez-la au package.json racine de votre espace de travail :

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 sera alors disponible pour tous les projets TypeScript.

Code exécutable

Pour un usage runtime (ex: handler AWS Lambda), il est recommandé d’utiliser un outil comme esbuild pour empaqueter le projet et effectuer du tree-shaking.

Ajoutez une cible comme celle-ci dans votre 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, src/index.ts est le point d’entrée. Le code exporté depuis ce fichier sera inclus dans le bundle avec ses dépendances.

Publication sur NPM

Pour publier sur NPM, vous devez créer un package.json pour votre projet.

Utilisez le plugin ESLint de vérification des dépendances Nx pour garantir que toutes les dépendances utilisées sont déclarées.

Construction

Le projet est configuré avec une cible build (définie dans project.json) :

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.

Les artefacts de construction se trouvent dans dist/packages/<my-library>/tsc.

Tests

Vitest est configuré pour les tests.

Écrire des tests

Placez vos tests dans des fichiers .spec.ts ou .test.ts à côté du code source :

• Répertoiresrc

  • hello.ts Code source
  • hello.spec.ts Tests pour hello.ts

Utilisez la syntaxe de type Jest avec 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!');
  });

});

Consultez la documentation Vitest pour plus de détails.

Exécuter les tests

Exécutez tous les tests avec :

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

Ou un test spécifique avec :

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

Pour VSCode, installez l’extension Vitest Runner for VSCode that actually works pour exécuter des tests directement depuis l’IDE.

Linting

Les projets utilisent ESLint et Prettier. Configurez-les dans les fichiers racines eslint.config.mjs et .prettierrc.

Vérification

Lancez le linter avec :

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 automatique

Corrigez les problèmes de lint avec :

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

Ou pour tous les projets :

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