disable certain global types for specific files, or specify type roots for specific files.

[trusktr]

This continues some ideas from #17042, which was closed by @microsoft (for inactivity, I think?).

Search Terms

disable certain global types for specific files, specific type roots for certain files

Suggestion

Ability to specify which @types (or in general, which specified typeRoots) apply to which files in a project.

Use Cases

My project's src folder contains both .ts and .test.ts files, and I'd like an easy way for globals like describe to be defined only for the .test.ts files.

Examples

Not sure, but maybe some sort of new options in tsconfig.json for specifying which types items, lib items, or typeRoots items apply to which files.

This would be a beneficial feature because various editors (VS Code aside) look for a tsconfig.json file at the root of a project, and at the moment the only way to make types work in all files is to just provides all types for all files, which is undesirable because describe is not a function that is available in source files (as an example).

Example configuration: maybe instead of a typeRoots array, it can be an object like:

"typeRoots": {
  "./src/**/*.test.ts": ["../path/to/test/types"], // test-only types
  "./src/**/*.ts": ["../path/to/@types"] // other types other files
}

Or something. That's just an example to get the idea rolling.

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

[trusktr]

The main concept is that we often need to install @types packages as devDependencies to use global types in things like tool configurations, scripts, tests, etc, and then those global types leak into source files (although they actually aren't available at runtime in those files).

If someone tries use a describe() test function (for example) in a source file instead of a test file, then at runtime this will be an error.

The idea here is that some option would allow us to specify which files certain types or typeRoots apply to, and our configuration would allow intellisense in editors like VS Code to show autocomplete options for APIs like describe() (for example) only in test files.

[trusktr]

The the new composite feature (described in the Project References doc) solve this request? Does it allow globals to be scoped per project?

The doc says

Previously, this structure (f.e. having both test/ and src/ folders that can import from each other) was rather awkward to work with if you used a single tsconfig file:

• It was possible for the implementation files to import the test files

This seems to imply that isolation of globals may be possible (f.e. so that things like describe() and it() in test files don't leak into source files) .

EDIT: Yes, composite (Project References) does allow segregating global types per each reference. However, migrating from regular projects to project references can be cumbersome and lead to issues requiring refactoring, which is not ideal. Having an option that works with or without (tangential to, agnostic of) project references would be great.

[trusktr]

This issue keeps popping up the more TS projects I work on.

What we need is a more robust way of managing which global types are included or excluded. A couple cases are illustrated next.

Case 1: ergonomics:

Setting types to an empty array and manually listing all global types only to exclude, for example, a single global lib, is not ideal.

For this use case, we simply need a way to exclude certain global types.

Case 2: libraries with global builds and modules:

The three package on NPM can be imported as ES Modules, and the type defs work that way. However, that package also includes global types for people that may be using a <script> tag to load the lib as a global variable. When this package is added to a project, then even if we wish to use ES Modules for all types, the global types are still available (although the global variable itself is not), so this error can happen:

import {Camera} from 'three'

// all good, no type or runtime error
const camera = new Camera

// no type error, but runtime error "can't read property Scene of undefined"
const scene = new THREE.Scene 

For this use case, we simply need a way to exclude certain global types.

Case 3: multiple libs in a project depend on the same global namespace, but expect different types

Sometimes a project needs to use both React (for old parts of the code base) and some new library that also relies on JSX (for new parts of the code base). What ends up happening is that both React and the new lib (f.e. Solid.js, Preact, and a bunch of others) need to define JSX types. Libs that depend on JSX types don't all define the JSX types in a way that plays nicely with each other (React doesn't because it assumes to be the king, but Preact does) so what can happen is conflicts in JSX type declarations.

For this case, it would be great to be able to control which global types are available for which sets of files (I imagine it similar to a paths mapping, but mapping sets of files to type roots or similar). Then the project author can put React files in one place, and other-library files (f.e. Preact files or Solid.js files) in another place, and simply configure which files particular global types are available to.

An alternate existing solution for this case is to split the project into multiple TypeScript Project References, but this can be cumbersome and lead to other issues.

Having an option to control which globals are available to which files (which is a more fine-grained control than just "which globals to exclude" with the set of files to which we control global visibility being the whole project, as shown in the previous cases) would be useful here, without needing to restructure a project and introducing new issues. Furthermore, this option could still be helpful in Project References (it is tangential, and can be an option that works in any tsconfig.json, regardless if that tsconfig.json is for a project reference).

Case 4: source files vs test code

Projects often include both .ts and .test.ts files co-located with each other (f.e. src/foo.ts is next to src/foo.test.ts). We may want certain global types available only in the test code (f.e. describe, it, expect, etc) but not in the source code.

For this case the solution is the same one suggested for Case 3, for example exposing or excluding some globals to or from one set of files.

---

Here's a set of issues with people effectively asking for more control over global types:

• Can't disable type definitions for one special library #17042
• Suggestion: add excludeTypeRoots to tsconfig #18588
• TypeScript "exclude" conflicts with types resolution vscode#10285
• Impossible to exclude original declaration file from module #21189
• Don't include all @types/ automatically, only dependencies from package.json #11917
• typeRoots does not exсlude typings in node_modules #15933
• https://stackoverflow.com/questions/48704043/exclude-types-typings-in-installed-dependencies
• https://stackoverflow.com/questions/52621222/how-do-you-exclude-global-types-declared-in-typescript-definitions
• https://stackoverflow.com/questions/48427807/tsconfig-how-to-ignore-types-whatever-node-modules-for-a-specific-directory
• https://stackoverflow.com/questions/56188867/conflicts-with-global-types-in-typescript
• https://stackoverflow.com/questions/58507122/how-to-exclude-types-from-typescript-global-cache-users-user-library-caches
• https://stackoverflow.com/questions/41558661/ignore-bundled-d-ts-and-use-external-declarations

---

@RyanCavanaugh Hoping this comment can satisfy the Awaiting More Feedback tag. (I'll move this comment to the OP)

[aleclarson]

Can we get an official response on this?

It's very annoying when I'm working on a browser-related project, and @types/node leaks in because a package in devDependencies depends on it.

I tried the "solution project" approach described in #37239 without success.

Related: #22331

[aleclarson]

This seems to be the current proposal:
https://gist.github.com/RyanCavanaugh/702ebd1ca2fc060e58e634b4e30c1c1c

Each file's global scope is determined individually

Really not a fan of that idea. Excluding type packages with file globbing sounds much nicer.

[Fallenstedt]

I experienced a global clash issue today, and reproduced it here
https://github.com/Fallenstedt/ts-globals-clash

Say you had a monorepo with two packages a and b.

• a uses the jasmine test runner
• b uses the jest test runner

The problem is b's test files are only reading jasmine types...when they should have jest types. Having the ability to exclude types for specific directories would be amazing. We are at the mercy of teams using the global feature of typescript well. Having a way to correct their mistakes would be great!

[RyanCavanaugh]

Excluding type packages with file globbing sounds much nicer.

This is just going to create compile errors in lib files that need them (and they surely must need them, otherwise they wouldn't reference them in the first place). The problem here isn't that random definition files end up in your program, the problem is that transitive dependencies end up in your program even though they're immaterial to your particular use case.

[trusktr]

Hello everyone and @RyanCavanaugh (and @aleclarson because you pointed out Ryan's proposal).

I've come up with a new compiler option idea that may solve some of the problems above (unless I missed that such a solution already exists):

#42003

The hypothetical new declareOnImportOnly, when set to true, would prevent global and module augmentations from running unless you explicitly import the file that the augmentation code is inside of.

Rather than all declare global and declare module definitions eagerly making their way into your scope from any file in your project (including node_modules), they will all stay out, unless imported.

This seems like a very practical and standard role for import syntax to have (because you get what you import).

To make this work well, you'd want to import particular files into your project, rather than simply importing package index files that import everything you may not use (this good practice also helps reduce bundle size without any tooling).

[trusktr]

The reason for my previous comment is, apparently, global types are picked up even when tsconfig.json contains

    "types": [],
    "typeRoots": []

and you've imported anything from a package that has global types (even if you never import the files that declare global). It completely ignore types and typeRoots in this case.

The problem here isn't that random definition files end up in your program, the problem is that transitive dependencies end up in your program even though they're immaterial to your particular use case.

@RyanCavanaugh Another problem is that some parts of one project need certain globals, while other parts of a project need other globals.

For example, having two forms of JSX in a project where some files need to pick up React's global JSX, and in the other files we want some other JSX types without React's JSX types polluting global.