Visual Studio 2010 TypeScript Build Tool

TypeScript is a new language from Microsoft. It is actually an Open Source project hosted in CodePlex. You can refer to many of the other articles in this web site for more about TypeScript. TypeScript programs are converted to JavaScript. Therefore, to develop TypeScript programs in Visual Studio we need to have Visual Studio process the TypeScript programs.

This article is written for Visual Studio 2010 (VS 2010). The procedures for doing what is described in this article change in every version of VS, not always for the better. I know that VS 2008 has a more convenient way to do this, but I forget the details. If you only need to work with TypeScript (and optionally HTML) in a project then this will make it easy to do. This article shows how to specify a Custom Build Tool for TypeScript programs. A VS 2010 Custom Build Tool is a way to specify a program, such as a compiler, to be used to process a file in a project. A Custom Build Tool can be specified to do what we need done for TypeScript programs. If you are anxious to see the details of what that is, jump ahead to Specifying the Custom Build Tool.

I will explain what a custom build tool is. If you specify a custom build tool for a file in a VS 2010 project, then when you build the project, if the file has been modified since the last build, then the file is processed by the specified tool. Let me say that in other words. I will use the example of a C# program. The C# compiler is csc.exe. If a .cs file (C# program) in a project has been modified after the last build was done, then the file is processed by the tool specified for the file, which is csc.exe for C# programs. For TypeScript, the tool (compiler) is tsc.exe. Therefore we want VS to execute tsc.exe for each .ts file in our project when the .ts file has been modified after the last build.

There is one other detail. I am using a C++ project for this. I know that seems strange, but to do what is described here (and as far as I know), it is a requirement that a C++ project be used, eventhough we have no C++ programs in the project. You do not need to understand why but I will try to explain. C++ is the only language that VS supports that is unmanaged or that can be unmanaged. In managed languages, only one language can exist in a project; projects for managed languages (other than C++) cannot mix languages. C++ projects however can include files containing other computer languages, to be compiled by a compiler other than C++. Therefore, for projects other than C++, VS uses one and only build tool (compiler), such as csc; there is no need to specify a custom build tool for any file except the one type of file that the project builds. Items of a C++ project can be other than C++ and therefore C++ projects support customization of what tool to use to build items.

If you have not yet installed the TypeScript plugin then follow the instructions in TypeScript With Visual Studio 2010 to do that. You will need to know the directory where the tsc command was installed, the directory will be used later in this article.

It is possible to do something like this for a file in a managed project in VS 2010 but it is not so easy to figure out. It is easier to use when it is set up but I need to learn more before I can explain it for others. I hope you understand all that but the following is the important part.

You can create any type of C++ project but for this article I will create an empty C++ project. Therefore in VS you can do:

"File" | "New" | "Project..."

Then in the "Installed Templates" click on the "Visual C++" node. Then in the middle pane click on "Empty Project". Give a name for the project; I used "TypeScriptHello". Change the Location if you need to. The window should look as in the following:

Then click "OK".

Next we will add a HTML file. A HTML file is not necessary for this but it makes the sample more interesting. Go to the Solution Explorer and right-click on the project. Select "Add" | "New Item...". You will get an "Add New Item" window. In the middle pane, select "HTML Page (.htm)". Specify a name for the file; I used "TypeScriptHello.html". The window should look as in the following:

Then click "OK".

Next we will add code to the HTML file. You only need to add one line. First ensure you are in the "Source" view, then add the following line between the <body> and </body> tags:

<script src="TypeScriptHello.js" type="text/ecmascript"></script>

Note that the name in the preceding src attribute must be the same as the ts file you created except it has "js" for the extension instead of "ts".

Next we will add a text file then rename the extension from "txt" to "ts" (ts is the extension for TypeScript files). Go to the Solution Explorer and right-click on the project and select "Add" | "New Item..." again. In the middle pane, select "Text File (.txt)". Specify a name for the file; I used "TypeScriptHello". The window should look as in the following:

Then click "OK".

Next we will rename the file. Go to the Solution Explorer and right-click on the file. Select "Rename", then change the extension to "ts". Next we will add code to the ts file. For the purposes of a very simple sample, just put the following one line in the file:

document.body.innerHTML = "TypeScript says Hello";

That takes care of the preliminaries.

Specifying the Custom Build Tool

Now for the important part. We need to modify the properties of the TypeScript file to specify a Custom Build Tool that specifies the TypeScript compiler. Right-click the ts file and select "Properties". You will see a window as in the following:

First, in the top-left is the "Configuration" box; click on it and select "All Configurations". Then click on the box to the right of "Item Type" and select "Custom Build Tool". Then click "OK". Then do it again; that is, right-click the ts file and select "Properties", then in the top-left click on the "Configuration" box and select "All Configurations". Note that in the left pane there is now a node (which was not there before) for "Custom Build Tool"; expand it and click on the "General" item. Then fill in the "Command Line", "Description" and "Outputs" fields with the following:

Command Line

"C:\Program Files (x86)\Microsoft SDKs\TypeScript\0.8.0.0\tsc.exe" --out .\%(Filename).js "%(FullPath)"

Description

Compiling %(Filename).ts

Outputs

.\%(Filename).js

Note that for the "Command Line" you will need the the directory where the tsc command was installed, as I mentioned previously. The "Outputs" is critical since that is what VS uses to determine whether the file needs to be built (compiled from the TypeScript input). The "Description" is for you; it is what will appear in the build output when the file is built.

The file properties should now look like:

With that Custom Build Tool, whenever you build the project and the TypeScript file has been modified, VS will execute the TypeScript compiler (tsc.exe) to convert the TypeScript to JavaScript.

Build the project using "Build" | "Build Solution". In the VS "Output" window you should see something like:

Then go to the Solution Explorer and right-click on the HTML file then select "View in Browser". You will get a page that just has "TypeScript says Hello" in it. Note that the message was put in the HTML from the JavaScript file yet we did not create the JavaScript file; the TypeScript compiler generated the JavaScript file from the TypeScript file.