Fix lỗi TypeScript "--resolveJsonModule is not specified" khi import JSON

Lỗi Gặp Phải

Bạn thử import một file JSON vào code TypeScript và trình biên dịch báo lỗi:

Module './config.json' was resolved to '/path/to/config.json', but '--resolveJsonModule' is not specified.

Hoặc trong các cấu hình chặt hơn:

Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension.

Câu lệnh import của bạn có thể trông như thế này:

import config from './config.json';

console.log(config.apiUrl);

TypeScript nhận ra phần mở rộng .json và từ chối xử lý nếu bạn chưa bật tùy chọn này một cách tường minh.

Nguyên Nhân

Import JSON bị tắt theo mặc định trong TypeScript. Trình biên dịch sẽ không đụng vào file .json cho đến khi bạn bật cờ resolveJsonModule — khi đó, TypeScript coi file JSON như một module thực thụ và tự động suy luận kiểu dữ liệu của nó. Nếu không bật, mọi lệnh import ... from '*.json' đều thất bại lúc biên dịch, dù file đó tồn tại trên đĩa và Node.js vẫn có thể load nó bình thường lúc runtime.

Lỗi này thường gặp nhất khi chuyển đổi dự án từ JS sang TS, hoặc khi copy nguyên mẫu import từ một dự án JavaScript sang dự án TypeScript.

Cách Sửa 1: Bật resolveJsonModule trong tsconfig.json (Khuyến nghị)

Mở tsconfig.json và thêm "resolveJsonModule": true vào trong compilerOptions:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "strict": true,
    "outDir": "./dist"
  }
}

Đó là toàn bộ cách sửa cho hầu hết các dự án. Lưu file, chạy build — lỗi biến mất.

Thêm vào đó: TypeScript sẽ tự động suy luận cấu trúc kiểu của JSON. Kiểm tra kiểu đầy đủ và tự động hoàn thành code, không cần annotation thêm:

// config.json
{
  "apiUrl": "https://api.example.com",
  "timeout": 5000
}

// app.ts
import config from './config.json';

// TypeScript biết: config.apiUrl là string, config.timeout là number
console.log(config.apiUrl.toUpperCase()); // ✓ an toàn kiểu

Cách Sửa 2: Truyền Cờ Trực Tiếp Qua Command Line

Đang chạy tsc trực tiếp mà không có file config? Truyền cờ ngay trên lệnh:

tsc --resolveJsonModule src/app.ts

Phù hợp cho các lần biên dịch tức thời. Với dự án thực tế, hãy dùng tsconfig.json — giúp cài đặt được lưu lại và theo dõi qua version control.

Cách Sửa 3: Lưu Ý Theo Từng Framework

Vite

Vite xử lý việc import JSON ở tầng bundler, nên file load bình thường lúc runtime. TypeScript vẫn cần cờ này để kiểm tra kiểu. Thêm resolveJsonModule: true vào tsconfig.json (hoặc tsconfig.app.json trong các scaffold Vite mới hơn) và lỗi sẽ biến mất cả trong tsc lẫn IDE của bạn.

Next.js

Next.js tự quản lý tsconfig.json và đã bao gồm resolveJsonModule theo mặc định trong các phiên bản gần đây (13+). Các dự án cũ hơn có thể chưa có — hãy thêm cờ thủ công nếu gặp lỗi này. Next.js sẽ không ghi đè cài đặt bạn đã đặt tường minh.

ts-node

Với ts-node, cách rõ ràng nhất là dùng tsconfig.json. Nếu cần một lệnh nhanh thay thế:

ts-node --compiler-options '{"resolveJsonModule":true}' src/script.ts

Xác Nhận Đã Sửa Xong

Chạy kiểm tra kiểu mà không emit để xác nhận mọi thứ đã sạch:

# Chỉ kiểm tra kiểu (không tạo file output)
npx tsc --noEmit

# Hoặc build đầy đủ
npx tsc

Không còn lỗi import JSON nghĩa là đã sửa thành công. Trong VS Code hoặc WebStorm, hover chuột lên object được import — tooltip sẽ hiển thị kiểu được suy luận với đúng các key và kiểu giá trị từ file JSON của bạn.

Vẫn thấy lỗi sau khi sửa tsconfig.json? Hãy kiểm tra xem build tool của bạn đang thực sự đọc file config nào. Các dự án có nhiều file tsconfig — tsconfig.app.json, tsconfig.build.json — thường có cờ ở một file nhưng không phải file được dùng lúc biên dịch.

Một Lưu Ý Quan Trọng: moduleResolution

Đang dùng "moduleResolution": "bundler", "node16", hoặc "nodenext"? Bạn cũng cần "esModuleInterop": true đi kèm với resolveJsonModule để default import hoạt động đúng:

{
  "compilerOptions": {
    "moduleResolution": "node16",
    "resolveJsonModule": true,
    "esModuleInterop": true
  }
}

Nếu không có esModuleInterop, hãy chuyển sang dùng namespace import:

import * as config from './config.json';
// thay vì:
import config from './config.json'; // cần esModuleInterop

Phòng Tránh

Thêm resolveJsonModule: true vào template dự án của bạn để người tiếp theo clone repo không gặp phải lỗi này. Hầu hết các scaffold hiện nay — Vite, Create React App — đã bao gồm nó. Lệnh tsc --init thuần thì không có.

Nếu các file JSON của bạn ngày càng phức tạp — object lồng nhau, nhiều kiểu dữ liệu — hãy validate chúng trước khi đưa vào trình biên dịch. Dán nhanh vào JSON Formatter của ToolCraft để phát hiện lỗi cú pháp ngay lập tức; mọi thứ chạy trên trình duyệt, không có gì được upload lên. Hãy loại trừ khả năng file JSON bị lỗi trước khi đi tìm vấn đề trong cấu hình TypeScript.

Với các dự án kết hợp cả file config JSON lẫn YAML, YAML ↔ JSON Converter của ToolCraft giúp bạn dễ dàng hợp nhất các nguồn config khi cần.