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:

   contentFor(type, config, contents) {
     if (type === 'app-prefix') {
       return `console.log("LOL");`
     }
    }

How We Teach This

The CLI docs mention 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 <script> element in their HTML that includes it, or use contentFor() with one of the types that appears in index.html to emit the scrip tag automatically. (contentFor targeting HTML is not deprecated, this deprecation only covers targeting javascript bundles.)

vendor-suffix

Returning content from an addon's contentFor() hook for type="vendor-suffix" 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 <script> element in their HTML that includes it, or use contentFor() with one of the types that appears in index.html to emit the scrip tag automatically. (contentFor targeting HTML is not deprecated, this deprecation only covers targeting javascript bundles.)

Drawbacks

This is a change to the v1 addon API. V2 addons already cannot use the contentFor hooks this RFC aims to deprecate. One could argue against bothering to change the v1 addon API.

Alternatives

We could leave this API alone, on the assumption that it will get included in a wider "deprecate v1 addons" RFC. I'm not advocating that because I don't think it's practical to deprecate v1 addons any time soon.

We could include app-boot in this RFC. It certainly deserves to be deprecated, and has only a single use in the ecosystem (ember-cli-fastboot). But I think it's proper replacement should get designed in a "v2 app format" RFC instead, so that the booting of an app (or a test suite) is codified clearly as code the user controls.