Docs: add info about merged app directory

We currently document one gotcha for addon authors building addons in TypeScript:

Because addons have no control over how files in app/ are transpiled, you cannot have .ts files in your addon’s app/ folder.

To expand on that for future readers who may stumble on this (and as a starting point for the docs we should write up):

Having .js supplied to a specific path inside the app namespace by both an addon and the app itself, when one of them is using TypeScript to generate that file, creates a caching problem. When addons inject .js files into the app namespace, and we’re compiling .ts files to .js files in the consuming app (always in the app namespace), or vice versa, we can end up in a situation where Ember CLI sees that there is already a .js file there, so it ignores the one generated from .ts. Which one it picks up seems to be semi-random (at least: we haven’t chased it down to see if it’s consistently replicable).

The real solution here is for addons to stop injecting themselves into the app namespace and to supply imports people can use instead to explicitly opt into using their functionality. However, until that becomes a community norm (best guess: not until Embroider lands), we should document this as a gotcha, including the kinds of build errors it produces, so that people find it when it happens to them and we have a useful place to direct addon authors to in understanding why and how they’re breaking their consumers.

Ecosystem issues

• #724
• ember-cli/ember-ajax#428
• stefanpenner/broccoli-persistent-filter#166

[patrickberkeley]

This is a big trap. Any app that consumes an addon that exports a file that matches the name of a file in the app will sporadically get a bad build.

ESA is one of the most popular add-ons, and it happens to export the application route. So that is why people have come across this issue using it.

Another very common case will be apps that consume app-specific addons (ones written just for one or two apps, not public consumption). The reason is this type of addon is often used to define a base which the one or more apps can extend. It is natural in this case for the files to have the same name in app and addon, and for there to be lots of them.

We were bitten by both the above scenarios (three apps use esa and consume two local add-ons). It was difficult to track down and cost us a bunch of time.

[lifeart]

// cc

I think it should be redlined and pinned in the docs - because this is floating behaviour and can create serious damage for business.

for case - we have application.ts route and have ember-simple-auth installed - it’s so easy to get issue with inconsistent builds, because there is no user action needed for it. (and alot of ember users use ember-simple-auth)