Post

Embedding LiveView apps in third-party sites with LiveViewPortal

Posted
Preview Image
By Víctor Fernández
5 min read
Embedding LiveView apps in third-party sites with LiveViewPortal

Phoenix, among many other things, is a great framework for developing web pages and applications. With LiveView, you get reactivity and real-time updates. To expand these characteristics and unlock live views to exist in any page, we’ve been working on a little PoC library: LiveViewPortal.

LiveViewPortal: How does it work?

The main concept of LiveViewPortal is to embed live views in third-party pages. To achieve html and styling isolation, it uses the Shadow DOM. The live view is embedded with a simple js fetch to the live view route, and then you can connect the socket. LiveViewPortal only provides a js library to make this easier and modify the sensible parts of Phoenix.LiveView. You will have to configure your Phoenix application to work with portals, so this guide will be your friend.

That was dense 😅, let’s do a quick overview and, if you want more, you can check the aforementioned (cool word) guide.

Phoenix routing and endpoint configuration

First, let’s check how it is possible to do this from the server side. In a regular Phoenix application you serve the live views (regular and nested) to an HTTP GET request initiated by the browser. LiveViewPortal is different because it performs a cross-origin request with fetch. This request includes credentials to receive the session cookie from the server. Likewise, the server must authorize that origin to perform requests and to send credentials with the corresponding headers.

With a little bit of configuration in endpoint.ex and router.ex you should be able to get everything ready. For this purpose, Plug is your friend, and you can meet your needs with a really simple plug. This is out of the scope for this blogpost but you can read the friendly guide.

HTML injection inside the Shadow DOM

The Shadow DOM is this gloomy-named feature of the Web Components standard that encapsulates a part of the DOM tree. From that previous MDN link:

Shadow DOM enables you to attach a DOM tree to an element, and have the internals of this tree hidden from JavaScript and CSS running in the page.

Great! Just what we need for our portals. We can attach a live view inside this shadow DOM and shield it from external interference. It also allows us to have elements with IDs that are already in use outside the shadow DOM. This comes in handy in the case that you want to embed a live view twice in the same page. Not a really common use case, but power to you if you do it.

Hey, but you forgot about <iframe>

There are a few reasons for not using <iframe>s:

  • Performance. No need to load a full DOM.
  • Session cookie: Safari has some conflicts with <iframe> and cookies. This means we could not use the session cookie.
  • Better comunication with host page and with other apps. No need for postMessage(). You can use and expose APIs inside window.
  • SEO.
    • With Shadow DOM, if the portal is loaded with the page, the content counts toward the host page.
    • With <iframe> the content counts toward the origin of the LiveView.

Client side

The actual LiveViewPortal API is really simple. Remember it is only a javascript library, no elixir code. It exposes a class and a function:

(Here put links to the code in github with the JSDoc)

  • deadMount. This function performs the first html only mount.
  • LivePortal. This class is a thin wrapper of LiveSocket and it allows to instantiate a live view and connect to it.

First mount

A LiveView mount is the LiveView entry-point. As stated in the docs:

For each LiveView in the root of a template, mount/3 is invoked twice: once to do the initial page load and again to establish the live socket.

This first mount— often called dead mount— has to be executed from js, because the LiveView is hosted on a different origin than the page. So that is what deadMount does. It fetches the live view and injects it into shadowRoot.innerHTML.

LivePortal

A LivePortal object lets you connect and disconnect a LiveView, both with callbacks. Easy. The object instantiation lets you pass the same options as LiveSocket, and you will have to define the full url route for the LiveView.

There is not that much mistery to the API. The cool part is that you can prefetch the live view and connect to the socket only when the user is ready for a torrent of real-time capabilities.

How can I use this?

The possibilities are endless! Well, probably not endless, but you can build interesting stuff with this. You could build a widget for the amazing LiveBeats, where you inject it into your personal page and people can see what you are playing in real-time. You could do that, but I’ve beat you to it (pun intended).

I’ll leave a tiny appetizer here, the script that loads the LiveBeats widget:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import { LivePortal, deadMount} from "../vendor/live_view_portal"

// this file will be executed from a script tag.

// suppose this is fetched from somewhere
const username = "victor23k"

const lvUrl = `http://localhost:4000/portal/profile-widget?username=${username}`;
let livePortal;

const mountPoint = await deadMount(lvUrl, "initial");
livePortal = new LivePortal(mountPoint.shadowRoot, {
  appName: "profile-widget",
  lvUrl,
  socketUrl: "http://localhost:4000/live"
});

livePortal.connect();
document.body.append(mountPoint);

How does this relate to Phoenix LiveView?

Our main goal is to merge this functionality into LiveView. We want this to be a part of the Phoenix ecosystem. Also, around the same time we started working on this library, a PR was opened in the LiveView repo to support multiple liveSockets in the same page, to different domains. There is some code from that PR in LiveViewPortal, as before that we were doing some more complicated stuff.

Besides that, the actual LiveView code modified in LiveViewPortal is quite simple, it adds support for a live view to exist inside the Shadow DOM, and on a page with a different url.

Wrapping up

That’s it! I hope that this LiveViewPortal is useful to you and that you experiment with it. If you are interested in having this merged in upstream LiveView, leave a comment here. If you have any questions, doubts, comments, you can create a post in ElixirForum (mentioning me if you want).

elixir, liveview
elixir liveview embedding liveview