Merge pull request basarat#581 from simon-robertson/patch-1

Extended the use case for the global.d.ts file

Author: basarat

docs/project/globals.md

@@ -4,7 +4,13 @@ We discussed *global* vs. *file* modules when covering [projects](./modules.md)
 
 Nevertheless, if you have beginner TypeScript developers you can give them a `global.d.ts` file to put interfaces / types in the global namespace to make it easy to have some *types* just *magically* available for consumption in *all* your TypeScript code.
 
-> For any code that is going to generate *JavaScript* we highly recommend using *file modules*.
+Another use case for a `global.d.ts` file is to declare compile-time constants that are being injected into the source code by Webpack via the standard [DefinePlugin](https://webpack.js.org/plugins/define-plugin/) plugin.
 
-* `global.d.ts` is great for adding extensions to `lib.d.ts` if you need to.
-* It's good for quick `declare module "some-library-you-dont-care-to-get-defs-for";` when doing JS to TS migrations.
+```ts
+declare const BUILD_MODE_PRODUCTION: boolean; // can be used for conditional compiling
+declare const BUILD_VERSION: string;
+```
+
+> For any code that is going to generate *JavaScript* we highly recommend using *file modules*, and only use `global.d.ts` to declare compile-time constants and/or to extend standard type declarations declared in `lib.d.ts`.
+
+* Bonus: The `global.d.ts` file is also good for quick `declare module "some-library-you-dont-care-to-get-defs-for";` when doing JS to TS migrations.