Client Side Embeds

[trieloff]

The current system of server-side embeds has some distinct advantages for authors and developers:

• ease of use
• works out of the box, no custom code needed

but it also comes with marked disadvantages, namely

• inability to reliably defer the loading of embeds (browsers largely ignore lazy) and thus
• massive decrease in lighthouse scores due to all the unnecessary data loaded by providers

@davidnuescheler and @MarquiseRosier have been experimenting with client-side embeds, with promising results, but this approach has two shortcomings:

• usage of OEmbed providers is hampered through CORS restrictions
• it requires a client-side script that must be added to each side
• it requires different markup to differentiate from traditional server-side embeds

The following is a proposal for a unified approach that combines the best of both worlds:

• [ ] extend helix-embed to honor the Accept: application/json header and return the raw metadata object from unfurl/iframely without a transformation to HTML
• [ ] extend helix-static to respond to the /_hlx_embed/embed.js URL and serve an `embed.js' script to run in the browser that will
  • [ ] wait for the page to render
  • [ ] find all occurrences of <a href="" class="helix-embed"> (or similar)
  • [ ] make a request to /_hlx_embed/${a.href} and retrieve a JSON metadata object
  • [ ] transform the metadata object into an appropriate DOM node
  • [ ] replace the <a href="" class="helix-embed"> with the DOM node
• extend helix-pipeline to replace external embed nodes in the MDAST with <a href="" class="helix-embed"> in HTML
• extend helix-pipeline to add an <esi:include src="/_hlx_embed/embed.js.esi"> at the bottom of each HTML document if embed nodes have been in the MDAST
• extend helix-static to serve /_hlx_embed/embed.js.esi with a <script src="/_hlx_embed/embed.js?version=${sha}"> response

As a result, authors will add embeds as before, and when requesting a page with an embed, following things will happen

1. each embed in the Markdown will become a <a href="" class="helix-embed">
2. the page will include an <esi:include src="/_hlx_embed/embed.js.esi"> at the bottom of the page
3. this ESI will be replaced with <script src="/_hlx_embed/embed.js?version=${sha}">
4. /_hlx_embed/embed.js?version=${sha} will be loaded by the browser and cached a long time
5. the script will make a request for each <a href="" class="helix-embed"> and replace the link with an appropriate embed

[tripodsan]

I don't like that the contents of the embed.js is dictated by helix-static, nor that helix-pipeline injects HTML.

I would:

• serve the embed.js from helix-pages, giving the author the possibility to overwrite in his project
• don't hardcode the esi include to the pipeline, but add it to the pre.js / htl of helix-pages

[trieloff]

I can understand the desire to override embed.js and we can add this ability to helix-static, too.

What speaks against adding the ESI to the pipeline?

[tripodsan]

I can understand the desire to override embed.js and we can add this ability to helix-static, too.

but if it's served from /scripts/embed.js it's automatically served from the correct place.

What speaks against adding the ESI to the pipeline?

people might have an opinion on the exact way how and when the script is loaded.

[tripodsan]

• [ ] make a request to /_hlx_embed/${a.href} and retrieve a JSON metadata object

better: make a request to /_hlx_embed?src=${a.href} and retrieve a JSON metadata object

:-)

[tripodsan]

Basically in other words: if we just removed all the embed stuff from the pipeline (except adding <a href="" class="helix-embed">), then it can be easily handled in helix-pages today and no changes to helix-static are needed.

[trieloff]

Closing. We probably don't need this.