Why does the typings tool deliberately create duplicate sets of typings?

Question

Reading the Angular 2 Quickstart I came across this section under TypeScript Configuration:

Typing file collisions

The TypeScript compiler does not tolerate redefinition of a type. For example, it throws an error if it's given two definitions for the Promise type.

Double definitions are common. In fact, the typings tool deliberately creates duplicate sets of typings (for reasons best explained elsewhere). Look in the project structure for the typings folder where we should find something like:

typings
  browser
    ambient
      es6-shim
        es6-shim.d.ts
  main
    ambient
      es6-shim
        es6-shim.d.ts
  browser.d.ts
  main.d.ts

The es6-shim typings are duplicated and the browser.d.ts and main.d.ts have overlapping content.

If I read the typings readme, it says:

If you're building a front-end package it's recommended you use typings/browser.d.ts. The browser typings are compiled by following the browser field overrides.

Questions:

Why does the typings tool deliberately create duplicate sets of typings?

Why is it recommended you use typings/browser.d.ts for front-end packages?

My guess is because supporting the browser field can create different types?

If so what is the browser field and in which way does it change typings?

Answer 1

Your guess was right. Typings recognizes that packages can function differently on the browser and in other locations. This feature is unnecessary for most common packages because isomorphic JS is trendy and many packages function identically on all JS environments.

If however, my code was deliberately checking the environment for functionality, or if I wanted to prevent users from using features that are broken in the browser, it would be helpful to have.

Here's an example. I have a color picker package. This package, if I'm on a desktop, will allow me to pick a color from anywhere on my screen. Obviously this relies on system-level APIs, and can't be used by the browser. On the other hand, my browser can pick the color within the browser window. Rather than release an entirely new package, I expose different typings to a programmer so they know which functionality is permitted based on their environment.

Ultimately, there's little cost to you (other than file space on your machine) and potentially functionality that would otherwise be impossible.