This project is read-only.


Split official "lib.t.ts" into different files / Special references clauses


Currently, lib.d.ts has too many things that shouldn't be there or there should be an option to include. By that I mean the sections:
  • IE10 ECMAScript Extensions
  • IE9 DOM APIs
  • IE10 DOM APIs
  • Windows Script Host APIS
Basically, everything that is not "core javascript api available to most browsers" should not be there. I believe this causes some problems as someone developing depending on the IDE can accidentally use a method that is not generally available in other browsers.

I know that the nature of javascript is dynamic and in the end this could happen to any method, not only those IE specific, but I think you get the point.

An idea to solve this would be to split the lib.d into multiple files, and allow for a special <references /> clause that would include the definitions.

So, imagine that you split the lib.d.ts into:
  • js.d.ts (only the core of javascript, curently most of lib.d.ts)
  • ie.d.ts
  • wsh.d.ts
  • etc
That brings us to the references tag. This tag would work just like today references, but instead of:

/// <reference path="~/lib.d.ts" />

could be something like:

/// <reference def="@/lib.d.ts" />

The @, just like the ~ would make a relative path to some special folder.

I suggest these folders would be searched in the following order:
  • Project specific "definitions folder" (eg. ~/Scripts/Definitions, preferably customizable)
  • Typescript extension folder (current home of lib.d.ts)
So, creating a blank typescript file would be the same as adding a line like this at the top of the file:

/// <reference path="@/lib.d.ts" />

which in turn would be a small file with a couple of <references /> tags to the other "core, ie, wsh", etc in the same order are they are in the file today, maintaining backward compatibility.

But if you add a references line to your file using the @ syntax, the compiler wouldn't add the default one and let the user choose the specific definitions it would include. (An alternative to this flow would be to have a specific tag like "<reference clear='true' />" or similar to remove any default references).

This would greatly improve the code completion for projects for node.js, browser extensions and even web pages that don't want to use the IE extensions by default, but restrict the development to general available JS, so you get build errors if you try to go out of the desired scope.

Also, as a bonus of this method, people could have their own "lib.d.ts" in the project's definition folder, so they could have a "default reference" for all project files without having to add the <references /> line to each file, as the compiler would just use the first lib.d.ts that it finds using the default reference it adds to "@/lib.d.ts". A lib.d.ts for a chrome extension could look like this:

<references path="js.d.ts" />
<references path="chrome.d.ts" />
<references path="jquery2.d.ts" />

And all files in the current project would just have that by default.

What do you think?
Closed Jul 28, 2014 at 11:18 PM by jonturner
As part of our move to GitHub, we're closing our CodePlex suggestions and asking that people move them to the GitHub issue tracker for further discussion. Some feature requests may already be active on GitHub, so please make sure to look for an existing issue before filing a new one.

You can find our GitHub issue tracker here:


nvivo wrote Apr 29, 2013 at 7:17 PM

Here are some more thoughts on how to simplify/implement this

If lib.d.ts was just another definition file in the project, added by the template as a nuget package, there would be no need to have an extra special char like @ on the path. Of course today you can call tsc --nolib to achieve a similar goal, but the point here is to make things more streamlined. So, by doing that the compiler would need to look for a custom lib.d.ts (or any other filename) somehow.

That doesn't mean necessarily that the compiler needs to look for a magic file in the project folder, but if in addition to "--nolib", there could be a "--definitions file1.d.ts,file2.d.ts,etc", the tooling could just add lib.d.ts by default as the first definitions, unless --nolib is defined.

If breaking some compatibility is allowed, compiler could not add anything by default and just leave it to the --definitions option and VS would add by default.

--definitions would allow only .d.ts files and they would need to be real definitions, only interfaces and no code whatsoever.

By having lib.d.ts and its parts as nuget packages, people would just maintain other sets of packages for nodejs, and change the default definition parameter to something else in the compiler options.

danquirk wrote Jun 12, 2014 at 12:46 AM

See also for splitting lib.d.ts based on ES version differences.