From 431b506a1e7ea617a26b0e9b223710c8f8e7328b Mon Sep 17 00:00:00 2001 From: Chris Freeman Date: Thu, 11 Nov 2021 13:52:28 -0700 Subject: [PATCH 01/10] first pass on Motivation --- text/0000-typescript-blueprints.md | 81 ++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 text/0000-typescript-blueprints.md diff --git a/text/0000-typescript-blueprints.md b/text/0000-typescript-blueprints.md new file mode 100644 index 0000000000..14745c1ea4 --- /dev/null +++ b/text/0000-typescript-blueprints.md @@ -0,0 +1,81 @@ +--- +Stage: Accepted +Start Date: 2021-11-11 +Release Date: Unreleased +Release Versions: + ember-source: vX.Y.Z + ember-data: vX.Y.Z + Relevant Team(s): Ember CLI +RFC PR: +--- + + + +# Author Built-In Blueprints in TypeScript + +## Summary + +> One paragraph explanation of the feature. + +## Motivation + +Ember CLI's generators are a foundational part of Ember itself. They are one of the first elements of the developer experience that Ember prides itself on, and continue to be an essential part of the ecosystem by virtue of the fact that both apps and addons can generate their own custom blueprints. For many years, the `ember-cli-typescript` addon has shipped its own set of TypeScript-flavored built-in blueprints that essentially act as drop-in replacement for the built-in blueprints that ship with Ember today. However, these blueprints have proven very difficult to maintain as it involves keeping them all up to date with every single change made to Ember itself, so much so that the current TypeScript blueprints have diverged to the point there is currently not a TypeScript blueprint for components at all. + +As part of the larger effort to [make Typescript an officially supported language in Ember](https://github.com/emberjs/rfcs/pull/724), we should ship TypeScript blueprints in Ember itself, in place of the existing Javascript blueprints. This would provide several benefits over the current system: + +1. Remove the disconnect between TypeScript and JavaScript blueprints discussed above, as the `ember-cli-typescript` team would no longer be responsible for maintaining an entirely independent set of blueprints. +1. Pave the way for TypeScript blueprint generation in any Ember app or addon right out of the box (likely via a `--typescript` flag or something similar). +1. Enable addon authors to better support TypeScript users by allowing them to publish their own TypeScript blueprints without concern for also supporting JavaScript users. + +Note that this does _not_ mean that we should _generate_ TypeScript by default, but rather that the blueprints themselves should _begin_ as TypeScript before actually being reified as actual code. By default, all of the Ember generators would still behave exactly as they do today: by generating Javascript files. This RFC is primarily concerned with TypeScript as an _implementation detail_ for the existing blueprints, rather than being prescriptive about whether or not users should adopt TypeScript themselves. + +## Detailed design + +> This is the bulk of the RFC. + +> Explain the design in enough detail for somebody +> familiar with the framework to understand, and for somebody familiar with the +> implementation to implement. This should get into specifics and corner-cases, +> and include examples of how the feature is used. Any new terminology should be +> defined here. + +## How we teach this + +> What names and terminology work best for these concepts and why? How is this +> idea best presented? As a continuation of existing Ember patterns, or as a +> wholly new one? + +> Would the acceptance of this proposal mean the Ember guides must be +> re-organized or altered? Does it change how Ember is taught to new users +> at any level? + +> How should this feature be introduced and taught to existing Ember +> users? + +## Drawbacks + +> Why should we _not_ do this? Please consider the impact on teaching Ember, +> on the integration of this feature with other existing and planned features, +> on the impact of the API churn on existing apps, etc. + +> There are tradeoffs to choosing any path, please attempt to identify them here. + +## Alternatives + +> What other designs have been considered? What is the impact of not doing this? + +> This section could also include prior art, that is, how other frameworks in the same domain have solved this problem. + +## Unresolved questions + +> Optional, but suggested for first drafts. What parts of the design are still +> TBD? From e7fab385ecf69bd3014da77440421e3a366fd19c Mon Sep 17 00:00:00 2001 From: Chris Freeman Date: Thu, 11 Nov 2021 14:35:59 -0700 Subject: [PATCH 02/10] first pass --- text/0000-typescript-blueprints.md | 38 ++++++++++++------------------ 1 file changed, 15 insertions(+), 23 deletions(-) diff --git a/text/0000-typescript-blueprints.md b/text/0000-typescript-blueprints.md index 14745c1ea4..7bc8f5ec15 100644 --- a/text/0000-typescript-blueprints.md +++ b/text/0000-typescript-blueprints.md @@ -36,44 +36,36 @@ As part of the larger effort to [make Typescript an officially supported languag 1. Pave the way for TypeScript blueprint generation in any Ember app or addon right out of the box (likely via a `--typescript` flag or something similar). 1. Enable addon authors to better support TypeScript users by allowing them to publish their own TypeScript blueprints without concern for also supporting JavaScript users. -Note that this does _not_ mean that we should _generate_ TypeScript by default, but rather that the blueprints themselves should _begin_ as TypeScript before actually being reified as actual code. By default, all of the Ember generators would still behave exactly as they do today: by generating Javascript files. This RFC is primarily concerned with TypeScript as an _implementation detail_ for the existing blueprints, rather than being prescriptive about whether or not users should adopt TypeScript themselves. +Note that this does **not** mean that we should generate TypeScript by default, but rather that the blueprints themselves should _begin_ as TypeScript before actually being reified as actual code. By default, all of the Ember generators would still behave exactly as they do today: by generating Javascript files. This RFC is primarily concerned with TypeScript as an _implementation detail_ for the existing blueprints, rather than being prescriptive about whether or not users should adopt TypeScript themselves. ## Detailed design -> This is the bulk of the RFC. +tl;dr: Blueprints will be handled exactly the same as before, with the one exception that any blueprint file ending in `.ts` will be run through Babel's [`@babel/plugin-transform-typescript`](https://babeljs.io/docs/en/babel-plugin-transform-typescript) to strip out all the TypeScript syntax. Please read on for a more detailed explanation. -> Explain the design in enough detail for somebody -> familiar with the framework to understand, and for somebody familiar with the -> implementation to implement. This should get into specifics and corner-cases, -> and include examples of how the feature is used. Any new terminology should be -> defined here. +In the current generator system, new files are created from templates that resides in the `files` directory of the blueprint that corresponds to generator that was invoked. When a user runs `ember generate service foo`, Ember CLI will locate the template at `blueprints/service/files/__root__/__path__/__name__.js`, load it into memory, perform a text replacement on all of the EJS-style tags (e.g. `class <%= classifiedModuleName => extends Service` becomes `class Foo extends Service`), and then writes the entire string out to a file at the correct path inside the parent app or addon. Notably, there is no evaluation of the code itself, as the entire process of blueprint generation is simple text replacement. -## How we teach this +In the new version of Ember's blueprint system, this template would instead be named `__name__.ts`. The generator process would run identically (locate the template, read into memory, perform text replacement) up until it is actually time to _write_ the file. Before that occurs, the (now fully populated) in-memory version of the newly generated file would be run through Babel's [`@babel/plugin-transform-typescript`](https://babeljs.io/docs/en/babel-plugin-transform-typescript). This would strip the file of all TypeScript-related syntax, resulting in a completely valid JavaScript file with no evidence that it had begun as TypeScript file. In this way, we're able to ensure that the built-in generators would continue to perform as exactly as they have previously. + +There are a few details worth calling out about this change to the generation process: -> What names and terminology work best for these concepts and why? How is this -> idea best presented? As a continuation of existing Ember patterns, or as a -> wholly new one? +1. While the TypeScript files are parsed and transformed, they are _not_ type-checked in any way. The Babel plugin is concerned solely with the transformation of TypeScript syntax into JavaScript syntax and does not pay any attention to what the types actually are. This is a good thing, as it minimizes any performance cost during the generation process and we'd expect any actual type-checking to happen at compilation time in the user's app, using their own `tsconfig` rather than one we'd have to supply (and maintain). +1. By default, the generators would behave exactly as they did before, however, the fact that all the blueprints are now written in TypeScript means that it becomes trivial to add a `--typescript` flag to the `generate` command that tells the generator to simply bypass the Babel transform and instead output TypeScript directly. Since TypeScript is a superset of JavaScript, we're able to easily accomodate both sets of users with a single blueprint file by starting out with the "higher-fidelity" TypeScript and down-leveling it JavaScript when needed. +1. Addon authors would be able to ship blueprints written in TypeScript that would "just work" in the same way that the built-in blueprints would, e.g. they'd get support for both JavaScript and TypeScript versions of their blueprints with no additional effort or maintenance. +1. No one is _required_ to write their blueprints in TypeScript. Any blueprint written in JavaScript would be handled in the exact same way that they are today. -> Would the acceptance of this proposal mean the Ember guides must be -> re-organized or altered? Does it change how Ember is taught to new users -> at any level? +## How we teach this -> How should this feature be introduced and taught to existing Ember -> users? +Since this RFC is primarily concerned with the implementation details of the blueprints themselves, I'm not sure that we'd necessarily _need_ to teach this. That said, I imagine that we would eventually include TypeScript in the documentation for creating custom blueprints as support for TypeScript in Ember rolls out. Since this RFC is not concerned with shipping a TypeScript _compiler_ as a built-in component of new Ember apps or addons, we wouldn't actually roll out any new functionality as a result of this RFC, and thus I don't think there'd be anything to teach (yet). ## Drawbacks -> Why should we _not_ do this? Please consider the impact on teaching Ember, -> on the integration of this feature with other existing and planned features, -> on the impact of the API churn on existing apps, etc. +There should be little to no impact on the end-user as a result of the changes proposed in the RFC. The one drawback worth mentioning is that this change does introduce additional memory and performance overhead as a result of running the files through Babel transforms when converting from TypeScript to JavaScript. -> There are tradeoffs to choosing any path, please attempt to identify them here. +That said, Ember (and most of the front-end world) already relies heavily on Babel, so this change would simply be extending a dependency that already exists. Furthermore, while there _is_ a cost to running a Babel transform as part of a generator, it will be extremely trivial given that generators only ever create a handful of files at a time, and a newly-generated Ember app runs _far_ more files through many more Babel transforms without issue. Finally, we'd be running the transform on the in-memory version of the file, so there'd be no additional I/O cost incurred. ## Alternatives -> What other designs have been considered? What is the impact of not doing this? - -> This section could also include prior art, that is, how other frameworks in the same domain have solved this problem. +We could continue to maintain a wholly independent set of blueprint files, a la [`ember-cli-typescript-blueprints`](https://github.com/typed-ember/ember-cli-typescript-blueprints). However, this would leave us with the same challenges that exist today, and would also make it harder to provide official support for TypeScript in Ember itself. ## Unresolved questions From 7c056a0327026384bd72654c68ed6e0dc26e23e7 Mon Sep 17 00:00:00 2001 From: Chris Freeman Date: Mon, 15 Nov 2021 14:08:10 -0700 Subject: [PATCH 03/10] feedback --- text/0000-typescript-blueprints.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/text/0000-typescript-blueprints.md b/text/0000-typescript-blueprints.md index 7bc8f5ec15..02f9e27848 100644 --- a/text/0000-typescript-blueprints.md +++ b/text/0000-typescript-blueprints.md @@ -28,11 +28,12 @@ RFC PR: Fill this in with the URL for the Proposal RFC PR ## Motivation -Ember CLI's generators are a foundational part of Ember itself. They are one of the first elements of the developer experience that Ember prides itself on, and continue to be an essential part of the ecosystem by virtue of the fact that both apps and addons can generate their own custom blueprints. For many years, the `ember-cli-typescript` addon has shipped its own set of TypeScript-flavored built-in blueprints that essentially act as drop-in replacement for the built-in blueprints that ship with Ember today. However, these blueprints have proven very difficult to maintain as it involves keeping them all up to date with every single change made to Ember itself, so much so that the current TypeScript blueprints have diverged to the point there is currently not a TypeScript blueprint for components at all. +Ember CLI's generators are a foundational part of Ember itself. They are one of the first elements of the developer experience that Ember prides itself on, and continue to be an essential part of the ecosystem by virtue of the fact that both apps and addons can generate their own custom blueprints. For many years, the `ember-cli-typescript` addon has provided its own set of TypeScript-flavored built-in blueprints that essentially act as drop-in replacement for the built-in blueprints that provide with Ember today. However, these blueprints have proven very difficult to maintain as it involves keeping them all up to date with every single change made to Ember itself, so much so that the current TypeScript blueprints have diverged to the point there is currently not a TypeScript blueprint for components at all. -As part of the larger effort to [make Typescript an officially supported language in Ember](https://github.com/emberjs/rfcs/pull/724), we should ship TypeScript blueprints in Ember itself, in place of the existing Javascript blueprints. This would provide several benefits over the current system: +As part of the larger effort to [make Typescript an officially supported language in Ember](https://github.com/emberjs/rfcs/pull/724), Ember should provide a single set of blueprints that will support both JavaScript and TypeScript. These new blueprints would be written in TypeScript, and would provide exactly the same JavaScript experience that today's users enjoy, while also providing several benefits over the current system: -1. Remove the disconnect between TypeScript and JavaScript blueprints discussed above, as the `ember-cli-typescript` team would no longer be responsible for maintaining an entirely independent set of blueprints. +1. Remove the disconnect between TypeScript and JavaScript blueprints discussed above, as the Typed Ember team would no longer be responsible for maintaining an entirely independent set of blueprints. +1. Allow for multiple versions of TypeScript blueprints to exist (since they'd belong to each version of Ember), rather than today where there is no way to tie standalone TypeScript blueprints to individual versions of Ember (e.g. there's no LTS version of the TypeScript blueprints today). 1. Pave the way for TypeScript blueprint generation in any Ember app or addon right out of the box (likely via a `--typescript` flag or something similar). 1. Enable addon authors to better support TypeScript users by allowing them to publish their own TypeScript blueprints without concern for also supporting JavaScript users. @@ -40,22 +41,24 @@ Note that this does **not** mean that we should generate TypeScript by default, ## Detailed design -tl;dr: Blueprints will be handled exactly the same as before, with the one exception that any blueprint file ending in `.ts` will be run through Babel's [`@babel/plugin-transform-typescript`](https://babeljs.io/docs/en/babel-plugin-transform-typescript) to strip out all the TypeScript syntax. Please read on for a more detailed explanation. +tl;dr: Blueprints will be handled exactly the same as before, with the one exception that any blueprint file written in TypeScript will be run through Babel's [`@babel/plugin-transform-typescript`](https://babeljs.io/docs/en/babel-plugin-transform-typescript) to strip out all the TypeScript syntax unless the user actually wants TypeScript output. Please read on for a more detailed explanation. In the current generator system, new files are created from templates that resides in the `files` directory of the blueprint that corresponds to generator that was invoked. When a user runs `ember generate service foo`, Ember CLI will locate the template at `blueprints/service/files/__root__/__path__/__name__.js`, load it into memory, perform a text replacement on all of the EJS-style tags (e.g. `class <%= classifiedModuleName => extends Service` becomes `class Foo extends Service`), and then writes the entire string out to a file at the correct path inside the parent app or addon. Notably, there is no evaluation of the code itself, as the entire process of blueprint generation is simple text replacement. In the new version of Ember's blueprint system, this template would instead be named `__name__.ts`. The generator process would run identically (locate the template, read into memory, perform text replacement) up until it is actually time to _write_ the file. Before that occurs, the (now fully populated) in-memory version of the newly generated file would be run through Babel's [`@babel/plugin-transform-typescript`](https://babeljs.io/docs/en/babel-plugin-transform-typescript). This would strip the file of all TypeScript-related syntax, resulting in a completely valid JavaScript file with no evidence that it had begun as TypeScript file. In this way, we're able to ensure that the built-in generators would continue to perform as exactly as they have previously. +Furthermore, blueprints would have to explicitly opt-in to this behavior by adding a `shouldTransformTypeScript: true` flag to the blueprint's `index.js` file. This will make the automatic TypeScript transform behavior purely opt-in, thereby preventing any conflicts with existing projects that may already have their own custom TypeScript blueprints. + There are a few details worth calling out about this change to the generation process: 1. While the TypeScript files are parsed and transformed, they are _not_ type-checked in any way. The Babel plugin is concerned solely with the transformation of TypeScript syntax into JavaScript syntax and does not pay any attention to what the types actually are. This is a good thing, as it minimizes any performance cost during the generation process and we'd expect any actual type-checking to happen at compilation time in the user's app, using their own `tsconfig` rather than one we'd have to supply (and maintain). 1. By default, the generators would behave exactly as they did before, however, the fact that all the blueprints are now written in TypeScript means that it becomes trivial to add a `--typescript` flag to the `generate` command that tells the generator to simply bypass the Babel transform and instead output TypeScript directly. Since TypeScript is a superset of JavaScript, we're able to easily accomodate both sets of users with a single blueprint file by starting out with the "higher-fidelity" TypeScript and down-leveling it JavaScript when needed. -1. Addon authors would be able to ship blueprints written in TypeScript that would "just work" in the same way that the built-in blueprints would, e.g. they'd get support for both JavaScript and TypeScript versions of their blueprints with no additional effort or maintenance. +1. Addon authors would be able to provide blueprints written in TypeScript that would "just work" in the same way that the built-in blueprints would, e.g. they'd get support for both JavaScript and TypeScript versions of their blueprints with no additional effort or maintenance. 1. No one is _required_ to write their blueprints in TypeScript. Any blueprint written in JavaScript would be handled in the exact same way that they are today. ## How we teach this -Since this RFC is primarily concerned with the implementation details of the blueprints themselves, I'm not sure that we'd necessarily _need_ to teach this. That said, I imagine that we would eventually include TypeScript in the documentation for creating custom blueprints as support for TypeScript in Ember rolls out. Since this RFC is not concerned with shipping a TypeScript _compiler_ as a built-in component of new Ember apps or addons, we wouldn't actually roll out any new functionality as a result of this RFC, and thus I don't think there'd be anything to teach (yet). +Since this RFC is primarily concerned with the implementation details of the blueprints themselves, I'm not sure that we'd necessarily _need_ to teach this. That said, I imagine that we would eventually include TypeScript in the documentation for creating custom blueprints as support for TypeScript in Ember rolls out. Since this RFC is not concerned with providing a TypeScript _compiler_ as a built-in component of new Ember apps or addons, we wouldn't actually roll out any new functionality as a result of this RFC, and thus I don't think there'd be anything to teach (yet). ## Drawbacks From 896004d7f1e773c3c3f01f9ff08f051d1480ff8c Mon Sep 17 00:00:00 2001 From: Chris Freeman Date: Tue, 16 Nov 2021 12:29:11 -0700 Subject: [PATCH 04/10] .ember-cli changes --- text/0000-typescript-blueprints.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0000-typescript-blueprints.md b/text/0000-typescript-blueprints.md index 02f9e27848..11e95fca5e 100644 --- a/text/0000-typescript-blueprints.md +++ b/text/0000-typescript-blueprints.md @@ -49,6 +49,8 @@ In the new version of Ember's blueprint system, this template would instead be n Furthermore, blueprints would have to explicitly opt-in to this behavior by adding a `shouldTransformTypeScript: true` flag to the blueprint's `index.js` file. This will make the automatic TypeScript transform behavior purely opt-in, thereby preventing any conflicts with existing projects that may already have their own custom TypeScript blueprints. +In addition to the per-blueprint flag, there will also be a new `isTypeScriptProject` flag added to `.ember-cli` that will allow users to mark an entire Ember app or addon as a TypeScript-first project. The presence of this flag would indicate that blueprints should output TypeScript by default, rather than JavaScript as they normally would. Flags specified in `.ember-cli` are automatically merged into the blueprint options when invoked, so this flag would be readily accessible to all blueprints. We'd also add a step to the `init` hook for `ember-cli-typescript` that would check for the presence of this flag in `.ember-cli` and warn if it's not set. In the future, we'd be able to set this flag as part of a `ember new --typescript` flag. + There are a few details worth calling out about this change to the generation process: 1. While the TypeScript files are parsed and transformed, they are _not_ type-checked in any way. The Babel plugin is concerned solely with the transformation of TypeScript syntax into JavaScript syntax and does not pay any attention to what the types actually are. This is a good thing, as it minimizes any performance cost during the generation process and we'd expect any actual type-checking to happen at compilation time in the user's app, using their own `tsconfig` rather than one we'd have to supply (and maintain). From de9284e239352760278ff38e51daa5bf0aa59737 Mon Sep 17 00:00:00 2001 From: Chris Freeman Date: Tue, 16 Nov 2021 14:24:45 -0700 Subject: [PATCH 05/10] summary --- text/0000-typescript-blueprints.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-typescript-blueprints.md b/text/0000-typescript-blueprints.md index 11e95fca5e..0dc1245778 100644 --- a/text/0000-typescript-blueprints.md +++ b/text/0000-typescript-blueprints.md @@ -24,7 +24,7 @@ RFC PR: Fill this in with the URL for the Proposal RFC PR ## Summary -> One paragraph explanation of the feature. +In order to support both TypeScript and JavaScript as official languages in Ember, we should enable blueprints to be written in TypeScript and (optionally) transformed to JavaScript. We should also convert all of the existing built-in blueprints to TypeScript to take advantage of this new functionality and lay the groundwork for future TypeScript inclusion efforts. ## Motivation From 336b7462dc810c9943d6c2958c777c43fa6f2a2d Mon Sep 17 00:00:00 2001 From: Chris Freeman Date: Tue, 16 Nov 2021 14:38:31 -0700 Subject: [PATCH 06/10] mention future testing --- text/0000-typescript-blueprints.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0000-typescript-blueprints.md b/text/0000-typescript-blueprints.md index 0dc1245778..5fb58f3a50 100644 --- a/text/0000-typescript-blueprints.md +++ b/text/0000-typescript-blueprints.md @@ -54,6 +54,7 @@ In addition to the per-blueprint flag, there will also be a new `isTypeScriptPro There are a few details worth calling out about this change to the generation process: 1. While the TypeScript files are parsed and transformed, they are _not_ type-checked in any way. The Babel plugin is concerned solely with the transformation of TypeScript syntax into JavaScript syntax and does not pay any attention to what the types actually are. This is a good thing, as it minimizes any performance cost during the generation process and we'd expect any actual type-checking to happen at compilation time in the user's app, using their own `tsconfig` rather than one we'd have to supply (and maintain). + 1. In the future, we DO also need the ability to test the actual TypeScript parts of the blueprints (i.e. do the blueprints output TS files that actually type-check?), but that functionality will be covered in a later RFC that is more concerned with enabling TypeScript support in Ember. 1. By default, the generators would behave exactly as they did before, however, the fact that all the blueprints are now written in TypeScript means that it becomes trivial to add a `--typescript` flag to the `generate` command that tells the generator to simply bypass the Babel transform and instead output TypeScript directly. Since TypeScript is a superset of JavaScript, we're able to easily accomodate both sets of users with a single blueprint file by starting out with the "higher-fidelity" TypeScript and down-leveling it JavaScript when needed. 1. Addon authors would be able to provide blueprints written in TypeScript that would "just work" in the same way that the built-in blueprints would, e.g. they'd get support for both JavaScript and TypeScript versions of their blueprints with no additional effort or maintenance. 1. No one is _required_ to write their blueprints in TypeScript. Any blueprint written in JavaScript would be handled in the exact same way that they are today. From d39c719e6ba02b3823595185d7a3bef3e8cc5afc Mon Sep 17 00:00:00 2001 From: Chris Freeman Date: Tue, 16 Nov 2021 15:07:16 -0700 Subject: [PATCH 07/10] fix typos, thanks heroiceric --- text/0000-typescript-blueprints.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-typescript-blueprints.md b/text/0000-typescript-blueprints.md index 5fb58f3a50..1096fe09f1 100644 --- a/text/0000-typescript-blueprints.md +++ b/text/0000-typescript-blueprints.md @@ -37,13 +37,13 @@ As part of the larger effort to [make Typescript an officially supported languag 1. Pave the way for TypeScript blueprint generation in any Ember app or addon right out of the box (likely via a `--typescript` flag or something similar). 1. Enable addon authors to better support TypeScript users by allowing them to publish their own TypeScript blueprints without concern for also supporting JavaScript users. -Note that this does **not** mean that we should generate TypeScript by default, but rather that the blueprints themselves should _begin_ as TypeScript before actually being reified as actual code. By default, all of the Ember generators would still behave exactly as they do today: by generating Javascript files. This RFC is primarily concerned with TypeScript as an _implementation detail_ for the existing blueprints, rather than being prescriptive about whether or not users should adopt TypeScript themselves. +Note that this does **not** mean that we should generate TypeScript by default, but rather that the blueprints themselves should _begin_ as TypeScript before actually being reified as actual code. By default, all of the Ember generators would still behave exactly as they do today: by generating JavaScript files. This RFC is primarily concerned with TypeScript as an _implementation detail_ for the existing blueprints, rather than being prescriptive about whether or not users should adopt TypeScript themselves. ## Detailed design tl;dr: Blueprints will be handled exactly the same as before, with the one exception that any blueprint file written in TypeScript will be run through Babel's [`@babel/plugin-transform-typescript`](https://babeljs.io/docs/en/babel-plugin-transform-typescript) to strip out all the TypeScript syntax unless the user actually wants TypeScript output. Please read on for a more detailed explanation. -In the current generator system, new files are created from templates that resides in the `files` directory of the blueprint that corresponds to generator that was invoked. When a user runs `ember generate service foo`, Ember CLI will locate the template at `blueprints/service/files/__root__/__path__/__name__.js`, load it into memory, perform a text replacement on all of the EJS-style tags (e.g. `class <%= classifiedModuleName => extends Service` becomes `class Foo extends Service`), and then writes the entire string out to a file at the correct path inside the parent app or addon. Notably, there is no evaluation of the code itself, as the entire process of blueprint generation is simple text replacement. +In the current generator system, new files are created from templates that reside in the `files` directory of the blueprint that corresponds to the generator that was invoked. When a user runs `ember generate service foo`, Ember CLI will locate the template at `blueprints/service/files/__root__/__path__/__name__.js`, load it into memory, perform a text replacement on all of the EJS-style tags (e.g. `class <%= classifiedModuleName => extends Service` becomes `class Foo extends Service`), and then writes the entire string out to a file at the correct path inside the parent app or addon. Notably, there is no evaluation of the code itself, as the entire process of blueprint generation is simple text replacement. In the new version of Ember's blueprint system, this template would instead be named `__name__.ts`. The generator process would run identically (locate the template, read into memory, perform text replacement) up until it is actually time to _write_ the file. Before that occurs, the (now fully populated) in-memory version of the newly generated file would be run through Babel's [`@babel/plugin-transform-typescript`](https://babeljs.io/docs/en/babel-plugin-transform-typescript). This would strip the file of all TypeScript-related syntax, resulting in a completely valid JavaScript file with no evidence that it had begun as TypeScript file. In this way, we're able to ensure that the built-in generators would continue to perform as exactly as they have previously. From a7b844530012ecddec87f722fc087600f68ec916 Mon Sep 17 00:00:00 2001 From: Chris Freeman Date: Tue, 16 Nov 2021 15:25:21 -0700 Subject: [PATCH 08/10] add PR number --- ...0-typescript-blueprints.md => 0776-typescript-blueprints.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename text/{0000-typescript-blueprints.md => 0776-typescript-blueprints.md} (99%) diff --git a/text/0000-typescript-blueprints.md b/text/0776-typescript-blueprints.md similarity index 99% rename from text/0000-typescript-blueprints.md rename to text/0776-typescript-blueprints.md index 1096fe09f1..9931b68f9c 100644 --- a/text/0000-typescript-blueprints.md +++ b/text/0776-typescript-blueprints.md @@ -6,7 +6,7 @@ Release Versions: ember-source: vX.Y.Z ember-data: vX.Y.Z Relevant Team(s): Ember CLI -RFC PR: +RFC PR: https://github.com/emberjs/rfcs/pull/776 ---