Use TypeScript in your Ember 2.x apps!

Just run:

ember install ember-cli-typescript@1

All dependencies will be added to your package.json, and you're ready to roll! (If you're upgrading from a previous release, you should check to merge any tweaks you've made to tsconfig.json.

In addition to ember-cli-typescript, the following are installed:

• Packages:
  • typescript (2.4 or greater)
  • @types/ember
  • @types/rsvp
  • @types/ember-testing-helpers
• Files:
  • tsconfig.json

If you make changes to the paths included in your tsconfig.json, you will need to restart the server to take the changes into account. Additionally, depending on what you're doing, you may notice that your tweaks to tsconfig.json aren't applied exactly as you might expect.

The configuration file is used by both Ember CLI (via broccoli) and for tool integration in editors.

Broccoli controls the inputs and the output folder of the various build steps that make the Ember build pipeline. Its expectation are impacted by TypeScript configuration properties like "include", "exclude", "outFile", "outDir".

We want to allow you to change unrelated properties in the tsconfig file.

This addon takes the following approach to allow this dual use:

• We generate a good default blueprint, which will give you type resolution in your editor for normal Ember.js paths. The generated tsconfig file does not set "outDir" and sets "noEmit" to true. This allows you to run editors which use the compiler without creating .js files throughout your codebase.

• Then, before calling broccoli, the addon:

  • removes any configured outDir to avoid name resolution problems in the broccoli tree processing
  • sets the noEmit option to false so that the compiler will emit files for consumption by your app
  • sets allowJs to false, so that the TypeScript compiler does not try to process JavaScript files imported by TypeScript files in your app
  • removes all values set for include, since we use Broccoli to manage the build pipeline directly.

You can still customize the tsconfig.json file further for your use case. For example, to see the output of the compilation in a separate folder you are welcome to set "outDir" to some path and set "noEmit" to false. Then tools which use the TypeScript compiler will generate files at that location, while the broccoli pipeline will continue to use its own temp folder.

Please see the wiki for additional how to tips from other users or to add your own tips. If an use case is frequent enough we can codify in the plugin.

If you are porting an existing app to TypeScript, you can install this addon and migrate your files incrementally by changing their extensions from .js to .ts. A good approach is to start at your leaf files and then work your way up. As TypeScript starts to find errors, make sure to celebrate your (small) wins with your team, specially if some people are not convinced yet. We would also love to hear your stories!

You may also find the blog series "Typing Your Ember" helpful as it walks you through not only how to install but how to most effectively use TypeScript in an Ember app today, and gives some important info on the background and roadmap for the project.

⚠️ Warning: this is not currently recommended. This is a WIP part of the add-on, and it will make a dramatic difference in the size of your add-on in terms of installation. The upcoming 1.1 release will enable a much better experience for consumers of your addon.

We're working on making a solution that lets us ship generated typings and compiled JavaScript instead of shipping the entire TypeScript compiler toolchain for add-ons. If you're using ember-cli-typescript in an add-on, you might add a note to your users about the install size until we get that sorted out!

If you want to experiment with this in the meantime, you can do so, but please give users fair warning about the increased size. To enable TypeScript for your addon, simple move ember-cli-typescript from devDependencies to dependencies in your package.json.

Note: the new modules API is not yet supported by the official typings (which are distinct from this addon, though we install them). We hope to have support for them shortly!

While TS already works nicely for many things in Ember, there are a number of corners where it won't help you out. Some of them are just a matter of further work on updating the existing typings; others are a matter of further support landing in TypeScript itself.

We are hard at work (and would welcome your help!) writing new typings for Ember which can give correct types for Ember's custom object model. If you'd like to try those out, please see instructions in that repo!

Here is the short list of things which do not work yet in the version of the typings published on DefinitelyTyped.

You'll frequently see errors for imports which TypeScript doesn't know how to resolve. For example, if you use htmlbars-inline-precompile:

import hbs from 'htmlbars-inline-precompile';

You'll see an error, because there aren't yet type definitions for it. You may see the same with some addons as well. These won't stop the build from working; they just mean TypeScript doesn't know where to find those.

Writing these missing type definitions is a great way to pitch in! Jump in #topic-typescript on the Ember Slack and we'll be happy to help you.

You'll see quite a few errors like this when calling .extends() on an existing Ember type:

Class 'FooController' incorrectly extends base class 'Controller'. Type '{ bar(): void; }' has no properties in common with type 'ActionHash'

This is a symptom of the current, out-of-date types. The new typings we're working on will solve these.

In the meantime, note that your application will still build just fine even with these errors... they'll just be annoying.

TypeScript won't detect a mismatch between this action and the corresponding call in the template:

Ember.Component.extend({
  actions: {
     turnWheel(degrees: number) {
        // ...
     }
  },
})

<button onclick={{action 'turnWheel' 'NOT-A-NUMBER'}}> Click Me </button>

Likewise, it won't notice a problem when you use the send method:

// TypeScript compiler won't detect this type mismatch
this.send('turnWheel', 'ALSO-NOT-A-NUMBER');

When you use Ember.get or Ember.set, TypeScript won't yet warn you that you're using the wrong type. So in foo() here, this will compile but be wrong at runtime:

Ember.Object.extend({
  urls: <string[]> null,
  port: 4200,  // number

  init() {
     this._super(...arguments);
     this.set('urls', []);
  },

  foo() {
    // TypeScript won't detect these type mismatches
    this.get('urls').addObject(51);
    this.set('port', '3000');
  },
});

By default the typescript compiler loads up any type definitions found in node_modules/@types. If the type defs you need are not found here you can register a custom value in paths in the tsconfig.json file. For example, for the Redux types, you can add a "redux" key:

{
  "compilerOptions": {
    "paths": {
      "my-app-name/*": ["app/*"],
      "redux": ["node_modules/redux/index.d.ts"]
    }
  }
}