web.dev

Ready Player Web

2019-08-20T17:00:00-07:00

Good game developers know that to capitalise on the opportunity of a particular platform it's important to embrace the unique characteristics of that platform. So what are the unique characteristics of the web? And what defines a web game?

At Google I/O 2019 I presented my thoughts on the state of the web games ecosystem, the current best practices for modern web game development, and where the industry is heading. In this blog post, I'll summarise some of the key points from my talk which you can watch in full on YouTube:

The challenges of web games

Before joining Google I created a mobile game known as Duet which was downloaded nearly 20 million times. Through that experience I learned that the three essential ingredients to building a successful business out of a game are:

A functional game
Users
A way to monetize users

Without these three elements, a game developer cannot succeed. Nowadays, these last two points are the most critical. Closed HTML5 ecosystems such as WeChat, Facebook Instant Games, and more have demonstrated that building games using HTML5 is achievable.

Modern best practices

By "functional game" I refer to the three most core elements of what makes a game work:

Performance
Visuals
Audio

In each of these areas, the web platform has made significant strides in the past few years. For CPU performance we have access to a performant new standard called Web Assembly. From the graphics side, WebGL 1.0 has good cross-browser support and future standards such as WebGPU are positioning the web platform for an extensible future of graphics programming similar to Vulkan and Metal. Finally, for web audio we have the common Web Audio API and more recently the Audio Worklet API.

Recently, Unity previewed a new runtime called Project Tiny which is focused on building 2D games for HTML5-based platforms. Project Tiny applies a new modular design to the engine structure of Unity enabling the core Unity engine to be under 1 megabyte in size.

Unity's Tanks Demo exported via HTML5.

From the technical side, there has never been a better time to embrace web game development.

Enter the loop

A great game is obviously more than just good performance, graphics, and sound though–to be great a game must be fun.

Fun is a difficult element to measure in a product. When a game is fun, interesting, or innovative enough, users will want to tell their friends–in other words, they'll want to share the experience. Tapping into this opportunity and coupling it with the web is a powerful combination that unlocks a lot of potential for viral growth. And on the web in particular, without a central discovery platform, our best bet towards acquiring users is to ensure our games are as viral as possible.

Good game developers know that to capitalise on a particular platform–whether at a software or hardware level–it's important to embrace the unique characteristics of that platform. For example, if you're building a game for a console with motion controls, you should probably think about the best way to embrace those motion controls.

In other words, you must respect the expectations of the users of the platform you're building for. What do users of the web expect? They expect web content to load fast and be interactive quickly. In my talk, I covered several examples of ways–both on and off the web–that games have been designed to load quickly, pull users into their game worlds, engage those users, and provide users with additional incentives to share their experiences.

I personally believe that the key to building a successful web game is to lean into this unique characteristic of the web. Specifically, the strength of the web's URL structure and the sharing loop that users can join in.

Here's an example of a web game I built using Construct 3 that leverages the URL in a fun and engaging way.

Space Board is a very simple game that can be played on either mobile with touch controls or on desktop with keyboard input. The objective is to navigate a maze of obstacles to reach a goal at the end.

How does Space Board leverage the URL in a unique fashion? By encoding the level structure into the URL itself. All levels are defined as a 10 by 10 grid of objects–e.g. walls, enemy turrets, keys, locked doors etc. The URL then lists all the individual grid positions and their contents. A wall is represented by a W character. An empty space is an underscore character.

Here's an example:

https://io-space-board.firebaseapp.com/?gameWorld=_wwwwwwwwww___ww__eww_k__d___ww___ww___ww_wwwww_www_wwwww_www___ww___ww_s_ww_f_ww___ww___wwwwwwwwwwww

It's ugly but it does the job.

Upon completing a level in Space Board, the player has the opportunity to design their own level using the simple level editor shown above. By enabling players to design their own levels we are giving them the opportunity for personalisation. When a user feels a connection to a game and a sense of ownership via creation and customisation they are more likely to want to share that 'thing' with the world.

The desire to share a game is the beginning of the viral loop that we are aiming to achieve with our web games. This game design and sharing mechanism is just one example that's possible but there are many other possibilities–I encourage you to watch my talk for further examples!

Return on investment

At present, there are ultimately two schools of thought with regards to how a game developer can generate revenue through web games:

Monetizing the games directly
Treating them as an acquisition channel

Treating web games as an acquisition channel means leveraging the web version of your native game as a mechanism to get your players hooked and convincing them to download your larger native binary. You then generate revenue with the native platform's built-in payment and billing backends.

Monetization is usually a mixture of advertising and microtransactions. There is still work to be done for the web to compete with native mobile platforms in game advertising. For example, formats like Rewarded Video Ads have been extremely popular for native mobile games for several years and yet we're only now seeing ad networks deploy these formats on the web.

Nonetheless, there are game developers who continue to be successful on the open web through advertising via traditional banner ads and interstitial video ads. Take a look at Adsense for Games for more information on these formats.

For microtransactions, the web offers complete flexibility due to the limitless number of payment methods that can be implemented. However this quality is a double-edged sword. The negative side of this is that players have less implicit trust towards a new website they discover versus the familiarity of the native mobile store payment methods.

One solution that brings a more consistent payment UI to the web is the Payment Request API. This API invokes a UI that is shown by the browser and streamlines the acquisition of payment details such as credit cards and billing addresses. However, acquiring payment details is just the first step of making a transaction. You need a backend billing platform as well.

The future

We've seen several surprisingly successful web games over the past few years. Slither.io has built a mixed web and native business that demonstrates the tremendous reach and viral growth opportunity that the web offers. Portals such as Poki.com are innovating in their user experience and releasing new games every month that match the fidelity of their mobile counterparts, such as Crossy Road.

Furthermore, if you look outside of the open web you can see that web games are already taking off. Closed ecosystems such as WeChat and LINE offer satisfying games which aren't playable on the open web but which are built on top of web technologies like HTML5 and WebViews. This is a clear sign that the web has reached a level of fidelity that's capable of rivaling native mobile games–perhaps not in a textbook definition of fidelity but in a more important metric: player attention.

Progressive Web Apps in multi-origin sites

2019-08-18T17:00:00-07:00

Background

In the past, there were some advantages to using multi-origin architectures, but for Progressive Web Apps, that approach presents many challenges. In particular, the same-origin policy, imposes restrictions for sharing things like service workers and caches, permissions, and for achieving a standalone experience across multiple origins. This article will describe the good and bad uses of multiple origins, and explain the challenges and workarounds for building Progressive Web Apps in multi-origin sites.

Good and bad uses of multiple origins

There are a few legitimate reasons for sites to employ a multi-origin architecture, mostly related to providing an independent set of web applications, or to create experiences that are completely isolated from each other. There are also uses that should be avoided.

The good

Let's look at the useful reasons first:

Localization / Language: Using a country-code top-level domain, to separate sites to be served in different countries (e.g. https://www.google.com.ar), or using subdomains to divide sites targeted to different locations (e.g.: https://newyork.craigslist.org) or to offer content for a specific language (e.g. https://en.wikipedia.org).
Device/Platform: Using different subdomains, to deliver different versions of a website to different devices. The m. or mobile. pattern is a common way to separate mobile from desktop in adaptive sites. For example: a site can maintain its desktop version at https://www.example.com and mobile version at https://m.example.com.
Independent webapps: Using different subdomains to provide experiences whose purpose differs considerably from the site on the main origin. For example, in a news site, the crosswords webapp could be intentionally served from https://crosswords.example.com, and installed and used as an independent PWA, without having to share any resources or functionality with the main website.

The bad

If you're not doing any of these things, it's likely that using a multi-origin architecture will be a disadvantage when building Progressive Web Apps.

Despite this, many sites continue being structured this way for no particular reason, or for 'legacy' reasons. One example is using subdomains to arbitrarily separate parts of a site that should be part of a unified experience.

The following patterns, for example, are highly discouraged:

Site sections: Separating different sections of a site on subdomains. In news sites, it's not uncommon to see the home page at: https://www.example.com, while the sports section lives at https://sports.example.com, politics at https://politics.example.com, and so forth. In the case of an e-commerce site, using something like https://category.example.com for product categories, https://product.example.com for product pages, etc.
User Flow: Another approach that's discouraged is to separate different smaller parts of the site, like pages for the login or purchase flows in subdomains. For example, using https://login.example.com, and https://checkout.example.com.

When building a site from scratch it's highly recommended to avoid dividing it into subdomains. For existing sites, migrating to a single origin is the best approach.

For those cases where migrating to a single origin is not possible, what follows is a list of challenges, and (where possible), workarounds that can be considered when building Progressive Web Apps.

Challenges and Workarounds for PWAs across different origins

When building a website on multiple origins, providing a unified PWA experience is challenging, mostly because of the same-origin policy, which imposes a number of constraints. Let's look at them one at a time.

Service workers

The origin of the service worker script URL has to be the same as the origin of the page calling register(). This means that, for example, a page at https://www.example.com can't call register() with a service worker url at https://section.example.com.

Another consideration is that a service worker can only control pages hosted under the origin and path it belongs to. This means that, if the service worker is hosted at https://www.example.com it can only control URLs from that origin (according to the path defined in the scope parameter), but won't control any page in other subdomains such as, for example, those in https://section.example.com.

In this case, the only workaround is to use multiple service workers (one per origin).

Caution: Registering, and having multiple active service workers consumes additional resources (memory, CPU, etc.), so use your best judgement on how many active service workers a user will likely need to navigate across the site.

Caching

The Cache object, indexedDB, and localStorage are also constrained to a single origin. This means it's not possible to access the caches that belong to https://www.example.com, from, for example: https://www.section.example.com.

Here are some things you can do to manage caches properly in scenarios like this:

Leverage browser caching: Using traditional browser caching best practices is always recommended. This technique provides the added benefit of reusing cached resources across origins, which can't be done with the service worker's cache. For best practices on how to use HTTP Cache with service workers, you can take a look at this post.
Keep service worker installation lightweight: If you are maintaining multiple service workers, avoid making users pay a big installation cost every time they navigate to a new origin. In other words: only pre-cache resources that are absolutely necessary.

Gotchas!

Once the service worker is active and running, the same-origin policy also restricts cross-origin requests made inside service workers. Fortunately this has a recommended workaround, which is to use CORS (as explained here). Using the no-cors mode when fetching resources inside the service worker is not recommended.

Permissions

Permissions are also scoped to origins. This means that if a user granted a given permission to the origin https://maps.google.com, it won't carry over to other origins, like https://www.google.com.

Since there's no way to share permissions across origins, the only solution here is to ask for permission on each of subdomain where a given feature is required (e.g. location). For things like web push, you can maintain a cookie to track if the permission has been accepted by the user in another subdomain, to avoid requesting it again.

Installation

To install a PWA, each origin must have its own manifest with a start_url that's relative to itself. This means that a user receiving the installation prompt on a given origin (i.e: https://section.example.com) won't be able to install the PWA with a start_url on a different one (i.e: https://www.example.com). In other words, users receiving the installation prompt in a subdomain will only be able to install PWAs for the subpages, not for the main URL of the app.

A simple workaround is to use astart_url with a redirect to the main origin. For example: subdomain https://section.example.com, can define a start_url of https://section.example.com/pwa, containing a redirect to: https://www.example.com, making the user always land at the home page.

There's also the issue that the same user could receive multiple installation prompts when navigating the site, if each subdomain meets the installation criteria, and prompts the user to install the PWA.

Mitigate this problem by applying any of the following techniques:

Showing the prompt on a single domain: If the site has many subdomains that pass the installation criteria, the beforeinstallprompt event could be used and preventDefault() called (as explained here), to prevent the prompt from appearing in unintended parts of the site (like subdomains), while continue to show it in other parts (e.g. the home page).
Showing the prompt once, across different subdomains: It's also possible to let each subdomain show the installation prompt. (This can make sense if some subdomains are more frequently visited). In this case, it's important to avoid showing the prompt to a user multiple times. To that purpose, a cookie could be used, to track if the prompt has already been shown, and check for its existence when the beforeinstallprompt event is triggered. If the cookie is present, it means that the user already received the prompt somewhere else, so preventDefault() can be called, to avoid showing it again.

Standalone Mode

While navigating in a standalone window, the browser will behave differently when the user moves outside of the scope set by the PWA's manifest. The behavior depends on each browser version and vendor. For example, the latest Chrome versions open a Chrome custom tab, when a user moves out of the scope in fullscreen mode.

In most cases, there's no solution for this, but a workaround can be applied for small parts of the experience that are hosted in subdomains (for example: login workflows):

The new URL, https://login.example.com, could open inside a full screen iframe.
Once the task is completed inside the iframe (for example, the login process), postMessage() can be used, to pass any resulting information from the iframe back to the parent page.
As a final step, once the message is received by the main page, the listeners can be unregistered, and the iframe finally be removed from the DOM.

Caution: The previous technique can help mitigating the potential UI change in a small part of the site, where the user can perform an action in a subdomain and return to the main origin (like in a login flow), but won't be an efficient technique to implement for entire paths, including many pages hosted in subdomains (like entire site sections).

Conclusion

Same-origin policy imposes many restrictions for sites built on top of multiple origins that want to achieve a coherent PWA experience. For that reason, to provide the best experience to users, we strongly recommend against dividing sites into different origins.

For existing sites that are already built in this way, it can be challenging to make multi-origin PWAs work correctly, but we have explored some potential workarounds. Each can come with tradeoffs, so use your judgement when deciding which approach to take on your website.

When evaluating a long-term strategy or site redesign, consider migrating to a single origin, unless there's an important reason to keep the multi-origin architecture.

With many thanks for their technical reviews and suggestions: PJ Mclachlan, Paul Covell, Dominick Ng, Alberto Medina, Pete LePage, Joe Medley, Cheney Tsai, Martin Schierle, and Andre Bandarra.

How Truebil made the web its channel of growth

2019-08-15T17:00:00-07:00

About

Founded in 2015, Truebil is an Indian online marketplace that sells 100% certified used cars. With over 1.4 million monthly active users, it's a one-stop solution that includes title transfer, insurance, loans, and service warranties. Prospective customers can see individual product pages with images and detailed inspection reports and get vehicle evaluations with the site's "Compare" and "Truescore" features. Truebil differentiates its product with rich features, including personalized recommendations based on machine learning, an add-to-favorites feature, a share-a-car feature, and more.

Challenge

Truebil is a lean startup with low-frequency, high-value transactions, so it was critical to choose the right platform to prioritize and invest in.

Truebil identified mobile as their target platform, and they chose the web for their first app, Truebil Lite, because of the web's easy discovery and low friction. Web technology provides lower development costs, less data and memory usage, and significantly lower customer acquisition costs than building a native app. And by building a progressive web app (PWA), Truebil could get all the perks of the web and the benefits of native.

Solution

An in-house team took four months to develop Truebil Lite using React, Django, and Preact (for production migration). They set clear guiding principles for the web app based on user goals. The experience had to be:

Fast on first load and subsequent navigations,
Reliable, independent of the user's network or device constraints, and
Engaging, especially for small mobile screens, so users would want to return to it.

Optimize for fast first load and navigations

Using Lighthouse to guide performance optimizations, the team adopted a performance-first culture while implementing new features. Truebil was able to significantly improve user experience by prioritizing the First Contentful Paint and Time to Interactive (TTI) metrics and optimizing for fast first loads, repeat visits, and smooth navigation. The team achieved those results by setting performance budgets and using a variety of techniques to achieve them.

Set performance budgets

With a performance-first mindset, the Truebil team chose to architect their experience as a single page app with server-side rendering for first load and client-side rendering for subsequent loads. Keeping web apps with client side rendering performant can be difficult, so Truebil set very strict performance budgets to ensure they don't compromise on speed, especially as they add more features.

The team set strict milestone-based budgets for TTI with the goal of keeping it below five seconds. To meet that goal they manually ensured no build would exceed a 250 KB JavaScript bundle size, kept a constant check on image sizes, and continually tracked the app's Lighthouse performance score.

Optimize JavaScript bundles

The team started with the basics by using the PRPL pattern to precache and optimize JavaScript payloads and by moving to HTTP/2 to serve critical JavaScript bundles.

To lazy-load non-critical resources, they used their framework-level lazy-loading components to load below-the-fold fragments.

To remove any JavaScript bundle bottlenecks, the team reduced payloads by code-splitting. They used component- and route-based chunking to to reduce main bundle size and improve their loading time by 44%, with TTI falling from 6 seconds to about 5 seconds and First Meaningful Paint (FMP) from 4.1 seconds to 3.6 seconds.

Impact of reducing chunk size.

Inline critical CSS

To further improve FMP, the team used Lighthouse to find opportunities for and validate the impact of performance optimizations. Lighthouse indicated that reducing render blocking CSS would have the biggest effect, so Truebil inlined all critical CSS and deferred non-critical CSS. This technique reduced FMP by around 2 seconds.

Impact of inlining critical CSS.

Avoid multiple, costly round trips to any origin

To mitigate overhead from DNS and TLS, Truebil used <link rel="preconnect"> and <link rel="dns-prefetch">. This approach causes the browser to complete the TLS handshake as soon as possible on page load and pre-resolve cross-origin domain names, allowing for a secure, snappy user experience.

Impact of adding <link rel=preconnect>.

Dynamically prefetch the next page

By analyzing their data, the team identified the most common user journeys that they could optimize for. In these cases, the app dynamically downloads the next page resource by using <link rel=prefetch> to ensure smooth navigation for users. While the team manually identifies the links to prefetch, they use webpack to bundle the JS for those links.

The effect of prefetching assets for common user journeys.

Optimize images and fonts

Images are a critical part of Truebil's product experience and credibility, with each product listing including up to 40 pictures. To ensure that images do not block page load, the team chose to serve all their resources from a CDN and use imagemagick for image optimization. They also Gzipped all compressible resources, including images, JavaScript, and CSS, to further cut down load time.

To avoid a flash of invisible text while keeping load time as low as possible, Truebil set up their CSS to use system fonts as a fallback until external fonts have loaded.

Further optimizations

When the app was ready, the team wanted to further reduce the vendor bundle size and JavaScript execution time, so they switched their React app to Preact in production. (Learn more in the React collection.) This approach helped them reduce the vendor bundle size from 82.3 KB to 51.2 KB.

Build in reliability

With a focus on the Indian market, a vast majority of Truebil's users access their product on patchy networks that sometimes fall into bandwidths as low as 2G. So building a resilient experience was critical not only to improving performance under constrained network conditions but also to delivering a product that their users could rely on—one that always works.

A hybrid caching strategy for reliable loading

The interactivity and rate of change for Truebil's content vary a lot. To ensure that all its content is both fresh and reliable, the Truebil team implemented API caching using a combination of network-first, cache-first, and fastest-first strategies.

For static pages, such as the subscriptions page, Truebil uses a cache-first strategy to go to their subscription API cache first, falling back to the network.

For pages with dynamic content that rarely changes, such as their product listing or details pages, Truebil uses a network-first strategy so that the browser first checks the network for content before falling back to the API cache if the network is unavailable.

And for dynamic pages that change often, such as the home, filter, search, and city pages, Truebil uses a fastest-first strategy to choose between network or cache based on whichever comes first. To ensure that content is fresh, the cache is updated whenever the network response differs from what's in the cache.

Service workers for a full offline experience

Even though a large part of Truebil's content is highly dynamic—cars can be added or bought at any time—the team wanted to ensure that their users had some content to engage with, even if they were going through patchy networks or were completely offline.

Using service workers, the team was able to cache both static data and the dynamic data that a user has already interacted with so that the user can view it offline. To make sure users know that content might change when they come back online, the team changed the UI to grayscale to indicate offline mode. Browsing product pages is a critical part of the Truebil user journey. Users who have visited the PWA at least once can browse listings and product pages that they have visited before but won't be able to see any updates to the listing or the product.

Truebil Lite in offline mode.

Improve engagement to keep users coming back

An engaging first experience

Since most of their users come from paid channels, Truebil needed to supplement their fast loading web app with a product that surfaces highly relevant recommendations to increase conversions. While the team uses a recommendation system based on sophisticated filtering for existing users, their system doesn't work for users who log in for the first time.

To avoid giving their first-time users a cold start, the team integrated a recommendation system using their digital marketing efforts. They add product details such as car model, price, and body type into an ad's destination URL through a UTM parameter, which is read by their recommendation system and reflected in the products surfaced. In case the sysme reads no such details in the URL, it falls back to popular cars, which is a combination of popular models, popular budgets, and cars that have been popular in the last few weeks or days.

An installable web app

Having built a fast, full-featured web app with a compelling user experience, Truebil wanted to ensure that their users would keep coming back. They realized that making the app installable would make repeat visits much more seamless.

The team implemented the Add to Home Screen feature to make their product a full progressive web app (PWA). This approach allowed users to add Truebil Lite to the home screen and launch it in full-screen mode. And since they had already implemented an offline mode, the team was able to add the new feature easily.

To ensure that their users weren't spammed and to increase the probability that users would install the app, the team recently updated their strategy for promoting PWA installation so that installation prompts appear when they'll actually be useful to different kinds of users. Truebil settled on a three-part strategy:

Show prompts when the user has completed an action or is idle.
Show contextual prompts to mature users.
Show a banner when the user has spent a set amount of time on the site.

Default banners on process completion and on high-traffic pages

The team decided to show an installation banner when a user completes a task or is on high-traffic pages but idle (that is, not taking an action, such as scrolling or filling out a form). This approach allowed them to avoid interrupting the user's activity.

Contextual prompts for mature users

For users who had interacted with the app for a while, the team used highly contextual custom messages to show the value of installing the app to the home screen:

Finally, the team built in a non-intrusive banner with a notification-like design that's triggered at specific events, such as opening a listing page or after the user has spent a set amount of time spent in the app:

Because of these improvements, Truebil's conversion and engagement rates have grown significantly with 26% longer user sessions and 61% more conversions, which is significant for their business given the high transaction value of each conversion.

For a startup with limited resources, choosing the right platform can be critical to the success of the business. Moving to a PWA focused on speed, resilience, and engagement, enabled us to increase our revenue-to-marketing spend by 80% thanks to increased conversions and the frictionless reach of the web.

—Rakesh Raman, Co-Founder and Chief of Product & Data Science at Truebil

44_%

Improvement in loading time

26_%

Longer user sessions

61_%

Increase in conversions

80_%

Increase in revenue-to-marketing spend

How to install the Thumbor image CDN

2019-08-13T17:00:00-07:00

Image CDNs make it easy to dynamically optimize the aesthetics and performance of your images. Unlike most image CDNs, Thumbor is open-source and can be used for free to resize, compress, and transform images. It's suitable for production use; Wikipedia and Square both use Thumbor.

This guide explains how to install Thumbor on your own server. Once installed, you'll be able to use Thumbor as an API for transforming your images.

Intro

You'll be installing Thumbor on a VM running Ubuntu 16.04. Ubuntu 16.04 is a very common image and these instructions are intended to work on any cloud provider. Creating a VM might sound like more work than installing Thumbor on your local machine, but the minutes that you take to create a VM will probably save you hours or days of frustration trying to get Thumbor to properly install on your local machine. Although easy to use, Thumbor is notoriously difficult to install but these instructions simplify the process. If dependencies download quickly, the installation can be completed in 5 to 10 minutes.

Prerequisites

This post assumes that you know how to create a Ubuntu 16.04 LTS VM on a cloud platform like Google Cloud, AWS, or Azure and how to use command line tools to set up the VM.

Install Thumbor Dependencies

Update and upgrade Ubuntu's already-installed packages:

sudo apt-get update -y && sudo apt-get upgrade -y

Install pip, the package manager for Python. Later you'll install Thumbor with pip.

sudo apt-get install -y python-pip

Install Thumbor's dependencies. Thumbor's documentation does not explicitly mention these dependencies, but Thumbor will not install successfully without them.

# ssl packages
sudo apt-get install -y libcurl4-openssl-dev libssl-dev

# computer vision packages
sudo apt-get install -y python-opencv libopencv-dev

# image format packages
sudo apt-get install -y libjpeg-dev libpng-dev libwebp-dev webp

Install Thumbor

Install Thumbor using pip.

sudo pip install thumbor

Note: Many Python developers use virtualenv to manage their packages. For the sake of simplicity, these instructions do not use virtualenv. If you are installing Thumbor in a standalone environment, virtualenv is not necessary. If you choose to use virtualenv, note that Thumbor requires Python 2.7 and will not work with newer versions of pip (e.g. these instructions use pip 8.1.1).

If you've successfully installed Thumbor, this should work:

thumbor --help

Run Thumbor

Run Thumbor. Debug logging is optional but can be helpful when you're getting started.

thumbor --log-level debug

Thumbor is now running.

Open Firewall Port

By default, Thumbor runs on port 8888. If your VM's IP address is 12.123.12.122, then you would access Thumbor from the web browser at http://12.123.12.123:8888/.../$IMAGE.

However, this probably won't work for you (yet) because cloud providers usually require that you explicitly open firewall ports before they will accept incoming traffic.

Update the firewall to expose port 8888. Here's more information on how to do this for: Google Cloud, AWS, and Azure. Note that for Google Cloud you need to first assign a static IP address to your VM and then allow an external HTTP connection.

Try It Out

Thumbor is now accessible and ready for use. Try it out by visiting the following URL:

http://YOUR_VIRTUAL_MACHINE:8888/unsafe/100x100/https://web.dev/install-thumbor/hero.jpg

Note that this URL uses HTTP. Thumbor uses HTTP by default but can be configured to use HTTPS.

You should see an image that is 100 pixels wide by 100 pixels tall. Thumbor has taken the image hero.jpg and size specified in the URL string and served the result. You can replace the image in the URL string (i.e https://web.dev/install-thumbor/hero.jpg) with any other image (e.g. https://your-site.com/cat.jpg) and Thumbor will resize that image too.

Appendix: Configuring Systemd

This step explains how to make sure that the Thumbor process keeps running, even after the VM has been restarted. This step is important for production sites, but optional if you're just playing around with Thumbor.

Systemd is the "system and service manager" for Linux operating systems. systemd makes it easy to configure when services (processes) run.

You will be configuring systemd to automatically start Thumbor on VM boot. If the VM is restarted, the Thumbor process will automatically restart as well. This is much more reliable than relying on user intervention to start Thumbor.

Navigate to the /lib/systemd/system directory. This directory contains the service files for systemd.

cd /lib/systemd/system

As superuser, create a thumbor.service file.

sudo touch thumbor.service

Using your favorite text editor (vim and nano come pre-installed on Ubuntu or you can install another editor), add the following configuration to thumbor.service. This configuration will run /usr/local/bin/thumbor (i.e. the Thumbor binary) once networking is available and will restart Thumbor on failure.

[Unit]

Description=Service for Thumbor image CDN

Documentation=https://thumbor.readthedocs.io/en/latest/

After=network.target

[Service]

ExecStart=/usr/local/bin/thumbor

Restart=on-failure

[Install]

WantedBy=multi-user.target

systemctl is the utility used to manage systemd. Use the start command to start Thumbor.

sudo systemctl start thumbor.service

Note: If Thumbor is currently running, you should stop it before attempting to start Thumbor using systemctl.

Next, "enable" Thumbor. This means that Thumbor will automatically start on boot.

sudo systemctl enable thumbor.service

Verify that you've successfully configured systemd by running the status command.

systemctl status thumbor.service

If you've successfully set up thumbor.service to use systemd, the status should show that it is enabled and active.

Third-party JavaScript performance

2019-08-12T17:00:00-07:00

Third-party JavaScript generally refers to scripts embedded in your website that are:

Not authored by you
Served from third-party servers

Sites use these scripts for various purposes, including:

Social sharing buttons
Video player embeds
Chat services
Advertising iframes
Analytics and metrics scripts
A/B testing scripts for experiments
Helper libraries (like date formatting, animation, and functional libraries)

Third-party scripts can provide powerful functionality, but that's not the whole story. They also affect privacy, security, and page behavior⁠—and they can be particularly problematic for performance.

Performance

Any significant amount of JavaScript can slow down performance. But because third-party JavaScript is usually outside your control, it can bring additional issues.

Network

Setting up connections takes time, and sending too many requests to multiple servers causes slowdowns. That time is even longer for secure connections, which may involve DNS lookups, redirects, and several round trips to the final server that handles the user's request.

Third-party scripts often add to network overhead with things such as:

Firing additional network requests
Pulling in unoptimized images and videos
Insufficient HTTP caching, which forces frequent fetching of network resources
Insufficient server compression of resources
Multiple instances of frameworks and libraries pulled in by different third-party embeds

Rendering

The way third-party JavaScript is loaded matters a lot. If it's done synchronously in the critical rendering path it delays parsing of the rest of the document.

Key Term: The critical rendering path includes all resources that the browser needs to display the first screen's worth of content.

If a third party has server issues and fails to deliver a resource, rendering is blocked until the request times out, which can be anywhere from 10 to 80 seconds. You can test and simulate this problem with WebPageTest Single-Point-of-Failure tests.

A/B testing scripts can also often delay rendering. Most of them block content display until they complete processing—which can be true even for asynchronous A/B testing scripts.

What to do about it

Using third-party JavaScript is often unavoidable, but there are things you can do to minimize adverse effects:

When choosing third-party resources, favor those that send the least amount of code while still giving you the functionality you need.
Use performance budgets for third-party content to keep their cost in check.
Don't use the same functionality from two different vendors. You probably don't need two tag managers or two analytics platforms.
Routinely audit and clean out redundant third-party scripts.

To learn how to audit third-party content and load it efficiently for better performance and user experience, check out the other posts in the Optimize your third-party resources section.

More capable form controls

2019-08-07T17:00:00-07:00

Many developers build custom form controls, either to provide controls that aren't built in to the browser, or to customize the look and feel beyond what's possible with the native form controls.

However, it can be difficult to replicate the features of built-in HTML form controls. Consider some of the features an <input> element gets automatically when you add it to a form:

The input is automatically added to the form's list of controls.
The input's value is automatically submitted with the form.
The input participates in form validation. You can style the input using the :valid and :invalid pseudoclasses.
The input is notified when the form is reset, when the form is reloaded, or when the browser tries to autofill form entries.

Custom form controls typically have few of these features. Developers can work around some of the limitations in JavaScript, like adding a hidden <input> to a form to participate in form submission. But other features just can't be replicated in JavaScript alone.

Two new web features make it easier to build custom form controls, and remove the limitations of current custom controls:

The formdata event lets an arbitrary JavaScript object participate in form submission, so you can add form data without using a hidden <input>.
The Form-associated custom elements API lets custom elements act more like built-in form controls.

These two features can be used to create new kinds of controls that work better with native web forms.

Building custom form controls is an advanced topic. This article assumes a certain knowledge of forms and form controls. When building a custom form control, there are many factors to consider, especially making sure that your controls are accessible to all users. To learn more about forms, go to the MDN guide on forms.

Event-based API

The formdata event is a low-level API that lets any JavaScript code participate in form submission. The mechanism works like this:

You add a formdata event listener to the form you want to interact with.
When a user clicks the submit button, the form fires a formdata event, which includes a FormData object that holds all of the data being submitted.
Each formdata listener gets a chance to add to or modify the data before the form is submitted.

Here's an example of sending a single value in a formdata event listener:

const form = document.querySelector('form');
// FormData event is sent on <form> submission, before transmission.
// The event has a formData property
form.addEventListener('formdata', ({formData}) => {
  // https://developer.mozilla.org/en-US/docs/Web/API/FormData
  formData.append('my-input', myInputValue);
});

Try this out using our example on Glitch. Be sure to run it on Chrome 77 or later to see the API in action.

Form-associated custom elements

You can use the event-based API with any kind of component, but it only allows you to interact with the submission process.

Native form controls participate in many parts of the form lifecycle besides submission. Form-associated custom elements aim to bridge the gap between custom widgets and native controls. Form-associated custom elements match many of the features of native form elements:

When you place a form-associated custom element inside a <form>, it's automatically associated with the form, like a native control.
The element can be labeled using a <label> element.
The element can set a value that's automatically submitted with the form.
The element can set a flag indicating whether or not it has valid input. If one of the form controls has invalid input, the form can't be submitted.
The element can provide callbacks for various parts of the form lifecycle—such as when the form is disabled or reset to its default state.
The element supports the standard CSS pseudoclasses for form controls, like :disabled and :invalid.

That's a lot of features! This article won't touch on all of them, but will describe the basics needed to integrate your custom element with a form.

This section assumes a basic familiarity with custom elements. For an introduction to custom elements, see Custom Elements v1: Reusable Web Components on Web Fundamentals.

Defining a form-associated custom element

To turn a custom element into a form-associated custom element requires a few extra steps:

Add a static formAssociated property to your custom element class. This tells the browser to treat the element like a form control.
Call the attachInternals() method on the element to get access to extra methods and properties for form controls, like setFormValue() and setValidity().
Add the common properties and methods supported by form controls, like name, value, and validity.

Here's how those items fit into a basic custom element definition:

// Form-associated custom elements must be autonomous custom elements--
// meaning they must extend HTMLElement, not one of its subclasses.
class MyCounter extends HTMLElement {

  // Identify the element as a form-associated custom element
  static formAssociated = true;

  constructor() {
    super();
    // Get access to the internal form control APIs
    this._internals = this.attachInternals();
    // internal value for this control
    this._value = 0;
  }

  // Form controls usually expose a "value" property
  get value() { return this._value; }
  set value(v) { this._value = v; }

  // The following properties and methods aren't strictly required, 
  // but native form controls provide them. Providing them helps
  // ensure consistency with native controls.
  get form() { return this._internals.form; }
  get name() { return this.getAttribute('name'); }
  get type() { return this.localName; }
  get validity() {return this.internals_.validity; }
  get validationMessage() {return this.internals_.validationMessage; }
  get willValidate() {return this.internals_.willValidate; }

  checkValidity() { return this.internals_.checkValidity(); }
  reportValidity() {return this.internals_.reportValidity(); }

  … 
}
customElements.define('my-counter', MyCounter);

Once registered, you can use this element wherever you'd use a native form control:

<form> 
  <label>Number of bunnies: <my-counter></my-counter></label>
  <button type="submit">Submit</button>
</form>

Setting a value

The attachInternals() method returns an ElementInternals object that provides access to form control APIs. The most basic of these is the setFormValue() method, which sets the current value of the control.

The setFormValue() method can take one of three types of values:

A string value.
A File object.
A FormData object. You can use a FormData object to pass multiple values (for example, a credit card input control might pass a card number, expiration date, and verification code).

To set a simple value:

this._internals.setFormValue(this._value);

To set multiple values, you can do something like this:

// Use the control's name as the base name for submitted data
const n = this.getAttribute('name');
const entries = new FormData();
entries.append(n + '-first-name', this.firstName_);
entries.append(n + '-last-name', this.lastName_);
this.internals_.setFormValue(entries);

The setFormValue() method takes a second, optional state parameter, used to store the internal state of the control. For more information, see Restoring form state.

Input validation

Your control can also participate in form validation by calling the setValidity() method on the internals object.

// Assume this is called whenever the internal value is updated
onUpdateValue() {
  if (!this.matches(':disabled') && this.hasAttribute('required') &&
      this._value < 0) {
    this._internals.setValidity({customError: true}, 'Value cannot be negative.');
  } 
  else {
    this._internals.setValidity({});
  }
  this.internals.setFormValue(this._value);
}

You can style a form-associated custom element with the :valid and :invalid pseudoclasses, just like a built-in form control.

Although you can set a validation message, Chrome currently fails to display the validation message for form-associated custom elements.

Lifecycle callbacks

A form-associated custom element API includes a set of extra lifecycle callbacks to tie in to the form lifecycle. The callbacks are optional: only implement a callback if your element needs to do something at that point in the lifecycle.

`void formAssociatedCallback(form)`

Called when the browser associates the element with a form element, or disassociates the element from a form element.

`void formDisabledCallback(disabled)`

Called after the disabled state of the element changes, either because the disabled attribute of this element was added or removed; or because the disabled state changed on a <fieldset> that's an ancestor of this element. The disabled parameter represents the new disabled state of the element. The element may, for example, disable elements in its shadow DOM when it is disabled.

`void formResetCallback()`

Called after the form is reset. The element should reset itself to some kind of default state. For native inputs, this usually involves setting the value property to match the value attribute set in markup (or in the case of a checkbox, setting the checked property to match the checked attribute.

`void formStateRestoreCallback(state, mode)`

Called in one of two circumstances:

When the browser restores the state of the element (for example, after a navigation, or when the browser restarts). The mode argument is "restore" in this case.
When the browser's input-assist features such as form autofilling sets a value. The mode argument is "autocomplete" in this case.

The type of the first argument depends on how the setFormValue() method was called. For more details, see Restoring form state.

Restoring form state

Under some circumstances—like when navigating back to a page, or restarting the browser, the browser may try to restore the form to the state the user left it in.

For a form-associated custom element, the restored state comes from the value(s) you pass to the setFormValue() method. You can call the method with a single value parameter, as shown in the earlier examples, or with two parameters:

this._internals.setFormValue(value, state);

The value represents the submittable value of the control. The optional state parameter is an internal representation of the state of the control, which can include data that doesn't get sent to the server. The state parameter takes the same types as the value parameter—it can be a string, File, or FormData object.

The state parameter is useful when you can't restore a control's state based on the value alone. For example, suppose you create a color picker with multiple modes: a palette or an RGB color wheel. The submittable value would be the selected color in a canonical form, like "#7fff00". But to restore the control to a specific state, you'd also need to know which mode it was in, so the state might look like "palette/#7fff00".

this._internals.setFormValue(this._value, 
    this._mode + '/' + this._value);

Your code would need to restore its state based on the stored state value.

formStateRestoreCallback(state, mode) {
  if (mode == 'restore') {
    // expects a state parameter in the form 'controlMode/value'
    [controlMode, value] = state.split('/');
    this._mode = controlMode;
    this._value = value;
  }
  // Chrome currently doesn't handle autofill for form-associated 
  // custom elements. In the autofill case, you might need to handle
  // a raw value.
}

In the case of a simpler control (for example a number input), the value is probably sufficient to restore the control to its previous state. If you omit state when calling setFormValue(), then the value is passed to formStateRestoreCallback().

formStateRestoreCallback(state, mode) {
  // Simple case, restore the saved value
  this._value = state;
}

A working example

The following example puts together many of the features of form-associated custom elements. Be sure to run it on Chrome 77 or later to see the API in action.

Feature detection

You can use feature detection to determine whether the formdata event and form-associated custom elements are available. There are currently no polyfills released for either feature. In both cases, you can fall back to adding a hidden form element to propagate the control's value to the form. Many of the more advanced features of form-associated custom elements will likely be difficult or impossible to polyfill.

if ('FormDataEvent' in window) {
  // formdata event is supported
}

if ('ElementInternals' in window && 
    'setFormData' in window.ElementInternals) {
  // Form-associated custom elements are supported
}

Conclusion

The formdata event and form-associated custom elements provide new tools for creating custom form controls.

The formdata event doesn't give you any new capabilities, but it gives you an interface for adding your form data to the submit process, without having to create a hidden <input> element.

The form-associated custom elements API provides a new set of capabilities for making custom form controls that work like built-in form controls.

Hero image by Oudom Pravat on Unsplash.

Largest Contentful Paint

2019-08-07T17:00:00-07:00

Historically, it's been a challenge for web developers to measure how quickly the main content of a web page loads and is visible to users.

Older metrics like load or DOMContentLoaded are not good because they don't necessarily correspond to what the user sees on their screen. And newer, user-centric performance metrics like First Paint (FP) and First Contentful Paint (FCP) only capture the very beginning of the loading experience. If a page shows a splash screen or displays a loading indicator, this moment is not very relevant to the user.

In the past we've recommended performance metrics like First Meaningful Paint (FMP) and Speed Index (SI) (both available in Lighthouse) to help capture more of the loading experience after the initial paint, but these metrics are complex, hard to explain, and often wrong—meaning they still do not identify when the main content of the page has loaded.

Sometimes simpler is better. Based on discussions in the W3C Web Performance Working Group and research done at Google, we've found that a more accurate way to measure when the main content of a page is loaded is to look at when the largest element was rendered.

Largest Contentful Paint defined

The Largest Contentful Paint (LCP) API, available in Chrome 77, reports the render time of the largest content element visible in the viewport.

What elements are considered?

As currently specified, the types of elements considered for Largest Contentful Paint are:

<img> elements
<image> elements inside an <svg> element
<video> elements (the poster image is used)
An element with a background image loaded via the url() function (as opposed to a CSS gradient)
Block-level elements containing text nodes or other inline-level text elements children.

Note, restricting the elements to this limited set was intentional in order to keep things simple in the beginning. Additional elements (e.g. <svg>, <video>) may be added in the future as more research is conducted.

How is an element's size determined?

The size of the element reported for Largest Contentful Paint is typically the size that's visible to the user within the viewport. If the element extends outside of the viewport, or if any of the element is clipped or has non-visible overflow, those portions do not count toward the element's size.

For image elements that have been resized from their intrinsic size, the size that gets reported is either the visible size or the intrinsic size, whichever is smaller. For example, images that are shrunk down to a much smaller than their intrinsic size will only report the size they're displayed at, whereas images that are stretched or expanded to a larger size will only report their intrinsic sizes.

For text elements, only the size of their text nodes is considered (the smallest rectangle that encompases all text nodes).

For all elements, any margin, padding, or border applied via CSS is not considered.

Determining which text nodes belong to which elements can sometimes be tricky, especially for elements whose children includes inline elements and plain text nodes but also block-level elements. The key point is that every text node belongs to (and only to) its closest block-level ancestor element. In spec terms: each text node belongs to the element that generates its containing block.

When is largest contentful paint reported?

Web pages often load in stages, and as a result, it's possible that the largest element on the page might change.

To handle this potential for change, the browser dispatches a PerformanceEntry of type largest-contentful-paint identifying the largest contentful element as soon as the browser has painted the first frame. But then, after rendering subsequent frames, it will dispatch another PerformanceEntry any time the largest contentful element changes.

It's important to note that an element can only be considered the largest contentful element once it has rendered and is visible to the user. Images that have not yet loaded are not considered "rendered". Neither are text nodes using web fonts during the font block period. In such cases a smaller element may be reported as the largest contentful element, but as soon as the larger element finishes rendering, it'll be reported via another PerformanceEntry object.

In addition to late-loading images and fonts, a page may add new elements to the DOM as new content becomes available. If any of these new elements is larger than the previous largest contentful element, a new PerformanceEntry will also be reported.

If a page removes an element from the DOM, that element will no longer be considered. Similarly, if an element's associated image resource changes (e.g. changing img.src via JavaScript), then that element will stop be considered until the new image loads.

The browser will stop reporting new entries as soon as the user interacts with the page (via a tap, scroll, or keypress), as user interaction often changes what's visible to the user (which is especially true with scrolling).

For analysis purposes, you should only report the most recently dispatched PerformanceEntry to your analytics service.

Caution: Since users can open pages in a background tab, it's possible that the largest contentful paint will not happen until the user focuses the tab, which can be much later than when they first loaded it.

Load time vs. render time

For security reasons, the render timestamp of images is not exposed for cross-origin images that lack the Timing-Allow-Origin header. Instead, only their load time is exposed (since this is already exposed via many other web APIs).

The usage example below shows how to handle elements whose render time is not available. But, when possible, it's always recommended to set the Timing-Allow-Origin header, so your metrics will be more accurate.

How are element layout and size changes handled?

To keep the performance overhead of calculating and dispatching new performance entries low, changes to an element's size or position do not generate new LCP candidates. Only the element's initial size and position in the viewport is considered.

This means images that are initially rendered off-screen and then transition on-screen may not be reported. It also means elements initially rendered in the viewport that then get pushed down, out of view will still report their initial, in-viewport size.

However, (as mentioned above) an element will be removed from consideration if it's removed from the DOM or if its associated image resource changes.

Examples

Here are some examples of when the Largest Contentful Paint occurs on a few popular websites:

In both of the timelines above, the largest element changes as content loads. In the first example, new content is added to the DOM and that changes what element is the largest. In the second example, the layout changes and content that was previously the largest is removed from the viewport.

While it's often the case that late-loading content is larger than content already on the page, that's not necessarily the case. The next two examples show the Largest Contentful Paint occurring before the page fully loads.

In the first example, the Instagram logo is loaded relatively early and it remains the largest element even as other content is progressively shown. In the Google search results page example, the largest element is a paragraph of text that is displayed before any of the images or logo finish loading. Since all the individual images are smaller than this paragraph, it remains the largest element throughout the load process.

In the first frame of the Instagram timeline, you may notice the camera logo does not have a green box around it. That's because it's an <svg> element, and <svg> elements are not currently considered LCP candidates. The first LCP candidate is the text in the second frame.

How to measure Largest Contentful Paint in JavaScript

The following code block shows how to measure LCP in JavaScript and report it to an analytics service when the user leaves the tab:

// Create a variable to hold the latest LCP value (since it can change).
let lcp;

// Create the PerformanceObserver instance.
const po = new PerformanceObserver((entryList) => {
  const entries = entryList.getEntries();
  const lastEntry = entries[entries.length - 1];

  // Update `lcp` to the latest value, using `renderTime` if it's available,
  // otherwise using `loadTime`. (Note: `renderTime` may not be available if
  // the element is an image and it's loaded cross-origin without the
  // `Timing-Allow-Origin` header.)
  lcp = lastEntry.renderTime || lastEntry.loadTime;
});

// Observe entries of type `largest-contentful-paint`, including buffered
// entries, i.e. entries that occurred before calling `observe()`.
po.observe({type: 'largest-contentful-paint', buffered: true});

// Send the latest LCP value to your analytics server once the user
// leaves the tab.
addEventListener('visibilitychange', function fn() {
  if (lcp && document.visibilityState === 'hidden') {
    sendToAnalytics({'largest-contentful-paint': lcp});
    removeEventListener('visibilitychange', fn, true);
  }
}, true);

Note, this example waits until the user leaves the tab to report LCP as a way of ensuring it only reports the latest entry. If you would prefer to report every entry (to avoid potentially missing sessions), make sure to configure your analytics to only include the last entry received per page load.

What if the largest element isn't the most important?

In some cases the most important element (or elements) on the page is not the same as the largest element, and developers may be more interested in measuring the render times of these other elements instead. This is possible using the Element Timing API.

The Largest Contentful Paint API is actually built on top of the Element Timing API and adds automatic reporting of the largest contentful element, but you can report on additional elements by explicitly adding the elementtiming attribute to them, and registering a PerformanceObserver to observe the element entry type.

Here's the example used in the specification:

<img... elementtiming='foobar'/>
<p elementtiming='important-paragraph'>This is text I care about.</p>
...
<script>
const observer = new PerformanceObserver((list) => {
  let perfEntries = list.getEntries();
  // Process the entries by iterating over them.
});
observer.observe({type: 'element', buffered: true});
</script>

Important: the types of elements considered for Largest Contentful Paint are the same as those observable via the Element Timing API. If you add the elementtiming attribute to an element that isn't one of those types, it will be ignored.

How to improve Largest Contentful Paint on your site

LCP is primarily affected by three factors:

Server response time
CSS blocking time
Asset/subresource load time

Also, if your site is client-rendered, and your largest contentful elements are added to the DOM via JavaScript, then your script's parse, compile, and execution time can also be a factor in LCP.

Here is some guidance you can reference to optimize all of these factors:

Apply instant loading with the PRPL pattern
Optimizing the Critical Rendering Path
Optimize your CSS
Optimize your Images
Optimize web Fonts
Optimize you JavaScript (for client-rendered sites)

Native lazy-loading for the web

2019-08-05T17:00:00-07:00

Support for natively lazy-loading images and iframes is coming to the web! This video shows a demo of the feature:

Starting with Chrome 76, you'll be able to use the new loading attribute to lazy-load resources without the need to write custom lazy-loading code or use a separate JavaScript library. Let's dive into the details.

Why native lazy-loading?

According to HTTPArchive, images are the most requested asset type for most websites and usually take up more bandwidth than any other resource. At the 90th percentile, sites send about 4.7 MB of images on desktop and mobile. That's a lot of cat pictures.

Embedded iframes also use a lot of data and can harm page performance. Only loading non-critical, below-the-fold images and iframes when the user is likely to see them improves page load times, minimizes user bandwidth, and reduces memory usage.

Currently, there are two ways to defer the loading of off-screen images and iframes:

Using the Intersection Observer API
Using scroll, resize, or orientationchange event handlers

Either option can let developers include lazy-loading functionality, and many developers have built third-party libraries to provide abstractions that are even easier to use. With lazy-loading supported directly by the browser, however, there's no need for an external library. Native lazy loading also ensures that deferred loading of images and iframes still works even if JavaScript is disabled on the client.

The `loading` attribute

Today, Chrome already loads images at different priorities depending on where they're located with respect to the device viewport. Images below the viewport are loaded with a lower priority, but they're still fetched as soon as possible.

In Chrome 76, you can use the loading attribute to completely defer the loading of offscreen images and iframes that can be reached by scrolling:

<img src="image.png" loading="lazy" alt="…" width="200" height="200">
<iframe src="https://example.com" loading="lazy"></iframe>

Here are the supported values for the loading attribute:

auto: Default lazy-loading behavior of the browser, which is the same as not including the attribute.
lazy: Defer loading of the resource until it reaches a calculated distance from the viewport.
eager: Load the resource immediately, regardless of where it's located on the page.

The feature will continue to be updated until it's launched in a stable release (Chrome 76 at the earliest). But you can try it out by enabling the following flags in Chrome:

chrome://flags/#enable-lazy-image-loading
chrome://flags/#enable-lazy-frame-loading

Load-in distance threshold

All images and iframes that are above the fold—that is, immediately viewable without scrolling—load normally. Those that are far below the device viewport are only fetched when the user scrolls near them.

The distance threshold is not fixed and varies depending on several factors:

The type of resource being fetched (image or iframe)
Whether Lite mode is enabled on Chrome for Android
The effective connection type

You can find the default values for the different effective connection types in the Chromium source. These numbers, and even the approach of fetching only when a certain distance from the viewport is reached, may change in the near future as the Chrome team improves heuristics to determine when to begin loading.

In Chrome 77, you can experiment with these different thresholds by throttling the network in DevTools. In the meantime, you will need to override the effective connection type of the browser using the chrome://flags/#force-effective-connection-type flag.

Image loading

To prevent the surrounding content from reflowing when a lazy-loaded image is downloaded, make sure to add height and width attributes to the <img> element or specify their values directly in an inline style:

<img src="..." loading="lazy" width="200" height="200">
<img src="..." loading="lazy" style="height:200px; width:200px;">

Images will still lazy-load if dimensions are not included, but specifying them decreases the chance of browser reflow.

Support for the intrinsicsize attribute is also being worked on, so images will lazy-load correctly if intrinsicsize is specified along with one other dimension (width or height).

<img src="…" alt="…" loading="lazy" intrinsicsize="250x200" width="450">
<!-- lazy-loaded -->

Take a look at this demo to see how the loading attribute works with 100 pictures.

iframe loading

The loading attribute affects iframes differently than images, depending on whether the iframe is hidden. (Hidden iframes are often used for analytics or communication purposes.) Chrome uses the following criteria to determine whether an iframe is hidden:

The iframe's width and height are 4 px or smaller.
display: none or visibility: hidden is applied.
The iframe is placed off-screen using negative X or Y positioning.

If an iframe meets any of these conditions, Chrome considers it hidden and won't lazy-load it in most cases. Iframes that aren't hidden will only load when they're within the load-in distance threshold. A placeholder shows for lazy-loaded iframes that are still being fetched.

FAQ

Are there plans to expand this feature?

There are plans to change the default lazy-loading behavior of the browser to automatically lazy-load any images or iframes that are well suited to being deferred if Lite mode is enabled on Chrome for Android.

Can I change how close an image or iframe needs to be before a load is triggered?

These values are hardcoded and can't be changed through the API. However, they may change in the future as the Chrome team experiments with different threshold distances and variables.

Can CSS background images take advantage of the `loading` attribute?

No, it can currently only be used with <img> tags.

How does the `loading` attribute work with images that are in the viewport but not immediately visible (for example, behind a carousel)?

Only images that are below the device viewport by the calculated distance load lazily. All images above the viewport, regardless of whether they're immediately visible, load normally.

What if I'm already using a third-party library or a script to lazy-load images or iframes?

The loading attribute should not affect code that currently lazy-loads your assets in any way, but there are a few important things to consider:

If your custom lazy-loader attempts to load images or frames sooner than when Chrome loads them normally—that is, at a distance greater than the load-in distance threshold— they are still deferred and load based on normal browser behavior.
If your custom lazy-loader uses a shorter distance to determine when to load a particular image or iframe than the browser, then the behavior would conform to your custom settings.

One of the important reasons to continue to use a third-party library along with loading="lazy" is to provide a polyfill for browsers that do not yet support the attribute.

Do other browsers support native lazy-loading?

The loading attribute can be treated as a progressive enhancement. Browsers that support it can lazy-load images and iframes. Those that don't yet can load images just like they would today. In terms of cross-browser support, loading should be supported in Chrome 76 and any Chromium 76-based browsers. There is also an open implementation bug for Firefox.

A similar API was proposed and used in IE and Edge but was focused on lowering the download priorities of resources instead of deferring them entirely. It was discontinued in favour of resource hints.

How do I handle browsers that don't yet support native lazy-loading?

Create a polyfill or use a third-party library to lazy-load images on your site. The loading property can be used to detect if the feature is supported in the browser:

if ('loading' in HTMLImageElement.prototype) {
  // supported in browser
} else {
  // fetch polyfill/third-party library
}

For example, lazysizes is a popular JavaScript lazy-loading library. You can detect support for the loading attribute to load lazysizes as a fallback library only when loading isn't supported. This works as follows:

Replace <img src> with <img data-src> to avoid an eager load in unsupported browsers. If the loading attribute is supported, swap data-src for src.
If loading is not supported, load a fallback (lazysizes) and initiate it. As per lazysizes docs, you use the lazyload class as a way to indicate to lazysizes which images to lazy-load.

<!-- Let's load this in-viewport image normally -->
<img src="hero.jpg" alt="…">

<!-- Let's lazy-load the rest of these images -->
<img data-src="unicorn.jpg" alt="…" loading="lazy" class="lazyload">
<img data-src="cats.jpg" alt="…" loading="lazy" class="lazyload">
<img data-src="dogs.jpg" alt="…" loading="lazy" class="lazyload">

<script>
  if ('loading' in HTMLImageElement.prototype) {
    const images = document.querySelectorAll('img[loading="lazy"]');
    images.forEach(img => {
      img.src = img.dataset.src;
    });
  } else {
    // Dynamically import the LazySizes library
    const script = document.createElement('script');
    script.src =
      'https://cdnjs.cloudflare.com/ajax/libs/lazysizes/4.1.8/lazysizes.min.js';
    document.body.appendChild(script);
  }
</script>

Here's a demo of this pattern. Try it out in a browser like Firefox or Safari to see the fallback in action.

The lazysizes library also provides a native loading plugin that uses native lazy-loading when available but falls back to the library's custom functionality when needed.

How does native lazy-loading affect advertisements on a web page?

All ads displayed to the user in the form of an image or iframe lazy-load just like any other image or iframe.

How are images handled when a web page is printed?

Although the functionality isn't in Chrome 76, there's an open issue to ensure that all images and iframes are immediately loaded if a page is printed.

Conclusion

Baking in native support for lazy-loading images and iframes can make it significantly easier for you to improve the performance of your web pages.

Are you noticing any unusual behavior with this feature enabled in Chrome? File a bug!

Establish network connections early to improve perceived page speed

2019-07-29T17:00:00-07:00

Before the browser can request a resource from a server, it must establish a connection. Establishing a secure connection involves three steps:

Look up the domain name and resolve it to an IP address.
Set up a connection to the server.
Encrypt the connection for security.

In each of these steps the browser sends a piece of data to a server, and the server sends back a response. That journey, from origin to destination and back, is called a round trip.

Depending on network conditions, a single round trip might take a significant amount of time. The connection setup process might involve up to three round trips—and more in unoptimized cases.

Taking care of all that ahead of time makes applications feel much faster. This post explains how to achieve that with two resource hints: <link rel=preconnect> and <link rel=dns-prefetch>.

Establish early connections with `rel=preconnect`

Modern browsers try their best to anticipate what connections a page will need, but they cannot reliably predict them all. The good news is that you can give them a (resource 😉) hint.

Adding rel=preconnect to a <link> informs the browser that your page intends to establish a connection to another domain, and that you'd like the process to start as soon as possible. Resources will load more quickly because the setup process has already been completed by the time the browser requests them.

Resource hints get their name because they are not mandatory instructions. They provide the information about what you'd like to happen, but it's ultimately up to the browser to decide whether to execute them. Setting up and keeping a connection open is a lot of work, so the browser might choose to ignore resource hints or execute them partially depending on the situation.

Informing the browser of your intention is as simple as adding a <link> tag to your page:

<link rel="preconnect" href="https://example.com">

You can speed up the load time by 100–500 ms by establishing early connections to important third-party origins. These numbers might seem small, but they make a difference in how users perceive web page performance.

chrome.com improved Time To Interactive by almost 1 s by pre-connecting to important origins.

Use-cases for `rel=preconnect`

Knowing where from, but not what you're fetching

Due to versioned dependencies, you sometimes end up in a situation where you know you'll be requesting a resource from a particular CDN, but not the exact path for it.

An example of a versioned URL.

The other common case is loading images from an image CDN, where the exact path for an image depends on media queries or runtime feature checks on the user's browser.

An example of an image CDN URL.

In these situations, if the resource you'll be fetching is important, you want to save as much time as possible by pre-connecting to the server. The browser won't download the file until your page requests it, but at least it can handle the connection aspects ahead of time, saving the user from waiting for several round trips.

Streaming media

Another example where you may want to save some time in the connection phase, but not necessarily start retrieving content right away, is when streaming media from a different origin.

Depending on how your page handles the streamed content, you may want to wait until your scripts have loaded and are ready to process the stream. Pre-connecting helps you cut the waiting time to a single round trip once you're ready to start fetching.

How to implement `rel=preconnect`

One way of initiating a preconnect is adding a <link> tag to the <head> of the document.

<head>
    <link rel="preconnect" href="https://example.com">
</head>

Preconnecting is only effective for domains other than the origin domain, so you shouldn't use it for your site.

Caution: Only preconnect to critical domains you will use soon because the browser closes any connection that isn't used within 10 seconds. Unnecessary preconnecting can delay other important resources, so limit the number of preconnected domains and test the impact preconnecting makes.

You can also initiate a preconnect via the Link HTTP header:

Link: <https://example.com/>; rel=preconnect

A benefit of specifying a preconnect hint in the HTTP header is that it doesn't rely on markup being parsed, and it can be triggered by requests for stylesheets, scripts, and more. For example, Google Fonts sends a Link header in the stylesheet response to preconnect to the domain that hosts the font files.

Some types of resources, such as fonts, are loaded in anonymous mode. For those you must set the crossorigin attribute with the preconnect hint:

<link rel="preconnect" href="https://example.com/ComicSans" crossorigin>

If you omit the crossorigin attribute, the browser only performs the DNS lookup.

Resolve domain name early with `rel=dns-prefetch`

You remember sites by their names, but servers remember them by IP addresses. This is why the domain name system (DNS) exists. The browser uses DNS to convert the site name to an IP address. This process — domain name resolution— is the first step in establishing a connection.

If a page needs to make connections to many third-party domains, preconnecting all of them is counterproductive. The preconnect hint is best used for only the most critical connections. For all the rest, use <link rel=dns-prefetch> to save time on the first step, the DNS lookup, which usually takes around 20–120 ms.

DNS resolution is initiated similarly to preconnect: by adding a <link> tag to the <head> of the document.

<link rel="dns-prefetch" href="http://example.com">

Browser support for dns-prefetch is slightly different from preconnect support, so dns-prefetch can serve as a fallback for browsers that don't support preconnect.

<link rel="preconnect" href="http://example.com">
<link rel="dns-prefetch" href="http://example.com">

Recommended

— To safely implement the fallback technique use separate link tags.

<link rel="preconnect dns-prefetch" href="http://example.com">

Not recommended

— Implementing dns-prefetch fallback in the same <link> tag causes a bug in Safari where preconnect gets cancelled.

Conclusion

These two resource hints are helpful for improving page speed when you know you'll download something from a third-party domain soon, but you don't know the exact URL for the resource. Examples include CDNs that distribute JavaScript libraries, images or fonts. Be mindful of constraints, use preconnect only for the most important resources, rely on dns-prefetch for the rest, and always measure the impact in the real-world.

Create OS-style backgrounds with backdrop-filter

2019-07-25T17:00:00-07:00

Translucence, blurring, and other effects are useful ways of creating depth while keeping the context of the background content. They support a host of use cases such as frosted glass, video overlays, translucent navigation headers, inappropriate image censoring, image loading, and so on. You may recognize these effects from two popular operating systems: Windows 10 and iOS.

An example of a frosted glass effect. Source.

Historically, these techniques were difficult to implement on the web, requiring less than perfect hacks or workarounds. In recent years both Safari and Edge have provided these capabilities through the background-filter (and alternatively, the -webkit-backdrop-filter) property, which dynamically blends foreground and background colors based on filter functions. Now Chrome supports background-filter, starting in version 76.

A demonstration of the filter functions for backdrop-filter. Try the example on CodePen.

Basics

The backdrop-filter property applies one or more filters to an element, changing the appearance of anything behind the element.
The overlaying element must be at least partially transparent.
The overlaying element will get a new stacking context.

Caution: backdrop-filter may harm performance. Test it before deploying.

CSS backdrop-filter applies one or more effects to an element that is translucent or transparent. To understand that, consider the images below.

No foreground transparency

—

.frosty-glass-pane {
    backdrop-filter: blur(2px);
  }

Foreground transparency

—

.frosty-glass-pane {
    opacity: .9;
    backdrop-filter: blur(2px);
  }

The image on the left shows how overlapping elements would be rendered if backdrop-filter were not used or supported. The image on the right applies a blurring effect using backdrop-filter. Notice that it uses opacity in addition to backdrop-filter. Without opacity, there would be nothing to apply blurring to. It almost goes without saying that if opacity is set to 1 (fully opaque) there will be no effect on the background.

The backdrop-filter property is like CSS filters in that all your favorite filter functions are supported: blur(), brightness(), contrast(), opacity(), drop-shadow(), and so on. It also supports the url() function if you want to use an external image as the filter, as well as the keywords none, inherit, initial, and unset. There are explanations for all of this on MDN, including descriptions of syntax, filters, and values.

When backdrop-filter is set to anything other than none, the browser creates a new stacking context. A containing block may also be created, but only if the element has absolute and fixed position descendants.

You can combine filters for rich and clever effects, or use just one filter for more subtle or precise effects. You can even combine them with SVG filters.

Feature detection and fallback

As with many features of the modern web, you'll want to know whether the user's browser supports backdrop-filter before using it. Do this with @supports(). For performance reasons, fall back to an image instead of a polyfill when backdrop-image isn't supported. The example below shows this.

@supports (backdrop-filter: none) {
	.background {
		backdrop-filter: blur(10px);
	}
}

@supports not (backdrop-filter: none) {
  .background {
    background-image: blurred-hero.png;
  }
}

Examples

Design techniques and styles previously reserved for native operating systems are now performant and achievable with a single CSS declaration. Let's look at some examples.

Single filter

In the following example, the frosted effect is achieved by combining color and blur. The blur is supplied by backdrop-filter, while the color comes from the element's semi-transparent background color.

.blur-behind-me {
  background-color: rgba(255, 255, 255, 0.3);
  backdrop-filter: blur(.5rem);
}

Try this example for yourself in CodePen.

Multiple filters

Sometimes you'll need multiple filters to achieve the desired effect. To do this, provide a list of filters separated by a space. For example:

.brighten-saturate-and-blur-behind-me {
  backdrop-filter: brightness(150%) saturate(150%) blur(1rem);
}

In the following example, each of the four panes has a different combination of backdrop filters while the same set of shapes are animated behind them.

Try this example for yourself in CodePen.

Overlays

This example shows how to blur a semi-transparent background to make text readable while stylistically blending with a page's background.

.modal {
  backdrop-filter: blur(10px);
  background-color: rgba(255, 255, 255, 0.5);
}

Try this example for yourself.

Text contrast on dynamic backgrounds

As stated earlier, backdrop-filter allows performant effects that would be difficult or impossible on the web. An example of this is changing a background in respone to an animation. In this example, backdrop-filter maintains the high contrast between the text and its background in spite of what's going on behind the text. It starts with the default background color darkslategray and uses backdrop-filter to invert the colors after the transformation.

.container::before {
  z-index: 1;
  background-color: darkslategray;
  filter: invert(1);
}

.container::after {
	backdrop-filter: invert(1);
  z-index: 3;
}

Try this example from Chen Hui Jing in Codrops.

Conclusion

More than 560 of you have upvoted the Chromium bug over the past few years, clearly marking this as a long awaited CSS feature. Chrome's release of backdrop-filter in version 76 brings the web a step closer to truly native-like UI presentation.

Additional resources

Keeping things fresh with stale-while-revalidate

2019-07-17T17:00:00-07:00

What shipped?

stale-while-revalidate helps developers balance between immediacy—loading cached content right away—and freshness—ensuring updates to the cached content are used in the future. If you maintain a third-party web service or library that updates on a regular schedule, or your first-party assets tend to have short lifetimes, then stale-while-revalidate may be a useful addition to your existing caching policies.

Support for setting stale-while-revalidate alongside max-age in your Cache-Control response header is available in Chrome 75 and Firefox 68.

Browsers that don't support stale-while-revalidate will silently ignore that configuration value, and use max-age, as I'll explain shortly…

What's it mean?

Let's break down stale-while-revalidate into two parts: the idea that a cached response might be stale, and the process of revalidation.

First, how does the browser know whether a cached response is "stale"? A Cache-Control response header that contains stale-while-revalidate should also contain max-age, and the number of seconds specified via max-age is what determines staleness. Any cached response newer than max-age is considered fresh, and older cached responses are stale.

If the locally cached response is still fresh, then it can be used as-is to fulfill a browser's request. From the perspective of stale-while-revalidate, there's nothing to do in this scenario.

But if the cached response is stale, then another age-based check is performed: is the age of the cached response within the window of time covered by the stale-while-revalidate setting?

If the age of a stale response falls into this window, then it will be used to fulfill the browser's request. At the same time, a "revalidation" request will be made against the network in a way that doesn't delay the use of the cached response. The returned response might contain the same information as the previously cached response, or it might be different. Either way, the network response is stored locally, replacing whatever was previously cache, and resetting the "freshness" timer used during any future max-age comparisons.

However, if the stale cached response is old enough that it falls outside the stale-while-revalidate window of time, then it will not fulfill the browser's request. The browser will instead retrieve a response from the network, and use that for both fulfilling the initial request and also populating the local cache with a fresh response.

Live Example

Below is a simple example of an HTTP API for returning the current time—more specifically, the current number of minutes past the hour.

In this scenario, the web server uses this Cache-Control header in its HTTP response:

Cache-Control: max-age=1, stale-while-revalidate=59

This setting means that, if a request for the time is repeated within the next 1 second, the previously cached value will still be fresh, and used as-is, without any revalidation.

If a request is repeated between 1 and 60 seconds later, then the cached value will be stale, but will be used to fulfill the API request. At the same time, "in the background," a revalidation request will be made to populate the cache with a fresh value for future use.

If a request is repeated after more than 60 seconds, then the stale response isn't used at all, and both fulfilling the browser's request and the cache revalidation will depend on getting a response back from the network.

Here's a breakdown of those three distinct states, along with the window of time in which each of them apply for our example:

What are the common use cases?

While the above example for a "minutes after the hour" API service is contrived, it illustrates the expected use case—services that provide information which needs to be refreshed, but where some degree of staleness is acceptable.

Less contrived examples might be an API for the current weather conditions, or the top news headlines that were written in the past hour.

Generally, any response that updates at a known interval, is likely to be requested multiple times, and is static within that interval is a good candidate for short-term caching via max-age. Using stale-while-revalidate in addition to max-age increases the likelihood that future requests can be fulfilled from the cache with fresher content, without blocking on a network response.

How does it interact with service workers?

If you've heard of stale-while-revalidate chances are that it was in the context of recipes used within a service worker.

Using stale-while-revalidate via a Cache-Control header shares some similarities with its use in a service worker, and many of the same considerations around freshness trade-offs and maximum lifetimes apply. However, there are a few considerations that you should take into account when deciding whether to implement a service worker-based approach, or just rely on the Cache-Control header configuration.

Use a service worker approach if…

You're already using a service worker in your web app.
You need fine-grained control over the contents of your caches, and want to implement something like a least-recently used expiration policy. Workbox's Cache Expiration module can help with this.
You want to be notified when a stale response changes in the background during the revalidation step. Workbox's Broadcast Cache Update module can help with this.
You need this stale-while-revalidate behavior in all modern browsers.

Use a Cache-Control approach if…

You would rather not deal with the overhead of deploying and maintaining a service worker for your web app.
You are fine with letting the browser's automatic cache management prevent your local caches from growing too large.
You are fine with an approach that is not currently supported in all modern browsers (as of July 2019; support may grow in the future).

If you're using a service worker and also have stale-while-revalidate enabled for some responses via a Cache-Control header, then the service worker will, in general, have "first crack" at responding to a request. If the service worker decides not to respond, or if in the process of generating a response it makes a network request using fetch(), then the behavior configured via the Cache-Control header will end up going into effect.

Learn more

stale-while-revalidate response in the Fetch API spec.
RFC 5861, covering the initial stale-while-revalidate specification.
The HTTP cache: your first line of defense, from the "Network reliability" guide on this site.

Hero image by Samuel Zeller on Unsplash.

Faster web navigation with predictive prefetching

2019-07-07T17:00:00-07:00

In my Faster Web Navigation with Predictive Prefetching session at Google I/O 2019, I began by talking about optimizing web apps with code-splitting and the potential performance implications for subsequent page navigation. In the second part of the talk, I discussed how to improve navigation speed by using Guess.js to set up predictive prefetching:

Code-splitting for faster web apps

Web apps are slow, and JavaScript is among the most expensive resources that you ship. Waiting for a slow web app to load can frustrate your users and decrease conversions.

Lazy-loading is an efficient technique to reduce the bytes of JavaScript that you're transferring over the wire. You can use several techniques to lazy-load JavaScript, including:

Component-level code-splitting
Route-level code-splitting

With component-level code-splitting, you can move individual components into separate JavaScript chunks. On particular events, you can load the relevant scripts and render the components.

With route-level code-splitting, however, you move entire routes into independent chunks. When users transition from one route to another, they have to download the associated JavaScript and bootstrap the requested page. These operations can lead to significant delays, especially on slow networks.

Prefetching JavaScript

Prefetching allows the browser to download and cache resources that the user is likely to need soon. The usual method is to use <link rel="prefetch">, but there are two common pitfalls:

Prefetching too many resources (overfetching) consumes a lot of data.
Some resources the user needs may never be prefetched.

Predictive prefetching solves these problems by using a report of users' navigational patterns to determine what assets to prefetch.

Predictive prefetching with Guess.js

Guess.js is a JavaScript library that provides predictive prefetching functionality. Guess.js consumes a report from Google Analytics or another analytics provider to build a predictive model that can be used to smartly prefetch only what the user is likely to need.

Guess.js has integrations with Angular, Next.js, Nuxt.js, and Gatsby. To use it in your application, add these lines to your webpack configuration to specify a Google Analytics view ID:

const { GuessPlugin } = require('guess-webpack');

// ...
plugins: [
   // ...
   new GuessPlugin({ GA: 'XXXXXX' })
]
// ...

If you're not using Google Analytics, you can specify a reportProvider and download data from your favorite service.

Integration with frameworks

To learn more about how to integrate Guess.js with your favorite framework check out these resources:

For a quick walkthrough on the integration with Angular, check out this video:

How does Guess.js work?

Here's how Guess.js implements predictive prefetching:

It first extracts data for the user navigational patterns from your favorite analytics provider.
It then maps the URLs from the report to the JavaScript chunks produced by webpack.
Based on the extracted data, it creates a simple predictive model of which pages a user is likely to navigate to from any given page.
It invokes the model for each JavaScript chunk, predicting the other chunks that are likely to be needed next.
It adds prefetching instructions to each chunk.

When Guess.js is done, each chunk will contain prefetching instructions similar to:

__GUESS__.p(
  ['a.js', 0.2],
  ['b.js', 0.8]
)

This Guess.js-generated code is telling the browser to consider prefetching chunk a.js with probability 0.2 and chunk b.js with probability 0.8.

Once the browser executes the code, Guess.js will check the user's connection speed. If it's sufficient, Guess.js will insert two <link rel="prefetch"> tags in the header of the page, one for each chunk. If the user is on a high-speed network, Guess.js will prefetch both chunks. If the user has a poor network connection, Guess.js will only prefetch chunk b.js since it has a high probability of being needed.

Learn more

To learn more about Guess.js, check out these resources:

How OpenSooq increased engagement by investing in the web

2019-07-02T17:00:00-07:00

Based in Amman, Jordan, OpenSooq is a mobile-first classifieds marketplace offering a wide range of products and services in 19 countries across the Middle East and North Africa.

The challenge

Over 85% of OpenSooq's traffic comes from mobile devices, and that number continues to rise. Many people in the region rely on low-end devices with limited storage capacities, which creates a strong need for OpenSooq's mobile site to be as fast and light as possible. However, slow load times on OpenSooq's old mobile site were affecting customer satisfaction and led to bounce rates as high as 49% in markets like Kuwait.

To serve its customers with a consistently better experience across all platforms, the company realized it needed a faster, more responsive website. So, in June 2017, OpenSooq's engineering team launched a Progressive Web App (PWA).

A focus on performance and reliability

OpenSooq's three in-house developers were able to build a full-featured PWA with React and webpack in just two and a half months.

To ensure that the site would be fast and easily indexable by search engines, the team chose to implement server-side rendering. With almost 28% of their users accessing the PWA on patchy 2G or 3G networks, it was critical that users trust the experience to work, regardless of network constraints. So the team implemented an offline experience using service workers and a cache-first-then-network strategy. They also used the PRPL pattern to give their users instant loading.

By adopting these best practices, the team was able to cut the average page load time (Time to Interactive) from 4 seconds to less than 2 seconds. And they used Lighthouse to make sure the site stayed that fast. Those efforts helped OpenSooq hit over 1.8 billion pageviews a month.

OpenSooq's Lighthouse performance metrics.

Over a quarter of our users access the OpenSooq PWA from low-mid networks, so reliability was essential for keeping those users engaged. Service workers and caching strategies helped us build the reliable user experience we needed, seamlessly.
Amin Shoman, PWA Technical Manager, OpenSooq

Improving re-engagement

OpenSooq's meaningful user notifications.

Having built a performant and reliable experience, the OpenSooq team wanted to make sure their users stayed engaged with the product. To do that, they enabled users to install the PWA to their home screen and added support for meaningful notifications. This allowed the site to notify buyers about seller interaction on queries and sellers about ad activation and expiration.

These improvements increased the monthly active users of OpenSooq's web experience by 14%. For users who installed the PWA, there was a 48% increase in the number of page visits per session and a 28% jump in average session duration. OpenSooq also saw a 25% increase in users' average time on a page and a 29% drop in average bounce rates across all markets.

Looking ahead

After just a few weeks of effort, OpenSooq created a 23 KB, full-featured PWA that delivers a consistent experience to users across all platforms and browsers. And because it's easy to update features on the web, the team has gone PWA-first by launching and testing new features and user flows on their PWA before rolling them out to other platforms.

OpenSooq is now working on adding a native install prompt and integrating the PWA with accelerated mobile pages (AMP). These enhancements will further speed up page loads and make the transition to the native app as seamless as possible. By building on the foundation of their initial development effort, the OpenSooq team will continue giving their users the best possible experience.

The importance of developing our PWA was clear to both the leadership and technical teams. After building a modern web app and making it performant, we're excited to see the business impact on our 2.5 month investment.
Ramzi Alqrainy, Chief Technology Officer, OpenSooq

Hello darkness, my old friend

2019-06-26T17:00:00-07:00

Introduction

📚 I have done a lot of background research on the history and theory of dark mode, if you are only interested in working with dark mode, feel free to skip the introduction.

Dark mode before Dark Mode

Green screen (Source)

We have gone full circle with dark mode. In the dawn of personal computing, dark mode wasn't a matter of choice, but a matter of fact: Monochrome CRT computer monitors worked by firing electron beams on a phosphorescent screen and the phosphor used in early CRTs was green. Because text was displayed in green and the rest of the screen was black, these models were often referred to as green screens.

Dark-on-white (Source)

The subsequently introduced Color CRTs displayed multiple colors through the use of red, green, and blue phosphors. They created white by activating all three phosphors simultaneously. With the advent of more sophisticated WYSIWYG desktop publishing, the idea of making the virtual document resemble a physical sheet of paper became popular.

The WorldWideWeb browser (Source)

This is where dark-on-white as a design trend started, and this trend was carried over to the early document-based web. The first ever browser, WorldWideWeb (remember, CSS wasn't even invented yet), displayed webpages this way. Fun fact: the second ever browser, Line Mode Browser—a terminal-based browser—was green on dark. These days, web pages and web apps are typically designed with dark text on a light background, a baseline assumption that is also hard-coded in user agent stylesheets, including Chrome's.

Smartphone used in bed (Source)

The days of CRTs are long over. Content consumption and creation has shifted to mobile devices that use backlit LCD or energy-saving AMOLED screens. Smaller and more transportable computers, tablets, and smartphones led to new usage patterns. Leisure tasks like web browsing, coding for fun, and high-end gaming frequently happen after-hours in dim environments. People even enjoy their devices in their beds at night-time. The more people use their devices in the dark, the more the idea of going back to the roots of light-on-dark becomes popular.

Why dark mode

Dark mode for aesthetic reasons

When people get asked why they like or want dark mode, the most popular response is that "it's easier on the eyes," followed by "it's elegant and beautiful." Apple in their Dark Mode developer documentation explicitly writes: "The choice of whether to enable a light or dark appearance is an aesthetic one for most users, and might not relate to ambient lighting conditions."

👩‍🔬 Read up more on user research regarding why people want dark mode and how they use it.

System 7 CloseView (Source)

Dark mode as an accessibility tool

There are also people who actually need dark mode and use it as another accessibility tool, for example, users with low vision. The earliest occurrence of such an accessibility tool I could find is System 7's CloseView feature, which had a toggle for Black on White and White on Black. While System 7 supported color, the default user interface was still black-and-white.

These inversion-based implementations demonstrated their weaknesses once color was introduced. User research by Szpiro et al. on how people with low vision access computing devices showed that all interviewed users disliked inverted images, but that many preferred light text on a dark background. Apple accommodates for this user preference with a feature called Smart Invert, which reverses the colors on the display, except for images, media, and some apps that use dark color styles.

A special form of low vision is Computer Vision Syndrome, also known as Digital Eye Strain, which is defined as "the combination of eye and vision problems associated with the use of computers (including desktop, laptop, and tablets) and other electronic displays (e.g. smartphones and electronic reading devices)." It has been proposed that the use of electronic devices by adolescents, particularly at night time, leads to an increased risk of shorter sleep duration, longer sleep-onset latency, and increased sleep deficiency. Additionally, exposure to blue light has been widely reported to be involved in the regulation of circadian rhythm and the sleep cycle, and irregular light environments may lead to sleep deprivation, possibly affecting mood and task performance, according to research by Rosenfield. To limit these negative effects, reducing blue light by adjusting the display color temperature through features like iOS' Night Shift or Android's Night Light can help, as well as avoiding bright lights or irregular lights in general through dark themes or dark modes.

Dark mode power savings on AMOLED screens

Finally, dark mode is known to save a lot of energy on AMOLED screens. Android case studies that focused on popular Google apps like YouTube have shown that the power savings can be up to 60%. The video below has more details on these case studies and the power savings per app.

Activating dark mode in the operating system

Now that I have covered the background of why dark mode is such a big deal for many users, let's review how you can support it.

Android Q dark theme settings

Operating systems that support a dark mode or dark theme typically have an option to activate it somewhere in the settings. On macOS X, it's in the system preference's General section and called Appearance (screenshot), and on Windows 10, it's in the Colors section and called Choose your color (screenshot). For Android Q, you can find it under Display as a Dark Theme toggle switch (screenshot), and on iOS 13, you can change the Appearance in the Display & Brightness section of the settings (screenshot).

The `prefers-color-scheme` media query

One last bit of theory before I get going. Media queries allow authors to test and query values or features of the user agent or display device, independent of the document being rendered. They are used in the CSS @media rule to conditionally apply styles to a document, and in various other contexts and languages, such as HTML and JavaScript. Media Queries Level 5 introduces so-called user preference media features, that is, a way for sites to detect the user's preferred way to display content.

☝️ An established user preference media feature is prefers-reduced-motion that lets you detect the desire for less motion on a page. I have written about prefers-reduced-motion before.

The prefers-color-scheme media feature is used to detect if the user has requested the page to use a light or dark color theme. It works with the following values:

no-preference: Indicates that the user has made no preference known to the system. This keyword value evaluates as false in the boolean context.
light: Indicates that the user has notified the system that they prefer a page that has a light theme (dark text on light background).
dark: Indicates that the user has notified the system that they prefer a page that has a dark theme (light text on dark background).

Supporting dark mode

Finding out if dark mode is supported by the browser

As dark mode is reported through a media query, you can easily check if the current browser supports dark mode by checking if the media query prefers-color-scheme matches at all. Note how I don't include any value, but purely check if the media query alone matches.

if (window.matchMedia('(prefers-color-scheme)').media !== 'not all') {
  console.log('🎉 Dark mode is supported');
}

At the time of writing, prefers-color-scheme is supported on both desktop and mobile (where available) by Chrome and Edge as of version 76, Firefox as of version 67, and Safari as of version 12.1 on macOS and as of version 13 on iOS. For all other browsers, you can check the Can I use support tables.

There is a custom element <dark-mode-toggle> available that adds dark mode support to older browsers. I write about it further down in this article.

Dark mode in practice

Let's finally see how supporting dark mode looks like in practice. Just like with the Highlander, with dark mode there can be only one: dark or light, but never both! Why do I mention this? Because this fact should have an impact on the loading strategy. Please don't force users to download CSS in the critical rendering path that is for a mode they don't currently use. To optimize load speed, I have therefore split my CSS for the example app that shows the following recommendations in practice into three parts in order to defer non-critical CSS:

style.css that contains generic rules that are used universally on the site.
dark.css that contains only the rules needed for dark mode.
light.css that contains only the rules needed for light mode.

Loading strategy

The two latter ones, light.css and dark.css, are loaded conditionally with a <link media> query. Initially, not all browsers will support prefers-color-scheme (detectable using the pattern above), which I deal with dynamically by loading the default light.css file via a conditionally inserted <link rel="stylesheet"> element in a minuscule inline script (light is an arbitrary choice, I could also have made dark the default fallback experience). To avoid a flash of unstyled content, I hide the content of the page until light.css has loaded.

<script>
  // If `prefers-color-scheme` is not supported, fall back to light mode.
  // In this case, light.css will be downloaded with `highest` priority.
  if (window.matchMedia('(prefers-color-scheme)').media === 'not all') {
    document.documentElement.style.display = 'none';
    document.head.insertAdjacentHTML(
        'beforeend',
        '<link rel="stylesheet" href="/light.css" onload="document.documentElement.style.display = ``">'
    );
  }
</script>
<!--
  Conditionally either load the light or the dark stylesheet. The matching file
  will be downloaded with `highest`, the non-matching file with `lowest`
  priority. If the browser doesn't support `prefers-color-scheme`, the media
  query is unknown and the files are downloaded with `lowest` priority (but
  above I already force `highest` priority for my default light experience).
-->
<link rel="stylesheet" href="/dark.css" media="(prefers-color-scheme: dark)">
<link rel="stylesheet" href="/light.css" media="(prefers-color-scheme: no-preference), (prefers-color-scheme: light)">
<!-- The main stylesheet -->
<link rel="stylesheet" href="/style.css">

Stylesheet architecture

I make maximum use of CSS variables, this allows my generic style.css to be, well, generic, and all the light or dark mode customization happens in the two other files dark.css and light.css. Below you can see an excerpt of the actual styles, but it should suffice to convey the overall idea. I declare two variables, -⁠-⁠color and -⁠-⁠background-color that essentially create a dark-on-light and a light-on-dark baseline theme.

/* light.css: 👉 dark-on-light */
:root {
  --color: rgb(5, 5, 5);
  --background-color: rgb(250, 250, 250);
}

/* dark.css: 👉 light-on-dark */
:root {
  --color: rgb(250, 250, 250);
  --background-color: rgb(5, 5, 5);
}

In my style.css, I then use these variables in the body { … } rule. As they are defined on the :root CSS pseudo-class—a selector that in HTML represents the <html> element and is identical to the selector html, except that its specificity is higher—they cascade down, which serves me for declaring global CSS variables.

/* style.css */
:root {
  color-scheme: light dark;
}

body {
  color: var(--color);
  background-color: var(--background-color);
}

In the code sample above, you will probably have noticed a property color-scheme with the space-separated value light dark.

Warning: The color-scheme property is still in development and it might not work as advertised, full support in Chrome will come later this year.

This tells the browser which color themes my app supports and allows it to activate special variants of the user agent stylesheet, which is useful to, for example, let the browser render form fields with a dark background and light text, adjust the scrollbars, or to enable a theme-aware highlight color. The exact details of color-scheme are specified in CSS Color Adjustment Module Level 1.

🌒 Read up more on what color-scheme actually does.

Everything else is then just a matter of defining CSS variables for things that matter on my site. Semantically organizing styles helps a lot when working with dark mode. For example, rather than -⁠-⁠highlight-yellow, consider calling the variable -⁠-⁠accent-color, as "yellow" may actually not be yellow in dark mode or vice versa. Below is an example of some more variables that I use in my example.

/* dark.css */
:root {
  --color: rgb(250, 250, 250);
  --background-color: rgb(5, 5, 5);
  --link-color: rgb(0, 188, 212);
  --main-headline-color: rgb(233, 30, 99);
  --accent-background-color: rgb(0, 188, 212);
  --accent-color: rgb(5, 5, 5);
}

/* light.css */
:root {
  --color: rgb(5, 5, 5);
  --background-color: rgb(250, 250, 250);
  --link-color: rgb(0, 0, 238);
  --main-headline-color: rgb(0, 0, 192);
  --accent-background-color: rgb(0, 0, 238);
  --accent-color: rgb(250, 250, 250);
}

Full example

In the following Glitch embed, you can see the complete example that puts the concepts from above into practice. Try toggling dark mode in your particular operating system's settings and see how the page reacts.

Loading impact

When you play with this example, you can see why I load my dark.css and light.css via media queries. Try toggling dark mode and reload the page: the particular currently non-matching stylesheets are still loaded, but with the lowest priority, so that they never compete with resources that are needed by the site right now.

😲 Read up more on why browsers download stylesheets with non-matching media queries.

Site in light mode loads the dark mode CSS with lowest priority.

Site in dark mode loads the light mode CSS with lowest priority.

Site in default light mode on a browser that doesn't support prefers-color-scheme loads the dark mode CSS with lowest priority.

Reacting on dark mode changes

Like any other media query change, dark mode changes can be subscribed to via JavaScript. You can use this to, for example, dynamically change the favicon of a page or change the <meta name="theme-color"> that determines the color of the URL bar in Chrome. The full example above shows this in action, in order to see the theme color and favicon changes, open the demo in a separate tab.

  const darkModeMediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
  darkModeMediaQuery.addListener((e) => {
    const darkModeOn = e.matches;
    console.log(`Dark mode is ${darkModeOn ? '🌒 on' : '☀️ off'}.`);
  });

Dark mode best practices

Avoid pure white

A small detail you may have noticed is that I don't use pure white. Instead, to prevent glowing and bleeding against the surrounding dark content, I choose a slightly darker white. Something like rgb(250, 250, 250) works well.

Re-colorize and darken photographic images

If you compare the two screenshots below, you will notice that not only the core theme has changed from dark-on-light to light-on-dark, but that also the hero image looks slightly different. My user research has shown that the majority of the surveyed people prefer slightly less vibrant and brilliant images when dark mode is active. I refer to this as re-colorization.

Hero image slightly darkened in dark mode.

Regular hero image in light mode.

Re-colorization can be achieved through a CSS filter on my images. I use a CSS selector that matches all images that don't have .svg in their URL, the idea being that I can give vector graphics (icons) a different re-colorization treatment than my images (photos), more about this in the next paragraph. Note how I again use a CSS variable, so I can later on flexibly change my filter.

🎨 Read up more on user research regarding re-colorization preferences with dark mode.

As re-colorization is only needed in dark mode, that is, when dark.css is active, there are no corresponding rules in light.css.

/* dark.css */
--image-filter: grayscale(50%);

img:not([src*=".svg"]) {
  filter: var(--image-filter);
}

Customizing dark mode re-colorization intensities with JavaScript

Not everyone is the same and people have different dark mode needs. By sticking to the re-colorization method described above, I can easily make the grayscale intensity a user preference that I can change via JavaScript, and by setting a value of 0%, I can also disable re-colorization completely. Note that document.documentElement provides a reference to the root element of the document, that is, the same element I can reference with the :root CSS pseudo-class.

const filter = 'grayscale(70%)';
document.documentElement.style.setProperty('--image-filter', value);

Invert vector graphics and icons

For vector graphics—that in my case are used as icons that I reference via <img> elements—I use a different re-colorization method. While research has shown that people don't like inversion for photos, it does work very well for most icons. Again I use CSS variables to determine the inversion amount in the regular and in the :hover state.

Icons are inverted in dark mode.

Regular icons in light mode.

Note how again I only invert icons in dark.css but not in light.css, and how :hover gets a different inversion intensity in the two cases to make the icon appear slightly darker or slightly brighter, dependent on the mode the user has selected.

/* dark.css */
--icon-filter: invert(100%);
--icon-filter_hover: invert(40%);

img[src*=".svg"] {
  filter: var(--icon-filter);
}

/* light.css */
--icon-filter_hover: invert(60%);

/* style.css */
img[src*=".svg"]:hover {
  filter: var(--icon-filter_hover);
}

Use `currentColor` for inline SVGs

For inline SVG images, instead of using inversion filters, you can leverage the currentColor CSS keyword that represents the value of an element's color property. This lets you use the color value on properties that do not receive it by default. Conveniently, if currentColor is used as the value of the SVG fill or stroke attributes, it instead takes its value from the inherited value of the color property. Even better: this also works for <svg><use href="…"></svg>, so you can have separate resources and currentColor will still be applied in context. Please note that this only works for inline or <use href="…"> SVGs, but not SVGs that are referenced as the src of an image or somehow via CSS. You can see this applied in the demo below.

<!-- Some inline SVG -->
<svg xmlns="http://www.w3.org/2000/svg"
    stroke="currentColor"
>
  […]
</svg>

Smooth transitions between modes

Switching from dark mode to light mode or vice versa can be smoothed thanks to the fact that both color and background-color are animatable CSS properties. Creating the animation is as easy as declaring two transitions for the two properties. The example below illustrates the overall idea, you can experience it live in the demo.

body {
  --duration: 0.5s;
   --timing: ease;

  color: var(--color);
  background-color: var(--background-color);

  transition:
    color var(--duration) var(--timing),
    background-color var(--duration) var(--timing);
}

Art direction with dark mode

While for loading performance reasons in general I recommend to exclusively work with prefers-color-scheme in the media attribute of <link> elements (rather than inline in stylesheets), there are situations where you actually may want to work with prefers-color-scheme directly inline in your HTML code. Art direction is such a situation. On the web, art direction deals with the overall visual appearance of a page and how it communicates visually, stimulates moods, contrasts features, and psychologically appeals to a target audience.

With dark mode, it's up to the judgment of the designer to decide what is the best image at a particular mode and whether re-colorization of images is maybe not good enough. If used with the <picture> element, the <source> of the image to be shown can be made dependent on the media attribute. In the example below, I show the Western hemisphere for dark mode, and the Eastern hemisphere for light mode or when no preference is given, defaulting to the Eastern hemisphere in all other cases. This is of course purely for illustrative purposes. Toggle dark mode on your device to see the difference.

<picture>
  <source srcset="western.webp" media="(prefers-color-scheme: dark)">
  <source srcset="eastern.webp" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)">
  <img src="eastern.webp">
</picture>

Dark mode, but add an opt-out

As mentioned in the why dark mode section above, dark mode is an aesthetic choice for most users. In consequence, some users may actually like to have their operating system UI in dark, but still prefer to see their webpages the way they are used to seeing them. A great pattern is to initially adhere to the signal the browser sends through prefers-color-scheme, but to then optionally allow users to override their system-level setting.

The `<dark-mode-toggle>` custom element

You can of course create the code for this yourself, but you can also just use a ready-made custom element (web component) that I have created right for this purpose. It's called <dark-mode-toggle> and it adds a toggle (dark mode: on/off) or a theme switcher (theme: light/dark) to your page that you can fully customize. The demo below shows the element in action (oh, and I have also 🤫 silently snuck it in all of the other examples above).

<dark-mode-toggle
    legend="Theme Switcher"
    appearance="switch"
    dark="Dark"
    light="Light"
    remember="Remember this"
></dark-mode-toggle>

in light mode.">

<dark-mode-toggle> in light mode.

in light mode.">

<dark-mode-toggle> in dark mode.

Try clicking or tapping the dark mode controls in the upper right corner in the demo below. If you check the checkbox in the third and the fourth control, see how your mode selection is remembered even when you reload the page. This allows your visitors to keep their operating system in dark mode, but enjoy your site in light mode or vice versa.

Conclusions

Working with and supporting dark mode is fun and opens up new design avenues. For some of your visitors it can be the difference between not being able to handle your site and being a happy user. There are some pitfalls and careful testing is definitely required, but dark mode is definitely a great opportunity for you to show that you care about all of your users. The best practices mentioned in this post and helpers like the <dark-mode-toggle> custom element should make you confident in your ability to create an amazing dark mode experience. Let me know on Twitter what you create and if this post was useful or also suggestions for improving it. Thanks for reading! 🌒

Resources for the prefers-color-scheme media query:

Resources for the color-scheme meta tag and CSS property:

General dark mode links:

Background research articles for this post:

Acknowledgements

The prefers-color-scheme media feature, the color-scheme CSS property, and the related meta tag are the implementation work of 👏 Rune Lillesveen. Rune is also a co-editor of the CSS Color Adjustment Module Level 1 spec. I would like to 🙏 thank Lukasz Zbylut, Rowan Merewood, Chirag Desai, and Rob Dodson for their thorough reviews of this article. The loading strategy is the brainchild of Jake Archibald. Emilio Cobos Álvarez has pointed me to the correct prefers-color-scheme detection method. The tip with referenced SVGs and currentColor came from Timothy Hatcher. Finally, I am thankful to the many anonymous participants of the various user studies that have helped shape the recommendations in this article. Hero image by Nathan Anderson.

Top tips for web performance

2019-06-23T17:00:00-07:00

According to HTTP Archive, a typical mobile web page weighs over 2.6 MB, and more than two thirds of that weight is images. That's a great opportunity for optimization!

Average mobile page bytes by content type

tl;dr

Don't save images larger than their display size.
Save multiple sizes for each image and use the srcset attribute to enable the browser to choose the smallest. The w value tells the browser the width of each version:

<img src="small.jpg"
     srcset="small.jpg 500w,
             medium.jpg 1000w,
             large.jpg 1500w"
     alt="…">

Save images with the right size

You can make your website faster and less data hungry by using images with dimensions that match the display size. In other words, give images the right width and height when you save them.

Take a look at the images below.

They appear nearly identical, but the file size of one is more than 10 times larger than the other.

Saved width 1000 px, file size 184 KB

Saved width 300 px, file size 16 KB

The first image is much larger in file size because it's saved with dimensions much larger than the display size. Both images are displayed with a fixed width of 300 pixels, so it makes sense to use an image saved at the same size.

For fixed widths, use images saved with the same dimensions as the display size.

But… what if display size varies?

In a multi-device world, images aren't always displayed at a single fixed size.

Image elements might have a percentage width, or be part of responsive layouts where image display sizes change to fit the screen size.

…and what about pixel-hungry devices like Retina displays?

Help the browser choose the right image size

Wouldn't it be great if you could make each image available at different sizes, then let the browser choose the best size for the device and display size? Unfortunately there's a catch-22 when it comes to working out which image is best. The browser should use the smallest possible image, but it can't know the width of an image without downloading it to check.

This is where srcset comes in handy. You save images at different sizes, then tell the browser the width of each version:

<img src="small.jpg"
     srcset="small.jpg 500w, medium.jpg 1000w, large.jpg 1500w"
     alt="…">

The w values show the width of each image in pixels. For example, small.jpg 500w tells the browser that small.jpg is 500 pixels wide. This enables the browser to choose the smallest possible image, depending on the screen type and the viewport size—without having to download images to check their size.

Caution: srcset gives the browser information about the saved width of each image file.

It does not specify the size to display the image—you still need CSS for that!

You can see srcset in action for the image below. If you're on a laptop or desktop computer, change your browser window size and reopen this page. Then use the Network panel of your browser tools to check which image was used. (You'll need to do that in an Incognito or Private window, otherwise the original image file will be cached.)

How can I create multiple image sizes?

You'll need to make multiple sizes available for every image you want to use with srcset.

For one-off images such as hero images you can manually save different sizes. If you have lots of images, such as product photos, you'll need to automate. For that there are two approaches.

Incorporate image processing in your build process

As part of your build process, you can add steps to create different sized versions of your images. See "Use Imagemin to compress images" to learn more.

Use an image service

Image creation and delivery can be automated using a commercial service like Cloudinary, or an open source equivalent such as Thumbor that you install and run yourself.

You upload your high resolution images, and the image service automatically creates and delivers different image formats and sizes depending on the URL parameters. For an example, open this sample image on Cloudinary and try changing the w value or the file extension in the URL bar.

Image services also have more advanced features such as the ability to automate "smart cropping" for different image sizes and automatically deliver WebP images to browsers that support the format, instead of JPEGs—without changing the file extension.

You can check the format delivered using your browser tools.

For the image URL above, a WebP file is automatically delivered to browsers that support WebP, without changing the .jpg file extension.

What if the image doesn't look right at different sizes?

In that case, you'll need to use the <picture> element for "art direction": providing a different image or image crop at different sizes. To learn more take a look at the "Art direction" codelab.

What about pixel density?

High-end devices have smaller (more dense) physical pixels. For example, a high-end phone might have two or three times as many pixels in each row of pixels as a cheaper device.

That can affect the size you need to save your images. We won't go into the gory details here, but you can find out more from the "Use density descriptors" codelab.

What about the display size of the image?

You can use sizes to make srcset work even better.

Without it, the browser uses the full width of the viewport when choosing an image from a srcset. The sizes attribute tells the browser the width that an image element will be displayed, so the browser can choose the smallest possible image file—before it makes any layout calculations.

In the example below, sizes="50vw" tells the browser that this image will be displayed at 50% of the viewport width.

<img src="small.jpg"
     srcset="small.jpg 500w, medium.jpg 1000w, large.jpg 1500w"
     sizes="50vw"
     alt="…">

You can see this in action at simpl.info/sizes and the "Specifying multiple slot widths" codelab.

Caution: sizes gives the browser information about the display width of on image element.

As with srcset it does NOT specify the size to display the image—you need CSS for that.

What about browser support?

srcset and sizes are supported by over 90% of browsers globally.

If a browser does not support srcset or sizes it will fall back to just using the src attribute.

This makes srcset and sizes great progressive enhancements!

Learn more

Take a look at the "Optimize your images" section of web.dev for a deeper dive into image optimization. For a more guided experience, consider trying the free "Responsive Images" course offered by Udacity.

This post accompanies Top tips for web performance: a fortnightly video series showing simple techniques to improve site speed.

Bringing service workers to Google Search

2019-06-19T17:00:00-07:00

Background

Search for just about any topic on Google, and you're presented with an instantly recognizable page of meaningful, relevant results. What you probably didn't realize is that this search results page is, under certain scenarios, served by a powerful piece of web technology called a service worker.

Rolling out service worker support for Google Search without negatively impacting the performance required dozens of engineers working across multiple teams. This is the story of what shipped, how performance was measured, and what tradeoffs were made.

Key reasons for exploring service workers

Adding a service worker to a web app, just like making any architectural change to your site, should be done with a clear set of goals in mind. For the Google Search team, there were a few key reasons why adding a service worker was worth exploring.

A service worker is extra code that sits in between your web app and the network, and running that code isn't free, so you need to make sure that what you're doing inside the service worker adds enough of a caching or functionality benefit to justify the cost of running the code. (This talk at the Chrome Dev Summit 2018 does a great job of exploring that idea in more detail.) An upfront understanding what you hope to achieve—and then collecting a full set of metrics to ensure that you've actually achieved it—should be the first step in your service worker journey.

Limited search result caching

The Google Search team found that it's common for users to search for the same terms more than once within a short period of time. Rather than trigger a new backend request just to get what's likely to be the same results, the Search team wanted to take advantage of caching and fulfill those repeat requests locally.

The importance of freshness can't be discounted, and sometimes users search for the same terms repeatedly because it's an evolving topic, and they expect to see fresh results. Using a service worker allows the Search team to implement fine-grained logic to control the lifetime of locally cached search results, and achieve the exact balance of speed vs. freshness that they believe best serves users.

Meaningful offline experience

Additionally, the Google Search team wanted to provide a meaningful offline experience. When a user wants to find out about a topic, they want to go straight to the Google Search page and start searching, without worrying about an active Internet connection.

Without a service worker, visiting the Google search page while offline would just lead to the browser's standard network error page, and users would have to remember to come back and try again once their connection returned. With a service worker, it's possible to serve a custom offline HTML response, and allow users to enter their search query immediately.

The results won't be available until there's an Internet connection, but the service worker allows the search to be deferred and sent to Google's servers as soon as the device goes back online using the background sync API.

Smarter JavaScript caching and serving

Another motivation was to optimize the caching and loading of the modularized JavaScript code that powers the various types of features on the search results page. There are a number of benefits offered by JavaScript bundling that make sense when there's no service worker involvement, so the Search team did not want to simply stop bundling entirely.

By using a service worker's ability to version and cache fine-grained chunks of JavaScript at runtime, the Search team suspected that they could reduce the amount of cache churn and ensure that JavaScript reused in the future can be cached efficiently. The logic inside of their service worker can analyze an outgoing HTTP request for a bundle that contains multiple JavaScript modules, and fulfill it by piecing together multiple, locally cached modules—effectively "unbundling" when possible. This saves user bandwidth, and improves overall responsiveness.

Success: On average, repeat visits handled by the service worker result in half as much new JavaScript downloaded, and that directly leads to 6% fewer delayed user interactions.

There are also performance benefits of using cached JavaScript served by a service worker: in Chrome, a parsed, byte code representation of that JavaScript is stored and reused, leading to less work that needs to be done at runtime in order to execute the JavaScript on the page.

Challenges and solutions

Here are a few of the hurdles that needed to be overcome in order to achieve the team's stated goals. While some of these challenges are specific to Google Search, many of them are applicable to a wide range of sites that might be considering a service worker deployment.

Problem: service worker overhead

The biggest challenge, and the one true blocker for launching a service worker on Google Search, was to ensure that it did not do anything that might increase user-perceived latency. Google Search takes performance very seriously, and in the past, has blocked launches of new functionality if it contributed even tens of milliseconds of additional latency for a given user population.

When the team started collecting performance data during their earliest experiments, it became obvious that there would be a problem. The HTML returned in response to navigation requests for the search result page is dynamic, and varies greatly depending on logic that needs to run on Search's web servers. There's currently no way for the service worker to replicate this logic and return cached HTML immediately—the best it could do is to pass along navigation requests to the backend web servers, which necessitates a network request.

Without a service worker, this network request happens immediately upon user navigation. When a service worker is registered, it always needs to be started up and given a chance to execute its fetch event handlers, even when there's no chance those fetch handlers will do anything other than go to the network. The amount of time that it takes to start up and run the service worker code is pure overhead added on top of every navigation:

This puts the service worker implementation at too much of a latency disadvantage to justify any other benefits. Additionally, the team found that, based on measuring service worker boot times on real-world devices, there was a wide distribution of startup times, with some low-end mobile devices taking almost as much time to start up the service worker as it might take to make the network request for the results page's HTML.

The single, most crucial feature that allowed the Google Search team to move ahead with their service worker launch is navigation preload. Using navigation preload is a key performance win for any service worker that needs to use a response from the network to satisfy navigation requests. It provides a hint to the browser to start making the navigation request immediately, at the same time as the service worker starts up:

As long as the amount of time it takes for the service worker to start up is less than the amount of time it takes to get a response back from the network, there shouldn't be any latency overhead introduced by the service worker.

The Search team also needed to avoid using a service worker on low-end mobile devices where the service worker boot time could exceed the navigation request. Since there's no hard-and-fast rule for what constitutes a "low-end" device, they came up with the heuristic of checking the total RAM installed on the device. Anything less than 2 gigabytes of memory fell into their low-end device category, where service worker startup time would be unacceptable.

Available storage space is another consideration, since the full set of resources to be cached for future use can run to several megabytes. The navigator.storage interface allows the Google Search page to figure out in advance whether their attempts to cache data run the risk of failing due to storage quota failures.

This left the Search team with multiple pieces of criteria that they could use to determine whether or not to use a service worker: if a user comes to the Google Search page using a browser that supports navigation preload, and has at least 2 gigabytes of RAM, and enough free storage space, then a service worker is registered. Browsers or devices that don't meet that criteria won't end up with a service worker, but they'll still see the same Google Search experience as they always have.

One side benefit of this selective registration is the ability to ship a smaller, more efficient service worker. Targeting fairly modern browsers to run the service worker code eliminates the overhead of transpilation and polyfills for older browsers. This ended up cutting out around 8 kilobytes of uncompressed JavaScript code from the total size of the service worker's implementation.

Problem: service worker scopes

Once the Search team ran enough latency experiments and were confident that using navigation preload offered them a viable, latency-neutral path for using a service worker, some practical issues started moving to the forefront. One of those issues has to do with service worker's scoping rules. A service worker's scope determines which pages it can potentially take control of.

Scoping works based on the URL path prefix. For domains that host a single web app, this isn't an issue, as you'd normally just use a service worker with the maximal scope of /, which could take control of any page under the domain. But Google Search's URL structure is a little more complicated.

If the service worker were given the maximal scope of /, it would end up being able to take control of any page hosted under www.google.com (or the regional equivalent), and there are URLs under that domain that have nothing to do with Google Search. A more reasonable, restrictive scope would be /search, which at least would eliminate URLs completely unrelated to search results.

Unfortunately, even that /search URL path is shared amongst different flavor of Google Search results, with URL query parameters determining which specific type of search result is shown. Some of those flavors use completely different codebases than the traditional web search result page. For example, Image Search and Shopping Search are both served under the /search URL path with different query parameters, but neither of those interfaces were ready to ship their own service worker experience (yet).

Solution: create a dispatch and routing framework

While there are some proposals that allow for something more powerful than URL path prefixes to determine service worker scopes, the Google Search team was stuck deploying a service worker that did nothing for a subset of pages it controlled.

To work around this, the Google Search team built up a bespoke dispatch and routing framework that could be configured to check for criteria like the query parameters of the client page, and use those to determine which specific code path to go down. Rather than hardcoding rules, the system was built to be flexible and allow teams that share the URL space, like Image Search and Shopping Search, to drop in their own service worker logic down the line, if they decide to implement it.

While this custom solution is internal to Google, the same general principle can be applied to any domain that includes a number of different logical web apps, all of whom live under a common URL.

Problem: personalized results and metrics

Users can sign in to Google Search using their Google Accounts, and their search results experience may be customized based on their particular account data. Logged in users are identified by specific browser cookies, which is a venerable and widely-supported standard.

One downside of using browser cookies, though, is that they are not exposed inside of a service worker, and there is no way of automatically examining their values and ensuring that they have not changed due to a user logging out or switching accounts. (There is effort underway to bring cookie access to service workers, but as of this writing, the approach is experimental and is not widely supported.)

A mismatch between the service worker's view of the current logged in user and the actual user logged in to the Google Search web interface could lead to incorrectly personalized search results or misattributed metrics and logging. Any of those failure scenarios would be a serious issue for the Google Search team.

Solution: send cookies using postMessage

Rather than wait for experimental APIs to launch and provide direct access to the browser's cookies inside of a service worker, the Google Search team went with a stop-gap solution: whenever a page controlled by the service worker is loaded, the page reads the relevant cookies and uses postMessage() to send them to the service worker.

The service worker then checks the current cookie value against the value that it expects, and if there's a mismatch, it takes steps to purge any user-specific data from its storage, and reloads the search results page without any incorrect personalization.

The specific steps that the service worker takes to reset things to a baseline are particular to Google Search's requirements, but the same general approach may be useful to other developers who deal with personalized data keyed off of browsers cookies.

Problem: experiments and dynamism

As mentioned, the Google Search team relies heavily on running experiments in production, and testing the effects of new code and features in the real world before turning them on by default. This can be a bit of a challenge with a static service worker that relies heavily on cached data, since opting users in and out of experiments often requires communication with the backend server.

Solution: dynamically generated service worker script

The solution that the team went with was to use a dynamically generated service worker script, customized by the web server for each individual user, instead of a single, static service worker script that gets generated ahead of time. Information about experiments that might affect the service worker's behavior or network requests in general are included directly in this customized service worker scripts. Changing the sets of active experiences for a user is done via a combination of traditional techniques, like browser cookies, as well as serving updated code in the registered service worker URL.

Using a dynamically generated service worker script also makes it easier to provide an escape hatch in the unlikely event that a service worker implementation has a fatal bug that needs to be avoided. The dynamic server worker response could be a no-op implementation, effectively disabling the service worker for some or all of the current users.

Problem: coordinating updates

One of the toughest challenges facing any real-world service worker deployment is to devise a reasonable tradeoff between avoiding the network in favor of the cache, while at the same time, ensuring that existing users get critical updates and changes soon after they're deployed to production. The right balance depends on a lot of factors:

Whether your web app is a long-lived single page app that a user keeps open indefinitely, without navigating to new pages.
What the deployment cadence is for updates to your backend web server.
Whether the average user would tolerate using a slightly out-of-date version of your web app, or whether freshness is the top priority.

While experimenting with service workers, the Google Search team made sure to keep the experiments running across a number of scheduled backend updates, to ensure that the metrics and user experience would more closely match what return users would end up seeing in the real-world.

Caution: It's important to remember that shipping a service worker is not a one-time deployment—you need to have a process in place, tailored to your own production infrastructure, to make sure that updates happen smoothly over time!

Solution: balance freshness and cache-utilization

After testing a number of different configuration options, the Google Search team found that the following setup provided the right balance between freshness and cache-utilization.

The service worker script URL is served with the Cache-Control: private, max-age=1500 (1500 seconds, or 25 minutes) response header, and is registered with updateViaCache set to 'all' to ensure that the header is honored. The Google Search web backend is, as you might imagine, a large, globally distributed set of servers that requires as close to 100% uptime as possible. Deploying a change that would affect the service worker script's contents is done in a rolling fashion.

If a user hits a backend that has been updated, and then quickly navigates to another page which hits a backend that hasn't yet received the updated service worker, they'd end up flip-flopping between versions multiple times. Therefore, telling the browser to only bother checking for an updated script if 25 minutes has passed since the last check does not have a significant downside. The upside of opting-in to this behavior is cutting down significantly on the traffic received by the endpoint that dynamically generates the service worker script.

Additionally, an ETag header is set on the service worker script's HTTP response, ensuring that when an update check is made after 25 minutes has passed, the server can respond efficiently with an HTTP 304 response if there haven't been any updates to the service worker deployed in the interim.

While some interactions within the Google Search web app use single page app-style navigations (i.e. via the History API), for the most part, Google Search is a traditional web app that uses "real" navigations. This comes into play when the team decided that it would be effective to use two options that accelerate the service worker update lifecycle: clients.claim() and skipWaiting(). Clicking around Google Search's interface generally ends up navigating to new HTML documents. Calling skipWaiting ensures that an updated service worker gets a chance to handle those new navigation requests immediately after installation. Similarly, calling clients.claim() means that the updated service worker gets a chance to start controlling any open Google Search pages that are uncontrolled, following service worker activation.

The approach that Google Search went with isn't necessarily a solution that works for everyone—it was the result of carefully A/B testing various combinations of serving options until they found what worked best for them. Developers whose backend infrastructure allow them to deploy updates more quickly might prefer that the browser check for an updated service worker script as frequently as possible, by always ignoring the HTTP cache. If you're building a single page app that users will might keep open for a long period of time, using skipWaiting() is probably not the right choice for you—you risk running into cache inconsistencies if you allow the new service worker to activate while there are long-lived clients.

Key Takeaways

By default, service workers aren't performance neutral

Adding a service worker to your web app means inserting an additional piece of JavaScript that needs to be loaded and executed before your web app gets responses to its requests. If those responses end up coming from a local cache rather than from the network, then the overhead of running the service worker is usually negligible in comparison to the performance win from going cache-first. But if you know that your service worker always has to consult the network when handling navigation requests, using navigation preload is a crucial performance win.

Service workers are (still!) a progressive enhancement

The service worker support story is much brighter today than it was even a year ago. All modern browsers now feature at least some support for service workers, but unfortunately, there are some advanced service worker features—like background sync and navigation preload—that aren't rolled out universally. Feature checking for the specific subset of features that you know you need, and only registering a service worker when those are present, is still a reasonable approach to take.

Similarly, if you've run experiments in the wild, and know that low-end devices end up performing poorly with the additional overhead of a service worker, you can abstain from registering a service worker in those scenarios as well.

You should continue to treat service workers as a progressive enhancement that gets added to a web app when all the prerequisites are met and the service worker adds something positive to user experience and overall loading performance.

Measure everything

The only way you can figure out whether shipping a service worker has had a positive or negative impact on your users' experiences is to experiment and measure the results.

The specifics of setting up meaningful measurements depends on what analytics provider you're using, and how you normally conduct experiments in your deployment setup. One approach, using Google Analytics to collect metrics, is detailed in this case study based on the experience using service workers in the Google I/O web app.

Non-goals

While many in the web development community associate service workers with Progressive Web Apps, building a "Google Search PWA" was not an initial goal of the team. The Google Search web app doesn't currently provide metadata via a web app manifest, nor does it encourage users to go through the Add to Homescreen flow. The Search team is currently satisfied with users coming to their web app via the traditional entry points for Google Search.

Rather than trying to turn the Google Search web experience into the equivalent of what you'd expect from an installed application, the focus on the initial roll out was to progressively enhance the existing web site.

Acknowledgements

Thanks to the entire Google Search web development team for their work on the service worker implementation, and for sharing the background material that went into writing this article. Particular thanks goes to Philippe Golle, Rajesh Jagannathan, R. Samuel Klatchko, Andy Martone, Leonardo Peña, Rachel Shearer, Greg Terrono, and Clay Woolam.

How we're bringing Google Earth to the web

2019-06-19T17:00:00-07:00

In an ideal world, every application that developers build, regardless of technology, would be available in the browser. But there are barriers to bringing projects to the web, depending on the technology they were built with and how well that technology is supported by the various browser vendors. WebAssembly (Wasm) is a compile target standardized by the W3C that helps us solve this problem by allowing us to run codebases from languages other than JavaScript on the web.

We've done just that with Google Earth, available today in preview beta on WebAssembly. Keep in mind that this is still a beta of Google Earth and may not be as smooth as you're used to (try out regular Earth for web). You can experiment with this beta in Chrome and other Chromium-based browsers, including Edge (Canary version) and Opera, as well as Firefox. Consider this beta your inspiration if you too are looking for better cross-browser support for your native applications.

Why we chose WebAssembly for Google Earth

We originally wrote most of Google Earth in C++ because it was a native application intended for desktop install. Then we were able to port it to Android and iOS as smartphones took hold, retaining most of our C++ codebase using NDK and Objective-C++. In 2017, when we brought Earth to the web, we used Native Client (NaCl) to compile the C++ code and run it in the Chrome browser.

At the time, NaCl was the only browser technology that allowed us to port our C++ code to the browser and give us the kind of performance Earth needed. Unfortunately, NaCl was a Chrome-only technology that never saw adoption across browsers. Now we're starting to switch to WebAssembly, which lets us take that same code and run it across browsers. This means Earth will be available to more people across the web.

A thread on threading

WebAssembly is still evolving as a standard, and browsers continue to get extended with more features and functionality. From the Earth perspective, the most significant difference in support for WebAssembly between browsers is support for threading. Some browsers offer multi-threading support and others don't. Think of Earth like a huge 3D video game of the real world. As such, we're constantly streaming data to the browser, decompressing it and making it ready for rendering to the screen. Being able to do this work on a background thread has shown a clear improvement in the performance of Earth in the browser.

Multi-threaded WebAssembly relies on a browser feature called SharedArrayBuffer, which was pulled from browsers after the Spectre and Meltdown security vulnerabilities were revealed. To mitigate potential damage from attacks, Chrome's security team introduced Site Isolation in Chrome for all desktop operating systems. Site Isolation limits each renderer process to documents from a single site. With this security feature in place, Chrome re-enabled SharedArrayBuffer for desktop—which allowed us to use multi-threaded WebAssembly with Earth for Chrome.

Other browsers are working on Site Isolation or other mitigations in order to re-enable SharedArrayBuffer. In the meantime, Earth runs single-threaded in those browsers.

How WebAssembly works with different browsers

We've learned a lot about the state of WebAssembly support in browsers porting Earth. If you're going to develop applications using WebAssembly, it's important to understand the current state of how WebAssembly works with different browsers.

Edge

Edge is on the verge of becoming two distinct development experiences based on Microsoft's choice to move from the EdgeHTML renderer over to a Chromium-based renderer. At the moment, the Google Earth beta on WebAssembly won't run on the current public version of Edge due to lack of support for WebGL2. That will be fixed once the new version of Edge, based on Chromium, ships in the near future. In the meantime, you can download the Canary version of Edge and see that Earth works quite well.

Chrome

Chrome has strong support for WebAssembly, including multi-threading on desktop, so you can expect Earth to run smoother as a result. However, we look forward to Chrome adding support for dynamic memory allocation with multi-threading in WebAssembly. Until then, Earth may fail to start on devices with limited amounts of memory (such as 32-bit machines).

Firefox

Firefox offers good support for WebAssembly, but has disabled support for multi-threading. As a result, you can expect a slower experience with Earth. We look forward to Mozilla bringing back support for multi-threading in future versions. On the upside, Firefox does support dynamic memory allocation.

Opera

Opera is based on Chromium just as Chrome is, along with upcoming versions of Edge. However, the current version of Opera only offers single-threaded support of WebAssembly. Earth does run in Opera, but at a somewhat degraded experience. Hopefully newer versions of Opera will have support for multi-threading and more robust WebAssembly support.

Safari

Safari has a strong implementation of WebAssembly, but it lacks full support for WebGL2. Therefore, Earth with WebAssembly does not run in Safari. Specifically, some of our shaders require GLSL 1.2. We hope that Earth will be available on Safari as well, once better support for WebGL2 is added.

Looking forward to more adoption of WebAssembly features

It's been a long road to make Earth available on the web. About six years ago, we started with an initial asm.js-based internal demo that was maintained and expanded over the years. It was then converted into a WebAssembly build of Earth, as WebAssembly became the W3C adopted standard.

We still have a ways to go for WebAssembly and Earth. Specifically, we'd like to move to the LLVM backend using Emscripten (the toolchain to generate WebAssembly out of C++ code). This change will enable future SIMD support, as well as stronger debugging tools like source maps for native code. Other things we hope to see are adoption of OffscreenCanvas and full support for dynamic memory allocation in WebAssembly. But we know we're on the right track: WebAssembly is the long-term future for Earth on the web.

Please take a moment to try our beta. Let us know how it works for you by leaving feedback directly in Earth.

Web components: the secret ingredient helping power the web

2019-06-17T17:00:00-07:00

At Google I/O 2019, Kevin Schaaf of the Polymer Project and Caridy Patiño of Salesforce talked about the state of web components.

How popular are web components?

If you've used the web today, you've probably used web components. By our count, somewhere between 5% and 8% of all page loads today use one or more web components. That makes web components one of the most successful new web platform features shipped in the last five years.

You can find web components on sites you probably use every day, like YouTube and GitHub. They're also used on many news and publishing sites built with AMP—AMP components are also web components. And many enterprises are also adopting web components.

What are web components?

So what are web components? The web components specifications provide a low-level set of APIs that let you extend the browser's built-in set of HTML tags. Web components provide:

A common method for creating a component (using standard DOM APIs).
A common way of receiving and sending data (using properties/events).

Outside of that standard interface, the standards don't say anything about how a component is actually implemented:

What rendering engine it uses to create its DOM.
How it updates itself based on changes to its properties or attributes.

In other words, web components tell the browser when and where to make a component, but not how.

Authors can choose functional rendering patterns just like React to build their web components, or they can use declarative templates like you might find in Angular or Vue. As an author you have total freedom to choose the technology you use inside the component, while still maintaining interoperability.

What are web components good for?

The key difference between web components and proprietary component systems is interoperability. Because of their standard interface, you can use web components anywhere you'd use a built-in element like <input> or <video>.

Because they can be expressed as real HTML, they can be rendered by all the popular frameworks. So your components can be consumed more widely, in a more diverse range of applications, without locking users into any one framework.

And because the component interface is standard, web components implemented using different libraries can be mixed on the same page. This fact helps future-proof your applications when you update your tech stack. Instead of a giant step-change between one framework and another, where you replace all of your components, you can update your components one at a time.

Who's using web components?

So for all of these reasons, Web Components are actually finding huge success in a variety of different use cases. Three use cases have been especially popular: content sites, design systems, and enterprise applications.

Content sites

Web components are the perfect technology for progressively enhancing content, because they can already be output as standard HTML by an untold number of CMS systems.

AMP is a great example of how quickly and easily Web Components slotted into the publishing industry's infrastructure for serving content.

Design systems

More and more companies are unifying the way they present themselves using a design system—a set of components and guidelines that define the common look and feel for an organization's sites and applications. Web components are a great fit here, too.

Often, designers have to contend with many teams building their own versions of the design system components on top of React, Angular, and all the other frameworks, instead of having a single set of canonical components.

Web components are the answer—a truly write once, run everywhere component system that still gives app teams freedom to use the framework of their choice

Companies like ING, EA, and Google are implementing their company's design language in web components.

Enterprise: Web components at Salesforce

Web components are also hitting a remarkable stride inside enterprises as a safe, future-proof technology to standardize on. Caridy Patiño, architect for Salesforce's UI platform, explained why they built their UI platform using web components.

Salesforce is a collection of applications—many of which came from acquisitions. Each of these may run on its own technology stack. Because they're built on different stacks, it's hard to give them all the same look and feel. In addition, Salesforce enables customers to build their own custom applications using the Salesforce platform. So ideally the components should be usable by outside developers, too.

Salesforce identified a set of needs from customers of their platform:

Standard, rather than proprietary solutions—so it's easier to find experienced developers, and quicker to ramp up new developers.
A common component model—so customizing any Salesforce application works the same way.

They also identified some things customers didn't want:

Breaking changes on their components and apps. In other words, backwards compatibility was a must.
Being stuck with old technology, and unable to evolve.
Being stuck inside a walled garden.

Using web components as the basis for the new UI platform met all of these needs, and the result is the new Lightning Web Components.

Get started with web components

There are a lot of great ways to get started with web components.

If you're building a web app, consider using some of the many off-the-shelf web components available. Here are just a few examples:

Google vends its own Material design system as web components: Material Web Components.
The Wired Elements are a cool set of web components that feature a sketchy, hand-drawn look.
There are great special-purpose Web Components like , which you can drop into any app to add 3D content.

If you're developing a design system for your company, or you're vending a single component or library that you want to be usable in any environment, consider authoring your components using web components. You can use the native web components APIs, but they're pretty low-level, so there are a number of libraries available to make the process easier.

To get started building your own components, you can check out LitElement, a web component base class developed by Google that has a great functional rendering experience similar to React.

Other tools and libraries to consider:

Stencil is a web-components-first framework. It includes several popular framework features, like JSX and TypeScript
Angular Elements provides a way to wrap Angular components as web components.
Vue.js web component wrapper provides a way to package Vue components as web components.

More resources:

open-wc.org features great getting started information, as well as tips and default configurations for build and development tooling.
Web Fundamentals provides primers on the basic web components APIs, and best practices for designing web components.
MDN provides reference docs for the web components APIs, plus some tutorials. \

Hero image by Jason Tuinstra on Unsplash.

Editor's note: The custom elements usage chart has been updated to show the full monthly usage data, as reported on chromestatus.com. A previous version of this post included a graph at a 6-month granularity, without the most recent months. The V0 & V1 series in the original chart were stacked; they are now shown unstacked with a total line to remove ambiguity. The abrupt jump in late 2017 is due to a change in the data collection system for chromestatus.com. This change affected the stats for all web platform features and resulted in more accurate measurements going forward.

Use Lighthouse for performance budgets

2019-06-13T17:00:00-07:00

Lighthouse now supports performance budgets. This feature, LightWallet, can be set up in under five minutes and provides feedback on the size and quantity of page resources.

Install Lighthouse

LightWallet is available in the command line version of Lighthouse v5+.

To get started, install Lighthouse:

npm install -g lighthouse

Create a Budget

Create a file named budget.json. In this file add the following JSON:

[
  {
    "resourceSizes": [
      {
        "resourceType": "script",
        "budget": 125
      },
      {
        "resourceType": "total",
        "budget": 300
      }
    ],
    "resourceCounts": [
      {
        "resourceType": "third-party",
        "budget": 10
      }
    ]
  }
]

This example budget.json file sets three separate budgets:

A budget of 125 KB for the total amount of JavaScript on the page.
A budget of 300 KB for the overall size of the page.
A budget of 10 requests for the numer of requests made to third-party origins.

You can set budgets for any of the following resource types: document, font, image, media, other,script, stylesheet, third-party, and total.

Run Lighthouse

Run Lighthouse using the --budget-path flag. This flag tells Lighthouse the location of your budget file.

lighthouse https://example.com --budget-path=./budget.json

Note: A budget file does not have to be named budget.json.

View the Results

If LightWallet has been configured correctly, the Lighthouse report will contain a Budgets section within the Performance category.

In the JSON version of the Lighthouse report, Lightwallet results can be found within the audit findings for the performance-budget audit.

The value of speed

2019-06-12T17:00:00-07:00

After a lot of hard work, you've done it. You've made your company's site noticeably faster. Now it's time for the fun part: showing stakeholders how much extra revenue your work has generated!

In this post we'll walk through how to do that by calculating the relative mobile conversion rate. This metric is useful because it quantifies the effects of site improvements while excluding external factors like marketing campaigns, which can obscure your findings. Let's get started!

Relative Mobile Conversion Rate (Rel mCvR)

A site's conversion rate can be influenced by site characteristics—like speed and usability—and by external factors—like marketing campaigns, seasonal events, and the mix of marketing channels.

A conversion happens when a site visitor becomes a customer. What counts as a conversion will vary depending on the nature of the site. Buying a product, subscribing to a service, registering as a user, or even just viewing a particular page could be considered a conversion. Check with your marketing team if you're not sure how conversions are counted in your company.

Since you're interested in how site speed affects conversions, the mobile site is most relevant—that's where you're most likely to see the benefits of speed improvements. Rather than looking at the mobile conversion rate alone, though, you'll be analyzing the relative mobile conversion rate (Rel mCvr), which is calculated by dividing the mobile conversion rate by the desktop conversion rate. This approach reduces the noise from external factors, which tend to affect both desktop and mobile, and makes it easier to see whether any increases in the mobile site's effectiveness were actually caused by the speed improvements.

Caution: Rel mCvR is influenced not only by speed, but also by other site characteristics like usability. If other big changes were made to the site during the period you want to analyze, you won't be able to measure the effects of speed improvements on their own, but you can show the benefits of all the improvements as a group.

Doing the analysis

If you have access to your site's page analytics data, you can follow along using that. This walkthrough uses Google Analytics to get site data. If you don't have a Google Analytics account, you can learn how to set one up at Get started with Analytics. Or, if you just want to see how Rel mCvR is calculated, you can get the sample data set shown below from this Google Sheet and skip steps 1–3.

Step 1: First get the speed and conversion data for the mobile site.

Open this custom report in Google Analytics, select your site from the Select a view drop-down list, and click Create.
Once the report has been generated, click Select a metric > Metric Group > Ecommerce Conversion Rate.
Select the Week view for the dataset.
Select a time period that covers 2–3 months before the speed optimization and 2–3 months after. (In our example, that's January 2018 through October 2018.)
Export the report to Google Sheets or your preferred spreadsheet application.

Step 2: Now get the speed and conversion data for the desktop site. Open this custom report in Google Analytics and repeat the process for step 1 to export the data to a spreadsheet.

Step 3: Copy the Ecommerce Conversion Rate column in the desktop report spreadsheet and insert it next to the Ecommerce Conversion Rate in the mobile report spreadsheet.

Step 4: To calculate the Rel mCvR, create a new column titled Relative Mobile Conversion Rate (Rel mCvR). Then add a formula to divide the mobile conversion rate by the desktop conversion rate.

Step 5: Create a chart based on the Mobile Avg. Page Load Time (sec) and Relative Mobile Conversion Rate (Rel mCvR) columns. To do that in Google Sheets:

Click Insert > Chart.
In the Chart Editor pane, select the Line chart chart type.
Select the Week Index, Mobile Avg. Page Load Time (sec), and Relative Mobile Conversion Rate (Rel mCvR) columns as the data ranges.
Click the Customize tab and then select Series.
In the Series selector drop-down list, select Relative Mobile Conversion Rate (Rel mCvR).
In the Axis drop-down list select Right axis.
If you like, click Chart & axis titles to customize the chart title and the left and right y-axis labels.

You should now have a chart that looks something like this:

Step 6: Using the chart, identify a period before the speed optimization (when load times were high) and a period after the speed optimization (when load times should be lower) that you want to analyze. In this example, you would compare eight weeks in Jan–Feb to eight weeks in Aug–Sept.

Step 7: In a new sheet, calculate the average load time and rel mCvR for the two periods. Then add the revenue coming from mobile visitors during the period after the speed optimization (Aug–Sept in the example). You can find revenue data in Google Analytics under the section Audience > Mobile > Overview.

Step 8: Now calculate what the revenue would have been if Rel mCvR had not improved. Do this by dividing the revenue (€1,835,962) by the current Rel mCvR (51%) and multiplying by the Rel mCvR for the period before the speed optimization (42%).

Step 9: Subtract the revenue that the company earned from what it would have earned if Rel mCvR had not improved.

In this example, the company earned an additional €323,993 in eight weeks thanks to Rel mCvR improving—that is, thanks to the mobile site becoming faster.

Things to consider when analyzing Rel mCvR

As noted above, other changes to the site, such as UX improvements, can influence Rel mCvR. Check that speed was the only big change to the site during the period you want to study. If there were other changes, Rel mCvR can tell you the effect of the changes as a group, but not of an individual change.
Watch out for any changes or events that affected the desktop site but not the mobile site—they can skew your results. If you discover any desktop-only changes, omit the affected period from your analysis.
You might wonder whether an increase in Rel mCvR is caused by a shift in conversions from desktop to mobile rather than an increase in conversions overall. While there is likely to be some change in the mix of desktop and mobile conversions due to speed improvements, keep in mind that Rel mCvR calculates the mobile conversion rate relative to the desktop conversion rate. So, you only see an increase in Rel mCvR when mCvR goes up more than dCvR. In other words, when doing this calculation you're already counting low, which means you have a safety margin that can compensate for any shifts in the channel mix.

Summing up

While it has some limitations, Rel mCvR is a great low-cost way to estimate how much a speed optimization increased revenue without, for example, having to run server-side or slow-down tests. And quantifying the relationship between performance and revenue can help you demonstrate the value of development projects whose benefits might not be immediately clear to non-technical stakeholders.

Next steps

Aircraft instrument panel image by Arie Wubben on Unsplash

Updates to the Web Payments APIs

2019-06-12T17:00:00-07:00

Web Payments have been publicly available in browsers since 2016. The core feature—the Payment Request API—is now available across multiple browsers: Chrome, Safari, Edge and soon Firefox. If you're new to Web Payments take a look at the "Web Payments Overview" to get started.

Since the launch of the Payment Request API and the Payment Handler API, there have been quite a few changes made to their respective specifications. These changes won't break your working code, but we recommend that you look out for them. This post summarizes those updates and will continue accumulating those API changes.

If you want to subscribe to further upcoming changes to Chrome's Web Payments implementation, please join the Public Payment Request Announcements group.

Alternatively, join the public Web Payments community for the same updates. You may ask questions there as well.

If you want to check older updates to Chrome, head over to "Changes in the Payment Request API" article at Web Fundamentals.

New method: `hasEnrolledInstrument()`

In the previous version of the Payment Request API, canMakePayment() was used to check for the user's presence of the user's payment instrument. In a recent update to the spec, canMakePayment() has been replaced with hasEnrolledInstrument() without changing its functionality.

The hasEnrolledInstrument() method has consensus from all major browsers. Chrome has implemented it in version 74 and both Webkit and Gecko have tracking bugs but have not yet implemented the method as of June 2019.

To use the new hasEnrolledInstrument() method, replace code that looks like this:

// Checking for instrument presence.
request.canMakePayment().then(handleInstrumentPresence).catch(handleError);

With code that looks like this:

// Checking for instrument presence.
if (request.hasEnrolledInstrument) {
  // hasEnrolledInstrument() is available.
  request.hasEnrolledInstrument().then(handleInstrumentPresence).catch(handleError);
} else {
  request.canMakePayment().then(handleInstrumentPresence).catch(handleError);
}

`canMakePayment()` no longer checks for instrument presence

Because hasEnrolledInstrument() now handles checking for the user's payment instrument, canMakePayment() has been updated to only check for payment app availability.

This change to canMakePayment() is bound to the implementation of hasEnrolledInstrument(). As of June 2019, it is implemented in Chrome 74 but not in any other browsers. Be sure to check if the hasEnrolledInstrument() method is available in the user's browser before attempting to use it.

// Checking for payment app availability without checking for instrument presence.
if (request.hasEnrolledInstrument) {
  // `canMakePayment()` behavior change corresponds to
  // `hasEnrolledInstrument()` availability.
  request.canMakePayment().then(handlePaymentAppAvailable).catch(handleError);
} else {
  console.log("Cannot check for payment app availability without checking for instrument presence.");
}

`languageCode` removed from `basic-card` payment method

PaymentAddress.languageCode has been removed from the shipping addresses and billing addresses for basic-card. The billing addresses of other payment methods (such as Google Pay) are not affected.

This change has been implemented in Chrome 74, Firefox, and Safari.

`PaymentRequest.show()` now takes an optional `detailsPromise`

PaymentRequest.show() allows a merchant to present a payment request UI before the final total is known. The merchant has ten seconds to resolve the detailsPromise before a timeout. This feature is intended for a quick server-side roundtrip.

This feature has shipped in Chrome 75 and Safari.

// Not implemented in Chrome 74 and older.
// There's no way to feature-detect this, so check a few
// older versions of Chrome that you're seeing hit your servers.
if (/Chrome\/((6[0-9])|(7[0-4]))/g.exec(navigator.userAgent) !== null) {
  return;
}

// Supported in Chrome 75+.
request.show(new Promise(function(resolveDetailsPromise, rejectDetailsPromise) {
  // Find out the exact total amount and call
  // `resolveDetailsPromise(details)`.
  // Use a 3 second timeout as an example.
  window.setTimeout(function() {
    resolveDetailsPromise(details);
  }, 3000); // 3 seconds.
}))
.then(handleResponse)
.catch(handleError);

`PaymentRequestEvent.changePaymentMethod()`

The Payment Handler API feature PaymentRequestEvent.changePaymentMethod() allows payment handlers (e.g., Google Pay) to trigger the onpaymentmethodchange event handler. changePaymentMethod() returns a promise that resolves to a merchant response with updated price information (e.g., tax recalculation).

Both PaymentRequestEvent.changePaymentMethod() and the paymentmethodchange event are available in Chrome 76 and Webkit has implemented the paymentmethodchange event in its Technology Preview.

// In service worker context, `self` is the global object.
self.addEventListener('paymentrequest', (evt) => {
  evt.respondWith(new Promise((confirmPaymentFunction, rejectPaymentFunction) => {
    if (evt.changePaymentMethod === undefined) {
      // Not implemented in this version of Chrome.
      return;
    }
    // Notify merchant that the user selected a different payment method.
    evt.changePaymentMethod('https://paymentapp.com', {country: 'US'})
    .then((responseFromMerchant) => {
      if (responseFromMerchant === null) {
        // Merchant ignored the 'paymentmethodchange' event.
        return;
      }
      handleResponseFromMerchant(responseFromMerchant);
    })
    .catch((error) => {
      handleError(error);
    });
  }));
});

Merchant example:

if (request.onpaymentmethodchange === undefined) {
  // Feature not available in this browser.
  return;
}

request.addEventListener('paymentmethodchange', (evt) => {
  evt.updateWith(updateDetailsBasedOnPaymentMethod(evt, paymentDetails));
});

Try it yourself! We've put together an example so you can experiment with this API.

Improved local development

Chrome 76 adds two small improvements for developer productivity. If your local development environment uses a self-signed certificate, you can now use the --ignore-certificate-errors command line flag to make Chrome allow Web Payments APIs in your development environment. If you develop using a local web server that does not support HTTPS, you can also use the --unsafely-treat-insecure-origin-as-secure=<origin> flag to make Chrome treat the HTTP origin as HTTPS.

How YouTube improved video performance with the Media Capabilities API

2019-06-11T17:00:00-07:00

In an experiment with the Media Capabilities API, YouTube saw a 7.1% increase in MTBR with only a 0.4% decrease in average resolution of videos served.

Key Term: MTBR (Mean Time Between Rebuffers) is total play time divided by the number of rebuffering events.

The Problem

Typically, media sites have several variants of each video that they can present to users, encoded in different frame rates, resolutions, and codecs. Until recently, web developers had to rely solely on isTypeSupported() or canPlayType() to determine whether each variant could be played in an individual user's browser. While this told the developer whether media could be played at all, it didn't provide an indication of playback quality, such as whether there would be frame drops or device battery drain. Without this information, developers either had to create their own heuristics or just assume that if a device could play a codec/resolution combination, it could do so smoothly and with power efficiency. For users with less capable devices, this often led to a poor experience.

The Solution

The Media Capabilities API allows websites to get more information about the client's video decode performance and make an informed decision about which codec and resolution to deliver to the user. Specifically, the API provides the developer with an estimate of the smoothness and power efficiency of a particular codec and resolution combination. This allows the developer to avoid scenarios where the client is likely to have a poor playback experience.

In Chrome, the Media Capabilities API uses metrics from previous playbacks to predict whether future playbacks in the same codec and at the same resolution will be smoothly decoded.

YouTube Case Study

YouTube used the Media Capabilities API to prevent their adaptive bitrate algorithm from automatically selecting resolutions that a device could not play smoothly.

Users who were part of the experimental group collectively saw less frequent rebuffers (the mean time between rebuffers, or MTBR, increased by 7.1%) while the average resolution, measured by video height, served to the aggregate group only declined by 0.4%. The substantial increase in the MTBR with the small corresponding reduction in average resolution indicates that this change significantly improved quality for a small subset of users who previously had a poor experience.

Implementing Media Capabilities API on your site

Check out the official sample to see how the Decoding Info API works.

How can performance improve conversion?

2019-06-10T17:00:00-07:00

In our other e-commerce guides you have learned about what you should measure to improve performance, and how to measure and report metrics to build a performance culture.

A conversion funnel.

In this guide we'll address the different ways in which a website should be optimized for performance to yield maximum conversions at the end of the funnel.

Discovery

New users discover a website in most cases through organic search, social sharing, website links or paid campaigns. Some important discovery mechanisms are directly affected by website performance. Website crawlers may have difficulty indexing sites that are slow to load or have extensive client side rendering and Javascript.

Speed can also be a direct ranking factor, for example on web search, ad campaigns or social networks. Keep in mind that new users who discover your website will get an uncached first load, so basically the worst possible experience. This can be especially frustrating if good money was spent to get the user to the website, just to see her dropping off due to a long first load.

Make sure to use appropriate tools as described in Fast Load Times to optimize towards a first load, because first impressions matter—if the first load is too slow, the user may never see the optimized second load or stay around to look at your products. In general loading times of a website map very well to bounce rates, which in turn often correlate well with conversions.

Engagement

After getting users to your site, you need to keep them engaged with your content, which you can verify in your analytics of choice by looking at session length, time-on-page, pages-per-session and general user flows.

A user flow through the funnel as seen by Google Analytics.

Besides various UX best practices, a smooth, fast and responsive experience is key here. While optimizing a website for discovery means optimizing for first load, optimizing for engagement means fast navigations and fast repeat loads. Analyze at which steps of the flow users drop out, and then relate back to speed metrics for these navigations. This can be analyzed for example via WebPageTest, Puppeteer or via the Chrome DevTools Record feature. We will show you more examples of those in the following guides.

Conversion

While website conversions are often bound to good discovery paired with great engagement, there are a couple of additional points to remember. Users expect hero images to load fast, call-to-action buttons should be rendered and labeled quickly, page should be responsive and layout jumps should be avoided. A user won't buy anything if she can't click the Buy Now button due to busy CPU or a jumping or unlabeled button. In general it's best to measure and track the time-to-action towards a conversion or a subgoal for it, for example the median time it takes shoppers to get from landing on your site, to viewing a product, to completing payment .

Re-Engagement

It turns out that only 2% of users convert on first visit, so it is important to get the other 98% to come back, and re-engage them with your content. Modern websites have different ways to do this, for example via mail, tailored display ads in remarketing or notifications. This works best if the flow from reengagement to website is as smooth as possible. Unfortunately this is not always the case, as for example mail apps often open links in their in-app webview, slowing down page load and complicating logins through different cache and cookie storage. Make sure to optimize for fast repeat loads and smooth UX flows to increase chances of reengagement.

Recap

E-commerce sites always strive for conversions, which are at the end of a purchase funnel. Every step along the funnel needs to be optimized for website speed to minimize bounce rates and drop-offs, and for each step there are different things to optimize, different pitfalls and culprits:

An e-commerce funnel showing which metric to optimize in which step.

To learn more, be sure to check out the other posts in this series on measuring to improve performance, and how report metrics to build a performance culture.

Hero image by Campaign Creators on Unsplash.

The Layout Instability API

2019-06-10T17:00:00-07:00

Have you ever been reading an article online when something suddenly changes on the page? Without warning, the text moves, and you've lost your place.

Or even worse: you're about to tap a link or a button, but in the instant before your finger lands—BOOM—the link moves, and you end up clicking something else!

Most of the time these kinds of experiences are just a mild annoyance or frustration. But in some cases, they can actually cause real damage or harm.

A screencast illustrating how layout instability can negatively affect users.

Unexpected movement of page content usually happens because resources are loaded asynchronously or DOM elements get dynamically added to the page above existing content. The culprit might be an image or video with unknown dimensions, a font that renders larger or smaller than its fallback, or a third-party ad or widget that dynamically resizes itself.

What makes this issue even more problematic is that how a site functions in development is often quite different from how users experience it in production: personalized or third-party content often doesn't behave the same in development as it does in production, test images are often already in the developer's browser cache, and API calls that run locally are often so fast that the delay isn't noticeable.

The first step toward properly solving this problem is to give developers the tools to measure it and understand how often it's occurring for real users. The Layout Instability API, currently being incubated in the WICG, aims to address this.

How is layout instability determined?

Layout Instability is determined by calculating a layout shift score every time the browser renders a new frame. Developers and analytics providers can then monitor these scores in the wild, identify the culprits, and improve the experience for their users.

Layout shift defined

For each element that's visible in the viewport, if the element's block-start and inline-start positions (e.g., its top and left position in the default writing mode) relative to its containing element has changed between the frame currently being rendered and the frame that was previously rendered, the element is identified as unstable.

The union of the visible areas of all unstable elements for the previous frame and the current frame—as a fraction of the total area of the viewport—is the layout shift score for the current frame.

Here are a few examples of how the layout shift score is calculated:

In the image above there's an element that takes up half of the viewport in one frame. Then, in the next frame, the element shifts down by 25% of the viewport height. The red, dotted rectangle indicates the union of the element's visible area in both frames, which, in this case, is 75% of the total viewport, so its layout shift score is 0.75.

The next example illustrates how adding content to an existing element affects the layout shift score:

Here the "Click Me!" button is appended to the bottom of the gray box with black text, which pushes the green box with white text down (and partially out of the viewport).

In this example, the gray box changes size, but its start position does not change so it's not an unstable element. The start position of the green box, however, does change, but since it's been moved partially out of the viewport, the invisible area is not considered when calculating the layout shift score. The union of the visible areas for the green box in both frames is the same as the area of the green box in the first frame, which is 50%, and its layout shift score is therefore 0.5 (as illustrated by the red, dotted rectangle).

This last example illustrates multiple unstable elements:

In the first frame above we have the initial results of an API request for animals, sorted in alphabetical order. In the second frame we have some more results that get added to the sorted list.

The first item in the list ("Cat") does not change its start position between frames, so it's stable. Similarly, the new items added to the list were not previously in the DOM, so their start positions don't change either. But the items labelled "Dog", "Horse", and "Zebra" all shift their start positions, so they're unstable elements.

Again, the red, dotted rectangles represent the union of these three unstable elements' before and after areas, which in this case represents around 38% of the viewport's area (a layout shift score of 0.38).

A key point that's hopefully clear from these examples is that layout shifts only occur when existing elements change their start position. If a new element is added to the DOM or an existing element changes size, it doesn't count as a layout shift—as long as the change doesn't cause other visible elements to change their start position.

Expected vs unexpected layout shifts

Not all layout shifts are bad. In fact, many dynamic web applications will frequently change the start position of elements on the page.

User-initiated layout shifts

A layout shift is only bad if the user isn't expecting it. On the other hand, layout shifts that occur in response to user interactions (e.g., clicking a link, pressing a button, typing in a search box, etc.) are generally fine, as long as the shift occurs close enough to the interaction that the relationship is clear to the user.

For example, if a user interaction triggers a network request that may take a while to complete, it's best to create some space right away and show a loading indicator to avoid an unpleasant layout shift when the request completes. If the user doesn't realize something is loading, or doesn't have a sense of when the resource will be ready, they may try to click something else while waiting—something that could move out from under them.

Animations and transitions

Animations and transitions, when done well, are a great way to update content on the page without surprising the user. Content that shifts abruptly and unexpectedly on the page almost always creates a bad user experience. But content that moves gradually and naturally from one position to the next can often help the user better understand what's going on, and guide them between state changes.

To ensure that effective uses of animations and transitions do not produce negative layout shift scores in the Layout Instability API, elements whose start position has changed by less than three pixels since the previous frame are not considered unstable elements.

A cumulative layout shift score

Layout shift scores are calculated per-frame, and they are reported regardless of whether the shift was triggered as a result of user input.

But users can experience layout instability throughout their entire browser session, and as I mentioned above, not all layout shifts are perceived negatively.

The cumulative layout shift (CLS) score is determined by calculating the sum of all unexpected layout shift scores from page load until the page's lifecycle state changes to hidden. In the current Chrome implementation, "unexpected layout shifts" are those that don't occur within 500 milliseconds of a discrete user interaction (i.e., click, taps, and key presses, but not scrolls or mouse moves)

A page that has no unexpected layout shifts will have a cumulative layout shift score of 0. Most typical content sites and web applications should strive for a score of 0 to provide the best experience for their users.

In addition, the cumulative layout shift score has been added as an experimental metric in the Chrome User Experience Report (CrUX), a dataset that captures how real-world Chrome users experience popular destinations on the web. With the addition of CLS as of the May 2019 release, developers can get a better understanding of how users experience layout instability on their sites, on their competitors' sites, and on the web as a whole.

Important: while most sites should strive for a CLS score of 0, it's certainly possible that some sites employ layout shifts deliberately (for example, in multimedia presentations, progressive visualisations, slideshows, etc.).

This is perfectly fine. CLS scores are intended to help developers who may not be aware of the problems caused by unexpected layout shifts; they're not intended to suggest that sites that deliberately shift the layout are necessarily problematic.

How to use the Layout Instability API

The Layout Instability API is available in Chrome 74+ with the experimental web platform features flag enabled (chrome://flags/#enable-experimental-web-platform-features) or by through the Layout Instability Origin Trial, which will be available until Sept. 3, 2019.

Similar to other performance APIs, Layout Instability can be observed via the PerformanceObserver interface, where you can subscribe to entries of type layout-shift.

The following code logs all layout shift entries as they happen:

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    console.log(entry);
  }
})

observer.observe({type: 'layout-shift', buffered: true});

Note: The buffered flag in the above example (supported in Chrome 77+) gives you access to entries that may have occurred prior to creating the PerformanceObserver.

Caution: The entryType value for this API has changed a few times during the experimentation period. In Chrome 76 it was layoutShift, and in Chrome 74-75 it was layoutJank. Developers implementing the stable API should only need to observe the current layout-shift value (as shown in the example above), but developers who are part of the origin trial may need to observe multiple entry types to cover their full user base. See this demo for an example of code that works in Chrome 74+.

If you want to calculate the cumulative layout shift score for your pages and track them in your analytics back end, you can declare a variable that stores the current cumulative layout shift score, and then increment it any time a new layout shift is detected. You'll typically want to record scores from the initial page load until the page's lifecycle state changes to hidden:

// Stores the current layout shift score for the page.
let cumulativeLayoutShiftScore = 0;

// Detects new layout shift occurrences and updates the
// `cumulativeLayoutShiftScore` variable.
const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    // Only count layout shifts without recent user input.
    if (!entry.hadRecentInput) {
      cumulativeLayoutShiftScore += entry.value;
    }
  }
});

observer.observe({type: 'layout-shift', buffered: true});

// Sends the final score to your analytics back end once
// the page's lifecycle state becomes hidden.
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    // Force any pending records to be dispatched.
    observer.takeRecords();

    // Send the final score to your analytics back end
    // (assumes `sendToAnalytics` is defined elsewhere).
    sendToAnalytics({cumulativeLayoutShiftScore});
  }
});

How to avoid unexpected layout shifts

For most websites, you can avoid all unexpected layout shifts by sticking to a few guiding principles:

Always include size attributes on your images and video elements, or otherwise reserve the required space with something like CSS aspect ratio boxes.
This approach ensures that the browser can allocate the correct amount of space in the document while the image is loading. Note that you can also use the unsized-media feature policy to force this behavior in browsers that support feature policies. And in the future you'll be able to use the intrinsicSize attribute to more easily address this issue.
Never insert content above existing content, except in response to a user interaction.
This ensures any layout shifts that occur are expected.
When layout shifts are necessary, use transitions or animation to provide context and continuity to the user.
This creates continuity from state to state that's easier for users to follow.

Feedback wanted

The Layout Instability API is being incubated in the WICG, and this is the time feedback from the developer community is the most helpful—specifically feedback on how well the API works on real websites and with the actual development techniques used today.

Are there any false positives (good experiences reported as unexpected layout shifts)?
Are there any false negatives (clear examples of layout instability not being reported)?
Are the scores meaningful and the data actionable?

You can give feedback by opening up an issue on the Layout Instability Spec's GitHub repo, or by contributing to the discussion already happening there.

Also, if your site is available in the CrUX dataset, you can query to see how real Chrome users are experiencing the stability of your site's layout, and you can compare these results to the results you're seeing when testing your site locally. If the results you see in CrUX are unexpected, you can sign up for the Layout Instability Origin Trial and monitor your user's experience via the JavaScript API.

As I mentioned in the introduction of this post. The first step toward properly solving layout instability is to measure it and understand how often it occurs for real users.

Making JavaScript and Google Search work together

2019-06-04T17:00:00-07:00

Great things are happening with Google Search, and we were excited to share them at Google I/O 2019!

In this post we'll focus on best practices for making JavaScript web apps discoverable in Google Search, including:

The new evergreen Googlebot
Googlebot's pipeline for crawling, rendering and indexing
Feature detection and error handling
Rendering strategies
Testing tools for your website in Google Search
Common challenges and possible solutions
Best practices for SEO in JavaScript web apps

Meet the evergreen Googlebot

This year we announced the much-awaited new evergreen Googlebot.

Googlebot is now running a modern Chromium rendering engine.

Googlebot now uses a modern Chromium engine to render websites for Google Search. On top of that, we will test newer versions of Chromium to keep Googlebot updated, usually within a few weeks of each stable Chrome release. This announcement is big news for web developers and SEOs because it marks the arrival of 1000+ new features—such as ES6+, IntersectionObserver, and Web Components v1—in Googlebot.

Learn how Googlebot works

Googlebot is a pipeline with several components. Let's take a look to understand how Googlebot indexes pages for Google Search.

Googlebot's pipeline for crawling, rendering, and indexing a page.

The process works like this:

Googlebot queues URLs for crawling.
It then fetches the URLs with an HTTP request based on the crawl budget.
Googlebot scans the HTML for links and queues the discovered links for crawling.
Googlebot then queues the page for rendering.
As soon as possible, a headless Chromium instance renders the page, which includes JavaScript execution.
Googlebot uses the rendered HTML to index the page.

Your technical setup can influence the process of crawling, rendering, and indexing. For example, slow response times or server errors can impact the crawl budget. Another example would be requiring JavaScript to render the links can lead to a slower discovery of these links.

Use feature detection and handle errors

The evergreen Googlebot has lots of new features, but some features are still not supported. Relying on unsupported features or not handling errors properly can mean Googlebot can't render or index your content.

Let's look at an example:

 <body>
   <script>
     navigator.geolocation.getCurrentPosition(function onSuccess(position) {
       loadLocalContent(position);
     });
   </script>
 </body>

This page might not show any content in some cases because the code doesn't handle when the user declines the permission or when getCurrentPosition call returns an error. Googlebot declines permission requests like this by default.

This is a better solution:

 <body>
   <script>
     if (navigator.geolocation) {
       // this browser supports the Geolocation API, request location!
       navigator.geolocation.getCurrentPosition(
         function onSuccess(position) {
           // we successfully got the location, show local content
           loadLocalContent(position);
         }, function onError() {
           // we failed to get the location, show fallback content
           loadGlobalContent();
         });
     } else {
       // this browser does not support the Geolocation API, show fallback content
       loadGlobalContent();
     }
   </script>
 </body>

If you have problems with getting your JavaScript site indexed, walk through our troubleshooting guide to find solutions.

Choose the right rendering strategy for your web app

The default rendering strategy for single-page apps today is client-side rendering. The HTML loads the JavaScript, which then generates the content in the browser as it executes.

Let's look at a web app that shows a collection of cat images and uses JavaScript to render entirely in the browser.

The rendering strategy influences the performance and robustness of your web apps.

If you're free to choose your rendering strategy, consider server-side rendering or pre-rendering. They execute JavaScript on the server to generate the initial HTML content, which can improve performance for both users and crawlers. These strategies allow the browser to start rendering HTML as it arrives over the network, making the page load faster. The rendering session at I/O or the blog post about rendering on the web shows how server-side rendering and hydration can improve the performance and user experience of web apps and provides more code examples for these strategies.

If you're looking for a workaround to help crawlers that don't execute JavaScript—or if you can't make changes to your frontend codebase—consider dynamic rendering, which you can try out in this codelab. Note, though, that you won't get the user experience or performance benefits that you would with server-side rendering or pre-rendering because dynamic rendering only serves static HTML to crawlers. That makes it a stop-gap rather than a long-term strategy.

Test your pages

While most pages generally work fine with Googlebot, we recommend testing your pages regularly to make sure your content is available to Googlebot and there are no problems. There are several great tools to help you do that.

The easiest way to do a quick check of a page is the Mobile-Friendly Test. Besides showing you issues with mobile-friendliness, it also gives you a screenshot of the above-the-fold content and the rendered HTML as Googlebot sees it.

The mobile-friendly test shows you the rendered HTML Googlebot uses.

You can also find out if there are resource loading issues or JavaScript errors.

It's recommended to verify your domain in Google Search Console so you can use the URL inspection tool to find out more about the crawling and indexing state of a URL, receive messages when Search Console detects issues and find out more details of how your site performs in Google Search.

The URL Inspection Tool in Search Console shows the status of a page in crawling, rendering, and indexing.

For general SEO tips and guidance, you can use the SEO audits in Lighthouse. To integrate SEO audits into your testing suite, use the Lighthouse CLI or the Lighthouse CI bot.

Lighthouse shows general SEO recommendations for a page.

These tools help you identify, debug, and fix issues with pages in Google Search and should be part of your development routine.

Stay up to date and get in touch

To stay up to date with announcements and changes to Google Search, keep an eye on our Webmasters Blog, the Google Webmasters Youtube channel, and our Twitter account. Also check out our developer guide to Google Search and our JavaScript SEO video series to learn more about SEO and JavaScript.

Service worker mindset

2019-06-03T17:00:00-07:00

Service workers are powerful and absolutely worth mastering. They let you deliver an entirely new level of experience to your users. Your site can load instantly. It can work offline. It can be installed as a native app and feel every bit as polished—but with the reach and freedom of the web.

But service workers are unlike anything most of us web devs are used to. They come with a steep learning curve and a handful of snags you've got to watch out for.

Google Developers and I recently collaborated on a project—Service Workies—a free game for mastering service workers. While building it and working with the complex ins and outs of service workers, I ran into a few snags. What helped me the most was coming up with a handful of depictive metaphors. In this post we'll explore these mental models and wrap our brains around the paradoxical traits that make service workers both tricky and awesome.

The same, but different

While coding your service worker, many things will feel familiar. You get to use your favorite new JavaScript language features. You listen to lifecycle events just like with UI events. You manage control flow with promises like you're used to.

But other service worker behavior causes you to scratch your head in confusion. Especially when you refresh the page and don't see your code changes applied.

A new layer

Normally when building a site you have just two layers to think about: the client and the server. The service worker is a brand new layer that sits in the middle.

Think of your service worker as a sort of browser extension—one that your site can install in your user's browser. Once installed, the service worker extends the browser for your site with a powerful middle layer. This service worker layer can intercept and handle all of the requests your site makes.

The service worker layer has its own lifecycle independent of the browser tab. A simple page refresh isn't enough to update a service worker—just like you wouldn't expect a page refresh to update code deployed on a server. Each layer has its own unique rules for updating.

In the Service Workies game we cover the many details of the service worker lifecycle and give you a ton of practice working with it.

Think of your service worker as a new middle layer with its own lifecycle and methods for updating.

Powerful, but limited

Having a service worker on your site gives you incredible benefits. Your site can:

work flawlessly even when the user is offline
gain massive performance improvements through caching
use push notifications
be installed as a PWA

With as much as service workers can do, they are limited by design. They can't do anything synchronous or in the same thread as your site. So that means no access to:

localStorage
the DOM
the window

The good news is there are a handful of ways your page can communicate with its service worker, including direct postMessage, one-to-one Message Channels and one-to-many Broadcast Channels.

Think of your service worker as something that lives outside of your page. You can talk to it, but it can't access your page directly.

Long-lived, but short-lived

An active service worker goes on living even after a user leaves your site or closes the tab. The browser keeps this service worker around so that it will be ready the next time the user comes back to your site. Before the very first request is made, the service worker gets a chance to intercept it and take control of the page. This is what allows a site to work offline—the service worker can serve a cached version of the page itself, even if the user has no connection to the internet.

In Service Workies we visualize this concept with Kolohe (a friendly service worker) intercepting and handling requests.

Stopped

Despite service workers appearing to be immortal, they can be stopped at almost any time. The browser doesn't want to waste resources on a service worker that isn't currently doing anything. Getting stopped isn't the same thing as getting terminated—the service worker remains installed and activated. It's just put to sleep. The next time it's needed (e.g., to handle a request), the browser wakes it back up.

waitUntil

Because of the constant possibility of getting put to sleep, your service worker needs a way to let the browser know when it's doing something important and doesn't feel like taking a nap. This is where event.waitUntil() comes into play. This method extends the lifecycle it's used in, keeping it both from being stopped and from moving on to the next phase of its lifecycle until we're ready. This gives us time to setup caches, fetch resources from the network, etc.

This example tells the browser that our service worker isn't done installing until the assets cache has been created and populated with the picture of a sword:

self.addEventListener("install", event => {
  event.waitUntil(
    caches.open("assets").then(cache => {
      return cache.addAll(["/weapons/sword/blade.png"]);
    })
  );
});

Watch out for global state

When this start/stop happens the service worker's global scope is reset. So be careful not to use any global state in your service worker or you'll be sad the next time it wakes back up and has different state from what it was expecting.

Consider this example that uses a global state:

const favoriteNumber = Math.random();
let hasHandledARequest = false;

self.addEventListener("fetch", event => {
  console.log(favoriteNumber);
  console.log(hasHandledARequest);
  hasHandledARequest = true;
});

On each request this service worker will log a number—let's say 0.13981866382421893. The hasHandledARequest variable also changes to true. Now the service worker sits idle for a bit, so the browser stops it. The next time there's a request, the service worker is needed again, so the browser wakes it up. Its script is evaluated again. Now hasHandledARequest is reset to false, and favoriteNumber is something completely different—0.5907281835659033.

You can't rely on stored state in a service worker. Also, creating instances of things like Message Channels can cause bugs: you'll get a brand new instance every time the service worker stops/starts.

Warning: This snag is especially important to keep in mind while working on your service worker code because when Chrome DevTools is open, the start/stop behavior is disabled. You may not even see bugs caused by relying on global state until they've shipped to your users.

In Service Workies chapter 3 we visualize our stopped service worker as losing all color while he hangs out waiting to be woken up.

Think of your service worker as a whippet dog. He's fast, loyal and awesome. He'll stick around by your side no matter what. But mostly he just wants to sleep. All the time. You've got to let him know when you want him to stay awake. Good boy!

Together, but separate

Your page can only be controlled by one service worker at a time. But it can have two service workers installed at once. When you make a change to your service worker code and refresh the page, you aren't actually editing your service worker at all. Service workers are immutable. You're instead making a brand new one. This new service worker (let's call it SW2) will install but it won't activate yet. It has to wait for the current service worker (SW1) to terminate (when your user leaves your site).

Messing with another service worker's caches

While installing, SW2 can get things setup—usually creating and populating caches. But heads up: this new service worker has access to everything that the current service worker has access to. If you're not careful, your new waiting service worker can really mess things up for your current service worker. Some examples that could cause you trouble:

SW2 could delete a cache that SW1 is actively using.
SW2 could edit the contents of a cache that SW1 is using, causing SW1 to respond with assets that the page isn't expecting.

Skip skipWaiting

A service worker can also use the risky skipWaiting() method to take control of the page as soon as it's done installing. This is generally a bad idea unless you're intentionally trying to replace a buggy service worker. The new service worker might be using updated resources that the current page isn't expecting, leading to errors and bugs.

Start clean

The way to prevent your service workers from clobbering each other is to make sure they use different caches. The easiest way to accomplish that is to version the cache names they use.

const version = 1;
const assetCacheName = `assets-${version}`;

self.addEventListener("install", event => {
  caches.open(assetCacheName).then(cache => {
    // confidently do stuff with your very own cache
  });
});

When you deploy a new service worker, you'll bump the version so that it does what it needs with an entirely separate cache from the previous service worker.

End clean

Once your service worker reaches the activated state, you know it has taken over, and the previous service worker is redundant (i.e., no longer needed). At this point it's important to clean up after the old service worker. Not only does it respect your users' cache storage limits, but it can also prevent unintentional bugs.

The caches.match() method is an often-used shortcut for retrieving an item from any cache where there's a match. But it iterates through the caches in the order they were created. So let's say you've got two versions of a script file app.js hanging out in two different caches—assets-1 and assets-2. Your page is expecting the newer script that's stored in assets-2. But if you haven't deleted the old cache, caches.match('app.js') is going to return the old one from assets-1 and most likely break your site.

All it takes to clean up after previous service workers is to delete any cache that the new service worker doesn't need:

const version = 2;
const assetCacheName = `assets-${version}`;

self.addEventListener("activate", event => {
  event.waitUntil(
    caches.keys().then(cacheNames => {
      return Promise.all(
        cacheNames.map(cacheName => {
          if (cacheName !== assetCacheName){
            return caches.delete(cacheName);
          }
        });
      );
    });
  );
});

Preventing your service workers from clobbering each other takes a bit of work and disciple but is worth the trouble.

Think of the combination of your service worker and your site as an installable app. Each version should work. Each version should be separate from the others. Imagine how buggy a game would be if the developer accidentally released a patch that used new game logic but outdated assets. You'd rage on the forums so fast! Keep your app versions tidy & clean.

Service worker mindset

Getting into the right mindset while thinking about service workers will help you build yours with confidence. Once you get the hang of them you'll be able to create incredible experiences for your users.

If you want to master all this by playing a game, then you're in luck! Go play Service Workies where you'll learn the ways of the service worker in order to slay the offline beasts.

What should you measure to improve performance?

2019-05-30T17:00:00-07:00

The different steps of a purchase funnel are prone to performance issues in different ways, and therefore need different measurement and optimizations:

A conversion funnel.

In this guide we'll address how the different steps can be measured. For this we recommend you to look at lab as well as field data.

Lab data is gathered by running tests locally, for example by using Lighthouse and other tools. This can make it possible to compare website performance over time and with competitors through a controlled, stable environment, but it might not be representative of the performance users experience in real life.

Field data is gathered via analytics from real users, and is therefore representative of their experience. However, it can't easily be compared over time or with competitors. Network connections and smartphone hardware evolve over time, and different target audiences might have different devices, thereby making comparisons with field data tough. See also Measure Performance In The Field.

To get a complete picture, both data sources are needed. The following sections show how to gather lab and field data for the different relevant performance marks across the funnel.

Discovery

Optimizing for discovery means optimizing for the first load, which is what new users will get, but also search and social crawlers. Lab data for a first load can be easily acquired through Lighthouse, while field data (at least for Chrome) is readily available through Chrome UX reports. A convenient combination of both can be found in PageSpeed Insights. You should also track relevant metrics from the field yourself: Measuring these metrics on real users' devices provides a good overview.

From a user perspective the most important metrics are:

First Contentful Paint (FCP): The time the user stares at a blank screen. This is when most users bounce, as they don't see progress.
First Meaningful Paint (FMP): When the user begins to see the main content they came for. This is often the hero image, but for a landing page it may even be a call to action such as a Buy button, since the user may have arrived with a clear intent (for example, through a targeted ad campaign).
First Input Delay (FID): The time the website needs to react to the user's first input. Excessive JavaScript and other asset loading problems can block this, leading to failed taps or clicks, erroneous inputs and page abandonment.

There are more metrics you can look at, but these are a good baseline. Additionally also make sure to capture bounce rates, conversions and user engagement so that you can set these in relation.

Engagement And Conversion

After the first load of a landing page, a user will proceed through your site, hopefully towards a successful conversion.

In this phase it is important to have fast and responsive navigations and interactions. Unfortunately it is not trivial to measure the complete flow of navigation and interaction events in the field, as every user takes different paths through the page. We therefore recommend measuring the time needed towards conversion or conversion subgoals ("Time-to-Action") by scripting and measuring the flow in a lab test, to compare performance over time or with competitors.

There are two convenient ways of doing this:

WebPageTest

WebPageTest offers a very flexible scripting solution. The basic idea is to:

Tell WebPageTest to navigate through the pages of the flow with the navigate command.
If needed script the clicking of buttons via clickAndWait commands and fill text fields via setValue. For testing of Single Page Applications use clickAndWait rather than navigate commands for all steps after the first, as navigate will do a full load instead of the lightweight virtual page load.
Make sure to combine the different steps of the flow in the analysis via combineSteps to produce a single overall result report for the complete flow.

Such a script could look like this:

combineSteps
navigate	https://www.store.google.com/landingpage
navigate	https://www.store.google.com/productpage
clickAndWait	innerText=Buy Now
navigate	https://www.store.google.com/basket
navigate	https://www.store.google.com/checkout

With a script like this in place you can easily measure and compare performance over time. This can even be automated through the WebPageTest API.

Puppeteer

Another great option to script testing is via headless Chrome, which can be controlled through the Node API Puppeteer. The general idea is to start the browser through Puppeteer, navigate to the landing page through the goto function, inject Javascript to fill fields or click buttons and proceed through the funnel through further goto calls as needed.

As a metric the duration of the flow can be measured directly, but you could also sum up the FCP, FMP or TTI values of the individual loads of the flow. Test website performance with Puppeteer provides an overview of how to get performance metrics via Puppeteer. A very simplified example Node script could look like this:

const puppeteer = require('puppeteer');
(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  const start = performance.now();
  await page.goto('https://www.store.google.com/landingpage');
  await page.goto('https://www.store.google.com/productpage');
  // click the buy button, which triggers overlay basket
  await page.click('#buy_btn');
  // wait until basket overlay is shown
  await page.waitFor('#close_btn');
  await page.goto('https://www.store.google.com/basket');
  await page.goto('https://www.store.google.com/checkout');
  console.log('Flow took ' + parseInt((performance.now() - start)/1000) + ' seconds');
  await browser.close();
})();

This script can easily be automated, and even be made part of the build process or perf budgets, and be monitored regularly.

Re-Engagement

Users will return to your site in different time intervals. Depending on time passed, the browser may have less of the website's resources cached, needing more network requests. This makes it difficult to estimate performance differences across repeat visits in lab tests. It is still recommended to keep an eye on this though, and a great lab test tool for repeat visits is WebPageTest, which has a dedicated option for a direct repeat visit:

Webpagetest offers options to test first load and repeat load as well

To get a better feeling for repeat visit performance in the field use your analytics package of choice to segment your performance metrics by user type. Here is an example of such a report in Google Analytics:

A Google Analytics custom report can be used to report speed metrics for new and returning users.

A report like this will give you page load times for new and returning users as well.

Recap

This guide showed you how to measure first load, flow and repeat load via field and lab tests. Make sure to optimize the different steps of the funnel accordingly to maximize discovery (first load), engagement (navigations and flow) and re-engagement (repeat load).

Image policies for fast load times and more

2019-05-30T17:00:00-07:00

Images often take up a significant amount of visual space and make up the majority of the downloaded bytes on a website. Optimizing images can improve loading performance and reduce network traffic.

Surprisingly, more than half of the sites on the web are serving poorly compressed or unnecessarily large images. This leaves a lot of room for performance improvements simply by optimizing the images.

You may ask, how do I know if my images are optimized and how should I optimize them? We are experimenting with a new set of feature policies for image optimization: oversized-images, unoptimized-lossy-images, unoptimized-lossless-images, andunoptimized-lossless-images-strict. All are now available for origin trials.

Optimized image policies

Feature policy is introducing a new set restrictions on images that can be applied with development-time enforcement. Images violating any of the restrictions will be rendered as placeholder images, which are easy to identify and fix. These policies can be specified in report-only mode where images will render normally without enforcement while violations are being observed via reports. (See Report-only mode in the wild, below for details.)

oversized-images

The oversized-images feature policy restricts the intrinsic dimensions of an image in relation to its container size.

When a document uses the oversized-images policy, any <img> element whose intrinsic resolution is more than X times larger than the container size in either dimension will be replaced with a placeholder image.

Why?

Serving images larger than what the viewing device can render—for example, serving desktop images to mobile contexts, or serving high-pixel-density images to a low-pixel-density device—is wasting network traffic and device memory. Read Serve images with correct dimensions and Serve responsive images for information on optimizing your images.

Examples

A few examples illustrate this. The following shows the default behavior when cutting an image's display size in half.

The default resizing behavior.

If I apply the following feature policy, I get a placeholder image instead.

Feature-Policy: oversized-images *(2);

When the image is too large for the container.

I get similar results if I lower only the width or the height.

Resize width and height.

How to use

To summarize, oversized-images policy can be specified through either:

Feature-Policy HTTP header
<iframe> allow attribute

To declare the oversized-images policy, you need to provide:

The feature name, oversized-images (Required)
A list of origins (Optional)
The threshold values (i.e., the downscaling ratio X) for the origins, specified in parenthesis (Optional)

We recommend a downscaling ratio of 2.0 or lower. Consider using responsive images with different resolutions to best serve images on various screen sizes, resolutions, and so on.

More examples

Feature-Policy: oversized-images *(2.0)

The policy is enforced on all origins with a threshold value of 2.0. Any <img> element with an image whose downscaling ratio that is greater than 2.0 is disallowed and will be replaced with a placeholder image.

Feature-Policy: oversized-images *(inf) 'self'(1.5)

The policy is enforced on the site's origin with a threshold value of 1.5. <img> elements in top-level browsing contexts and same origin nested browsing contexts will only render normally if the downscaling ratio is less than or equal to 1.5. <img> elements everywhere else will render normally.

unoptimized-{lossy,lossless}-images

The unoptimized-lossy-images, unoptimized-lossless-images, unoptimized-lossless-images-strict feature policies restrict the file size of an image in relation to its intrinsic resolution:

unoptimized-lossy-images: Lossy formats should not exceed a byte-per-pixel ratio of X, with a fixed 1KB overhead allowance. For a W x H image, the file size threshold is calculated as W x H x X + 1024.
unoptimized-lossless-images: Lossless formats should not exceed a byte-per-pixel ratio of X, with a fixed 10KB overhead allowance. For a W x H image, the file size threshold is calculated as W x H x X + 10240.
unoptimized-lossless-images-strict: Lossless formats should not exceed a byte-per-pixel ratio of X, with a fixed 1KB overhead allowance. For a W x H image, the file size threshold is calculated as W x H x X + 1024.

When a document uses any of these policies, any <img> element violating the constraint will be replaced with a placeholder image.

Why?

The larger the download size is, the longer it takes for an image to load. The file size should be kept as small as possible when optimizing an image: stripping metadata, picking a good image format, using image compression, and so on. Read Use Imagemin to compress images and Use WebP images for information on optimizing your images.

Example

The following shows the default browser behavior. Without the feature policy an unoptimized lossy image can be displayed just the same as an optimized image.

Comparing an optimized image with an unoptimized image.

If I apply the following feature policy, I get a placeholder image instead.

Feature-Policy: unoptimized-lossy-images *(0.5);

When the image is not optimized.

How to use

If you are new to feature policy, please check out Introduction to Feature Policy for more details.

To summarize, unoptimized-{lossy,lossless}-images policies can be either specified through:

Feature-Policy HTTP header
<iframe> allow attribute

To declare an unoptimized-{lossy,lossless}-images policy, you will need to provide:

The feature name, for example, unoptimized-lossy-images (Required)
A list of origins (Optional)
The threshold values (i.e., byte-per-pixel ratio X) for the origins, specified in parenthesis (Optional)

We recommend a byte-per-pixel ratio of 0.5 or lower for unoptimized-lossy-images and a byte-per-pixel ratio of 1 or lower for unoptimized-lossless-images and unoptimized-lossless-images-strict.

WebP formats have better compression ratios than other formats. Serve all your images in WebP lossy format if you can. If that is not sufficient, try WebP lossless format. Use JPEG on browsers that don't support WebP formats. Use PNG if none of thes formats work.

If you are using WebP formats, try with stricter thresholds:

0.2 for WEBPV8
0.5 for WEBPL

More examples

Feature-Policy:  unoptimized-lossy-images *(0.5);
                 unoptimized-lossless-images *(1.0);
                 unoptimized-lossless-images-strict *(1.0);

This policy is enforced on all origins with a threshold value of 0.5 (for lossy formats) and 1 (for lossless formats). Any <img> element whose image has a byte-per-pixel ratio exceeding the constraint is disallowed and will be replaced with a placeholder image.

Feature-Policy: unoptimized-lossy-images *(inf) 'self'(0.3);
                unoptimized-lossless-images *(inf) 'self'(0.8);
                unoptimized-lossless-images-strict *(inf) 'self'(0.8);

This policy is enforced on the site's origin with a threshold value of 0.3 (for lossy formats) and 0.8 (for lossless formats). The <img> elements in top-level browsing contexts and same origin nested browsing contexts will only render normally if the byte-per-pixel ratio meets these constraints. The <img> elements everywhere else will render normally.

Report-only mode in the wild

Publishing a site with placeholder images may not be what you want. You can use the policies in enforcement mode (with unoptimized images rendered as placeholder images) during development and staging, and use report-only mode in production. (Check out Feature Policy Reporting for more details.) Similar to Feature-Policy HTTP header, the Feature-Policy-Report-Only header lets you observe violation reports in the wild without any enforcement.

Limitations

Image policies only work on HTML image elements (<img>, <source>, etc.) and are not yet supported on background images or generated content. If you would like to have policies supported on broader contents, please let us know.

Optimizing your images

I've talked quite a bit about optimizing your images, but haven't said how to do it. That topic is out of scope for this article, but you can learn more from the links below and from the codelabs listed at the end of the article.

Experiment with the policies in origin trials

Image policies are available in Chrome 75 via an origin trial.

To participate:

request a token
Add the token on any pages in your origin using an Origin-Trial HTTP header:

Origin-Trial: **token as provided in the developer console**
Specify an image policy via HTTP header Feature-Policy header:

Feature-Policy: **image policies specified here**

Check out Origin Trials Guide for Web Developers for more details.

Please give us feedback

Hopefully this article has given you a good understanding of the image policies and gotten you excited. We'd really love for you to try out the policies and give us feedback.

You can give us feedback for each of the features mentioned in this article to our mailing list: feature-control@chromium.org.

We would love to know what threshold values you used and found useful. We would love to know whether unoptimized-lossless-images or unoptimized-lossless-images-strict is more intuitive and easy to use, or if we should use a difference overhead allowance instead. We will be sending out a survey near the end of the trial. Stay tuned!

Extract critical CSS

2019-05-28T17:00:00-07:00

The browser must download and parse CSS files before it can show the page, which makes CSS a render-blocking resource. If CSS files are big, or network conditions are poor, requests for CSS files can significantly increase the time it takes for a web page to render.

Key Term: Critical CSS is a technique that extracts the CSS for above-the-fold content in order to render content to the user as fast as possible.

Above-the-fold is all the content a viewer sees on page load, before scrolling. There is no universally defined pixel height of what is considered above the fold content since there is a myriad of devices and screen sizes.

Inlining extracted styles in the <head> of the HTML document eliminates the need to make an additional request to fetch these styles. The remainder of the CSS can be loaded asynchronously.

Inlined critical CSS

Improving render times can make a huge difference in perceived performance, especially under poor network conditions. On mobile networks, high latency is an issue regardless of bandwidth.

Comparison of loading a page with render-blocking CSS (top) and the same page with inlined critical CSS (bottom) on a 3G connection

If you have poor First Contentful Paint (FCP) and see "Eliminate render-blocking resource" opportunity in Lighthouse audits it's a good idea to give critical CSS a go.

Gotchas!

Keep in mind that if you inline a large amount of CSS, it delays the transmission of the rest of the HTML document. If everything is prioritized then nothing is. Inlining also has some downsides in that it prevents the browser from caching the CSS for reuse on subsequent page loads, so it's best to use it sparingly.

To minimize the number of roundtrips to first render, aim to keep above-the-fold content under 14 KB (compressed).

New TCP connections cannot immediately use the full available bandwidth between the client and the server, they all go through slow-start to avoid overloading the connection with more data than it can carry. In this process, the server starts the transfer with a small amount of data and if it reaches the client in perfect condition, doubles the amount in the next roundtrip. For most servers, 10 packets or approximately 14 KB is the maximum that can be transferred in the first roundtrip.

The performance impact you can achieve with this technique depends on the type of your website. Generally speaking, the more CSS a site has, the greater the possible impact of inlined CSS.

Overview of tools

There are a number of great tools that can automatically determine the critical CSS for a page. This is good news because doing this manually would be a tedious process. It requires analysis of the entire DOM to determine the styles that are applied to each element in the viewport.

Critical

Critical extracts, minifies and inlines above-the-fold CSS and is available as npm module. It can be used with Gulp (directly) or with Grunt (as a plugin) and there's a webpack plugin too.

It's a simple tool that takes a lot of thinking out of the process. You don't even have to specify the stylesheets, Critical automatically detects them. It also supports extracting critical CSS for multiple screen resolutions.

criticalCSS

CriticalCSS is another npm module that extracts above-the-fold CSS. It is also available as a CLI.

It doesn't have options to inline and minify critical CSS, but it does let you force-include rules that don't actually belong in critical CSS and gives you more granular control over including @font-face declarations.

Penthouse

Penthouse is a good choice if your site or app has a large number of styles or styles which are being dynamically injected into the DOM (common in Angular apps). It uses Puppeteer under the hood and even features an online hosted version too.

Penthouse doesn't detect stylesheets automatically, you have to specify the HTML and CSS files that you want to generate critical CSS for. The upside is that it's good at running many jobs in parallel.

Are long JavaScript tasks delaying your Time to Interactive?

2019-05-28T17:00:00-07:00

tl;dr: Long Tasks can keep the main thread busy, delaying user interaction. Chrome DevTools can now visualize Long Tasks, making it easier to see tasks to optimize.

If you use Lighthouse to audit your pages, you may be familiar with Time to Interactive, a metric representing when users can interact with your page and get a response. But did you know Long (JavaScript) Tasks can contribute heavily to a poor TTI?

What are Long Tasks?

A Long Task is JavaScript code that monopolizes the main thread for extended periods of time, causing the UI to "freeze".

While a web page is loading, Long Tasks can tie up the main thread and make the page unresponsive to user input even if it looks ready. Clicks and taps often don't work because event listeners, click handlers etc have not yet been attached.

CPU-heavy Long Tasks occur due to complex work that takes longer than 50ms. Why 50ms? The RAIL model suggests you process user input events in 50ms to ensure a visible response within 100ms. If you don't, the connection between action and reaction is broken.

Are there Long Tasks in my page that could delay interactivity?

Until now, you've needed to manually look for "long yellow blocks" of script over 50ms long in Chrome DevTools or use the Long Tasks API to figure out what tasks were delaying interactivity. This could be a little cumbersome.

To help ease your performance auditing workflow, DevTools now visualizes Long Tasks. Tasks (shown in gray) have red flags if they are Long Tasks.

Record a trace in the Performance panel of loading up a web page.
Look for a red flag in the main thread view. You should see tasks are now gray ("Task").
Hovering over a bar will let you know the duration of the task and if it was considered "long".

What is causing my Long Tasks?

To discover what is causing a long task, select the gray Task bar. In the drawer beneath, select Bottom-Up and Group by Activity. This allows you to see what activities contributed the most (in total) to the task taking so long to complete. Below, it appears to be a costly set of DOM queries.

What are common ways to optimize Long Tasks?

Large scripts are often a major cause of Long Tasks so consider splitting them up. Also keep an eye on third-party scripts; their Long Tasks can delay primary content from getting interactive.

Break all your work into small chunks (that run in < 50ms) and run these chunks at the right place and time; the right place may even be off the main thread, in a worker. Phil Walton's Idle Until Urgent is a good read on this topic.

Keep your pages responsive. Minimizing Long Tasks is a great way to ensure your users have a delightful experience when they visit your site. For more on Long Tasks, check out User-centric Performance Metrics.

Speed at scale: what's new in web performance?

2019-05-23T17:00:00-07:00

During the "Speed at Scale" talk at Google I/O 2019, we announced three things that we hope will improve web performance over the coming year.

Lighthouse now supports Performance Budgeting

LightWallet is a new feature in Lighthouse that adds support for performance budgets. Performance budgets establish standards for the performance of your site. More importantly, they make it is easy to identify and fix performance regressions before they ship.

LightWallet is available in the newest version of the Lighthouse CLI and only takes a couple minutes to set up. These instructions provide more information.

Unsure what your budgets should be? Try our experimental Performance Budget Calculator which can generate a LightWallet compatible budget configuration.

Native image and iframe lazy-loading comes to the web

Web pages often contain a large number of images, which contribute to data-usage, page-bloat and slower page loads. Many of these images are offscreen, requiring a user to scroll in order to view them.

Until now, you've needed to solve lazy-loading images using a JavaScript library but that may soon change. This summer, Chrome will be launching support for the loading attribute which brings native <img> and <iframe> lazy-loading to the web.

The loading attribute allows a browser to defer loading offscreen images and iframes until users scroll near them. loading supports three values:

lazy: is a good candidate for lazy loading.
eager: is not a good candidate for lazy loading. Load right away.
auto: browser will determine whether or not to lazily load.

<img src="io2019.jpg" loading="lazy" alt="..." />
<iframe src="video-player.html" loading="lazy"></iframe>

The exact heuristics for "when the user scrolls near" is left up to the browser. In general, our hope is that browsers will start fetching deferred images and iframe content a little before it comes into the viewport.

The loading attribute is implemented behind flags in Chrome Canary. You can try out this demo in Chrome 75+ with the chrome://flags/#enable-lazy-image-loading and chrome://flags/#enable-lazy-frame-loading flags turned on.

A write-up on the native lazy-loading feature is available with more details.

Google Fonts now supports font-display as a query parameter

We announced support for font-display is now available in production for all Google Fonts via the display query-string parameter:

https://fonts.googleapis.com/css?family=Lobster&display=swap

The font-display descriptor lets you decide how your web fonts will render or fallback, depending on how long it takes for them to load. It supports a number of values including auto, block, swap, fallback and optional.

Previously, the only way to specify font-display for web fonts from Google Fonts was to self-host them but this change removes the need to do so.

The Google Fonts documentation has been updated to include font-display in the default code embeds (as seem below). We hope this will encourage more developers to try out this exciting addition.

Here's a demo on Glitch of using display with multiple font families. Try it out with DevTools network emulation to see the impact of font-display: swap.

Watch for more

Our talk also covered several production case studies of using advanced performance patterns to improve user-experience. These included sites leveraging image CDNs, Brotli compression, smart JavaScript serving and prefetching to speed up their pages. Watch the talk to learn more :)

Introducing PROXX

2019-05-08T17:00:00-07:00

The team that brought you squoosh.app is back! This time, we built a web-based game called PROXX (proxx.app). PROXX is a game of proximity inspired by the legendary game Minesweeper. The game is situated in the space and your job is to find out where the black holes are. It works on all kinds of devices—from desktop all the way to feature phones. Users can play the game using a mouse, keyboard, d-pad even with a screen reader.

PROXX on a feature phone.

Our baseline

Before building this game, we set the following goals and budgets for the application:

Same core experience: all devices must function the same way
Accessible: mouse, keyboard, touch, d-pad, screen readers
Performant:
- Less than 25kb of initial payload
- Less than 5 seconds TTI (time to interactive) on slow 3G
- Consistent 60fps animation

PROXX on a pixelbook.

Web Workers

The game consists of 4 main entities, the core game logic, the UI service, the state service, and the animation graphics. Since we knew from the get-go we would have to run heavily animated graphics on the main thread, we moved the game logic and state service to a web worker in order to keep the main thread as free as possible.

Build time pre-render

Our UI is built with Preact, as it allows us to hit our aggressive target for an initial payload that is less than 25kb. In order to give a good initial loading experience, we decided to pre-render our 1st view. We prerender at build time using Puppeteer to access the top page and let preact populate the DOM. The resulting DOM is then serialized to HTML and saved as index.html

Canvas for animation, (invisible) DOM For accessibility

We render the game graphics in a canvas using WebGL. One canvas is responsible for the background animation and another one canvas for the game grid on top. We also have an HTML table with buttons for accessibility reasons, that is on top of both of these canvases, but is made invisible (opacity: 0). Even though what you see is a canvas rendering of the game state, the player is interacting with the invisible DOM table, giving us the ability to attach event listeners and rely on the browser's focus management.

By keeping the DOM element in the canvas, we are able to tap into browsers native accessibility features. For example: by setting role="grid" on our game table, screen readers can announce the row and column of the focused cell without us having to implement that.

Rollup for bundling and code splitting

Our total size for the app comes down to 100KB gzipped. Out of that, 20KB is for the initial payload (index.html). We use Rollup.js for this project. We have shared dependencies between the main thread and our web worker, and Rollup can put these shared dependencies in a separate chunk that only needs to be loaded once. Other bundlers like webpack duplicate the shared dependencies which results in double-loading.

Supporting feature phones

Smart feature phones such as KaiOS phones are rapidly gaining popularity. These are very resource constrained devices, but our approach of using web workers whenever we can allowed us to make the experience highly responsive on these phones as well. Since feature phones come with different input interface (d-pad and number keys, no touchscreen), we also implemented key-based interface.

PROXX on a feature phone.

What's next

We had great but busy time building this game in time for Google I/O 2019, so we will take some well-deserved time off to rest, but plan to come back with more in-depth documentation on each of these areas of the game.

Until then, please check the talk Mariko gave at I/O on this project.

You can browse the code at the proxx github repo.

Cheers! Surma, Jake, Mariko

SameSite cookies explained

2019-05-06T17:00:00-07:00

Cookies are one of the methods available for adding persistent state to web sites. Each cookie is a key=value pair along with a number of attributes that control when and where that cookie is used. You've probably already used these attributes to set things like expiry dates or indicating the cookie should only be sent over HTTPS. Servers set cookies by sending the aptly-named Set-Cookie header in their response. For all the detail you can dive into RFC6265bis, but for now here's a quick refresher.

Say you have a blog where you want to display a "What's new" promo to your users. Users can dismiss the promo and then they won't see it again for a while. You can store that preference in a cookie, set it to expire in a month (2,600,000 seconds), and only send it over HTTPS. That header would look like this:

Set-Cookie: promo_shown=1; Max-Age=2600000; Secure

Servers set cookies using the Set-Cookie header.

When your reader views a page that meets those requirements, i.e. they're on a secure connection and the cookie is less than a month old, then their browser will send this header in its request:

Cookie: promo_shown=1

Your browser sends cookies back in the Cookie header.

You can also add and read the cookies available to that site in JavaScript using document.cookie. Making an assignment to document.cookie will create or override a cookie with that key. For example, you can try the following in your browser's JavaScript console:

> document.cookie = "promo_shown=1; Max-Age=2600000; Secure"
< "promo_shown=1; Max-Age=2600000; Secure"

Reading document.cookie will output all the cookies accessible in the current context, with each cookie separated by a semicolon:

> document.cookie;
< "promo_shown=1; color_theme=peachpuff; sidebar_loc=left"

JavaScript can access cookies using document.cookie.

If you try this on a selection of popular sites you will notice that most of them set significantly more than just three cookies. In most cases, those cookies are sent on every single request to that domain, which has a number of implications. Upload bandwidth is often more restricted than download for your users, so that overhead on all outbound requests is adding a delay on your time to first byte. Be conservative in the number and size of cookies you set. Make use of the Max-Age attribute to help ensure that cookies don't hang around longer than needed.

What are first-party and third-party cookies?

If you go back to that same selection of sites you were looking at before, you probably noticed that there were cookies present for a variety of domains, not just the one you were currently visiting. Cookies that match the domain of the current site, i.e. what's displayed in the browser's address bar, are referred to as first-party cookies. Similarly, cookies from domains other than the current site are referred to as third-party cookies. This isn't an absolute label but is relative to the user's context; the same cookie can be either first-party or third-party depending on which site the user is on at the time.

Cookies may come from a variety of different domains on one page.

Continuing the example from above, let's say one of your blog posts has a picture of a particularly amazing cat in it and it's hosted at /blog/img/amazing-cat.png. Because it's such an amazing image, another person uses it directly on their site. If a visitor has been to your blog and has the promo_shown cookie, then when they view amazing-cat.png on the other person's site that cookie will be sent in that request for the image. This isn't particularly useful for anyone since promo_shown isn't used for anything on this other person's site, it's just adding that overhead to the request.

If that's an unintended effect, why would you want to do this? It's this mechanism that allows sites to maintain state when they are being used in a third-party context. For example, if you embed a YouTube video on your site then visitors will see a "Watch later" option in the player. If your visitor is already signed in to YouTube, that session is being made available in the embedded player by a third-party cookie—meaning that "Watch later" button will just save the video in one go rather than prompting them to sign in or having to navigate them away from your page and back over to YouTube.

A cookie in a third-party context is sent when visiting different pages.

One of the cultural properties of the web is that it's tended to be open by default. This is part of what has made it possible for so many people to create their own content and apps there. However, this has also brought a number of security and privacy concerns. Cross-site request forgery (CSRF) attacks rely on the fact that cookies are attached to any request to a given origin, no matter who initiates the request. For example, if you visit evil.example then it can trigger requests to your-blog.example, and your browser will happily attach the associated cookies. If your blog isn't careful with how it validates those requests then evil.example could trigger actions like deleting posts or adding their own content.

Users are also becoming more aware of how cookies can be used to track their activity across multiple sites. However until now there hasn't been a way to explicitly state your intent with the cookie. Your promo_shown cookie should only be sent in a first-party context, whereas a session cookie for a widget meant to be embedded on other sites is intentionally there for providing the signed-in state in a third-party context.

Explicitly state cookie usage with the `SameSite` attribute

The introduction of the SameSite attribute (defined in RFC6265bis) allows you to declare if your cookie should be restricted to a first-party or same-site context. It's helpful to understand exactly what 'site' means here. The site is the combination of the domain suffix and the part of the domain just before it. For example, the www.web.dev domain is part of the web.dev site.

Key Term: If the user is on www.web.dev and requests an image from static.web.dev then that is a same-site request.

The public suffix list defines this, so it's not just top-level domains like .com but also includes services like github.io. That enables your-project.github.io and my-project.github.io to count as separate sites.

Key Term: If the user is on your-project.github.io and requests an image from my-project.github.io that's a cross-site request.

Introducing the SameSite attribute on a cookie provides three different ways to control this behaviour. You can choose to not specify the attribute, or you can use Strict or Lax to limit the cookie to same-site requests.

If you set SameSite=Strict this means your cookie will only be sent in a first-party context. In user terms, the cookie will only be sent if the site for the cookie matches the site currently shown in the browser's URL bar. So, if the promo_shown cookie is set as follows:

Set-Cookie: promo_shown=1; SameSite=Strict

When the user is on your site, then the cookie will be sent with the request as expected. However when following a link into your site, say from another site or via an email from a friend, on that initial request the cookie will not be sent. This is good where you have cookies relating to functionality that will always be behind an initial navigation, such as changing a password or making a purchase, but is too restrictive for promo_shown. If your reader follows the link into the site, they want the cookie sent so their preference can be applied.

That's where SameSite=Lax comes in by allowing the cookie to be sent with these top-level navigations. Let's revisit the cat article example from above where another site is referencing your content. They make use of your photo of the cat directly and provide a link through to your original article.

<p>Look at this amazing cat!</p>
<img src="https://blog.example/blog/img/amazing-cat.png" />
<p>Read the <a href="https://blog.example/blog/cat.html">article</a>.</p>

If the cookie has been set as so:

Set-Cookie: promo_shown=1; SameSite=Lax

When the reader is on the other person's blog the cookie will not be sent when the browser requests amazing-cat.png. However when the reader follows the link through to cat.html on your blog, that request will include the cookie. This makes Lax a good choice for cookies affecting the display of the site with Strict being useful for cookies related to actions your user is taking.

Caution: Neither Strict nor Lax are a silver bullet for your site security. Cookies are sent as part of the user's request and you should treat them the same as any other user input. That means sanitizing and validating the input. Never use a cookie to store data you consider a server-side secret.

Finally there is the option of not specifying the value which has previously been the way of implicitly stating that you want the cookie to be sent in all contexts. In the latest draft of RFC6265bis this is being made explicit by introducing a new value of SameSite=None. This means you can use None to clearly communicate you intentionally want the cookie sent in a third-party context.

Explicitly mark the context of a cookie as None, Lax, or Strict.

Objective: If you provide a service that other sites consume such as widgets, embedded content, affiliate programmes, advertising, or sign-in across multiple sites then you should use None to ensure your intent is clear.

Changes to the default behavior without SameSite

Chrome 76 introduces a new same-site-by-default-cookies flag. Setting this flag will shift the default treatment of cookies to apply SameSite=Lax if no other SameSite value is provided. This is a move towards providing a more secure default and one that makes the intended purpose of cookies clearer to users. If you want to delve into the details, check out Mike West's "Incrementally Better Cookies".

With this flag enabled in Chrome, both new and existing cookies without the SameSite attribute will be restricted to the same site the user is browsing. If you have cookies that need to be available in a third-party context, then you must declare that to the browser and the user by marking them as SameSite=None. You will want to apply this when setting new cookies and actively refresh existing cookies even if they are not approaching their expiry date.

If you rely on any services that provide third-party content on your site, you should also check with the provider that they are updating their services. You may need to update your dependencies or snippets to ensure that your site picks up the new behavior.

These changes are backwards-compatible with browsers that have correctly implemented earlier versions of the SameSite attribute, or just do not support it at all. By applying these changes to your cookies, you are making their intended use explicit rather than relying on the default behavior of the browser. Likewise, any clients that do not recognize SameSite=None as of yet should ignore it and carry on as if the attribute was not set.

Additionally in Chrome, if you also enable the cookies-without-same-site-must-be-secure flag then you must also specify SameSite=None cookies as Secure or they will be rejected. Note, this flag won't have any effect unless you also have same-site-by-default-cookies enabled.

Warning: At the time of writing, the network library on iOS and Mac incorrectly handles unknown SameSite values and will treat any unknown value (including None) as if it was SameSite=Strict, which affects Safari on Mac and browsers wrapping WebKit on iOS (Safari, Chrome, Firefox, and others). This should be fixed in an upcoming release and may be available in the Tech Preview now. You can track their progress in the WebKit Bugzilla #198181.

Behavior with `same-site-by-default-cookies` enabled

Set-Cookie: promo_shown=1

No attribute set

— If you send a cookie without any SameSite attribute specified.

Set-Cookie: promo_shown=1; SameSite=Lax

Default behavior applied

— Chrome will treat that cookie as if SameSite=Lax was specified.

Behavior with `cookies-without-same-site-must-be-secure` enabled

Set-Cookie: widget_session=abc123; SameSite=None

Rejected

— Setting a cookie without Secure will be rejected.

Set-Cookie: widget_session=abc123; SameSite=None; Secure

Accepted

— You must ensure that you pair SameSite=None with the Secure attribute.

Objective: These flags are intended to encourage more secure defaults, but you shouldn't rely on a browser's default behavior. Best practice is to always be explicit in stating the attributes so your intent is clear.

Designing for `SameSite` cookies

A core practice in software design is the Separation of Concerns which essentially states that each part of your system should have one clear purpose. This is more simply put in the Unix philosophy which says, "Make each program do one thing well". By adding the SameSite attribute to your cookies you are creating the distinction between first-party and third-party usage, but a third-party cookie can still be used in a first-party context. It might seem simpler to just have the single cookie, but now you have one component doing two jobs.

If you have one cookie that's providing functionality in both contexts, for example perhaps providing a user identifier for your main site and for an embeddable widget, then consider separating these into separate cookies. As browsers and users start to change how they accept and manage cookies providing this distinction makes your site more robust in scenarios where third-party cookies are blocked or cleared.

What should I do to enable `SameSite` today?

The majority of languages and libraries support the SameSite attribute for cookies, however the addition of SameSite=None is still relatively new which means that you may need to work around some of the standard behavior for now. These are documented in the SameSite examples repo on GitHub. If your particular use case is missing, please raise issue or submit a pull request with your solution.

Kind thanks for contributions and feedback from Lily Chen, Malte Ubl, Mike West, Rob Dodson, Tom Steiner, and Vivek Sekhar

Cookie hero image by Pille-Riin Priske on Unsplash

Visual searching with the Web Perception Toolkit

2019-05-06T17:00:00-07:00

Wouldn't it be great if users could search your site using their camera? Imagine this. Your site is Razor McShaveyface. Your customers tell you they have trouble finding the right cartridges for their razor when they reorder. They don't know the right keywords for your product search. And let's be honest, they probably never will.

What if they never need to? What if they could point their phone's camera at the UPC code on package and your site could present them with the right cartridge and a big red "reorder" button?

Think of other ways you can use a camera on a site. Imagine a site that supports in-store price checking. Imagine getting information about a museum exhibit or historical marker. Imagine identifying real-world landmarks in games like geocaching or scavenger hunts.

The Web Perception Toolkit makes these camera-based scenarios possible. In some cases you can even create an experience without writing code.

How does it work?

The open-source Web Perception Toolkit helps you add visual search to your website. It passes a device camera stream through a set of detectors that map real-world objects, here called "targets", to content on your site. This mapping is defined using Structured Data (JSON-LD) on your site. With this data, you can present the right information in a customizable UI.

I'll show you enough of this to give you a taste of how it works. For a complete explanation, check out the Getting Started guide, the toolkit reference, the I/O Sandbox demo and the sample demos.

Structured data

The toolkit can't find just any target in the camera's view. You must provide it with linked JSON data for the targets you want it to recognize. This data also contains information about those targets that will be shown to the user.

The data is all you need to create a user experience like the one in the image below. If you do nothing else, the Web Perception Toolkit can identify targets, then show and hide cards based on the information provided in the data. Try this for yourself using our artifact-map demo.

The default interface.

Add data to your site with a JSON linked data file, included using a <script> tag and the "application/ld+json" MIME type.

<script type="application/ld+json" src="//path/to/your/sitemap.jsonld">

The file itself looks something like this:

[
  {
    "@context": "https://schema.googleapis.com/",
    "@type": "ARArtifact",
    "arTarget": {
      "@type": "Barcode",
      "text": "012345678912"
    },
    "arContent": {
      "@type": "WebPage",
      "url": "http://localhost:8080/demo/artifact-map/products/product1.html",
      "name": "Product 1",
      "description": "This is a product with a barcode",
      "image": "http://localhost:8080/demo/artifact-map/products/product1.png"
    }
  }
]

The user experience

What if you want more than the default user experience? The toolkit gives you livecycle events, Card and Button objects for crafting the user experience around those events, and an easy way to style the cards. I'm going to show a little of this with code based losely on our Getting Started guide.

The most important lifecycle event is PerceivedResults, which is firedß every time a target is found. A target can be a real-world object or a marker such as a bar code or QR code.

The process for responding to this event is the same as for any other event with an exception alrady alluded to. If you don't implement the event, a user interface is automatically created using structured data. To override this behavior start your event handler by callingevent.preventDefault().

const container = document.querySelector('.container');
async function onPerceivedResults(event) {
  // preventDefault() to stop default result Card from showing.
  event.preventDefault();
  // Process the event.
}
window.addEventListener(PerceptionToolkit.Events.PerceivedResults, onPerceivedResults);

Let's look at the event more closely. The event itself contains arrays of markers and targets that it has both found and lost. When targets are found in the world, the even fires and passes found objects in event.found. Similarly, when targets pass from the camera view the event fires again, passing lost objects in event.lost. This helps account for hand and marker movements: cameras not held steadily enough, dropped markers, that kind of thing.

async function onPerceivedResults(event) {
  // preventDefault() to stop default result Card from showing
  event.preventDefault();
  if (container.childNodes.length > 0) { return; }
  const { found, lost } = event.detail;
  // Deal with lost and found objects.
}

Next, you show an appropriate card based on what the toolkit found.

async function onPerceivedResults(event) {
  event.preventDefault();
  if (container.childNodes.length > 0) { return; }
  const { found, lost } = event.detail;
  if (found.length === 0 && lost.length === 0) {
    // Object not found.
    // Show a card with an offer to show the catalog.
  } else if (found.length > 0) {
    // Object found.
    // Show a card with a reorder button.
  }
}

Adding cards and buttons is simply a matter of instantiating them and appending them to a parent object. For example:

const { Card } = PerceptionToolkit.Elements;
const card = new Card();
card.src = 'Your message here.'
container.appendChild(card)'

Finally, here's what the whole thing looks like. Notice the conveniences I've added to the user experience. Whether the marker is found or not, I provide one-click access to what I think is most useful in the circumstances.

async function onPerceivedResults(event) {
  // preventDefault() to stop default result Card from showing
  event.preventDefault();
  if (container.childNodes.length > 0) { return; }
  const { found, lost } = event.detail;
  const { ActionButton, Card } = PerceptionToolkit.Elements;
  if (found.length === 0 && lost.length === 0) {
    //Make a view catalog button.
    const button =  new ActionButton();
    button.label = 'View catalog';
    button.addEventListener('click', () => {
      card.close();
      //Run code to launch a catalog.
    });
    //Make a card for the button.
    const card = new Card();
    card.src = 'We wish we could help, but that\'s not our razor. Would you like to see our catalog?';
    card.appendChild(button);
    //Tell the toolkit it does not keep the card around
    // if it finds something it recognizes.
    card.dataset.notRecognized = true;
    container.appendChild(card);
  } else if (found.length > 0) {
    //Make a reorder button.
    const button = new ActionButton();
    button.label = 'Reorder';
    botton.addEventListener('click', () => {
      card.close();
      //Run code to reorder.
    })
    const card = new Card();
    card.src = found[0].content;
    card.appendChild(button);
    container.appendChild(card);
  }
}

Formatting cards

The Web Perception Toolkit provides built-in formatting for cards and buttons with the default stylesheet. But you can easily add your own. The provided Card and ActionButton objects contain style properties (among many others) that let you put your organizational stamp on the look and feel. To include the default stylesheet, add a <link> element to your page.

<link rel="stylesheet" href="//path/to/toolkit/styles/perception-toolkit.css">

Conclusion

As I said at the top, this is not an exhaustive look at the Web Perception Toolkit. Hopefully it gives you a sense of how easy it is to add visual searching to a website. Learn more with the Getting Started guide and the sample demos. Dig in to the toolkit documentation to learn what it can do.

Hands-on with Portals: seamless navigation on the Web

2019-05-05T17:00:00-07:00

Making sure your pages load fast is key to delivering a good user experience. But one area we often overlook is page transitions—what our users see when they move between pages.

A new web platform API called Portals aims to help with this by streamlining the experience as users navigate across your site. See Portals in action:

Seamless embeds and navigation with Portals. Created by Adam Argyle.

What Portals enable

Single Page Applications (SPAs) offer nice transitions but come at the cost of higher complexity to build. Multi-page Applications (MPAs) are much easier to build, but you end up with blank screens between pages.

Portals offer the best of both worlds: the low complexity of an MPA with the seamless transitions of an SPA. Think of them like an <iframe> in that they allow for embedding, but unlike an <iframe>, they also come with features to navigate to their content.

Seeing is believing: please first check out what we showcased at Chrome Dev Summit last year:

With classic navigations, users have to wait with a blank screen until the browser finishes rendering the destination. With Portals, users get to experience an animation, while the <portal> pre-renders content and creates a seamless navigation experience.

Before Portals, we could have rendered another page using an <iframe>. We could also have added animations to move the frame around the page. But an <iframe> won't let you navigate into its content. Portals close this gap, enabling interesting use cases.

Try out Portals in Chrome Canary

Try out Portals in Chrome Canary by flipping an experimental flag: chrome://flags/#enable-portals. Once Portals are enabled, confirm in DevTools that you have the new shiny HTMLPortalElement.

Let's walk through a basic example.

// Create a portal with the wikipedia page, and embed it
// (like an iframe). You can also use the <portal> tag instead.
portal = document.createElement('portal');
portal.src = 'https://en.wikipedia.org/wiki/World_Wide_Web';
portal.style = '...';
document.body.appendChild(portal);

// When the user touches the preview (embedded portal):
// do fancy animation, e.g. expand …
// and finish by doing the actual transition
portal.activate();

It's that simple. Try this code in the DevTools console, the wikipedia page should open up.

If you wanted to build something like we showed at Chrome Dev Summit which works just like the demo above, the following snippet will be of interest.

// Adding some styles with transitions
const style = document.createElement('style');
const initialScale = 0.4;
style.innerHTML = `
  portal {
    position:fixed;
    width: 100%;
    height: 100%;
    opacity: 0;
    box-shadow: 0 0 20px 10px #999;
    transform: scale(${initialScale});
    bottom: calc(20px + 50% * ${initialScale} - 50%);
    left: calc(20px + 50% * ${initialScale} - 50%);
    z-index: 10000;
  }
  .portal-transition {
    transition:
      transform 0.4s,
      bottom 0.7s,
      left 0.7s,
      opacity 1.0s;
  }
  @media (prefers-reduced-motion: reduce) {
    .portal-transition {
      transition: all 0.001s;
    }
  }
  .portal-reveal {
    transform: scale(1.0);
    bottom: 0px;
    left: 0px;
  }
  .fade-in {
    opacity: 1.0;
  }
`;
const portal = document.createElement('portal');
// Let's navigate into the WICG Portals spec page
portal.src = 'https://wicg.github.io/portals/';
// Add a class that defines the transition. Consider using 
// `prefers-reduced-motion` media query to control the animation. 
// https://developers.google.com/web/updates/2019/03/prefers-reduced-motion
portal.classList.add('portal-transition');
portal.addEventListener('click', evt => {
  // Animate the portal once user interacts
  portal.classList.add('portal-reveal');
});
portal.addEventListener('transitionend', evt => {
  if (evt.propertyName == 'bottom') {
    // Activate the portal once the transition has completed
    portal.activate();
  }
});
document.body.append(style, portal);

// Waiting for the page to load.
// using setTimeout is a suboptimal way and it's best to fade-in
// when receiving a load complete message from the portal via postMessage
setTimeout(_ => portal.classList.add('fade-in'), 2000);

It is also easy to do feature detection to progressively enhance a website using Portals.

if ('HTMLPortalElement' in window) {
  // If this is a platform that have Portals...
  const portal = document.createElement('portal');
  ...
}

If you want to quickly experience what Portals feel like, try using uskay-portals-demo.glitch.me. Be sure you access it with Chrome Canary and turn on the experimental flag!

Enter a URL you want to preview.
The page will then be embedded as a <portal> element.
Click on the preview.
The preview will be activated after an animation.

Check out the spec

We are actively discussing the Portals spec in the Web Incubation Community Group (WICG). To quickly get up to speed, take a look at the explainer. These are the three important features to familiarize yourself with:

The <portal> element: The HTML element itself. The API is very simple. It consists of the src attribute, the activate function and an interface for messaging (postMessage). activate takes an optional argument to pass data to the <portal> upon activation.
The portalHost interface: Adds a portalHost object to the window object. This lets you check if the page is embedded as a <portal> element. It also provides an interface for messaging (postMessage) back to the host.
The PortalActivateEvent interface: An event that fires when the <portal> is activated. There is a neat function called adoptPredecessor which you can use to retrieve the previous page as a <portal> element. This allows you to create seamless navigations and composed experiences between two pages.

Let's look beyond the basic usage pattern. Here is a non-exhaustive list of what you can achieve with Portals along with sample code.

Customize the style when embedded as a `<portal>` element

// Detect whether this page is hosted in a portal
if (window.portalHost) {
  // Customize the UI when being embedded as a portal
}

Messaging between the `<portal>` element and `portalHost`

// Send message to the portal element
const portal = document.querySelector('portal');
portal.postMessage({someKey: someValue}, ORIGIN);

// Receive message via window.portalHost
window.portalHost.addEventListener('message', evt => {
  const data = evt.data.someKey;
  // handle the event
});

Activating the `<portal>` element and receiving the `portalactivate` event

// You can optionally add data to the argument of the activate function
portal.activate({data: {'somekey': 'somevalue'}});

// The portal content will receive the portalactivate event
// when the activate happens
window.addEventListener('portalactivate', evt => {
  // Data available as evt.data
  const data = evt.data;   
});

Retrieving the predecessor

// Listen to the portalactivate event
window.addEventListener('portalactivate', evt => {
  // ... and creatively use the predecessor
  const portal = evt.adoptPredecessor();
  document.querySelector('someElm').appendChild(portal);
});

Knowing your page was adopted as a predecessor

// The activate function returns a Promise.
// When the promise resolves, it means that the portal has been activated.
// If this document was adopted by it, then window.portalHost will exist.
portal.activate().then(_ => {
  // Check if this document was adopted into a portal element.
  if (window.portalHost) {
    // You can start communicating with the portal element
    // i.e. listen to messages
    window.portalHost.addEventListener('message', evt => {
      // handle the event
    });
  }
});

By combining all of the features supported by Portals, you can build really fancy user experiences. For instance, the demo below demonstrates how Portals can enable a seamless user experience between a website and third party embed content.

Interested in this demo? Fork it on GitHub and build your own version!

Use cases and plans

We hope you liked this brief tour of Portals! We can't wait to see what you can come up with. For instance, you might want to start using Portals for non-trivial navigations such as: pre-rendering the page for your best-seller product from a product category listing page.

Another important thing to know is that Portals can be used in cross-origin navigations, just like an <iframe>. So, if you have multiple websites that cross reference one another, you can also use Portals to create seamless navigations between two different websites. This cross-origin use case is very unique to Portals, and can even improve the user experience of SPAs.

Feedback welcome

Portals are still in the early stages so not everything is working yet (that's why it's behind an experimental flag). That said, it's ready for experimentation in Chrome Canary. Feedback from the community is crucial to the design of new APIs, so please try it out and tell us what you think! You can check the current limitations on the Chromium bug tracker and if you have any feature requests, or feedback, please head over to the WICG GitHub repo.

How to report metrics and build a performance culture

2019-05-04T17:00:00-07:00

Introduction

Website performance is a key goal towards e-commerce conversions, so it must be a core priority for business stakeholders and leadership, not just development teams.

For that reason, it's crucial to make performance metrics visible and tangible for all stakeholders, and to build reporting and monitoring into your workflow.

This guide describes what to be aware of and what to avoid to achieve this successfully.

A word about metrics

There are countless metrics to evaluate website performance, and while it may seem useful to collect all of them, too many metrics can be confusing and misleading. There are several ways to deal with this:

Gather multiple metrics and try to narrow and filter afterwards on what might be relevant for the task at hand.
Abstract metrics into an overall score, as for example Lighthouse does. This can be especially useful for non-technical staff and other stakeholders, but is probably insufficient for deeper technical analysis.
Try to find the one metric which is most relevant as a predictor for your conversions and then optimize towards this.

In reality, a pragmatic combination makes the most sense here. Gather more rather than less to begin with, report an abstract score to management, and optimize towards the one metric which best predicts your conversions.

Finding this metric can be done by using your analytics tool of choice to map performance metrics to user engagement, conversions and transaction values. For example, a custom report to do so looks like this in Google Analytics:

Fig 1: Custom report in Google Analytics to analyze the impact of speed on conversions and engagement.

Caution: Metrics can be deceiving. Unfortunately metrics can sometimes be misleading with respect to performance. Keep reading for specifics.

Increasing bounce rate

Problem

Often it is assumed that bounce rate will drop when page load speed increases. While this normally does hold true, measurements sometimes show the opposite. This is because analytics can only measure a bounce after the analytics library is loaded. A faster page load means analytics code also loads faster, so analytics may see more bounces even if there aren't more happening.

Solution

This can be eased by measuring real page abandonment instead.

Decreasing relative conversions

Problem

Relative conversions may sometimes seem to drop for faster sites. This is because faster pages reach a bigger audience who might be less engaged or committed. While incremental traffic and conversions increase with faster pages, relative conversions (the ratio of conversions to page views or visitors) might still drop.

Solution

This effect can be eased by looking out for absolute conversions instead, and even calculate Cost Per Sales (conversions divided with investment level) or ROI.

Dropping engagement

Problem

Page engagement may seem to drop for a faster page.

Solution

This can actually be a positive signal! If the page is faster users can reach their goal more quickly and might just have shorter sessions and less time on page.

Using averages or medians

Problem

In general, it can be deceiving to look at averages and medians of performance metrics (see this nicely described in Everything You Know About Latency Is Wrong). Similar to a chain being just as strong as the weakest link, the performance of a funnel is only as good as its slowest load. A single slow load may be enough to lose the user. Therefore averages and medians are more likely to hide the real performance issues, than to reveal them.

Solution

It's best to analyze complete distributions, but as this is not always easily possible we recommend using 90th percentiles—this is the value for which 90% of loads were faster. Even then a user hitting ten pages will still have one load slower than this, and might drop out there.

While performance measurement is highly important, make sure to keep an open mind and question unexpected results—and make sure to not report misleading numbers to stakeholders and management. If unsure on what to pick and report, we'd advise as a minimum for 90th percentile First Contentful Paint, which is also what we use across our public tooling.

Third party content

Website performance is especially prone to being dragged down by third party content (see Eliminate render-blocking resources). This is a particular problem for e-commerce, often due to trackers and widgets.

Some ways to handle third party content with respect to performance:

Always keep third party content out of the critical rendering path. If the third party has server problems and times out, it will impact your website heavily. You can test and simulate this via WebPageTest Single-Point-of-Failure tests.
Continually measure and report the ratio of third party content, for example via WebPageTest domain breakdown. Make sure to use performance budgets for third party content.
If you suspect that a particular third party component is having a detrimental effect on performance, do a performance comparison with it included and excluded. Find out how.
Try to stay on one stack from one vendor if possible. For example, if you have a tag manager and analytics on one stack, you may only need a single script, and may be able to take advantage of HTTP2 synergies as there is only one host involved.
Make sure not to use the same functionality from two different vendors. You shouldn't need two tag managers or two analytics platforms.
Routinely audit and clean out redundant third party scripts, trackers and widgets. This can easily be done via Ghostery Extension or tools like WhatRuns:

A Ghostery report showing all loaded trackers

Learn more in Loading Third-Party JavaScript.

Performance Culture

Unfortunately performance is often seen as a one-off optimization task, and then regresses over time as stakeholders raise new feature requests or insist on adding new trackers and widgets.

Performance must be a continuous goal to improve acquisition, discovery, and conversion rates as well as safeguarding the reputation of your brand. This can be achieved with performance budgets like Tinder did, and by establishing and fostering a performance culture, where all employees and especially decision makers recognize speed as a core feature of the website.

Make metrics tangible

Reports on metrics are often abstract and easy to challenge or dismiss. It's best to make your performance tangible and visible. There are several good ways to do this:

Facebook and Google do this by providing slow networks across the company for testing.
Make average, low-spec devices with low bandwidth or high latencies available to management and other stakeholders.
Consider adding overlays showing performance metrics on your development or staging servers. Connections to these servers from mobile can potentially be throttled by default on corporate networks.
Monitors can be placed strategically across the company showing videos or timestrips of your website's loading behavior, preferably in comparison to competitors. WebPageTest can create these very easily and automatically.
Performance can also be fun—maybe a game based on an individual Lighthouse report can reach audiences which can't be reached by pure reports and metrics?

Recap

This guide explains why the selection of metrics, and how they are reported and handled, is as important as the measurement and optimization itself—or even more. Make sure to prefer percentiles or distributions over averages, be cautious of using just bounce rate or relative conversion rate as impact measures, and make sure that metrics are easy to understand and tangible for stakeholders across the company. Establishing a performance culture is also an important step towards a well performing e-commerce site.

web.dev at I/O 2019

2019-05-03T17:00:00-07:00

With I/O right around the corner, we wanted to sneak out a quick update to let you know what we've been working on since our beta launch at Chrome Dev Summit.

New look

We want web.dev to be a best-in-class reading experience—something that folks look forward to opening on their phones, tablets, and desktops.

In this iteration, we launched a new design with improved typography and a bit more visual punch. We have a number of UI features still in the backlog that we plan to ship in the coming months, but we hope you like this new visual style 💅

Improved Lighthouse support

In the Learn section, we've rolled out new Lighthouse audit docs with updated images, scoring explainers, and links to guides which dive deeper into specific topics.

We've also connected these docs to our measure tool so when you audit your site you should have a better understanding of what each result means and how to fix it.

New blog!

Last, but not least, we have our new blog.

Not that long ago, our team used to produce a site called HTML5Rocks. HTML5Rocks always felt like a group of folks coming together to share their collective excitement about what was possible on the web.

As we've been building web.dev, we've often said that we want to bring back some of that "HTML5Rocks magic ✨". Get people excited about what's possible, and use new services like Glitch to let them remix and play with running code. So for the web.dev blog, we're making it our mission to keep things open, experimental, and fun 👩‍🔬

Wrapping up

If you want to stay up to date with the latest on web.dev, you can click that little subscribe button in the bottom-right corner to join our newsletter, or add the site to your feed reader of choice.

We're really excited for this year's I/O, so definitely check back in the days and weeks ahead as we roll out new content. There's a boatload of stuff coming and we can't wait to share it with you.

Thanks! 👋

- The web.dev crew

Discover performance opportunities with Lighthouse

2018-11-04T16:00:00-08:00

Lighthouse is a tool that helps you measure and find ways to improve a page's performance. Here's the general workflow for how you use Lighthouse:

You tell Lighthouse what page to audit.
Lighthouse loads that page and records how long the page takes to hit various performance milestones. These milestones are called metrics.
Lighthouse gives you a report on how the page did. The report provides a score for each metric and a list of opportunities which, if you implement them, should make the page load faster.

Your mission is to improve your metrics scores over time, or at least make sure that they don't get worse. There's no way to work on metrics directly, though. Instead, you follow the opportunities that Lighthouse provides. Working on those opportunities tends to improve your metrics scores.

Run Lighthouse from your profile page

Run Lighthouse from your web.dev profile page:

Provide any URL, and Lighthouse runs a series of audits generating a report of how well the page did.
Review the audits report to identify areas in which your page can be improved.
For each audit, you'll find guidance and immediate steps you can take to improve your scores.

Run Lighthouse from Chrome DevTools

Chrome DevTools is the set of web developer tools that are built directly into the Google Chrome browser. You don't have to download anything to get DevTools. If you have Chrome, then you have DevTools.

In Chrome, go to the page that you want to audit.
Press Control+Shift+J or Command+Option+J (Mac) to open DevTools.

Click the Audits tab. If you don't see this tab, click the » symbol and then select Audits from the list. Lighthouse is the engine that powers the Audits panel. That's why you see an image of a lighthouse.

Make sure the Mobile radio button is selected. When Lighthouse audits your page, it will simulate a mobile device's viewport and user agent string.
Make sure the Performance checkbox is enabled. You can enable or disable the rest of the checkboxes in the Audits section. If you enable them, then you'll see a bunch of opportunities on ways to improve those other aspects of your page.
Make sure the Simulated Fast 3G, 4x CPU Slowdown radio button is selected. Lighthouse doesn't actually throttle your network or CPU while it loads the page. Instead, it looks at how long the page took to load under normal conditions, and then it estimates how long it would have taken on a fast 3G network with a CPU that is 4 times less powerful than your machine's.
Make sure that the Clear Storage checkbox is enabled. This option forces Lighthouse to go to the network for every page resource, which is how first-time visitors experience the page.
Click Run Audits. After 5 to 10 seconds, Lighthouse shows you a report.

You can set the configuration options to whatever makes the most sense for your needs. If you don't understand them, the ones mentioned here are good defaults. If you can get your page fast with these options, then your page will be fast for everyone. The important thing is to stay consistent with the options across audits.

For example, if you run some audits with Simulated Fast 3G, 4x CPU Slowdown throttling enabled and then other times you run audits with throttling disabled, your metrics scores will be significantly lower when you have throttling enabled. You might spend a lot of time trying to figure out why your page is so much slower now, when in reality the only thing that changed was your configuration.

Understand your report

The top-right of your report lists your overall performance score. 100 is a perfect score. Below the overall score are the metrics scores. Lighthouse v3 Scoring Guide explains how each metric score contributes to the overall score.

Hover over a metric to learn more about it. Click Learn more to read documentation about it.

Below your metrics scores you see screenshots of how the page looked while it loaded.

Below the screenshots you see opportunities for improving the page's performance.

Click an opportunity to learn more about it.

Next steps

Try using Lighthouse to audit your page, either from your profile page or from Chrome DevTools. Implement one of the opportunities, and then audit your page again to see how the change affected your report. Your metrics scores should ideally be a little better, and Lighthouse should no longer be flagging that opportunity as something to work on.

Running Lighthouse yourself is great for spot-checking issues, but ultimately you'll want to setup continuous monitoring to make sure your site stays healthy. To track your Lighthouse progress over time add your site to the your profile.

web.dev

Ready Player Web

The challenges of web games #

Modern best practices #

Enter the loop #

Return on investment #

The future #

Progressive Web Apps in multi-origin sites

Background #

Good and bad uses of multiple origins #

The good #

The bad #

Challenges and Workarounds for PWAs across different origins #

Service workers #

Caching #

Permissions #

Installation #

Standalone Mode #

Conclusion #

How Truebil made the web its channel of growth

About #

Challenge #

Solution #

Optimize for fast first load and navigations #

Set performance budgets #

Optimize JavaScript bundles #

Inline critical CSS #

Avoid multiple, costly round trips to any origin #

Dynamically prefetch the next page #

Optimize images and fonts #

Further optimizations #

Build in reliability #

A hybrid caching strategy for reliable loading #

Service workers for a full offline experience #

Improve engagement to keep users coming back #

An engaging first experience #

An installable web app #

Default banners on process completion and on high-traffic pages #

Contextual prompts for mature users #

A custom banner for time-based prompts #

How to install the Thumbor image CDN

Intro #

Prerequisites #

Install Thumbor Dependencies #

Install Thumbor #

Run Thumbor #

Open Firewall Port #

Try It Out #

Appendix: Configuring Systemd #

Third-party JavaScript performance

Performance #

Network #

Rendering #

What to do about it #

More capable form controls

Event-based API #

Form-associated custom elements #

Defining a form-associated custom element #

Setting a value #

Input validation #

Lifecycle callbacks #

void formAssociatedCallback(form) #

void formDisabledCallback(disabled) #

void formResetCallback() #

void formStateRestoreCallback(state, mode) #

Restoring form state #

A working example #

Feature detection #

Conclusion #

Largest Contentful Paint

Largest Contentful Paint defined #

What elements are considered? #

How is an element's size determined? #

When is largest contentful paint reported? #

Load time vs. render time #

How are element layout and size changes handled? #

Examples #

How to measure Largest Contentful Paint in JavaScript #

What if the largest element isn't the most important? #

How to improve Largest Contentful Paint on your site #

The challenges of web games

Modern best practices

Enter the loop

Return on investment

The future

Background

Good and bad uses of multiple origins

The good

The bad

Challenges and Workarounds for PWAs across different origins

Service workers

Caching

Permissions

Installation

Standalone Mode

Conclusion

About

Challenge

Solution

Optimize for fast first load and navigations

Set performance budgets

Optimize JavaScript bundles

Inline critical CSS

Avoid multiple, costly round trips to any origin

Dynamically prefetch the next page

Optimize images and fonts

Further optimizations

Build in reliability

A hybrid caching strategy for reliable loading

Service workers for a full offline experience

Improve engagement to keep users coming back

An engaging first experience

An installable web app

Default banners on process completion and on high-traffic pages

Contextual prompts for mature users

A custom banner for time-based prompts

Intro

Prerequisites

Install Thumbor Dependencies

Install Thumbor

Run Thumbor

Open Firewall Port

Try It Out

Appendix: Configuring Systemd

Performance

Network

Rendering

What to do about it

Event-based API

Form-associated custom elements

Defining a form-associated custom element

Setting a value

Input validation

Lifecycle callbacks

`void formAssociatedCallback(form)`

`void formDisabledCallback(disabled)`

`void formResetCallback()`

`void formStateRestoreCallback(state, mode)`

Restoring form state

A working example

Feature detection

Conclusion

Largest Contentful Paint defined

What elements are considered?

How is an element's size determined?

When is largest contentful paint reported?

Load time vs. render time

How are element layout and size changes handled?

Examples

How to measure Largest Contentful Paint in JavaScript

What if the largest element isn't the most important?

How to improve Largest Contentful Paint on your site

Why native lazy-loading?

The `loading` attribute

Load-in distance threshold

Image loading

iframe loading

FAQ

Are there plans to expand this feature?

Can I change how close an image or iframe needs to be before a load is triggered?