search

ember-learn / ember-cli-addon-docs

Easy, beautiful docs for your OSS Ember addons
https://ember-learn.github.io/ember-cli-addon-docs
MIT License
176 stars 143 forks source link

ADDON_DOCS_ROOT_URL causes issues with FastBoot #327

Open samselikoff opened 5 years ago

samselikoff commented 5 years ago

We use the string ADDON_DOCS_ROOT_URL as a token placeholder value for rootURL in our config/environment.js, so that when building for production, AddonDocs can build a single version of the app, and then it can deploy it to two places: the root URL / of the site, and the versioned URL /versions/my-branch of the site. It does this by swapping out this token value at deploy-time.

This abstraction is causing some issues in FastBoot and potentially elsewhere. I'm wiring up Prember, but as it goes through to pre-render Mirage's AddonDocs site, the Ember app is trying to make API requests to /ADDON_DOCS_ROOT_URL/assets/ember-cli-mirage.json (or whatever). The problem is the rootURL is not set in time for FastBoot to do its thing.

I understand that it saves us a build, but should we back out of this and pay the 2x build cost for now, just so AddonDocs sites are "well-behaved" Ember apps with a known build-time rootURL? Or is there precedent elsewhere for changing these values multiple times using the same built app?

/cc @dfreeman @pzuraq

acorncom commented 5 years ago

Or is there precedent elsewhere for changing these values multiple times using the same built app?

@samselikoff given that rootURL is config data and config data can be controlled via meta tags or other "external to Ember" processes, it doesn't seem far-fetched to expect to be able to swap those values as desired. Is it FastBoot that is having trouble or Prember in particular?

samselikoff commented 5 years ago

@acorncom Prember, as its out-of-the-box experience expects to be able to use that value. Because it's that token that is replaced late in the build, it doesn't work right now.

If we could somehow tell Prember about it, or tell Prember to run twice on the two different versions of the app (which I believe it needs to to get things like URLs and asset paths correct), that might save us a refactor.

dfreeman commented 5 years ago

The issue as it stands now, I think, is that we don't do the substitution during the build at all; we only do it as part of the deploy process (and that's worked out okay so far because we only set the special root URL in the production environment).

We might look into using the postprocessTree hook instead to do the ADDON_DOCS_ROOT_URL substitution (and file duplication, in the case we're updating the root as well). That would allow us to make sure it happens during a regular ember build rather than only during deploys. We'd still need to come up with a way to serve both copies of the app in that case, and to make prember crawl both of them, but that seems likely doable.

I'll hopefully have a little time to investigate post-EmberConf and see what we can do.

lolmaus commented 4 years ago

@samselikoff Have you been able to resolve this and enable a rehydratable static site for ember-cli-addon-docs?

samselikoff commented 4 years ago

No, unfortunately I’m not working on this project anymore. Should definitely be possible though!