In a TypeScript project, importing an npm package that ships only JavaScript fails with "Could not find a declaration file for module ...". What is an `@types/*` package, how does the compiler find one, and what problems does that split introduce?

## Where declarations come from There are exactly three ways your compiler can know the shape of a dependency: 1. **The package ships them.** Its own `.d.ts` files, emitted from its TypeScript source or hand-written, advertised through `package.json`. This is the modern default. 2. **A separate `@types` package.** Declarations only, no runtime code, published under the `@types` npm scope. 3. **You write them.** A local ambient declaration in your own repo. Option 2 exists because TypeScript arrived long after most of npm. **DefinitelyTyped** is a large community repository holding declarations for thousands of JavaScript libraries; each folder in it is published automatically to npm as `@types/<name>`. Installing `@types/lodash` adds no code to your bundle at all — the package is nothing but types, and it belongs in `devDependencies` for an application. ## How the compiler finds them For `import { x } from 'somepkg'`, resolution proceeds roughly as: locate `node_modules/somepkg`, consult its `package.json` for declarations, and if there are none, look for `node_modules/@types/somepkg`, walking up the directory tree the same way Node walks up for packages. Scoped packages are flattened with a double underscore: declarations for `@scope/pkg` live in `@types/scope__pkg`. There is a second, separate mechanism. Packages under the type roots (by default every `@types` folder found walking up from the project) are also included **globally**, not just when imported — which is how `@types/node` makes `process` and `Buffer` available without an import. The `types` compiler option narrows that automatic global inclusion to a named list; it does **not** stop `import`-driven resolution from finding `@types` packages. Without any of this, and with `noImplicitAny` on, the compiler reports that it could not find a declaration file for the module and suggests installing `@types/<name>`. ## The problems the split creates **Version drift.** `@types/[email protected]` and `[email protected]` are unrelated release trains. The declarations may miss a new option, describe a removed one, or model an old signature. Since nothing checks declarations against implementation, the compiler will confidently green-light a call that throws at runtime, and equally reject a call that works fine. **Hand-written, not derived.** These declarations are written by volunteers reading documentation. They are frequently excellent and occasionally wrong — over-permissive (`any` where a union belongs) or over-strict. **Duplicates and conflicts.** Two dependencies pulling different major versions of the same `@types` package can end up with two copies declaring the same globals, producing duplicate-identifier errors inside declaration files — which is one of the classic reasons teams reach for `skipLibCheck`. **Redundancy.** If a library now bundles its own types, a leftover `@types` entry in your `package.json` is dead weight and can shadow or conflict with the real ones. DefinitelyTyped marks such packages as stubs, and removing them is the fix. ## Practical rules - Check whether the library bundles types **before** installing `@types` for it; the newer the library, the more likely it does. - Keep the `@types` version aligned with the library's major version where the maintainers track it, and treat a mismatch as a real risk rather than a lint nit. - `@types/node` is special: pin it near the Node version you actually run, because it also decides which globals exist. - If no declarations exist anywhere, you are into hand-written ambient declarations — a different mechanism with its own tradeoffs. - Treat an `@types` declaration as an unverified claim. When it disagrees with the library's real behaviour, the library is right.