Cách khắc phục lỗi 'Could not find a declaration file for module' trong TypeScript

Lỗi Build lúc nửa đêm

Đã 10 giờ tối. Bạn vừa hoàn thành một tính năng sử dụng thư viện bên thứ ba mới. Mọi thứ trông có vẻ hoàn hảo trong đầu, nhưng khi bạn chạy lệnh build, terminal bùng nổ với những dòng chữ đỏ. Thủ phạm? Một lỗi kiểm soát đầu vào kinh điển của TypeScript:

Could not find a declaration file for module 'module-name'. '/path/to/module.js' implicitly has an 'any' type.

Bạn có thể sẽ thấy đường gạch chân ngoằn ngoèo màu đỏ gây khó chịu dưới câu lệnh import trong VS Code. Về cơ bản, TypeScript đang nói: "Tôi thấy mã JavaScript này, nhưng tôi không biết cấu trúc đối tượng của nó trông như thế nào. Tôi sẽ không đoán mò, vì vậy tôi dừng lại ở đây." Dưới đây là cách để khai thông quy trình làm việc của bạn và tiếp tục xuất bản mã nguồn.

Danh sách kiểm tra nhanh để Debug

Trước khi cố gắng ép buộc một cách sửa lỗi, hãy kiểm tra ba điều này để xem tại sao TypeScript lại phàn nàn:

• Kiểm tra nguồn: Nhìn vào bên trong node_modules/module-name. Nếu bạn không thấy file index.d.ts hoặc trường types trong package.json, thư viện đó được viết bằng JavaScript thuần túy.
• Tìm kiếm trên DefinitelyTyped: Hầu hết các thư viện JS cũ đều có các kiểu dữ liệu (types) do cộng đồng hỗ trợ.
• Xác minh đường dẫn: Nếu đây là một file cục bộ, hãy kiểm tra kỹ baseUrl trong tsconfig.json. Một lỗi đánh máy ở đó có thể khiến một file cục bộ trông giống như một module bên ngoài bị thiếu.

Giải pháp 1: Sử dụng DefinitelyTyped (Cách sửa tốt nhất)

Hầu hết mọi khi, bạn không phải là người đầu tiên sử dụng thư viện này với TypeScript. Các công cụ phổ biến như lodash hoặc react-datepicker không đi kèm với các kiểu dữ liệu, nhưng cộng đồng duy trì chúng trong không gian tên @types. Việc này chỉ mất 10 giây để khắc phục.

# Thay thế 'module-name' bằng thư viện cụ thể của bạn
npm install --save-dev @types/module-name

# Sử dụng yarn hoặc pnpm?
yarn add -D @types/module-name
pnpm add -D @types/module-name

Sau khi cài đặt xong, lỗi sẽ biến mất. Nếu VS Code vẫn cứng đầu, hãy khởi động lại server TypeScript bằng cách nhấn Ctrl+Shift+P và chọn TypeScript: Restart TS Server.

Giải pháp 2: Tạo file khai báo tùy chỉnh

Nếu bạn đang sử dụng một thư viện ít tên tuổi hoặc thư viện nội bộ, gói @types có thể không tồn tại. Trong trường hợp này, bạn cần bảo TypeScript đừng lo lắng nữa. Bạn có thể tạo một khai báo "tóm tắt" coi toàn bộ module là kiểu any. Nó không hoàn toàn an toàn, nhưng nó hoạt động.

• Tạo một thư mục types bên trong thư mục src của bạn.
• Tạo một file có tên declarations.d.ts.
• Thêm dòng duy nhất này:

// src/types/declarations.d.ts
declare module 'module-name';

TypeScript thường tự động nhận diện các file .d.ts. Nếu không, hãy đảm bảo tsconfig.json của bạn bao gồm thư mục types đó:

// tsconfig.json
{
  "include": ["src/**/*", "src/types/*.d.ts"]
}

Giải pháp 3: Xử lý SVGs và CSS Modules

Bạn sẽ thường xuyên thấy lỗi này khi import các tài nguyên không phải là mã nguồn. TypeScript mong đợi mã nguồn, vì vậy khi bạn import một file .png hoặc .module.css, nó sẽ bị bối rối. Bạn có thể khắc phục điều này trên toàn cầu trong cùng file declarations.d.ts đó:

// Xử lý CSS Modules
declare module '*.module.css' {
  const classes: { [key: string]: string };
  export default classes;
}

// Xử lý import hình ảnh
declare module '*.svg' {
  const content: any;
  export default content;
}

Giải pháp 4: Tùy chọn "Tôi cần triển khai ngay bây giờ"

Nếu bạn đang dưới áp lực thời hạn chặt chẽ và chỉ một import duy nhất bị lỗi, hãy sử dụng "lối thoát hiểm". Điều này bỏ qua lỗi cho dòng cụ thể đó. Hãy sử dụng cách này một cách tiết kiệm—phụ thuộc vào nó quá nhiều sẽ làm mất đi ý nghĩa của việc sử dụng TypeScript.

// @ts-ignore
import { UntypedComponent } from 'some-old-library';

Xác minh

Đừng chỉ giả định nó hoạt động vì đường gạch đỏ đã biến mất. Hãy xác nhận bằng các bước sau:

• Chạy kiểm tra thủ công: Thực thi npx tsc --noEmit. Lệnh này kiểm tra toàn bộ dự án của bạn để tìm lỗi kiểu mà không tạo ra các file output.
• Xóa cache: Nếu lỗi vẫn còn, hãy xóa thư mục .next hoặc dist và khởi động lại dev server. Đôi khi các định nghĩa kiểu cũ vẫn còn ẩn nấp trong cache.

Lời kết

Các lỗi kiểu dữ liệu thường là dấu hiệu cho thấy dự án của bạn có một "điểm mù". Mặc dù Giải pháp 2 là cách nhanh nhất để gỡ rối công việc, nhưng nó loại bỏ "lưới an toàn" cho thư viện đó. Nếu thư viện đó là một phần cốt lõi của ứng dụng, hãy cân nhắc viết một vài interface trong file .d.ts của bạn. Việc này tốn nhiều công sức hơn nhưng mang lại cho bạn khả năng tự động hoàn thành (autocomplete) và sự bảo vệ giúp TypeScript trở nên đáng giá ngay từ đầu.