Une meilleure expérience avec TypeScript et TSConfig

Depuis le début de cette série, nous avons travaillé avec TypeScript en créant des fichiers .ts et en utilisant lang="ts" dans la section script des composants Vue.js.

Cependant, nous n'avons pas encore configuré TypeScript dans notre projet, donc nous ne tirons pas parti de tout son potentiel. De plus, l'un des avantages d'utiliser TypeScript dans une bibliothèque est d'exposer des types aux développeurs qui l'utiliseront. Cela permet le contrôle de type et l'auto-complétion dans leur IDE.

Configuration de TypeScript ​

Commencez par installer TypeScript et les types Node.js nécessaires dans packages/huchet-vue :

pnpm add -D typescript @types/node

Grâce à l'énorme écosystème de plugins Vite, nous pouvons utiliser le plugin vite-plugin-dts pour générer des fichiers .d.ts pour notre bibliothèque.

Installez-le :

pnpm add -D vite-plugin-dts

Ensuite, mettez à jour le fichier vite.config.ts dans packages/huchet-vue :

import Vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'
import Dts from 'vite-plugin-dts'

export default defineConfig({
  plugins: [
    Vue(),
    Dts(), 
  ],
  build: {
    // ...
  }
})

Est-ce que cela fonctionne maintenant ? Pas encore. Si c'était aussi simple, je n'écrirais pas tout un article à ce sujet !

Lorsque vous utilisez TypeScript, vous devez le configurer via un fichier tsconfig.json. Ce fichier comprend de nombreuses options pour informer TypeScript sur le type de projet, y compris les types et variables globaux, les chemins de fichiers, et même la méthode de compilation de code souhaitée.

Écrire cela pour la première fois peut être fastidieux, mais heureusement, certains projets fournissent une configuration de base à partir de laquelle étendre.

Un autre problème avec tsconfig.json est qu'un package peut en avoir plusieurs. Notre fichier vite.config.ts et nos fichiers .vue ont des contextes différents. Le premier doit avoir accès à l'API Node.js, tandis que le second a besoin d'accéder à l'API DOM et navigateur.

Nous pouvons résoudre cela en utilisant un seul fichier tsconfig.json avec l'option references. Cela nous permet de diviser un fichier TSConfig en plusieurs fichiers, chacun ciblant un contexte spécifique.

Voici le plan :

1. tsconfig.json pour combiner les deux contextes.
2. tsconfig.node.json pour le contexte Node.js.
3. tsconfig.app.json pour le contexte Vue.js.

Le contexte TypeScript Node ​

Créez le fichier tsconfig.node.json dans packages/huchet-vue :

touch tsconfig.node.json

Remplissez-le avec le contenu suivant :

{
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
    "target": "ES2022",
    "lib": ["ES2023"],
    "moduleDetection": "force",
    "types": ["node"],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "allowImportingTsExtensions": true,
    "strict": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noEmit": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "noUncheckedSideEffectImports": true
  },
  "include": ["vite.config.ts"]
}

Ce fichier est similaire à ce qui est fourni dans n'importe quel template Vite, sauf que nous avons ajouté l'option types définie sur ["node"] pour garantir que les types Node.js sont disponibles dans le fichier de configuration Vite. Cette configuration cible uniquement le fichier vite.config.ts.

Cela constitue notre premier contexte TypeScript.

Le contexte TypeScript Vue.js ​

Le deuxième contexte ciblera les fichiers Vue.js et TypeScript de notre dossier src, nommé tsconfig.app.json.

Créez le fichier tsconfig.app.json :

touch tsconfig.app.json

Incluez le contenu suivant :

{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "include": [
    "src/**/*.ts",
    "src/**/*.vue"
  ]
}

Avant d'utiliser cette configuration, installez la configuration de base TypeScript de Vue.js :

pnpm add -D @vue/tsconfig

Vue.js propose une configuration de base sur laquelle s'appuyer, ce qui est crucial car TypeScript évolue rapidement, et Vue.js nécessite des configurations spécifiques. Écrire une configuration TypeScript à partir de zéro n'est pas attrayant pour la plupart des développeurs.

Notre configuration étend la configuration de Vue.js avec l'option extends et cible le dossier src à l'aide de l'option include. C'est simple et fonctionnel.

C'est notre deuxième contexte TypeScript.

La configuration TypeScript globale ​

Maintenant, créez le fichier tsconfig.json pour unifier les deux contextes. Ce fichier ne définit pas un nouveau contexte ou des options de compilateur, mais référence les deux autres contextes pour que le compilateur TypeScript puisse les utiliser au besoin.

Créez le fichier tsconfig.json :

touch tsconfig.json

Incluez le contenu suivant :

{
  "files": [],
  "references": [
    {
      "path": "./tsconfig.app.json"
    },
    {
      "path": "./tsconfig.node.json"
    }
  ]
}

Le tableau files vide est crucial pour éviter d'inclure tous les fichiers du projet. Chaque référence a son propre contexte, donc nous devons nous assurer qu'un seul contexte cible un fichier.

Cela constitue notre configuration TypeScript globale.

Génération des types ​

Avec nos configurations TypeScript en place, nous pouvons procéder à la génération des types pour notre bibliothèque.

Puisque nous combinons deux contextes, le plugin vite-plugin-dts a besoin d'un lien explicite vers le contexte de nos composants.

Mettez à jour le fichier vite.config.ts dans packages/huchet-vue :

import { resolve } from 'node:path'
import Vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'
import Dts from 'vite-plugin-dts'

export default defineConfig({
  plugins: [
    Vue(),
    Dts({
      tsconfigPath: resolve(__dirname, 'tsconfig.app.json'),
    })
  ],
  build: {
    // ...
  },
})

Nous utilisons le fichier tsconfig.app.json puisque Vite construit les fichiers Vue.js et TypeScript à partir du dossier src.

Procédez à la génération des types :

pnpm run build

Dans notre dossier dist, un dossier types contenant les fichiers .d.ts devrait apparaître.

dist
├── index.d.ts
├── index.mjs
└── Button
    ├── Button.vue.d.ts
    └── index.d.ts

Exposition des types ​

Ayant généré les types, l'étape suivante consiste à les exposer aux développeurs utilisant notre bibliothèque.

Mettez à jour le fichier package.json dans packages/huchet-vue :

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs"
    }
  },
  "main": "./dist/index.mjs",
  "types": "dist/index.d.ts"
}

Nous définissons le champ types pour qu'il pointe vers le fichier index.d.ts dans le dossier dist, garantissant que les types sont disponibles dans l'IDE lorsque les développeurs importent notre bibliothèque.