tsc TS2307: Cannot find module 'X' or its type declarations (missing @types) in CI

TS2307 here means the JavaScript package resolves at runtime, but it ships no bundled types and the matching @types/X stub is not installed, so tsc has no declarations to type-check against.

What this error means

tsc fails with "error TS2307: Cannot find module 'X' or its corresponding type declarations" for a third-party library that imports and runs fine in Node, but has its types in a separate DefinitelyTyped package.

tsc

src/server.ts:1:21 - error TS2307: Cannot find module 'express' or its corresponding type declarations.

1 import express from 'express';
                      ~~~~~~~~~

Common causes

The library ships no types and @types is a devDependency only

Packages like express keep their declarations in @types/express. If that stub is missing from the CI install (for example it was a devDependency skipped by npm ci --omit=dev), tsc cannot find types.

A lockfile that omits the @types package

The runtime dependency was added without its @types counterpart, so npm ci installs the library but not the declarations.

How to fix it

Install the matching @types stub

Add the DefinitelyTyped package for the library to devDependencies.
Commit the updated lockfile.
Ensure CI installs dev dependencies (do not pass --omit=dev) when it runs tsc.

Terminal

npm install --save-dev @types/express
npm ci   # without --omit=dev so @types is present

Install dev deps before type-checking

Type stubs live in devDependencies, so the type-check job must install them. A production-only install removes the types tsc needs.

.github/workflows/ci.yml

- run: npm ci
- run: npx tsc --noEmit

How to prevent it

Add the @types/* stub whenever you add a library that has no bundled types.
Keep @types packages in devDependencies and install dev deps in the type-check job.
Commit the lockfile so the same stub versions install in CI.