You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+42-27Lines changed: 42 additions & 27 deletions
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,8 @@
2
2
3
3
Use TypeScript in your Ember 2.x and 3.x apps!
4
4
5
-
[](https://travis-ci.org/typed-ember/ember-cli-typescript)[](https://ci.appveyor.com/project/chriskrycho/ember-cli-typescript/branch/master)
5
+
[](https://travis-ci.org/typed-ember/ember-cli-typescript)
*[Setup and Configuration](#setup-and-configuration)
@@ -40,14 +41,19 @@ ember install ember-cli-typescript@latest
40
41
41
42
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`.
42
43
43
-
In addition to ember-cli-typescript, the following are installed—all at their current "latest" value—or generated:
44
+
In addition to ember-cli-typescript, we make the following changes to your project:
45
+
46
+
* We install the following packages—all at their current "latest" value—or generated:
*[`@types/ember-test-helpers`](https://www.npmjs.com/package/@types/ember-test-helpers) – these are the importable test helpers from [RFC #232](https://github.com/emberjs/rfcs/blob/master/text/0232-simplify-qunit-testing-api.md)-style tests
53
+
*[`@types/ember-testing-helpers`](https://www.npmjs.com/package/@types/ember-testing-helpers) – these are the globally-available acceptance test helpers
*`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](#global-types-for-your-package) for information on its default contents and how to use it effectively
53
59
*`types/<app name>/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](#environment-and-configuration-typings) for details
@@ -58,35 +64,22 @@ ember-cli-typescript runs its test suite against the 2.12 LTS, the 2.16 LTS, the
58
64
59
65
### `tsconfig.json`
60
66
61
-
In general, you may customize your TypeScript build process as usual using the `tsconfig.json` file. However, there are a couple points worth noting.
62
-
63
-
First, 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.
67
+
We generate a good default [`tsconfig.json`][blueprint], which will usually make everything _Just Work_. In general, you may customize your TypeScript build process as usual using the `tsconfig.json` file.
64
68
65
-
Second, if you make changes to the paths included in or excluded from the build via your `tsconfig.json`, you will need to restart the server to take the changes into account: ember-cli-typescript does not currently watch the `tsconfig.json` file
66
-
67
-
Finally, depending on what you're doing, you may notice that your tweaks to `tsconfig.json` aren't applied _exactly_ as you might expect, because the configuration file is used by both Ember CLI (via [broccoli]) and for tool
68
-
integration in editors.
69
-
70
-
[broccoli]: http://broccolijs.com/
69
+
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!):
71
70
72
-
Usually, the TypeScript compiler's behavior is determined entirely by configuration properties like `"include"`, `"exclude"`, `"outFile"`, and `"outDir"`. However, your editor _also_ leans on those properties to determine how to resolve files, what to do during file watching, etc. And in this case, we have the third player of Ember.js and Broccoli in play, managing the TypeScript compilation and feeding it only what it actually needs (so that Broccoli's support for tree merging, concatenation, etc. works as expected).
71
+
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.
73
72
74
-
This addon takes the following approach to allow normal use with your editor tooling while also supporting the customization required for Broccoli:
73
+
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.
75
74
76
-
* 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.
75
+
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!
77
76
78
-
* Then, before calling broccoli, the addon:
77
+
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.
79
78
80
-
* removes any configured `outDir` to avoid name resolution problems in the Broccoli tree processing
81
-
* sets the `noEmit` option to `false` so that the compiler will emit files for consumption by your app
82
-
* sets `allowJs` to `false`, so that the TypeScript compiler does not try to process JavaScript files imported by TypeScript files in your app
83
-
* removes all values set for `include`, since we use Broccoli to manage the build pipeline directly
79
+
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.
You can still customize those properties in `tsconfig.json` for your use case. Just note that the changes won't directly impact how Ember/Broccoli builds your app!
88
-
89
-
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.
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!
312
305
306
+
#### Fixing the Ember Data `error TS2344` problem
307
+
308
+
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:
309
+
310
+
```
311
+
node_modules/@types/ember-data/index.d.ts(920,56): error TS2344: Type 'any' does not satisfy the constraint 'never'.
312
+
```
313
+
314
+
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`.
315
+
316
+
**The fix:** add a declaration like this in your `types` directory:
317
+
318
+
```ts
319
+
declaremodule'ember-data' {
320
+
interfaceModelRegistry {
321
+
[key:string]:any;
322
+
}
323
+
}
324
+
```
325
+
326
+
(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!)
327
+
313
328
### Type definitions outside `node_modules/@types`
314
329
315
330
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, if you are using [True Myth], you'll need to follow that project's installation instructions (since it ships types in a special location to support both CommonJS and ES Modules):
0 commit comments