Fixing compilation issues while using declare module or similar "global" type declarations

[timocov]

Related issues: #231, #102, #203.

The situation

You added some d.ts file with fancy declare module statements (or similar "global-like" statements that affects the compilation in other places indirectly) into your project and the compilation works fine but when you're trying to bundle declaration files with this tool it fails with errors that the compiler cannot find module or symbol (see #231 or #102 (comment) for more examples).

Problem

When you run tsc (with a project file that is loaded by default or when you specify -p or -b, not with files provided via arguments) the compiler loads all the files specified in include option from the config into the compilation and parses, analyses and do type checks them as a compilation unit. Thus, if you have "*.ts" in your include option it will load .d.ts files too so you see no errors while compiling.

It is a good (you just added one file and it is automatically added into your compilation, less work to do 🎉) and at the same time bad thing (as globals are applied to all your codebase independently if you actually imported them yet or not, but this is different topic, hopefully almost no one uses globals nowadays), but it exists.

On the other hand, this tool to speed up the work time (imagine you have 500k lines of code and to generate "API" you use only 10k of them, probably you don't want to compile everything and wait for 3 minutes every time when you can get it done in less than one) as an entry point for the compiler provides only entry points you specified in the config/CLI, so instead of bunch of files from your src folder (just an example) the compiler gets only one or few files - entry points and load the rest later - but only these that were imported directly in your files.

This causes the issue - some of the files might not be loaded automatically while using the tool and you get errors like "cannot find symbol/node/module".

Solution

To solve the problem you need to explicitly specify what files you want to get loaded and where (but it has to be explicit!). To achieve that there are several approaches based on the situation and type of declarations (but you can ignore it and use one that you like):

1. Explicitly "load" such files by using triple-slash directives i.e. /// <reference file="../path/to/file.d.ts" > - this works similarly to import statement but not include referenced file into a bundle, the compiler loads it only for types. Technically speaking it needs to be specifier in every file where you use types from a declaration file, but you can try to load it only in one of them and hope that it helps 😂 (it could be an entry point tho).
2. In some cases you can rely on types compiler option that pre-loads specified types from "types" folders (can be controlled by using typeRoots compiler option).

Also see my response here.

If you have any ideas/thoughts/questions - please ask them in this thread.

[nolawnchairs]

This doesn't work in my case. My library has type augmentations for ExpressJS that I use to add properties to a typed object.

declare namespace Express {
  interface Request {
    policies?: string[]
    skipAuth?: boolean
  }
}

The tsc command is OK with this, but fails when I run dts-bundle-generator. I need to add @ts-ignore to the code, which kind of defeats the purpose of adding the type augmentations in the first place. How would I add a specific file, in my case types.d.ts so I can generate type files?

[timocov]

Can you provide a repro for your issue?