← TypeScript: Implementing a Simple IOC Container for Service Location

TypeScript: Organizing your code with AMD modules and require.js

October 23, 2012 21 Comments

TypeScript has two methods of generating JavaScript output files: CommonJS, and AMD. CommonJS is the default, and amd modules can be generated by adding the –module AMD option to the compiler flags.

In this post, I’ll show how to create and use AMD modules, as well as configuring require.js by using require.config.

Update

I have updated the source for this article to 0.8.1 version of the compiler, which can be found here.

The older 0.8.0 source for this solution can be found here

Creating a default project using CommonJS

Let’s start with a standard new TypeScript project – which by default creates an app.ts file, and a default.htm – and add the following:

\app directory (for application files)
\app\classes (for our AMD classes)
\lib directory (for external libraries)
\modules (for our module definitions)
\app\AppMain.ts
\app\AppConfig.ts
\app\classes\Greeter.ts
download require.js and include it in the \lib directory.
\modules\require.d.ts

\modules\Require.d.ts

Add the following module definition to \modules\require.d.ts

declare module require {
    export function (requires: string[], f: Function);
    export function (requires: string);
    export function config(require: any);
};

\app\classes\Greeter.ts as an AMD module

Cut the code defining the Greeter class from \app.ts into the \app\classes\Greeter.ts file:

Effectively, we are now starting to organise our project, with one .ts file for each class.

app\classes\Greeter.ts:

class Greeter {
    element: HTMLElement;
    span: HTMLElement;
    timerToken: number;

    constructor (element: HTMLElement) { 
        this.element = element;
        this.element.innerText += "The time is: ";
        this.span = document.createElement('span');
        this.element.appendChild(this.span);
        this.span.innerText = new Date().toUTCString();
    }

    start() {
        this.timerToken = setInterval(() => this.span.innerText = new Date().toUTCString(), 500);
    }

    stop() {
        clearTimeout(this.timerToken);
    }

}

Compiling the project now should show the error: The name ‘Greeter’ does not exist in the current scope.

Let’s fix this first by using a CommonJS reference – add a reference path to app.ts:

app.ts

/// <reference path="app/classes/Greeter.ts" />

window.onload = () => {
    var el = document.getElementById('content');
    var greeter = new Greeter(el);
    greeter.start();
};

The project should now compile.

If you run the project now, (using Internet Explorer), the Greeter.js file will be unreferenced:

0x800a1391 – JavaScript runtime error: ‘Greeter’ is undefined

The simple solution is to include this new Greeter.js file in default.htm:

default.htm

<head>
    <meta charset="utf-8" />
    <title>TypeScript HTML App</title>
    <link rel="stylesheet" href="app.css" type="text/css" />
    <script type="text/javascript" src="app/classes/Greeter.js"></script>
    <script src="app.js"></script>
</head>

Converting Greeter.ts to an AMD module

Lets now convert Greeter.ts to an AMD module. To compile project files to AMD modules, unload your project file, edit it, and add the –module AMD option to the command line options:

Update

: Here is the 0.8.1 version of the project file:

Note that you will need to remove the –sourcmap option for Debug configuration, as sourcemap and AMD do not work well together.

  <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <!--remove the --sourcemap option below-->
    <TypeScriptSourceMap></TypeScriptSourceMap>
  </PropertyGroup>
  <Target Name="BeforeBuild">
    <Message Text="Compiling TypeScript files" />
    <Message Text="Executing tsc$(TypeScriptSourceMap) @(TypeScriptCompile ->'&quot;%(fullpath)&quot;', ' ')" />
    <Exec Command="tsc$(TypeScriptSourceMap) --module AMD @(TypeScriptCompile ->'&quot;%(fullpath)&quot;', ' ')" />
  </Target>

Older version 0.8.0 compiler version:

  <Target Name="BeforeBuild">
    <Exec Command="&quot;$(PROGRAMFILES)\Microsoft SDKs\TypeScript.8.0.0\tsc&quot; --module AMD @(TypeScriptCompile ->'&quot;%(fullpath)&quot;', ' ')" />
  </Target>

Export Greeter

Now modify the Greeter class definition, and add the export keyword:

app/classes/Greeter.ts

export class Greeter {

and modify the app.ts file to import the the module:

app.ts

import gt = module("app/classes/Greeter");

window.onload = () => {
    var el = document.getElementById('content');
    var greeter = new gt.Greeter(el);
    greeter.start();
};

Running the app at this stage now will produce the following error:

Unhandled exception at line 1, column 1 in http://localhost:8524/app.js

0x800a138f – JavaScript runtime error: The value of the property ‘define’ is null or undefined, not a Function object

Configuring require.js

In order to use AMD modules, we need to tell our page to include require.js. Looking at the require.js documentation, the way to do this is to include the following in your html page:

default.htm

<script data-main="app/AppConfig" type="text/javascript" src="lib/require.js"></script>

Note that the require.js syntax is to use the data-main property to specify a JavaScript file to load as the initial starting point for the application – in this case : app/AppConfig.js.

AppConfig.ts

Create an app/AppConfig.ts TypeScript file, as follows:

app/AppConfig.ts

/// <reference path="../modules/require.d.ts" />

import gt = module("classes/Greeter");

require([], () => {
    // code from window.onload
    var el = document.getElementById('content');
    var greeter = new gt.Greeter(el);
    greeter.start();
});

Note that we have moved the application startup code (the window.onload function) into the body of the require function.

The app should now run using AMD loading.

Adding further modules

Should your application require further AMD modules, simply include them in the /lib directory, and specify them in the first array as follows:

app/AppConfig.ts

require(['../lib/jquery-1.7.2','../lib/underscore', '../lib/backbone', '../lib/console'], () => {
    // code from window.onload
    var el = document.getElementById('content');
    var greeter = new gt.Greeter(el);
    greeter.start();
});

Note that the paths for require are relevant to the AppConfig.ts file (which is in the app directory).

Using require.config

require.js has a number of configuration options that make it so powerful. Among these is the ability to define dependencies between modules.

Unfortunately, including a require.config in our app/AppConfig.ts file as shown below will result in a run-time error:

0x800a01b6 – JavaScript runtime error: Object doesn’t support property or method ‘config’

app/AppConfig.ts

/// <reference path="../modules/require.d.ts" />

// the config below will cause a run-time error
require.config({
    baseUrl: '../'
});

import gt = module("classes/Greeter");

require(['../lib/jquery-1.7.2','../lib/underscore', '../lib/backbone', '../lib/console'], () => {
    // code from window.onload
    var el = document.getElementById('content');
    var greeter = new gt.Greeter(el);
    greeter.start();
});

This run-time error is caused because the TypeScript compiler ( with –module AMD ) compile option wraps the entire file in a require statement:

app/AppConfig.js (generated)

define(["require", "exports", "classes/Greeter"], function (require, exports, __gt__) {
    // this require.config below should NOT be inside the define function
    require.config({
        baseUrl: '../'
    });
    var gt = __gt__;

    require([
        '../lib/jquery-1.7.2', 
        '../lib/underscore', 
        '../lib/backbone', 
        '../lib/console'
    ], function () {
        var el = document.getElementById('content');
        var greeter = new gt.Greeter(el);
        greeter.start();
    });
})

Using require.config with AMD modules solution:

The solution here is to separate our require config file from our application main file, and remove any import module statements from the configuration file as follows:

AppMain.ts

Create an AppMain.ts file within the app folder as follows:

app/AppMain.ts

import gt = module("classes/Greeter");

export class AppMain {
    public run() {
        var el = document.getElementById('content');
        var greeter = new gt.Greeter(el);
        greeter.start();

    }
}

Modify AppConfig.ts to use named require parameters

app/AppConfig.ts

/// <reference path="../modules/require.d.ts" />
/// <reference path="AppMain.ts" />
require.config({
    //baseUrl: '../' // commented for now
});

require(['AppMain', 
    '../lib/jquery-1.7.2','../lib/underscore', '../lib/backbone', '../lib/console' ], 
    (main) => {
    // code from window.onload
    var appMain = new main.AppMain();
    appMain.run();
});

Note that we have specified to require.js that it must load a file named ‘AppMain’ ( our AppMain.ts compiled file), and that when the require function runs, AppMain’s classes will be referenced by the named parameter main. If we were to name all of the parameters in the require array, our code would look something like this:

app/AppConfig.ts

require(['AppMain', 
    '../lib/jquery-1.7.2','../lib/underscore', '../lib/backbone', '../lib/console' ], 
    (main, $, _, console) => {
    var appMain = new main.AppMain();
    appMain.run();
});

Using named require parameters and shims

Fortunately, require.js allows us to configure named parameters via the paths config variable, and then define a shim property for each named path, that includes the export symbol, and any dependencies, as follows:

app/AppConfig.ts

require.config({
    baseUrl: '../',
    paths: {
        'jquery': 'lib/jquery-1.7.2',
        'underscore': 'lib/underscore',
        'backbone': 'lib/backbone',
        'console': 'lib/console'
    }, 
    shim: {
        jquery: {
            exports: '$'
        },
        underscore: {
            exports: '_'
        },
        backbone: {
            deps: ["underscore", "jquery"],
            exports: "Backbone"
        },
        console: {
            exports: "console"
        }
    }
});

require([
     'jquery'
    , 'underscore'
    , 'backbone'
    , 'console'
    ], 
    ($, _, Backbone, console) => {
    $(() => {

        // code goes here

    });
});

Have fun,

- Blorkfish.

About these ads

Filed under TypeScript

21 Responses to TypeScript: Organizing your code with AMD modules and require.js

Luís Furtado says:

October 25, 2012 at 12:18 am

Great article man! It helps me a lot!

Reply
- blorkfish says:
  
  October 25, 2012 at 12:17 pm
  
  Thanks, mate. Much appreciated.
  
  Reply
JcFx says:

October 25, 2012 at 9:26 am

Good stuff. Really useful.

Reply
- blorkfish says:
  
  October 25, 2012 at 12:18 pm
  
  Thanks mate. Glad you found the post useful.
  
  Reply
Pingback: TypeScript: Organizing your code with AMD modules and require.js | coolmuse
CCPony says:

November 9, 2012 at 1:41 am

Great post. Question: how would you use TypeScript to name the resultant module? – - for example:

define (“NamedModule”, ["require", "export"], function (require, export) {..}

Thanks Blork – - CCPony

Reply
joeriks says:

December 7, 2012 at 9:46 am

Great post, thanks for sharing. A question: did you try to put the RequireJS optimizer into this, or some other bundle&minifier?

Reply
- blorkfish says:
  
  December 7, 2012 at 12:41 pm
  
  Hey joeriks, no not yet. Have you tried ?
  
  Reply
Jed Hunsaker says:

December 9, 2012 at 8:30 pm

Hmm… the only problem I have with this is once you enter the “// code goes here” block, you’ve lost all of the Intellisense you would get from a /// at the top.

Reply
- Jed Hunsaker says:
  
  December 9, 2012 at 8:31 pm
  
  The comment system cut out my HTML tag above, but I’m trying to say if you reference jquery.d.ts at the top, you overwrite it with the $ down below, losing all Intellisense (code hints) in Visual Studio.
  
  Reply
- Jed Hunsaker says:
  
  December 9, 2012 at 9:04 pm
  
  Aha! OK – put the reference path=”../modules/jquery.d.ts” up at the top and then down below, replace the $ sign with $:JQueryStatic. Then you get all the Intellisense! Yay!
  
  Reply
Robin says:

December 12, 2012 at 7:29 pm

I was getting along well with this until the Configuring RequireJS section. Now I get an error saying “Module name “classes/Greeter” has not been loaded yet for context: _. Use require([])”

I downloaded the full source solution and get something similar:
“Module name “app/classes/Greeter” has not been loaded yet for context: _”

Any ideas? I’d really appreciate any suggestions.

Reply
- blorkfish says:
  
  December 14, 2012 at 1:25 am
  
  Hi Robyn,
  I was able to reproduce your problem – and it seems that it has to do with the newest version of the TypeScript compiler (0.8.1 and up). I have updated this blog, and also included a 0.8.1 version of the sample app.
  In essence, it was caused by not having the –module AMD compiler flag. Have a look a the modifications to the project file for the correct syntax. Also, it seems that sourcemaps are not working with AMD modules, so you will need to remove this flag from the compile options.
  Have fun,
  Blorkfish
  
  Reply
Pingback: Modularization in TypeScript « Keyhole Software
Pingback: Modularization in TypeScript | Brett Jones, Dev.
Brett Jones says:

January 14, 2013 at 11:39 pm

Hey all,

I’ve been looking into this whole TypeScript/JS AMD stuff and wrote a blog post on the subject. I found a fairly convenient way to do what you’re doing here, only without introducing the AMD/requireJS syntax into your TypeScript code, which I think is definitely a plus.

I’d love to hear your thoughts – check it out at http://brettjonesdev.com/modularization-in-typescript/

Brett Jones – @brettjonesdev

Reply
Luke Ryan says:

January 22, 2013 at 5:24 am

Great post.. really helpful!

Reply
- blorkfish says:
  
  January 23, 2013 at 12:42 pm
  
  Hey Luke,
  Thanks, mate. Glad you found it helpful.
  
  Reply
naing ye lin thein (@n41ng) says:

February 1, 2013 at 12:20 am

Thnx, Just picked up TS a few days ago and this is the first real helpful documentation on TypeScript and implementing AMD that I have come across so far. Now I am off to go and read that Ioc for typescript article…

Reply
deadcabbit says:

April 1, 2013 at 10:39 am

Setting up r.js building is not a big deal, but with no conditional compilation in the htm file generating a production html and a dev html ends up pretty messy in my opinion (I’m not a .net developer so there may be better ways; I would use an afterBuild script possibly run via node). Using require.js without building is pointless (at least outside development).

What I don’t like in the above code is that we’re still using named functions (Greeter in this case), a returnable anonymous “class” would not work, though that would be the “AMD way” (export class {…) – of course one may use something like “export class Klass”, but probably there’s a better way, I’m just not familiar enough with ts.

Reply
Arek Bal says:

May 4, 2013 at 6:41 pm

Guys, you are not “required” to use require.d.ts. Script ‘require.js’ is enough
calling require with callback in *.ts makes u lose type information anyway.

Proper way of doing it are module declarations like that one:
import blogger = module(‘Blogger’)

which during generation encloses rest of code in proper define() block.

Keep in mind that:
1. Module load statement above can use a .ts filename where ‘Blogger’ is because ts files without module block inside are modules(like in python). But… check a line below…
2. In order to have AMDable module you should not enclose your code in non-exportable module at top-level.

Reply

_blorkfish_blog_

TypeScript: Organizing your code with AMD modules and require.js

Update

Creating a default project using CommonJS

\modules\Require.d.ts

\app\classes\Greeter.ts as an AMD module

app\classes\Greeter.ts:

app.ts

default.htm

Converting Greeter.ts to an AMD module

Update

Export Greeter

app/classes/Greeter.ts

app.ts

Configuring require.js

default.htm

AppConfig.ts

app/AppConfig.ts

Adding further modules

app/AppConfig.ts

Using require.config

app/AppConfig.ts

app/AppConfig.js (generated)

Using require.config with AMD modules solution:

AppMain.ts

app/AppMain.ts

Modify AppConfig.ts to use named require parameters

app/AppConfig.ts

app/AppConfig.ts

Using named require parameters and shims

app/AppConfig.ts

21 Responses to TypeScript: Organizing your code with AMD modules and require.js

Leave a Reply Cancel reply

Recent Posts

Archives

Categories

Meta

Follow “_blorkfish_blog_”

_blorkfish_blog_

TypeScript: Organizing your code with AMD modules and require.js

Update

Creating a default project using CommonJS

\modules\Require.d.ts

\app\classes\Greeter.ts as an AMD module

app\classes\Greeter.ts:

app.ts

default.htm

Converting Greeter.ts to an AMD module

Update

Export Greeter

app/classes/Greeter.ts

app.ts

Configuring require.js

default.htm

AppConfig.ts

app/AppConfig.ts

Adding further modules

app/AppConfig.ts

Using require.config

app/AppConfig.ts

app/AppConfig.js (generated)

Using require.config with AMD modules solution:

AppMain.ts

app/AppMain.ts

Modify AppConfig.ts to use named require parameters

app/AppConfig.ts

app/AppConfig.ts

Using named require parameters and shims

app/AppConfig.ts

Share this:

Like this:

21 Responses to TypeScript: Organizing your code with AMD modules and require.js

Leave a Reply Cancel reply

Recent Posts

Archives

Categories

Meta

Follow “_blorkfish_blog_”