Potentially misleading documentation for the types TSConfig option

[aweebit]

Acknowledgement

• I acknowledge that issues using this template may be closed without further explanation at the maintainer's discretion.

Comment

Here is what the docs for the types TSConfig option say:

When you have this option set, by not including a module in the types array it:

• Will not add globals to your project (e.g process in node, or expect in Jest)
• Will not have exports appear as auto-import recommendations

I run the following commands:

mkdir tsconfig-types-misleading-docs
cd tsconfig-types-misleading-docs
npm init -y
npm pkg set type="module"
npm i -D typescript@~5.7.3 @types/json-schema
npm i json-schema
touch index.ts

And created the following tsconfig.json file:

{
  "compilerOptions": {
    "noEmit": true,
    "target": "ESNext",
    "module": "Preserve",
    "types": []
  }
}

Upon opening tsconfig-types-misleading-docs in VS Code 1.97.2 (the latest version at the time of writing), navigating to index.ts and typing type Type = JSONSchema, I see suggestions from the json-schema package:

Weirdly enough, I only see those suggestions when both @types/json-schema and json-schema are installed. Moreover, I stop seeing them when I remove the noEmit, target and module options from tsconfig.json (but not when I remove only some of them). And then I can also remove the types option itself and still won't see the suggestions.

So what is going on here? Are the docs misleading, or am I missing something?

Should I care to include types for packages that do not have any global declarations like json-schema in the types field?

A similar question came up before on Stack Overflow:

• types option in TSConfig doesn't work as stated in the TS docs

[RyanCavanaugh]

This is intentional: auto-import shows you types from your listed npm dependencies, and json-schema is one of them. types: [] is not relevant here. When you remove noEmit, target, and module, the default settings are such that those likely not considered to be reachable.

The docs are still correct here; you are seeing the import suggestions because of your package.json, not because of the types entry