intermediate30 minby DevFox

Dependencies and Their Type Definitions

Where types come from when they are not in the package, community type packages, versions drifting apart, and typing a library that ships none.

TypeScript

You install a package and the import is underlined:

text

Could not find a declaration file for module 'legacy-uploader'.
Try `npm i --save-dev @types/legacy-uploader` if it exists.

There is no such package. The library ships no types. You have three options and one of them switches off checking for everything that touches it.

By the end of this lesson you will know where types come from, what to do when there are none, how to fix ones that are wrong without waiting for upstream, and why two copies of the same type definition can make a value incompatible with itself.

Three places types come from

Bundled with the package, which is now the norm:

json

{
  "name": "photo-tools",
  "types": "./dist/index.d.ts"
}

Or through the exports map, where — as the modules lesson noted — types must be the first key in each condition block or it is never reached.

From DefinitelyTyped, published as @types/name:

bash

npm install --save-dev @types/express

These are community-maintained descriptions of a package that ships none. They are versioned separately, which is where drift comes from.

Written by you, when neither exists.

Bundled with the package
The norm now. Versioned with the code, so they cannot drift.
@types from DefinitelyTyped
Community-written, versioned separately from the package they describe — which is exactly where drift comes from.
Written by you
A declaration file you own, describing only the part of the library you actually call.

Check them in this order. Each step is more work than the one before it.

skipLibCheck: true means the compiler does not check these files internally. Nearly every project sets it, and it hides conflicts between two packages that disagree about a shared type.

A package with no types

Bad — silencing it.

Good — a declaration for what you use.

The suppression makes the import compile and everything reached through it any — so the typo in endpiont, the misspelled uplaod, and every value derived from the response are all unchecked. A single @ts-expect-error at an import can remove checking from an entire module.

The declaration takes ten minutes and covers only the three functions you call, which is the point: describe what you use, not the whole library. Nobody needs a complete definition, and an incomplete one is enormously better than none.

Point the compiler at it:

A .d.ts inside include is picked up automatically; typeRoots matters when the files live elsewhere.

If your declaration turns out well, publishing it to DefinitelyTyped is a genuinely small contribution that saves the next person the same afternoon.

When the types are wrong

More annoying than missing types are inaccurate ones — a parameter typed string that accepts string | number, a return type missing null.

Module augmentation adds to an existing declaration:

Now request.user exists everywhere, which is the standard way to describe what your middleware attaches. This works because interfaces merge — the behaviour the foundations course flagged as a hazard, here being the feature.

For a type that is wrong rather than incomplete, correct it at one boundary:

One assertion, in one file, with the rest of your codebase using the corrected signature. Contrast with asserting at forty call sites, which is forty places to update when upstream fixes it.

Mark it so it expires:

@ts-expect-error errors when there is nothing to suppress, so the day the package is fixed your build tells you the comment is stale — which @ts-ignore never does.

Two copies of the same type

That message is genuinely confusing the first time. It means two copies of a package are installed, so Photo from one is a different type from Photo from the other — structurally identical and nominally distinct, because they come from different declaration files.

Three fixes, in order of preference:

Or a peer dependency, if you are the one publishing. Or paths as a last resort, pointing every import at one copy.

The same happens with @types/react in a large front-end tree, and it is the standard explanation for "this component is not assignable to itself".

dependencies or devDependencies

The rule is about what your consumers need:

dependencies

Installed for everyone who installs you.

Code that runs at runtime — and, for a library, the @types packages your public signatures mention.

devDependencies

Installed only for people working on you.

Build tools, test frameworks, linters, and the @types for all of those.

Nothing to do with when you use it — only with whether somebody installing your package needs it too

The case people get wrong: if your package is a library and its public types reference a package's types, that @types package belongs in dependencies, not devDependencies.

A consumer needs @types/express to use that signature. In devDependencies it is not installed for them, and they get an error about a type they never mentioned.

For an application rather than a library, devDependencies is correct for all of them — nothing consumes your types.

Keeping dependencies honest

Three habits worth the small cost.

Audit before adding. Does it ship types? How large is it? When was it last updated? How many dependencies does it bring? A one-function package with fourteen transitive dependencies is a poor trade.

Pin exactly in an application. A lock file is not optional for anything you deploy — it is what makes the software you tested the software that runs.

Constrain ranges in a library. ^4.17.0, not 4.17.21. An exact pin in a published library is an unsatisfiable conflict for anyone using you and anything else that depends on the same package.

And in CI:

depcheck's second category is the dangerous one: a package you import without declaring works locally because something else installed it, and breaks when that dependency changes.

A cheat sheet to keep

Where to go next

You can now work with a package whatever state its types are in — missing, wrong or duplicated — without giving up checking for the code around it. The habit that pays most is writing a small declare module instead of suppressing an import: ten minutes, and the typos in your own calls are caught again.

Next is Utility Types, which covers the transformations that ship with the language. Partial, Pick, Omit, Record and the rest are how you derive one type from another instead of maintaining two that drift.

Before you move on, run npm ls on a @types package you depend on and check whether there is more than one version. Duplicate type packages are common, quiet, and the explanation for a class of error that otherwise makes no sense.