Master punch list for resolving Fastboot 1.0 build issues

[kratiahuja]

This issue with track the things we need to do in order to resolve the fastboot build. This issue supersedes #264, #246 etc. Once this master list is resolved, fastboot build and serve issues should be resolved.

Pre requisites

With the help of ember-cli team, we have come up with a viable solution to resolve the double builds. The solution is described in the meeting notes here.

Build blockers

Following are the things we need to do in ember-cli-fastboot. The sub items under each section are more of a checklist:

• Build fastboot overrides using treeForPublic hook per the new build spec. It will works as follows:
  • Collect the fastboot-app tree from the project addons and create a funnel for every addon tree with destDir as appName-fastboot
  • Collect the fastboot-app tree from the root app and create a funnel for the app fastboot tree with destDir as appName-fastboot
  • Merge the trees collected from the addons and app and create a new Funnel
  • Run the JS transpilation on the new funneled tree using ember-cli-preprocess-registry/preprocessors API. Use the preprocessJs method from the preprocessors with providing the registry
  • Concat the output of transpilation with outputFile set to assets/appName-fastboot.js
  • Merge the above output tree with the tree returned from treeForPublic
• Make sure the fastboot-app tree in app is a watched directory tree. Most likely it will be otherwise follow treeForGenerator does here
• Update FastBootConfig broccoli plugin to add assets/appName-fastboot.js in appFiles manifest list of package.json. The corresponding code is here
• Update existing intializers of ember-cli-fastboot per the new spec
• Expose a hook to add to manifest files
• Remove the old fastboot double build spec
  • Remove usage of private ember-cli patching from ember-cli-fastboot. See example here
  • Remove invoking fastboot-filter-initializers in ember-cli-fastboot. See relevant example changes here
  • Remove config function from ember-cli-fastboot/index.js
  • Set app-boot contentFor correctly. See example here
  • Fix config-module contentFor hook to not rely on __is_building_fastboot__ flag. See example fix here
  • Remove preconcat function as it will be unused in new build spec
  • In postprocessTree hook, we should invoke FastBootConfig broccoli plugin directly instead of invoking FastBootBuild broccoli plugin. See example changes here
  • Remove FastBootBuild broccoli plugin as it will be unused
• Update tests
• Kill ember fastboot command 🔪
• Kill usage of process.env.EMBER_CLI_FASTBOOT flag as it will be unavailable in new build spec 🔪
• Doc updates
  • Update addon guide to not have usage of process.env.EMBER_CLI_FASTBOOT flag
  • Update user guide with example to how to add/override fastboot specific functionality in app using fastboot-app and app folders.
  • Update addon user guide on how to write to vendorFiles or appFiles array. Only meant for advanced usage.
• Update some of the exisiting addons to not rely on process.env.EMBER_CLI_FASTBOOT flag or not contain app/[instance-]initializers/[browser|fastboot]/*.js folder structure. These addons should follow the new build spec
  • ember-network
  • ember-cli-head
  • Identify other addons that need to be updated
• Decide FastBoot release version number with the new build spec. Should we do 1.0 or 2.0? (owners: @rwjblue @tomdale )
• Close all open issues in ember-cli-fastboot related to build and/or serve since the new build spec should resolve it.
• Release FastBoot! 🎉
• Blog on FastBoot? (owners: @rwjblue @tomdale )

cc: @danmcclain @rwjblue @tomdale @leitsubomi @arjansingh

[simonihmig]

Thanks for making this very transparent, especially for the nice summary of the new build process in the meeting notes! 👍 @kratiahuja

Having worked a bit on some addons making them play nice with FastBoot, I am happy to test this out in the wild once there is a branch out to play with!

Certainly there is some churn involved for addon authors with the removal of process.env.EMBER_CLI_FASTBOOT, not counting 'ember-cli-fastboot' itself there seem to be 95 addons affected as of now: https://emberobserver.com/code-search?codeQuery=process.env.EMBER_CLI_FASTBOOT. Even more important to make the required changes clear upfront...

What I am missing in the build spec...

1. Adding FastBoot specific vendor files

As a workaround for now, ember-network and other such addons can rely on vendorFiles array in FastBoot manifest and add the Node-fetch implementation in there.

Looking at FastBootConfig the vendorFiles list is hardcoded. For some special case in an addon we wanted to use that recently to get something into FastBoot, but found no way to get custom files into this. So is there a public API designed (or at least planned) that addons will be able to use for this? (add this to items list?)

2. Skipping browser-only vendor files

Looking at the code search of process.env.EMBER_CLI_FASTBOOT, most addons use it to guard against app.import() when importing browser-only libs. How is this supposed to work now? Say an addon, that is a wrapper for some jQuery plugin, wants to import that (globals-based plugin) only in a browser environment (because it calls DOM/jQuery right away). Before the discussed changes here the FastBoot build did not contain this piece of code, but now it does. And the AMD-module override story does not apply here, does it?

[kratiahuja]

@simonihmig Here are my responses:

Adding FastBoot specific vendor files

The public API is using the vendorFiles and appFiles. It's more of an advanced public API. Addons that need to add such files into this array need to run after ember-cli-fastboot and during the postProcessTree read the package.json file and update the manifest and rewrite the file back. It's a bit manual process but only addons with advanced fastboot knowledge will need this. We can update the docs with an example of this as well (in the addon user guide section)

Skipping browser-only vendor files

This is where the undecided item this.import from the build spec will help as well. However, we are not considering that as a blocker. Addons can write to the vendor file using app.import with wrapping the library in an environment check. We can have the docs updated with an example. In browser land, that code will be eval'd and in fastboot it will be skipped. The AMD module override story does not apply here since that is only for app specific overrides.

[kratiahuja]

Certainly there is some churn involved for addon authors with the removal of process.env.EMBER_CLI_FASTBOOT, not counting 'ember-cli-fastboot' itself there seem to be 95 addons affected as of now: https://emberobserver.com/code-search?codeQuery=process.env.EMBER_CLI_FASTBOOT. Even more important to make the required changes clear upfront...

We did discuss the churn concern at length and concluded that FastBoot is not 1.0 yet because of the fact that there are serious build performance issues. Fixing that and having addons fix a small piece of code would be better. Having said that, we still need to decide whether to release the build improvement as 1.0 or 2.0.

[simonihmig]

We did discuss the churn concern at length and concluded that FastBoot is not 1.0 yet because of the fact that there are serious build performance issues.

Sure, not criticizing that decision! Just wanted to point out the importance to communicate these changes early (addon guides!), so addon authors can start refactoring their implementation, such that we don't end up having a stable ember-cli-fastboot out that no addon supports...

Willing to help with the docs if there is some need, just ping me! ;)

[rwjblue]

Just wanted to point out the importance to communicate these changes early

Totally agreed! At this point, there is not much that an addon author can reliably do to prepare (because we need to actually do the work). This issue describes all known details about the migration, we could perhaps mention something about this in the README or something. I think once we get the changes described here done, we can release a series of alphas so that authors can start preparing...

Thoughts on other things we can do to raise awareness?

[simonihmig]

Yeah, I see most things need some release to play with. But the issue "Skipping browser-only vendor files" that @kratiahuja commented on here #360 (comment) can already be implemented in addons today, right?

I suspect the vast majority of the above listed cases of addons using process.env.EMBER_CLI_FASTBOOT is to guard against importing browser-only libs.

If I understand this right, this would work now something like this:

• Move the browser lib intro treeForVendor, wrapping that with stew.map in a if (FastBoot === undefined) { ... original file contents ... }
• app.import that file straight away in included

Is that right? Because then addons could use that technique even now, without any new ember-cli-fastboot release. Or do I miss something?

[kratiahuja]

Thoughts on other things we can do to raise awareness?

@rwjblue I think we need the docs to call this out sooner (more like FYI upcoming breaking changes). People refer to the fastboot website often and that is the best landing place for them to know upcoming changes. This will give enough awareness for addons to know a breaking change is planned.

Is that right? Because then addons could use that technique even now, without any new ember-cli-fastboot release. Or do I miss something?

@simonihmig Yes that is right at a highlevel. Addons could do that today too. In the long run, we could think of a blacklist API that does it for you rather than each addon writing the same boiler plate code.

[kratiahuja]

Willing to help with the docs if there is some need, just ping me! ;)

Definitely will do! :)

[kratiahuja]

PR #369 solves most of the issues in ember-cli-fastboot that an app without any other fastboot complaint addon can be tested with.

Also took a slightly different approach to how we want to put in initializers/instance-initializers for fastboot than mentioned in the build spec. The reason is two fold:

1. Loader behavior is now well defined with clear boundaries. Before a module is required it can be overriden.
2. I think it is bad to unecessary ship AMD modules to browser when they will be essentially no-op.