Repository: TypeScript
Issue: Multiple UMD typings in one file.d.ts
Labels: Suggestion,Awaiting More Feedback

**TypeScript Version:**  2.4.1

**[1]** Simplistic scenario: I am Facebook and I want to ship typings for both `@types/react` and `@types/react-dom` in one file.

Currently those are 2 files, and they use UMD typings with `export as namespace`. You can:
  * either move them to be non-script module-only with multiple `declare module "react"`, `declare module "react-dom"`;
  * or make them both scripts with `declare namespace React`, `declare namespace ReactDOM` inside.

* * *

**[2]** Another more realistic scenario: plugins/extensions.

I am GitHub and I want to enable extensions to my shiny new GitHub Desktop (Electron) app. I want to ship a bundled `EverythingYouNeed.d.ts` file, embedding typings for the specific React version, for the specific RX version, and of course GitHub-specific APIs and extension points' typings.

At runtime I load React, ReactDOM, RX and bunch of GitHub APIs on global — so technically I can manually edit 3rd party typings from UMD style to namespaced style, before bundling them together. Extensions will just take everything off global. But it's a lot of fiddly work **over external assets (DTS)**. Maintenance cost is high.

* * *

**[3]** My actual realistic scenario is similar to GitHub one above, but in a corporate environment. I am preparing a tooling for the individual departments to use as a base for creating HTML apps. I want it to be as bundled and blackboxed as possible. Specific 3rd party libraries, specific versions etc.

As much as I can bundle JS, HTML and CSS and even compress, currently I am forced either to distribute a large number of individual decl.d.ts, or hand-edit those to allow bundling together.

For the interest of disclosure, currently I partially process external DTS files with RegExes, and partially manually edit to fit them in the bundle. Quite embarrassing!

Suggestion
=======

Two things:
* Export specific module as a specific namespace
* Module-aware syntax in non-module files

Exporting specific module as namespace
-------------

**react-bundled.d.ts**
```typescript
declare module "react" {
 // declarations for React stuff...
}
export module "react" as namespace React;  <-- see export specific module

declare module "react-dom" {
 // declarations for ReactDOM stuff...
}
export module "react-dom" as namespace ReactDOM;  <-- see export specific module
```

Module-aware syntax in scripts
------------

**react-bundle-maker.ts**
```typescript
declare import * as React from "react";
declare import * as ReactDOM from "react-dom";
```

I tell the compiler: consider typings for module X imported by the external forces. Now let me just use it.

And if I run that `react-bundle-maker.ts` file from above through `tsc --declaration`, I expect to get the same output as `react-bundled.d.ts` above.

Why these suggestions
============

These two suggestions (with possible tweaks etc.) avoid dilemmas and problems of various kinds of loaders and bundlers as discussed in [4433 Bundling TS module type definitions](https://github.com/Microsoft/TypeScript/issues/4433), [6319 Support 'target':'es5' with 'module':'es6'](https://github.com/Microsoft/TypeScript/issues/6319) and [4434 Bundling TS modules](https://github.com/Microsoft/TypeScript/issues/4434).

External loaders are dealing OK with runtime loading, but TS needs to improve its story on compile-time with modules — particularly in case of bundling for a large app scenario.

One specific hole I didn't want to dig is specifying the 'root' module for bundling. Ability to use `declare import` in scripts solves that neatly.

If we allow features I suggested, or something other to that effect, we'll have much smoother bundling workflow for DTS files.