diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 36ded6d2cd..6cd2c78254 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -14,7 +14,7 @@ and choosing `View file' from the `...' menu in the right hand corner of the fil This pull request is proposing a new RFC. -To succeed, it will need to pass into the [Exploring Stage](https://github.com/emberjs/rfcs#exploring)), followed by the [Accepted Stage](https://github.com/emberjs/rfcs#accepted). +To succeed, it will need to pass into the [Exploring Stage](https://github.com/emberjs/rfcs#exploring), followed by the [Accepted Stage](https://github.com/emberjs/rfcs#accepted). A Proposed or Exploring RFC may also move to the [Closed Stage](https://github.com/emberjs/rfcs#closed) if it is withdrawn by the author or if it is rejected by the Ember team. This requires an "FCP to Close" period. diff --git a/text/0389-dynamic-tag-names.md b/text/0389-dynamic-tag-names.md index 57d56f1d79..55f6ec7151 100644 --- a/text/0389-dynamic-tag-names.md +++ b/text/0389-dynamic-tag-names.md @@ -1,5 +1,5 @@ --- -stage: recommended +stage: accepted start-date: 2018-10-14T00:00:00.000Z release-date: # FIXME release-versions: # FIXME diff --git a/text/0740-ember-data-deprecate-non-strict-relationships.md b/text/0740-ember-data-deprecate-non-strict-relationships.md index ac664200cb..ed27252589 100644 --- a/text/0740-ember-data-deprecate-non-strict-relationships.md +++ b/text/0740-ember-data-deprecate-non-strict-relationships.md @@ -1,5 +1,5 @@ --- -stage: released +stage: recommended start-date: 2021-04-23T00:00:00.000Z release-date: 2023-09-19T00:00:00.000Z release-versions: @@ -10,6 +10,7 @@ prs: accepted: 'https://github.com/emberjs/rfcs/pull/740' ready-for-release: 'https://github.com/emberjs/rfcs/pull/910' released: 'https://github.com/emberjs/rfcs/pull/967' + recommended: 'https://github.com/emberjs/rfcs/pull/972' project-link: --- diff --git a/text/0743-ember-data-deprecate-legacy-imports.md b/text/0743-ember-data-deprecate-legacy-imports.md index 74ed18d392..27a7372a8d 100644 --- a/text/0743-ember-data-deprecate-legacy-imports.md +++ b/text/0743-ember-data-deprecate-legacy-imports.md @@ -1,5 +1,5 @@ --- -stage: released +stage: recommended start-date: 2021-04-23T00:00:00.000Z release-date: 2023-09-18T00:00:00.000Z release-versions: @@ -10,6 +10,7 @@ prs: accepted: 'https://github.com/emberjs/rfcs/pull/743' ready-for-release: 'https://github.com/emberjs/rfcs/pull/947' released: 'https://github.com/emberjs/rfcs/pull/969' + recommended: 'https://github.com/emberjs/rfcs/pull/979' --- # EmberData | Deprecate Legacy Imports diff --git a/text/0779-first-class-component-templates.md b/text/0779-first-class-component-templates.md index d86a727e04..06a88ac1ce 100644 --- a/text/0779-first-class-component-templates.md +++ b/text/0779-first-class-component-templates.md @@ -1,14 +1,18 @@ --- -stage: accepted +stage: released start-date: 2021-12-03T00:00:00.000Z release-date: release-versions: + ember-template-imports: 4.0.0 + ember-source: 3.28.0 teams: - framework - learning - cli prs: - accepted: https://github.com/emberjs/rfcs/pull/779 + accepted: 'https://github.com/emberjs/rfcs/pull/779' + ready-for-release: 'https://github.com/emberjs/rfcs/pull/871' + released: 'https://github.com/emberjs/rfcs/pull/1050' project-link: --- diff --git a/text/0812-tracked-built-ins.md b/text/0812-tracked-built-ins.md index 5213b8e707..faeb3cac53 100644 --- a/text/0812-tracked-built-ins.md +++ b/text/0812-tracked-built-ins.md @@ -1,5 +1,5 @@ --- -stage: released +stage: recommended start-date: 2022-03-29T00:00:00.000Z release-date: 2023-01-21T00:00:00.000Z release-versions: @@ -11,6 +11,7 @@ prs: accepted: 'https://github.com/emberjs/rfcs/pull/812' ready-for-release: 'https://github.com/emberjs/rfcs/pull/886' released: 'https://github.com/emberjs/rfcs/pull/937' + recommended: 'https://github.com/emberjs/rfcs/pull/943' project-link: --- diff --git a/text/0830-evolving-embers-major-version-process.md b/text/0830-evolving-embers-major-version-process.md index be7cc0d2ad..2243495d81 100644 --- a/text/0830-evolving-embers-major-version-process.md +++ b/text/0830-evolving-embers-major-version-process.md @@ -1,15 +1,18 @@ --- -stage: accepted +stage: released start-date: 2022-07-12T00:00:00.000Z release-date: release-versions: + ember-source: 6.0.0 + ember-cli: 6.0.0 teams: - steering - framework - learning prs: - accepted: https://github.com/emberjs/rfcs/pull/830 - + accepted: 'https://github.com/emberjs/rfcs/pull/830' + ready-for-release: 'https://github.com/emberjs/rfcs/pull/878' + released: 'https://github.com/emberjs/rfcs/pull/1057' --- # Evolving Ember's Major Version Process diff --git a/text/0848-deprecate-array-prototype-extensions.md b/text/0848-deprecate-array-prototype-extensions.md index 08f75c1925..9ef0c9ac83 100644 --- a/text/0848-deprecate-array-prototype-extensions.md +++ b/text/0848-deprecate-array-prototype-extensions.md @@ -1,5 +1,5 @@ --- -stage: released +stage: recommended start-date: 2022-08-21T00:00:00.000Z release-date: release-versions: @@ -10,6 +10,7 @@ prs: accepted: 'https://github.com/emberjs/rfcs/pull/848' ready-for-release: 'https://github.com/emberjs/rfcs/pull/1020' released: 'https://github.com/emberjs/rfcs/pull/1042' + recommended: 'https://github.com/emberjs/rfcs/pull/1043' project-link: --- diff --git a/text/0977-v2-app-format.md b/text/0977-v2-app-format.md new file mode 100644 index 0000000000..d865c35ad2 --- /dev/null +++ b/text/0977-v2-app-format.md @@ -0,0 +1,379 @@ +--- +stage: accepted +start-date: 2023-10-06 +release-date: # In format YYYY-MM-DDT00:00:00.000Z +release-versions: +teams: # delete teams that aren't relevant + - cli + - data + - framework + - learning +prs: + accepted: https://github.com/emberjs/rfcs/pull/977 +project-link: +suite: +--- + + + +# v2 App Format + +## Summary + +This RFC defines a new app format, +building off the prior work in [v2 Addon format](https://rfcs.emberjs.com/id/0507-embroider-v2-package-format), +and is designed to make Ember apps more compatible with the rest of the JavaScript ecosystem. This RFC will define conventions of the app and clearly identify functionality that is considered "compatibility integrations" and could be considered optional in the near future. + +## Motivation + +When ember-cli was created there was no existing JS tooling that met the needs of the Ember Framework. Over the years we have added more and more developer-friendly conventions to our build system that many Ember applications and addons depend on. As the wider JavaScript tooling story has evolved over the years Ember has fallen behind, this is mainly because our custom-built tools have not been keeping up with the wider community and we haven’t been able to directly use any more advanced tooling in our apps. Efforts have been started to improve the situation with the advent of [Embroider](https://github.com/embroider-build/embroider) but the current stable release of Embroider still runs inside ember-cli and is somewhat bound in terms of performance and capability by the underlying technology [broccolijs](https://github.com/broccolijs/broccoli) and some other architectural decisions. + +Over the past year the Ember Core Tooling team have been working hard to invert the control between bundlers and ember-cli, which means that instead of ember-cli running a bundler (such as Webpack in the current Embroider stable version) as part of its build system the whole Ember build process will essentially become a plugin to the bundler. This means that we can more effectively make use of bundler innovations, performance improvements, and we are more capable of adapting to whatever next generation of build systems come to the Javascript ecosystem. + +With the Ember build system as a plugin to bundlers we have the ability to only intervene on things that are Emberisims (i.e. not-standard) and as we work to make Ember more standard we can eventually turn off these ”compatibility plugins”. Compatibility plugins will need to be powered by an “ember prebuild” that collects information about your app and addons and output metadata that the bundler plugins will consume. The intention is that this prebuild will be done automatically for you as part of the bundler plugin setup and you should not have to worry about preforming extra steps. + +This RFC is not going to describe a new blueprint where you don't need any compatibility plugins (or an ember prebuild) to run an Ember app, this RFC instead is going to propose a new blueprint that has all the compatibility plugins turned on so that it is easiest for most people to upgrade to. Any discussion about a minimal “compatibility-free” blueprint should happen in a later RFC. + +## Key Ideas + +Much like the [v2 Addon format RFC](https://rfcs.emberjs.com/id/0507-embroider-v2-package-format#key-ideas) we want the new app blueprint to rely on ES Modules and not leave anything hidden or automatic. This not only makes it easier for developers to know where things are coming from, it also makes it easier for bundlers to know what to do with Ember applications. + +Each of the following sections go into detail of all the changes between the current blueprint and the new proposal which is currently being developed at https://github.com/embroider-build/app-blueprint + +### Focus on Vite + +The new app blueprint will default to using Vite to power local development and build for production. Vite has been on a meteoric rise in popularity over the past few years, and it represents the state of the art when it comes to Developer Ergonomics. Standardising on such a popular build system will bring the Ember community a lot of benefits but the key areas of improvement that we expect developers to experience are: + +- significantly improved rebuild speeds during local development +- the ability to use "standard" vite plugins with your Ember apps +- significant improvements to debugability of your code in development because Vite serves ES Modules directly to your browser in development + +### Removal of requirejs support + +The default build system that will be used in this new blueprint will be Vite and for the most part Vite requires that your app is described in terms of ES Modules. The default build from `ember-cli` would express all of your modules using AMD and requirejs `define()` statements. There is an open RFC for [Strict ES Module Support](https://github.com/emberjs/rfcs/pull/938) that removes Ember's reliance on AMD to define modules and that RFC would be a requirement for this one i.e. when building with Vite you essentially have no requirejs module support. This means that any addon or application that interacts with requirejs would need to be updated for people to upgrade to this new blueprint. + +### Top level await added + +Since we are now using ES Modules througout the whole application it now becomes possible to use [top-level-await](https://v8.dev/features/top-level-await) in the module-scope of any of your files. This opens up a lot of possibilities for Ember developers and is a great example of how adopting standards helps to bring improvements from the wider ecosystem to Ember developers. + +## Detailed design + +In this section I'm going to go through each of the changes in the new proposed blueprint, in each section I will do my best to explain the reasoning for why it needs to be like this but if you have any questions or comments please feel free to comment on the RFC and we will try to update that section. + +### Entrypoint -> index.html + +A lot of modern bundlers make use of your index.html file as the main entrypoint to kick off bundling. Any files that are referenced in your index.html would then end up getting bundled. + +This already an issue for an Ember app because the index.html that is traditionally found at `app/index.html` is ultimately not used directly. Information in the index.html file is used to generate the real file that is used at the end of the pipeline. + +This new blueprint proposes to remove this oddity and both allow bundlers to look directly at the source index.html instead of the output build artifact and will remove almost all ember build customisations that targed the index.html. We still intend to support `{{content-for}}` entries in the index.html with a few caveats that I will explain in more detail in the next section, but the support for `{{content-for}}` will need to be provided by a bundler plugin that has the ability to replace content in the index.html. + +The index.html will also have an inline script tag that performs the application boot. This process used to be hidden away in a `{{content-for “app-boot”}}` section in one of the javascript files automatically added to the index.html during the build pipeline. This explicit inline application boot significantly improves the visibility of how the application actually boots and should allow developers to customise that process without our build system needing to provide a way to handle those customisations. Incidently this now means that if you are using an addon to customise the `{{content-for “app-boot”}}` then this will no longer work. If Embroider discovers that an app is trying to customise the app-boot in any way it will throw this error: + +> Your app uses at least one classic addon that provides content-for 'app-boot'. This is no longer supported. +> +> With Embroider, you have full control over the app-boot script, so classic addons no longer need to modify it under the hood. +> +> The following code is used for your app boot: +> +> {{inline-custom-app-boot-code}} +> +> 1. If you want to keep the same behavior, copy and paste it to the app-boot script included in app/index.html. +> 2. Once app/index.html has the content you need, remove the present error by setting "useAddonAppBoot" to false in the build options. + +The embedded boot section in the index.html will look like the following: + +``` + +``` + +This boot section touches app/app.js and the new app/config/environment.js files which are both described in sections below. + +#### content-for in index.html + +The way that `{{content-for}}` works in ember-cli currently is under-specified and cronically under documented. The highest level summary is that anyone can currently add `{{content—for “any-string“}}` and as long as any active ember-addon provided a value for that specific content-for section the exact string that the addon provided would be injected at that point in the document. While we are familiar with sections like `{{content-for “head”}}` there is no pre-defined list and the common sections are only common due to convention. This makes it **extremely** hard for a modern build system that doesn’t understand ember-addons to be able to know what to do with these sections. + +We are proposing that we codify the conventional sections as the default set, and the ember prebuild will be able to collate the text each addon wants to add to these sections + +- head +- test-head +- head-footer +- test-head-footer +- body +- test-body +- body-footer +- test-body-footer +- config-module +- app-boot + +If you are using any other custom `{{content-for}}` section then you will need to explicitly pass this to your embroider config via a `availableContentForTypes` configuration + +### App Entrypoint -> app/app.js + +In a classic build ember-cli would collect all the of the modules in your app into an entrypoint in the build that would go through and define each of the modules in the require.js AMD registry. There is already an [RFC that describes the fact that we want to deprecate this AMD registry](https://github.com/emberjs/rfcs/blob/strict-es-module-support/text/0938-strict-es-module-support.md), but the key thing for this RFC is that we are trying to think of our app as series of real ES Modules we need to provide some way for the built-in discovery of these modules that allows Ember to still resolve those modules by name (for Dependency Injection concerns like services) + +We are providing this with the virtual module `'@embroider/virtual/compat-modules';`. This means that any bundler plugin that wants to support Ember needs to be able to support virtual module imports. The contents of this file can be obtained by asking the Embroider resolver which collates the list of modules during the Ember prebuild. + +We then pass the list of modules to an updated version of the Ember Resolver (that has already been released) which means that the Ember Resolver no longer needs to rely on requirejs.entries to find all of the parts of your application. This set of compat modules also needs to be passed into the `loadInitializers()` from `ember-load-initializers` so that doesn't use AMD for initalizer discovery either. Here is an example of the difference in the `app/app.js` file: + +```diff + import Application from '@ember/application'; ++import compatModules from '@embroider/virtual/compat-modules'; + import Resolver from 'ember-resolver'; + import loadInitializers from 'ember-load-initializers'; + import config from 'current-blueprint/config/environment'; + + export default class App extends Application { + modulePrefix = config.modulePrefix; + podModulePrefix = config.podModulePrefix; +- Resolver = Resolver; ++ Resolver = Resolver.withModules(compatModules); + } + +-loadInitializers(App, config.modulePrefix); ++loadInitializers(App, config.modulePrefix, compatModules); +``` + +One very important thing to note is that because we're moving from AMD to real ESM modules we now have a timing change for any code that is executing in the module scope, this code will now be executed eagerly and will not wait until the module is actually consumed by your app. This change happens because AMD inherently lazily executes module code only when that module is consumed, and ES modules are inherently a static graph of modules. + +For the most part this change should not affect many people and most of the problems that we noticed related to this change came from addons that had code that had errors in it but was never cleaned up. It was never noticed before because the code was not being exercised by tests or consumers of the addons so most of the time the fix was to just delete the previously inert code. + +### Application Config -> app/config/environment.js and config/environment.js + +In a Classic build ember-cli automatically generated a module `app/config/environment.js` in your application build pipeline that is customisable with the config `storeConfigInMeta`. If `storeConfigInMeta` is true (which is the default) then the contents of this module will look for a `` tag in your html and parse out the your previously serialised config object and return the value as the default export from the module. This is what people recieve when they import from `app-name/config/environment`. + +This is another example of an Ember-specific complexity in the build system that can be confusing for other build systems. In the new blueprint we propose making the `app/config/environment.js` file exist in your source, and the contents will clearly be loading the config from meta: + +```js +import loadConfigFromMeta from '@embroider/config-meta-loader'; + +export default loadConfigFromMeta('app-name'); +``` + +The serialising of the config into the index.html is still being handled by `{{content-for 'head'}}` and is not going to change as a result of this RFC. + +One restriction in the new blueprint is that we don't have an automatic implementation for when `storeConfigInMeta` is set to `false`. Our reasoning is that if you have set this setting then you are likely doing something custom and you would need to update `app/config/environment.js` to reflect your custom setup. We don't need to provide any customisation here because this is a user-owned module and you can edit it as you please. + +### Test Entrypoint -> tests/index.html and tests/test-helper.js + +The `tests/index.html` will have the same treatment as the main `index.html` where the test boot code will now be exposed directly in an inline script so that test booting is not hidden deep in the build pipeline. + +```html + +``` + +To facilitate this new API the test-helper needs to be changed to essentially "wrap" its contents in a function that can be called rather than it running as a side effect of the import: + +```diff + import Application from 'current-blueprint/app'; + import config from 'current-blueprint/config/environment'; + import * as QUnit from 'qunit'; + import { setApplication } from '@ember/test-helpers'; + import { setup } from 'qunit-dom'; +-import { start } from 'ember-qunit'; ++import { start as qunitStart } from 'ember-qunit'; + ++export function start() { + setApplication(Application.create(config.APP)); + setup(QUnit.assert); + +-start(); ++qunitStart(); + ++} +``` + +This also allows us to load qunit, load all the test files, and then start qunit once all the tests are loaded. The loading of the test files is now also made explicit with the line: + +```js +import.meta.glob("./**/*.{js,gjs,gts}", { eager: true }); +``` + +`import.meta.glob` is described in detail in the [Introduce a Wildcard Module Import API RFC](https://rfcs.emberjs.com/id/0939-import-glob). It is natively supported in Vite but it would need to be implemented in any other build system that wants to support building an Ember app. + +### Explicit Babel Config -> babel.config.cjs + +In a classic build ember-cli-babel manages all configurations to babel in a way that is entirely hidden to the end-user. This is nice considering that users don't need to manage this file themselves, but it is also problematic because if anyone wants to customise their babel config they need to rely on extension points provided by both ember-cli and ember-cli-babel and in some cases those extension points may not even be available e.g. it is currently impossible for an app to configure an ast-transform for the ember-template-compiler and people workaround this issue by creating an in-repo addon that does this configuration for them. + +In the new blueprint we will have an explicit `babel.config.cjs` that will come pre-configured with all the babel-plugins that ember-cli-babel would have configured for you. + +Here is the full contents of the proposed babel file: + +```js +const { + babelCompatSupport, + templateCompatSupport, +} = require('@embroider/compat/babel'); + +module.exports = { + plugins: [ + [ + 'babel-plugin-ember-template-compilation', + { + compilerPath: 'ember-source/dist/ember-template-compiler.js', + enableLegacyModules: [ + 'ember-cli-htmlbars', + 'ember-cli-htmlbars-inline-precompile', + 'htmlbars-inline-precompile', + ], + transforms: [...templateCompatSupport()], + }, + ], + [ + 'module:decorator-transforms', + { + runtime: { + import: require.resolve('decorator-transforms/runtime-esm'), + }, + }, + ], + [ + '@babel/plugin-transform-runtime', + { + absoluteRuntime: __dirname, + useESModules: true, + regenerator: false, + }, + ], + ...babelCompatSupport(), + ], + + generatorOpts: { + compact: false, + }, +}; +``` + +You can see that there are two functions being imported from `@embroider/compat/babel`: `babelCompatSupport()` and `templateCompatSupport()`. This collects any extra babel config that is provided by any installed v1 ember-addon and makes sure that it still works with this new config. When an app no longer has any v1 ember-addons these functions can be removed but we will likely be leaving them in the default blueprint for the foreseeable future because they cost nothing if they are not being used. + +For people who are familiar with Babel config files you may have noticed that we have not included `@babel/preset-env` in this config. While our browser support has classically been handled by babel and `@babel/preset-env`, Vite has a config option [`build.target`](https://vite.dev/config/build-options#build-target) that controls what browsers you would like to down-compile your code for. This `build.target` config is passed to esbuild which is ultimately in charge of making sure your code runs in your stated targets i.e. in your `config/targets` file. While we are still going to read your `config/targets` file and pass that to the `build.target` config, it's worth noting that esbuild does not support the same range of browsers that `@babel/preset-env` does. This isn't a problem for the default blueprint because it supports all browsers that are part of Ember's official support matrix. We also don't see this as a blocker for adoption of this new blueprint because any applications that have a wider browser support matrix than Vite's `build.target` can provide can just manually configure `@babel/preset-env` in their babel config, now that it's significantly easier to edit your babel config. + +### Ember Pre-Build Config -> ember-cli-build.js + +To enable the current stable version of embroider you need to wrap your Ember Application defined in `ember-cli-build.js` in a `compatBuild()` function. The `compatBuild()` function takes a plugin that runs your bundler (i.e. Webpack) as part of the ember-cli pipeline and an optional config that allows you to turn on each of the "static flags" of embroider one-by-one. + +In the "Inversion of Control" version of the blueprint we intend to keep the same `compatBuild()` API but the job of the builder will be very different. Instead of Vite running as part of the ember-cli pipeline we are only running a prebuild that collects information about your application and its addons to make that available to the Embroider Vite plugin. When running directly in Vite the builder argument to `compatBuild()` will be inert and will do nothing. + +To continue to support commands like `ember build` or `ember test` we need some way for ember-cli to interact with Vite and allow Vite to build the application and run tests against the built output. Running `ember test` will essentially run Vite once (as a "one shot build" with no watching functionality) using the builder imported from `@embroider/vite` and then run `ember test --path {outdir}` where `{outdir}` will target the build output from Vite. This allows us to continue to support testem and any CI process that people have defined to use `ember build` without needing to update. Here is an example of an updated `ember-cli-build.js` file: + +```diff + const EmberApp = require('ember-cli/lib/broccoli/ember-app'); ++const { compatBuild } = require('@embroider/compat'); ++const { builder } = require('@embroider/vite'); + + module.exports = function (defaults) { + let app = new EmberApp(defaults, {}); +- return app.toTree(); ++ return compatBuild(app, builder, { /* optional Embroider options */ }); + }; +``` + +The other change that will happen in the next Embroider major release (and will be true for the new blueprint) is that the options passed to `compatBuild()` will have **all the static flags turned on by default**. + +Also some flags, like `staticEmberSource`, `staticAddonTrees`, and `staticAddonTestSuportTrees` are forced to be on and will throw an error if you try to set them to false. This error will give guidance wherever possible and link to relevant documentation. + +### Explicit Bundler Config -> vite.config.mjs + +If you are using the current stable release of Embroider then Embroider is generating a Webpack config for you automatically. It is possible for you to make some changes via config but the majority of the Webpack config file is hidden from you. + +This RFC proposes that we don't hide the bundler config any more, we will instead have a standard Vite config file that configures the required Embroider plugins. + +Here is the current version of the proposed vite config: + +```js +import { defineConfig } from 'vite'; +import { extensions, classicEmberSupport, ember } from '@embroider/vite'; +import { babel } from '@rollup/plugin-babel'; + +export default defineConfig({ + plugins: [ + classicEmberSupport(), + ember(), + // extra plugins here + babel({ + babelHelpers: 'runtime', + extensions, + }), + ], +}); +``` + +This config is defining 2 "compound plugins" that contain all the functionality needed for an Ember app to be built with Vite. We have split them into `classicEmberSupport()` and `ember()` to communicate that some of the plugins could be considered optional if you aren't using classic Ember features e.g. you have converted all your templates to GJS files. + +### Application metadata -> package.json + +In the [v2 Addon format RFC](https://rfcs.emberjs.com/id/0507-embroider-v2-package-format) we introduced the fact that the package.json `ember-addon` MetaData object should be versioned to identify which addons have been upgraded to the new spec. We will be reusing that concept for v2 apps by requiring the following section to be added to the package.json + +```json +{ + "ember-addon" { + "type": "app", + "version": 2 + } +} +``` + +This will opt Embroider into modern resolving rules so that it can interoperate properly with bundlers. + +### Exports -> package.json + +[Package Exports](https://webpack.js.org/guides/package-exports/) is an addition to the ESM resolving rules that all modern bundlers support. It allows you to configure paths that should be importable from ouside your package, as well as giving you a standard way to "redirect" imports that target your package. + +We already use these semantics in Ember applications when we expect `import SomeComponent from 'app-name/components/some-component'` to actually import the file path `/path/to/app-name/app/components/some-component.js`. In this example you can see that the `/app/` subpath has been added to the location. In ember-cli this semantic is handled in broccoli by actually rewriting paths, but this is one of the main reasons why tooling gets confused by our import paths because it's not using a standard method to define our import paths. + +The new blueprint will add the following exports section to the package.json by default: + +```json +{ + "./tests/*": "./tests/*", + "./*": "./app/*" +} +``` + +This essentially "redirects" all requests to modules in the `app` folder, with the exepction of any path that has `app-name/tests/` at the start. This means that importing your test helpers like `import superHelper from 'app-name/tests/helpers/super-helper'` won't try to import from the path `/path/to/app-name/app/tests/helpers/super-helper.js` + +## How we teach this + +All of the guides will need to be updated to make sure that we reference the build system correctly. We will also need to make sure that the system we use that automatically builds the tutorial for us can work with the new build system and blueprint. + +It will also probably be worthwhile getting Embroider API documentation added to https://api.emberjs.com/ as one of the listed projects on the left-hand side. + +The majority of this RFC is written from the perspective of someone that is running `ember new` for the first time on a brand new app, but we will need to make sure to write both upgrade guides and appropriate codemods for anyone that is wanting to upgrade their apps from the old blueprints to this new default. We also need to put some consideration into the experience of people using [ember-cli-update](https://github.com/ember-cli/ember-cli-update) to upgrade Ember versions when we make this the new default. + +It's also important to note that this RFC does not represent the new bluerpint for a Polaris application. This is just upgrading our build system to use more modern and standard tools. Any communication around this RFC change should be explicit that this is a **part** of what is needed for Polaris but this blueprint update is not giving you all of polaris. This is a single step in that direction. + +## Drawbacks + +### Upgradability + +If developers are using ember-cli-update to upgrade their apps there might be a case where in an upcoming version of Ember they will be "opted in" to an Embroider build with Vite. We don't expect this process to be automatic but we do think that we can get most applications across this line with the use of tooling and codemods. One way to mitigate this problem is that we could maintain a "classic blueprint" until the next Ember major release that people could switch to while they are figuring out how to upgrade to Embroider and Vite. + +### Webpack support + +The blueprint will default to using Vite as a bundler, and we plan to document the process to add support for more bundlers as part of the implementation of this RFC. We had originally intended to provide support for Webpack as a bundler to help people who have already upgraded to the current stable Embroider version and customised their Webpack builds but Webpack support is not trivial to implement. The Ember Tooling Team believes that the benefits of having Vite as the default build experience are so great that we should not delay the implementation of this RFC while we try to backport the Inversion of control implementation of Embroider to Webpack. + +## Unresolved questions + +### package.json meta key + +The way that Embroider is currently implemented the Ember MetaData in package.json is set with the key `ember-addon` even for applications. On the one hand it seems good that the applications and addons use the same key for this, but on the other hand it may be confusing that the key for the metadata has the word `addon` in it. We could move both addons and apps to just use the metadata key `ember` but that could create chrun with very little benefit. diff --git a/text/0995-deprecate-non-colocated-components.md b/text/0995-deprecate-non-colocated-components.md index 943c2a0896..1365249178 100644 --- a/text/0995-deprecate-non-colocated-components.md +++ b/text/0995-deprecate-non-colocated-components.md @@ -1,5 +1,5 @@ --- -stage: released +stage: recommended start-date: 2023-12-15T00:00:00.000Z release-date: release-versions: @@ -13,6 +13,7 @@ prs: accepted: 'https://github.com/emberjs/rfcs/pull/995' ready-for-release: 'https://github.com/emberjs/rfcs/pull/1012' released: 'https://github.com/emberjs/rfcs/pull/1023' + recommended: 'https://github.com/emberjs/rfcs/pull/1040' project-link: --- diff --git a/text/1001-deprecate-named-inject.md b/text/1001-deprecate-named-inject.md index 7f7e484625..4953b52fb2 100644 --- a/text/1001-deprecate-named-inject.md +++ b/text/1001-deprecate-named-inject.md @@ -1,13 +1,14 @@ --- -stage: accepted +stage: ready-for-release start-date: 2023-12-26T00:00:00.000Z release-date: release-versions: -teams: # delete teams that aren't relevant +teams: - framework - typescript prs: - accepted: https://github.com/emberjs/rfcs/pull/1001 + accepted: 'https://github.com/emberjs/rfcs/pull/1001' + ready-for-release: 'https://github.com/emberjs/rfcs/pull/1013' project-link: --- diff --git a/text/1006-deprecate-action-template-helper.md b/text/1006-deprecate-action-template-helper.md index 124eb9aea4..ca274a3623 100644 --- a/text/1006-deprecate-action-template-helper.md +++ b/text/1006-deprecate-action-template-helper.md @@ -1,5 +1,5 @@ --- -stage: released +stage: recommended start-date: 2024-02-13T00:00:00.000Z release-date: 2024-06-07T00:00:00.000Z release-versions: @@ -15,6 +15,7 @@ prs: accepted: 'https://github.com/emberjs/rfcs/pull/1006' ready-for-release: 'https://github.com/emberjs/rfcs/pull/1011' released: 'https://github.com/emberjs/rfcs/pull/1022' + recommended: 'https://github.com/emberjs/rfcs/pull/1036' project-link: --- diff --git a/text/1009-move-deprecation-workflow-to-apps.md b/text/1009-move-deprecation-workflow-to-apps.md new file mode 100644 index 0000000000..c62922b3e0 --- /dev/null +++ b/text/1009-move-deprecation-workflow-to-apps.md @@ -0,0 +1,335 @@ +--- +stage: accepted +start-date: 2024-02-22T00:00:00.000Z +release-date: # In format YYYY-MM-DDT00:00:00.000Z +release-versions: +teams: # delete teams that aren't relevant + - cli + - data + - framework + - learning + - typescript +prs: + accepted: https://github.com/emberjs/rfcs/pull/1009 +project-link: +suite: +--- + + + +# Move the deprecation workflow library to be installed in apps by default + +## Summary + +Historically, folks have benefitted from [ember-cli-deprecation-workflow](https://github.com/mixonic/ember-cli-deprecation-workflow). This behavior is _so useful_, that it should be built in to folks applications by default. + +## Motivation + +Everyone needs a deprecation-workflow, and yet `ember-cli-deprecation-workflow` is not part of the default blueprint. + +This RFC proposes how we can ship deprecation workflow handling behavior in apps by default, which may give us a blessed path for better integrating with build time deprecations as well (though that is not the focus of this RFC). + + +## Detailed design + + +Have `ember-cli-deprecation-workflow` installed by default. + +1. applications must have `@embroider/macros` installed by default. +2. the app.js or app.ts can conditionally import a file which sets up the deprecation workflow + ```diff app/app.js + import Application from '@ember/application'; + + import { importSync, isDevelopingApp, macroCondition } from '@embroider/macros'; + + import loadInitializers from 'ember-load-initializers'; + import Resolver from 'ember-resolver'; + import config from 'test-app/config/environment'; + + + if (macroCondition(isDevelopingApp())) { + + importSync('./deprecation-workflow'); + + } + + export default class App extends Application { + modulePrefix = config.modulePrefix; + podModulePrefix = config.podModulePrefix; + Resolver = Resolver; + } + + loadInitializers(App, config.modulePrefix); + ``` +3. then in `app/deprecation-workflow.js` would use the already public API, + ```js + import setupDeprecationWorkflow from 'ember-cli-deprecation-workflow'; + + setupDeprecationWorkflow({ + /** + false by default, but if a developer / team wants to be more aggressive about being proactive with + handling their deprecations, this should be set to "true" + */ + throwOnUnhandled: false, + handlers: [ + /* ... handlers ... */ + ] + }); + ``` + + +This follows the README of [ember-cli-deprecation-workflow](https://github.com/ember-cli/ember-cli-deprecation-workflow?tab=readme-ov-file#getting-started). + + + +## How we teach this + +We'd want to add a new section in the guides under [`Application Concerns`](https://guides.emberjs.com/release/applications/) that talks about deprecations, how and how to work through those deprecations. + +All of this content already exists using a similar strategy as above, here, [under "Configuring Ember"](https://guides.emberjs.com/release/configuring-ember/handling-deprecations/#toc_deprecation-workflow), and also walks through how to use `ember-cli-deprecation-workflow`. + +This README of [ember-cli-deprecation-workflow](https://github.com/ember-cli/ember-cli-deprecation-workflow?tab=readme-ov-file#getting-started) also explains, in detail, how to use this tool / workflow, and that content can be copied in to the guides. + +## Drawbacks + +For older projects, this could be _a_ migration. But as it is additional blueprint boilerplate, it is optional. + +## Alternatives + +There are only a few features of `ember-cli-deprecation-workflow` that we need to worry about: +- enabled or not - do we check deprecations at all, or ignore everything (current default) +- `throwOnUnhandled` - this is the most aggressive way to stay on top of your deprecations, but can be frustrating for folks who may not be willing to fix things in `node_modules` when new deprecations are introduced. + +- `window.flushDeprecations()` - prints the list of deprecations encountered since the last page refresh +- Matchers - a fuzzier way to match deprecation messages rather than strictly matching on the deprecation id (sometimes deprecation messages have information about surrounding / relevant context, and these could be used to more fine-grainedly work through large-in-numbers deprecations) +- Logging / Ignoring / Throwing - when encountering a matched deprecation (whether by id or by regex, how should it be handled?) + + +However, folks can get a basic deprecation-handling workflow going in their apps without the above features, + +1. applications must have `@embroider/macros` installed by default. +2. the app.js or app.ts can conditionally import a file which sets up the deprecation workflow + ```diff app/app.js + import Application from '@ember/application'; + + import { importSync, isDevelopingApp, macroCondition } from '@embroider/macros'; + + import loadInitializers from 'ember-load-initializers'; + import Resolver from 'ember-resolver'; + import config from 'test-app/config/environment'; + + + if (macroCondition(isDevelopingApp())) { + + importSync('./deprecation-workflow'); + + } + + export default class App extends Application { + modulePrefix = config.modulePrefix; + podModulePrefix = config.podModulePrefix; + Resolver = Resolver; + } + + loadInitializers(App, config.modulePrefix); + ``` + this conditional import is now easily customizable for folks in their apps, so they could opt to _not_ strip deprecation messages in production, and see where deprecated code is being hit by users (reported via Sentry, BugSnag, or some other reporting tool) -- which may be handy for folks who have a less-than-perfect test suite (tests being the only current way to automatically detect where deprecated code lives). +3. the `app/deprecation-workflow.js` would use the already public API, [`registerDeprecationHandler`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fdebug/registerDeprecationHandler) + ```ts + import { registerDeprecationHandler } from '@ember/debug'; + + import config from '/config/environment'; + + const SHOULD_THROW = config.environment !== 'production'; + const SILENCED_DEPRECATIONS: string[] = [ + // Add ids of deprecations you temporarily want to silence here. + ]; + + registerDeprecationHandler((message, options, next) => { + if (!options) { + console.error('Missing options'); + throw new Error(message); + } + + if (SILENCED_DEPRECATIONS.includes(options.id)) { + return; + } else if (SHOULD_THROW) { + throw new Error(message); + } + + next(message, options); + }); + ``` + + +This simple implementation of deprecation workflow may work for libraries' test-apps, but it is not as robust as what `ember-cli-deprecation-workflow` offers, per the above-listed set of features that folks are used to. + +To get all of those features from `ember-cli-deprecation-workflow`, we could define a function, `setupDeprecationWorkflow`, taken from the [Modernization PR on ember-cli-deprecation-workflow](https://github.com/mixonic/ember-cli-deprecation-workflow/pull/159), this is what the deprecation-workflow file could look like: + +
ember-cli-deprecation-workflow/index.js + +```js +import { registerDeprecationHandler } from '@ember/debug'; + +const LOG_LIMIT = 100; + +export default function setupDeprecationWorkflow(config) { + self.deprecationWorkflow = self.deprecationWorkflow || {}; + self.deprecationWorkflow.deprecationLog = { + messages: {}, + }; + + registerDeprecationHandler((message, options, next) => + handleDeprecationWorkflow(config, message, options, next), + ); + + registerDeprecationHandler(deprecationCollector); + + self.deprecationWorkflow.flushDeprecations = flushDeprecations; +} + +let preamble = `import setupDeprecationWorkflow from 'ember-cli-deprecation-workflow'; + +setupDeprecationWorkflow({ + workflow: [ +`; + +let postamble = ` ] +});`; + +export function detectWorkflow(config, message, options) { + if (!config || !config.workflow) { + return; + } + + let i, workflow, matcher, idMatcher; + for (i = 0; i < config.workflow.length; i++) { + workflow = config.workflow[i]; + matcher = workflow.matchMessage; + idMatcher = workflow.matchId; + + if (typeof idMatcher === 'string' && options && idMatcher === options.id) { + return workflow; + } else if (typeof matcher === 'string' && matcher === message) { + return workflow; + } else if (matcher instanceof RegExp && matcher.exec(message)) { + return workflow; + } + } +} + +export function flushDeprecations() { + let messages = self.deprecationWorkflow.deprecationLog.messages; + let logs = []; + + for (let message in messages) { + logs.push(messages[message]); + } + + let deprecations = logs.join(',\n') + '\n'; + + return preamble + deprecations + postamble; +} + +export function handleDeprecationWorkflow(config, message, options, next) { + let matchingWorkflow = detectWorkflow(config, message, options); + if (!matchingWorkflow) { + if (config && config.throwOnUnhandled) { + throw new Error(message); + } else { + next(message, options); + } + } else { + switch (matchingWorkflow.handler) { + case 'silence': + // no-op + break; + case 'log': { + let key = (options && options.id) || message; + + if (!self.deprecationWorkflow.logCounts) { + self.deprecationWorkflow.logCounts = {}; + } + + let count = self.deprecationWorkflow.logCounts[key] || 0; + self.deprecationWorkflow.logCounts[key] = ++count; + + if (count <= LOG_LIMIT) { + console.warn('DEPRECATION: ' + message); + if (count === LOG_LIMIT) { + console.warn( + 'To avoid console overflow, this deprecation will not be logged any more in this run.', + ); + } + } + + break; + } + case 'throw': + throw new Error(message); + default: + next(message, options); + break; + } + } +} + +export function deprecationCollector(message, options, next) { + let key = (options && options.id) || message; + let matchKey = options && key === options.id ? 'matchId' : 'matchMessage'; + + self.deprecationWorkflow.deprecationLog.messages[key] = + ' { handler: "silence", ' + matchKey + ': ' + JSON.stringify(key) + ' }'; + + next(message, options); +} +``` + +
+ +and at this point, we may as well build it into `ember` and not use an additional library at all, **and this is what the primary proposal of this RFC: build the deprecation workflow setup function in to ember**, so re-running through the setup steps: + +1. applications must have `@embroider/macros` installed by default. +2. the app.js or app.ts can conditionally import a file which sets up the deprecation workflow + ```diff app/app.js + import Application from '@ember/application'; + + import { importSync, isDevelopingApp, macroCondition } from '@embroider/macros'; + + import loadInitializers from 'ember-load-initializers'; + import Resolver from 'ember-resolver'; + import config from 'test-app/config/environment'; + + + if (macroCondition(isDevelopingApp())) { + + importSync('/deprecation-workflow'); + + } + + export default class App extends Application { + modulePrefix = config.modulePrefix; + podModulePrefix = config.podModulePrefix; + Resolver = Resolver; + } + + loadInitializers(App, config.modulePrefix); + ``` + this conditional import is now easily customizable for folks in their apps, so they could opt to _not_ strip deprecation messages in production, and see where deprecated code is being hit by users (reported via Sentry, BugSnag, or some other reporting tool) -- which may be handy for folks who have a less-than-perfect test suite (tests being the only current way to automatically detect where deprecated code lives). +3. the `app/deprecation-workflow.js` would use the already public API, [`registerDeprecationHandler`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fdebug/registerDeprecationHandler) + ```js + import { setupDeprecationWorkflow } from '@ember/debug'; + + setupDeprecationWorkflow({ + throwOnUnhandled: true, + handlers: [ + /* ... handlers ... */ + ] + }); + ``` + + + +## Unresolved questions + +n/a diff --git a/text/1026-ember-data-deprecate-store-extends-ember-object.md b/text/1026-ember-data-deprecate-store-extends-ember-object.md index 46ad7a0c4a..4e344fcda2 100644 --- a/text/1026-ember-data-deprecate-store-extends-ember-object.md +++ b/text/1026-ember-data-deprecate-store-extends-ember-object.md @@ -1,14 +1,17 @@ --- -stage: accepted +stage: released start-date: 2024-05-11T00:00:00.000Z -release-date: # In format YYYY-MM-DDT00:00:00.000Z +release-date: release-versions: -teams: # delete teams that aren't relevant + ember-data: 5.3.0 +teams: - data prs: - accepted: https://github.com/emberjs/rfcs/pull/1026 + accepted: 'https://github.com/emberjs/rfcs/pull/1026' + ready-for-release: 'https://github.com/emberjs/rfcs/pull/1035' + released: 'https://github.com/emberjs/rfcs/pull/1047' project-link: -suite: +suite: --- # EmberData | Deprecate Store extending EmberObject @@ -106,4 +109,4 @@ none ## Unresolved questions -None \ No newline at end of file +None diff --git a/text/1046-template-tag-in-routes.md b/text/1046-template-tag-in-routes.md new file mode 100644 index 0000000000..1166efbd9b --- /dev/null +++ b/text/1046-template-tag-in-routes.md @@ -0,0 +1,204 @@ +--- +stage: ready-for-release +start-date: 2024-10-04T00:00:00.000Z +release-date: +release-versions: +teams: + - framework + - learning + - typescript +prs: + accepted: 'https://github.com/emberjs/rfcs/pull/1046' + ready-for-release: 'https://github.com/emberjs/rfcs/pull/1053' +project-link: +suite: +--- + + + +# Use Template Tag in Routes + +## Summary + +Allow `app/templates/*.hbs` to convert to `app/temlates/*.gjs`. + +## Motivation + +We are rapidly approaching the point where Template Tag is the recommended way to author components. This means using `.gjs` (or `.gts`) files that combine your template and Javascript into one file. But you cannot currently use Template Tag to author the top-level templates invoked by the router (`app/templates/*.hbs`). + +This inconsistency is especially apparent when working on teaching materials for new users. Making people learn both `.hbs` with global component resolution and `.gjs` with strict template resolution before they can even make their first component is unreasonable. + +This RFC proposes allowing consistent use of `.gjs` everywhere. It doesn't remove any support for `.hbs`, but recommends that the guides default to all `.gjs`. + +## Detailed design + +The [implementation is small and already done](https://github.com/emberjs/ember.js/pull/20768). + +### Illustration By Example + +If you currently have this: + +```hbs +{{! app/templates/example.hbs }} +
+ +
+``` + +You can convert it to this: + +```gjs +// app/templates/example.gjs +import MainContent from 'my-app/components/main-content'; + +``` + +Key differences: + +- this is [strict handlebars](https://github.com/emberjs/rfcs/blob/master/text/0496-handlebars-strict-mode.md), so components are imported explicitly +- the controller is no longer `this`, it is `@controller`. + +Many things that you might have been forced to put on a controller can now be done directly. For example, if your controller has a `doSomething` event handler: + +```hbs +{{! app/templates/example.hbs }} +
+``` + +You now have options to implement it in-place in the same file. If it's stateless it can just be a function: + +```gjs +// app/templates/example.gjs + +// This import will be unnecessary after https://github.com/emberjs/rfcs/pull/1033 +import { on } from '@ember/modifier'; + +function doSomething() { + alert("It worked"); +} + + +``` + +If it's stateful, you can upgrade from a template-only component to a Glimmer component: + +```gjs +// app/templates/example.gjs +import { on } from '@ember/modifier'; +import Component from '@glimmer/component'; +import { tracked } from '@glimmer/tracking'; + +export default class extends Component { + @tracked activated = false; + + doSomething = () => { + this.activated = !this.activated; + } + + +} +``` + +### Specification + +When Ember resolves a route template (`owner.lookup("template:example")`: + +1. Check whether the resulting value has a component manager. + - If no, do exactly what happens today. + - If yes, continue to step 2. +2. Synthesize a route template that invokes your component with these arguments: + - @model: which means exactly the same as always. + - @controller: makes the controller available. + +Keen observers will notice that this says nothing about only supporting gjs files. Any component is eligible, no matter how it's authored or what Component Manager it uses. This is by design, because there's no reason for the router to violate the component abstraction and care about how that component was implemented. + +However, in our learning materials we should present this as a feature designed for GJS files. Using it with components authored in .hbs would be needlessly confusing, because automatic template co-location **does not work in app/templates**, because it would collide with traditional route templates. + +### ember-route-template addon + +This RFC replaces the [ember-route-template](https://github.com/discourse/ember-route-template) addon. If you're already using it, it would continue to work without breaking, but you can simply delete all the calls to its `RouteTemplate` function and remove it. The popularity of that addon among teams who are already adopting Template Tag is an argument in favor of this RFC. + +### Codemod + +Because Embroider already generates imports for components, helpers, and modifiers in non-strict templates, there is [ongoing work](https://github.com/embroider-build/embroider/pull/2134) to offer Embroider's existing functionality as a Template Tag codemod. + +For route templates, the only extra feature required would be replacing `this` with `@controller`. + +In order to help people be successful with the codemod, we should also: + +- deprecate passing dynamic component strings to the `{{component ...}}` helper, since that is the only non-strict-handlebars feature that Embroider cannot automatically concert to the equivalent strict-handlebars code. + +- continue to emphasize v2 addons, because v1 addons that use the full weird panoply of old behaviors can make the codemod unreliable. + +### TypeScript + +No new typescript-specific features are required. If you're authoring route templates in GTS, Glint should treat them just like any other component. You will need to manually declare the signature for `@model` and `@controller`, but that is the same as now. + +## How we teach this + +This RFC was directly inspired by a first attempt at updating the Guides for Template Tag. It became immediately apparent that we can write _much_ clearer guides if we can teach all GJS, instead of a mix of GJS and HBS. + +Starting at https://guides.emberjs.com/release/components/ when the first `application.hbs` file is introduced, we would use `.gjs` instead. In those opening examples that are empahsizing HTML, the only change to the content would be wrapping `` around the HTML. + +Progressing to https://guides.emberjs.com/release/components/introducing-components/, learners extract their first component. It now becomes possible to do that within the same file. This allows teaching fewer things in a single step. First, people can learn what a component is. Second, it can be refactored into a separate file. We can avoid teaching anything about "pascal case" and naming rules, because everything just follows javascript naming rules. + +When starting to teach routing in https://guides.emberjs.com/release/routing/defining-your-routes/, the file extensions change and `` wrappers are added, but nothing else on that page necessarily changes. + +In https://guides.emberjs.com/release/routing/query-params/, it's appropriate to first introduce the `@controller` argument. + +In https://guides.emberjs.com/release/routing/controllers/, the list of reasons to use a controller gets shortened to only queryParams, since now you can manage state directly in your route's component. + +### How to teach: what to do when you encounter an HBS route template? + +Guides will need one or more callout boxes in the routing area to point people toward a dedicated page about HBS files in app/templates. + +The dedicated page will explain that this is the older pattern, the controller is available as `this` the model is still `@model`, and the instruction for dealing with them is to run the codemod to convert them to GJS. + +## Drawbacks + +There is appetite for a more ambitious RFC that changes more things about routing. Eliminating controllers, making routes play nice with the newer `@ember/destroyable` system, allowing parallel model hooks, etc, are all good goals. There is a risk that if we do those things soon, this would be seen as two steps of churn instead of one. + +I think we can mitigate that risk because + +- we won't deprecate `.hbs` routes yet, so no churn is forced immediately. +- we can ship the Template Tag codemod so that even big apps can adopt at low cost +- it's extremely unlikely that a future routing design would use anything other than `.gjs` to define route entrypoints. By converting now, you are already moving in the right direction by eliminating all the non-strict behaviors. + +## Alternatives + +### Bigger Router RFC + +The main alternative here is to do a bigger change to the routing system. A "Route Manager" RFC would allow the creation of new Route implementations that could have their own opinions about how to route to GJS files. This RFC does not preclude that other work from also happening. + +The main benefit of this RFC is that the [implementation is small and already done](https://github.com/emberjs/ember.js/pull/20768) so we could have it immediately. + +### Eliminate Bare Templates Entirely + +The existence of "bare templates" in the system alongside HBS components is a major source of incoherence and potential confusion. It's especially bad that the behavior is hard-coded to depend on particular filesystem paths (a standalone hbs file in `app/components` gets built to a component whereas anywhere else it remains a bare template). + +To eliminate this source of incoherence, it would be desirable to introduce a feature flag that would make _all_ hbs files interpreted as components, regardless of filesystem path. + +This is probably worth doing regardless of whether we also do the present RFC and deserves its own separate proposal. There is a practical question of whether this will be faster than eliminating all HBS via codemod and deprecation and removal. diff --git a/text/1055-vanilla-prettier-setup-in-blueprints.md b/text/1055-vanilla-prettier-setup-in-blueprints.md new file mode 100644 index 0000000000..278bcd4efc --- /dev/null +++ b/text/1055-vanilla-prettier-setup-in-blueprints.md @@ -0,0 +1,81 @@ +--- +stage: accepted +start-date: 2024-12-03T00:00:00.000Z +release-date: +release-versions: +teams: + - cli +prs: + accepted: https://github.com/emberjs/rfcs/pull/1055 +project-link: +suite: +--- + +# Vanilla Prettier Setup in Blueprints + +## Summary + +This RFC proposes to migrate to a vanilla Prettier setup in the blueprints, instead of running Prettier via ESLint and Stylelint. + +## Motivation + +1. Because we run Prettier via ESLint and Stylelint, we only run the files these linters support through Prettier - Using a vanilla Prettier setup, would format all files Prettier supports, ensuring even more consistency in projects +2. Less dependencies in the blueprints - `eslint-plugin-prettier` and `stylelint-prettier` would not be needed anymore +3. The Prettier team recommends running Prettier directly, and not via linters: + - Running Prettier directly is faster than running Prettier via ESLint and Stylelint + - ESLint and Stylelint show red squiggly lines in editors (when using the corresponding extensions), while the idea behind Prettier is to make developers forget about formatting + +`3.` is mostly taken from [Integrating with Linters > Notes](https://prettier.io/docs/en/integrating-with-linters.html#notes) + +## Detailed Design + +We would add the following scripts to the `package.json` file in the `app` blueprint: + +```diff ++ "format": "prettier . --cache --write", ++ "lint:format": "prettier . --cache --check", +``` + +- `lint:format` would check the formatting of _all_ files Prettier supports +- `lint:format` would also run when running the `lint` script +- `format` would format _all_ files Prettier supports +- `format` would also run when running the `lint:fix` script + +> NOTE: We use `format` instead of `lint:format:fix`, because we don't want to run Prettier parallel to ESLint and Stylelint when fixing lint errors. The `lint:fix` script will be updated to always run `format` last. + +We would remove the following dependencies from the `package.json` file in the `app` blueprint: + +```diff +- "eslint-plugin-prettier": "*", +- "stylelint-prettier": "*", +``` + +As these would not be needed anymore. + +> NOTE: We will keep `eslint-config-prettier` installed, as we need this package to turn off the stylistic ESLint rules that might conflict with Prettier. + +We would update the `.prettierignore` file in the `app` blueprint: + +```diff ++ /pnpm-lock.yaml +``` + +To make sure Prettier does not format pnpm's lockfile. + +We would also need to make sure that every file generated by the `app` blueprint is formatted correctly. + +## How We Teach This + +N/A + +## Drawbacks + +- Some developers or teams prefer running Prettier via ESLint and Stylelint + +## Alternatives + +N/A + +## Unresolved Questions + +N/A \ No newline at end of file