Update TS Guides for Native Types (#2064)

* WIP: Native Types Bonanza * Fix TS gotcha docs * Update addons section * Update Converting An App guides * Update EmberData TS guides * Update tsconfig types docs with latest info * Fix lint * eslint.config.mjs update Co-authored-by: NullVoxPopuli <[email protected]> --------- Co-authored-by: NullVoxPopuli <[email protected]> Co-authored-by: Edward Faulkner <[email protected]>
ember-learn · Feb 14, 2025 · e675d8f · e675d8f
1 parent 8fcae19
commit e675d8f
Show file tree

Hide file tree

Showing 7 changed files with 227 additions and 223 deletions.
diff --git a/.local.dic b/.local.dic
@@ -18,6 +18,7 @@ autotracking
 aXe
 backticks
 beforeEach
+BelongsTo
 blockquote
 blogPost
 bookmarklet
@@ -101,6 +102,7 @@ hackable
 HammerJS
 hardcode
 hashchange
+HasMany
 Hm
 Hoc
 htmlbars
@@ -245,6 +247,7 @@ VoiceOver
 voilà
 Voilà
 vscode-glimmer-syntax
+WarpDrive
 websocket
 working-with-html-css-and-javascript
 yay

diff --git a/guides/release/typescript/additional-resources/gotchas.md b/guides/release/typescript/additional-resources/gotchas.md
@@ -33,10 +33,6 @@ For examples, see:
 
 - [Service][service] registry
 - [Controller][controller] registry
-- EmberData [Model][model] registry
-- EmberData [Transform][transform] registry
-- EmberData [Serializer][serializers-and-adapters] registry
-- EmberData [Adapter][serializers-and-adapters] registry
 
 ## Decorators
 
@@ -125,43 +121,16 @@ export default class MyRoute extends Route {
 }
 ```
 
-## Fixing the EmberData `error TS2344` problem
-
-If you're developing an Ember app or addon and _not_ using EmberData (and accordingly not even have the EmberData types installed), you may see an error like this and be confused:
-
-```text
-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 EmberData because the `this` value in several of Ember's test types can include a reference to the EmberData `Store` class.
-
-**The fix:** add a declaration like this in a new file named `ember-data.d.ts` in your `types` directory:
-
-```typescript {data-filename="types/ember-data.d.ts"}
-declare module 'ember-data/types/registries/model' {
-  export default interface ModelRegistry {
-    [key: string]: unknown;
-  }
-}
-```
-
-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 EmberData 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!
-
 <!-- Internal links -->
 
 [controller]: ../../core-concepts/routing/#toc_controller-injections-and-lookups
 [get-set]: ../../additional-resources/legacy/#toc_classic-get-or-set-methods
 [model-attr]: ../../core-concepts/ember-data/#toc_attr
 [model-belongsto]: ../../core-concepts/ember-data/#toc_belongsto
 [model-hasmany]: ../../core-concepts/ember-data/#toc_hasMany
-[model]: ../../core-concepts/ember-data/#toc_models
 [owner-lookup]: https://api.emberjs.com/ember/release/classes/Owner/methods/lookup?anchor=lookup
-[serializers-and-adapters]: ../../core-concepts/ember-data/#toc_serializers-and-adapters
 [service]: ../../core-concepts/services/#toc_using-services
 [signature]: ../../core-concepts/invokables/#toc_signature-basics
-[transform]: ../../core-concepts/ember-data/#toc_transforms
 
 <!-- External links -->
 

diff --git a/guides/release/typescript/application-development/addons.md b/guides/release/typescript/application-development/addons.md
@@ -18,24 +18,19 @@ Project files will be generated with `.ts` extensions instead of `.js`.
 
 In addition to the usual packages added with `ember addon`, the following packages will be added at their current "latest" value:
 
-- `typescript`
-- `@tsconfig/ember`
-- `@typescript-eslint/*`
-- `@types/ember`
-- `@types/ember-data`
-- `@types/ember__*` – `@types/ember__object` for `@ember/object`, etc.
-- `@types/ember-data__*` – `@types/ember-data__model` for `@ember-data/model`, etc.
-- `@types/qunit`
-- `@types/rsvp`
-
-The `typescript` package provides tooling to support TypeScript type checking and compilation. The `@types` packages from [DefinitelyTyped][] provide TypeScript type definitions for all of the Ember and EmberData modules.
+- `typescript` – tooling to support TypeScript type checking and compilation.
+- `@tsconfig/ember` – a shared TypeScript configuration for Ember apps.
+- `@typescript-eslint/*` – ESLint support for TypeScript.
+- `@types/qunit` - TypeScript type definitions for QUnit.
+- `@types/rsvp` - TypeScript type definitions for RSVP.
+- `@warp-drive/core-types` - shared core types, type utilities and constants for the WarpDrive and EmberData packages.
 
 <div class="cta">
   <div class="cta-note">
     <div class="cta-note-body">
       <div class="cta-note-heading">Zoey says...</div>
       <div class="cta-note-message">
-        Ember also publishes its own native types compiled directly from its source code, as described <a href="https://blog.emberjs.com/stable-typescript-types-in-ember-5-1/">in this blog post</a>. For now, we continue to use the <code>@types</code> packages by default for the sake of compatibility with EmberData, because EmberData is not yet compatible with Ember's native official types. However, if you do not use EmberData, we <i>highly</i> recommend following the instructions in that blog post to switch to the native types, which are guaranteed to always be 100% correct and 100% up to date!
+        Ember and EmberData publish their own native types compiled directly from their source code, so you do not need to install any <code>@types/ember</code> or <code>@types/ember-data</code> packages. These packages should be considered legacy, are only lightly maintained, and will conflict with the native types.
       </div>
     </div>
     <img src="/images/mascots/zoey.png" role="presentation" alt="">
@@ -164,7 +159,6 @@ declare module 'addon/templates/*' {
 
 <!-- External links -->
 
-[DefinitelyTyped]: https://github.com/DefinitelyTyped/DefinitelyTyped
 [dts]: https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html
 [ember-addon]: https://cli.emberjs.com/release/writing-addons/
 [glint]: https://typed-ember.gitbook.io/glint/

diff --git a/guides/release/typescript/application-development/configuration.md b/guides/release/typescript/application-development/configuration.md
@@ -11,7 +11,12 @@ If you use the `--typescript` flag when generating your Ember app, we generate a
       "my-app/tests/*": ["tests/*"],
       "my-app/*": ["app/*"],
       "*": ["types/*"]
-    }
+    },
+    "types": [
+      "ember-source/types",
+      "ember-data/unstable-preview-types",
+      // ...more ember-data types...
+      "@warp-drive/core-types/unstable-preview-types"
   }
 }
 ```
@@ -38,8 +43,8 @@ To enable TypeScript sourcemaps, you'll need to add the corresponding configurat
 
 ```javascript {data-filename="ember-cli-build.js" data-diff="+3"}
 const app = new EmberApp(defaults, {
-  'ember-cli-babel': { enableTypeScriptTransform: true },
-  babel: { sourceMaps: 'inline' },
+  "ember-cli-babel": { enableTypeScriptTransform: true },
+  babel: { sourceMaps: "inline" },
 });
 ```
 

diff --git a/guides/release/typescript/application-development/converting-an-app.md b/guides/release/typescript/application-development/converting-an-app.md
@@ -2,35 +2,47 @@ These directions are for converting an _existing_ Ember app to TypeScript. If yo
 
 ## Enable TypeScript Features
 
-### A Bit of a Hack
+### Install TypeScript and Related Packages
 
-Since `ember-cli` _currently_ has no flag to convert your project to TypeScript, we're going to use a bit of a hack and _temporarily_ install the legacy `ember-cli-typescript` addon to complete most of the migration:
+See [Getting Started: Packages to Support TypeScript][packages] for descriptions of these packages.
 
 ```shell
-ember install ember-cli-typescript@latest
+npm add --save-dev typescript @tsconfig/ember
+npm add --save-dev @types/qunit @types/rsvp
+npm add --save-dev @typescript-eslint/eslint-plugin @typescript-eslint/parser
+npm remove @babel/plugin-proposal-decorators @babel/eslint-parser
 ```
 
-The `ember-cli-typescript` addon will install _most_ of the necessary packages and create or update _most_ of the necessary files as described in [Getting Started][].
+### Add TypeScript Configuration
+
+Add a `tsconfig.json` file to the root of your project. Copy its contents from the [current output from the Ember CLI blueprints][tsconfig.json].
 
-You can then immediately remove the `ember-cli-typescript` dependency and follow the rest of this guide.
+### Set Up TypeScript for EmberData
 
-### Manually Enable TypeScript Transpilation
+Follow the instructions in the [EmberData Typescript Guides][ED-ts-guides].
+
+### Enable TypeScript Transpilation for Builds
 
 To enable TypeScript transpilation in your app, simply add the corresponding configuration for Babel to your `ember-cli-build.js` file.
 
-```javascript {data-filename="ember-cli-build.js" data-diff="+2"}
-const app = new EmberApp(defaults, {
-  'ember-cli-babel': { enableTypeScriptTransform: true },
-});
+```javascript {data-filename="ember-cli-build.js" data-diff="+3"}
+module.exports = function (defaults) {
+  const app = new EmberApp(defaults, {
+    "ember-cli-babel": { enableTypeScriptTransform: true },
+    // ...
+  });
+
+  return app.toTree();
+};
 ```
 
-### Manually Add `lint:types` Script
+### Enable Type Checking in CI
 
 To easily check types with the command line, add the `lint:types` script as shown [here][lint-types].
 
 The default `lint` script generated by Ember CLI will include the `lint:types` script automatically.
 
-### Manually Force Blueprint Generators to Use TypeScript
+### Configure Blueprint Generators to Use TypeScript
 
 With the following configuration, project files will be generated with `.ts` extensions instead of `.js`:
 
@@ -41,13 +53,34 @@ With the following configuration, project files will be generated with `.ts` ext
 }
 ```
 
-### Manually Set Up `@typescript-eslint`
-
-```shell
-npm add --save-dev @typescript-eslint/eslint-plugin @typescript-eslint/parser
+```js {data-filename="config/ember-cli-update.json" data-diff="+12"}
+{
+  // ...
+  "packages": [
+    {
+      "name": "ember-cli",
+      // ...
+      "blueprints": [
+        {
+          // ...
+          "options": [
+            // ...
+            "--typescript"
+          ]
+        }
+      ]
+    }
+  ]
+}
 ```
 
-Then, update your `.eslintrc.js` to include the [current output from the Ember CLI blueprints][eslintrc]. You might consider using ESLint [overrides][] configuration to separately configure your JavaScript and TypeScript files during the migration.
+### Configure ESLint
+
+Then, update your `eslint.config.mjs` to include the [current output from the Ember CLI blueprints][eslintrc]. You might consider using ESLint [overrides][] configuration to separately configure your JavaScript and TypeScript files during the migration.
+
+### Add Initial Type Declarations
+
+Add types for your `config/environment.js` file by creating a type declaration file at `app/config/environment.d.ts`. You can find an example file in the [current output from the Ember CLI blueprints][environment.d.ts].
 
 ## Migrate Existing Code to TypeScript
 
@@ -83,23 +116,29 @@ In general, we recommend migrating to Octane idioms before, or in conjunction wi
 
 ## ember-cli-typescript
 
-If you're migrating from `ember-cli-typescript`, particularly an older version, to Ember's out-of-the-box TypeScript support, you may also need to update your `tsconfig.json`. Current versions of `ember-cli-typescript` generate the correct config at installation. You do _not_ need `ember-cli-typescript` installed for new apps or addons.
+The `ember-cli-typescript` package was used to add TypeScript support to Ember apps before Ember's native TypeScript support was available. You do _not_ need `ember-cli-typescript` installed for new apps or addons.
+
+If you're migrating from `ember-cli-typescript` to Ember's native TypeScript support, most of your existing configuration will still be relevant. Just read through the steps of this guide and ensure that your config matches the expected config as described above.
 
 <!-- Internal links -->
 
+[ED-ts-guides]: ../../core-concepts/ember-data/#toc_adding-emberdata-types-to-an-existing-typescript-app
 [getting started]: ../../getting-started/
 [legacy]: ../../additional-resources/legacy/
+[packages]: ../../getting-started/#toc_packages-to-support-typescript
 [strictness]: ../../additional-resources/faq/#toc_strictness
 
 <!-- External links -->
 
 [allowJs]: https://www.typescriptlang.org/tsconfig/#allowJs
 [any]: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any
 [dts]: https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html
-[eslintrc]: https://github.com/ember-cli/editor-output/blob/stackblitz-app-output-typescript/.eslintrc.js
+[environment.d.ts]: https://github.com/ember-cli/editor-output/blob/stackblitz-app-output-typescript/app/config/environment.d.ts
+[eslintrc]: https://github.com/ember-cli/editor-output/blob/stackblitz-app-output-typescript/eslint.config.mjs
 [lint-types]: https://github.com/ember-cli/editor-output/blob/stackblitz-app-output-typescript/package.json
 [JSDoc]: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#handbook-content
 [overrides]: https://eslint.org/docs/latest/use/configure/configuration-files#configuration-based-on-glob-patterns
 [ts-check]: https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html#ts-check
 [ts-expect-error]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-9.html
+[tsconfig.json]: https://github.com/ember-cli/editor-output/blob/stackblitz-app-output-typescript/tsconfig.json
 [unknown]: https://www.typescriptlang.org/docs/handbook/2/functions.html