Multiple UMD typings in one file.d.ts

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

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

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, 6319 Support ‘target’:‘es5’ with ‘module’:‘es6’ and 4434 Bundling TS modules.

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.

[jrieken]

@jrieken can you give a brief overview, what do you do to you generate monaco.d.ts?

That is a very special process to which @alexandrudima can answer questions. See these two files to find you ways into it: https://github.com/Microsoft/vscode/blob/master/build/monaco/api.ts#L364, https://github.com/Microsoft/vscode/blob/master/build/monaco/monaco.d.ts.recipe#L1

[weswigham]

On practical side, zipping does not work, because extension writers need to use OTHER components except for those included with the app.

You can list multiple typeRoots in a tsconfig and keep their stuff and your stuff separate.