JavaScript TypeScript Other
Clone or download
Latest commit f0ebdf5 Aug 7, 2018
Permalink
Failed to load latest commit information.
.github/ISSUE_TEMPLATES Fixes from @chriskrycho review Jul 6, 2018
.vscode Make sure VS Code doesn't explode for *any* ember-try scenario. Feb 11, 2018
blueprints fix: cleanup Jul 26, 2018
config Update build matrix to cover TS + Ember CLI versions May 15, 2018
lib Merge branch 'master' into addon-test-support Jul 26, 2018
node-tests fix: cleanup Jul 26, 2018
tests fix: build test Jul 26, 2018
vendor Initial Commit from Ember CLI v2.10.0 Dec 3, 2016
.bowerrc Initial Commit from Ember CLI v2.10.0 Dec 3, 2016
.editorconfig Initial Commit from Ember CLI v2.10.0 Dec 3, 2016
.ember-cli Initial Commit from Ember CLI v2.10.0 Dec 3, 2016
.eslintignore Upgrade ember-cli and friends May 15, 2018
.eslintrc.js Merge branch 'master' into node-acceptance-tests May 24, 2018
.gitignore Upgrade Ember from 2.13.3 to 2.17.1. Dec 17, 2017
.jshintrc Initial Commit from Ember CLI v2.10.0 Dec 3, 2016
.npmignore Upgrade Ember from 2.13.3 to 2.17.1. Dec 17, 2017
.travis.yml Allow failures in beta scenarios Jun 6, 2018
.watchmanconfig Initial Commit from Ember CLI v2.10.0 Dec 3, 2016
CHANGELOG.md v1.4.0 Aug 7, 2018
CODE_OF_CONDUCT.md Add CODE_OF_CONDUCT.md Feb 12, 2018
LICENSE.md Initial Commit from Ember CLI v2.10.0 Dec 3, 2016
README.md Merge branch 'master' into @ember-test-helpers Jul 25, 2018
appveyor.yml Update build matrix to cover TS + Ember CLI versions May 15, 2018
debug.sh Copied over from ember-cli-typify Dec 4, 2016
ember-cli-build.js Ensure ember-try directories are propertly excluded from watching Apr 15, 2018
index.js fix: cleanup Jul 26, 2018
is_md_only.sh Skip everything if only .md files have changed Feb 24, 2018
known-typings.md Add ember-test-friendly-error-handler to known-typings.md Apr 2, 2018
package.json v1.4.0 Aug 7, 2018
testem.js Upgrade dependencies and enforce node 4 support Feb 8, 2018
tsconfig.json fix: build test Jul 26, 2018
yarn.lock Merge branch 'master' into node-acceptance-tests May 24, 2018

README.md

ember-cli-typescript

Use TypeScript in your Ember 2.x and 3.x apps!

*nix build status (master) Windows build status Ember Observer Score

Getting Help

When seeking help, you should first consider what you need, and which aspect of the Ember+TypeScript ecosystem your issue pertains to.

💬 Getting Started

We have an Ember Community Slack channel #-topic-typescript where you can ask about getting started, good resources for self-directed learning and more.

📚 Issues With Ember Type Definitions

If you've found that some of the Ember type information is missing things, or is incorrect in some way, please first ensure you're using the latest version of the packages this addon installs. Although StackOverflow and Discuss are not the advised places to report problems, you may find an answer there.

If you still see a problem, please create a bug report here or a feature request here.

⚙️ Issues With Adding TypeScript Support To Apps and Addons

If you run into a problem with the way TypeScript is compiled in Ember apps (i.e., a broccoli error message, incorrect build output, etc...), please first check StackOverflow and Discuss, as you may find an answer.

If you still need help, please open an bug report here or a feature request here

Issues With Static Analysis of TypeScript In Ember Apps and Addons

The TypeScript compiler does some very basic static analysis of your code, and most developers use Palantir's TSLint tool for more thorough checking.

One sure way to tell which tool is generating an error message is that Linters like TSLint and ESLint will always mention their name, and the name of the pertinent rule, when it alerts you to a violation.

Example:
[tslint] variable name must be in lowerCamelCase, PascalCase or UPPER_CASE (variable-name)

variable-name is the name of the rule.

For issues relating to typescript compiler analysis, create an issue in this repository by clicking here. For TSLint-related concerns, please create an issue in the ember-cli-tslint project by clicking here. If you run into issues with using ESLint with Ember, create an issue here.

Setup and Configuration

To install or upgrade the addon, just run:

ember install ember-cli-typescript@latest

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, we make the following changes to your project:

Other Packages This Addon Installs

Files this addon Generates

  • We add the following files to your project:

    • tsconfig.json
    • types/<app name>/index.d.ts – the location for any global type declarations you need to write for you own application; see Global types for your package for information on its default contents and how to use it effectively
    • app/config/environment.d.ts – a basic set of types defined for the contents of the config/environment.js file in your app; see Environment and configuration typings for details

Ember support

ember-cli-typescript runs its test suite against the 2.12 LTS, the 2.16 LTS, the 2.18 LTS, the current release, the beta branch, and the canary branch. It's also in active use in several large applications. Any breakage for upcoming releases should be detected and fixed ahead of those releases, but you can help us guarantee that by running your own Ember.js+TypeScript app with beta and canary turned on and let us know if you run into issues with upcoming Ember.js releases.

tsconfig.json

We generate a good default tsconfig.json, which will usually make everything Just Work™. In general, you may customize your TypeScript build process as usual using the tsconfig.json file.

However, there are a few things worth noting if you're already familiar with TypeScript and looking to make further or more advanced customizations (i.e. most users can just ignore this section!):

  1. The generated tsconfig file does not set "outDir" and sets "noEmit" to true. Under the hood, Ember's own invocation of tsc does set these, but the default configuration we generate allows you to run editors which use the compiler without creating extraneous .js files throughout your codebase, leaving the compilation to ember-cli-typescript to manage.

    You can still customize those properties in tsconfig.json if your use case requires it, however. 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 (e.g. the watcher tooling in JetBrains IDEs) will generate files at that location, while the Ember.js/Broccoli pipeline will continue to use its own temp folder.

  2. Closely related to the previous point: any changes you do make to outDir won't have any effect on how Ember builds your application—we have to pipe everything into Ember CLI via broccoli, so we override that. In general, everything else works just as you'd expect, though!

  3. By default, we target the highest stable version of JavaScript available in the TypeScript compiler, so that you may ship anything from that very code without further modification to browsers that support it all the way back to ES3, in line with the Babel configuration in your app's config/targets.js. You can set this target to whatever is appropriate for your application, but we strongly encourage you to leave it set to the highest stable version of JavaScript if you are developing an addon, so that consumers of your addon have full flexibility in this regard.

  4. If you make changes to the paths included in or excluded from the build via your tsconfig.json (using the "include", "exclude", or "files" keys), you will need to restart the server to take the changes into account: ember-cli-typescript does not currently watch the tsconfig.json file.

Sourcemaps

To enable TypeScript sourcemaps, you'll need to add the corresponding configuration for Babel to your ember-cli-build.js file:

const app = new EmberApp(defaults, {
  babel: {
    sourceMaps: 'inline',
  },
});

(Note that this will noticeably slow down your app rebuilds.)

If you're updating from an older version of the addon, you may also need to update your tsconfig.json. (Current versions generate the correct config at installation.) Either run ember generate ember-cli-typescript or verify you have the same sourcemap settings in your tscsonfig.json that appear in the blueprint.

Using TypeScript with Ember effectively

In addition to the points made below, you may find the Typing Your Ember blog series (especially the "Update" sequence) particularly helpful in knowing how to do specific things.

Incremental adoption

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. As TypeScript starts to find errors (and it usually does!), make sure to celebrate your wins – even if they're small! – with your team, especially if some people are not convinced yet. We would also love to hear your stories!

Some specific tips for success on the technical front:

  • Use the strictest strictness settings that our typings allow. While it may be tempting to start with the loosest strictness settings and then to tighten them down as you go, this will actually mean that "getting your app type-checking" will become a repeated process – getting it type-checking with every new strictness setting you enable! – rather than something you do just once. The only strictness setting you should turn off is strictFunctionTypes, which our current type definitions do not support. The recommended strictness settings in your "compilerOptions" hash:

    "noImplicitAny": true,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "strictNullChecks": true,
    "strictPropertyInitialization": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    
  • Make liberal use of any for things you don't have types for as you go, and come back and fill them in later. This will let you do the strictest strictness settings but with an escape hatch that lets you say "We will come back to this when we have more idea how to handle it."

  • A good approach is to start at your "leaf" files (the ones that don't import anything else from your app, only Ember types) and then work your way back inward toward the most core types that are used everywhere. Often the highest-value modules are your Ember Data models and any core services that are used everywhere else in the app – and those are also the ones that tend to have the most cascading effects (having to update tons of other places in your app) when you type them later in the process.

  • Set "noEmitOnError": true in the "compilerOptions" hash in your tsconfig.json – it will help a lot if you can be sure that for the parts of your app you have added types to are still correct. And you'll get nice feedback immediately when you have type errors that way!

    type errors in your build!

You may 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.

Install other types!

You'll want to use other type definitions as much as possible. The first thing you should do, for example, is install the types for your testing framework of choice: @types/ember-mocha or @types/ember-qunit. Beyond that, look for types from other addons: it will mean writing any a lot less and getting a lot more help both from your editor and from the compiler.

To make this easier, we're maintaining a list of addons with known type definitions either on Definitely Typed or as part of the addon itself. (If you know of typings that aren't in that list, please open a pull request to add them!)

The types directory

During installation, we create a types directory in the root of your application and add a "paths" mapping that includes that directory in any type lookups TypeScript tries to do. This is convenient for a few things:

  • global types for your package (see the next section)
  • writing types for third-party/vendor packages which do not have any types
  • developing types for an addon which you intend to upstream later

These are all fallbacks, of course, you should use the types supplied directly with a package

Global types for your package

At the root of your application or addon, we include a types/<your app> directory with an index.d.ts file in it. Anything which is part of your application but which must be declared globally can go in this file. For example, if you have data attached to the Window object when the page is loaded (for bootstrapping or whatever other reason), this is a good place to declare it.

In the case of applications (but not for addons), we also automatically include declarations for Ember's prototype extensions in this index.d.ts file, with the Array prototype extensions enabled and the Function prototype extensions commented out. You should configure them to match your own config (which we cannot check during installation). If you are disabling Ember's prototype extensions, you can remove these declarations entirely; we include them because they're enabled in most Ember applications today.

Environment configuration typings

Along with the @types/ files mentioned above, ember-cli-typescript adds a starter interface for config/environment.js in app/config/environment.d.ts. This interface will likely require some changes to match your app.

We install this file because the actual config/environment.js is (a) not actually identical with the types as you inherit them in the content of an application, but rather a superset of what an application has access to, and (b) not in a the same location as the path at which you look it up. The actual config/environment.js file executes in Node during the build, and Ember CLI writes its result as <my-app>/config/environment into your build for consumption at runtime.

String-keyed lookups

Ember makes heavy use of string-based APIs to allow for a high degree of dynamicism. With some limitations, you can nonetheless use TypeScript very effectively to get auto-complete/IntelliSense as well as to accurately type-check your applications.

The "Update" sequence in the Typing Your Ember has detailed explanations and guides for getting good type-safety for Ember's string-based APIs, e.g. the use of get and set, service and controller injection, Ember Data models and lookups

  • Part 1: A look at normal Ember objects, "arguments" to components (and controllers), and service (or controller) injections.
  • Part 2: Class properties — some notes on how things differ from the Ember.Object world.
  • Part 3: Computed properties, actions, mixins, and class methods.
  • Part 4: Using Ember Data, and service and controller injections improvements. (This includes a detailed guide to updating making the service and controller injections and Ember Data lookups behave as described below.)

A few of the most common speed-bumps are listed here to help make this easier:

this type workaround

One important note for using class types effectively with today's Ember typings: you will (at least for now) need to explicitly write out a this type for methods, computed property callbacks, and actions if you are going to use get or set

import Component from '@ember/component';

export default class UserProfile extends Component {
  changeUsername(this: UserProfile, userName: string) {
    //           ^---------------^
    // `this` tells TS to use `UserProfile` for `get` and `set` lookups
  }
}

This is a workaround for how incredibly dynamic Ember.Object instances are and hopefully will improve over time as we continue to iterate on the type definitions. Again, see the relevant blog post for details.

Nested keys in get or set

In general, this.get and this.set will work as you'd expect if you're doing lookups only a single layer deep. Things like this.get('a.b.c') don't (and can't ever!) type-check; see the blog posts for a more detailed discussion of why.

The workaround is simply to do one of two things:

  1. The type-safe approach. This will typecheck, but is both ugly and only works *if there are no nulls or undefineds along the way. If nested is null at runtime, this will crash!

    import { get } from '@ember/object';
    
    // -- Type-safe but ugly --//
    get(get(get(someObject, 'deeply'), 'nested'), 'key');
  2. Using // @ts-ignore. This will not do any type-checking, but is useful for the cases where you are intentionally checking a path which may be null or undefined anywhere long it.

    // @ts-ignore
    get(someObject, 'deeply.nested.key');

    It's usually best to include an explanation of why you're ignoring a lookup!

Service and controller injections

Ember does service and controller lookups with the inject functions at runtime, using the name of the service or controller being injected up as the default value—a clever bit of metaprogramming that makes for a nice developer experience. TypeScript cannot do this, because the name of the service or controller to inject isn't available at compile time in the same way.

This means that if you do things the normal Ember way, you will have to specify the type of your service or controller explicitly everywhere you use it. But… where should we put that? If we try to set it up as a class property, we'll get an error as of Ember 3.1 (and it only accidentally works before that): computed properties and injections must be installed on the prototype.

There are two basic approaches we can take. The first uses the .extend method in conjunction with class definitions to make sure the injections are set up correctly; the second leans on the still-experimental Ember Decorators project to let us do everything in the class body while still getting the niceties of ES6 classes. The decorators approach is much nicer, and likely to eventually become the standard across Ember in general assuming the decorators spec stabilizes. For today, however, it's an opt-in rather than the default because it remains an experimental extension to the JavaScript standard.

Using .extend

The officially supported method for injections uses a combination of class body and traditional EmberObject.extend functionality. We generate a service like normal by running ember generate service my-session. The resulting definition will look like this:

// my-app/services/my-session.ts
import Service from '@ember/service';
import RSVP from 'rsvp';

export default class MySession extends Service {
  login(email: string, password: string): RSVP.Promise<string> {
    // login and return the confirmation message
  }
}

declare module '@ember/service' {
  interface Registry {
    'my-session': MySession;
  }
}

You'll need to add that module and interface declaration to all your existing service and controller declarations for this to work (again, see the blog post for further details), but once you do that, you'll have this much nicer experience throughout! It's not quite vanilla Ember.js, but it's close—and this way, you still get all those type-checking and auto-completion benefits, but with a lot less noise! Moreover, you actually get a significant benefit over "vanilla" Ember: we type-check that you typed the key correctly in the service invocation.

Then we can use the service as usual:

// my-app/components/user-profile.ts
import Component from '@ember/component';
import { inject as service } from '@ember/service';

export default class UserProfile extends Component.extend({
  mySession: service('my-session'),
}) {
  login(email: string, password: string) {
    this.session.login(email, password);
  }
}

Notice that the type of mySession will be the MySession type here: TypeScript is using the "registry" set up in the last lines of the my-session module to look up the type by its name. If we had written just service() instead, Ember would have resolved the correct type at runtime as usual, but TypeScript would not be able to tell which service we had, only that it was a Service. In that case, the this.session would not have a login property from TS's perspective, and this would fail to type-check. That extra string gives TS the information it needs to resolve the type and give us auto-completion, type-checking, etc.

(In Ember 3.0 or earlier, we would have this.get('session').login(email, password); instead.)

Although this may look a little strange, everything works correctly. We can use other ES6 class functionality and behaviors (including class properties) as normal; it is just the special Ember pieces which have to be set up on the prototype like this: injections, computed properties, and the actions hash.

Using decorators

The alternative here is to use Ember Decorators. In that case, we'd have precisely the same definition for our MySession service, but a much cleaner implementation in the component class:

// my-app/components/user-profile.ts
import Component from '@ember/component';
import { service } from '@ember-decorators/service';
import MySession from 'my-app/services/my-session';

export default class UserProfile extends Component {
  @service mySession!: MySession;

  login(this: UserProfile, email: string, password: string) {
    this.session.login(email, password);
  }
}

Note that we need the MySession type annotation this way, but we don't need the string lookup (unless we're giving the service a different name than the usual on the class, as in Ember injections in general). Without the type annotation, the type of session would just be any. This is because decorators (as of TS 2.8 – 3.0) are not allowed to modify the types of whatever they decorate. As a result, we wouldn't get any type-checking on that session.login call, and we wouldn't get any auto-completion either. Which would be really sad and take away a lot of the reason we're using TypeScript in the first place!

Also use the ! non-null assertion operator to prevent TS2564, that is caused by enabling strictPropertyInitialization in tsconfig.json.

If you're on an Ember version below 3.1, you'll want to wrap your service type in ComputedProperty, because native ES5 getters are not available there, which means that instead of accessing the service via this.mySession, you would have to access it as this.get('mySession') or get(this, 'mySession'). This means the above code would rather look like:

// my-app/components/user-profile.ts
import Component from '@ember/component';
import { get } from '@ember/object';
import ComputedProperty from '@ember/object/computed';
import { service } from '@ember-decorators/service';
import MySession from 'my-app/services/my-session';

export default class UserProfile extends Component {
  @service mySession!: ComputedProperty<MySession>;

  login(this: UserProfile, email: string, password: string) {
    get(this, 'session').login(email, password);
  }
}

This also holds true for all other macros of the ember-decorators addon.

Ember Data lookups

We use the same basic approach for Ember Data type lookups with string keys as we do for service or controller injections. As a result, once you add the module and interface definitions for each model, serializer, and adapter in your app, you will automatically get type-checking and autocompletion and the correct return types for functions like findRecord, queryRecord, adapterFor, serializerFor, etc. No need to try to write out those (admittedly kind of hairy!) types; just write your Ember Data calls like normal and everything should just work.

The declarations and changes you need to add to your existing files are:

  • Models

    import DS from 'ember-data';
    
    export default class UserMeta extends DS.Model.extend({
      // attribute declarations here, as usual
    }) {}
    
    declare module 'ember-data' {
      interface ModelRegistry {
        'user-meta': UserMeta;
      }
    }
  • Adapters

    import DS from 'ember-data';
    
    export default class UserMeta extends DS.Adapter {
      // properties and methods
    }
    
    declare module 'ember-data' {
      interface AdapterRegistry {
        'user-meta': UserMeta;
      }
    }
  • Serializers

    import DS from 'ember-data';
    
    export default class UserMeta extends DS.Serializer {
      // properties and methods
    }
    
    declare module 'ember-data' {
      interface SerializerRegistry {
        'user-meta': UserMeta;
      }
    }

In addition to the registry, note the oddly defined class for DS.Models. This is because we need to set up the attribute bindings on the prototype (for a discussion of how and why this is different from class properties, see Typing Your Ember, Update, Part 2), but we cannot just use a const here because we need a named type—like a class!—to reference in the type registry and elsewhere in the app.

Opt-in unsafety

Also notice that unlike with service and controller injections, there is no unsafe fallback method by default, because there isn't an argument-less variant of the functions to use as there is for Service and Controller injection. If for some reason you want to opt out of the full type-safe lookup for the strings you pass into methods like findRecord, adapterFor, and serializerFor, you can add these declarations somewhere in your project:

import DS from 'ember-data';

declare module 'ember-data' {
  interface ModelRegistry {
    [key: string]: DS.Model;
  }

  interface AdapterRegistry {
    [key: string]: DS.Adapter;
  }

  interface SerializerRegistry {
    [key: string]: DS.Serializer;
  }
}

However, we strongly recommend that you simply take the time to add the few lines of declarations to each of your DS.Model, DS.Adapter, and DS.Serializer instances instead. It will save you time in even the short run!

Fixing the Ember Data error TS2344 problem

If you're developing an Ember app or addon and not using Ember Data (and accordingly not even have the Ember Data types installed), you may see an error like this and be confused:

node_modules/@types/ember-data/index.d.ts(920,56): error TS2344: Type 'any' does not satisfy the constraint 'never'.

This happens because the types for Ember's test tooling includes the types for Ember Data because the this value in several of Ember's test types can include a reference to DS.Store.

The fix: add a declaration like this in a new file named ember-data.d.ts in your types directory:

declare module 'ember-data' {
  interface ModelRegistry {
    [key: string]: any;
  }
}

This works because (a) we include things in your types directory automatically and (b) TypeScript will merge this module and interface declaration with the main definitions for Ember Data from DefinitelyTyped behind the scenes.

If you're developing an addon and concerned that this might affect consumers, it won't. Your types directory will never be referenced by consumers at all!

Class property setup errors

Some common stumbling blocks for people switching to ES6 classes from the traditional EmberObject setup:

  • Assertion Failed: InjectedProperties should be defined with the inject computed property macros. – You've written someService = inject() in an ES6 class body in Ember 3.1+. Replace it with the .extend approach or by using decorators (@service or @controller) as discussed above. Because computed properties of all sorts, including injections, must be set up on a prototype, not on an instance, if you try to use class properties to set up injections, computed properties, the action hash, and so on, you will see this error.

  • Assertion Failed: Attempting to lookup an injected property on an object without a container, ensure that the object was instantiated via a container. – You failed to pass ...arguments when you called super in e.g. a component class constructor. Always do super(...arguments), not just super(), in your constructor.

Type definitions outside node_modules/@types

By default, the TypeScript compiler loads all type definitions found in node_modules/@types. If the type defs you need are not found there and are not supplied in the root of the package you're referencing, you can register a custom value in paths in the tsconfig.json file. For example, if you're using ember-browserify, you're used to writing imports like this:

import MyModule from 'npm:my-module';

If my-module has types, you will not be able to resolve them this way by default. You can add a simple tweak to your tsconfig.json to resolve the types correctly, however, mapping npm:* to node_modules/*.

{
  "compilerOptions": {
    "paths": {
      "my-app-name/*": ["app/*"],
      "npm:*": ["node_modules/*"]
    }
  }
}

ember-cli-mirage

Mirage adds files from a nonstandard location to your application tree, so you'll need to tell the TypeScript compiler about how that layout works.

For an app, this should look roughly like:

{
  "compilerOptions": {
    "paths": {
      // ...
      "my-app-name/mirage/*": "mirage/*",
    }
  },
  "include": [
    "app",
    "tests",
    "mirage"
  ]
}

And for an addon:

{
  "compilerOptions": {
    "paths": {
      // ...
      "dummy/mirage/*": "tests/dummy/mirage/*",
    }
  },
  "include": [
    "addon",
    "tests"
  ]
}

Note that if Mirage was present when you installed ember-cli-typescript (or if you run ember g ember-cli-typescript), this configuration should be automatically set up for you.

"TypeScript is complaining about multiple copies of the same types!"

You may sometimes see TypeScript errors indicating that you have duplicate type definitions for Ember, Ember Data, etc. This is usually the result of an annoying quirk of the way both npm and yarn resolve your dependencies in their lockfiles.

Just tell me how to fix it

There are two options here, neither of them great:

  • manually edit yarn.lock or package-lock.json and merge the conflicting
  • add a "resolutions" key to your package.json with the version you want to install of the types you're installing:
{
  "resolutions": {
    "**/@types/ember": "2.8.15"
  }
}

Why is this happening?

If you're using another package which includes these types, and then you trigger an upgrade for your own copy of the type definitions, npm and yarn will both try to preserve the existing installation and simply add a new one for your updated version. In most cases, this is sane behavior, because it prevents transitive dependency breakage hell. However, in the specific case of type definitions, it causes TypeScript to get confused.

Using ember-cli-typescript with Ember CLI addons

During development, your .ts files will be watched and rebuilt just like any other sources in your addon when you run ember serve, ember test, etc.

However, in order not to force downstream consumers to install the entire TS build toolchain when they want to use an addon written in TypeScript, ember-cli-typescript is designed to allow you to publish vanilla .js files to the npm registry, alongside .d.ts declarations so that consumers who are using TypeScript can benefit from it.

Publishing

This addon provides two commands to help with publishing your addon: ember ts:precompile and ember ts:clean. The default ember-cli-typescript blueprint will configure your package.json to run these commands in the prepublishOnly and postpublish phases respectively, but you can also run them by hand to verify that the output looks as you expect.

The ts:precompile command will put compiled .js files in your addon directory and populate the overall structure of your package with .d.ts files laid out to match their import paths. For example, addon/index.ts would produce addon/index.js as well as index.d.ts in the root of your package.

The ts:clean command will remove the generated .js and .d.ts files, leaving your working directory back in a pristine state.

Note: While .ts files from both the app and addon directories of your addon will be transpiled by ts:precompile, only the declaration files from addon will be published. Since the final import paths for app files will depend on the name of the consuming application, we can't put those declaration files in a meaningful place.

Linking Addons

Often when developing an addon, it can be useful to run that addon in the context of some other host app so you can make sure it will integrate the way you expect, e.g. using yarn link or npm link.

When you do this for a TypeScript addon, by default your .ts files won't be consumed by the host app. In order for a linked addon to work, you need to take a few steps:

  • ensure ember-cli-typescript is installed and set up in the host app
  • override isDevelopingAddon() in the linked addon to return true
  • update the paths and include entries in your tsconfig.json to instruct the compiler how to resolve imports and include the addon's TypeScript files:
compilerOptions: {
  // ...other options
  paths: {
    // ...other paths, e.g. for your tests/ tree
    "my-app": [
      "app/*",
      // add addon app directory that will be merged with the host application
      "node_modules/my-addon/app/*"
    ],
    // resolve: import x from 'my-addon';
    "my-addon": [
      "node_modules/my-addon/addon"
    ],
    // resolve: import y from 'my-addon/utils/y';
    "my-addon/*": [
      "node_modules/my-addon/addon/*"
    ]
  }
},
include: [
  // ...other includes, e.g. app, tests, types
  "node_modules/my-addon/app",
  "node_modules/my-addon/addon"
]

This will cause ember-cli-typescript in the host app to take over compiling the TS files in the addon as well, automatically rebuilding any time you make a change.

Note: remember to remove your isDevelopingAddon override before publishing!

In-Repo Addons

In-repo addons work in much the same way as linked ones: their TypeScript compilation is managed by the host app. They have isDevelopingAddon return true by default, so you only have to update the paths and include entries in your tsconfig.json to instruct the compiler how to resolve imports and include the addon's TypeScript files:

compilerOptions: {
  // ...other options
  paths: {
    // ...other paths, e.g. for your tests/ tree
    "my-app": [
      "app/*",
      // add addon app directory that will be merged with the host application
      "lib/my-addon/app/*"
    ],
    // resolve: import x from 'my-addon';
    "my-addon": [
      "lib/my-addon/addon"
    ],
    // resolve: import y from 'my-addon/utils/y';
    "my-addon/*": [
      "lib/my-addon/addon/*"
    ]
  }
},
include: [
  // ...other includes, e.g. app, tests, types
  "lib/my-addon"
]

Gotchas

A few things to look out for when working with TypeScript in addons:

  • Normally, addons under development automatically return true from their isDevelopingAddon() hook, which ember-cli-typescript relies on to determine whether to process the addon's .ts files. However, if the name field in your package.json doesn't match the name in your index.js, this default behavior will fail and you'll need to override the method yourself.
  • TypeScript has very particular rules when generating declaration files to avoid letting private types leak out unintentionally. You may find it useful to run ember ts:precompile yourself as you're getting a feel for these rules to ensure everything will go smoothly when you publish.

Current limitations

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, or changes to Ember's object model.

We are hard at work (and would welcome your help!) writing new typings for Ember and the surrounding ecosystem. 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.

Some imports don't resolve

You'll frequently see errors for imports which TypeScript doesn't know how to resolve. For example, if you use Ember Concurrency today and try to import its task helper:

import { task } from 'ember-concurrency';

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][Slack] and we'll be happy to help you.

Type safety when invoking actions

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');