Advance RFC #0724 "Official TypeScript Support" to Stage Recommended

[emberjs-rfcs-bot]

Advance #724 to the Recommended Stage

Summary

This pull request is advancing the RFC to the Recommended Stage.

• PR to Accepted Stage: RFC: Official TypeScript support #724
• PR to Ready For Release Stage
• PR to Released Stage

An FCP is required before merging this PR to advance.

Recommended Stage Summary

The "Recommended" stage is the final milestone for an RFC. It provides a signal to the wider community to indicate that a feature has been put through its ecosystem paces and is ready to use.

To reach the "Recommended" stage, the following should be true:

If appropriate, the feature is integrated into the tutorial and the guides prose. API documentation is polished and updates are carried through to other areas of API docs that may not directly pertain to the feature.

If the proposal replaces an existing feature, the addon ecosystem has largely updated to work with both old and new features.

If the proposal updates or replaces an existing feature, high-quality codemods are available.

If needed, Ember debugging tools as well as popular IDE support have been updated to support the feature.

If the feature is part of a suite of features that were designed to work together for best ergonomics, the other features are also ready to be "Recommended".

Any criteria for "Recommended" for this proposal that were established in the Ready For Release stage have been met.

An FCP is required to enter this stage. Multiple RFCs may be moved as a batch into "Recommended" with the same PR.

Checklist to move to Recommended

• Criteria specific to this feature: Any additional criteria for "Recommended" for this proposal that were established in the Ready For Release stage have been met.
• Tutorial: If appropriate, the feature is integrated into the tutorial.
• Guides: If appropriate, the feature is integrated into the guides prose.
• API Docs: API documentation is polished and updates are carried through to other areas of API docs that may not directly pertain to the feature.
• Addon Ecosystem: If the proposal replaces an existing feature, the addon ecosystem has largely updated to work with both old and new features.
• Codemods: If the proposal updates or replaces an existing feature, high-quality codemods are available.
• Debugging Tools: If needed, Ember debugging tools (e.g. Ember Inspector, Deprecation Workflow) have been updated to support the feature.
• IDE Support: If needed, popular IDE support has been updated to support the feature.
• Engines, SSR: If needed, ecosystem feature such as Ember Engines, SSR support have been updated to support the feature.
• Blueprints: Blueprints have been updated to support the feature and to reflect the new best practices implied by this feature.
• Linting: Lint rules have been updated or added or removed to support the feature and to reflect the new best practices implied by this feature.
• Deprecations: If this feature implies that other features are no longer best practice, RFCs have been created to deprecate those features.
• Blog Post: Consider if a blog post should be written to introduce this feature to the community.
• Feature Suite: If the feature is part of a suite of features that were designed to work together for best ergonomics, the other features are also ready to be "Recommended".
• FCP to Recommended: This PR has been converted from a draft to a regular PR and the Final Comment Period label has been added to start the FCP.

Criteria for moving to Recommended (required)

<-- Copy and paste the criteria for "Recommended" from the Ready For Release stage here -->

A set of criteria for moving this RFC to the Recommended Stage, following release:

1. Add TypeScript chapter to Ember Guides.

[ef4]

Even though official stable types in ember-source have been released for a while, the latest app blueprint in ember-cli still uses DefinitelyTyped instead.

[gitKrystan]

I've started a PR to the Guides for basic TS documentation. WIP PR here: ember-learn/guides-source#1960

[gitKrystan]

Even though official stable types in ember-source have been released for a while, the latest app blueprint in ember-cli still uses DefinitelyTyped instead.

This is intentional because the ember-source stable types do not currently work with the ember-data types yet. The guides section will explain this and we are working toward getting ember-data types working with ember-source stable types ASAP.

[ef4]

Latest update here: people are working through the issues for the ember-data types. That is the remaining blocker to enable this feature in the default blueprint.

[gitKrystan]

TypeScript chapter for the Ember Guides:
PR: ember-learn/guides-source#1960
Preview: https://deploy-preview-1960--ember-guides.netlify.app/release/using-typescript/

[ef4]

Status update during rfc review: people are actively working on the ember-data types, probably going to re-use the strategy ember-source has been using.

[ef4]

• ember-data canary has now has types
• the ember data packages are about to start shipping separate type packages to aid migration.

[ef4]

The ember-data separate type packages have shipped and there is now a guide.

There is work to do to integrate these new types with the main emberjs guides.

[ef4]

Status notes:

• the implementation side needs more people to test the alpha types so we can build confidence
• the guides could begin getting updated as long as it's labeled to explain that these are the alpha types

[kategengler]

Open question for Ember Data types: (from @runspired) What is acceptable to reach stable? Do we need to reduce the surface area of files to match the JS Files that are shipping for it to be official? Possible option is "dts buddy".

Krystan and Peter: Not necessary for official?

Runspired: What about types that they shouldn't have access to?

Ed: Internal structure leaking is a problem. There are hacks in the addon authoring blueprint to avoid these references.

Peter: Good point on imports, probably needs to be resolved.

Ed: Ember doesn't roll up

Verdict: need a solution

[ef4]

The guides already have a "Zoe says" box pointing to the blog post that has instructions to use the native types, explaining the caveat that they're not default because ember-data users can't use them yet.

Maybe we can update that info to also point to the ember-data unstable types?

[gitKrystan]

PR to point Guides users to the EmberData alpha types in conjunction with the Ember native types: ember-learn/guides-source#2036 (now merged).

[ef4]

We think it's time to PR the blueprints in ember-cli to replace the definitely-typed packages, since even including unstable ember-data types is going to be a better experience.

[ef4]

There were concerns about the lack of type-rollup meaning that internal paths would be usable in apps. We think it would be sufficient to document that types including (for example) /-private are not supported public API.