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

[typescript-bot]

This issue has been marked as "Working as Intended" and has seen no recent activity. It has been automatically closed for house-keeping purposes.

[aweebit]

@RyanCavanaugh Sorry, but I still don't quite get it.

The documentation gives the following short description of the types option:

Specify type package names to be included without being referenced in a source file

This and the fact that the detailed description only talks about @types packages make it seem like those packages' names (without the @types/ prefix) are the only thing you can put in the array. That is clearly not the case, since names of regular packages that provide their own types directly as well as paths to .d.ts files (or paths to .ts / .js files for which declarations are available) can also be specified.

But let's assume it were the case for the sake of argument. From the current types documentation and your comment, my understanding is that types from @types packages listed as dependencies in package.json are suggested no matter what. But then I don't see how this part of the documentation would be useful:

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

• Will not have exports appear as auto-import recommendations

I think it would only be relevant for @types package installed in node_modules but not listed in package.json, wouldn't it? But exporting types from such “ghost” dependencies is a terrible idea anyway, which makes this line entirely meaningless.

Is there maybe some different place where the import suggestion mechanism and how package.json and the types option affect it is clearly documented?

My main practical question is again this:

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

But also I am just curious to understand how all of this works.

---

Let's now lift the assumption the docs are right about it only being possible to specify @types package names in types.

I did a small experiment by patching first the type declarations exported by @types/json-schema and then the type declarations of the typescript package with this new declaration:

declare global {
    var myGlobal: number;
}

With no types option specified, there was only an import suggestion for myGlobal when I patched @types/json-schema, but not when I patched typescript. This is in accordance with this sentence from the docs:

By default all visible "@types" packages are included in your compilation.

This made me questioning, however, why is it the case that packages that do not care to export their own types and rely on the DefinitelyTyped infrastructure instead are kind of privileged here? Why am I expected to manually specify "types": ["typescript"] if I want the globals from typescript to always be added, but I don't have to do that with json-schema since its globals from the corresponding @types package are added by default? Isn't that unfair towards libraries that provide first-class TypeScript support?

And isn't it weird that as long as I only want globals from @types packages added, I do not have to think about adding the packages to types if I just leave the option unspecified, but I suddenly have to start thinking about it as soon as I want to add globals from some package with first-class TypeScript support?

Example: say I first used globals from @types/node, @types/express and @types/json-schema, but then decided I also needed globals from typescript. With only the @types packages, I could just leave types unspecified and not have to worry about including all of them. But when I need the typescript globals, I cannot simply set types to ["typescript"] because it would make the @types globals unavailable! I now suddenly have to be explicit about all the packages and must set "types": ["node", "express", "json-schema", "typescript"]. Isn't that confusing?

If I had to suggest an ideal solution without those quirks disregarding the threats of breaking changes, those would be the TSConfig options I would propose:

• typesFromDependencies (boolean): include types from dependencies listed in package.json files from all enclosing folders (default: true)
• typesFromTypesDependencies (boolean): include types from @types dependencies listed in package.json files from all enclosing folders (default: matches typesFromDependencies)
  • I don't think this option would be particularly useful, but it would make simulating the current default behavior easy by setting "typesFromDependencies": false and "typesFromTypesDependencies": true.
• types (string array): modules whose types should be additionally included in the compilation (default: [])
  • When simulating the current default behavior as described above, it is now enough to set "types": ["typescript"] if all you want to do is to add the typescript globals.
• typeRoots (string array): paths to directories containing packages whose types should be additionally included in the compilation (default: [])
  • The fact typeRoots would now only introduce additional paths instead of overriding the inclusion of types from packages in all enclosing folders would make Add option to include default typeRoots when overriding typeRoots #30855 unnecessary.

Consulting package.json files instead of simply including everything from node_modules could break things big times for libraries relying on global types from “ghost” dependencies mentioned earlier, so maybe this particular part of my proposal is not worth it.

In general, if the proposal were to be implemented, it would make sense to only include the change in a major version release, even though TypeScript does not follow semantic versioning, so as not to be flooded by bug reports from people ignoring this fact and depending on "typescript": "^5.7.3" and the like.

---

When you remove noEmit, target, and module, the default settings are such that those likely not considered to be reachable.

Can you please explain this in more detail? What exactly do you mean by “not reachable”? After all, I can still do import { JSONSchema4 } from 'json-schema' and it will work just fine.

[aweebit]

In 6.0 Deprecation Candidates (#54500), @sheetalkamat suggests:

May be default types should be [] verses undefined

That would be in line with my suggestion.

@RyanCavanaugh please read my comment above and reconsider this issue, I simply didn't have enough time to answer before it was automatically closed.

[tjcouch-sil]

I am also confused about types, especially the following line:

Will not have exports appear as auto-import recommendations

I don't see setting types to [] doing anything different to my IntelliSense imports list, and I wonder why not. This StackOverflow answer interestingly pointed me to TypeScript 4.8's documentation indicating that you can exclude imports by file patterns:

{
    // Note that `javascript.preferences.autoImportFileExcludePatterns` can be specified for JavaScript too.
    "typescript.preferences.autoImportFileExcludePatterns": [
      "**/node_modules/@types/node"
    ]
}

But that doesn't explain why setting types to [] does nothing when the documentation seems to indicate it should.

In my particular use case, I'm trying not to exclude any packages from the imports list; I want to keep them all. However, there is what seems to me to be a bug with a package I'm using that the owner suggested setting types to [] to solve. That seems more like a sideways workaround to me, but here we are nonetheless; I want to get past an error, and this seems to be the way to do so right now.

Looking forward to receiving clarity. Thank you!

[RyanCavanaugh]

@aweebit there are like thirty different questions throughout your comment and I don't have time to do 1:1 explanations for all of them. Auto-import tries to "do the right thing" given information it has. These are heuristics. If you have a very concrete specific thing you need to know, I will take on a direct question, but I can't do personal explanations of every single behavior of these heuristics.

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

No, unless it's for some reason absolutely critical that the very first time you type JSONSchema you get an auto-import suggestion for it.

[typescript-bot]

This issue has been marked as "Question" and has seen no recent activity. It has been automatically closed for house-keeping purposes.