DEV Community: Ada Rose Cannon 🏳️‍🌈

Making an AR Game with AFrame

Ada Rose Cannon 🏳️‍🌈 — Thu, 14 Jan 2021 16:57:37 +0000

Making an AR Game with AFrame

Using AFRAME, THREE.js and WebXR to build a game during a 4.5hr live stream.

Here is a .gif (jiff?) of the final game, click here to play the game. It uses the WebXR DOM Overlay API, and the WebXR Hit Test API. So right now the best way to play it is in Mobile Chrome or Samsung Internet Beta.

A virtual ball being shot into a virtual basketball hoop.

If you want to watch all four-plus hours of the live stream the URLs are here:

If you want to just look through the source code here it is:
AdaRoseCannon/basketball-demo
Playbasket ball in AR with Aframe and the WebXR device API GitHub is home to over 50 million developers working… github.com

This was my first time live streaming a whole project from start to finish. It was fun I think I would do it again for small projects like this. In this blog post I will talk about what tools I used to make it and some of the tricks that went into it.

Setting up AFrame

First thing first is to create a new HTML file. index.html and put in some HTML boilerplate. I do this in VSCode using the Emmet Abbreviation ! to auto-fill some basic HTML.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My AR Game</title>
</head>
<body>

</body>
</html>

Next to add the AFrame script I copy and paste the script tag from the AFrame docs.

<script src="[https://aframe.io/releases/1.1.0/aframe.min.js](https://aframe.io/releases/1.1.0/aframe.min.js)"></script>

And paste the AFrame hello world into the body:

<a-scene>
  <a-box position="-1 0.5 -3" rotation="0 45 0" color="#4CC3D9">
  </a-box>
  <a-sphere position="0 1.25 -5" radius="1.25" color="#EF2D5E">
  </a-sphere>
  <a-cylinder position="1 0.75 -3" radius="0.5" height="1.5" color="#FFC65D">
  </a-cylinder>
  <a-plane position="0 0 -4" rotation="-90 0 0" width="4" height="4" color="#7BC8A4">
  </a-plane>
  <a-sky color="#ECECEC"></a-sky>
</a-scene>

Testing

To test it I start a local http server to let me display it on my computer. I use the node http-server module. If you don’t have node environment to hand a couple of other options are the Chrome Web Server extension or building it on a website like glitch.com

WebXR requires a secure origin to run. Secure origins usually begin with https:// a special secure origin is http://localhost which lets you access local a http server.

If you are using Glitch you can just open the URL on the your phone to test it.

Unfortunately the requirement for a secure origin makes things tricky for testing a local server on external devices. Normally I would access the server on my development computer via IP address like so: http://192.168.0.10:8080 but since it’s not a secure origin it can’t be used for WebXR.

To test it on my phone there are two options which work well, the most convenient option is to plug in my phone using USB and use Chrome’s remote debugging to forward the port of the http server. Open chrome://inspect in Chrome to access this feature:

chrome://inspect

Once that is set up you can then open up http://localhost:8080 (replace 8080 with whatever port you are using) on your phone and test like you would on your computer.

During my live streams I couldn’t get this working since I was using my phone’s USB-C port to capture the HDMI. So I used https://ngrok.com/ to get a real https: enabled URL for my local server.

Enabling AR features

The first thing to notice when you try AR in our AFRame scene is that you’ll see through the device camera briefly before it gets obscured when the scene gets shown. This is because the element covers the whole scene.

To solve this we’ll add a new AFrame component to hide objects when the scene goes into AR. This code is from work done by Klaus Weidner in one of the AFrame demos:

AFRAME.registerComponent('hide-in-ar-mode', {
  init: function () {
    this.el.sceneEl.addEventListener('enter-vr', (ev) => {
    if (this.el.sceneEl.is('ar-mode')) {
      this.el.setAttribute('visible', false);
    }
    });
    this.el.sceneEl.addEventListener('exit-vr', (ev) => {
    this.el.setAttribute('visible', true);
    });
  }
})

I included this snippet in a little library of useful components I copy from project to project. As well as some other useful parts so I will just add that script to the page:

<script src="[https://ada.is/basketball-demo/ar-components.js](https://ada.is/basketball-demo/ar-components.js)"></script>

This adds a hide-in-ar-mode component and an ar-hit-test we can use in Aframe. We add the hide-in-ar-mode component to HTML elements I want to hide in AR such as the so it now looks like this:

<a-sky color="#ECECEC" hide-in-ar-mode></a-sky>

The other issue is the scale. The AFrame hello world example is designed for VR. In VR where physically large scenes work well because you can take advantage of the unlimited space. In the AFrame Hello World Example the content is placed 5 meters from the user and is 2.5m tall. This is very large and looks impressive in VR but in AR is much too big to fit in many people’s real environment.

When designing AR scenes, try to avoid having the content larger than 0.5m to enable people to fit it in their environment.

When designing AR scenes, try to avoid having the content larger than 0.5m to enable people to fit it in their environment. I say this as someone who lives in a small apartment.

The times when you want to break this rule is when the AR scene is designed to only be used outside where space is more available or when the virtual object is a stand in for a real object which has specific dimensions. Such as if they are buying a particular piece of furniture and want to see how well it fits in their house.

To update the scene I made all the objects in the scene 10% of their original size. All of the units in WebXR and AFrame are in meters so I turned 1.25m into 0.125m (12.5cm or about 6 inches.)

Adding hit testing

Hit testing allows you cast rays from the virtual content into the real world. So you can place virtual objects inline with real world objects such as the floor, tables and walls.

It will get you both the position and normal of where it hits letting objects be placed on services both vertical and horizontal.

The hit-test feature is one which is not available by default in WebXR because it lets you get additional information about a user’s environment.

But you can request it when the XR session is started in AFrame you add it to your element using the webxr component like so:

<a-scene webxr="optionalFeatures: hit-test;">

To assist in how it’s used I made a component to help with it in the library I mentioned earlier:

<script src="[https://ada.is/basketball-demo/ar-components.js](https://ada.is/basketball-demo/ar-components.js)"></script>

The ar-hit-test component will continuously do hit-testing using the most relevant user input available assisting you to build something which works on a variety of hardware. Such as it will default from using the headset position but will use a VR controller or hand tracking if it is available.

Wherever the hit lands it will place the object. This makes it handy for being a targeting reticle in AR.

We’ll make a 20cm square to use for the guiding reticle:

<a-plane
 rotation="-90 0 0"
 width="0.2"
 height="0.2"
 src="./arrow.png"
 material="transparent:true;"
></a-plane>

arrow.png

Like <div> is for HTML for AFrame it is <a-entity>. This is a plain element with no additional properties such as 3D models. We will make a new which uses the ar-hit-test component to be positioned by hit-testing.

<a-entity ar-hit-test="doHitTest:false" visible="false">

Reticle HTML goes here ...

</a-entity>

We’ve also made it invisible since the ar-hit-test component will make it visible again when it’s able to do hit-testing.

Creating the Basketball Hoop

Now we have some way of getting the position of real world objects we want to create the hoop to go on the wall.

Objects placed on surfaces using hit testing have their y-axis (the up and down axis) aligned with the normal of the surface they are being placed on. This means that objects placed on the floor should appear pretty normal but on surfaces like walls or ceilings they will get rotated. The objects are usually also rotated around this normal to face the hit-test source but this behaviour is not in the spec and so may vary.

Since an object placed on the wall will be rotated 90 degrees we will start it off with some initial rotation as we design it. So the encapsulating entity #hoop will have rotation="90 0 0" which is similar to an object placed on a wall. If we were placing it on the floor a rotation of 0 0 0 would suffice. This rotation will be reset when we place the object against the wall to what ever the orientation of the normal of the wall is.

The hoop will be made of 3 simple shapes, a plane for the back board a torus for the hoop and an open ended cone for the net:

<a-entity id="hoop" rotation="90 0 0" position="0 2 -1.8"> 

    <a-torus scale="0.6 0.6 0.6" position="0 0.173 -0.1" color="#43A367" radius="0.25" radius-tubular="0.005"></a-torus>

    <a-plane
     scale="0.6 0.6 0.6"
     position="0 0 -0.3"
     rotation="-90 0 0"
     width="0.9"
     height="0.9"
     material="transparent: true; side: double;"
     src="./backboard.png"
    ></a-plane>

    <a-cone scale="0.6 0.6 0.6" position="0 0.173 -0.010" color="tomato" radius-bottom="0.25" radius-top="0.3" material="side: double; opacity:0.5; transparent: true;" geometry="height: 0.29; openEnded: true" rotation="90 0 0"></a-cone>

</a-entity>

The end result is simple but should be clear what is.

The basketball hoop created by the code earlier

Positioning the hoop

We want the player to be able to position the hoop on their wall. We can get their chosen position by copying the location from the reticle:

const reticle = document.querySelector("[ar-hit-test]");

function positionHoop() {

    hoop.setAttribute("visible", true);
    hoop.setAttribute("position", reticle.getAttribute("position"));
    hoop.setAttribute("rotation", reticle.getAttribute("rotation"));
}

reticle.addEventListener('select', function (e) {
    positionHoop();
});

This very simple function will make the hoop visible and position the hoop at the same position and rotation as the reticle when a select is made. This naive function will often make the hoop a bit crooked though as it will be tilted to face the hit-test origin but lining it up is hard. So we will need to do some Vector Math to ensure the z direction of the hoop lines up with the y-axis.

const upVector = new THREE.Vector3(0, 1, 0);
const tempVector = new THREE.Vector3();
const tempQuaternion = new THREE.Quaternion();

function positionHoop() {

    hoop.setAttribute("position", reticle.getAttribute("position"));
    hoop.setAttribute("visible", true);

    tempVector.set(0, 0 ,-1);
    tempVector.applyQuaternion(reticle.object3D.quaternion);
    tempQuaternion.setFromUnitVectors(tempVector, upVector);
    hoop.object3D.quaternion.multiplyQuaternions(tempQuaternion, reticle.object3D.quaternion);
};

This slightly more complicated function will work out the Quaternion rotation needed to rotate the reticle into an upright position. It will then set the quaternion rotation of the hoop to multiplication of that rotation with the reticle’s rotation. Resulting in a hoop that is facing the right way but twisted slightly so that it points up.

Adding physics to the scene

Physics is handled by the very useful aframe-physics-system this allows you to make the objects in the scene behave in physically realistic ways.

There are two types of physics objects:

Static Bodies, these do not move or react to being hit by other objects they effectively have infinite mass and are unaffected by gravity. They are cheap to use but cannot move. Anything that should not move should be a static body such as Floors and Walls and in our case the basketball hoop.
Dynamic Bodies, these have mass and will fall with constant acceleration under gravity. They can bounce off static bodies or collide with other dynamic bodies. The only dynamic body in the scene is the ball itself.

To set up the physics system we will include the script after the A-Frame script and add the physics component to our scene element:

<script src="https://cdn.jsdelivr.net/gh/n5ro/aframe-physics-system@v4.0.1/dist/aframe-physics-system.min.js"></script>

...

<a-scene physics="debug: false">

To help setting up your scene it can be worth while to set debug to true so that you can see the shapes it has made outlined in red.

Next we add a sphere with the dynamic-body component to be the ball:

<a-sphere id="ball" dynamic-body radius="0.1" color="orange" position="0.1 2.36 -1.5"></a-sphere>

If we reload the page the ball should fall indefinitely.

The next step is to add static-body to the floor plane so that something can stop the ball, I also made it much larger as the ball will roll when it hits it.

<a-plane
    rotation="-90 0 0"
    width="20"
    height="20"
    color="#43A367"
    static-body
    hide-in-ar-mode
></a-plane>

When we play the game we want to interact with the hoop. So next we will add static-body to the backboard plane.

What do we do about the hoop? This is a lot more complicated. The hoop is a convex object it has a pretty complex topology and the 3D model has many vertices which makes the physics very expensive.

The trick here is to have an invisible torus with as few polygons as we can manage, we make it a static body but make it invisible and place it on top of the high resolution model. This is a common trick in video games to have the physics objects with much simpler geometry than the visible objects.

<a-torus scale="0.6 0.6 0.6" static-body="shape: mesh;" position="0 0.173 -0.1" visible="false" radius="0.27" radius-tubular="0.02" geometry="radius: 0.29; segmentsRadial: 5; segmentsTubular: 12">
</a-torus>

By having the static objects of the hoop inside the hoop entity they will be kept inline with the visible objects.

AFrame Physics System also has a JavaScript API for detecting when two objects collide or setting velocities of objects. It is available on the body property of the entity we want to control as long it is a static or dynamic body.

If we want to set the position and velocity of an object such as the ball we use this method. Here is how we launch the ball from the currently active controller:

const ball = document.getElementById('ball');

  reticle.addEventListener('select', function (e) {

  // Set the ball location to the controller position
  const pose = e.detail.pose;
  ball.body.position.copy(pose.transform.position);  // {x, y, z}

  // Have an initial velocity vector of 5ms into the screen
  tempVector.set(0, 0 ,-5);

  // Set our velocity vector direction to the controller orientation
  // {x, y, z, w}
  tempVector.applyQuaternion(pose.transform.orientation);

  // set the velocity of the ball to our velocity vector
  ball.body.velocity.copy(tempVector);
});

Dom Overlay

The last thing we need is to make some UI so that the user can say when they have set the hoop position and are ready to play. We can build a normal HTML interface for this:

<div id="overlay" class="container">
  <h1>Welcome To Basketball</h1>
  <section class="overlay-content">
    <p id="instructions">Place the basket along a wall</p>
  </section>
  <div style="display: flex; justify-content: space-between; align-self: stretch;">
    <button id="go-button">Ready to Play!</button>
    <button id="exit-button">Stop AR</button>
  </div>
</div>

Then you can use it by declaring it on the WebXR component on the scene object:

<a-scene webxr="optionalFeatures: hit-test, dom-overlay; overlayElement:#overlay;" >

Using real HTML buttons and text has many benefits for the user such as working with accessibility tools, being more readable. It can be styled with regular CSS and can be coded with normal JavaScript.

Something to bear in mind though is that when the user taps on DOM Overlay Elements they will fire input events such as 'click' 'mousedown' and 'touchstart' events as usual but in addition will fire WebXR 'select' events first!

So you may need to use something like a setTimeout in your 'select' events to ensure that a button has not been pushed if you are waiting for input from the HTML buttons.

You can detect support for DOM Overlay by looking for xrsession.domOverlayState.type . If domOverlayState is not set then domOverlay is not present in the browser. If type is not set then the current hardware/browser configuration does not support DOM Overlay so you can use the following function to detect it:

function hasDomOverlay(xrsession) {
  if (!xrsession.domOverlayState) {
    // DOM Overlay is not supported
    return false;
  }

  if (!xrsession.domOverlayState.type) {
    // DOM Overlay is not in use
    return false;
  }

  return true;
}

If you are using DOM Overlay for essential paths through the code then you can use this to detect availability and provide fall back behaviors.

Read the source code to the finished demo

Here is the source code to the demo, I hope this guide helps you make sense of it and some of the decisions that were made. If you have further questions feel free to reach out to me through Twitter.

Thank you so much for reading!
AdaRoseCannon/basketball-demo
Playbasket ball in AR with Aframe and the WebXR device API - AdaRoseCannon/basketball-demo github.com

HTML and Templates & JavaScript Template Literals

Ada Rose Cannon 🏳️‍🌈 — Tue, 27 Oct 2020 09:01:45 +0000

HTML and Templates & JavaScript Template Literals

HTML in the Web is often made of reusable components, composed by templates, making it convenient to edit the different parts that make up a website. There are many templating languages used in the web such as handlebars, Pug, Vue and JSX; these are primarily used for composing HTML. Modern JavaScript has templating syntax built in which can use for all kinds of purposes including composing HTML.

In this post I will introduce the JavaScript syntax for templating and then show how it can be used in the real world for sanitising HTML and introducing some of the frameworks which use template literals for their templating.

Template Literals are a really nice JavaScript feature you may not have used much yet, they look a bit like strings:

const message = `Hello World`;

message === "Hello World"

You can include new lines:

const message = `Hello
World`;

message === "Hello\nWorld"

You can use the dollar-curly-brace ${} syntax to inject variables:

const name = 'Ada';

const message = `Hello ${name}`;

This works really well when combined with Arrow Function Expressions to make templating functions, which turn the arguments into a string:

const messageFn = name => `Hello ${name}`;

const message = messageFn("Ada");

Tagged Template Literals

You can put a tag on a template to transform the template before it gets turned into a string.

The tag is a function which is called with the first argument being an array of the rest of the arguments are the values of the place holders. In the example below we use the rest parameter to put all of the place holder arguments into an array.

There is always one more string than the number of placeholders. You can reassemble the output by interleaving these Arrays such that for a template with N placeholders the output is:

strings[0] + placeholders[0] + strings[1] + placeholders[1] + … + strings[N] + placeholders[N] + strings[N+1];

This is what is looks like in JavaScript:

function myTag(strings, ...placeholders) {
  const N = placeholders.length;
  let out = '';
  for (let i=0; i<N;i++) {
   out += strings[i] + placeholders[i];
  }
  out += strings[N];
  return out;
}

const message = myTag`Hello ${1} world ${2}.`

This function is equivalent to the String.raw function which is the default behaviour for template literals.


const message = String.raw`Hello ${1} world ${2}.`

You can also use String.raw inside your custom template tag to regenerate a string. In the example below we check the input to make sure it’s a string then use String.raw to output the data as a String.

function myTag(strings, ...placeholders) {

  for (const placeholder of placeholders) {
    if (typeof placeholder !== 'string') {
      throw Error('Invalid input');
    }
  }

  return String.raw(strings, ...placeholders);
}

Your tagged template literal doesn’t have to return a String it can return what ever you need, here is a very simple tag which measures the length of the input:

function myTag(a, ...b) {
  return String.raw(a, ...b).length;
}

HTML & Tagged Template Literals

Template literals are great for HTML because you can add newlines and very cleanly have dynamic classes and other attributes.

const myHTMLTemplate = (title, class) => `
  <!DOCTYPE html>
  <html>
    <head><title>${title}</title></head>
    <body class="${class}">
      ...
`;

If you use Visual Studio Code the Lit-HTML extension will add syntax highlighting and HTML intellisense features and emmet shortcuts for templates tagged with a tag called html . The html tag doesn’t have to be the one from the lit-html library even using String.raw will give you the really nice features of HTML inside a JavaScript or TypeScript file.

HTML syntax highlighting in a JS file

Sanitising HTML with a Tagged Template Literal

When you are outputting HTML that may contain user generated content you have to be careful about malicious JavaScript users may try into inject into all kinds of elements, these kinds of attacks are known as cross-site scripting aka XSS.

It’s best to strip out dangerous elements and attributes. You can do that in a template literal tag using a library like html-parser2.

We want to have two types of input into the placeholder, raw text strings which needs sanitising and safe HTML which is either authored by us or has been put through the sanitiser. This class just stores a string and we can use it to mark strings that are safe.

class SafeHTML {
    constructor (inStr) {
        this.string = inStr;
        this[Symbol.toPrimitive] = function (hint) {
            return this.string;
        }
    }
}

Then we have our template literal tag function, this does nothing to SafeHTML objects and sanitises raw strings returning a new SafeHTML from our template literal.

const html = (stringArray,...placeholders)=>{
    const sanitisedHTMLArray = placeholders.map(
        p => p instanceof SafeHTML ? p : stripHTML(p)
    );
    const out = String.raw(stringArray, ...sanitisedHTMLArray);
    return new SafeHTML(out);
}

To strip the HTML first I listed all the elements I wanted to allow and the attributes which are safe, these are mostly all used for formatting or semantics.

const allowedTagAttributes = {
 a: ["href"],
 b: [],
 i: [],
 img: ["src", "alt", "title"],
 abbr: ["title"],
 ul: [],
 li: [],
 h1: [],
 h2: [],
 h3: [],
 h4: [],
 h5: [],
 h6: [],
 hr: [],
 figure: [],
 figcaption: [],
 p: [],
 u: [],
 s: [],
 ruby: [],
 small: [],
 span: [],
 del: [],
 strong: [],
 table: [],
 thead: [],
 tbody: [],
 tr: [],
 td: [],
 time: [],
 ol: [],
};

const allowedTags = *Object*.keys(allowedTagAttributes);

Then we use htmlparser2 to go through the input text string and rebuild the HTML string using just the allowed elements:

function stripHTML(inStr) {
 const textOut = [];
 const parser = new htmlparser2.Parser(
  {

   onopentag(tagname, attribs) {
    if (allowedTags.includes(tagname)) {
     const allowedAttribs = allowedTagAttributes[tagname];
     if (tagname === "a") {
      attribs.href = sanitiseURL(attribs.href);
     }

     textOut.push(
      `<${tagname} ${
       allowedAttribs
       .map((key) => attribs[key] ? `${key}=${attribs[key]}` : "")
       .join(" ")}>`
     );
    }
   },

   ontext(text) {
    textOut.push(text);
   },

   onclosetag(tagname) {
    if (allowedTags.includes(tagname)) {
     textOut.push(`</${tagname}>`);
    }
   },

  },
  { decodeEntities: false }
 );

 parser.write(inStr);
 parser.end();
 return textOut.join("");
}

When we use the html tag function we just created we can now seperate our authored HTML from users unsafe HTML.

const unsafe = `<img onmouseenter="location.href='[https://example.com'](https://example.com')" src="[http://placekitten.com/200/300](http://placekitten.com/200/300)" />`;

const safeHTML = html`

<style>
div {
  color: red;
}
</style>

<div>User Content: ${unsafe}.</div>

`;

Using template literals with JS frameworks

If you need more functionality than basic templating there are some really light and fast frameworks which use template literals.

lit-html is pretty well known and designed to work with the polymer web component framework.
Polymer/lit-html
Efficient, Expressive, Extensible HTML templates in JavaScript Full documentation is available at… github.com

lighter-html is designed to be really fast and very small. It’s really well featured and a great way to build a really fast web site.
WebReflection/lighterhtml
Social Media Photo by Kristine Weilert on Unsplash The hyperHTML strength & experience without its complexity 🎉 I am… github.com

By Ada Rose Cannon on October 6, 2020.

Canonical link

Isomorphic ES Modules

Ada Rose Cannon 🏳️‍🌈 — Mon, 18 Jun 2018 10:36:43 +0000

Aka, One weird trick to share node_modules with browser side scripts.

Earlier I demonstrated how to build a Single Page App which shares templates with the Server Side Code. (See the video below.)

We share the web app’s templates to enable the first page load to be pre-rendered on the server. This practice lets Web Apps start faster and be more resilient to network failure.

In the live coding session we use the new EcmaScript (ES) Modules because it allows us to share code directly without using work-arounds such as making bundles using WebPack or Browserify.

ES Modules have really high level of browser support in spite of being so new. Support for ES Modules is now up to 70%! And support for Samsung Internet will be coming in a release in the near future.

Final source code from the video demo: https://glitch.com/edit/#!/ada-isomorphic?path=server.js:2:20

Defining the terms ES Modules and Isomorphic

ES Modules — Noun.

You may already be using a module system in the way you work. If you are a web developer who works in node there is a good chance you have encountered CommonJS modules. CommonJS modules allow you to acquire snippets of JavaScript from other JavaScript files. For example:

const formatDate = require('./time-utils/format-date.js');

There is also the ability to pull JavaScript code from files provided by the npm packaging system.

const express = require('express');

These examples also can be used in the browser by using bundling tools like rollup, browserify or webpack. This can result in shipping a large bundle of code to the browser rather than loading them when they are needed unless one sets your development environment to split your code automatically.

ES Modules, are similar to CommonJS modules in that they allow us to acquire snippets of JavaScript from other JavaScript files, except this time it is designed to work in the browser, over the network. For example:

<script type="module"> 
  import formatDate from 'https://site.com/time-utils/format.js';
  formatDate(Date.now());
</script>

or from a local URL:

<script type="module">
  import formatDate from './time-utils/format.js';
  formatDate(Date.now());
</script>

We will explore some the differences between CommonJS modules and ES modules throughout this article.

Isomorphic— Adjective.

Code written in an isomorphic fashion has the property of being able to perform its function in both a node server and in the web browser.

This has the benefit of not having to reimplement logic which needs to happen on both the client and the server. Having to rewrite logic in two different languages can result in differing behaviour, or the logic slowly diverging over time as changes are made to each file independently.

Using ES Modules to write a Single Page Application with Server Side Rendering for the first load.

I will use the shorthand SSR *to refer to Server Side Rendering and *SPA to refer to Single Page Apps throughout this article .

An ideal web app experience is one which starts fast and then becomes a seamless native-like experience. One which responds quickly to interactions, has seamless transitions between pages and never needs to reload the page.

A website built as a SPA behaves beautifully but often requires a large JavaScript bundle to be downloaded before the first render can happen. Server Side Rendering allows us to display the content the user needs before the JavaScript has downloaded.

NB! This can have a side effect of having a website which looks loaded but is unresponsive because the JavaScript is still being downloaded and parsed. Therefore it is important that all links on your web site work and go to another page which can then be rendered on the server.

This is my plan for building the app in this fashion:

Setup Client Side Rendering.
Get the Client Side Rendering to update the page when I press links.
Import the client side templates on the server.
Get the server to render the same pages at the same URLs.

If you are doing this yourself it doesn’t matter whether you do the client side first or the server side. My personal preference is to build a great SSR experience and then enhance it to a Single Page App.

In this example I start of making a SPA and give it fast loading through SSR as an enhancement, because today many developers like to start off with the client side first and I wanted this to be representative of their experience. (Also it puts the more complex parts for SSR at the end, thus bringing this article to a satisfying conclusion.)

1. Setup Client Side Rendering

Our first task here is to pick an appropriate framework (or none if you’d prefer.) For our purposes it must have the following properties: be able to run on the client and the server and be able to be loaded via ES modules.

Since ES Modules are still very new, there isn’t universal support for them yet; many libraries only provide CommonJS or UMD modules. Fortunately many larger, well supported projects provide both CommonJS modules and an ES module version.

We are going to go with HyperHTML for this example but hopefully the problems we encounter and solve are applicable to your framework of choice. Of course this gets even simpler if you have no framework at all.

I like HyperHTML because it is very fast, it is very tiny (4.6kb minified and compressed) and there is a compatible library for the server called ViperHTML which we can use there.

So first we install HyperHTML via npm:

npm install --save hyperhtml

Now we have to access it in the web browser. To do this I have to expose the files via my web server. In this case I am using express:

app.use('/node_modules/', express.static('./node_modules'));

Now I can access any file in my node_modules directory on the client. I can import HyperHTML from the esm directory on the server:

<script type="module">

  // `wire` is used for making templates in HyperHTML
  // `bind` is for writing those templates to the DOM
  import {wire, bind} from '/node_modules/hyperhtml/esm/index.js';

  // HyperHTML describes its templates using template literals
  const myTemplate = wire()`<h1>My Template</h1>`;

  // We use `bind` to render it.
  const render = bind(document.body);
  render`This is my template: ${myTemplate}`;
</script>

The code we will share between the client and the server is the templates. They will contain logic to fetch information and display it in lists. I will store it in a seperate .js file to be referenced by both the client and the server:

// in templates.js

import {wire} from '/node_modules/hyperhtml/esm/index.js';

const myTemplate = wire()`<h1>My Template</h1>`;

export {
  myTemplate
};

We can then import this file as usual in our script:

<!-- In main.html -->

<script type="module">
  import { bind } from '/node_modules/hyperhtml/esm/index.js';
  import { myTemplate } from './templates.js';

  const render = bind(document.body);
  render`This is my template: ${myTemplate}`;
</script>

2. Responding to click events.

Once we have written templates from our app we probably have links which should change the URL and render something different.

These links should include the appropriate app state information to allow us to do server side rendering later. Even though it is a Single Page App, something page-like should result in changing the ‘/path’ and state should be passed via query parameters.

NB! In addition the URL shouldn’t just be a hash url. i.e. Search because a URL like that won’t trigger the page load needed for server side rendering in case the script hasn’t loaded or has an error.

Once one of the ‘a’ tags are clicked we can intercept it and respond appropriately:

window.addEventListener('click', e => {
  if (e.target.tagName === 'A' && e.target.href) {
    const url = new URL(e.target.href);
    const parameters = new URLSearchParams(url.search);

    // ... Some logic to check to see if this should be handled
    // within the Single Page App ...

    render`${someTemplate(someData)}`

    // Prevent the page from reloading
    e.preventDefault();
  }
});

If you are using

tags for traversing the site, e.g. search functionalities, then you will need to intercept and handle those too.

They can be a little more complex since you will need to validate the form and respond appropriately but the principal is the same as for handling link clicks. Remember the e.preventDefault() otherwise the page will reload anyway.

But now we should have a basic Single Page App using our templates.

Unfortunately users are unable to refresh the page or share the URL because we have not updated the URL bar so we should added some logic to handle that.

window.addEventListener('click', e => {

    // ... Our click handling logic ...

    // Update the URL Bar
    history.pushState({feed}, 'Some title', e.target.href);

    render`${someTemplate(someData)}`

    // Prevent the page from reloading
    e.preventDefault();
  }
});

window.addEventListener('popstate', function () {
  if (history.state) {
     renderToMain`${myTemplate(history.state.feed)}`;
  }
});

The history handling logic is the simplest possible case. If you are relying on some kind of asynchronous operation which may fail, like network events, the logic may be more complicated to handle returning to the old URL if the async operation fails.

3. Using ES Modules in the Node Server

Node modules by default use CommonJS for importing modules. If you try using import in node you will get an error because node doesn’t yet understand ES Modules.

Fortunately there is solution. The node module esm allows us to use imports in the browser just by changing the way we launch the app.

npm install --save esm

Then we can change our start script to invoke node with -r esm. For example this is how I start node in my package.json:

"scripts": {
  "start": "node -r esm server.js"
},

Esm allows us to use ES modules side by side with CommonJS. These two commands are equivalent:

const path = require('path');

import path from 'path';

So let’s import our templates:

import { myTemplate } from './static/templates.js'

This would normally work great for JavaScript dependencies in the same directory but in the case of depending on files from our /node_modules directory node will try to find that by the path /node_modules which is not a real directory along side the script. It is actually somewhere else.

As a result importing our template.js file is going to error because ./static/templates.js is depends on /node_modules/hyperhtml/esm/index.js, which doesn’t resolve to a valid path in node.

In addition, on the server we want to use viperhtml, the node version of hyperhtml.

In the video above, I solve this by creating a proxy file /static/scripts/hyper/index.js which gets loaded in node:

import {wire, bind} from 'viperhtml';
export {
  wire, bind
}

When I try to load /static/scripts/hyper/* on the client side, express intercepts the route and returns /node_modules/hyperhtml/esm/index.js as before.

This works, but is a little messy. Fortunately since recording the video, Andrea Giammarchi has come up with a neater solution by creating an additional loader which changes the path to rewrite import module from '/m/module/index.js' to import module from 'module/index.js' which works on the node side.
esm-iso *Isomorphic ESM Loader*www.npmjs.com

In case you preferto use /node_modules/ for your URL to access node modules like I do in my examples, I forked it to map import module from '/node_modules/module/index.js' to import module from 'module/index.js'
slash-node-modules-loader *Use with -r slash-node-modules-loader to be able to require from require('/node_modules/:somedir/somefile.js') to have…*www.npmjs.com

There is an example demo showing how to use this here: https://glitch.com/edit/#!/isomorphic?path=server.js:19:0

These modules allow, any imports to /m/something or /node_modules/something to resolve correctly. Without needing to do any clever rewrites.

We still have to do a redirect for the case where the node library and the browser library are different. In this situation our JavaScript module should require the server side version, we can then add a route in the networking to redirect to the client side version when it is tried to be loaded.

// main.js

// This works fine when loaded on the server
import myLibrary from '/node_modules/node-my-library';

On the server we instead of serving node-my-library we serve browser-my-library instead so the browser version uses the correct file.

// server.js
...
app.use(
  '/node_modules/node-my-library',
   express.static('/node_modules/browser-my-library')
)

app.use(
  '/node_modules',
  express.static('./node_modules')
)

4. Using the templates on the server

This step will vary depending on the framework you are using, but here is how we render with viperHTML on the server:

import {myTemplate} from './static/templates.js';
import viperHTML from 'viperhtml';
import fetch from 'node-fetch';

// Make the browser fetch work in node
global.fetch = fetch;

// Async version of bind() for writing to the network
const asyncRender = viperHTML.async();


const indexFile = fs.readFileSync('./static/index.html', 'utf8').split('<!-- render here -->');

app.get('/', (req,res) => {

  // Set the content type header
  res.set({ 'content-type': 'text/html; charset=utf-8' });

  // Use viperhtml's to render and pipe over the network
  (asyncRender(chunk => res.write(chunk))`
    ${{html: indexFile[0]}}
    ${myTemplate(req.query.foo)}
    ${{html: indexFile[1]}}
  `)
  .then(() => res.end())
});

We render the template according to what the url’s query parameter was by passing the foo query parameter into the template req.query.foo

Final source code from the video demo: https://glitch.com/edit/#!/ada-isomorphic?path=server.js:2:20

Thanks for reading

This article tries to compress a lot of complex ideas into short paragraphs. I also gloss over details not relating to using ES Modules, You can see more detail and the logic grow more organically by watching the video.

Thank you to Andrea Giammarchi for helping with HyperHTML and coming up with the node rewriting module. I hope we’ll see a lot more usage of ES Modules in the browser and on the server soon.