ember-cli-typescript

v5.3.0

Published

8 months ago

Allow Ember apps to use TypeScript files.

Downloads

2,046,564

0High
0Medium
0Low

ember-addon typescript

MAINTENANCE MODE

ember-cli-typescript will no longer be updated unless necessary - ec-ts is no longer needed and all available features are configurable in userland.

See the official TypeScript docs on the ember guides website here: https://guides.emberjs.com/release/typescript/ This section of the docs has details for getting started with TypeScript, beyond what is laid out here.

With every release, we output the --typescript output of new ember apps to this StackBlitz: https://stackblitz.com/github/ember-cli/editor-output/tree/stackblitz-app-output-typescript

How to use TypeScript without `ember-cli-typescript`?

Apps and v1 addons need to configure Babel to compile TypeScript files via the ember-cli-babel config, as described in the ember-cli-babel.

Additionally, you will need the tsconfig.json generated by the Ember TypeScript blueprint (see below for details), and then can run glint or tsc directly on the CLI. (Again, see the official docs for details!)

Apps

'ember-cli-babel': {
  enableTypeScriptTransform: true,
},

v1 addons

Configure this in the addon's index.js in the root of the project:

module.exports = {
  name: require('package').name,
  options: {
    'ember-cli-babel': {
      enableTypeScriptTransform: true
    }
  }
}

v2 addons

The V2 Addon Blueprint does not use nor need ember-cli-typescript, nor any of its features.

What tsconfig.json should be used?

The official blueprints for apps and v1 addons (as of 2023-12-06) specifies:

{
  "extends": "@tsconfig/ember/tsconfig.json",
  "compilerOptions": {
    // The combination of `baseUrl` with `paths` allows Ember's classic package
    // layout, which is not resolvable with the Node resolution algorithm, to
    // work with TypeScript.
    "baseUrl": ".",
    "paths": {
      "<%= name %>/tests/*": ["tests/*"],
      "<%= name %>/*": ["app/*"],
      "*": ["types/*"]
    }
  }
}

{
  "extends": "@tsconfig/ember/tsconfig.json",
  "compilerOptions": {
    // The combination of `baseUrl` with `paths` allows Ember's classic package
    // layout, which is not resolvable with the Node resolution algorithm, to
    // work with TypeScript.
    "baseUrl": ".",
    "paths": {
      "dummy/tests/*": ["tests/*"],
      "dummy/*": ["tests/dummy/app/*", "app/*"],
      "<%= addonName %>": ["addon"],
      "<%= addonName %>/*": ["addon/*"],
      "<%= addonName %>/test-support": ["addon-test-support"],
      "<%= addonName %>/test-support/*": ["addon-test-support/*"],
      "*": ["types/*"]
    }
  }
}

What `@types/*` packages do I install?

"@types/ember": "^4.0.8",
"@types/ember-data": "^4.4.13",
"@types/ember-data__adapter": "^4.0.4",
"@types/ember-data__model": "^4.0.3",
"@types/ember-data__serializer": "^4.0.4",
"@types/ember-data__store": "^4.0.5",
"@types/ember__application": "^4.0.9",
"@types/ember__array": "^4.0.7",
"@types/ember__component": "^4.0.19",
"@types/ember__controller": "^4.0.9",
"@types/ember__debug": "^4.0.6",
"@types/ember__destroyable": "^4.0.3",
"@types/ember__engine": "^4.0.8",
"@types/ember__error": "^4.0.4",
"@types/ember__helper": "^4.0.4",
"@types/ember__modifier": "^4.0.7",
"@types/ember__object": "^4.0.9",
"@types/ember__owner": "^4.0.7",
"@types/ember__polyfills": "^4.0.4",
"@types/ember__routing": "^4.0.17",
"@types/ember__runloop": "^4.0.7",
"@types/ember__service": "^4.0.6",
"@types/ember__string": "^3.16.3",
"@types/ember__template": "^4.0.4",
"@types/ember__test": "^4.0.4",
"@types/ember__utils": "^4.0.5",
"@types/qunit": "^2.19.7",
"@types/rsvp": "^4.0.6",

You can use ember's built in types, so you only need the following:

"@types/qunit": "^2.19.7",
"@types/rsvp": "^4.0.6",

Note that ember-data will eventually ship their own types, and allow everyone to remove all the DT types.

Documentation

This README focuses on basic information about setting up and using the addon. For more details, see the documentation, which includes:

troubleshooting tips
a walkthrough for using TypeScript with Ember effectively
guides for publishing addons written in TypeScript
more details on how the addon sets up your project during installation

…and much more!

Usage

Installation and Setup

You can simply ember install the dependency like normal:

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, see below! you should check to merge any tweaks you've made to tsconfig.json.

Upgrading from 1.x

There are a number of important changes between ember-cli-typescript v1 and v2, which mean the upgrade process is straightforward but specific:

Update ember-cli-babel. Fix any problems introduced during the upgrade.
Update ember-decorators. Fix any problems introduced during the upgrade.
Update ember-cli-typescript. Follow the detailed upgrade guide below to fix discrepancies between Babel and TypeScript's compiled output.

If you deviate from this order, you are likely to have a much more difficult time upgrading!

Update ember-cli-babel

ember-cli-typescript requires ember-cli-babel at version 7.1.0 or above, which requires ember-cli 2.13 or above. It also requires @babel/core 7.2.0 or higher.

The recommended approach here is to deduplicate existing installations of the dependency, remove and reinstall ember-cli-babel to make sure that all its transitive dependencies are updated to the latest possible, and then to deduplicate again.

If using yarn:

npx yarn-deduplicate
yarn remove ember-cli-babel
yarn add --dev ember-cli-babel
npx yarn-deduplicate

If using npm:

npm dedupe
npm uninstall ember-cli-babel
npm install --save-dev ember-cli-babel
npm dedupe

Note: If you are also using ember-decorators—and specifically the babel-transform that gets added with it—you will need update @ember-decorators/babel-transforms as well (anything over 3.1.0 should work):

ember install ember-decorators@^3.1.0 @ember-decorators/babel-transforms@^3.1.0

Update ember-decorators

If you're on a version of Ember before 3.10, follow the same process of deduplication, reinstallation, and re-deduplication as described for ember-cli-babel above for ember-decorators. This will get you the latest version of ember-decorators and, importantly, its @ember-decorators/babel-transforms dependency.

Update ember-cli-typescript

Now you can simply ember install the dependency like normal:

ember install ember-cli-typescript@latest

Note: To work properly, starting from v2, ember-cli-typescript must be declared as a dependency, not a devDependency for addons. With ember install this migration will be automatically handled for you.

If you choose to make the upgrade manually with yarn or npm, here are the steps you need to follow:

Remove ember-cli-typescript from your devDependencies.
With yarn:
```
yarn remove ember-cli-typescript
```
With npm:
```
npm uninstall ember-cli-typescript
```

Install the latest of ember-cli-typescript as a dependency:

With yarn:

yarn add ember-cli-typescript@latest

With npm:

npm install --save ember-cli-typescript@latest

Run ember generate:
```
ember generate ember-cli-typescript
```

Account for addon build pipeline changes

Since we now integrate in a more traditional way into Ember CLI's build pipeline, there are two changes required for addons using TypeScript.

Addons can no longer use .ts in app, because an addon's app directory gets merged with and uses the host's (i.e. the other addon or app's) preprocessors, and we cannot guarantee the host has TS support. Note that .ts will continue to work for in-repo addons because the app build works with the host's (i.e. the app's, not the addon's) preprocessors.
Similarly, apps must use .js to override addon defaults in app, since the different file extension means apps no longer consistently "win" over addon versions (a limitation of how Babel + app merging interact).

Account for TS → Babel issues

ember-cli-typescript v2 uses Babel to compile your code, and the TypeScript compiler only to check your code. This makes for much faster builds, and eliminates the differences between Babel and TypeScript in the build output that could cause problems in v1. However, because of those differences, you’ll need to make a few changes in the process of upgrading.

const enum is not supported at all. You will need to replace all uses of const enum with simply enum or constants.
Using ES5 getters or setters with this type annotations is not supported through at least Babel 7.3. However, they should also be unnecessary with ES6 classes, so you can simply remove the this type annotation.
Trailing commas after rest function parameters (function foo(...bar[],) {}) are disallowed by the ECMAScript spec, so Babel also disallows them.
Re-exports of types have to be disambiguated to be types, rather than values. Neither of these will work:
```
export { FooType } from 'foo';
```
```
import { FooType } from 'foo';
export { FooType };
```
In both cases, Babel attempts to emit a value export, not just a type export, and fails because there is no actual value to emit. You can do this instead as a workaround:
```
import * as Foo from 'foo';
export type FooType = Foo.FooType;
```

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 a channel (#topic-typescript) on the Ember Community Discord server 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 don't find an answer, please open an enhancement request or bug report in this project.

⚙️ 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 don't find an answer, please open an enhancement request or bug report in this project.

✅ Issues With Linting TypeScript

The TypeScript compiler does some very basic linting of your code, but most developers use (and Microsoft now officially recommends) ESLint.

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

For example, in VS Code, you might see a popover with this message:

[eslint] variable name must be in lowerCamelCase, PascalCase or UPPER_CASE (variable-name)

Here, variable-name is the name of the rule, and [eslint] is the source of the rule.

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

Supported Ember and TypeScript versions

ember-cli-typescript runs its test suite against Ember CLI current and beta. 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.

This library supports the current version of TypeScript and at least one previous minor or major release. In other words, if 3.4 is the latest release, we do support 3.4.x, 3.3.x, and might support 3.2.x as well. (The test suite only runs against the current release and next branch, but the TS versions do not affect the build process in the same way they do type definitions.)

Installing from git

This addon uses TypeScript for its own implementation, so if you install ember-cli-typescript from git rather than from the npm registry, you won't get compiled .js files. To get everything working, you can install ts-node as a project dependency, and ember-cli-typescript will ensure it's registered correctly to transpile source files as needed.