DefinitelyTyped: kho @types cho TypeScript

Thách thức của việc định kiểu cho package npm

Một phần lớn npm ra đời trước cả TypeScript, và nhiều tác giả thư viện chẳng có hứng thú học cú pháp declaration file để tự viết type. TypeScript không thể định kiểu cho thứ nó không thấy. Nếu không có một nơi tập trung, mọi dự án phụ thuộc vào package chưa có type sẽ phải tự viết `declare module` riêng — lặp lại đúng một kiểu đoán mò ở hàng ngàn codebase khác nhau. DefinitelyTyped gom hết việc đoán mò đó vào một kho được review, thay vì để nó rải rác khắp nơi.

DefinitelyTyped cung cấp những gì

DefinitelyTyped là một monorepo chứa file khai báo kiểu TypeScript, mỗi package npm một thư mục riêng, publish lên npm dưới scope `@types` — cài `@types/node` là lấy ngay type cho `node`. Mỗi package có file `index.d.ts` kèm file test được dtslint kiểm tra kiểu, không chạy, để khai báo luôn khớp với thực tế.

Cách kho định nghĩa kiểu này hoạt động

• ✓Tổ chức thành một pnpm monorepo duy nhất — mỗi thư viện một thư mục `types/<package>`, theo cấu trúc mới mà README nói đã thay đổi gần đây.
• ✓Type của mỗi package đi qua dtslint, chạy TypeScript compiler trên các file `.d.ts` và kiểm tra assertion `$ExpectType` / `@ts-expect-error` trong file test.
• ✓`@arethetypeswrong/cli` (`attw`) so sánh field `exports`/`type` trong `package.json` của package với bản implementation thật trên npm để bắt lỗi lệch CJS/ESM; các lỗi đã biết được ghi trong `attw.json`.
• ✓`tsconfig.json` của mọi package bắt buộc bật `noImplicitAny`, `noImplicitThis`, `strictNullChecks`, `strictFunctionTypes`, và không được bật `esModuleInterop` hay `allowSyntheticDefaultImports`.
• ✓PR đi qua một bot (`dt-bot`) tự động tag đúng owner của package, giúp review gần như tự phục vụ.
• ✓Package `@types` có dist-tag npm riêng cho các bản TypeScript cũ hơn — ví dụ README đưa ra: `ts2.5` và `ts2.7` trỏ tới hai phiên bản type react khác nhau.

Đóng góp và cập nhật định nghĩa kiểu

Fork rồi clone repo — repo khá lớn nên README khuyên dùng 'blobless clone' qua `git clone --filter=blob:none` để khỏi tải hết blob ngay từ đầu. Cài Node, rồi chạy `pnpm install`; có thể giới hạn chỉ một package bằng `pnpm install -w --filter "{./types/foo}..."` thay vì cài cả workspace. Sửa file `.d.ts` cùng file `<package>-tests.ts` tương ứng, rồi chạy `pnpm test <package>` để kiểm tra trước khi mở PR. Package mới bắt đầu từ `npx dts-gen --dt --name <my-package> --template module`, lệnh này tự sinh `index.d.ts`, file test, `tsconfig.json` và `package.json`. Khi một thư viện bắt đầu tự đóng gói type riêng, gỡ bản trên DefinitelyTyped bằng `pnpm run not-needed <typingsPackageName> <asOfVersion>`, lệnh này publish một bản stub trỏ sang phiên bản mới.

Khi thư viện tự đóng gói kiểu riêng

Câu hỏi thường gặp

Trường hợp sử dụng tốt nhất

• •Định kiểu cho một package npm chỉ có JS bằng cách cài `@types/<package>` thay vì tự viết `declare module`.
• •Đối chiếu dist-tag của package `@types` với bản TypeScript cũ bạn đang kẹt lại, theo đúng bảng version-tag mà README đưa ra ví dụ cho react.
• •Gửi PR sửa một type sai hoặc thiếu ở package bạn đang thực sự dùng — đúng tiêu chí README nêu để PR được chấp nhận.
• •Gỡ type của một package bằng `not-needed` khi thư viện gốc bắt đầu tự đóng gói declaration riêng.

Ai nên dùng — và ai nên bỏ qua

Dev TypeScript đang dùng một package JS thuần không có type sẵn nên kiểm tra DefinitelyTyped trước — cài package `@types` thường nhanh hơn tự viết ambient declaration. Bỏ qua việc đóng góp nếu bạn là tác giả thư viện và đã viết bằng TypeScript; README khuyên bạn tự đóng gói file `.d.ts` sinh ra thay vì publish lên đây. Coding agent muốn cày PR hàng loạt vào repo này cũng nên bỏ qua — README từ chối thẳng kiểu làm việc đó và giới hạn đóng góp tự động ở một PR duy nhất, phải được người dùng xác nhận.

Repo liên quan