Importação de JSON em TypeScript: guia completo com exemplos

Como importar JSON em TypeScript e não enlouquecer

Se você já tentou fazer import data from './config.json' em TypeScript, conhece aquela sensação: o compilador fica vermelho, reclama e lança o erro Cannot find module. Dor familiar? Pois é! A questão sobre importar JSON em TypeScript é uma das mais populares no Stack Overflow. E não é surpresa: JSON é usado em toda parte — configurações, localização, dados mock, listas estáticas. Mas o TypeScript, por padrão, não sabe trabalhar com arquivos JSON.

Neste tutorial, abordaremos todas as formas de importar JSON em TypeScript — desde simplesmente ativar uma flag no tsconfig até a tipagem avançada. Você aprenderá como fazer o TypeScript se dar bem com JSON e nunca mais verá aquele erro vermelho. Vamos nessa!

Por que o TypeScript não vê o JSON?

Antes de mergulhar no código, vamos entender o motivo. TypeScript é uma extensão do JavaScript que adiciona tipagem estática. Por padrão, o compilador TypeScript espera que todos os módulos importados sejam arquivos .ts ou .js. JSON não é um módulo, é um formato de dados. O TypeScript simplesmente não sabe como interpretá-lo.

A solução está em duas frentes:

\n
• Configuração do compilador — ativar o suporte a JSON através da flag resolveJsonModule.
\n
• Declaração de módulo — descrever manualmente o tipo para arquivos JSON, caso a flag não seja adequada.
\n

Método 1: Ativando resolveJsonModule (o caminho correto)

A forma mais simples e recomendada é adicionar a opção resolveJsonModule no tsconfig.json. Esta flag diz ao TypeScript: "Ei, amigo, vamos importar JSON como módulos normais".

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

Depois disso, você pode escrever tranquilamente:

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

O que acontece aqui? O TypeScript cria automaticamente tipos para o JSON importado. Se o seu JSON tem os campos apiUrl: string e port: number, o TypeScript inferirá seus tipos e verificará o uso. Legal, né?

Mas há um detalhe: resolveJsonModule também requer a ativação de esModuleInterop ou allowSyntheticDefaultImports para que a importação padrão funcione corretamente. Sem isso, você receberá um erro ao tentar importar.

Método 2: Importação com exportações nomeadas

Às vezes você não precisa do JSON inteiro, mas apenas de campos específicos. O TypeScript também suporta isso:

import { apiUrl, port } from './config.json';\n\nconsole.log(apiUrl); // string\nconsole.log(port);   // número

Isso é possível graças ao chamado "tree-shaking" em bundlers (Webpack, Vite), mas no nível do TypeScript é apenas uma desestruturação de objeto. No entanto, lembre-se: se você usa resolveJsonModule, o TypeScript cria automaticamente tipos para todos os campos, então você pode importar tanto o objeto inteiro quanto suas partes.

Método 3: require em vez de import (para projetos antigos)

Se você trabalha em um projeto onde resolveJsonModule não pode ser ativado por algum motivo (por exemplo, conflito com outras configurações), pode usar o bom e velho require:

const config = require('./config.json');\n\nconsole.log(config.apiUrl); // funciona, mas sem tipos

O problema dessa abordagem é óbvio: você perde a tipagem. O TypeScript não sabe o que está dentro de config e o considerará como tipo any. Isso abre caminho para erros. Se for usar require, pelo menos adicione uma declaração de tipo:

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