Sửa lỗi TypeScript: Could not find a declaration file for module ts(7016)

Lỗi Gặp Phải

Bạn import một package và TypeScript ngay lập tức báo lỗi:

Could not find a declaration file for module 'library-name'. '/path/to/node_modules/library-name/index.js' implicitly has an 'any' type.
  Try `npm i --save-dev @types/library-name` if it exists or add a new declaration (.d.ts) file containing `declare module 'library-name';`  ts(7016)

Build thất bại. Editor sáng đỏ. Pipeline deploy bị chặn.

Nguyên Nhân

TypeScript cần thông tin kiểu dữ liệu để hiểu một module export ra những gì — các hàm, tham số, kiểu trả về. Thông tin đó nằm trong các file khai báo .d.ts.

Khi một package không đi kèm các file này, TypeScript không biết module đó trông như thế nào. Nó từ chối tiếp tục trừ khi bạn cho phép any ngầm định. Ba tình huống thường kích hoạt ts(7016) nhất:

• Package là JavaScript thuần không có types đi kèm
• Package cộng đồng @types/library-name chưa được cài đặt
• Bạn đang import một file JS nội bộ không có file .d.ts tương ứng

Cách Sửa 1: Cài Package @types (Phổ Biến Nhất)

Trước tiên, kiểm tra xem cộng đồng đã viết types trên DefinitelyTyped chưa:

npm install --save-dev @types/library-name
# hoặc dùng yarn
yarn add -D @types/library-name
# hoặc dùng pnpm
pnpm add -D @types/library-name

Những package bạn sẽ gặp thường xuyên:

npm install --save-dev @types/lodash
npm install --save-dev @types/express
npm install --save-dev @types/node
npm install --save-dev @types/react @types/react-dom

Sau khi cài xong, khởi động lại TypeScript server trong VS Code: Ctrl+Shift+P → TypeScript: Restart TS Server. Xong.

Kiểm tra package có tồn tại không

npm info @types/library-name

Có thông tin package trả về? Cài thôi. Báo lỗi kiểu 404? Không có types cộng đồng — chuyển sang Cách Sửa 2.

Cách Sửa 2: Tự Viết File Khai Báo

Không có types ở đâu cả và bạn cần gỡ chặn ngay bây giờ. Tạo một file khai báo trong project:

mkdir -p src/@types

Tạo file src/@types/library-name.d.ts:

declare module 'library-name';

Một dòng duy nhất. Nó báo với TypeScript: "tin tôi đi, module này tồn tại — coi mọi thứ từ nó là any." Đây là cách chữa tạm, không phải giải pháp thực sự, nhưng giúp bạn tiếp tục làm việc ngay lập tức.

Tốt hơn: chỉ khai báo những gì bạn thực sự dùng

Biết rõ cấu trúc của thứ bạn đang import? Hãy khai báo cụ thể. Bạn có type safety thật sự mà không cần khai báo hết toàn bộ export:

declare module 'legacy-analytics' {
  interface TrackOptions {
    event: string;
    userId?: string;
    properties?: Record<string, unknown>;
  }

  export function track(options: TrackOptions): void;
  export function identify(userId: string): void;
  export default { track, identify };
}

Cách Sửa 3: Trỏ tsconfig.json Đến Các File Khai Báo

TypeScript sẽ không tự tìm các file .d.ts của bạn. Mở tsconfig.json và kiểm tra typeRoots và include:

{
  "compilerOptions": {
    "typeRoots": [
      "./node_modules/@types",
      "./src/@types"
    ]
  },
  "include": [
    "src",
    "src/@types"
  ]
}

Chú ý bẫy này: nếu typeRoots được định nghĩa nhưng bỏ sót ./node_modules/@types, mọi package @types đã cài sẽ bị bỏ qua hoàn toàn. Chỉ thiếu một dòng đó thôi mà gây ra không biết bao nhiêu lần đau đầu.

Cách Sửa 4: allowJs Khi Chuyển Dần Từ JS Sang TS

Đang chuyển đổi một project JavaScript và gặp ts(7016) trên chính các file JS của mình? Thêm phần này vào tsconfig.json:

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false
  }
}

TypeScript sẽ tự suy luận kiểu từ JS thuần. Không cần khai báo tường minh. Phù hợp cho việc chuyển đổi từng bước.

Cách Sửa 5: Lối Thoát Nhanh (Đừng Để Vậy Lâu)

Deadline còn một tiếng, types có thể chờ? Tắt kiểm tra implicit any:

{
  "compilerOptions": {
    "noImplicitAny": false
  }
}

Hoặc bỏ qua một import cụ thể:

// @ts-expect-error -- TODO: thêm types cho untyped-library
import legacyLib from 'untyped-library';

Dùng // @ts-expect-error thay vì // @ts-ignore. Sự khác biệt rất quan trọng: @ts-expect-error sẽ cảnh báo bạn khi chú thích đó không còn cần thiết nữa. @ts-ignore thì im lặng mãi mãi.

Kiểm Tra Kết Quả

Sau khi áp dụng một cách sửa, xác nhận rằng nó đã có hiệu lực:

# Không có lỗi nào = ổn rồi
npx tsc --noEmit

# Kiểm tra riêng ts(7016)
npx tsc --noEmit 2>&1 | grep 7016

Trong VS Code, hover chuột lên import. Thấy type signature thực sự thay vì any? Types đã được tải đúng cách.

Phòng Tránh

• Trước khi thêm bất kỳ thư viện JS nào, hãy tìm kiếm package @types tương ứng — nhiều package đã có sẵn và chỉ mất 10 giây để cài
• Nhiều package hiện đại giờ đã đi kèm types trực tiếp. Kiểm tra package.json của chúng xem có trường "types" hoặc "typings" không — nếu có thì không cần cài thêm @types
• Thêm tsc --noEmit vào CI — phát hiện các instance mới trước khi vào code review
• Giữ src/@types/ trong version control cho các khai báo tùy chỉnh. Đừng rải rác các file .d.ts khắp nơi trong project