Add troubleshooting section about CDN URL gotcha

[ramhoj]

This PR adds a new section to the troubleshooting document explaining a gotcha where the javascript asset file can be incorrectly linked when config.asset_host is configured with different URLs in different environments and assets are not re-compiled between those environments.

As the new section explains this is common on Heroku where the user is encouraged to use their pipeline promote feature that does not re-compile assets between apps.

A common pattern is to use one app as a staging environment to evaluate builds. Upon acceptance, the staging app is “promoted” to the production environment. If WEBPACKER_ASSET_HOST is not set to an empty value in the staging application that application’s CDN URL will be compiled into the manifest.json file and reused in the production application.

This issue can be tricky to detect as there might be no immediate error. The file probably still exists as it’s used by staging. When the staging environment later is re-deployed with new finger-printed assets the CDN will eventually remove the asset files that production is still dependent on.

All credit to @willcosgrove who provided this solution in #3005.

[guillaumebriday]

I might be wrong but if the WEBPACKER_ASSET_HOST is empty the output will look something like that /packs/foo right?

Is this something we really want? If the CDN is different between staging and production maybe we should recompile assets no?

[ramhoj]

In our application (Rails 6.1.4, webpacker 6.0.0.rc.5) the output includes the config.asset_host URL resulting in e.g https://d29i806g85j6o3.cloudfront.net/packs/js/927-232a4435482e775b09be.js as output in the browser. The output to the manifest file should be what you describe, as the host not being present in the compiled manifest file is what fixed the issue.

Is it for performance reasons that the full URL is normally compiled into the manifest file? While recompiling the assets per environment would most probably fix the issue it goes against Heroku's default workflow of promoting one environment to another. Heroku customers can achieve this by pushing directly to the production environment to trigger a build there. However this is way slower, our slug tages about 10 minutes to compile on Heroku but only a couple of seconds to promote.

[justin808]

@guillaumebriday this change sounds reasonable and it should get merged.

It's worth noting that for React on Rails Pro applications that use dynamic code splitting using loadable-components, it's very important to ensure that the JS files don't get any full URLs compiled into them.