How To Use

This is a how to guide on how to develop with Dojo 1 in TypeScript using dojo/typings.

Installation

The easiest way to install is via npm:

> npm install dojo-typings --save-dev

It is unlikely that you will require the typings in a build application, so --save-dev will add the dependency just to the development dependencies.

This will install the lastest version of the dojo-typings into ./node_modules/dojo-typings. The npm package does not include any of the tests or examples. If you want the tests and examples as well, you should just git clone the repository:

> git clone https://github.com/dojo/typings.git dojo-typings

This will clone the repository into dojo-typings of the current working directory.

Referencing

Depending on your development environment, you maybe managing your TypeScript typings in a variety of ways.

tsconfig.json

In order to have the typings available as part of your project using tsconfig.json you will need to add the appropriate version of Dojo/Dijit/DojoX to your files property:

{
    "compilerOptions": {
        "target": "es5",
        "module": "amd",
        "moduleResolution": "node"
    },
    "include": [
        "./src/**/*.ts",
        "./node_modules/dojo-typings/dojo/1.11/modules.d.ts",
        "./node_modules/dojo-typings/dijit/1.11/modules.d.ts",
        "./node_modules/dojo-typings/dojox/1.11/modules.d.ts"
    ]
}

If you are specifying lib in the tsconfig.json you also need to include scripthost, which brings in a few specific typings that are used by some legacy parts of Dojo 1:

{
    "compilerOptions": {
        "target": "es5",
        "module": "umd",
        "moduleResolution": "node",
        "lib": [
            "dom",
            "es5",
            "scripthost"
        ]
    }
}

tsd.d.ts

If you are managing your typings via a tsd.d.ts then you should add references to this file, for example:

/// <reference path="../node_modules/dojo-typings/dojo/1.11/index.d.ts" />
/// <reference path="../node_modules/dojo-typings/dojo/1.11/modules.d.ts" />
/// <reference path="../node_modules/dojo-typings/dijit/1.11/index.d.ts" />
/// <reference path="../node_modules/dojo-typings/dijit/1.11/modules.d.ts" />
/// <reference path="../node_modules/dojo-typings/dojox/1.11/index.d.ts" />
/// <reference path="../node_modules/dojo-typings/dojox/1.11/modules.d.ts" />

tsc

If you are just managing the command with the compiler, you need to add the appropriate typing files to the command line:

> tsc --target es5 --module amd main.ts ../node_modules/dojo-typings/dojo/1.11/modules.d.ts

Modules

The typings included in the modules.d.ts provide modules in the typical namespacing of modules for Dojo 1. For example the module dojo/query.js is available as dojo/query. If you have a "standard" loader/dojo configuration, this should meet your needs. For example, if your configuration looks something like this, modules.d.ts will work for you:

var dojoConfig = {
    async: true,
    baseUrl: '.',
    isDebug: true,
    packages: [
        'app',
        'dijit',
        'dojo',
        'dojox'
    ],
    selectorEngine: 'lite',
    tlmSiblingOfDojo: false
};

If you have a different namespace for your modules, you can either declare the modules you need, replicating what the exports like in modules.d.ts or copy and rename the modules names in the modules.d.ts. For example, if you wanted to "rename" the dojo/_base/lang module to dojo111/_base/lang you would need a declaration like this:

declare module 'dojo111/_base/lang' {
    const lang: dojo._base.Lang;
    export = lang;
}

Importing

In order to import your modules and use them in TypeScript, you should utilize the ES6 module import syntax. If your environment is setup properly and your IDE integrates into the TypeScript language services, you should be able to import modules and have intellisense code completion. For example, to use dojo/request, you would write something like this:

import * as request from 'dojo/request';

request
    .get('some/stuff.json', { handleAs: 'json' })
    .then((response) => {
        /* do something with response */
    });

Compiling

Dojo 1 modules are all AMD, therefore, you should be using a loader that understands AMD modules. Therefore you are likely to need to emit any TypeScript code as AMD modules, although we are confident with the umd format works with the Dojo AMD loader as well as CommonJS require (as well as many other loaders).

Also, while you might be running in an environment that supports ES6 syntax, interfacing to Dojo 1 with ES6 code has not been tested.

Therefore we recommend the following compiler options:

{
    "compilerOptions": {
        "target": "es5",
        "module": "umd",
        "moduleResolution": "classic"
    }
}

Loader Plugins

One of the current limitations of TypeScript is that it does not have an easy way of supporting dynamic values for module names that resolve to a particular export. Therefore, if you want to utilize a loader plugin, for example to load a text resource, you will need to specify the ambient declaration yourself. You would place this in a .d.ts file within your project, for example:

declare module 'dojo/text!sometext.html' {
    const text: string;
    export = text;
}

Notes

• While TypeScript now prefers the namespace keyword for ambient declarations, since module was a confusing term in relationship to the concept of code modules, we find the name more descriptive when declaring ambient AMD modules, so we use namespace for type declarations and use module when declaring an AMD MID.
• We validate the typings with noImplicitAny set to true and recommend that you use this as well, although if you are trying to port existing code to TypeScript you might find this difficult to do until you have refactored your code base.