This quick start guide will teach you how to wire up TypeScript with Knockout.js.

We assume that you're already using Node.js with npm.

Table of Contents #

Lay out the project #

Let's start out with a new directory. We'll name it proj for now, but you can change it to whatever you want.

mkdir proj
cd proj

To start, we're going to structure our project in the following way:

proj/
   +- src/
   +- built/

TypeScript files will start out in your src folder, run through the TypeScript compiler, and end up in built.

Let's scaffold this out:

mkdir src
mkdir built

Install our build dependencies #

First ensure TypeScript and Typings are installed globally.

npm install -g typescript typings

You obviously know about TypeScript, but you might not know about Typings. Typings is a package manager for grabbing definition files. We'll now use Typings to grab declaration files for Knockout:

typings install --ambient --save knockout

The --ambient flag will tell Typings to grab any declaration files from DefinitelyTyped, a repository of community-authored .d.ts files. This command will create a file called typings.json and a folder called typings in the current directory.

Grab our runtime dependencies #

We'll need to grab Knockout itself, as well as something called RequireJS. RequireJS is a library that enables us to load modules at runtime asynchronously.

There are several ways we can go about this:

  1. Download the files manually and host them.
  2. Download the files through a package manager like Bower and host them.
  3. Use a Content Delivery Network (CDN) to host both files.

We'll keep it simple and go with the first option, but Knockout's documentation has details on using a CDN, and more libraries like RequireJS can be searched for on cdnjs.

Let's create an externals folder in the root of our project.

mkdir externals

Now download Knockout and download RequireJS into that folder. The latest and minified versions of the files should work just fine.

Add a TypeScript configuration file #

You'll want to bring your TypeScript files together - both the code you'll be writing as well as any necessary declaration files.

To do this, you'll need to create a tsconfig.json which contains a list of your input files as well as all your compilation settings. Simply create a new file in your project root named tsconfig.json and fill it with the following contents:

{
    "compilerOptions": {
        "outDir": "./built/",
        "sourceMap": true,
        "noImplicitAny": true,
        "module": "amd",
        "target": "es5"
    },
    "files": [
        "./typings/main.d.ts",
        "./src/require-config.ts",
        "./src/hello.ts"
    ]
}

We're including typings/main.d.ts, which Typings created for us. That file automatically includes all of your installed dependencies.

You might be wondering about a separate file named browser.d.ts in the typings folder, especially since we're going to run this in a browser. The short story is that some packages are tailored differently by tools that target browsers. In general, these situations are niche scenarios and we won't run into those, so we can ignore browser.d.ts.

You can learn more about tsconfig.json files here.

Write some code #

Let's write our first TypeScript file using Knockout. First, create a new file in your src directory named hello.ts.

import * as ko from "knockout";

class HelloViewModel {
    language: KnockoutObservable
    framework: KnockoutObservable

    constructor(language: string, framework: string) {
        this.language = ko.observable(language);
        this.framework = ko.observable(framework);
    }
}

ko.applyBindings(new HelloViewModel("TypeScript", "Knockout"));

Next, we'll create a file named require-config.ts in src as well.

declare var require: any;
require.config({
    paths: {
        "knockout": "externals/knockout-3.4.0",
    }
});

This file will tell RequireJS where to find Knockout when we import it, just like we did in hello.ts. Any page that you create should include this immediately after RequireJS, but before importing anything else. To get a better understanding of this file and how to configure RequireJS, you can read up on its documentation.

We'll also need a view to display our HelloViewModel. Create a file at the root of proj named index.html with the following contents:

Hello from todo and todo!

Language:

Framework:

Notice there are three script tags. First, we're including RequireJS itself. Then we're mapping the paths of our external dependencies in require-config.js so that RequireJS knows where to look for them. Finally, we're calling require with a list of modules we'd like to load.

Putting it all together #

Just run:

tsc

Now open up index.html in your favorite browser and everything should be ready to use! You should see a page that says "Hello from TypeScript and Knockout!" Below that, you'll also see two input boxes. As you modify their contents and switch focus, you'll see that the original message changes.

Documentation generated by mdoc.