typescript ambient declarations, global.d.ts, lib and typeRoot.md

When using typescript, you may have global ambient declarations you need to add.

For example, my HTML defines several variables prior to my main .js file being loaded and executed. The .js file, packed using webscript and written in typescript, needs access to those variables.

Accesing the HTML variables is much like accessing “window” inside of a .ts file. The typescript compiler declares a window object for us and makes it available without import in our .ts files.

We clearly need something like that.

google searching did not yield alot of insight, but the key thoughts you need to know are:

• typescript reads all your files in your compiler path e.g. src then compiles the file you want to compile and output.
• typescript has a search path algorithm that is used when importing modules. This search path is not relevant to solving the global ambient problem.

Global ambient can be declared in a global.d.ts file:

declare const myvar: boolean

The real question is whether you should put them in your compile path, such as src/global.d.ts or in a place such as your “typeRoot” setting in tsconfig.json.

The short answer is that you can put global.d.ts into your src/ directory (or whatever you have set as your compiler path to find source files). The compiler will automatically pickup global.d.ts when it sweeps through and “loads” all of your source files. If you were to create a “global.ts” file, it would be picked up and superscede the global.d.ts so use a filename that is not being used already. You could includes global.d.ts anywhere in your paths so you could add this to a variety of places in your source tree it does not have to be at the root. Note that any files, even index.d.ts, inside a sub-directory, will be picked up so you could add “globals” within a sub-directory. If you define a module “src/foo/foo.ts” and then add “src/foo/index.d.ts” the compiler picks up foo.ts and index.d.ts. However, if you add a “foo/index.ts” and keep “foo/index.d.ts” obviousuly, “foo/index.ts” will take precedence. Generally, just stick to global.d.ts or interfaces.d.ts or something unique and put it in smart spot to be picked up.

Why not put them under your typeRoot folder? For example, typeRoot may be set to “node_modules/@typings” and “./typings”. These files are only searched when importing modules. They are not in the compiler path by default. If you added “./typings” to your “source” path then they would be found because they are in the compile path. You use “./typings” to add types to npm modules, for example to add types to a purely javascript npm module.

You could use the tsconfig “lib” setting to include your global.d.ts file in the compilation. That’s a valid use for it. However, once you set “lib” in tsconfig.json, you must include all libs you need e.g. esnext, dom. Once lib is present, it is the full specification of the “lib”—your entries do not add to the lib path. It would have been nice to have a “moreLib” setting :-). So its more work to use lib vs global.d.ts.