Posted by on Dec 4, 2015 in #Office365Dev, Visual Studio | 4 comments

If you would like to use something that is strongly typed compared to JavaScript when building your Office add-ins, there’s a superset of JavaScript called TypeScript. It compiles back to plain JavaScript and runs in any browser, any host and any operating system.

It’s a great way to help you ensure the quality and code maintainability of your project. Also, if you’re coming from a more strongly typed programming language (like C#, Java, etc.), TypeScript can be your way into the world of JavaScript.

To get started, create your Office add-in project in Visual Studio. Get the Office add-in templates in Visual Studio 2015 by downloading the Office developer tools at: http://aka.ms/GetLatestOfficeDevTools

Depending on what type of Office add-in you’re creating, you’ll end up with a slightly different structure. Either way, you want to rename the file endings of all the *.js files to *.ts. This is what switches your JavaScript files into TypeScript and configures your project to compile them.

jsrename

You’ll notice that you will get tons of errors in your *.js files. That’s because the TypeScript compiler doesn’t know about some of the libraries in your project. For instance, jQuery and Office.js. In order to help our IDE here, we need to get something called definition files (or type definitions) for these libraries. There’s a huge open source project with type definitions for just about any JavaScript library that you can think of available at: https://github.com/DefinitelyTyped/DefinitelyTyped

Go ahead and grab the type definitions (*.d.ts) for jQuery and Office.js:
https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/jquery/jquery.d.ts
https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/office-js/office-js.d.ts

Include them in your project and the TypeScript compiler should be much happier!

definitionfiles

In the Home.ts file (or any other TypeScript file that you happen to be working in) – make sure that your reference tags are valid and include the type definitions and other TypeScript files you need. I updated mine like this:

With the type definitions and reference tags in place, you get the benefit of IntelliSense and other valuable tooling – because our IDE now knows much more about the code we are writing. However, there is still a couple of red squiggly lines in there. Even though we made the App.js file a TypeScript file, we need to make sure to write that code in TypeScript – because right now it’s just plain JavaScript (which is valid TypeScript, but it does not provide much usefulness).

ts

I rewrote the default App.js file to TypeScript like the following. You can learn more about how to write TypeScript at the TypeScript homepage: http://www.typescriptlang.org/

The compiler generates JavaScript from your TypeScript files, that’s what makes it work everywhere. So you should continue to reference *.js files in your HTML. If you browse your file system, you can see that the *.js files (along with *.js.map files) will be located besides the *.ts files.

This is what the compiled App.ts (JavaScript output) file looks like.

You can also customize your build phase and debugging experience in a few ways. If you get into the properties of your Visual Studio project and locate the TypeScript Build tab – you can select things such as the ECMAScript version (what’s ECMAScript you may ask – head to: http://blogs.msdn.com/b/tess/archive/2015/11/12/mastering-asp-net-5-without-growing-a-beard.aspx), source map location, output properties and more.

tsprops

When your code grows larger, investing in using something like TypeScript really proves to be valuable. At some point you will surely refactor code, hunt bugs and debug – and with TypeScript your life gets a bit easier! You can use Visual Studio to debug your TypeScript code and not have to deal with the plain JavaScript itself (this is what the *.js.map files are good for, mapping between the TypeScript and JavaScript).

A sample project extending the Visual Studio 2015 template for an Office task pane add-in with TypeScript and TypeScript type definitions is available at: https://github.com/simonjaeger/Office-Addin-TypeScript

-Simon Jaeger