Complete Guide to JSON File Import in TypeScript: From Module Declarations to Type Safety

Consistency Between Module Declarations and Import Syntax

When importing JSON files in TypeScript, module declarations must align with import syntax. Using declare module "*.json" declares that all JSON modules have a single default export named default. While functional, this approach is suboptimal since TypeScript 2.9.

Analysis of Common Import Errors

The frequent error "Property 'primaryMain' does not exist on type 'typeof \"*.json\"'" stems from mismatched import methods and module declarations. With import colors = require('../colors.json'), TypeScript expects access to module exports, not the JSON data itself.

// Error example
import colors = require('../colors.json');
console.log(colors.primaryMain); // Error: primaryMain does not exist

// Correct approach
import colors from '../colors.json';
console.log(colors.primaryMain); // Correct access

Modern Solutions in TypeScript 2.9+

TypeScript 2.9 introduced the resolveJsonModule compiler option, revolutionizing JSON imports. This feature allows TypeScript to directly analyze JSON file structures and generate corresponding type definitions.

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

Comparison of Different Import Syntaxes

Depending on esModuleInterop settings, developers can choose various import methods:

// Method 1: Default import (recommended)
import colorsJson from '../colors.json';
console.log(colorsJson.primaryMain);

// Method 2: Namespace import
import * as colorsJson from '../colors.json';
console.log(colorsJson.default.primaryMain);

// Method 3: Renamed default import
import {default as colorsJson} from '../colors.json';
console.log(colorsJson.primaryMain);

// Method 4: CommonJS style
const colorsJson = require('../colors.json');
console.log(colorsJson.default.primaryMain);

Type Safety and IntelliSense

With resolveJsonModule enabled, TypeScript generates precise type definitions based on JSON static structures. This provides complete type checking and intelligent code completion.

// TypeScript infers colorsJson type structure
import colorsJson from '../colors.json';

// Proper type checking
colorsJson.primaryMain = "#05B4F0"; // Correct
colorsJson.nonExistentProperty = "value"; // Type error
colorsJson.primaryMain = 123; // Type error: cannot assign number to string

Practical Application Scenarios

JSON file imports are valuable in various scenarios including:

• Configuration management: Application settings, theme colors
• Static data loading: Localization strings, icon mappings
• Build-time data injection: Embedding data during compilation

Compatibility Considerations and Notes

While resolveJsonModule is powerful, developers should note:

• TypeScript 2.9.0 had related bugs; use 2.9.2 or later
• Some target module formats may not fully support this feature
• JSON imports may not work in TypeScript variants like AssemblyScript
• For large JSON files, consider dynamic imports to avoid initial load performance issues

Best Practices Summary

Based on technical analysis and practical experience, we recommend:

1. Always enable resolveJsonModule and esModuleInterop compiler options
2. Use default import syntax: import data from './data.json'
3. Avoid manual *.json module type declarations; let TypeScript infer automatically
4. For complex JSON structures, define interfaces for enhanced type safety
5. Standardize JSON import conventions in team projects for code consistency

By following these guidelines, developers can efficiently and safely use JSON files in TypeScript projects, leveraging TypeScript's type system advantages while avoiding common import errors and compatibility issues.