Importation de JSON en TypeScript : guide complet avec exemples

Comment importer du JSON en TypeScript sans perdre la tête

Si vous avez déjà essayé de faire import data from './config.json' en TypeScript, vous connaissez cette sensation : le compilateur rougit, râle et renvoie une erreur Cannot find module. Une douleur familière ? Et comment ! La question de l'importation de JSON en TypeScript est l'une des plus populaires sur Stack Overflow. Et ce n'est pas surprenant : le JSON est utilisé partout — configurations, localisation, données fictives, listes statiques. Mais TypeScript, par défaut, ne sait pas travailler avec les fichiers JSON.

Dans ce tutoriel, nous allons passer en revue toutes les méthodes d'importation de JSON en TypeScript — de l'activation simple d'un drapeau dans tsconfig jusqu'à la typification avancée. Vous apprendrez comment faire ami-ami TypeScript avec JSON, et vous ne verrez plus jamais cette erreur rouge. C'est parti !

Pourquoi TypeScript ne voit-il pas le JSON ?

Avant de plonger dans le code, comprenons la raison. TypeScript est une surcouche de JavaScript qui ajoute la typification statique. Par défaut, le compilateur TypeScript s'attend à ce que tous les modules importés soient des fichiers .ts ou .js. Le JSON n'est pas un module, c'est un format de données. TypeScript ne sait tout simplement pas comment l'interpréter.

La solution se situe sur deux plans :

\n
• Configuration du compilateur — activer la prise en charge du JSON via le drapeau resolveJsonModule.
\n
• Déclaration de module — décrire manuellement le type pour les fichiers JSON, si le drapeau ne convient pas.
\n

Méthode 1 : Activer resolveJsonModule (la bonne voie)

La méthode la plus simple et recommandée est d'ajouter l'option resolveJsonModule dans tsconfig.json. C'est un drapeau qui dit à TypeScript : "Hé, mon pote, importons le JSON comme des modules normaux".

// tsconfig.json\n{\n    "compilerOptions": {\n        "resolveJsonModule": true,\n        "esModuleInterop": true\n    }\n}

Après cela, vous pouvez tranquillement écrire :

// config.ts\nimport config from './config.json';\n\nconsole.log(config.apiUrl); // fonctionne !\nconsole.log(config.port);    // fonctionne !

Que se passe-t-il ici ? TypeScript crée automatiquement des types pour le JSON importé. Si votre JSON contient un champ apiUrl: string et port: number, TypeScript déduira leurs types et vérifiera leur utilisation. Cool, non ?

Mais il y a un détail : resolveJsonModule nécessite également l'activation de esModuleInterop ou allowSyntheticDefaultImports pour que l'import par défaut fonctionne correctement. Sans cela, vous obtiendrez une erreur lors de la tentative d'importation.

Méthode 2 : Importation avec des exports nommés

Parfois, vous n'avez pas besoin de tout le JSON, mais seulement de certains champs. TypeScript le prend également en charge :

import { apiUrl, port } from './config.json';\n\nconsole.log(apiUrl); // chaîne de caractères\nconsole.log(port);   // nombre

C'est possible grâce à ce qu'on appelle le "tree-shaking" dans les bundlers (Webpack, Vite), mais au niveau de TypeScript, c'est simplement une déstructuration d'objet. Cependant, rappelez-vous : si vous utilisez resolveJsonModule, TypeScript crée automatiquement des types pour tous les champs, vous pouvez donc importer en toute sécurité l'objet entier ou ses parties.

Méthode 3 : require au lieu de import (pour les anciens projets)

Si vous travaillez sur un projet où resolveJsonModule ne peut pas être activé pour une raison quelconque (par exemple, conflit avec d'autres paramètres), vous pouvez utiliser le bon vieux require :

const config = require('./config.json');\n\nconsole.log(config.apiUrl); // fonctionne, mais sans types

Le problème de cette approche est évident : vous perdez la typification. TypeScript ne sait pas ce qui se trouve à l'intérieur de config et le considérera comme de type any. Cela ouvre la voie aux erreurs. Si vous utilisez require, ajoutez au moins une déclaration de type :

interface Config {\n    apiUrl: string;\n    port: number;