diff --git a/text/1029-deprecate-app-prefix.md b/text/1029-deprecate-app-prefix.md new file mode 100644 index 0000000000..3a675d7170 --- /dev/null +++ b/text/1029-deprecate-app-prefix.md @@ -0,0 +1,108 @@ +--- +stage: accepted +start-date: 2024-05-20T00:00:00.000Z +release-date: +release-versions: +teams: # delete teams that aren't relevant + - cli + - learning +prs: + accepted: https://github.com/emberjs/rfcs/pull/1029 +project-link: +--- + + + +# Deprecate app-prefix, app-suffix, tests-prefix, and tests-suffix + +## Summary + +ember-cli addons can use their `contentFor` method to emit arbitrary Javascript into many places. This RFC proposes deprecating and removing several of them: + + - app-prefix + - app-suffix + - tests-prefix + - tests-suffix + - vendor-prefix + - vendor-suffix + +## Motivation + +All of these assume there's going to be one "app" bundle, one "vendor" bundle, and one "tests" bundle. But those assumptions are now nonsense, given code-splitting and builds that can directly evaluate the module graph in the browser. + +They are also seldom used based on code searches on emberobserver.com: + +| Feature | Usage Count | Relevance | +| ---------| ------------- | ----------------------------------------------------------------------------------- | +| app-prefix | 2 addons | Last updated 6 and 8 years ago | +| app-suffix | 1 addon | Last updated 6 years ago | +| tests-prefix | 0 addons | Never appears in emberobserver at all | +| tests-suffix | 0 addons | Only some embroider testing infrastructure ever refers to this at all. | +| vendor-prefix | 3 addons | Last updated 6, 7, and 9 years ago | +| vendor-suffix | 2 addons | Last updated 6 and 9 years ago | + +## Transition Path + +For all of these types of `contentFor` we will emit a deprecation if an addon returns content for the given `type` argument. An example of the deprecated behavior looks like: + +```js + contentFor(type, config, contents) { + if (type === 'app-prefix') { + return `console.log("LOL");` + } + } +``` + +## How We Teach This + +The CLI docs [mention contentFor](https://ember-cli.com/api/classes/addon#method_contentFor) but they don't actually document any of the use cases we are deprecating. They describe using contentFor to target index.html instead. That is not being deprecated by this RFC. + + +### Deprecation Guide Content + +#### app-prefix + +Returning content from an addon's `contentFor()` hook for `type="app-prefix"` is deprecated. Addons will no longer be allowed to inject arbitrary javascript here. If you need to provide code that apps will run before booting, document that app authors should import and call your code at the start of their own `app.js` file. + +#### app-suffix + +Returning content from an addon's `contentFor()` hook for `type="app-suffix"` is deprecated. Addons will no longer be allowed to inject arbitrary javascript here. If you need to provide code that apps will run before booting, document that app authors should import and call your code at the start of their own `app.js` file. + +If you were using app-suffix to overwrites modules provided by the app, that is intentionally not supported. Adjust your API to tell app authors to import your code and invoke it where appropriate. + +#### tests-prefix + +Returning content from an addon's `contentFor()` hook for `type="tests-prefix"` is deprecated. Addons will no longer be allowed to inject arbitrary javascript here. Provide utilities that users can import into their own test setup code instead. + +#### tests-suffix + +Returning content from an addon's `contentFor()` hook for `type="tests-suffix"` is deprecated. Addons will no longer be allowed to inject arbitrary javascript here. Provide utilities that users can import into their own test setup code instead. + +#### vendor-prefix + +Returning content from an addon's `contentFor()` hook for `type="vendor-prefix"` is deprecated. Addons will no longer be allowed to inject arbitrary javascript here. If you really need to run script (non-module) code, provides your own script via your addon's `/public` directory and either document that app authors should createa a `