The File List

The file list you supply to the compiler is a space-separated list of all the files you want it to compile. This is much like the list you would send to the C# compiler (csc.exe), but with one difference. With csc.exe, you also need to include a list of references to the DLLs containing namespaces and classes your own C# code uses. This is not necessary with TypeScript. The tsc compiler will scan the top of each file in the list supplied for <reference file="..."> statements and include those referenced (both .d.ts and .ts) in its list for compilation. It does the same for files referenced via an import statement in your code.

It will also check those files for <reference> and import statements, include those files, and so on, until it has completely walked through the entire reference tree and has a complete list of files to compile. The net result is that you don’t need to include any declaration files in the file list for the compiler and perhaps fewer .ts files than you thought as well.

Also, unless you send it the --nolib option, the compiler will automatically include the lib.d.ts declaration file for the standard JavaScript runtime library and DOM API. The TLS does the same walk of <references> and import statements as it provides IntelliSense, so if IntelliSense appears to be working correctly across all your TypeScript files, you know your reference tree is intact as well, ready for compilation.

Has Someone Else Written It?

As you know by now, the TypeScript team has written four declaration files:

• lib.d.ts covers the standard JavaScript Runtime Library, HTML5 APIs, and the DOM API.
• jquery.d.ts covers the definitions for jQuery 1.7.
• winjs.d.ts covers the Windows Library for JavaScript (for Windows 8 JavaScript apps).
• winrt.d.ts covers the Windows Runtime Library (for Windows 8 apps).

Beyond these four, the TypeScript community has already done quite a bit of work on both improving these four files and creating many more besides. Currently, the unofficial repository for declaration files is https://github.com/borisyankov/DefinitelyTyped. Here you’ll find updates for the four Microsoft declaration files and several dozen more libraries from AngularJS to QUnit to WebGL. And, of course, if you can’t find the declaration file on DefinitelyTyped, then Google may still be your friend.

Substitute with an Ambient Declaration

All declaration files contain interface definitions for the classes defined in a library and ambient declarations for global variables of those classes. Without these, both the compiler and TLS will complain as soon as you use one of those global variables in your code, and it will not compile.

If you are sufficiently secure in your knowledge of the library you want to use, you can add an ambient declaration for the global variable you want to use and assign it the any type. For instance, let’s suppose you want to use jQuery but don’t have the declaration file at hand. You can declare its global variable like so:

declare var $ : any;
 

and continue to use jQuery with no issue. You’ll get no IntelliSense or type checking—everything will be of the any type—but that’s how we worked with jQuery before anyway.

Use the Compiler to Generate a Declaration File

You saw earlier that the TypeScript compiler will generate a declaration file for you if you pass it the --declaration flag. For example:

> tsc --declaration SimpleLibrary.ts
 

Assuming SimpleLibrary.ts compiles correctly, the compiler will generate SimpleLibrary.js for inclusion in your project releases and SimpleLibrary.d.ts for use in your development work.

This sounds like an ideal solution, and it is—for libraries written in TypeScript. Unfortunately for JavaScript libraries, the compiler accepts only valid TypeScript files. If I wanted to generate my own declaration file for jQuery, I couldn’t just download jquery.js, rename it to jquery.ts, and point the compiler at it: the compiler would throw many errors at it. And even if it did compile, the resultant declaration file would not contain much useful type information and perhaps lose some of the subtlety in the library. Because it is written in plain JavaScript, the compiler perceives all parameters to be of the any type rather than strings, numbers, and so forth. Remember: it is the TLS in the Visual Studio extension that infers types rather than the compiler.

All in all, unless you’re referencing a library written in TypeScript, this is the most unsatisfactory solution of the four. Even Microsoft went down the route of writing a custom script to produce its declaration files based on Web IDL and standards definitions rather than pass the actual JavaScript libraries through the compiler.

Roll Your Own

Like it or not, your best shot may be to write your own declaration file. Remember that a declaration file is just a collection of interfaces and ambient declarations for global variables, values, and functions. For example, lib.d.ts starts by declaring a handful of familiar number-related values before going on to define the interface for the number object type and then a class variable for it:

declare var NaN: number;
declare var Infinity: number;
declare function eval(x: string): any;
declare function parseInt(s: string, radix?: number): number;
declare function parseFloat(string: string): number;
declare function isNaN(number: number): bool;
declare function isFinite(number: number): bool;
 
...
 
interface Number {
    toString(radix?: number): string;
    toFixed(fractionDigits?: number): string;
    toExponential(fractionDigits?: number): string;
    toPrecision(precision: number): string;
}
declare var Number: {
    new (value?: any): Number;
    (value?: any): number;
    prototype: Number;
    MAX_VALUE: number;
    MIN_VALUE: number;
    NaN: number;
    NEGATIVE_INFINITY: number;
    POSITIVE_INFINITY: number;
}
 

One note, though: remember to include a prototype property inside your variable declaration to generate the correct OO properties for JavaScript.

In Your MSBuild File

The key to your projects correctly integrating TypeScript into their compilation is in adding a call to the TypeScript compiler before the actual build. You know from Chapter 1 that if it is installed, the Web Essentials extension compiles our TypeScript files for us on the fly, but when we build the project, Visual Studio will compile them again based on a different set of criteria from those expressed in the Web Essentials Options dialog box (shown earlier in Figure 3-1). The build criteria can be found in the MSBuild file for your project—typically the .jsproj,  .csproj, or .vbproj file in the root directory of your project.

Let’s have a look at the MSBuild file for a TypeScript project and see what it does:

1. Create a new HTML Application with TypeScript project in VS called CompilerTest.
2. Add a second TypeScript file to the project. Call it second.ts.
3. In the Solution Explorer window, right-click the project name and then select Unload Project.
4. Right-click the project name again and click Edit CompilerTest.csproj file.
5. To reload the project back into Visual Studio after you’ve finished looking at this, right-click the project name in the Solution Explorer window and then select Reload Project.

The relevant parts of the file are as follows.

<ItemGroup>
  <Content Include="app.js">
    <DependentUpon>app.ts</DependentUpon>
  </Content>
  <Content Include="second.js">
    <DependentUpon>second.ts</DependentUpon>
  </Content>
  <TypeScriptCompile Include="second.ts" />
  <TypeScriptCompile Include="app.ts" />
</ItemGroup>
 

<Target Name="BeforeBuild">
 

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <TypeScriptSourceMap> --sourcemap</TypeScriptSourceMap>
</PropertyGroup>
 
<Target Name="BeforeBuild">
  <Message Text="Compiling TypeScript files" />
  <Message Text="Executing tsc$(TypeScriptSourceMap)
    @(TypeScriptCompile ->'&quot;%(fullpath)&quot;', ' ')" />
  <Exec Command="tsc$(TypeScriptSourceMap)
    @(TypeScriptCompile ->'&quot;%(fullpath)&quot;', ' ')" />
</Target>
 

<Target Name="BeforeBuild">
  <Exec Command="&quot;$(PROGRAMFILES)Microsoft SDKsTypeScript<VERSION>	sc&quot; @(TypeScriptCompile ->'&quot;%(fullpath)&quot;', ' ')" />
</Target>

<ItemGroup>
  <AvailableItemName Include="TypeScriptCompile" />
</ItemGroup>
<ItemGroup>
  <TypeScriptCompile Include="$(ProjectDir)***.ts" />
</ItemGroup>
 

<Exec Command="tsc$(TypeScriptSourceMap) -c --Target ES5 @(TypeScriptCompile ->'&quot;%(fullpath)&quot;', ' ')" />
 

<ItemGroup>
  <Content Include="app.js">
    <DependentUpon>app.ts</DependentUpon>
  </Content>
  <Content Include="second.js">
    <DependentUpon>second.ts</DependentUpon>
  </Content>
  <None Include="second.ts" />
  <None Include="app.ts" />
</ItemGroup>
 

In Your Web Sites

After your project is compiling your TypeScript to your preference, you still have a couple of points to consider if you’re a web developer.

You can’t embed TypeScript within a web page. TypeScript lives inside its own files. If your current project has web pages with <script> blocks containing actual JavaScript rather than references to files, you’ll need to ask yourself whether there is any way to refactor that JavaScript out to an external file. Chapter 1 provides a very simple example of doing this, so all the event wire-up and scripting is done after the page has loaded. If it’s not possible (perhaps your server-side code injects script into the page), remember that your TypeScript code will still be able to interact with any functions or variables on the page as long as you include ambient declarations for them in your .ts file.

If you’re using the Bundling feature in ASP.NET 4.5’s System.Web.Optimization feature, you may want to use that to gather your compiled JavaScript (not the TypeScript files) into one file rather than using the compiler’s own --out option. Indeed, this approach offers a lot more flexibility if you want to compile several libraries into their own files.

BundleTable.Bundles.Add(
   new ScriptBundle("∼/ts/AllScript.js")
         .IncludeDirectory("∼/ts/", "*.js", true));
 

Remember, however, to reference the bundled JavaScript file in your pages and not the individual JavaScript files.

In the Development Life Cycle

Before wrapping up, it’s worth saying that whatever you can do in JavaScript, you can probably also do in TypeScript, and some more on top of that. Declaration files for popular JavaScript libraries are still being written, and the TypeScript project itself is still a way from wrapping up a v1.0 release. By that time, it would not be surprising to see a complete and cogent application development life cycle based solely in HTML and TypeScript. Consider the following:

• The UI design phase is language-neutral anyway.
• The Class and Module features in TypeScript allow for more-accurate code design, development, and maintenance already.
• The TypeScript debugging story is already getting better through the generation of source map files that allow step-through debugging in Visual Studio.
• Unit testing in TypeScript is already possible with a QUnit declaration file in the works. Other efforts also show that unit testing is possible using Jasmine and Chutzpah. (See the appendix for links.)
• Including TypeScript files in source control is the same as for any other type of file. Just remember not to check in the JavaScript files that the compiler generates from them. After all, you don’t check in your project’s bin and obj folders, do you? Do you?