Surma on web.dev

Deep-copying in JavaScript using structuredClone

2021-12-16T00:00:00Z

For the longest time, you had to resort to workarounds and libraries to create a deep copy of a JavaScript value. The Platform now ships with structuredClone(), a built-in function for deep-copying.

Browser support

Chrome 98, Supported 98
Firefox 94, Supported 94
Edge 98, Supported 98
Safari 15.4, Supported 15.4

Source

Shallow copies #

Copying a value in JavaScript is almost always shallow, as opposed to deep. That means that changes to deeply nested values will be visible in the copy as well as the original.

One way to create a shallow copy in JavaScript using the object spread operator ...:

const myOriginal = {
  someProp: "with a string value",
  anotherProp: {
    withAnotherProp: 1,
    andAnotherProp: true
  }
};

const myShallowCopy = {...myOriginal};

Adding or changing a property directly on the shallow copy will only affect the copy, not the original:

myShallowCopy.aNewProp = "a new value";
console.log(myOriginal.aNewProp)
// ^ logs `undefined`

However, adding or changing a deeply nested property affects both the copy and the original:

myShallowCopy.anotherProp.aNewProp = "a new value";
console.log(myOriginal.anotherProp.aNewProp) 
// ^ logs `a new value`

The expression {...myOriginal} iterates over the (enumerable) properties of myOriginal using the Spread Operator. It uses the property name and value, and assigns them one by one to a freshly created, empty object. As such, the resulting object is identical in shape, but with its own copy of the list of properties and values. The values are copied, too, but so-called primitive values are handled differently by the JavaScript value than non-primitive values. To quote MDN:

In JavaScript, a primitive (primitive value, primitive data type) is data that is not an object and has no methods. There are seven primitive data types: string, number, bigint, boolean, undefined, symbol, and null.

MDN — Primitive

Non-primitive values are handled as references, meaning that the act of copying the value is really just copying a reference to the same underlying object, resulting in the shallow copy behavior.

Deep copies #

The opposite of a shallow copy is a deep copy. A deep copy algorithm also copies an object’s properties one by one, but invokes itself recursively when it finds a reference to another object, creating a copy of that object as well. This can be very important to make sure that two pieces of code don’t accidentally share an object and unknowingly manipulate each others’ state.

There used to be no easy or nice way to create a deep-copy of a value in JavaScript. Many people relied on third-party libraries like Lodash’s cloneDeep() function. Arguably the most common solution to this problem was a JSON-based hack:

const myDeepCopy = JSON.parse(JSON.stringify(myOriginal));

In fact, this was such a popular workaround, that V8 aggressively optimized JSON.parse() and specifically the pattern above to make it as fast as possible. And while it is fast, it comes with a couple of shortcomings and tripwires:

Recursive data structures: JSON.stringify() will throw when you give it a recursive data structure. This can happen quite easily when working with linked lists or trees.
Built-in types: JSON.stringify() will throw if the value contains other JS built-ins like Map, Set, Date, RegExp or ArrayBuffer.
Functions: JSON.stringify() will quietly discard functions.

Structured cloning #

The platform already needed the ability to create deep copies of JavaScript values in a couple of places: Storing a JS value in IndexedDB requires some form of serialization so it can be stored on disk and later deserialized to restore the JS value. Similarly, sending messages to a WebWorker via postMessage() requires transferring a JS value from one JS realm to another. The algorithm that is used for this is called “Structured Clone”, and until recently, wasn’t easily accessible to developers.

That has now changed! The HTML spec was amended to expose a function called structuredClone() that runs exactly that algorithm as a means for developers to easily create deep copies of JavaScript values.

const myDeepCopy = structuredClone(myOriginal);

That’s it! That’s the entire API. If you want to dive deeper into the details, take a look at the MDN article.

Features and limitations #

Structured cloning addresses many (although not all) shortcomings of the JSON.stringify() technique. Structured cloning can handle cyclical data structures, support many built-in data types and is generally more robust and often faster.

However, it still has some limitations that may catch you off-guard:

Prototypes: If you use structuredClone() with a class instance, you’ll get a plain object as the return value, as structured cloning discards the object’s prototype chain.
Functions: If your object contains functions, they will be quietly discarded.
Non-cloneables: Some values are not structured cloneable, most notably Error and DOM nodes. It will cause structuredClone() to throw.

If any of these limitations are a deal-breaker for your use-case, libraries like Lodash still provide custom implementations of other deep-cloning algorithms that may or may not fit your use-case.

Performance #

While I haven’t done a new micro-benchmark comparison, I did a comparison in early 2018, before structuredClone() was exposed. Back then, JSON.parse() was the fastest option for very small objects. I expect that to remain the same. Techniques that relied on structured cloning were (significantly) faster for bigger objects. Considering that the new structuredClone() comes without the overhead of abusing other APIs and is more robust than JSON.parse(), I recommend you make it your default approach for creating deep copies.

Conclusion #

If you need to create a deep-copy of a value in JS—maybe that be because you use immutable data structures or you want to make sure a function can manipulate an object without affecting the original—you no longer need to reach for workarounds or libraries. The JS ecosystem now has structuredClone(). Huzzah.

Introducing libSquoosh

2021-06-08T00:00:00Z

We are happy to introduce libSquoosh, an experimental Node library on top of which the Squoosh CLI is built, giving you all the capabilities for the Squoosh CLI with a JavaScript-idiomatic interface.

Squoosh.app is a PWA that compresses images for you in the browser. It supports many old and new image formats and processes them client-side in the browser through WebAssembly. This means your pictures stay safely on your own computer rather than being sent to a server somewhere, and that Squoosh works even when offline.

At Chrome DevSummit 2020 we announced Squoosh v2, together with the Squoosh CLI to bring all the codecs of Squoosh to the command-line using Node and WebAssembly. This allows you to compress entire folders with one command and make use of the CLI's to let it choose the codec parameters for you.

The CLI enables a lot of automation and so it's only natural that developers began asking for a more idiomatic interface than programmatically invoking the Squoosh CLI via the shell. Anton (@atjn on GitHub) stepped up to the task and separated the Squoosh CLI code into two parts: The command line interface code and the underlying core functionality.

import { ImagePool } from "@squoosh/lib";

// libSquoosh uses a worker-pool under the hood
// to parallelize all image processing.
const imagePool = new ImagePool();

// Accepts both file paths and Buffers/TypedArrays.
const image = imagePool.ingestImage("./squoosh.jpeg");

// Optional.
// await image.preprocess({
//   resize: {
//     enabled: true,
//     width: 128,
//   },
// });

await image.encode({
  // All codecs are initialized with default values
  // that can be individually overwritten.
  mozjpeg: {
    quality: 10,
  },
  avif: {
    cqLevel: 10,
  },
  jxl: {},
});

const { extension, binary } = await image.encodedWith.mozjpeg;
await fs.writeFile(`output.${extension}`, binary);
// ... same for other encoders ...

await imagePool.close();

Our goal is to make image compression more accessible to tooling authors. We hope to see integration into Webpack, Rollup and other build tools to make sure your images are appropriately optimized for the web.

I'd like to express a huge "thank you" to Anton for the time he has committed to Squoosh!

It's still early for the Squoosh CLI and libSquoosh and we have many more ideas and plans that we'd like to implement. In the meanwhile, try libSquoosh! However, be mindful that this is an early, experimental release and that there is a good chance you will run into some bugs. If you find some or have questions, please open an issue.

If you are interested in contributing to Squoosh—for example contributing to the extremely sparse documentation around libSquoosh or help with any of the other parts of the app—we are starting a mentorship program to help you get started. If you want to know more, check out our tracking issue.

Pixel-perfect rendering with devicePixelContentBox

2020-07-07T00:00:00Z

Since Chrome 84, ResizeObserver supports a new box measurement called devicePixelContentBox, that measures the element's dimension in physical pixels. This enables rendering pixel-perfect graphics, especially in the context of high-density screens.

Browser support

Chrome 84, Supported 84
Firefox 93, Supported 93
Edge 84, Supported 84
Safari, Not supported

Background: CSS pixels, canvas pixels, and physical pixels #

While we often work with abstract units of length like em, % or vh, it all boils down to pixels. Whenever we specify the size or position of an element in CSS, the browser's layout engine will eventually convert that value to pixels (px). These are "CSS Pixels", which have a lot of history and only have a loose relationship with the pixels you have on your screen.

For a long time, it was fairly reasonable to estimate anyone's screen pixel density with 96DPI ("dots per inch"), meaning any given monitor would have roughly 38 pixels per cm. Over time, monitors grew and/or shrunk or started to have more pixels on the same surface area. Combine that with the fact that lots of content on the web define their dimensions, including font sizes, in px, and we end up with illegible text on these high-density ("HiDPI") screens. As a counter-measure, browsers hide the monitor's actual pixel density and instead pretend that the user has a 96 DPI display. The px unit in CSS represents the size of one pixel on this virtual 96 DPI display, hence the name "CSS Pixel". This unit is only used for measurement and positioning. Before any actual rendering happens, a conversion to physical pixels happens.

How do we go from this virtual display to the user's real display? Enter devicePixelRatio. This global value tells you how many physical pixels you need to form a single CSS pixel. If devicePixelRatio (dPR) is 1, you are working on a monitor with roughly 96DPI. If you have a retina screen, your dPR is probably 2. On phones it is not uncommon to encounter higher (and weirder) dPR values like 2, 3 or even 2.65. It is essential to note that this value is exact, but doesn't let you derive the monitor's actual DPI value. A dPR of 2 means that 1 CSS pixel will map to exactly 2 physical pixels.

Example

My monitor has a dPR of 1 according to Chrome…

It has 3440 pixels in width and the display area is 79cm wide. That leads to a resolution of 110 DPI. Close to 96, but not quite. That is also the reason why a <div style="width: 1cm; height: 1cm"> will not exactly measure 1cm in size on most displays.

Finally, dPR can also be affected by your browser's zoom feature. If you zoom in, the browser increases the reported dPR, causing everything to render bigger. If you check devicePixelRatio in a DevTools Console while zooming, you can see fractional values appear.

DevTools showing a variety of fractional devicePixelRatio due to zooming.

Let's add the <canvas> element to the mix. You can specify how many pixels you want the canvas to have using the width and height attributes. So <canvas width=40 height=30> would be a canvas with 40 by 30 pixels. However, this does not mean that it will be displayed at 40 by 30 pixels. By default, the canvas will use the width and height attribute to define its intrinsic size, but you can arbitrarily resize the canvas using all the CSS properties you know and love. With everything we have learned so far, it might occur to you that this will not be ideal in every scenario. One pixel on the canvas might end up covering multiple physical pixels, or just a fraction of a physical pixel. This can lead to unpleasing visual artifacts.

To summarize: Canvas elements have a given size to define the area that you can draw on. The number of canvas pixels is completely independent from the canvas' display size, specified in CSS pixels. The number of CSS pixels is not the same as the number of physical pixels.

Pixel perfection #

In some scenarios, it is desirable to have an exact mapping from canvas pixels to physical pixels. If this mapping is achieved, it's called "pixel-perfect". Pixel-perfect rendering is crucial for legible rendering of text, especially when using subpixel rendering or when displaying graphics with tightly aligned lines of alternating brightness.

To achieve something as close to a pixel-perfect canvas as possible on the web, this has been more or less the go-to approach:

<style>
  /* … styles that affect the canvas' size … */
</style>
<canvas id="myCanvas"></canvas>
<script>
  const cvs = document.querySelector('#myCanvas');
  // Get the canvas' size in CSS pixels
  const rectangle = cvs.getBoundingClientRect();
  // Convert it to real pixels. Ish.
  cvs.width = rectangle.width * devicePixelRatio;
  cvs.height = rectangle.height * devicePixelRatio;
  // Start drawing…
</script>

The astute reader might be wondering what happens when dPR is not an integer value. That is a good question and exactly where the crux of this entire problem lies. In addition, if you specify an element's position or size using percentages, vh, or other indirect values, it is possible that they will resolve to fractional CSS pixel values. An element with margin-left: 33% can end up with a rectangle like this:

DevTools showing fractional pixel values as a result of a getBoundingClientRect() call.

CSS pixels are purely virtual, so having fractions of a pixel is okay in theory, but how does the browser figure out the mapping to physical pixels? Because fractional physical pixels are not a thing.

Pixel snapping #

The part of the unit conversion process that takes care of aligning elements with physical pixels is called "pixel snapping", and it does what it says on the tin: It snaps fractional pixel values to integer, physical pixel values. How exactly this happens is different from browser to browser. If we have an element with a width of 791.984px on a display where dPR is 1, one browser might render the element at 792px physical pixels, while another browser might render it at 791px. That's just a single pixel off, but a single pixel can be detrimental to renderings that need to be pixel-perfect. This can lead to blurriness or even more visible artifacts like the Moiré effect.

The top image is a raster of differently colored pixels. The bottom image is the same as above, but the width and height have been reduced by one pixel using bilinear scaling. The emerging pattern is called the Moiré effect.
(You might have to open this image in a new tab to see it without any scaling applied to it.)

`devicePixelContentBox` #

devicePixelContentBox gives you an element's content box in device pixel (i.e. physical pixel) units. It's part of ResizeObserver. While ResizeObserver is now supported in all major browsers since Safari 13.1, the devicePixelContentBox property is only in Chrome 84+ for now.

As mentioned in ResizeObserver: it's like document.onresize for elements, the callback function of a ResizeObserver will be called before paint and after layout. That means that the entries parameter to the callback will contain the sizes of all observed elements just before they are being painted. In the context of our canvas problem outlined above, we can use this opportunity to adjust the number of pixels on our canvas, ensuring that we end up with an exact one-to-one mapping between canvas pixels and physical pixels.

const observer = new ResizeObserver((entries) => {
  const entry = entries.find((entry) => entry.target === canvas);
  canvas.width = entry.devicePixelContentBoxSize[0].inlineSize;
  canvas.height = entry.devicePixelContentBoxSize[0].blockSize;

  /* … render to canvas … */
});
observer.observe(canvas, {box: ['device-pixel-content-box']});

The box property in the options object for observer.observe() lets you define which sizes you wish to observe. So while each ResizeObserverEntry will always provide borderBoxSize, contentBoxSize and devicePixelContentBoxSize (provided the browser supports it), the callback will only be invoked if any of the observed box metrics change.

With this new property, we can even animate our canvas' size and position (effectively guaranteeing fractional pixel values), and not see any Moiré effects on the rendering. If you would like to see the Moiré effect on the approach using getBoundingClientRect(), and how the new ResizeObserver property allows you to avoid it, take a look at the demo in Chrome 84 or later!

Feature detection #

To check if a user's browser has support for devicePixelContentBox, we can observe any element, and check if the property is present on the ResizeObserverEntry:

function hasDevicePixelContentBox() {
  return new Promise((resolve) => {
    const ro = new ResizeObserver((entries) => {
      resolve(entries.every((entry) => 'devicePixelContentBoxSize' in entry));
      ro.disconnect();
    });
    ro.observe(document.body, {box: ['device-pixel-content-box']});
  }).catch(() => false);
}

if (!(await hasDevicePixelContentBox())) {
  // The browser does NOT support devicePixelContentBox
}

Conclusion #

Pixels are a surprisingly complex topic on the web and up until now there was no way for you to know the exact number of physical pixels an element occupies on the user's screen. The new devicePixelContentBox property on a ResizeObserverEntry gives you that piece of information and allows you to do pixel-perfect renderings with <canvas>. devicePixelContentBox is supported in Chrome 84+.

Use web workers to run JavaScript off the browser's main thread

2019-12-05T00:00:00Z

In the past 20 years, the web has evolved dramatically from static documents with a few styles and images to complex, dynamic applications. However, one thing has remained largely unchanged: we have just one thread per browser tab (with some exceptions) to do the work of rendering our sites and running our JavaScript.

As a result, the main thread has become incredibly overworked. And as web apps grow in complexity, the main thread becomes a significant bottleneck for performance. To make matters worse, the amount of time it takes to run code on the main thread for a given user is almost completely unpredictable because device capabilities have a massive effect on performance. That unpredictability will only grow as users access the web from an increasingly diverse set of devices, from hyper-constrained feature phones to high-powered, high-refresh-rate flagship machines.

If we want sophisticated web apps to reliably meet performance guidelines like the Core Web Vitals—which is based on empirical data about human perception and psychology—we need ways to execute our code off the main thread (OMT).

Why web workers? #

JavaScript is, by default, a single-threaded language that runs tasks on the main thread. However, web workers provide a sort of escape hatch from the main thread by allowing developers to spin up separate threads to handle work off of the main thread. While the scope of web workers is limited and doesn't offer direct access to the DOM, they can be hugely beneficial if there is considerable work that needs to be done that would otherwise overwhelm the main thread.

Where Core Web Vitals are concerned, running work off the main thread can be beneficial. In particular, offloading work from the main thread to web workers can reduce contention for the main thread, which can improve important responsiveness metrics such as Interaction to Next Paint (INP) and First Input Delay (FID). When the main thread has less work to process, it can respond more quickly to user interactions.

Less main thread work—especially during startup—also carries a potential benefit for Largest Contentful Paint (LCP) by reducing long tasks. Rendering an LCP element requires main thread time—either for rendering text or images, which are frequent and common LCP elements—and by reducing main thread work overall, you can ensure that your page's LCP element is less likely to be blocked by expensive work that a web worker could handle instead.

Threading with web workers #

Other platforms typically support parallel work by allowing you to give a thread a function, which runs in parallel with the rest of your program. You can access the same variables from both threads, and access to these shared resources can be synchronized with mutexes and semaphores to prevent race conditions.

In JavaScript, we can get roughly similar functionality from web workers, which have been around since 2007 and supported across all major browsers since 2012. Web workers run in parallel with the main thread, but unlike OS threading they can't share variables.

To create a web worker, pass a file to the worker constructor, which starts running that file in a separate thread:

const worker = new Worker("./worker.js");

Communicate with the web worker by sending messages via the postMessage API. Pass the message value as a parameter in the postMessage call and then add a message event listener to the worker:

`main.js` #

const worker = new Worker("./worker.js");
worker.postMessage([40, 2]);

`worker.js` #

addEventListener("message", event => {
  const [a, b] = event.data;
  // Do stuff with the message
});

To send a message back to the main thread, use the same postMessage API in the web worker and set up an event listener on the main thread:

`main.js` #

const worker = new Worker("./worker.js");
worker.postMessage([40, 2]);
worker.addEventListener("message", event => {
  console.log(event.data);
});

`worker.js` #

addEventListener("message", event => {
  const [a, b] = event.data;
  // Do stuff with the message
  postMessage(a+b);
});

Admittedly, this approach is somewhat limited. Historically, web workers have mainly been used for moving a single piece of heavy work off the main thread. Trying to handle multiple operations with a single web worker gets unwieldy quickly: you have to encode not only the parameters but also the operation in the message, and you have to do bookkeeping to match responses to requests. That complexity is likely why web workers haven't been adopted more widely.

But if we could remove some of the difficulty of communicating between the main thread and web workers, this model could be a great fit for many use cases. And, luckily, there's a library that does just that!

Comlink: making web workers less work #

Comlink is a library whose goal is to let you use web workers without having to think about the details of postMessage. Comlink lets you to share variables between web workers and the main thread almost like other programming languages that support threading.

You set up Comlink by importing it in a web worker and defining a set of functions to expose to the main thread. You then import Comlink on the main thread, wrap the worker, and get access to the exposed functions:

`worker.js` #

import {expose} from "comlink";

const api = {
  someMethod() { /* … */ }
}
expose(api);

`main.js` #

import {wrap} from "comlink";

const worker = new Worker("./worker.js");
const api = wrap(worker);

The api variable on main thread behaves the same as the one in the web worker, except that every function returns a promise for a value rather than the value itself.

What code should you move to a web worker? #

Web workers don't have access to the DOM and many APIs like WebUSB, WebRTC, or Web Audio, so you can't put pieces of your app that rely on such access in a worker. Still, every small piece of code moved to a worker buys more headroom on the main thread for stuff that has to be there—like updating the user interface.

One problem for web developers is that most web apps rely on a UI framework like Vue or React to orchestrate everything in the app; everything is a component of the framework and so is inherently tied to the DOM. That would seem to make it difficult to migrate to an OMT architecture.

However, if we shift to a model in which UI concerns are separated from other concerns, like state management, web workers can be quite useful even with framework-based apps. That's exactly the approach taken with PROXX.

PROXX: an OMT case study #

The Google Chrome team developed PROXX as a Minesweeper clone that meets Progressive Web App requirements, including working offline and having an engaging user experience. Unfortunately, early versions of the game performed poorly on constrained devices like feature phones, which led the team to realize that the main thread was a bottleneck.

The team decided to use web workers to separate the game's visual state from its logic:

The main thread handles rendering of animations and transitions.
A web worker handles game logic, which is purely computational.

OMT had interesting effects on PROXX's feature phone performance. In the non-OMT version, the UI is frozen for six seconds after the user interacts with it. There's no feedback, and the user has to wait for the full six seconds before being able to do something else.

UI response time in the non-OMT version of PROXX.

In the OMT version, however, the game takes twelve seconds to complete a UI update. While that seems like a performance loss, it actually leads to increased feedback to the user. The slowdown occurs because the app is shipping more frames than the non-OMT version, which isn't shipping any frames at all. The user therefore knows that something is happening and can continue playing as the UI updates, making the game feel considerably better.

UI response time in the OMT version of PROXX.

This is a conscious tradeoff: we give users of constrained devices an experience that feels better without penalizing users of high-end devices.

Implications of an OMT architecture #

As the PROXX example shows, OMT makes your app reliably run on a wider range of devices, but it doesn't make your app faster:

You're just moving work from the main thread, not reducing the work.
The extra communication overhead between the web worker and the main thread can sometimes make things marginally slower.

Considering the tradeoffs #

Since the main thread is free to process user interactions like scrolling while JavaScript is running, there are fewer dropped frames even though total wait time may be marginally longer. Making the user wait a bit is preferable to dropping a frame because the margin of error is smaller for dropped frames: dropping a frame happens in milliseconds, while you have hundreds of milliseconds before a user perceives wait time.

Because of the unpredictability of performance across devices, the goal of OMT architecture is really about reducing risk—making your app more robust in the face of highly variable runtime conditions—not about the performance benefits of parallelization. The increase in resilience and the improvements to UX are more than worth any small tradeoff in speed.

A note about tooling #

Web workers aren't yet mainstream, so most module tools—like WebPack and Rollup—don't support them out of the box. (Parcel does though!) Luckily, there are plugins to make web workers, well, work with WebPack and Rollup:

worker-plugin for WebPack
rollup-plugin-off-main-thread for Rollup

Summing up #

To make sure our apps are as reliable and accessible as possible, especially in an increasingly globalized marketplace, we need to support constrained devices—they're how most users are accessing the web globally. OMT offers a promising way to increase performance on such devices without adversely affecting users of high-end devices.

Also, OMT has secondary benefits:

It moves JavaScript execution costs to a separate thread.
It moves parsing costs, meaning UI might boot up faster. That might reduce First Contentful Paint or even Time to Interactive, which can in turn increase your Lighthouse score.

Web workers don't have to be scary. Tools like Comlink are taking the work out of workers and making them a viable choice for a wide range of web applications.

Hero image from Unsplash, by James Peacock.

Techniques to make a web app load fast, even on a feature phone

2019-09-23T00:00:00Z

At Google I/O 2019 Mariko, Jake, and I shipped PROXX, a modern Minesweeper-clone for the web. Something that sets PROXX apart is the focus on accessibility (you can play it with a screenreader!) and the ability to run as well on a feature phone as on a high-end desktop device. Feature phones are constrained in multiple ways:

Weak CPUs
Weak or non-existent GPUs
Small screens without touch input
Very limited amounts of memory

But they run a modern browser and are very affordable. For this reason, feature phones are making a resurgence in emerging markets. Their price point allows a whole new audience, who previously couldn't afford it, to come online and make use of the modern web. For 2019 it is projected that around 400 million feature phones will be sold in India alone, so users on feature phones might become a significant portion of your audience. In addition to that, connection speeds akin to 2G are the norm in emerging markets. How did we manage to make PROXX work well under feature phone conditions?

PROXX gameplay.

Performance is important, and that includes both loading performance and runtime performance. It has been shown that good performance correlates with increased user retention, improved conversions and—most importantly—increased inclusivity. Jeremy Wagner has much more data and insight on why performance matters.

This is part 1 of a two-part series. Part 1 focuses on loading performance, and part 2 will focus on runtime performance.

Capturing the status quo #

Testing your loading performance on a real device is critical. If you don't have a real device at hand, I recommend WebPageTest (WPT), specifically the "simple" setup. WPT runs a battery of loading tests on a real device with an emulated 3G connection.

3G is a good speed to measure. While you might be used to 4G, LTE or soon even 5G, the reality of mobile internet looks quite different. Maybe you're on a train, at a conference, at a concert, or on a flight. What you'll be experiencing there is most likely closer to 3G, and sometimes even worse.

That being said, we're going to focus on 2G in this article because PROXX is explicitly targeting feature phones and emerging markets in its target audience. Once WebPageTest has run its test, you get a waterfall (similar to what you see in DevTools) as well as a filmstrip at the top. The film strip shows what your user sees while your app is loading. On 2G, the loading experience of the unoptimized version of PROXX is pretty bad:

The filmstrip video shows what the user sees when PROXX is loading on a real, low-end device over an emulated 2G connection.

When loaded over 3G, the user sees 4 seconds of white nothingness. Over 2G the user sees absolutely nothing for over 8 seconds. If you read why performance matters you know that we have now lost a good portion of our potential users due to impatience. The user needs to download all of the 62 KB of JavaScript for anything to appear on screen. The silver lining in this scenario is that the second anything appears on screen it is also interactive. Or is it?

The First Meaningful Paint in the unoptimized version of PROXX is technically interactive but useless to the user.

After about 62 KB of gzip'd JS has been downloaded and the DOM has been generated, the user gets to see our app. The app is technically interactive. Looking at the visual, however, shows a different reality. The web fonts are still loading in the background and until they are ready the user can see no text. While this state qualifies as a First Meaningful Paint (FMP), it surely does not qualify as properly interactive, as the user can't tell what any of the inputs are about. It takes another second on 3G and 3 seconds on 2G until the app is ready to go. All in all, the app takes 6 seconds on 3G and 11 seconds on 2G to become interactive.

Waterfall analysis #

Now that we know what the user sees, we need to figure out the why. For this we can look at the waterfall and analyze why resources are loading too late. In our 2G trace for PROXX we can see two major red flags:

There are multiple, multi-colored thin lines.
JavaScript files form a chain. For example, the second resource only starts loading once the first resource is finished, and the third resource only starts when the second resource is finished.

The waterfall gives insight into which resources are loading when and how long they take.

Reducing connection count #

Each thin line (dns, connect, ssl) stands for the creation of a new HTTP connection. Setting up a new connection is costly as it takes around 1s on 3G and roughly 2.5s on 2G. In our waterfall we see a new connection for:

Request #1: Our index.html
Request #5: The font styles from fonts.googleapis.com
Request #8: Google Analytics
Request #9: A font file from fonts.gstatic.com
Request #14: The web app manifest

The new connection for index.html is unavoidable. The browser has to create a connection to our server to get the contents. The new connection for Google Analytics could be avoided by inlining something like Minimal Analytics, but Google Analytics is not blocking our app from rendering or becoming interactive, so we don't really care about how fast it loads. Ideally, Google Analytics should be loaded in idle time, when everything else has already loaded. That way it won't take up bandwidth or processing power during the initial load. The new connection for the web app manifest is prescribed by the fetch spec, as the manifest has to be loaded over a non-credentialed connection. Again, the web app manifest doesn't block our app from rendering or becoming interactive, so we don't need to care that much.

The two fonts and their styles, however, are a problem as they block rendering and also interactivity. If we look at the CSS that is delivered by fonts.googleapis.com, it's just two @font-face rules, one for each font. The font styles are so small in fact, that we decided to inline it into our HTML, removing one unnecessary connection. To avoid the cost of the connection setup for the font files, we can copy them to our own server.

Parallelizing loads #

Looking at the waterfall, we can see that once the first JavaScript file is done loading, new files start loading immediately. This is typical for module dependencies. Our main module probably has static imports, so the JavaScript cannot run until those imports are loaded. The important thing to realize here is that these kinds of dependencies are known at build time. We can make use of <link rel="preload"> tags to make sure all dependencies start loading the second we receive our HTML.

Results #

Let's take a look at what our changes have achieved. It's important to not change any other variables in our test setup that could skew the results, so we will be using WebPageTest's simple setup for the rest of this article and look at the filmstrip:

We use WebPageTest's filmstrip to see what our changes have achieved.

These changes reduced our TTI from 11 to 8.5, which is roughly the 2.5s of connection setup time we aimed to remove. Well done us.

Prerendering #

While we just reduced our TTI, we haven't really affected the eternally long white screen the user has to endure for 8.5 seconds. Arguably the biggest improvements for FMP can be achieved by sending styled markup in your index.html. Common techniques to achieve this are prerendering and server-side rendering, which are closely related and are explained in Rendering on the Web. Both techniques run the web app in Node and serialize the resulting DOM to HTML. Server-side rendering does this per request on the, well, server side, while prerendering does this at build time and stores the output as your new index.html. Since PROXX is a JAMStack app and has no server side, we decided to implement prerendering.

There are many ways to implement a prerenderer. In PROXX we chose to use Puppeteer, which starts Chrome without any UI and allows you to remote control that instance with a Node API. We use this to inject our markup and our JavaScript and then read back the DOM as a string of HTML. Because we are using CSS Modules, we get CSS inlining of the styles that we need for free.

  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.setContent(rawIndexHTML);
  await page.evaluate(codeToRun);
  const renderedHTML = await page.content();
  browser.close();
  await writeFile("index.html", renderedHTML);

With this in place, we can expect an improvement for our FMP. We still need to load and execute the same amount of JavaScript as before, so we shouldn't expect TTI to change much. If anything, our index.html has gotten bigger and might push back our TTI a bit. There's only one way to find out: running WebPageTest.

The filmstrip shows a clear improvement for our FMP metric. TTI is mostly unaffected.

Our First Meaningful Paint has moved from 8.5 seconds to 4.9 seconds, a massive improvement. Our TTI still happens at around 8.5 seconds so it has been largely unaffected by this change. What we did here is a perceptual change. Some might even call it a sleight of hand. By rendering an intermediate visual of the game, we are changing the perceived loading performance for the better.

Inlining #

Another metric that both DevTools and WebPageTest give us is Time To First Byte (TTFB). This is the time it takes from the first byte of the request being sent to the first byte of the response being received. This time is also often called a Round Trip Time (RTT), although technically there is a difference between these two numbers: RTT does not include the processing time of the request on the server side. DevTools and WebPageTest visualize TTFB with a light color within the request/response block.

The light section of a request signifies the request is waiting to receive the first byte of the response.

Looking at our waterfall, we can see that the all of requests spend the majority of their time waiting for the first byte of the response to arrive.

This problem was what HTTP/2 Push was originally conceived for. The app developer knows that certain resources are needed and can push them down the wire. By the time the client realizes that it needs to fetch additional resources, they are already in the browser's caches. HTTP/2 Push turned out to be too hard to get right and is considered discouraged. This problem space will be revisited during the standardization of HTTP/3. For now, the easiest solution is to inline all the critical resources at the expense of caching efficiency.

Our critical CSS is already inlined thanks to CSS Modules and our Puppeteer-based prerenderer. For JavaScript we need to inline our critical modules and their dependencies. This task has varying difficulty, based on the bundler that you're using.

With the inlining of our JavaScript we have reduced our TTI from 8.5s to 7.2s.

This shaved 1 second off our TTI. We have now reached the point where our index.html contains everything that is needed for the initial render and becoming interactive. The HTML can render while it is still downloading, creating our FMP. The moment the HTML is done parsing and executing, the app is interactive.

Aggressive code splitting #

Yes, our index.html contains everything that is needed to become interactive. But on closer inspection it turns out it also contains everything else. Our index.html is around 43 KB. Let's put that in relation to what the user can interact with at the start: We have a form to configure the game containing a couple of components, a start button and probably some code to persist and load user settings. That's pretty much it. 43 KB seems like a lot.

The landing page of PROXX. Only critical components are used here.

To understand where our bundle size is coming from we can use a source map explorer or a similar tool to break down what the bundle consists of. As predicted, our bundle contains the game logic, the rendering engine, the win screen, the lose screen and a bunch of utilities. Only a small subset of these modules are needed for the landing page. Moving everything that is not strictly required for interactivity into a lazily-loaded module will decrease TTI significantly.

Analyzing the contents of PROXX's `index.html` shows a lot of unneeded resources. Critical resources are highlighted.

What we need to do is code split. Code splitting breaks apart your monolithic bundle into smaller parts that can be lazy-loaded on-demand. Popular bundlers like Webpack, Rollup, and Parcel support code splitting by using dynamic import(). The bundler will analyze your code and inline all modules that are imported statically. Everything that you import dynamically will be put into its own file and will only be fetched from the network once the import() call gets executed. Of course hitting the network has a cost and should only be done if you have the time to spare. The mantra here is to statically import the modules that are critically needed at load time and dynamically load everything else. But you shouldn't wait to the very last moment to lazy-load modules that are definitely going to be used. Phil Walton's Idle Until Urgent is a great pattern for a healthy middle ground between lazy loading and eager loading.

In PROXX we created a lazy.js file that statically imports everything that we don't need. In our main file, we can then dynamically import lazy.js. However, some of our Preact components ended up in lazy.js, which turned out to be a bit of a complication as Preact can't handle lazily-loaded components out of the box. For this reason we wrote a little deferred component wrapper that allows us to render a placeholder until the actual component has loaded.

export default function deferred(componentPromise) {
  return class Deferred extends Component {
    constructor(props) {
      super(props);
      this.state = {
        LoadedComponent: undefined
      };
      componentPromise.then(component => {
        this.setState({ LoadedComponent: component });
      });
    }

    render({ loaded, loading }, { LoadedComponent }) {
      if (LoadedComponent) {
        return loaded(LoadedComponent);
      }
      return loading();
    }
  };
}

With this in place, we can use a Promise of a component in our render() functions. For example, the <Nebula> component, which renders the animated background image, will be replaced by an empty <div> while the component is loading. Once the component is loaded and ready to use, the <div> will be replaced with the actual component.

const NebulaDeferred = deferred(
  import("/components/nebula").then(m => m.default)
);

return (
  // ...
  <NebulaDeferred
    loading={() => <div />}
    loaded={Nebula => <Nebula />}
  />
);

With all of this in place, we reduced our index.html to a mere 20 KB, less than half of the original size. What effect does this have on FMP and TTI? WebPageTest will tell!

The filmstrip confirms: Our TTI is now at 5.4s. A drastic improvement from our original 11s.

Our FMP and TTI are only 100ms apart, as it is only a matter of parsing and executing the inlined JavaScript. After just 5.4s on 2G, the app is completely interactive. All the other, less essential modules are loaded in the background.

More Sleight of Hand #

If you look at our list of critical modules above, you'll see that the rendering engine is not part of the critical modules. Of course, the game cannot start until we have our rendering engine to render the game. We could disable the "Start" button until our rendering engine is ready to start the game, but in our experience the user usually takes long enough to configure their game settings that this isn't necessary. Most of the time the rendering engine and the other remaining modules are done loading by the time the user presses "Start". In the rare case that the user is quicker than their network connection, we show a simple loading screen that waits for the remaining modules to finish.

Conclusion #

Measuring is important. To avoid spending time on problems that are not real, we recommend to always measure first before implementing optimizations. Additionally, measurements should be done on real devices on a 3G connection or on WebPageTest if no real device is at hand.

The filmstrip can give insight into how loading your app feels for the user. The waterfall can tell you what resources are responsible for potentially long loading times. Here's a checklist of things you can do to improve loading performance:

Deliver as many assets as possible over one connection.
Preload or even inline resources that are required for the first render and interactivity.
Prerender your app to improve perceived loading performance.
Make use of aggressive code splitting to reduce the amount of code needed for interactivity.

Stay tuned for part 2 where we discuss how to optimize runtime performance on hyper-constrained devices.

Emscripten and npm

2019-01-15T00:00:00Z

WebAssembly (wasm) is often framed as either a performance primitive or a way to run your existing C++ codebase on the web. With squoosh.app, we wanted to show that there is at least a third perspective for wasm: making use of the huge ecosystems of other programming languages. With Emscripten, you can use C/C++ code, Rust has wasm support built in, and the Go team is working on it, too. I'm sure many other languages will follow.

In these scenarios, wasm is not the centerpiece of your app, but rather a puzzle piece: yet another module. Your app already has JavaScript, CSS, image assets, a web-centric build system and maybe even a framework like React. How do you integrate WebAssembly into this setup? In this article we are going to work this out with C/C++ and Emscripten as an example.

Docker #

Note: While I will be using Docker, you don't need a deep understanding of Docker to follow this article. If you have Docker installed on your machine, you are good to go!

I have found Docker to be invaluable when working with Emscripten. C/C++ libraries are often written to work with the operating system they are built on. It is incredibly helpful to have a consistent environment. With Docker you get a virtualized Linux system that is already set up to work with Emscripten and has all the tools and dependencies installed. If something is missing, you can just install it without having to worry about how it affects your own machine or your other projects. If something goes wrong, throw the container away and start over. If it works once, you can be sure that it will continue to work and produce identical results.

The Docker Registry has an Emscripten image by trzeci that I have been using extensively.

Integration with npm #

In the majority of cases, the entry point to a web project is npm's package.json. By convention, most projects can be built with npm install && npm run build.

In general, the build artifacts produced by Emscripten (a .js and a .wasm file) should be treated as just another JavaScript module and just another asset. The JavaScript file can be handled by a bundler like webpack or rollup, and the wasm file should be treated like any other bigger binary asset, like images.

As such, the Emscripten build artifacts need to be built before your "normal" build process kicks in:

{
    "name": "my-worldchanging-project",
    "scripts": {
    "build:emscripten": "docker run --rm -v $(pwd):/src trzeci/emscripten
./build.sh",
    "build:app": "<the old build command>",
    "build": "npm run build:emscripten && npm run build:app",
    // ...
    },
    // ...
}

The new build:emscripten task could invoke Emscripten directly, but as mentioned before, I recommend using Docker to make sure the build environment is consistent.

docker run ... trzeci/emscripten ./build.sh tells Docker to spin up a new container using the trzeci/emscripten image and run the ./build.sh command. build.sh is a shell script that you are going to write next! --rm tells Docker to delete the container after it's done running. This way, you don't build up a collection of stale machine images over time. -v $(pwd):/src means that you want Docker to "mirror" the current directory ($(pwd)) to /src inside the container. Any changes you make to files in the /src directory inside the container will be mirrored to your actual project. These mirrored directories are called "bind mounts".

Let's take a look at build.sh:

#!/bin/bash

set -e

export OPTIMIZE="-Os"
export LDFLAGS="${OPTIMIZE}"
export CFLAGS="${OPTIMIZE}"
export CXXFLAGS="${OPTIMIZE}"

echo "============================================="
echo "Compiling wasm bindings"
echo "============================================="
(
    # Compile C/C++ code
    emcc \
    ${OPTIMIZE} \
    --bind \
    -s STRICT=1 \
    -s ALLOW_MEMORY_GROWTH=1 \
    -s MALLOC=emmalloc \
    -s MODULARIZE=1 \
    -s EXPORT_ES6=1 \
    -o ./my-module.js \
    src/my-module.cpp

    # Create output folder
    mkdir -p dist
    # Move artifacts
    mv my-module.{js,wasm} dist
)
echo "============================================="
echo "Compiling wasm bindings done"
echo "============================================="

There's a lot to dissect here!

set -e puts the shell into "fail fast" mode. If any commands in the script return an error, the entire script gets aborted immediately. This can be incredibly helpful as the last output of the script will always be a success message or the error that caused the build to fail.

With the export statements, you define the values of a couple of environment variables. They allow you to pass additional command-line parameters to the C compiler (CFLAGS), the C++ compiler (CXXFLAGS), and the linker (LDFLAGS). They all receive the optimizer settings via OPTIMIZE to make sure that everything gets optimized the same way. There are a couple of possible values for the OPTIMIZE variable:

-O0: Don't do any optimization. No dead code is eliminated, and Emscripten does not minify the JavaScript code it emits, either. Good for debugging.
-O3: Optimize aggressively for performance.
-Os: Optimize aggressively for performance and size as a secondary criterion.
-Oz: Optimize aggressively for size, sacrificing performance if necessary.

For the web, I mostly recommend -Os.

The emcc command has a myriad of options of its own. Note that emcc is supposed to be a "drop-in replacement for compilers like GCC or clang". So all flags that you might know from GCC will most likely be implemented by emcc as well. The -s flag is special in that it allows us to configure Emscripten specifically. All available options can be found in Emscripten's settings.js, but that file can be quite overwhelming. Here's a list of the Emscripten flags that I think are most important for web developers:

--bind enables embind.
-s STRICT=1 drops support for all deprecated build options. This ensures that your code builds in a forward compatible manner.
-s ALLOW_MEMORY_GROWTH=1 allows memory to be automatically grown if necessary. At the time of writing, Emscripten will allocate 16MB of memory initially. As your code allocates chunks of memory, this option decides if these operations will make the entire wasm module fail when memory is exhausted, or if the glue code is allowed to expand the total memory to accommodate the allocation.
-s MALLOC=... chooses which malloc() implementation to use. emmalloc is a small and fast malloc() implementation specifically for Emscripten. The alternative is dlmalloc, a fully-fledged malloc() implementation. You only need to switch to dlmalloc if you are allocating a lot of small objects frequently or if you want to use threading.
-s EXPORT_ES6=1 will turn the JavaScript code into an ES6 module with a default export that works with any bundler. Also requires -s MODULARIZE=1 to be set.

The following flags are not always necessary or are only helpful for debugging purposes:

-s FILESYSTEM=0 is a flag that relates to Emscripten and it's ability to emulate a filesystem for you when your C/C++ code uses filesystem operations. It does some analysis on the code it compiles to decide whether to include the filesystem emulation in the glue code or not. Sometimes, however, this analysis can get it wrong and you pay a rather hefty 70kB in additional glue code for a filesystem emulation that you might not need. With -s FILESYSTEM=0 you can force Emscripten to not include this code.
-g4 will make Emscripten include debugging information in the .wasm and also emit a source maps file for the wasm module. You can read more on debugging with Emscripten in their debugging section.

And there you go! To test this setup, let's whip up a tiny my-module.cpp:

    #include <emscripten/bind.h>

    using namespace emscripten;

    int say_hello() {
      printf("Hello from your wasm module\n");
      return 0;
    }

    EMSCRIPTEN_BINDINGS(my_module) {
      function("sayHello", &say_hello);
    }

And an index.html:

    <!doctype html>
    <title>Emscripten + npm example</title>
    Open the console to see the output from the wasm module.
    <script type="module">
    import wasmModule from "./my-module.js";

    const instance = wasmModule({
      onRuntimeInitialized() {
        instance.sayHello();
      }
    });
    </script>

(Here is a gist containing all files.)

To build everything, run

$ npm install
$ npm run build
$ npm run serve

Navigating to localhost:8080 should show you the following output in the DevTools console:

Adding C/C++ code as a dependency #

If you want to build a C/C++ library for your web app, you need its code to be part of your project. You can add the code to your project's repository manually or you can use npm to manage these kind of dependencies as well. Let's say I want to use libvpx in my webapp. libvpx is a C++ library to encode images with VP8, the codec used in .webm files. However, libvpx is not on npm and doesn't have a package.json, so I can't install it using npm directly.

To get out of this conundrum, there is napa. napa allows you to install any git repository URL as a dependency into your node_modules folder.

Note: If you dislike using napa, please take a look at the appendix for a more Docker-centric solution that doesn't require napa.

Install napa as a dependency:

$ npm install --save napa

and make sure to run napa as an install script:

{
// ...
"scripts": {
    "install": "napa",
    // ...
},
"napa": {
    "libvpx": "git+https://github.com/webmproject/libvpx"
}
// ...
}

When you run npm install, napa takes care of cloning the libvpx GitHub repository into your node_modules under the name libvpx.

You can now extend your build script to build libvpx. libvpx uses configure and make to be built. Luckily, Emscripten can help ensure that configure and make use Emscripten's compiler. For this purpose there are the wrapper commands emconfigure and emmake:

# ... above is unchanged ...
echo "============================================="
echo "Compiling libvpx"
echo "============================================="
(
    rm -rf build-vpx || true
    mkdir build-vpx
    cd build-vpx
    emconfigure ../node_modules/libvpx/configure \
    --target=generic-gnu
    emmake make
)
echo "============================================="
echo "Compiling libvpx done"
echo "============================================="

echo "============================================="
echo "Compiling wasm bindings"
echo "============================================="
# ... below is unchanged ...

A C/C++ library is split into two parts: the headers (traditionally .h or .hpp files) that define the data structures, classes, constants etc. that a library exposes and the actual library (traditionally .so or .a files). To use the VPX_CODEC_ABI_VERSION constant of the library in your code, you have to include the library's header files using a #include statement:

#include "vpxenc.h"
#include <emscripten/bind.h>

int say_hello() {
    printf("Hello from your wasm module with libvpx %d\n", VPX_CODEC_ABI_VERSION);
    return 0;
}

The problem is that the compiler doesn't know where to look for vpxenc.h. This is what the -I flag is for. It tells the compiler which directories to check for header files. Additionally, you also need to give the compiler the actual library file:

# ... above is unchanged ...
echo "============================================="
echo "Compiling wasm bindings"
echo "============================================="
(
    # Compile C/C++ code
    emcc \
    ${OPTIMIZE} \
    --bind \
    -s STRICT=1 \
    -s ALLOW_MEMORY_GROWTH=1 \
    -s ASSERTIONS=0 \
    -s MALLOC=emmalloc \
    -s MODULARIZE=1 \
    -s EXPORT_ES6=1 \
    -o ./my-module.js \
    -I ./node_modules/libvpx \
    src/my-module.cpp \
    build-vpx/libvpx.a

# ... below is unchanged ...

If you run npm run build now, you will see that the process builds a new .js and a new .wasm file and that the demo page will indeed output the constant:

You will also notice that the build process takes a long time. The reason for long build times can vary. In the case of libvpx, it takes a long time because it compiles an encoder and a decoder for both VP8 and VP9 every time you run your build command, even though the source files haven't changed. Even a small change to your my-module.cpp will take a long time to build. It would be very beneficial to keep the build artifacts of libvpx around once they have been built the first time.

One way to achieve this is using environment variables.

# ... above is unchanged ...
eval $@

echo "============================================="
echo "Compiling libvpx"
echo "============================================="
test -n "$SKIP_LIBVPX" || (
    rm -rf build-vpx || true
    mkdir build-vpx
    cd build-vpx
    emconfigure ../node_modules/libvpx/configure \
    --target=generic-gnu
    emmake make
)
echo "============================================="
echo "Compiling libvpx done"
echo "============================================="
# ... below is unchanged ...

(Here's a gist containing all the files.)

The eval command allows us to set environment variables by passing parameters to the build script. The test command will skip building libvpx if $SKIP_LIBVPX is set (to any value).

Now you can compile your module but skip rebuilding libvpx:

$ npm run build:emscripten -- SKIP_LIBVPX=1

Customizing the build environment #

Sometimes libraries depend on additional tools to build. If these dependencies are missing in the build environment provided by the Docker image, you need to add them yourself. As an example, let's say you also want to build the documentation of libvpx using doxygen. Doxygen is not available inside your Docker container, but you can install it using apt.

If you were to do that in your build.sh, you would re-download and re-install doxygen everytime you want to build your library. Not only would that be wasteful, but it would also stop you from working on your project while offline.

Here it makes sense to build your own Docker image. Docker images are built by writing a Dockerfile that describes the build steps. Dockerfiles are quite powerful and have a lot of commands, but most of the time you can get away with just using FROM, RUN and ADD. In this case:

FROM trzeci/emscripten

RUN apt-get update && \
    apt-get install -qqy doxygen

With FROM, you can declare which Docker image you want to use as a starting point. I chose trzeci/emscripten as a basis — the image you have been using all along. With RUN, you instruct Docker to run shell commands inside the container. Whatever changes these commands make to the container is now part of the Docker image. To make sure that your Docker image has been built and is available before you run build.sh, you have to adjust your package.json a bit:

{
    // ...
    "scripts": {
    "build:dockerimage": "docker image inspect -f '.' mydockerimage || docker build -t mydockerimage .",
    "build:emscripten": "docker run --rm -v $(pwd):/src mydockerimage ./build.sh",
    "build": "npm run build:dockerimage && npm run build:emscripten && npm run build:app",
    // ...
    },
    // ...
}

(Here's a gist containing all the files.)

This will build your Docker image, but only if it has not been built yet. Then everything runs as before, but now the build environment has the doxygen command available, which will cause the documentation of libvpx to be built as well.

Conclusion #

It is not surprising that C/C++ code and npm are not a natural fit, but you can make it work quite comfortably with some additional tooling and the isolation that Docker provides. This setup will not work for every project, but it's a decent starting point that you can adjust for your needs. If you have improvements, please share.

Appendix: Making use of Docker image layers #

An alternative solution is to encapsulate more of these problems with Docker and Docker's smart approach to caching. Docker executes Dockerfiles step-by-step and assigns the result of each step an image of it's own. These intermediate images are often called "layers". If a command in a Dockerfile hasn't changed, Docker won't actually re-run that step when you are re-building the Dockerfile. Instead it reuses the layer from the last time the image was built.

Previously, you had to go through some effort to not rebuild libvpx every time you build your app. Instead you can move the building instructions for libvpx from your build.sh into the Dockerfile to make use of Docker's caching mechanism:

FROM trzeci/emscripten

RUN apt-get update && \
    apt-get install -qqy doxygen git && \
    mkdir -p /opt/libvpx/build && \
    git clone https://github.com/webmproject/libvpx /opt/libvpx/src
RUN cd /opt/libvpx/build && \
    emconfigure ../src/configure --target=generic-gnu && \
    emmake make

(Here's a gist containing all the files.)

Note that you need to manually install git and clone libvpx as you don't have bind mounts when running docker build. As a side-effect, there is no need for napa anymore.

Emscripten’s embind

2018-08-20T00:00:00Z

In my last wasm article, I talked about how to compile a C library to wasm so that you can use it on the web. One thing that stood out to me (and to many readers) is the crude and slightly awkward way you have to manually declare which functions of your wasm module you are using. To refresh your mind, this is the code snippet I am talking about:

const api = {
    version: Module.cwrap('version', 'number', []),
    create_buffer: Module.cwrap('create_buffer', 'number', ['number', 'number']),
    destroy_buffer: Module.cwrap('destroy_buffer', '', ['number']),
};

Here we declare the names of the functions that we marked with EMSCRIPTEN_KEEPALIVE, what their return types are, and what the types of their arguments are. Afterwards, we can use the methods on the api object to invoke these functions. However, using wasm this way doesn't support strings and requires you to manually move chunks of memory around which makes many library APIs very tedious to use. Isn't there a better way? Why yes there is, otherwise what would this article be about?

C++ name mangling #

While the developer experience would be reason enough to build a tool that helps with these bindings, there's actually a more pressing reason: When you compile C or C++ code, each file is compiled separately. Then, a linker takes care of munging all these so-called object files together and turning them into a wasm file. With C, the names of the functions are still available in the object file for the linker to use. All you need to be able to call a C function is the name, which we are providing as a string to cwrap().

C++ on the other hand supports function overloading, meaning you can implement the same function multiple times as long as the signature is different (e.g. differently typed parameters). At the compiler level, a nice name like add would get mangled into something that encodes the signature in the function name for the linker. As a result, we wouldn't be able to look up our function with its name anymore.

Enter embind #

embind is part of the Emscripten toolchain and provides you with a bunch of C++ macros that allow you to annotate C++ code. You can declare which functions, enums, classes or value types you are planning to use from JavaScript. Let's start simple with some plain functions:

#include <emscripten/bind.h>

using namespace emscripten;

double add(double a, double b) {
    return a + b;
}

std::string exclaim(std::string message) {
    return message + "!";
}

EMSCRIPTEN_BINDINGS(my_module) {
    function("add", &add);
    function("exclaim", &exclaim);
}

Compared to my previous article, we are not including emscripten.h anymore, as we don't have to annotate our functions with EMSCRIPTEN_KEEPALIVE anymore. Instead, we have an EMSCRIPTEN_BINDINGS section in which we list the names under which we want to expose our functions to JavaScript.

To compile this file, we can use the same setup (or, if you want, the same Docker image) as in the previous article. To use embind, we add the --bind flag:

$ emcc --bind -O3 add.cpp

Now all that's left is whipping up an HTML file that loads our freshly created wasm module:

<script src="/a.out.js"></script>
<script>
Module.onRuntimeInitialized = _ => {
    console.log(Module.add(1, 2.3));
    console.log(Module.exclaim("hello world"));
};
</script>

As you can see, we aren't using cwrap() anymore. This just works straight out of the box. But more importantly, we don't have to worry about manually copying chunks of memory to make strings work! embind gives you that for free, along with type checks:

This is pretty great as we can catch some errors early instead of dealing with the occasionally quite unwieldy wasm errors.

Objects #

Many JavaScript constructors and functions use options objects. It's a nice pattern in JavaScript, but extremely tedious to realize in wasm manually. embind can help here, too!

For example, I came up with this incredibly useful C++ function that processes my strings, and I urgently want to use it on the web. Here is how I did that:

#include <emscripten/bind.h>
#include <algorithm>

using namespace emscripten;

struct ProcessMessageOpts {
  bool reverse;
  bool exclaim;
  int repeat;
};

std::string processMessage(std::string message, ProcessMessageOpts opts) {
  std::string copy = std::string(message);
  if(opts.reverse) {
  std::reverse(copy.begin(), copy.end());
  }
  if(opts.exclaim) {
  copy += "!";
  }
  std::string acc = std::string("");
  for(int i = 0; i < opts.repeat; i++) {
  acc += copy;
  }
  return acc;
}

EMSCRIPTEN_BINDINGS(my_module) {
  value_object<ProcessMessageOpts>("ProcessMessageOpts")
  .field("reverse", &ProcessMessageOpts::reverse)
  .field("exclaim", &ProcessMessageOpts::exclaim)
  .field("repeat", &ProcessMessageOpts::repeat);

  function("processMessage", &processMessage);
}

I am defining a struct for the options of my processMessage() function. In the EMSCRIPTEN_BINDINGS block, I can use value_object to make JavaScript see this C++ value as an object. I could also use value_array if I preferred to use this C++ value as an array. I also bind the processMessage() function, and the rest is embind magic. I can now call the processMessage() function from JavaScript without any boilerplate code:

console.log(Module.processMessage(
    "hello world",
    {
    reverse: false,
    exclaim: true,
    repeat: 3
    }
)); // Prints "hello world!hello world!hello world!"

Classes #

For completeness sake, I should also show you how embind allows you to expose entire classes, which brings a lot of synergy with ES6 classes. You can probably start to see a pattern by now:

#include <emscripten/bind.h>
#include <algorithm>

using namespace emscripten;

class Counter {
public:
    int counter;

    Counter(int init) :
    counter(init) {
    }

    void increase() {
    counter++;
    }

    int squareCounter() {
    return counter * counter;
    }
};

EMSCRIPTEN_BINDINGS(my_module) {
    class_<Counter>("Counter")
    .constructor<int>()
    .function("increase", &Counter::increase)
    .function("squareCounter", &Counter::squareCounter)
    .property("counter", &Counter::counter);
}

On the JavaScript side, this almost feels like a native class:

<script src="/a.out.js"></script>
<script>
Module.onRuntimeInitialized = _ => {
    const c = new Module.Counter(22);
    console.log(c.counter); // prints 22
    c.increase();
    console.log(c.counter); // prints 23
    console.log(c.squareCounter()); // prints 529
};
</script>

What about C? #

embind was written for C++ and can only be used in C++ files, but that doesn't mean that you can't link against C files! To mix C and C++, you only need to separate your input files into two groups: One for C and one for C++ files and augment the CLI flags for emcc as follows:

$ emcc --bind -O3 --std=c++11 a_c_file.c another_c_file.c -x c++ your_cpp_file.cpp

Conclusion #

embind gives you great improvements in the developer experience when working with wasm and C/C++. This article does not cover all the options embind offers. If you are interested, I recommend continuing with embind's documentation. Keep in mind that using embind can make both your wasm module and your JavaScript glue code bigger by up to 11k when gzip'd — most notably on small modules. If you only have a very small wasm surface, embind might cost more than it's worth in a production environment! Nonetheless, you should definitely give it a try.

Emscripting a C library to Wasm

2018-03-05T00:00:00Z

Sometimes you want to use a library that is only available as C or C++ code. Traditionally, this is where you give up. Well, not anymore, because now we have Emscripten and WebAssembly (or Wasm)!

The toolchain #

I set myself the goal of working out how to compile some existing C code to Wasm. There's been some noise around LLVM's Wasm backend, so I started digging into that. While you can get simple programs to compile this way, the second you want to use C's standard library or even compile multiple files, you will probably run into problems. This led me to the major lesson I learned:

While Emscripten used to be a C-to-asm.js compiler, it has since matured to target Wasm and is in the process of switching to the official LLVM backend internally. Emscripten also provides a Wasm-compatible implementation of C's standard library. Use Emscripten. It carries a lot of hidden work, emulates a file system, provides memory management, wraps OpenGL with WebGL — a lot of things that you really don't need to experience developing for yourself.

While that might sound like you have to worry about bloat — I certainly worried — the Emscripten compiler removes everything that's not needed. In my experiments, the resulting Wasm modules are appropriately sized for the logic that they contain and the Emscripten and WebAssembly teams are working on making them even smaller in the future.

You can get Emscripten by following the instructions on their website or using Homebrew. If you are a fan of dockerized commands like me and don't want to install things on your system just to have a play with WebAssembly, there is a well-maintained Docker image that you can use instead:

    $ docker pull trzeci/emscripten
    $ docker run --rm -v $(pwd):/src trzeci/emscripten emcc <emcc options here>

Compiling something simple #

Let's take the almost canonical example of writing a function in C that calculates the n^th fibonacci number:

    #include <emscripten.h>

    EMSCRIPTEN_KEEPALIVE
    int fib(int n) {
      if(n <= 0){
        return 0;
      }
      int i, t, a = 0, b = 1;
      for (i = 1; i < n; i++) {
        t = a + b;
        a = b;
        b = t;
      }
      return b;
    }

If you know C, the function itself shouldn't be too surprising. Even if you don't know C but know JavaScript, you will hopefully be able to understand what's going on here.

emscripten.h is a header file provided by Emscripten. We only need it so we have access to the EMSCRIPTEN_KEEPALIVE macro, but it provides much more functionality. This macro tells the compiler to not remove a function even if it appears unused. If we omitted that macro, the compiler would optimize the function away — nobody is using it after all.

Let's save all that in a file called fib.c. To turn it into a .wasm file we need to turn to Emscripten's compiler command emcc:

    $ emcc -O3 -s WASM=1 -s EXTRA_EXPORTED_RUNTIME_METHODS='["cwrap"]' fib.c

Let's dissect this command. emcc is Emscripten's compiler. fib.c is our C file. So far, so good. -s WASM=1 tells Emscripten to give us a Wasm file instead of an asm.js file. -s EXTRA_EXPORTED_RUNTIME_METHODS='["cwrap"]' tells the compiler to leave the cwrap() function available in the JavaScript file — more on this function later. -O3 tells the compiler to optimize aggressively. You can choose lower numbers to decrease build time, but that will also make the resulting bundles bigger as the compiler might not remove unused code.

After running the command, you should end up with a JavaScript file called a.out.js and a WebAssembly file called a.out.wasm. The Wasm file (or "module") contains our compiled C code and should be fairly small. The JavaScript file takes care of loading and initializing our Wasm module and providing a nicer API. If needed, it will also take care of setting up the stack, the heap, and other functionality usually expected to be provided by the operating system when writing C code. As such, the JavaScript file is a bit bigger, weighing in at 19KB (~5KB gzip'd).

Running something simple #

The easiest way to load and run your module is to use the generated JavaScript file. Once you load that file, you will have a Module global at your disposal. Use cwrap to create a JavaScript native function that takes care of converting parameters to something C-friendly and invoking the wrapped function. cwrap takes the function name, return type and argument types as arguments, in that order:

    <script src="a.out.js"></script>
    <script>
      Module.onRuntimeInitialized = _ => {
        const fib = Module.cwrap('fib', 'number', ['number']);
        console.log(fib(12));
      };
    </script>

If you run this code, you should see the "144" in the console, which is the 12th Fibonacci number.

The holy grail: Compiling a C library #

Up until now, the C code we have written was written with Wasm in mind. A core use-case for WebAssembly, however, is to take the existing ecosystem of C libraries and allow developers to use them on the web. These libraries often rely on C's standard library, an operating system, a file system and other things. Emscripten provides most of these features, although there are some limitations.

Let's go back to my original goal: compiling an encoder for WebP to Wasm. The source for the WebP codec is written in C and available on GitHub as well as some extensive API documentation. That's a pretty good starting point.

    $ git clone https://github.com/webmproject/libwebp

To start off simple, let's try to expose WebPGetEncoderVersion() from encode.h to JavaScript by writing a C file called webp.c:

    #include "emscripten.h"
    #include "src/webp/encode.h"

    EMSCRIPTEN_KEEPALIVE
    int version() {
      return WebPGetEncoderVersion();
    }

This is a good simple program to test if we can get the source code of libwebp to compile, as we don't require any parameters or complex data structures to invoke this function.

To compile this program, we need to tell the compiler where it can find libwebp's header files using the -I flag and also pass it all the C files of libwebp that it needs. I'm going to be honest: I just gave it all the C files I could find and relied on the compiler to strip out everything that was unnecessary. It seemed to work brilliantly!

    $ emcc -O3 -s WASM=1 -s EXTRA_EXPORTED_RUNTIME_METHODS='["cwrap"]' \
        -I libwebp \
        webp.c \
        libwebp/src/{dec,dsp,demux,enc,mux,utils}/*.c

Now we only need some HTML and JavaScript to load our shiny new module:

<script src="/a.out.js"></script>
<script>
  Module.onRuntimeInitialized = async (_) => {
    const api = {
      version: Module.cwrap('version', 'number', []),
    };
    console.log(api.version());
  };
</script>

And we will see the correction version number in the output:

Get an image from JavaScript into Wasm #

Getting the encoder's version number is great and all, but encoding an actual image would be more impressive, right? Let's do that, then.

The first question we have to answer is: How do we get the image into Wasm land? Looking at the encoding API of libwebp, it expects an array of bytes in RGB, RGBA, BGR or BGRA. Luckily, the Canvas API has getImageData(), that gives us an Uint8ClampedArray containing the image data in RGBA:

async function loadImage(src) {
  // Load image
  const imgBlob = await fetch(src).then((resp) => resp.blob());
  const img = await createImageBitmap(imgBlob);
  // Make canvas same size as image
  const canvas = document.createElement('canvas');
  canvas.width = img.width;
  canvas.height = img.height;
  // Draw image onto canvas
  const ctx = canvas.getContext('2d');
  ctx.drawImage(img, 0, 0);
  return ctx.getImageData(0, 0, img.width, img.height);
}

Now it's "only" a matter of copying the data from JavaScript land into Wasm land. For that, we need to expose two additional functions. One that allocates memory for the image inside Wasm land and one that frees it up again:

    EMSCRIPTEN_KEEPALIVE
    uint8_t* create_buffer(int width, int height) {
      return malloc(width * height * 4 * sizeof(uint8_t));
    }

    EMSCRIPTEN_KEEPALIVE
    void destroy_buffer(uint8_t* p) {
      free(p);
    }

create_buffer allocates a buffer for the RGBA image — hence 4 bytes per pixel. The pointer returned by malloc() is the address of the first memory cell of that buffer. When the pointer is returned to JavaScript land, it is treated as just a number. After exposing the function to JavaScript using cwrap, we can use that number to find the start of our buffer and copy the image data.

const api = {
  version: Module.cwrap('version', 'number', []),
  create_buffer: Module.cwrap('create_buffer', 'number', ['number', 'number']),
  destroy_buffer: Module.cwrap('destroy_buffer', '', ['number']),
};

const image = await loadImage('/image.jpg');
const p = api.create_buffer(image.width, image.height);
Module.HEAP8.set(image.data, p);
// ... call encoder ...
api.destroy_buffer(p);

Grand Finale: Encode the image #

The image is now available in Wasm land. It is time to call the WebP encoder to do its job! Looking at the WebP documentation, WebPEncodeRGBA seems like a perfect fit. The function takes a pointer to the input image and its dimensions, as well as a quality option between 0 and 100. It also allocates an output buffer for us, that we need to free using WebPFree() once we are done with the WebP image.

The result of the encoding operation is an output buffer and its length. Because functions in C can't have arrays as return types (unless we allocate memory dynamically), I resorted to a static global array. I know, not clean C (in fact, it relies on the fact that Wasm pointers are 32bit wide), but to keep things simple I think this is a fair shortcut.

    int result[2];
    EMSCRIPTEN_KEEPALIVE
    void encode(uint8_t* img_in, int width, int height, float quality) {
      uint8_t* img_out;
      size_t size;

      size = WebPEncodeRGBA(img_in, width, height, width * 4, quality, &img_out);

      result[0] = (int)img_out;
      result[1] = size;
    }

    EMSCRIPTEN_KEEPALIVE
    void free_result(uint8_t* result) {
      WebPFree(result);
    }

    EMSCRIPTEN_KEEPALIVE
    int get_result_pointer() {
      return result[0];
    }

    EMSCRIPTEN_KEEPALIVE
    int get_result_size() {
      return result[1];
    }

Now with all of that in place, we can call the encoding function, grab the pointer and image size, put it in a JavaScript-land buffer of our own, and release all the Wasm-land buffers we have allocated in the process.

    api.encode(p, image.width, image.height, 100);
    const resultPointer = api.get_result_pointer();
    const resultSize = api.get_result_size();
    const resultView = new Uint8Array(Module.HEAP8.buffer, resultPointer, resultSize);
    const result = new Uint8Array(resultView);
    api.free_result(resultPointer);

Depending on the size of your image, you might run into an error where Wasm can't grow the memory enough to accommodate both the input and the output image:

Luckily, the solution to this problem is in the error message! We just need to add -s ALLOW_MEMORY_GROWTH=1 to our compilation command.

And there you have it! We compiled a WebP encoder and transcoded a JPEG image to WebP. To prove that it worked, we can turn our result buffer into a blob and use it on an <img> element:

const blob = new Blob([result], { type: 'image/webp' });
const blobURL = URL.createObjectURL(blob);
const img = document.createElement('img');
img.src = blobURL;
document.body.appendChild(img);

Behold, the glory of a new WebP image!

Conclusion #

It's not a walk in the park to get a C library to work in the browser, but once you understand the overall process and how the data flow works, it becomes easier and the results can be mind-blowing.

WebAssembly opens many new possibilities on the web for processing, number crunching and gaming. Keep in mind that Wasm is not a silver bullet that should be applied to everything, but when you hit one of those bottlenecks, Wasm can be an incredibly helpful tool.

Bonus content: Running something simple the hard way #

If you want to try and avoid the generated JavaScript file, you might be able to. Let's go back to the Fibonacci example. To load and run it ourselves, we can do the following:

<!DOCTYPE html>
<script>
  (async function () {
    const imports = {
      env: {
        memory: new WebAssembly.Memory({ initial: 1 }),
        STACKTOP: 0,
      },
    };
    const { instance } = await WebAssembly.instantiateStreaming(
      fetch('/a.out.wasm'),
      imports,
    );
    console.log(instance.exports._fib(12));
  })();
</script>

WebAssembly modules that have been created by Emscripten have no memory to work with unless you provide them with memory. The way you provide a Wasm module with anything is by using the imports object — the second parameter of the instantiateStreaming function. The Wasm module can access everything inside the imports object, but nothing else outside of it. By convention, modules compiled by Emscripting expect a couple of things from the loading JavaScript environment:

Firstly, there is env.memory. The Wasm module is unaware of the outside world so to speak, so it needs to get some memory to work with. Enter WebAssembly.Memory. It represents a (optionally growable) piece of linear memory. The sizing parameters are in "in units of WebAssembly pages", meaning the code above allocates 1 page of memory, with each page having a size of 64 KiB. Without providing a maximum option, the memory is theoretically unbounded in growth (Chrome currently has a hard limit of 2GB). Most WebAssembly modules shouldn't need to set a maximum.
env.STACKTOP defines where the stack is supposed to start growing. The stack is needed to make function calls and to allocate memory for local variables. Since we don't do any dynamic memory management shenanigans in our little Fibonacci program, we can just use the entire memory as a stack, hence STACKTOP = 0.

HowTo Components – howto-checkbox

2017-10-02T00:00:00Z

Summary #

A <howto-checkbox> represents a boolean option in a form. The most common type of checkbox is a dual-type which allows the user to toggle between two choices -- checked and unchecked.

The element attempts to self apply the attributes role="checkbox" and tabindex="0" when it is first created. The role attribute helps assistive technology like a screen reader tell the user what kind of control this is. The tabindex attribute opts the element into the tab order, making it keyboard focusable and operable. To learn more about these two topics, check out What can ARIA do? and Using tabindex.

When the checkbox is checked, it adds a checked boolean attribute, and sets a corresponding checked property to true. In addition, the element sets an aria-checked attribute to either "true" or "false", depending on its state. Clicking on the checkbox with a mouse, or space bar, toggles these checked states.

The checkbox also supports a disabled state. If either the disabled property is set to true or the disabled attribute is applied, the checkbox sets aria-disabled="true", removes the tabindex attribute, and returns focus to the document if the checkbox is the current activeElement.

The checkbox is paired with a howto-label element to ensure it has an accessible name.

Reference #

Demo #

View live demo on GitHub

Example usage #

<style>
  howto-checkbox {
    vertical-align: middle;
  }
  howto-label {
    vertical-align: middle;
    display: inline-block;
    font-weight: bold;
    font-family: sans-serif;
    font-size: 20px;
    margin-left: 8px;
  }
</style>

<howto-checkbox id="join-checkbox"></howto-checkbox>
<howto-label for="join-checkbox">Join Newsletter</howto-label>

Code #

(function() {

Define key codes to help with handling keyboard events.

  const KEYCODE = {
    SPACE: 32,
  };

Cloning contents from a <template> element is more performant than using innerHTML because it avoids additional HTML parse costs.

  const template = document.createElement('template');

  template.innerHTML = `
    <style>
      :host {
        display: inline-block;
        background: url('../images/unchecked-checkbox.svg') no-repeat;
        background-size: contain;
        width: 24px;
        height: 24px;
      }
      :host([hidden]) {
        display: none;
      }
      :host([checked]) {
        background: url('../images/checked-checkbox.svg') no-repeat;
        background-size: contain;
      }
      :host([disabled]) {
        background:
          url('../images/unchecked-checkbox-disabled.svg') no-repeat;
        background-size: contain;
      }
      :host([checked][disabled]) {
        background:
          url('../images/checked-checkbox-disabled.svg') no-repeat;
        background-size: contain;
      }
    </style>
  `;


  class HowToCheckbox extends HTMLElement {
    static get observedAttributes() {
      return ['checked', 'disabled'];
    }

The element's constructor is run anytime a new instance is created. Instances are created either by parsing HTML, calling document.createElement('howto-checkbox'), or calling new HowToCheckbox(); The constructor is a good place to create shadow DOM, though you should avoid touching any attributes or light DOM children as they may not be available yet.

    constructor() {
      super();
      this.attachShadow({mode: 'open'});
      this.shadowRoot.appendChild(template.content.cloneNode(true));
    }

connectedCallback() fires when the element is inserted into the DOM. It's a good place to set the initial role, tabindex, internal state, and install event listeners.

    connectedCallback() {
      if (!this.hasAttribute('role'))
        this.setAttribute('role', 'checkbox');
      if (!this.hasAttribute('tabindex'))
        this.setAttribute('tabindex', 0);

A user may set a property on an instance of an element, before its prototype has been connected to this class. The _upgradeProperty() method will check for any instance properties and run them through the proper class setters. See the lazy properties section for more details.

      this._upgradeProperty('checked');
      this._upgradeProperty('disabled');

      this.addEventListener('keyup', this._onKeyUp);
      this.addEventListener('click', this._onClick);
    }

    _upgradeProperty(prop) {
      if (this.hasOwnProperty(prop)) {
        let value = this[prop];
        delete this[prop];
        this[prop] = value;
      }
    }

disconnectedCallback() fires when the element is removed from the DOM. It's a good place to do clean up work like releasing references and removing event listeners.

    disconnectedCallback() {
      this.removeEventListener('keyup', this._onKeyUp);
      this.removeEventListener('click', this._onClick);
    }

Properties and their corresponding attributes should mirror one another. The property setter for checked handles truthy/falsy values and reflects those to the state of the attribute. See the avoid reentrancy section for more details.

    set checked(value) {
      const isChecked = Boolean(value);
      if (isChecked)
        this.setAttribute('checked', '');
      else
        this.removeAttribute('checked');
    }

    get checked() {
      return this.hasAttribute('checked');
    }

    set disabled(value) {
      const isDisabled = Boolean(value);
      if (isDisabled)
        this.setAttribute('disabled', '');
      else
        this.removeAttribute('disabled');
    }

    get disabled() {
      return this.hasAttribute('disabled');
    }

attributeChangedCallback() is called when any of the attributes in the observedAttributes array are changed. It's a good place to handle side effects, like setting ARIA attributes.

    attributeChangedCallback(name, oldValue, newValue) {
      const hasValue = newValue !== null;
      switch (name) {
        case 'checked':
          this.setAttribute('aria-checked', hasValue);
          break;
        case 'disabled':
          this.setAttribute('aria-disabled', hasValue);

The tabindex attribute does not provide a way to fully remove focusability from an element. Elements with tabindex=-1 can still be focused with a mouse or by calling focus(). To make sure an element is disabled and not focusable, remove the tabindex attribute.

          if (hasValue) {
            this.removeAttribute('tabindex');

If the focus is currently on this element, unfocus it by calling the HTMLElement.blur() method

            this.blur();
          } else {
            this.setAttribute('tabindex', '0');
          }
          break;
      }
    }

    _onKeyUp(event) {

Don’t handle modifier shortcuts typically used by assistive technology.

      if (event.altKey)
        return;

      switch (event.keyCode) {
        case KEYCODE.SPACE:
          event.preventDefault();
          this._toggleChecked();
          break;

Any other key press is ignored and passed back to the browser.

        default:
          return;
      }
    }

    _onClick(event) {
      this._toggleChecked();
    }

_toggleChecked() calls the checked setter and flips its state. Because _toggleChecked() is only caused by a user action, it will also dispatch a change event. This event bubbles in order to mimic the native behavior of <input type=checkbox>.

    _toggleChecked() {
      if (this.disabled)
        return;
      this.checked = !this.checked;
      this.dispatchEvent(new CustomEvent('change', {
        detail: {
          checked: this.checked,
        },
        bubbles: true,
      }));
    }
  }

  customElements.define('howto-checkbox', HowToCheckbox);
})();

HowTo Components – howto-tabs

2017-04-06T00:00:00Z

Summary #

<howto-tabs> limit visible content by separating it into multiple panels. Only one panel is visible at a time, while all corresponding tabs are always visible. To switch from one panel to another, the corresponding tab has to be selected.

By either clicking or by using the arrow keys the user can change the selection of the active tab.

If JavaScript is disabled, all panels are shown interleaved with the respective tabs. The tabs now function as headings.

Reference #

Demo #

View live demo on GitHub

Example usage #

<style>
  howto-tab {
    border: 1px solid black;
    padding: 20px;
  }
  howto-panel {
    padding: 20px;
    background-color: lightgray;
  }
  howto-tab[selected] {
    background-color: bisque;
  }

If JavaScript does not run, the element will not match :defined. In that case this style adds spacing between tabs and previous panel.

  howto-tabs:not(:defined), howto-tab:not(:defined), howto-panel:not(:defined) {
    display: block;
  }
</style>

<howto-tabs>
  <howto-tab role="heading" slot="tab">Tab 1</howto-tab>
  <howto-panel role="region" slot="panel">Content 1</howto-panel>
  <howto-tab role="heading" slot="tab">Tab 2</howto-tab>
  <howto-panel role="region" slot="panel">Content 2</howto-panel>
  <howto-tab role="heading" slot="tab">Tab 3</howto-tab>
  <howto-panel role="region" slot="panel">Content 3</howto-panel>
</howto-tabs>

Code #

(function() {

Define key codes to help with handling keyboard events.

  const KEYCODE = {
    DOWN: 40,
    LEFT: 37,
    RIGHT: 39,
    UP: 38,
    HOME: 36,
    END: 35,
  };

To avoid invoking the parser with .innerHTML for every new instance, a template for the contents of the shadow DOM is shared by all <howto-tabs> instances.

  const template = document.createElement('template');
  template.innerHTML = `
    <style>
      :host {
        display: flex;
        flex-wrap: wrap;
      }
      ::slotted(howto-panel) {
        flex-basis: 100%;
      }
    </style>
    <slot name="tab"></slot>
    <slot name="panel"></slot>
  `;

HowtoTabs is a container element for tabs and panels.

All children of <howto-tabs> should be either <howto-tab> or <howto-tabpanel>. This element is stateless, meaning that no values are cached and therefore, changes during runtime work.

  class HowtoTabs extends HTMLElement {
    constructor() {
      super();

Event handlers that are not attached to this element need to be bound if they need access to this.

      this._onSlotChange = this._onSlotChange.bind(this);

For progressive enhancement, the markup should alternate between tabs and panels. Elements that reorder their children tend to not work well with frameworks. Instead shadow DOM is used to reorder the elements by using slots.

      this.attachShadow({ mode: 'open' });

Import the shared template to create the slots for tabs and panels.

      this.shadowRoot.appendChild(template.content.cloneNode(true));

      this._tabSlot = this.shadowRoot.querySelector('slot[name=tab]');
      this._panelSlot = this.shadowRoot.querySelector('slot[name=panel]');

This element needs to react to new children as it links up tabs and panel semantically using aria-labelledby and aria-controls. New children will get slotted automatically and cause slotchange to fire, so not MutationObserver is needed.

      this._tabSlot.addEventListener('slotchange', this._onSlotChange);
      this._panelSlot.addEventListener('slotchange', this._onSlotChange);
    }

connectedCallback() groups tabs and panels by reordering and makes sure exactly one tab is active.

    connectedCallback() {

The element needs to do some manual input event handling to allow switching with arrow keys and Home / End.

      this.addEventListener('keydown', this._onKeyDown);
      this.addEventListener('click', this._onClick);

      if (!this.hasAttribute('role'))
        this.setAttribute('role', 'tablist');

Up until recently, slotchange events did not fire when an element was upgraded by the parser. For this reason, the element invokes the handler manually. Once the new behavior lands in all browsers, the code below can be removed.

      Promise.all([
        customElements.whenDefined('howto-tab'),
        customElements.whenDefined('howto-panel'),
      ])
        .then(() => this._linkPanels());
    }

disconnectedCallback() removes the event listeners that connectedCallback() added.

    disconnectedCallback() {
      this.removeEventListener('keydown', this._onKeyDown);
      this.removeEventListener('click', this._onClick);
    }

_onSlotChange() is called whenever an element is added or removed from one of the shadow DOM slots.

    _onSlotChange() {
      this._linkPanels();
    }

_linkPanels() links up tabs with their adjacent panels using aria-controls and aria-labelledby. Additionally, the method makes sure only one tab is active.

    _linkPanels() {
      const tabs = this._allTabs();

Give each panel a aria-labelledby attribute that refers to the tab that controls it.

      tabs.forEach((tab) => {
        const panel = tab.nextElementSibling;
        if (panel.tagName.toLowerCase() !== 'howto-panel') {
          console.error(`Tab #${tab.id} is not a` +
            `sibling of a <howto-panel>`);
          return;
        }

        tab.setAttribute('aria-controls', panel.id);
        panel.setAttribute('aria-labelledby', tab.id);
      });

The element checks if any of the tabs have been marked as selected. If not, the first tab is now selected.

      const selectedTab =
        tabs.find((tab) => tab.selected) || tabs[0];

Next, switch to the selected tab. _selectTab() takes care of marking all other tabs as deselected and hiding all other panels.

      this._selectTab(selectedTab);
    }

_allPanels() returns all the panels in the tab panel. This function could memorize the result if the DOM queries ever become a performance issue. The downside of memorization is that dynamically added tabs and panels will not be handled.

This is a method and not a getter, because a getter implies that it is cheap to read.

    _allPanels() {
      return Array.from(this.querySelectorAll('howto-panel'));
    }

_allTabs() returns all the tabs in the tab panel.

    _allTabs() {
      return Array.from(this.querySelectorAll('howto-tab'));
    }

_panelForTab() returns the panel that the given tab controls.

    _panelForTab(tab) {
      const panelId = tab.getAttribute('aria-controls');
      return this.querySelector(`#${panelId}`);
    }

_prevTab() returns the tab that comes before the currently selected one, wrapping around when reaching the first one.

    _prevTab() {
      const tabs = this._allTabs();

Use findIndex() to find the index of the currently selected element and subtracts one to get the index of the previous element.

      let newIdx = tabs.findIndex((tab) => tab.selected) - 1;

Add tabs.length to make sure the index is a positive number and get the modulus to wrap around if necessary.

      return tabs[(newIdx + tabs.length) % tabs.length];
    }

_firstTab() returns the first tab.

    _firstTab() {
      const tabs = this._allTabs();
      return tabs[0];
    }

_lastTab() returns the last tab.

    _lastTab() {
      const tabs = this._allTabs();
      return tabs[tabs.length - 1];
    }

_nextTab() gets the tab that comes after the currently selected one, wrapping around when reaching the last tab.

    _nextTab() {
      const tabs = this._allTabs();
      let newIdx = tabs.findIndex((tab) => tab.selected) + 1;
      return tabs[newIdx % tabs.length];
    }

reset() marks all tabs as deselected and hides all the panels.

    reset() {
      const tabs = this._allTabs();
      const panels = this._allPanels();

      tabs.forEach((tab) => tab.selected = false);
      panels.forEach((panel) => panel.hidden = true);
    }

_selectTab() marks the given tab as selected. Additionally, it unhides the panel corresponding to the given tab.

    _selectTab(newTab) {

Deselect all tabs and hide all panels.

      this.reset();

Get the panel that the newTab is associated with.

      const newPanel = this._panelForTab(newTab);

If that panel doesn’t exist, abort.

      if (!newPanel)
        throw new Error(`No panel with id ${newPanelId}`);
      newTab.selected = true;
      newPanel.hidden = false;
      newTab.focus();
    }

_onKeyDown() handles key presses inside the tab panel.

    _onKeyDown(event) {

If the keypress did not originate from a tab element itself, it was a keypress inside the a panel or on empty space. Nothing to do.

      if (event.target.getAttribute('role') !== 'tab')
        return;

Don’t handle modifier shortcuts typically used by assistive technology.

      if (event.altKey)
        return;

The switch-case will determine which tab should be marked as active depending on the key that was pressed.

      let newTab;
      switch (event.keyCode) {
        case KEYCODE.LEFT:
        case KEYCODE.UP:
          newTab = this._prevTab();
          break;

        case KEYCODE.RIGHT:
        case KEYCODE.DOWN:
          newTab = this._nextTab();
          break;

        case KEYCODE.HOME:
          newTab = this._firstTab();
          break;

        case KEYCODE.END:
          newTab = this._lastTab();
          break;

Any other key press is ignored and passed back to the browser.

        default:
          return;
      }

The browser might have some native functionality bound to the arrow keys, home or end. The element calls preventDefault() to prevent the browser from taking any actions.

      event.preventDefault();

Select the new tab, that has been determined in the switch-case.

      this._selectTab(newTab);
    }

_onClick() handles clicks inside the tab panel.

    _onClick(event) {

If the click was not targeted on a tab element itself, it was a click inside the a panel or on empty space. Nothing to do.

      if (event.target.getAttribute('role') !== 'tab')
        return;

If it was on a tab element, though, select that tab.

      this._selectTab(event.target);
    }
  }

  customElements.define('howto-tabs', HowtoTabs);

howtoTabCounter counts the number of <howto-tab> instances created. The number is used to generated new, unique IDs.

  let howtoTabCounter = 0;

HowtoTab is a tab for a <howto-tabs> tab panel. <howto-tab> should always be used with role="heading" in the markup so that the semantics remain useable when JavaScript is failing.

A <howto-tab> declares which <howto-panel> it belongs to by using that panel’s ID as the value for the aria-controls attribute.

A <howto-tab> will automatically generate a unique ID if none is specified.

  class HowtoTab extends HTMLElement {

    static get observedAttributes() {
      return ['selected'];
    }

    constructor() {
      super();
    }

    connectedCallback() {

If this is executed, JavaScript is working and the element changes its role to tab.

      this.setAttribute('role', 'tab');
      if (!this.id)
        this.id = `howto-tab-generated-${howtoTabCounter++}`;

Set a well-defined initial state.

      this.setAttribute('aria-selected', 'false');
      this.setAttribute('tabindex', -1);
      this._upgradeProperty('selected');
    }

Check if a property has an instance value. If so, copy the value, and delete the instance property so it doesn't shadow the class property setter. Finally, pass the value to the class property setter so it can trigger any side effects. This is to safe guard against cases where, for instance, a framework may have added the element to the page and set a value on one of its properties, but lazy loaded its definition. Without this guard, the upgraded element would miss that property and the instance property would prevent the class property setter from ever being called.

    _upgradeProperty(prop) {
      if (this.hasOwnProperty(prop)) {
        let value = this[prop];
        delete this[prop];
        this[prop] = value;
      }
    }

Properties and their corresponding attributes should mirror one another. To this effect, the property setter for selected handles truthy/falsy values and reflects those to the state of the attribute. It’s important to note that there are no side effects taking place in the property setter. For example, the setter does not set aria-selected. Instead, that work happens in the attributeChangedCallback. As a general rule, make property setters very dumb, and if setting a property or attribute should cause a side effect (like setting a corresponding ARIA attribute) do that work in the attributeChangedCallback(). This will avoid having to manage complex attribute/property reentrancy scenarios.

    attributeChangedCallback() {
      const value = this.hasAttribute('selected');
      this.setAttribute('aria-selected', value);
      this.setAttribute('tabindex', value ? 0 : -1);
    }

    set selected(value) {
      value = Boolean(value);
      if (value)
        this.setAttribute('selected', '');
      else
        this.removeAttribute('selected');
    }

    get selected() {
      return this.hasAttribute('selected');
    }
  }

  customElements.define('howto-tab', HowtoTab);

  let howtoPanelCounter = 0;

HowtoPanel is a panel for a <howto-tabs> tab panel.

class HowtoPanel extends HTMLElement {

  constructor() {
    super();
  }

  connectedCallback() {
    this.setAttribute('role', 'tabpanel');
    if (!this.id)
      this.id = `howto-panel-generated-${howtoPanelCounter++}`;
  }
}

customElements.define('howto-panel', HowtoPanel);
})();

HowTo Components – howto-tooltip

2017-04-06T00:00:00Z

Summary #

A <howto-tooltip> is a popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it. The element that triggers the tooltip references the tooltip element with aria-describedby.

The element self-applies the role tooltip and sets tabindex to -1, as the tooltip itself can never be focused.

Reference #

Demo #

View live demo on GitHub

Example usage #

<div class="text">
<label for="name">Your name:</label>
<input id="name" aria-describedby="tp1"/>
<howto-tooltip id="tp1">Ideally your name is Batman</howto-tooltip>
<br>
<label for="cheese">Favourite type of cheese: </label>
<input id="cheese" aria-describedby="tp2"/>
<howto-tooltip id="tp2">Help I am trapped inside a tooltip message</howto-tooltip>

Code #

class HowtoTooltip extends HTMLElement {

The constructor does work that needs to be executed exactly once.

  constructor() {
    super();

These functions are used in a bunch of places, and always need to bind the correct this reference, so do it once.

    this._show = this._show.bind(this);
    this._hide = this._hide.bind(this);
}

connectedCallback() fires when the element is inserted into the DOM. It's a good place to set the initial role, tabindex, internal state, and install event listeners.

  connectedCallback() {
    if (!this.hasAttribute('role'))
      this.setAttribute('role', 'tooltip');

    if (!this.hasAttribute('tabindex'))
      this.setAttribute('tabindex', -1);

    this._hide();

The element that triggers the tooltip references the tooltip element with aria-describedby.

    this._target = document.querySelector('[aria-describedby=' + this.id + ']');
    if (!this._target)
      return;

The tooltip needs to listen to focus/blur events from the target, as well as hover events over the target.

    this._target.addEventListener('focus', this._show);
    this._target.addEventListener('blur', this._hide);
    this._target.addEventListener('mouseenter', this._show);
    this._target.addEventListener('mouseleave', this._hide);
  }

disconnectedCallback() unregisters the event listeners that were set up in connectedCallback().

  disconnectedCallback() {
    if (!this._target)
      return;

Remove the existing listeners, so that they don't trigger even though there's no tooltip to show.

    this._target.removeEventListener('focus', this._show);
    this._target.removeEventListener('blur', this._hide);
    this._target.removeEventListener('mouseenter', this._show);
    this._target.removeEventListener('mouseleave', this._hide);
    this._target = null;
  }

  _show() {
    this.hidden = false;
  }

  _hide() {
    this.hidden = true;
  }
}

customElements.define('howto-tooltip', HowtoTooltip);

HowTo Components – Overview

2017-04-06T00:00:00Z

"HowTo: Components" are a collection of web components that implement common UI patterns. The purpose of these implementations is to be an educational resource. You can read through the densely commented implementation of different components and hopefully learn from them. Note that they are explicitly NOT a UI library and should NOT be used in production.

Components #

<howto-checkbox>: represents a boolean option in a form. The most common type of checkbox is a dual-type which allows the user to toggle between two choices—checked and unchecked.
<howto-tabs>: limits visible content by separating it into multiple panels.
<howto-tooltip>: a popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.

Goals #

Our aim is to demonstrate best practices for writing robust components that are accessible, performant, maintainable, and easy to style. Each component is completely self-contained so it can serve as a reference implementation.

Accessibility #

The components closely follow the WAI ARIA Authoring Practices, which is a guide to explain and show ARIA, the Accessible Rich Internet Application standard. If you are unfamiliar with ARIA, check out our introduction on WebFundamentals. Each component links to the relevant section of the Authoring Practices. While not strictly necessary, we do recommend reading the section of the Authoring Practices before diving into the code.

Performance #

In web development the term "performance" can be applied to a multitude of things. In the context of <howto>, performance mostly refers to animations consistently running at 60fps, even on mobile devices.

Visual Flexibility #

As much as possible, components are not styled, except for layout or to indicate a selected or active state. This is to keep the implementation visually flexible and focused. By not spending time on decoration, we limit the code to only what is absolutely necessary to make the component function. If any style is required for the component to function, the style will be marked with a comment explaining why that is.

Maintainable code #

As HowTo: Components is a reference implementation, we spent extra time on writing readable and easily comprehensible code that is densely commented.

Non-Goals #

Be a library / framework / toolkit #

<howto> components are not published on npm, bower or any other platform because they are not meant to be used in production. For the sake of terse, readable code, we are using modern JavaScript APIs and are supporting modern browsers which implement the Web Components standards. You will be able to adapt the code to fit your own needs after reading these implementations.

Be backwards compatible #

The code should not be relied on directly. We might, and very likely will, drastically change the implementation and API of any element if a better implementation is discovered. This is a living resource where we can share, explore, and discuss best practices for building web UIs.

Be complete #

We currently don't (and probably won't) implement *all *components that can be found in the WAI ARIA Authoring Practices. However, re-using the principles used in other <howto> components should enable readers to implement any components that are missing.

ResizeObserver: it’s like document.onresize for elements

2016-10-07T00:00:00Z

Before ResizeObserver, you had to attach a listener to the document's resize event to get notified of any change of the viewport's dimensions. In the event handler, you would then have to figure out which elements have been affected by that change and call a specific routine to react appropriately. If you needed the new dimensions of an element after a resize, you had to call getBoundingClientRect() or getComputedStyle(), which can cause layout thrashing if you don't take care of batching all your reads and all your writes.

This didn't even cover cases where elements change their size without the main window having been resized. For example, appending new children, setting an element's display style to none, or similar actions can change the size of an element, its siblings, or its ancestors.

This is why ResizeObserver is a useful primitive. It reacts to changes in size of any of the observed elements, independent of what caused the change. It provides access to the new size of the observed elements too.

Browser support

Chrome 64, Supported 64
Firefox 69, Supported 69
Edge 79, Supported 79
Safari 13.1, Supported 13.1

Source

API #

All the APIs with the Observer suffix we mentioned above share a simple API design. ResizeObserver is no exception. You create a ResizeObserver object and pass a callback to the constructor. The callback is passed an array of ResizeObserverEntry objects—one entry per observed element—which contains the new dimensions for the element.

var ro = new ResizeObserver(entries => {
  for (let entry of entries) {
    const cr = entry.contentRect;
    console.log('Element:', entry.target);
    console.log(`Element size: ${cr.width}px x ${cr.height}px`);
    console.log(`Element padding: ${cr.top}px ; ${cr.left}px`);
  }
});

// Observe one or multiple elements
ro.observe(someElement);

Some details #

What is being reported? #

Generally, a ResizeObserverEntry reports the content box of an element through a property called contentRect, which returns a DOMRectReadOnly object. The content box is the box in which content can be placed. It is the border box minus the padding.

It's important to note that while ResizeObserver reports both the dimensions of the contentRect and the padding, it only watches the contentRect. Don't confuse contentRect with the bounding box of the element. The bounding box, as reported by getBoundingClientRect(), is the box that contains the entire element and its descendants. SVGs are an exception to the rule, where ResizeObserver will report the dimensions of the bounding box.

As of Chrome 84, ResizeObserverEntry has three new properties to provide more detailed information. Each of these properties returns a ResizeObserverSize object containing a blockSize property and an inlineSize property. This information is about the observered element at the time the callback is invoked.

borderBoxSize
contentBoxSize
devicePixelContentBoxSize

All of these items return read-only arrays because in the future it's hoped that they can support elements that have multiple fragments, which occur in multi-column scenarios. For now, these arrays will only contain one element.

Platform support for these properties is limited, but Firefox already supports the first two.

When is it being reported? #

The spec proscribes that ResizeObserver should process all resize events before paint and after layout. This makes the callback of a ResizeObserver the ideal place to make changes to your page's layout. Because ResizeObserver processing happens between layout and paint, doing so will only invalidate layout, not paint.

Gotcha #

You might be asking yourself: what happens if I change the size of an observed element inside the callback to ResizeObserver? The answer is: you will trigger another call to the callback right away. Fortunately, ResizeObserver has a mechanism to avoid infinite callback loops and cyclic dependencies. Changes will only be processed in the same frame if the resized element is deeper in the DOM tree than the shallowest element processed in the previous callback. Otherwise, they'll get deferred to the next frame.

Application #

One thing that ResizeObserver allows you to do is to implement per-element media queries. By observing elements, you can imperatively define your design breakpoints and change an element's styles. In the following example, the second box will change its border radius according to its width.

const ro = new ResizeObserver(entries => {
  for (let entry of entries) {
    entry.target.style.borderRadius =
        Math.max(0, 250 - entry.contentRect.width) + 'px';
  }
});
// Only observe the second box
ro.observe(document.querySelector('.box:nth-child(2)'));

Another interesting example to look at is a chat window. The problem that arises in a typical top-to-bottom conversation layout is scroll positioning. To avoid confusing the user, it is helpful if the window sticks to the bottom of the conversation, where the newest messages appear. Additionally, any kind of layout change (think of a phone going from landscape to portrait or vice versa) should achieve the same.

ResizeObserver allows you to write a single piece of code that takes care of both scenarios. Resizing the window is an event that a ResizeObserver can capture by definition, but calling appendChild() also resizes that element (unlessoverflow: hidden is set), because it needs to make space for the new elements. With this in mind, it takes very few lines to achieve the desired effect:

const ro = new ResizeObserver(entries => {
  document.scrollingElement.scrollTop =
    document.scrollingElement.scrollHeight;
});

// Observe the scrollingElement for when the window gets resized
ro.observe(document.scrollingElement);
// Observe the timeline to process new messages
ro.observe(timeline);

Pretty neat, huh?

From here, I could add more code to handle the case where the user has scrolled up manually and wants scrolling to stick to that message when a new message comes in.

Another use case is for any kind of custom element that is doing its own layout. Until ResizeObserver, there was no reliable way to get notified when its dimensions change so its children can be laid out again.

Conclusion #

ResizeObserver is available in most major browsers. In some cases, that availability is quite recent. There are some polyfills available but it is not possible to completely duplicate the functionality of ResizeObserver. Current implementations either rely on polling or on adding sentinel elements to the DOM. The former will drain your battery on mobile by keeping the CPU busy while the latter modifies your DOM and might mess up styling and other DOM-reliant code.

Photo by Markus Spiske on Unsplash.

Introduction to HTTP/2

2016-09-29T00:00:00Z

HTTP/2 will make our applications faster, simpler, and more robust — a rare combination — by allowing us to undo many of the HTTP/1.1 workarounds previously done within our applications and address these concerns within the transport layer itself. Even better, it also opens up a number of entirely new opportunities to optimize our applications and improve performance!

The primary goals for HTTP/2 are to reduce latency by enabling full request and response multiplexing, minimize protocol overhead via efficient compression of HTTP header fields, and add support for request prioritization and server push. To implement these requirements, there is a large supporting cast of other protocol enhancements, such as new flow control, error handling, and upgrade mechanisms, but these are the most important features that every web developer should understand and leverage in their applications.

HTTP/2 does not modify the application semantics of HTTP in any way. All the core concepts, such as HTTP methods, status codes, URIs, and header fields, remain in place. Instead, HTTP/2 modifies how the data is formatted (framed) and transported between the client and server, both of which manage the entire process, and hides all the complexity from our applications within the new framing layer. As a result, all existing applications can be delivered without modification.

Why not HTTP/1.2? #

To achieve the performance goals set by the HTTP Working Group, HTTP/2 introduces a new binary framing layer that is not backward compatible with previous HTTP/1.x servers and clients—hence the major protocol version increment to HTTP/2.

That said, unless you are implementing a web server (or a custom client) by working with raw TCP sockets, then you won’t see any difference: all the new, low-level framing is performed by the client and server on your behalf. The only observable differences will be improved performance and availability of new capabilities like request prioritization, flow control, and server push.

A brief history of SPDY and HTTP/2 #

SPDY was an experimental protocol, developed at Google and announced in mid 2009, whose primary goal was to try to reduce the load latency of web pages by addressing some of the well-known performance limitations of HTTP/1.1. Specifically, the outlined project goals were set as follows:

Target a 50% reduction in page load time (PLT).
Avoid the need for any changes to content by website authors.
Minimize deployment complexity, and avoid changes in network infrastructure.
Develop this new protocol in partnership with the open-source community.
Gather real performance data to (in)validate the experimental protocol.

Not long after the initial announcement, Mike Belshe and Roberto Peon, both software engineers at Google, shared their first results, documentation, and source code for the experimental implementation of the new SPDY protocol:

So far we have only tested SPDY in lab conditions. The initial results are very encouraging: when we download the top 25 websites over simulated home network connections, we see a significant improvement in performance—pages loaded up to 55% faster. (Chromium Blog)

Fast-forward to 2012 and the new experimental protocol was supported in Chrome, Firefox, and Opera, and a rapidly growing number of sites, both large (for example, Google, Twitter, Facebook) and small, were deploying SPDY within their infrastructure. In effect, SPDY was on track to become a de facto standard through growing industry adoption.

Observing this trend, the HTTP Working Group (HTTP-WG) kicked off a new effort to take the lessons learned from SPDY, build and improve on them, and deliver an official "HTTP/2" standard. A new charter was drafted, an open call for HTTP/2 proposals was made, and after a lot of discussion within the working group, the SPDY specification was adopted as a starting point for the new HTTP/2 protocol.

Over the next few years SPDY and HTTP/2 continued to coevolve in parallel, with SPDY acting as an experimental branch that was used to test new features and proposals for the HTTP/2 standard. What looks good on paper may not work in practice, and vice versa, and SPDY offered a route to test and evaluate each proposal before its inclusion in the HTTP/2 standard. In the end, this process spanned three years and resulted in a over a dozen intermediate drafts:

March 2012: Call for proposals for HTTP/2
November 2012: First draft of HTTP/2 (based on SPDY)
August 2014: HTTP/2 draft-17 and HPACK draft-12 are published
August 2014: Working Group last call for HTTP/2
February 2015: IESG approved HTTP/2 and HPACK drafts
May 2015: RFC 7540 (HTTP/2) and RFC 7541 (HPACK) are published

In early 2015 the IESG reviewed and approved the new HTTP/2 standard for publication. Shortly after that, the Google Chrome team announced their schedule to deprecate SPDY and NPN extension for TLS:

HTTP/2's primary changes from HTTP/1.1 focus on improved performance. Some key features such as multiplexing, header compression, prioritization and protocol negotiation evolved from work done in an earlier open, but non-standard protocol named SPDY. Chrome has supported SPDY since Chrome 6, but since most of the benefits are present in HTTP/2, it’s time to say goodbye. We plan to remove support for SPDY in early 2016, and to also remove support for the TLS extension named NPN in favor of ALPN in Chrome at the same time. Server developers are strongly encouraged to move to HTTP/2 and ALPN.

We’re happy to have contributed to the open standards process that led to HTTP/2, and hope to see wide adoption given the broad industry engagement on standardization and implementation. (Chromium Blog)

The coevolution of SPDY and HTTP/2 enabled server, browser, and site developers to gain real-world experience with the new protocol as it was being developed. As a result, the HTTP/2 standard is one of the best and most extensively tested standards right out of the gate. By the time HTTP/2 was approved by the IESG, there were dozens of thoroughly tested and production-ready client and server implementations. In fact, just weeks after the final protocol was approved, many users were already enjoying its benefits as several popular browsers (and many sites) deployed full HTTP/2 support.

Design and technical goals #

Earlier versions of the HTTP protocol were intentionally designed for simplicity of implementation: HTTP/0.9 was a one-line protocol to bootstrap the World Wide Web; HTTP/1.0 documented the popular extensions to HTTP/0.9 in an informational standard; HTTP/1.1 introduced an official IETF standard; see Brief History of HTTP. As such, HTTP/0.9-1.x delivered exactly what it set out to do: HTTP is one of the most widely adopted application protocols on the Internet.

Unfortunately, implementation simplicity also came at a cost of application performance: HTTP/1.x clients need to use multiple connections to achieve concurrency and reduce latency; HTTP/1.x does not compress request and response headers, causing unnecessary network traffic; HTTP/1.x does not allow effective resource prioritization, resulting in poor use of the underlying TCP connection; and so on.

These limitations were not fatal, but as the web applications continued to grow in their scope, complexity, and importance in our everyday lives, they imposed a growing burden on both the developers and users of the web, which is the exact gap that HTTP/2 was designed to address:

HTTP/2 enables a more efficient use of network resources and a reduced perception of latency by introducing header field compression and allowing multiple concurrent exchanges on the same connection… Specifically, it allows interleaving of request and response messages on the same connection and uses an efficient coding for HTTP header fields. It also allows prioritization of requests, letting more important requests complete more quickly, further improving performance.

The resulting protocol is more friendly to the network, because fewer TCP connections can be used in comparison to HTTP/1.x. This means less competition with other flows, and longer-lived connections, which in turn leads to better utilization of available network capacity. Finally, HTTP/2 also enables more efficient processing of messages through use of binary message framing. (Hypertext Transfer Protocol version 2, Draft 17)

It is important to note that HTTP/2 is extending, not replacing, the previous HTTP standards. The application semantics of HTTP are the same, and no changes were made to the offered functionality or core concepts such as HTTP methods, status codes, URIs, and header fields. These changes were explicitly out of scope for the HTTP/2 effort. That said, while the high-level API remains the same, it is important to understand how the low-level changes address the performance limitations of the previous protocols. Let’s take a brief tour of the binary framing layer and its features.

Binary framing layer #

At the core of all performance enhancements of HTTP/2 is the new binary framing layer, which dictates how the HTTP messages are encapsulated and transferred between the client and server.

The "layer" refers to a design choice to introduce a new optimized encoding mechanism between the socket interface and the higher HTTP API exposed to our applications: the HTTP semantics, such as verbs, methods, and headers, are unaffected, but the way they are encoded while in transit is different. Unlike the newline delimited plaintext HTTP/1.x protocol, all HTTP/2 communication is split into smaller messages and frames, each of which is encoded in binary format.

As a result, both client and server must use the new binary encoding mechanism to understand each other: an HTTP/1.x client won’t understand an HTTP/2 only server, and vice versa. Thankfully, our applications remain blissfully unaware of all these changes, as the client and server perform all the necessary framing work on our behalf.

Streams, messages, and frames #

The introduction of the new binary framing mechanism changes how the data is exchanged between the client and server. To describe this process, let’s familiarize ourselves with the HTTP/2 terminology:

Stream: A bidirectional flow of bytes within an established connection, which may carry one or more messages.
Message: A complete sequence of frames that map to a logical request or response message.
Frame: The smallest unit of communication in HTTP/2, each containing a frame header, which at a minimum identifies the stream to which the frame belongs.

The relation of these terms can be summarized as follows:

All communication is performed over a single TCP connection that can carry any number of bidirectional streams.
Each stream has a unique identifier and optional priority information that is used to carry bidirectional messages.
Each message is a logical HTTP message, such as a request, or response, which consists of one or more frames.
The frame is the smallest unit of communication that carries a specific type of data—e.g., HTTP headers, message payload, and so on. Frames from different streams may be interleaved and then reassembled via the embedded stream identifier in the header of each frame.

In short, HTTP/2 breaks down the HTTP protocol communication into an exchange of binary-encoded frames, which are then mapped to messages that belong to a particular stream, all of which are multiplexed within a single TCP connection. This is the foundation that enables all other features and performance optimizations provided by the HTTP/2 protocol.

Request and response multiplexing #

With HTTP/1.x, if the client wants to make multiple parallel requests to improve performance, then multiple TCP connections must be used (see Using Multiple TCP Connections ). This behavior is a direct consequence of the HTTP/1.x delivery model, which ensures that only one response can be delivered at a time (response queuing) per connection. Worse, this also results in head-of-line blocking and inefficient use of the underlying TCP connection.

The new binary framing layer in HTTP/2 removes these limitations, and enables full request and response multiplexing, by allowing the client and server to break down an HTTP message into independent frames, interleave them, and then reassemble them on the other end.

The snapshot captures multiple streams in flight within the same connection. The client is transmitting a DATA frame (stream 5) to the server, while the server is transmitting an interleaved sequence of frames to the client for streams 1 and 3. As a result, there are three parallel streams in flight.

The ability to break down an HTTP message into independent frames, interleave them, and then reassemble them on the other end is the single most important enhancement of HTTP/2. In fact, it introduces a ripple effect of numerous performance benefits across the entire stack of all web technologies, enabling us to:

Interleave multiple requests in parallel without blocking on any one.
Interleave multiple responses in parallel without blocking on any one.
Use a single connection to deliver multiple requests and responses in parallel.
Remove unnecessary HTTP/1.x workarounds (see Optimizing for HTTP/1.x, such as concatenated files, image sprites, and domain sharding).
Deliver lower page load times by eliminating unnecessary latency and improving utilization of available network capacity.
And much more…

The new binary framing layer in HTTP/2 resolves the head-of-line blocking problem found in HTTP/1.x and eliminates the need for multiple connections to enable parallel processing and delivery of requests and responses. As a result, this makes our applications faster, simpler, and cheaper to deploy.

Stream prioritization #

Once an HTTP message can be split into many individual frames, and we allow for frames from multiple streams to be multiplexed, the order in which the frames are interleaved and delivered both by the client and server becomes a critical performance consideration. To facilitate this, the HTTP/2 standard allows each stream to have an associated weight and dependency:

Each stream may be assigned an integer weight between 1 and 256.
Each stream may be given an explicit dependency on another stream.

The combination of stream dependencies and weights allows the client to construct and communicate a "prioritization tree" that expresses how it would prefer to receive responses. In turn, the server can use this information to prioritize stream processing by controlling the allocation of CPU, memory, and other resources, and once the response data is available, allocation of bandwidth to ensure optimal delivery of high-priority responses to the client.

A stream dependency within HTTP/2 is declared by referencing the unique identifier of another stream as its parent; if the identifier is omitted the stream is said to be dependent on the "root stream". Declaring a stream dependency indicates that, if possible, the parent stream should be allocated resources ahead of its dependencies. In other words, "Please process and deliver response D before response C".

Streams that share the same parent (in other words, sibling streams) should be allocated resources in proportion to their weight. For example, if stream A has a weight of 12 and its one sibling B has a weight of 4, then to determine the proportion of the resources that each of these streams should receive:

Sum all the weights: 4 + 12 = 16
Divide each stream weight by the total weight: A = 12/16, B = 4/16

Thus, stream A should receive three-quarters and stream B should receive one- quarter of available resources; stream B should receive one-third of the resources allocated to stream A. Let’s work through a few more hands-on examples in the image above. From left to right:

Neither stream A nor B specifies a parent dependency and are said to be dependent on the implicit "root stream"; A has a weight of 12, and B has a weight of 4. Thus, based on proportional weights: stream B should receive one-third of the resources allocated to stream A.
Stream D is dependent on the root stream; C is dependent on D. Thus, D should receive full allocation of resources ahead of C. The weights are inconsequential because C’s dependency communicates a stronger preference.
Stream D should receive full allocation of resources ahead of C; C should receive full allocation of resources ahead of A and B; stream B should receive one-third of the resources allocated to stream A.
Stream D should receive full allocation of resources ahead of E and C; E and C should receive equal allocation ahead of A and B; A and B should receive proportional allocation based on their weights.

As the above examples illustrate, the combination of stream dependencies and weights provides an expressive language for resource prioritization, which is a critical feature for improving browsing performance where we have many resource types with different dependencies and weights. Even better, the HTTP/2 protocol also allows the client to update these preferences at any point, which enables further optimizations in the browser. In other words, we can change dependencies and reallocate weights in response to user interaction and other signals.

One connection per origin #

With the new binary framing mechanism in place, HTTP/2 no longer needs multiple TCP connections to multiplex streams in parallel; each stream is split into many frames, which can be interleaved and prioritized. As a result, all HTTP/2 connections are persistent, and only one connection per origin is required, which offers numerous performance benefits.

For both SPDY and HTTP/2 the killer feature is arbitrary multiplexing on a single well congestion controlled channel. It amazes me how important this is and how well it works. One great metric around that which I enjoy is the fraction of connections created that carry just a single HTTP transaction (and thus make that transaction bear all the overhead). For HTTP/1 74% of our active connections carry just a single transaction—persistent connections just aren’t as helpful as we all want. But in HTTP/2 that number plummets to 25%. That’s a huge win for overhead reduction. (HTTP/2 is Live in Firefox, Patrick McManus)

Most HTTP transfers are short and bursty, whereas TCP is optimized for long- lived, bulk data transfers. By reusing the same connection, HTTP/2 is able to both make more efficient use of each TCP connection, and also significantly reduce the overall protocol overhead. Further, the use of fewer connections reduces the memory and processing footprint along the full connection path (in other words, client, intermediaries, and origin servers). This reduces the overall operational costs and improves network utilization and capacity. As a result, the move to HTTP/2 should not only reduce network latency, but also help improve throughput and reduce the operational costs.

Flow control #

Flow control is a mechanism to prevent the sender from overwhelming the receiver with data it may not want or be able to process: the receiver may be busy, under heavy load, or may only be willing to allocate a fixed amount of resources for a particular stream. For example, the client may have requested a large video stream with high priority, but the user has paused the video and the client now wants to pause or throttle its delivery from the server to avoid fetching and buffering unnecessary data. Alternatively, a proxy server may have fast downstream and slow upstream connections and similarly wants to regulate how quickly the downstream delivers data to match the speed of upstream to control its resource usage; and so on.

Do the above requirements remind you of TCP flow control? They should, as the problem is effectively identical (see Flow Control). However, because the HTTP/2 streams are multiplexed within a single TCP connection, TCP flow control is both not granular enough, and does not provide the necessary application-level APIs to regulate the delivery of individual streams. To address this, HTTP/2 provides a set of simple building blocks that allow the client and server to implement their own stream- and connection-level flow control:

Flow control is directional. Each receiver may choose to set any window size that it desires for each stream and the entire connection.
Flow control is credit-based. Each receiver advertises its initial connection and stream flow control window (in bytes), which is reduced whenever the sender emits a DATA frame and incremented via a WINDOW_UPDATE frame sent by the receiver.
Flow control cannot be disabled. When the HTTP/2 connection is established the client and server exchange SETTINGS frames, which set the flow control window sizes in both directions. The default value of the flow control window is set to 65,535 bytes, but the receiver can set a large maximum window size (2^31-1 bytes) and maintain it by sending a WINDOW_UPDATE frame whenever any data is received.
Flow control is hop-by-hop, not end-to-end. That is, an intermediary can use it to control resource use and implement resource allocation mechanisms based on own criteria and heuristics.

HTTP/2 does not specify any particular algorithm for implementing flow control. Instead, it provides the simple building blocks and defers the implementation to the client and server, which can use it to implement custom strategies to regulate resource use and allocation, as well as implement new delivery capabilities that may help improve both the real and perceived performance (see Speed, Performance, and Human Perception) of our web applications.

For example, application-layer flow control allows the browser to fetch only a part of a particular resource, put the fetch on hold by reducing the stream flow control window down to zero, and then resume it later. In other words, it allows the browser to fetch a preview or first scan of an image, display it and allow other high priority fetches to proceed, and resume the fetch once more critical resources have finished loading.

Server push #

Another powerful new feature of HTTP/2 is the ability of the server to send multiple responses for a single client request. That is, in addition to the response to the original request, the server can push additional resources to the client (Figure 12-5), without the client having to request each one explicitly.

Why would we need such a mechanism in a browser? A typical web application consists of dozens of resources, all of which are discovered by the client by examining the document provided by the server. As a result, why not eliminate the extra latency and let the server push the associated resources ahead of time? The server already knows which resources the client will require; that’s server push.

In fact, if you have ever inlined a CSS, JavaScript, or any other asset via a data URI (see Resource Inlining), then you already have hands-on experience with server push. By manually inlining the resource into the document, we are, in effect, pushing that resource to the client, without waiting for the client to request it. With HTTP/2 we can achieve the same results, but with additional performance benefits. Push resources can be:

Cached by the client
Reused across different pages
Multiplexed alongside other resources
Prioritized by the server
Declined by the client

PUSH_PROMISE 101 #

All server push streams are initiated via PUSH_PROMISE frames, which signal the server’s intent to push the described resources to the client and need to be delivered ahead of the response data that requests the pushed resources. This delivery order is critical: the client needs to know which resources the server intends to push to avoid creating duplicate requests for these resources. The simplest strategy to satisfy this requirement is to send all PUSH_PROMISE frames, which contain just the HTTP headers of the promised resource, ahead of the parent’s response (in other words, DATA frames).

Once the client receives a PUSH_PROMISE frame it has the option to decline the stream (via a RST_STREAM frame) if it wants to. (This might occur for example because the resource is already in cache.) This is an important improvement over HTTP/1.x. By contrast, the use of resource inlining, which is a popular "optimization" for HTTP/1.x, is equivalent to a "forced push": the client cannot opt-out, cancel it, or process the inlined resource individually.

With HTTP/2 the client remains in full control of how server push is used. The client can limit the number of concurrently pushed streams; adjust the initial flow control window to control how much data is pushed when the stream is first opened; or disable server push entirely. These preferences are communicated via the SETTINGS frames at the beginning of the HTTP/2 connection and may be updated at any time.

Each pushed resource is a stream that, unlike an inlined resource, allows it to be individually multiplexed, prioritized, and processed by the client. The only security restriction, as enforced by the browser, is that pushed resources must obey the same-origin policy: the server must be authoritative for the provided content.

Header compression #

Each HTTP transfer carries a set of headers that describe the transferred resource and its properties. In HTTP/1.x, this metadata is always sent as plain text and adds anywhere from 500–800 bytes of overhead per transfer, and sometimes kilobytes more if HTTP cookies are being used. (See Measuring and Controlling Protocol Overhead .) To reduce this overhead and improve performance, HTTP/2 compresses request and response header metadata using the HPACK compression format that uses two simple but powerful techniques:

It allows the transmitted header fields to be encoded via a static Huffman code, which reduces their individual transfer size.
It requires that both the client and server maintain and update an indexed list of previously seen header fields (in other words, it establishes a shared compression context), which is then used as a reference to efficiently encode previously transmitted values.

Huffman coding allows the individual values to be compressed when transferred, and the indexed list of previously transferred values allows us to encode duplicate values by transferring index values that can be used to efficiently look up and reconstruct the full header keys and values.

As one further optimization, the HPACK compression context consists of a static and dynamic table: the static table is defined in the specification and provides a list of common HTTP header fields that all connections are likely to use (e.g., valid header names); the dynamic table is initially empty and is updated based on exchanged values within a particular connection. As a result, the size of each request is reduced by using static Huffman coding for values that haven’t been seen before, and substitution of indexes for values that are already present in the static or dynamic tables on each side.

Security and performance of HPACK #

Early versions of HTTP/2 and SPDY used zlib, with a custom dictionary, to compress all HTTP headers. This delivered an 85% to 88% reduction in the size of the transferred header data, and a significant improvement in page load time latency:

On the lower-bandwidth DSL link, in which the upload link is only 375 Kbps, request header compression in particular, led to significant page load time improvements for certain sites (in other words, those that issued large number of resource requests). We found a reduction of 45–1142 ms in page load time simply due to header compression. (SPDY whitepaper, chromium.org)

However, in the summer of 2012, a "CRIME" security attack was published against TLS and SPDY compression algorithms, which could result in session hijacking. As a result, the zlib compression algorithm was replaced by HPACK, which was specifically designed to: address the discovered security issues, be efficient and simple to implement correctly, and of course, enable good compression of HTTP header metadata.

For full details of the HPACK compression algorithm, see IETF HPACK - Header Compression for HTTP/2.

Feedback #

IntersectionObserver's coming into view

2016-04-20T00:00:00Z

Browser support

Chrome 51, Supported 51
Firefox 55, Supported 55
Edge 15, Supported 15
Safari 12.1, Supported 12.1

Source

Let's say you want to track when an element in your DOM enters the visible viewport. You might want to do this so you can lazy-load images just in time or because you need to know if the user is actually looking at a certain ad banner. You can do that by hooking up the scroll event or by using a periodic timer and calling getBoundingClientRect() on that element.

This approach, however, is painfully slow as each call to getBoundingClientRect() forces the browser to re-layout the entire page and will introduce considerable jank to your website. Matters get close to impossible when you know your site is being loaded inside an iframe and you want to know when the user can see an element. The Single Origin Model and the browser won't let you access any data from the web page that contains the iframe. This is a common problem for ads for example, that are frequently loaded using iframes.

Making this visibility test more efficient is what IntersectionObserver was designed for, and it's landed in all modern browsers. IntersectionObserver lets you know when an observed element enters or exits the browser's viewport.

How to create an `IntersectionObserver` #

The API is rather small, and best described using an example:

const io = new IntersectionObserver(entries => {
  console.log(entries);
}, {
  /* Using default options. Details below */
});

// Start observing an element
io.observe(element);

// Stop observing an element
// io.unobserve(element);

// Disable entire IntersectionObserver
// io.disconnect();

Using the default options for IntersectionObserver, your callback will be called both when the element comes partially into view and when it completely leaves the viewport.

If you need to observe multiple elements, it is both possible and advised to observe multiple elements using the same IntersectionObserver instance by calling observe() multiple times.

An entries parameter is passed to your callback which is an array of IntersectionObserverEntry objects. Each such object contains updated intersection data for one of your observed elements.

🔽[IntersectionObserverEntry]
    time: 3893.92
    🔽rootBounds: ClientRect
        bottom: 920
        height: 1024
        left: 0
        right: 1024
        top: 0
        width: 920
    🔽boundingClientRect: ClientRect
    // ...
    🔽intersectionRect: ClientRect
    // ...
    intersectionRatio: 0.54
    🔽target: div#observee
    // ...

rootBounds is the result of calling getBoundingClientRect() on the root element, which is the viewport by default. boundingClientRect is the result of getBoundingClientRect() called on the observed element. intersectionRect is the intersection of these two rectangles and effectively tells you which part of the observed element is visible. intersectionRatio is closely related, and tells you how much of the element is visible. With this info at your disposal, you are now able to implement features like just-in-time loading of assets before they become visible on screen. Efficiently.

IntersectionObservers deliver their data asynchronously, and your callback code will run in the main thread. Additionally, the spec actually says that IntersectionObserver implementations should use requestIdleCallback(). This means that the call to your provided callback is low priority and will be made by the browser during idle time. This is a conscious design decision.

Scrolling divs #

I am not a big fan of scrolling inside an element, but I am not here to judge, and neither is IntersectionObserver. The options object takes a root option that lets you define an alternative to the viewport as your root. It is important to keep in mind that root needs to be an ancestor of all the observed elements.

Intersect all the things! #

No! Bad developer! That's not mindful usage of your user's CPU cycles. Let's think about an infinite scroller as an example: In that scenario, it is definitely advisable to add sentinels to the DOM and observe (and recycle!) those. You should add a sentinel close to the last item in the infinite scroller. When that sentinel comes into view, you can use the callback to load data, create the next items, attach them to the DOM and reposition the sentinel accordingly. If you properly recycle the sentinel, no additional call to observe() is needed. The IntersectionObserver keeps working.

More updates, please #

As mentioned earlier, the callback will be triggered a single time when the observed element comes partially into view and another time when it has left the viewport. This way IntersectionObserver gives you an answer to the question, "Is element X in view?". In some use cases, however, that might not be enough.

That's where the threshold option comes into play. It allows you to define an array of intersectionRatio thresholds. Your callback will be called every time intersectionRatio crosses one of these values. The default value for threshold is [0], which explains the default behavior. If we change threshold to [0, 0.25, 0.5, 0.75, 1], we will get notified every time an additional quarter of the element becomes visible:

Any other options? #

As of now, there's only one additional option to the ones listed above. rootMargin allows you to specify the margins for the root, effectively allowing you to either grow or shrink the area used for intersections. These margins are specified using a CSS-style string, á la "10px 20px 30px 40px", specifying top, right, bottom and left margin respectively. To summarize, the IntersectionObserver options struct offers the following options:

new IntersectionObserver(entries => {/* … */}, {
  // The root to use for intersection.
  // If not provided, use the top-level document's viewport.
  root: null,
  // Same as margin, can be 1, 2, 3 or 4 components, possibly negative lengths.
  // If an explicit root element is specified, components may be percentages of the
  // root element size.  If no explicit root element is specified, using a
  // percentage is an error.
  rootMargin: "0px",
  // Threshold(s) at which to trigger callback, specified as a ratio, or list of
  // ratios, of (visible area / total area) of the observed element (hence all
  // entries must be in the range [0, 1]).  Callback will be invoked when the
  // visible ratio of the observed element crosses a threshold in the list.
  threshold: [0],
});

`<iframe>` magic #

IntersectionObservers were designed specifically with ads services and social network widgets in mind, which frequently use <iframe> elements and could benefit from knowing whether they are in view. If an <iframe> observes one of its elements, both scrolling the <iframe> as well as scrolling the window containing the <iframe> will trigger the callback at the appropriate times. For the latter case, however, rootBounds will be set to null to avoid leaking data across origins.

What is `IntersectionObserver` Not about? #

Something to keep in mind is that IntersectionObserver is intentionally neither pixel perfect nor low latency. Using them to implement endeavours like scroll-dependent animations are bound to fail, as the data will be—strictly speaking—out of date by the time you'll get to use it. The explainer has more details about the original use cases for IntersectionObserver.

How much work can I do in the callback? #

Short 'n Sweet: Spending too much time in the callback will make your app lag—all the common practices apply.

Go forth and intersect thy elements #

The browser support for IntersectionObserver is good, as it is available in all modern browsers. If necessary, a polyfill can be used in older browsers and is available in WICG's repository. Obviously, you won't get the performance benefits using that polyfill that a native implementation would give you.

You can start using IntersectionObserver right now! Tell us what you came up with.

Surma on web.dev

Deep-copying in JavaScript using structuredClone

Shallow copies #

Deep copies #

Structured cloning #

Features and limitations #

Performance #

Conclusion #

Introducing libSquoosh

Pixel-perfect rendering with devicePixelContentBox

Background: CSS pixels, canvas pixels, and physical pixels #

Pixel perfection #

Pixel snapping #

devicePixelContentBox #

Feature detection #

Conclusion #

Use web workers to run JavaScript off the browser's main thread

Why web workers? #

Threading with web workers #

main.js #

worker.js #

main.js #

worker.js #

Comlink: making web workers less work #

worker.js #

main.js #

What code should you move to a web worker? #

PROXX: an OMT case study #

Implications of an OMT architecture #

Considering the tradeoffs #

A note about tooling #

Summing up #

Techniques to make a web app load fast, even on a feature phone

Capturing the status quo #

Waterfall analysis #

Reducing connection count #

Parallelizing loads #

Results #

Prerendering #

Inlining #

Aggressive code splitting #

More Sleight of Hand #

Conclusion #

Emscripten and npm

Docker #

Integration with npm #

Adding C/C++ code as a dependency #

Customizing the build environment #

Conclusion #

Appendix: Making use of Docker image layers #

Emscripten’s embind

C++ name mangling #

Enter embind #

Objects #

Classes #

What about C? #

Conclusion #

Emscripting a C library to Wasm

The toolchain #

Compiling something simple #

Running something simple #

The holy grail: Compiling a C library #

Get an image from JavaScript into Wasm #

Grand Finale: Encode the image #

Conclusion #

Bonus content: Running something simple the hard way #

HowTo Components – howto-checkbox

Summary #

Reference #

Demo #

Example usage #

Code #

HowTo Components – howto-tabs

Summary #

Reference #

Demo #

Example usage #

Code #

HowTo Components – howto-tooltip

Summary #

`devicePixelContentBox` #

`main.js` #

`worker.js` #

`main.js` #

`worker.js` #

`worker.js` #

`main.js` #

How to create an `IntersectionObserver` #

`<iframe>` magic #

What is `IntersectionObserver` Not about? #