Post headline image

Tips for Upgrading Your Kendo UI JavaScript to TypeScript

As a C# developer turned JavaScript developer, I can't even begin to tell you how much more confident TypeScript makes me feel about the quality of my JavaScript. The thing I always hated most about JavaScript is that while the typing system allows anything to be anything, the only thing it usually allows the code to be, is terrible. Terribly designed, terribly performing, and terrible to debug. But with TypeScript, I can enforce the way I want JavaScript to work, without having to learn a completely new language like CoffeeScript. As a C# developer, TypeScript works they way I work, and I like that.™

Telerik recently announced that the Q1 2013 release of Kendo UI would ship with TypeScript support. I personally was very excited about this, as I've been passive-aggressively tweeting to them about TypeScript support for months. The team graciously let me test it out while they were working on it internally, and I wanted to pass along some tips to help make your own transition as smooth as possible. Since the first beta comes out tomorrow, I thought I'd post this now so you can prepare. 

Tip #1: Navigating the kendoui.d.ts TypeScript file.
Telerik uses an automated tool to assist in generate its TypeScript definition file, but then enhances that output with some manual work, for things like event handlers and so forth. Because of this, there are actually two "parts" of the kendoui.d.ts file. The top part of the file has all of the manual definitions, and the bottom part has the automated ones. I imagine their tooling takes the flat file for the manual definitions and appends the automatic ones underneath (hopefully they will open-source this tool sometime in the future, hint hint). So be aware that the namespaces and modules are defined twice. If you Ctrl+Click a definition and navigate to it's source, and don't find the properties or methods you are looking for, just remember there is another set of definitions elsewhere in the file. Ctrl+F is your friend.

Tip #2: Pull your JavaScript out of your Razor Views
When I write an ASP.NET MVC View, I usually start by scaffolding the HTML, and then I dump whatever JavaScript I'm going to need inline with the page, and at the bottom of the view. This way I can test the code and tweak the JavsScript without flipping through any more editor windows than I have to. The problem with this is, the JavaScript Intellisense engine is not pluggable in Visual Studio (at least, not right now), so Microsoft can't leverage the TypeScript IntelliSense in .CSHTML files like it can in .TS files. For existing apps, the workflow that works well for me is to prototype what I want in the view itself, get everything functioning, and then move the JavaScript to a page-specific TypeScript file and get to work tightening the screws. It may seem counter-intuitive at first, but remember I already converted my core libraries to TypeScript, wo what's left on the page is usually related to wiring up elements to events and so forth.

Tip #3: Annotate *everything*
The main value of TypeScript is in having confidence that your code will work the way you intended. This is accomplished by adding annotations to your function parameters with types that you've either created in your app, or from external type definitions. The kendo.all.d.ts file is one such definition, and the DefinitelyTyped GitHub repository has a TON of other TypeScript definition files for most of the commonly-used libraries. But you can't have that confidence if you don't take the time to annotate *everything*.

With Kendo UI, I've found that the deeper you get into the API, the more helpful TypeScript is. Take, for example, specifying the Editor for a Grid Column. Without TypeScript, you are left with this (questionable property highlighted in yellow):

But, with TypeScript, by annotating the function parameters, now you get help.

Note that operatingExpenseColumns is annotated as an array of GridColumns, and the Editor function for the AnnualIncrease editor function has parameter types as well. If you hover your mouse over "editor" in that definition, you'll see what types the parameters are supposed to be. The namespaces are virtually identical to what you are already used to, so if you can't find what you're looking for, just type "kendo." and IntelliSense will help you though.

Tip #4: Change your DataSource Model definitions
IMHO, making a mistake in a Kendo DataSource definition is the easiest way to break your whole app, so getting it right the first time is important. Before this release, the DataSource control only allowed for one way to define your model, through key-value pairs. That setup looks very similar to an object definition, but does not work well with TypeScript. So they added a new method, which is to create an array of DataSourceModelField objects instead. So instead of our original definition:

...after some slight modifications, you get this instead. Note the type annotations, and the fact that fields are now string-based.

Tip #5: Pay attention to value types
One problem I ran into in the conversion was, after the conversion was finished, none of my Grids were honoring the column widths specified in the ColumnDefinition. In my JavaScript version, I had specified the width as an integer, which Kendo dutifly honored. But not so with my TypeScript definition, and TypeScript did not throw an error. Grid column widths needs to be specified as a string with a unit of measurement at the end. So instead of this  you need this .

I hope that gets you up and running with TypeScript for Kendo UI. The whole experience for me was very pleasant, and I'm grateful for the opportunity to contribute in a small way towards the end result. If you have any other conversion tips, please feel free to leave them in the comments.