bsmth.de

Firefox Enterprise is here

Tue, 13 Oct 2026 08:00:00 GMT

Today, Mozilla launched Firefox Enterprise. The first release is Firefox Enterprise 158, which branches off Firefox 158. I’ve been working on it as a product manager since 2025, so it’s good to finally be able to talk about what we’ve been building. This post covers how I ended up working on it, and the decisions I pushed for along the way.

From MDN to Firefox

I joined Mozilla in 2022 as a technical writer on MDN Web Docs. I wrote a lot of HTTP documentation and the Firefox release notes for developers, but the job was wider than writing. I ran content migrations, maintained browser compatibility data, worked with the communities who translate MDN, and helped keep one of the most active projects on GitHub running smoothly.

In 2025, I moved from documenting Firefox to working on it. It turned out writing and reading browser release notes for a few years also gave me a solid understanding of how a browser is built and shipped.

Working on Enterprise means understanding how the whole product fits together: the UI, profile management, networking, preferences, enterprise policies, build and release systems, supporting services, testing infrastructure, and general operational constraints.

What is Firefox Enterprise?

Firefox has been used in organizations for a long time. The Extended Support Release has been around since 2012, and the policy engine (mostly thanks to Mike Kaply) since version 60 of Firefox. Thousands of organizations deploy and manage Firefox with ESR and enterprise policies.

Firefox Enterprise builds on that. There are two parts: a Firefox browser with additional security features built for managed environments, and an Admin Console that you run on your own infrastructure. IT teams use the Admin Console to manage policies and access, and to set controls for how data moves through the browser and how it can be used.

The services Mozilla runs for consumer Firefox can be self-hosted alongside the Admin Console: browser updates, Sync (for history and bookmarks, for example), Remote Settings, telemetry, and crash collection. Security event logging is off by default, and crash reporting can be turned off. When enabled, security events, crash reports, and telemetry go to the customer’s Admin Console, not to Mozilla.

What we landed in 158

The release notes have the full list, but here are some highlights:

Company sign-in: users must authenticate through their company’s single sign-on (SSO) before browsing, using any OpenID Connect (OIDC) identity provider.
Device posture: admins can require things like disk encryption or endpoint security for sign-in, and Firefox signs the user out if the device isn’t compliant.
Watermarking: admins can overlay text such as the user’s email address and a timestamp on the sites they choose, so a leaked screenshot or photo of a sensitive page is attributable.
Data loss prevention (DLP): admins can block or warn on paste, upload, download, and print on the sites they choose. The built-in checks run on-device.
Lockdown Mode: admins can apply extra restrictions to specific sites, such as turning off JIT or isolating the site in its own container.
Access Connector: users can access internal sites from a personal device without a device-wide VPN.
Central policies: admins manage policies from one place, and many changes apply without restarting the browser.

Building Firefox Enterprise

We needed to know that Firefox Enterprise worked in real environments, and to find the gaps, before customers depended on it. I helped structure that as an internal alpha first, followed by a customer pilot. Working directly with prospective customers showed us what deploying and supporting a browser in an organization involves. I also worked across the browser, Admin Console, infrastructure, and QA teams to manage dependencies and make scope trade-offs.

Here are two product decisions I pushed for.

Building DLP into the browser

For data loss prevention, the usual options are to buy a solution or partner with an existing vendor. I pushed for another option: building it into Firefox Enterprise ourselves. It was the harder path, but I think it was the right bet for two reasons.

First, checks and enforcement happen client-side. The browser evaluates the rules locally rather than sending content to a separate service to decide whether a paste, upload, download, or print is allowed, and DLP works without another agent to deploy. If you already run a DLP agent, you can connect it through Firefox’s existing Content Analysis integration, and Firefox defers to it and turns the built-in checks off.

Second, we keep control over what to build next. Owning DLP end-to-end means our roadmap isn’t blocked by anyone else’s.

Big thanks to Greg Stoll and David Parks, who built the original Content Analysis integration that lets people hook Firefox up to third-party DLP agents.¹ Greg brought his experience with the policy surface and the browser internals to the Firefox Enterprise team and helped guide our implementation. Thanks also to Jonathan Mendez for his help designing and implementing the new built-in agent.

Describing policies with schema metadata

With more than 130 policies in the console, we needed something better than a text entry field for hand-written JSON, and designing UX for each policy doesn’t scale.

We already had a schema that describes policies, and my proposal was to make it the single source of truth describing policy capabilities, with enough information in it for multiple types of consumer. Practically, that meant adding richer data, including compatibility data, and using the schema to power a visual, form-based editor in the Admin Console.

The console reads the schema and renders the appropriate fields and validation, without anyone having to build a separate UI for each policy. Where a generated form needs extra care, we can override it with a custom editor.

Here’s an excerpt of the schema entry for the AIControls policy:

"AIControls": {
  "type": "object",
  "x-category": "Content settings",
  "x-compatibility": {
    "firefox": { "version_added": "149.0.2" },
    "firefox_esr": { "version_added": "153" },
    "firefox_enterprise": { "version_added": "149.0.2" }
  },
  // …

One schema covers all of those policies today, and a new policy gets a basic form by extending the schema rather than designing a new screen. People say the documentation is the product. In our case, the metadata is the product: like browser compatibility data, it also powers downstream documentation and enriches other products.

Who can run Firefox Enterprise

Firefox Enterprise is rolling out across Europe, with sales focused on France, Germany, Austria, and Switzerland to begin with. More markets will follow. You need an Admin Console to use it, so the way in is to request a demo.

More to come

Getting a first public release out is only the start of the work, and I’ll write more about the details as we go. If you run Firefox in your organization, or you’d like to and something is stopping you, I’d like to hear about it. You can get in touch on Bluesky or mail me.

Updated October 19, 2026: Originally, I only credited Greg for the Content Analysis integration. David co-built it, so I’ve corrected that. ↩

PSA: Cache your prettier writes

Tue, 22 Jul 2025 07:11:00 GMT

If you’re using Prettier in your projects, you might benefit from caching that’s been introduced since version 2.7 (June 2022). Let’s have a look at how it works and how much faster it runs.

Caching using the Prettier CLI

The functionality was added by @sosukesuzuki in prettier#12800, and it adds a --cache option:

prettier --write --cache ./files

You can use -w as a shorthand for --write:

# shorthand
prettier -w --cache ./files

Watch out: -c is short for --check, not --cache. Combining -c and -w doesn’t make sense (“check” and “write”), so everything under ./files will be formatted and a cache will be evicted / deleted:

# This means `--write --check`, so DON'T DO THIS:
prettier -w -c ./files

That’s a good illustration why verbose CLI options are better, especially in collaborative projects where someone else may have to guess what the shorthand means.

Prettier’s cache location

When you run Prettier with the --cache option, a cache (a minified JSON file) is created at ./node_modules/.cache/prettier/.prettier-cache, which contains details about files that have been formatted. You can also set the location to somewhere else if you want:

prettier --write --cache --cache-location=.my-prettier-cache ./files

And you can evict the cache by removing the file or running Prettier without the --cache option:

rm ./node_modules/.cache/prettier/.prettier-cache
# or
prettier --write ./files

Caching strategies

There’s two options for the caching strategy; content (the file contents) or metadata, which I believe is the file’s last modified timestamp and size. Metadata may change without file contents being changed, so caching on file contents could be slower on first run due to reading data from disk, but avoids checking and formatting files with metadata-only changes.

This appears to be inspired the ESLint caching implementation. Thanks to the open nature of the project’s development, it’s apparent that there’s minimal real-world differences in those two strategies based on cherry-picked example sources.

Don’t sweat the difference if you’re only interested in performance. If you’re running Prettier in CI with caching enabled, you want to cache based on content as you’re likely formatting a fresh clone whose ‘last modified’ timestamps are irrelevant.

Performance impact on 14,000 files

I wrote about this before; this is the outcome of enabling Prettier’s cache in mdn/content. Running prettier --write v prettier --write --cache on 14,000 files comes out like so:

# without a cache
prettier --write .  98.97s user 10.11s system 126% cpu 1:26.14 total
# with a cache
prettier --write --cache .  14.82s user 7.73s system 129% cpu 17.396 total

So in this case, we go from 90 seconds to 17 seconds, which definitely helps. And yes, I do format the whole repo occasionally when testing config changes, applying updates, and other weird scenarios.

Most authors aren’t formatting the whole repo locally very often, with pre-commit hooks running on staged files only. There’s still a lot of linting and formatting tools running during regular development due to search-and-replace changes and bulk edits, for instance.

Send it to /dev/null

Also it looks like you can shave off a precious second by sending everything to /dev/null:

prettier --write --cache . > /dev/null  14.74s user 7.29s system 134% cpu 16.424 total

Or by disabling logging:

prettier --write --cache --log-level=silent .  14.65s user 7.57s system 135% cpu 16.428 total

Job well done

Well done to the author and the maintainers on the improvements. GitHub says there’s 9.9 million projects using Prettier, and the number is likely way higher, so I think there’s a serious chunk of developer years saved and hours of CI avoided through good old caching. Congrats :clap:, and happy formatting!

Using BCD to spot missing MDN Web Docs gaps

Thu, 17 Jul 2025 19:13:00 GMT

I built a small proof-of-concept page that lists BCD features without MDN Web Docs pages. I deployed it at bcd.bsmth.de/ so you can have a look and see if you want to fill gaps in web documentation with us. It’s far from stable and may change at any point, but this post describes how it works and why I built it.

What is BCD?

MDN Web Docs reference pages have tables at the bottom that show Browser Compatibility Data (BCD) for technologies like HTML, CSS, JavaScript, and others. Previously, this data was maintained in pure HTML tables at the bottom of each MDN article, right after page content.

Around July 2017, most of this hand-curated information was converted from HTML to JSON, decoupling this support information from documentation. The browser compat information landed in a repo called mdn/browser-compat-data, which made maintenance a lot smoother and usability a lot more flexible. To make this data available in projects programmatically, a Node.js package is built from the browser-compat-data repository and published to npm.

Data from mdn/browser-compat-data powers a lot of tools, such as compatibility hints in your IDE, on Can I Use, powering Baseline, and many other tools for web development.

Using BCD in a project

I’ve contributed around 70 pull requests to BCD so far, most of which are about HTTP features and other technologies I touch when documenting release notes for Firefox. What I also like about BCD is that you can pull it into your projects from npm:

npm install @mdn/browser-compat-data

And you can find out browser support for features like Temporal.Duration like so:

import bcd from "@mdn/browser-compat-data";

const releaseDate = new Date(bcd.__meta.timestamp);
console.log(`BCD release: v${bcd.__meta.version}, ${date}`);
// BCD release: v6.0.32, Tue Jul 15 2025 18:24:38 GMT+0200 (Central European Summer Time)

const temporalSupport = bcd.javascript.builtins.Temporal.Duration.__compat;
console.log(temporalSupport);
//{
//  mdn_url: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration',
//  source_file: 'javascript/builtins/Temporal/Duration.json',
//  spec_url: 'https://tc39.es/proposal-temporal/#sec-temporal-duration-objects',
//  status: { deprecated: false, experimental: true, standard_track: true },
//  support: {
//    chrome: { impl_url: 'https://crbug.com/42201538', version_added: false },
//    firefox: { version_added: '139' },
//    safari: {
//      impl_url: 'https://webkit.org/b/223166',
//      version_added: 'preview'
//    },
//   ...

There’s lots of reasons why knowing browser compat information is useful in projects, the most obvious one being static analysis of your code to give hints about feature support during development.

Detecting missing documentation

One interesting thing is that each of the BCD entries has an mdn_url, for example the javascript.builtins.Temporal.Duration entry above has this member:

// mdn_url: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration',

And if you look at that MDN page, you can see this mirrored in the Temporal.Duration page front matter:

title: Temporal.Duration
slug: Web/JavaScript/Reference/Global_Objects/Temporal/Duration
page-type: javascript-class
status:
  - experimental
browser-compat: javascript.builtins.Temporal.Duration

So now we have a mapping between MDN, which contains the documentation, and BCD, which contains support data, identifiable by the BCD key javascript.builtins.Temporal.Duration.

To build a small app with BCD data, I had a look through each of the entries and checked if it’s missing an mdn_url. This can happen if support information is added to BCD, but no documentation page for it has been written yet. So let’s try to fetch some interesting BCD entries without an mdn_url. Basically, this is all we need to check CSS properties:

for (const [key, value] of Object.entries(bcd.css.properties)) {
  const compat = value.__compat;
  // if there's support info, but no mdn_url, we're interested:
  if (compat.support && !compat.mdn_url) {
    console.log(key);
  }
}
// -webkit-app-region
// -webkit-border-horizontal-spacing
// -webkit-border-vertical-spacing
// …

And we’re more or less done! The rest of the work is adding filtering and visualization logic. It’s good to set a max depth to traverse for BCD data, because I’m generally interested in checking if properties.align-self is missing an MDN URL but not properties.align-self.stretch:

.thing {
  align-self: stretch;
}

It doesn’t make that much sense to have dedicated pages for each property’s value (like stretch) as most of these keywords can’t be explained in isolation.

Check missing MDN pages

I deployed the example app here: https://bcd.bsmth.de/ so you can have a look at the types of information you can explore. It’s less important to have MDN pages for deprecated and non-standard things, so those are hidden by default.

Bear in mind this is a basic example app to get my creative juices flowing, and obviously there’s lots of technologies to check aside from CSS. I haven’t decided if I want to have all technology categories on the same page or on separate pages (/css, /html), or to be able to switch between technology categories and focus on CSS only, JS only, HTTP only, via a dropdown. Maybe there’s a better way to display the information other than tables, like cards?

Anyway, I hope you find it interesting, and at the least you have some ideas about using BCD data in your projects. If you want to fill in some of the documentation gaps, get in touch, or just go for it and don’t forget to mention me (@bsmth).

I'm in the 512KB Club

Fri, 09 May 2025 19:13:00 GMT

Since February 2025, my website’s now listed on The 512KB Club! This collection of small websites is a showcase of what’s possible when you set out to do a lot, using only a little. Let’s see what that’s all about and why it matters.

Performant and useful websites

The 512KB Club is a curated list of websites that follow these two basic rules:

The website must be an actual site that contains a reasonable amount of information.
The total uncompressed web resources must not exceed 512KB.

In order for a website to be included, you have to run a Cloudflare URL Scan on your website and if the uncompressed size is less than 512KB, you’re eligible. Each site has to be submitted as a pull request with proof of scan results. If it passes code review, you’re listed with all the other gloriously-small websites at 512KB.club.

It’s a neat idea, and it definitely nerd-sniped me because of the performance aspect. I really like fast, slim websites, especially when they are bringing visitors in with the intention to read content.

The club promotes usability as a side-effect

The 512KB Club is interesting for a number of reasons. The first rule “must be an actual site that contains a reasonable amount of information” is crucial, and I love that this is rule #1. The 512KB Club FAQ has a highlighted section that answers why ultra-minimal link pages don’t qualify:

The whole point of the 512KB Club is to showcase what can be done with 512KB of space. Anyone can come along and make a <10KB site containing 3 lines of CSS and a handful of links to other pages.

That’s NOT a good showcase of what can be done with 512KB.

What we’re looking for are sites with interesting design concepts that prove 512KB is a load of space that you can do so much with.

So this is not about code-golfing a page down to an absurd level, or sending plain text to clients in HTTP responses (small, but ugly?). The goal is to be deliberate with the resources you’re using during development and what you send down the wire.

A lot of modern websites are slow and massive, and this is consistently trending upwards since the dawn of time:

The 512KB Club bucks this trend to show what developers can do with a small footprint, leaving plenty of breathing room.

Another side-effect of chasing this metric is that it nudges people towards designing accessible websites. Accessibility shouldn’t be a side-quest, but browsers are most efficient when they’re parsing and rendering properly-structured HTML, CSS and JavaScript.

Libraries and other tools (not to mention AI-generated slop) often produce garbled, generated content in a way that negatively impacts accessibility. If everything is flat <div>s all the way down, assistive technologies like screen readers can’t present sensible information for people to coherently navigate.

The bottom line is that a stripped-down, standards-based approach to web dev may be less exciting to build with, but it’s what the most amount of clients can support, enabling more people to use and enjoy your projects.

Some picks from the 512KB Club

It’s no surprise that a lot of these pages are personal blogs, as this type of website lends itself to being hacked on. A personal blog is great not only for communication, but for testing out different technologies, coding, or design patterns. Here’s a few others I chose from the club in no particular order:

cli.club [25.5Kb]: A collection of CLI software covering a wide range of categories from messaging, music, text editing and more.
mattstein.com [206Kb]: Matt’s a designer, developer, and former technical writer who has a great site that showcases a lot of projects and talents.
bestmotherfucking.website [5.4Kb]: I can’t really omit this one due to infamy. One to avoid if you’re sensitive to profanity, but this made a splash around 2017 in reaction to bloated web trends.
silviamaggidesign.com [311Kb]: Designer and Accessibility Specialist Silvia Maggi has a website with a nice aesthetic that’s also easy to read and navigate.
lichess.org [495Kb]: The awesome Lichess is a free/libre, open-source chess server powered by volunteers and donations. It just scrapes into club membership with 17Kb to spare.
slowernews.com [169Kb]: A curated site of notable news items, things likely to trend on Hacker News. It looks like new content arrives a few times per month.

Aside from these, I would recommend taking a look through some of the pages at random as the directory is a mix of different types of pages, and it’s a unique way to discover something new. I think the best ones live somewhere in the middle in terms of page weight, as sites around 200Kb will be balancing performance and delivering engaging and nice-looking content.

Keeping it performant

My PR was merged on February 13th, so a big thanks to the maintainers for including me. The 512kb Club has since changed ownership to Brad Taunt and is now managed on SourceHut. I’m delighted to be part of the club so that I can now show off this beautiful Orange Team banner on my site:

Thanks a lot for reading! Feel free to get in touch on Bluesky if you have any thoughts or recommendations.

2024: MDN HTTP content, GitHub, Firefox

Sat, 11 Jan 2025 10:13:00 GMT

It’s that time of the year again - 2024 is ~~coming to a close~~ wrapped. Let’s look at what I did over the last year on GitHub. I’ll share some stats that I collected from my work, visualize the data to understand it a little more, and show the categories and types of work I focused on.

MDN GitHub PRs in 2024

A lot of the work that goes into keeping MDN running happens in our GitHub organization, which has about 40 active repos. As is tradition, let’s have a look at the count of my PRs in these repos each month:

March 2024 was the busiest month in terms of PRs opened, with a total of 35 PRs landing (down from the 44 I made in August 2023). May and October 2024 seemed like they were quiet enough, but as usual opening PRs is not everything we do. There’s a lot of housekeeping of the GitHub organization, discussions, our other online community spaces, etc.

Get this data

You can get this data (at least the public bits) yourself using the gh CLI:

gh api --paginate \
  "search/issues?q=author:bsmth+org:mdn+type:pr+created:2024-01-01..2024-12-31" \
  --jq '.items[] | [.title, .number, .state, .html_url, .created_at] | @csv' \
  > 2024_bsmth_prs.csv

PRs by repository

I created 274 PRs across 23 public MDN GitHub repositores in 2024. This is slightly lower than last the 281 PRs in 25 repositories from 2023, but it’s actually surprisingly close. Usually, I’m working on mdn/content and mdn/browser-compat-data repos, but in 2024, I did a lot of editing on the MDN Blog. After the blog, the shared-assets repository was the number 3 repo that I contributed to, and I’ll go into more detail on that later.

The year of conventional commits

I first started trying conventional commits to make my PRs a bit more structured somewhere around 2021. Over the years, I see more and more projects using this as a way to generate release notes and otherwise categorize changes, so I do this regularly now. In 2024, I did a lot better at sticking to this pattern. I’ve said it before, it’s hard to use conventional commits when you work on a documentation project - everything is docs: on MDN, so I have used relnote: for Firefox, and a scope like docs(http): for technology categories.

Here’s a breakdown of the types and scope of MDN PRs in 2024:

It appears I’m a fan of chore: commits, and that’s a bit of a catch-all for “maintenance”, but there’s a lot of it, so it deserves to be noted. This chart also highlights that HTTP was the biggest technology category I worked on, which is a relief, because it was my goal for Q3 and Q4 in 2024, which I’ll go into in the next section. PRs using feat: are usually additions of pages or code, so there was a good amount of new content added for HTTP docs.

2024 goals and themes

I had three main goals that my work was guided by:

MDN HTTP documentation
Maintenance & chores
Firefox release notes

Let’s take a look at these categories, what they are, why they’re important, and a few highlights from each.

MDN HTTP documentation area

I wrote a good summary of these changes for the MDN 2024 recap. It’s a topic I love, because HTTP is what keeps the web humming, powering data exchange between people, servers, browsers, and machines.

MDN’s HTTP section has over 300 pages, made of 61 response status codes (like 200 (OK) or 418 (I’m a teapot)) and 148 HTTP headers for sending metadata and instructions back and forth, including Content Security Policy and Permissions Policy. Guides describe HTTP’s evolution from version 0.9 to HTTP/3, covering topics from basic usage to crucial mechanisms like caching.

The main point of the HTTP work was to update and improve examples, remove obsolete content, and standardize formatting across the entire section. I didn’t get to everything, and there’s some stragglers still on my list to fix (HTTP/1.1-specific concepts) but I’m very happy with the progress, and the positive feedback from our readers is up 10% (absolute) in this section since I started.

In the MDN summary post, I highlighted the Server-Timing HTTP header as interesting, you can use to surface server metrics to a client:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 123
pubDate: Fri, 03 Jan 2025 10:41:21 GMT
Server-Timing: custom-metric;dur=123.45;desc="My custom metric"

--- response body ---

For example, the BBC iPlayer is using the Server-Timing header to send performance metrics about the service, visible in the Network > Timings panel in Firefox. The main point of sending these metrics is to grab them via the Server Timing API so you can act on server-side metrics in the same way as all the other metrics processed with the Performance API.

Most of the work was adding content (feat), and tidying up and fixing docs (chore), but there were some release notes for Fx 132 that were interesting to work on, too.

Reading: For brushing up on HTTP topics, I enjoyed HTTP/2 in Action by Barry Pollard (@tunetheweb). If you’re familiar with HTTP/1.1 and want to dive into how the successive protocol(s) work, I can really recommend the book. Sending a big thanks to Barry.

Mermaid diagrams and shared assets

I’ve championed SVG and mermaid syntax for sequence diagrams on MDN, mostly for maintenance reasons, as it makes it easier to store sources for images that we usually need to update later. Binaries and images in documentation are something to be really careful about adding, because they very often cause heartache. The worst offenders in docs are screenshots of code or screenshots of products or software UIs.

There’s typically always a better alternative than screenshots. For code, add actual code blocks to your prose so you can detect, lint, spellcheck, and update them easily, among other reasons. For product screenshots, like guides on setting up hosting on a specific provider, these go out of date almost instantly - official documentation is usually better to link to instead. I try to stick to SVG, where possible, but there are always exceptions (like fancy interactive diagrams), so it’s also good to be flexible when needed.

I pushed a lot for images to be stored in a shared-assets repository, which allows us to reuse images instead of duplicate them in the source, and these are easier to write, read, maintain, and they look nice, too.

GitHub chores & maintenance

As usual, there’s a ton of ad-hoc, unplanned work that keeps us extremely busy. We try very hard to keep up with everything that’s happening in the MDN GitHub organization, which includes moderating issues, pull requests, and discussions, replying to questions, talking to our community, partners, readers and contributors. I hope we’ve managed to keep MDN inviting for people to learn and contribute, as well as engaging to work on for new and long-time collaborators. We all love maintaining MDN as much as people love reading it, so I hope that shows.

Firefox release notes

The MDN team document each Firefox release with release notes specifically for developers. You can find everything in the Firefox release notes for developers pages. We also document Experimental features in Firefox for things that are only available behind a preference (though configuration). This might be interesting if you’re looking to try out new features before they’ve landed in stable releases. One of the notable changes was documenting that HTTP/2 Server Push is now deactivated by default in most major browsers.

Writing about the web

Lastly, these are things I wrote about on the MDN blog:

Getting hands-on with Rust

In February 2024, I took a 3-day “Introduction to Rust” course run by Florian Gilcher of Ferrous Systems GmbH. My prior experience was documenting a Rust client for a time series database, and refreshing the Compiling from Rust to WebAssembly tutorial on MDN. In the course, we built a TCP server which was challenging, but great fun. I learned a lot, and I plan to put some of this to use in MDN’s new build system, rari.

That’s a wrap

We made it to the end of my 2024 wrap-up post. I want to send a big thanks to Ruth John and the rest of the MDN team for the support and guidance all year. I wouldn’t have landed all my HTTP work if it wasn’t for Hamish - thanks for the patience!

Thanks a lot for reading, and let me know what your thoughts are, if I missed something, or if you have any other suggestions. Feel free to get in touch on Bluesky.

Intl.Segmenter for l10n in JavaScript

Tue, 10 Sep 2024 09:13:00 GMT

Earlier this year, JavaScript Intl.Segmenter gained support in all three major browser engines, meaning it’s achieved Baseline status of “newly available”. Now, your applications can natively retrieve meaningful information from strings in a variety of locales in the latest browsers.

This is great news for developers that need ergonomic l10n for locale-aware apps or UIs instead of custom handling or third-party libraries. Let’s explore what this opens up with some hands-on examples.

What is text segmentation used for?

Text segmentation is a way to divide text into units like characters, words, and sentences. Let’s say you have the following Japanese text and you’d like to perform a word count:

吾輩は猫である。名前はたぬき。

If you’re unfamiliar with Japanese, you might try built-in string methods in your first attempt. For English strings, a rough way to count the words is to split by space characters:

const str = "How many words. Are there?";
const words = str.split(" ");
console.log(words);
// ["How","many","words.","Are","there?"]
console.log(words.length);
// 5

The punctuation is mixed in with the word matches, and this will be inaccurate, but it’s a good approximation. The problem is we don’t have any spaces separating the characters in the Japanese string. Maybe your next idea would be to reach for str.length to count the characters. Using string length, you’d get 15, and if you remove the full stops (。) you might guess 13 words. The problem is we actually have 8 words in the string without punctuation:

'吾輩' 'は' '猫' 'で' 'ある' '名前' 'は' 'たぬき'

If you rely on string methods for a word count, you’ll quickly run into trouble as you can’t reliably split by specific character and you can’t use spaces as separators like you can in English.

This is what locale-sensitive segmentation is built for. The format for creating a segmenter in the Intl namespace is as follows:

new Intl.Segmenter(locales, options);

Let’s try passing the string into the segmenter with the ja-JP locale for Japanese, and we explicitly set each segment to be of word-level granularity:

const jaSegmenter = new Intl.Segmenter("ja-JP", { granularity: "word" });
const segments = jaSegmenter.segment("吾輩は猫である。名前はたぬき。");

console.log(Array.from(segments));

This example logs the following array to the console:

[
  {
    "segment": "吾輩",
    "index": 0,
    "input": "吾輩は猫である。名前はたぬき。",
    "isWordLike": true
  },
  {
    "segment": "は",
    "index": 2,
    "input": "吾輩は猫である。名前はたぬき。",
    "isWordLike": true
  },
  {
    "segment": "猫",
    "index": 3,
    "input": "吾輩は猫である。名前はたぬき。",
    "isWordLike": true
  },
  // etc.

For each item in the array, we get the segment, it’s index as it appears in the original string, the full input string, and a Boolean isWordLike to disambiguate words from punctuation etc. Now we have a robust and structured way to interact with the words that is locale-aware. The segmenter’s granularity is word in this example, so we can filter each item based on whether it’s isWordLike to ignore punctuation:

const jaString = "吾輩は猫である。名前はたぬき。";

const jaSegmenter = new Intl.Segmenter("ja-JP", { granularity: "word" });
const segments = jaSegmenter.segment(jaString);

const words = Array.from(segments)
  .filter((item) => item.isWordLike)
  .map((item) => item.segment);

console.log(words);
// ["吾輩","は","猫","で","ある","名前","は","たぬき"]
console.log(words.length);
// 8

This looks much better. We have an array with Japanese words using the segmenter, ready for adding locale-aware word count to our application. We’ll explore that use case a bit more with a small example in the following sections. Before that, we’ll take a look at the rest of the options that you can pass into a segmenter.

Intl.Segmenter options and configuration

We’ve seen above that you can split input by word according to the locale. If you don’t pass any options, the default behavior is to split by grapheme, which is the user-perceived character. This is useful if you’re doing a character count on strings in different encodings or languages where characters are made of combined characters such as किंतु in Hindi:

const str = "किंतु";
console.log(str.length);
// 5 <- oops

const hindiSegmenter = new Intl.Segmenter("hi");
const hindiSegments = hindiSegmenter.segment(str);
const hiGraphemes = Array.from(hindiSegments).map((item) => item.segment);

console.log(hiGraphemes);
// ["किं","तु"]
console.log(hiGraphemes.length);
// 2 <- looks better

The last option you might need is to segment text by sentence, which is also very convenient if you don’t want to keep track of language-specific full-stops. Some languages may use a period character ., but this is not always consistent. Let’s take the following example:

const hindiText = "वाक्य एक। वाक्य दो।"; // <- what do I split on here?

const hiSegmenter = new Intl.Segmenter("hi", { granularity: "sentence" });
const hiSegments = hiSegmenter.segment(hindiText);
const hiSentences = Array.from(hiSegments).map((item) => item.segment);

console.log(hiSentences);
// ["वाक्य एक। ","वाक्य दो।"]
console.log(hiSentences.length);
// 2

In another Hindi example, we have a character that looks similar to a pipe (।) that’s separating sentences. Now you don’t have to track Western periods or other locale-specific equivalents to split text into sentences.

If you want to check support for a locale, you can use supportedLocalesOf. This returns an array with the provided locales that are supported in segmentation without having to fall back to the default locale. The following checks if the segmenter can use Hindi, Japanese, and German for segmentation:

console.log(Intl.Segmenter.supportedLocalesOf(["hi", "ja-JP", "de"]));
// Array ["hi", "ja-JP", "de"] <- all are supported

Japanese locale word count example

If your browser supports Intl.Segmenter, you can try out the following example. There’s some Japanese text from Wikipedia, and a <pre> element below it to show the output of our script.

If you’ve followed all of the snippets so far, you shouldn’t see anything surprising here. The only difference is that we’re getting the selected text using window.getSelection before passing that into the segmenter which we’ve wrapped in a function. After that, we’re listening for the mouseup event when it’s fired on the paragraph and adding the output of the countSelection function to the <pre> element:

function countSelection() {
  const selection = window.getSelection();
  const selectedText = selection.toString();

  const jaSegmenter = new Intl.Segmenter("ja-JP", { granularity: "word" });
  const segments = jaSegmenter.segment(selectedText);

  const words = Array.from(segments)
    .filter((item) => item.isWordLike)
    .map((item) => item.segment);

  document.getElementById("word-count").textContent =
    `Word count: ${words.length}\n - "${words}"`;
}

document
  .getElementById("text-content")
  .addEventListener("mouseup", countSelection);

To try it out, select some of the Japanese text below with your mouse. On mouseup, we log the word count along with the output of the segmenter with word-level granularity:

There's a live preview of this example on the site.

That’s a wrap

Locale-sensitive text segmentation with JavaScript is now more ergonomic in the latest browsers. This feature is particularly useful for handling non-Latin languages, where the usual string manipulation methods will be unreliable. If your app needs to handle multiple locales and you’re regularly working with text manipulation, Intl.Segmenter can help segment text by word, characters, or sentences based on locale. This simplifies tasks such as word or character count, sentence-splitting, string comparisons and more advanced text processing.

Feel free to get in touch on Bluesky if you have any feedback or if you want to say hi. See you next time!

Honorable mentions: Thanks to these people who gave me a shout-out for my blog post:

JavaScript Intl Supports Word and Sentence Segmentation by Tom Smykowski on medium.com (2024)

New exclusive accordions in HTML

Tue, 13 Aug 2024 09:13:00 GMT

Giving the same name to a group of <details> elements makes them behave like exclusive accordions. This is good news for developers who have been writing custom accordions from scratch because it’s soon supported across all major browsers. Let’s explore what this means with some quick examples.

This feature’s stable in Chrome 120, Safari 17.2 and is enabled in Firefox Nightly, so you can already start trying it out. While you’re testing this out, be sure to read the accessibility concerns section.

How does `<details>` work?

If you’re unfamiliar with <details>, it’s an element that creates a ‘disclosure widget’ in which information is visible only when the widget is toggled to an “open” state. You should include in it a <summary> element, which is used for the text describing the disclosure. If you omit the <summary>, a browser-specific string like “Details” will be used by default. Click the two elements below to toggle them between open and closed states and notice the missing <summary> in the first one:

<details>
  <p>
    The response phrase for 413 "Content Too Large" used to be "Payload Too
    Large", and this message is still widely used.
  </p>
</details>

<details>
  <summary>System configuration</summary>
  <ul>
    <li>200GB RAM</li>
    <li>4PB storage</li>
  </ul>
</details>

There's a live preview of this example on the site.

Since an accordion is a series of expandable sections that allow users to show or hide content, a series of <details> elements can be used to create an accordion-like interface. Using the name attribute, these elements can mimic “exclusive accordions”, meaning only one can be open and other sections automatically close when a new one is opened.

There’s great potential for <details> elements to fit into your pages because some minimal styling can go a long way to create interactive accordions using only HTML and CSS.

<details>
  <summary>System configuration</summary>
  <ul>
    <li>200GB RAM</li>
    <li>4PB storage</li>
  </ul>
</details>

<details>
  <summary>Recommended settings</summary>
  <ul>
    <li>Extreme mode: on</li>
    <li>Raytracing: enabled</li>
  </ul>
</details>

<details>
  <summary>Other details</summary>
  <ul>
    <li>Material: Faux Leather, Metal</li>
    <li>Item Weight: 10.2Kg</li>
  </ul>
</details>

There's a live preview of this example on the site.

Using `<details name>` to create exclusive accordions

The addition of the name attribute lets you connect multiple <details> elements and make an accordion exclusive, so only one <details> element with the same name can be open at any time. The browser toggles all others with the same name to “closed”. It’s quite nice to be able to include this when you want to group multiple <details> elements:

<details name="tech-specs">
  <summary>System configuration</summary>
  <ul>
    <li>200GB RAM</li>
    <li>4PB storage</li>
  </ul>
</details>

<details name="tech-specs">
  <summary>Recommended settings</summary>
  <ul>
    <li>Extreme mode: on</li>
    <li>Raytracing: enabled</li>
  </ul>
</details>

<details name="tech-specs">
  <summary>Other details</summary>
  <ul>
    <li>Material: Faux Leather, Metal</li>
    <li>Item Weight: 10.2Kg</li>
  </ul>
</details>

There's a live preview of this example on the site.

An FAQ is one of the common uses, where the visitor can open one topic at a time:

<details name="faq">
  <summary>Can I request a refund?</summary>
  <p>
    Yes, you have up to 30 days to request a refund. See our T&C for details.
  </p>
</details>

<!-- etc. -->

There's a live preview of this example on the site.

Accessibility concerns

Scott O’Hara, Eric Eggert and Adrian Roselli have all written multiple times about accessibility issues with this pattern. Notably, widgets can’t tell you how many disclosures there are and your current position within a group, nor can you ‘expand all’ and ‘collapse all’ widgets. Search is also not handled for collapsed widgets, so a CMD + F won’t match inside a collapsed widget. :weary:

Others, like HSBC Accessibility Hub and Florian Schroiff from A11Y Collective lists <details> and <summary> as a good implementation example and says they “offer a semantic and accessible solution with less code” so there are mixed opinions whether promoting this pattern is a good thing.

I lean towards Florian’s thoughts here, and that browsers should fill the gaps in poor and undefined behavior rather than hope good custom implementations propagate everywhere. There are a lot of ways to create this pattern, and I think our best bet is native browser behavior, which will probably be used off-the-shelf in most cases and reach the most amount of people.

These two examples were referenced in discussions if you want to have a look at accessible accordions that don’t use <details> and <summary>:

ARIA Authoring Practices Guide Accordion Example on w3.org
U.S. Web Design System (USWDS) Accordion on designsystem.digital.gov

That’s a wrap

With more support landing for this feature in more stable browsers, it’s a good indicator that the web platform is providing better functionality for features that web developers have had to write themselves. If you’re looking for a polyfill, there’s a great post by Bramus, which includes a polyfill for browsers that don’t support this yet.

Feel free to get in touch on Bluesky if you have any feedback or if you want to say hi. I hope you enjoyed this post and you’ll get more mileage out of the <details> element, which is a flexible and useful element for a lot of cases. Don’t get too lost in the <details> and see you next time!

New JavaScript Set methods

Wed, 26 Jun 2024 09:13:00 GMT

There’s some fresh JavaScript Set features that have just achieved cross-browser support, so let’s have a look at what they can do. Read on if you’re new to Set in JavaScript and you’re curious how to use these new JavaScript methods. I’ll highlight some advantages with basic examples to show why you might reach for these instead of building your own implementations.

What’s new in Set methods?

For those of you looking for the TL;DR, here’s the gist of new methods that have cross-browser support:

intersection() returns a new set with the elements that are in both this set and the given set.
union() returns a new set with all elements in this set and the given set.
difference() returns a new set with elements in this set but not in the given set.
symmetricDifference() returns a new set with elements in either set, but not in both.
isSubsetOf() returns a boolean indicating if all elements of this set are in a another set.
isSupersetOf() returns a boolean indicating if all elements of another set are in a this set.
isDisjointFrom() returns a boolean indicating if this set has no elements in common with another set.

If you’re confused, don’t worry, we’ll describe what they do in the following sections. In a nutshell, each of these methods are used to check what the contents of a set is compared to the contents of another set.

What is a JavaScript Set?

A set is similar to an Array, except that each value can only be stored once. To demonstrate this, we can take a list of items, add them all to a set, and then inspect the results of the set. Let’s see how these work in the following example:

<div id="container">
  <div>
    <span>My list</span>
    <ol>
      <li>apple</li>
      <li>pear</li>
      <li>carrot</li>
      <li>pear</li>
      <li>apple</li>
      <li>yoshi</li>
    </ol>
  </div>
  <div>
    <span>My set</span>
    <ol id="set"></ol>
  </div>
</div>

Let’s grab the <li> items, add them all to a new Set, and put them under <ol id="set">:

const allListItems = document.querySelectorAll("li");
const setList = document.getElementById("set");

const mySet = new Set();
allListItems.forEach((item) => {
  mySet.add(item.textContent);
});

// List the set contents in new <li> elements:
mySet.forEach((item) => {
  const li = document.createElement("li");
  li.textContent = item;
  setList.appendChild(li);
});

In the combined output, we have two ordered list elements. The <ol> on the right is the contents of the <ol> list on the left, but it’s been converted to a set. We have all duplicates removed from the list because we’re guaranteed that a set is unique:

There's a live preview of this example on the site.

This might not look like much in a small example such as this, but it’s really convenient to have a built-in way to make unique collections of items, especially over larger data and more complex data types and objects. For example, consider that you can add elements to a set like so:

const dogs = new Set();
const yoshi = { name: "Yoshi", personality: "Friendly" };
dogs.add(yoshi);

It’s also typically faster to check if an element is in a set as opposed to in an Array, so this fits use cases where you have a large data structure and you need to keep an eye on performance of lookups. You can also compose new sets with specific logical properties based on existing sets, and we’ll take a look at some examples of that below.

We’ll be covering all of the new methods below, but if you want to see everything you can do with a Set, check the Instance methods documentation.

Union of two sets

A union is a good place to start off if you’re not familiar with sets. With the union, we can check what elements are in ‘either or both’ sets. In the example below, we have two lists and we want to make a third one that contains all items from both lists, but without duplicates:

<div id="container">
  <div>
    <span>Set one</span>
    <ol id="set-one">
      <li>apple</li>
      <li>banana</li>
      <li>pear</li>
      <li>carrot</li>
    </ol>
  </div>
  <div>
    <span>Set two</span>
    <ol id="set-two">
      <li>banana</li>
      <li>peach</li>
      <li>plum</li>
      <li>apple</li>
    </ol>
  </div>
  <div>
    <span>Union set</span>
    <ol id="union"></ol>
  </div>
</div>

const listOneItems = document.querySelectorAll("#set-one li");
const listTwoItems = document.querySelectorAll("#set-two li");
const allListItems = document.querySelectorAll("li");
const unionList = document.getElementById("union");

// Create sets for each list
const set1 = new Set();
const set2 = new Set();

// Add list items to each set
listOneItems.forEach((item) => {
  set1.add(item.textContent);
});
listTwoItems.forEach((item) => {
  set2.add(item.textContent);
});

// Create a union of both sets
const unionSet = set1.union(set2);

// List the items in the union
unionSet.forEach((item) => {
  const li = document.createElement("li");
  li.textContent = item;
  unionList.appendChild(li);
});

There's a live preview of this example on the site.

We’re using the HTML textContent of each list item so we have sets of strings, but you can see how this can be powerful if we consider that sets can contain data types like arrays or objects.

This is helpful because we don’t need any custom implementations to remove duplicates, do equality checks, or make other comparisons. Once we have elements in a set, we know they’re all unique, and the union method is an optimized way to make a third set of (unique) items that appear in ‘either or both’ sets.

Set intersection

With set intersection, we can check what elements occur in both sets to see what the overlap is. In this example, instead of displaying the intersection set as a third list like we did with union above, we can use it to highlight elements that are ‘both sets only’:

// Make the intersection set
const intersectionSet = set1.intersection(set2);

// Loop through lists and highlight if they're in the intersection
allListItems.forEach((item) => {
  if (intersectionSet.has(item.textContent)) {
    item.className = "match";
  }
});

There's a live preview of this example on the site.

Set symmetric difference

Before we look at difference, let’s look at symmetricDifference which might sound complex, but hopefully the example below demystifies that. What the symmetric difference does is lets us check which elements are in either set, but not both.

const setNotBoth = set1.symmetricDifference(set2);

allListItems.forEach((item) => {
  if (setNotBoth.has(item.textContent)) {
    item.className = "match";
  }
});

There's a live preview of this example on the site.

If this is all new and you’re struggling to understand, compare the symmetric difference with the intersection example. You should see that the symmetricDifference method does the opposite logical operation of the intersection.

Set difference

With set difference, we can check which elements are in one set but not in another. For this example, we are creating two new sets instead of one. The first one (set1only) is created with set1.difference(set2) and what we get back is a new set of items that are ‘set one only’. We do the same with the new set set2only to find items that are in set two but not in the first one. For each list, we can use the sets created with difference to highlight list items that don’t appear in the other list.

const set1only = set1.difference(set2);
const set2only = set2.difference(set1);

allListItems.forEach((item) => {
  if (set1only.has(item.textContent)) {
    item.className = "setOneMatch";
  } else if (set2only.has(item.textContent)) {
    item.className = "setTwoMatch";
  }
});

There's a live preview of this example on the site.

Subset, superset, and disjoint from

The last of the new methods and concepts that we can explore are subset, superset, and ‘disjoint from’ methods. By now, you’re familiar with the set operations that return new sets. The subset, superset, and disjoint from methods don’t return new sets, but a Boolean value to indicate certain state or logical checks.

The first two we can look at are subset and superset. Instead of highlighting list items, we have some statements or assertions like “Set one is a subset of set two”. We then add some text (TRUE / FALSE) to the list item depending on the result of a check like if (set1.isSupersetOf(set2)):

if (set1.isSubsetOf(set2)) {
  oneSubTwo.textContent += " [TRUE]";
} else {
  oneSubTwo.textContent += " [FALSE]";
}

There's a live preview of this example on the site.

So with subset, we can check if all the items from a set appear in another set or not. With superset, we’re doing the opposite, to see if a set has all items from another set, with some additional items. Note that if the two sets are equal, they’ll satisfy both isSubsetOf() and isSupersetOf() methods:

const one = new Set([4, 8, 12]);
const two = new Set([4, 8, 12]);
console.log(one.isSubsetOf(two)); // true
console.log(one.isSupersetOf(two)); // true

The last method for us to look at is isDisjointFrom() where we can find out if two sets have no common elements. The first and second sets below are not disjoint from each other as they have one element (“C”) in common. The third set is disjoint from the other two as it has no items in common with either set:

// Assertions
const oneDisjointTwo = document.getElementById("1disjointFrom2");
const twoDisjointThree = document.getElementById("2disjointFrom3");
const threeDisjointOne = document.getElementById("3disjointFrom1");

if (set1.isDisjointFrom(set2)) {
  oneDisjointTwo.textContent += " [TRUE]";
} else {
  oneDisjointTwo.textContent += " [FALSE]";
}

if (set2.isDisjointFrom(set3)) {
  twoDisjointThree.textContent += " [TRUE]";
} else {
  twoDisjointThree.textContent += " [FALSE]";
}

if (set3.isDisjointFrom(set1)) {
  threeDisjointOne.textContent += " [TRUE]";
} else {
  threeDisjointOne.textContent += " [FALSE]";
}

There's a live preview of this example on the site.

That’s a wrap

I hope you enjoyed this post about Set methods and why I think sets are an interesting concept to understand. Feel free to get in touch on Bluesky if you have any feedback or if you want to say hi. You should be all Set for your next project, so see you next time!

Honorable mentions: Thanks to these people who gave me a shout-out for my blog post:

New JavaScript Set methods by Chris Coyier on frontendmasters.com

Page Visibility API usage & hints

Fri, 10 May 2024 10:13:00 GMT

Checking document visibility gives you insight into how visitors are interacting with your pages and can provide hints about the status of your applications. This post takes a look at what page visibility is, how you can use the Page Visibility API in your websites, and describes pitfalls to avoid if you build features around this functionality.

The Page Visibility API lets you find out the visibility of a page and set up event listeners to do something when page visibility changes. Let’s look at what page visibility means, how you can use this API, and some common pitfalls to avoid.

What’s the Page Visibility API?

The Page Visibility API was developed as a standalone specification, but it’s been incorporated directly into the HTML spec under Page visibility. This API exposes a way to determine a document’s visibility state so you can check if a web page is “visible” or “hidden”. Sounds straightforward, but pages can be “hidden” in several different ways.

A page is “hidden” if the browser window with the page is minimized, if it’s completely obscured by another application, or the user switches to another tab. Page visibility also changes to “hidden” if the operating system’s screen lock is activated, so mobile device behavior is also taken into consideration. By contrast, a page remains “visible” even when it’s partially visible on the screen.

How to check page visibility changes

You can check the visibility of a document using document.visibilityState, which will return either visible or hidden. Alternatively, you can check the value of the document.hidden Boolean property:

console.log(document.visibilityState); // "visible"
console.log(document.hidden); // false

In practice, it’s convenient to use the visibilitychange event so you can trigger logic when the visibility state of a page changes instead of checking the visibility manually:

document.addEventListener("visibilitychange", (event) => {
  // doSomething();
});

When the state changes, you can do something depending on the document.visibilityState or document.hidden Boolean:

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    // Page visibility is now 'hidden'
  } else {
    // Page visibility is now 'visible'
  }
});

It’s worth noting that there’s no document.visible, so if you’re only interested in that state, you can use document.visibilityState === "visible" (or !document.hidden):

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "visible") {
    // The page is visible again!
  }
});

Why page visibility is useful

Page visibility is useful in many cases, but the most likely fits are managing usage of compute resources, in analytics, and adding functionality that can improve user experience (UX) on a range of devices. Let’s take a look at these in more detail.

Session lifecycle in analytics

In the analytics domain, it’s common to record the point when pages change from visible to hidden. A page changing to a hidden state might be the last event that’s observable by a page, so developers often treat it as the end of the user’s session. However, this heavily depends on how you define ‘a session’. You may define a session based on a fixed period of inactivity as opposed to relying solely on ‘first page hide’. Therefore, this use case will vary according to your needs:

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon("/log", analyticsData);
  }
};

Managing resources efficiently

The use case I’m personally most excited about is the opportunity to stop doing something resource-intensive when someone is no longer viewing the page. This capability is really powerful considering that it allows us to manage client (or even server) compute or bandwidth in a deliberate way.

When it comes to managing resources, browsers already have some related features like tab unloading when system memory is critically low, and optimizing what background tabs are doing. We can still make our client-side applications more efficient, especially in areas that browsers don’t or can’t automatically handle.

For example, when a page is hidden, your app can use lower bitrate video, or throttle real-time communication (WebSockets and WebRTC). IndexedDB processes can be optimized as browsers don’t throttle these connections to avoid timeouts. You can stop invisible animations or other visual media, timers, throttle network requests, stop polling endpoints, there are a lot of opportunities for efficiency gains. You can find more information about what browsers do in the “Policies in place to aid background page performance” section on the Page Visibility API page.

Improving user experience

When the page changes from hidden to visible, we could assume that a visitor has returned to our page, so we can restart anything that we may have paused when the page was hidden. However, there are a few logical traps, especially concerning media, that you could fall into. Therefore, you need to be careful when resuming actions in such cases. We’ll look at examples of this in detail in the next section.

Patterns to avoid with page visibility checks

User freedom is essential for your pages, so this API should be used with care to ensure your visitors have agency while browsing. In other words, give people control over when to start, resume, and skip media on your pages. You also shouldn’t assume that visitors want media to be paused automatically when a page is hidden. Expose a preference or allow visitors to opt-in to this kind of functionality instead.

There used to be a code snippet on MDN on the visibilitychange page that was a good example of how this API can cause usability issues. Can you spot what the problem is in the JavaScript code below?

<audio
  controls
  src="https://mdn.github.io/webaudio-examples/audio-basics/outfoxing.mp3"
></audio>

const audio = document.querySelector("audio");

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    audio.pause();
  } else {
    audio.play();
  }
});

There is an <audio> element with controls visible so the user can start and stop the media. In JavaScript, we’re looking at the visibilitychange event and doing the following:

If the page is hidden, pause the audio.
If the page is shown, play the audio.

This sounds reasonable, but there’s actually a big problem. If I navigate to the page, then switch to another tab and back again (or restore a browser window after it’s been minimized) audio will autoplay. The point is that page visibility may toggle between hidden and visible without the user ever interacting with the <audio> element.

This situation becomes even more annoying if the <audio> element is located below the fold and is not visible on page load. This is extremely frustrating if visitors need to hunt down where audio is playing after they’ve located which tab it’s coming from.

To avoid usability issues, check if someone has interacted with media before resuming playback. There may be better ways to approach this, but the fix I made to the MDN reference page example was to store the state of the audio player when the page is hidden. When the page visibility changes to visible, resume media playback only if it was playing when the page was hidden.

Let’s modify the event listener to store the audio state on page hide. A boolean playingOnHide is sufficient for this purpose; set it when the document’s visibility changes to hidden:

// Initialize as false; we're not auto playing audio when the page loads
let playingOnHide = false;

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    // Page changed to "hidden" state, store if audio playing
    playingOnHide = !audio.paused;
    // Pause audio if page is hidden
    audio.pause();
  }
});

As with document.hidden, there is no audio.playing state, so we have to check !audio.paused (not paused) instead. That means the playingOnHide Boolean can be set to whatever the value of !audio.paused is on page hide, and we’re pretty much done. The only other state the visibility of the page can be is visible, so in the else statement, we handle the playing logic:

let playingOnHide = false;

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    playingOnHide = !audio.paused;
    audio.pause();
  } else {
    // Page became visible! Resume playing if audio was "playing on hide"
    if (playingOnHide) {
      audio.play();
    }
  }
});

The finished code looks like this with a tidy little gate for checking the audio state on page hide:

<audio
  controls
  src="https://mdn.github.io/webaudio-examples/audio-basics/outfoxing.mp3"
></audio>

const audio = document.querySelector("audio");

let playingOnHide = false;

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    playingOnHide = !audio.paused;
    audio.pause();
  } else {
    if (playingOnHide) {
      audio.play();
    }
  }
});

That’s a wrap

I hope you enjoyed this post about page visibility and why I think it opens up interesting opportunities for resource management, analytics, UX, and other use cases. I’m looking forward to hearing your thoughts on different ways to use this API and what other efficiency gains developers can make use of that browsers don’t handle well.

Let me know what your thoughts are, if I missed something, or if you have any other suggestions. Feel free to get in touch on Bluesky if you have any feedback or if you want to say hi.

2023: GitHub, Interop, Firefox release notes.

Sun, 21 Jan 2024 10:13:00 GMT

Now that 2023 is ~~coming to a close~~ wrapped, I thought I’d take a look back at what I managed to achieve over the year. I joined Mozilla in 2022 as a Staff Technical Writer on the MDN team, which made 2023 the first full year that I focused entirely on MDN Web Docs. In this post, I’ll share some stats that I collected from my work on GitHub, visualize the data to understand it a little more, and show the categories I focused on.

MDN GitHub PRs in 2023

A lot of the work that goes into keeping MDN running happens in our GitHub organization which has about 40 active repos. Let’s have a look at the count of my PRs in these repos each month:

It looks like August was the busiest month, with 44 PRs landing. It’s also pretty noticeable when I took parental leave as my productivity is just about halved over March-April and September-October.

PRs by repository

I created 281 PRs across 25 public MDN GitHub repositores last year. The mdn/content and mdn/browser-compat-data repos are noteworthy, so we can split the chart above and highlight these against other public MDN repos as mdn/other.

Although the content and BCD repositories are usually the primary sources to add and update data, we can see from this graph that a lot of maintenance (about 30% of my work) happens in other repos, also. There is also a Blog on MDN since May 2023 that I worked on, although this repo is private for now, so those contributions are not included in these stats.

Trying to stick to conventions

I tried to stick to conventional commits whenever I could, and my diligence improved over the course of the year. In general, it’s a little tricky using the conventional commits per spec seeing as everything is arguably docs: on MDN, so I’ve expanded on this scheme to use relnote: for Firefox, and subcategories like docs(HTTP): for site sections. It’s not perfect, but it helps to get a rough overview of the types of work landing based on commit data:

2023 goals and themes

I had three main goals that my work was guided by:

Interop 2023
Firefox release notes
General maintenance & GitHub chores

Let’s take a look at these categories, what they are, why they’re important, and a few highlights from each.

Interop ’23

Our team included Interop ’23 as part of our high-level documentation goals for the year. The intention is that the focus areas in Interop 2023 have the corresponding MDN docs audited for freshness as the features and their support are evolving. If you want to see other Interop 2023 tasks and PRs, check this tracking issue on GitHub.

Interop 2023 is a cross-browser effort to improve the interoperability of the web — to reach a state where each technology works exactly the same in every browser.

A lot of features reached stable status across all major browser engines in 2023 and that meant we could remove a lot of experimental warnings and update code to use the latest syntax.

By chance, I happened to work quite a lot on CSS colors and this turned out to be a really interesting deep dive for me. I’ve written a fair bit about CSS colors in 2023 here and on the MDN blog; you can find out more in my posts about CSS.

Here’s some pull requests with some of my highlights:

Diving into CSS custom properties: Adding more details to the “Using CSS Custom Properties” page
Making display more versatile: Expand on usage of multi-keyword display values

Firefox release notes

A yearly goal for the MDN content team was making sure that the Firefox release notes for developers were updated in time for each stable release. The ‘definition of done’ for each task is that there is a release note for changes affecting web developers, browser compatibility data is updated, and that corresponding reference and learning resources are audited and updated when necessary.

Similarly to Interop, closely following the Firefox release process helps us keep docs fresh and gives the team insight on how the web platform is changing month over month. Features are added or removed in Firefox based on relevance and developer feedback along with maintenance costs and other rationale, so keeping tabs on these changes helps us understand which features are noteworthy and why.

Here’s a filtered list of PRs by month with Fx or relnote in the title:

The August peak now makes sense as I took on a lot of the Firefox 117 release tasks for CSS, HTTP, SVG, Web APIs, and DevTools changes.

Highlights:

Highlighting new color functions: Support for color(), lab(), lch(), oklab(), oklch() in Firefox 117
CSS examples made clearer: Adding examples for ‘auto none’ in CSS ‘contain-intrinsic-size’ property for Firefox 117

GitHub chores & maintenance

If I was to categorize the ad-hoc or unplanned work I do, it lands under general maintenance and upkeep of the MDN GitHub organization. The goal of this work is to keep our code repositories healthy and continuously improve the experience of contributing to MDN.

This work typically involves improvements and fixes for CI and shared workflows (GitHub actions), improving Community Standards (READMEs, CONTRIBUTING.md, contribution guidelines, etc.), and other admin work.

Highlights:

mdn/content fix(CI): reorder workflow steps, pass in .nvmrc config
mdn/mdn-contributor-spotlight chore: Add template docs and workflows
mdn/community-meetings feat: Add minutes from 2023-12-11 call

That’s a wrap

We made it to the end of my 2023 wrap-up post: Thanks a lot for reading. This was a great housekeeping task for me to see where my work lands and to course-correct for 2024.

Let me know what your thoughts are, if I missed something, or if you have any other suggestions. I haven’t made the raw PR stats available (although it’s all public data), but I’m happy to add them to this post if anyone is interested in taking a look for themselves. Feel free to get in touch on Bluesky if you have any feedback or if you want to say hi.

JavaScript console methods

Sun, 03 Dec 2023 07:30:00 GMT

Earlier in the year, I wrote about using grep on the MDN Blog for code search under the “developer essential” category. I categorize it this way because I think it will give people unfamiliar with grep a massive productivity boost and exposure to skills like working on the command line and regular expressions. This looks like it’s becoming a series of posts on “essentials” (or what I think are incredibly beneficial skills, at least) for working effectively as a web developer.

The next topic I thought would be interesting was JavaScript console methods. People who work extensively with JavaScript might not even be aware that the console has capabilities that could eliminate the need to write custom handling or use third-party libraries. What’s better than using built-in functionality that works everywhere to cut out unnecessary code?

In the blog post, I covered some examples of what the console can do and some of the lesser-known methods that you might find helpful or just plain fun:

const dogs = [
  { name: "Yoshi", color: "Black", personality: "Calm" },
  { name: "Melanie", color: "Brown", personality: "Hyperactive" },
  { name: "Peppers", color: "white", personality: "Unpredictable" },
];

console.table(dogs);

Check out the post I wrote for the MDN Blog that describes some fun and exciting console methods. Everyone will find something new to use in projects, whether you’re a beginner or an advanced JavaScript developer. Here’s what the post covers:

:rotating_light: logging levels to indicate severity
:100: counting events & adding timers for events or tasks
:open_mouth: displaying data as tables
:clipboard: grouping logs by topic, task, or event type
:microscope: exploring application traces using the console
:see_no_evil: clearing out the console if logs become noisy or distracting

console.warn("You might not be subscribed to the MDN Blog RSS feed.");

const errorMsg = `Oops, we're on ${document.location} instead!`;
// If the assertion is true, nothing happens
console.assert(document.location == "https://bsmth.de", { errorMsg });
// Assertion failed:
// Object { errorMsg: "Oops, we're on https://bsmth.de/mdn-blog-javascript-regex-reference/ instead" }

If you liked the post, you should also see the JavaScript regular expression updates. Let me know what you think about the MDN blog post and if you use grep for something fun. Leave a comment below or get in touch on Bluesky.

console.info("Happy hacking!") :computer:

Learn grep for powerful code search

Mon, 10 Jul 2023 05:30:00 GMT

A big part of web development extends beyond the usual suspects of HTML, CSS, JavaScript, and HTTP. You need to glue these building blocks together, and for that, you need to be able to use tools, systems, and other fundamentals.

Aside from soft skills, understanding how files and file systems work, using shell scripting languages, working with IDEs, and managing the actual code are developer essentials.

I think that search is one of the most important skills when it comes to working with code. I make searches using grep many times a day to look for all kinds of patterns in code and documentation. If I find a typo in a document on MDN, I’ll use grep to search all of MDN Web Docs to see if there are others like it or if it’s copy-pasted elsewhere. For code, I’ll look where variables are defined in a project, error messages in logs, patterns that are deprecated or need to be refactored, and so on.

# find "the the " repeated word typo
grep -r "the the " files
# path/to/index.md: and upper limit or the the keyword `auto`.

# find legacy rgba() CSS function, ignore node_modules
grep -r --exclude-dir=node_modules "rgba(" ./
# ./files/path/to/index.md:  background: rgba(0, 0, 0, 0.3);

The post I wrote for the MDN blog will get you started with interesting and fun examples to try. Check it out if you’d like to read about:

what grep is and how to use it
piping commands into grep
some real-world timings to show how fast it is compared to alternatives
why I think learning grep will give you a significant skills and productivity boost

# time how long it takes to grep for a pattern and
# perform a line count on the output
time grep -r "\`\`\`plain" files/en-us/web/ | wc -l
     252
grep -r  0.43s user 0.29s system 99% cpu 0.730 total
wc -l  0.00s user 0.00s system 0% cpu 0.729 total

Happy /(grep|hack)ing)/ :mag:

CSS hues with hsl()

Fri, 30 Jun 2023 08:33:16 GMT

After deep-diving into color functions like lab(), lch() and color(), I realized that hue was actually a great topic to update across MDN Web Docs. I am pretty happy with the outcome and there was a lot of interesting findings, updated pages, and new examples that should help beginners get started using hues in CSS.

#color-wheel {
  border-radius: 50%;
  background: conic-gradient(
    in hsl longer hue,
    hsl(0deg 100% 50%),
    hsl(360deg 100% 50%)
  );
}
/* For browsers that don't support hue interpolation methods */
@supports not (background: conic-gradient(in hsl longer hue)) {
  #color-wheel {
    background: conic-gradient(red, yellow, green, cyan, blue, magenta, red);
  }
}

There's a live preview of this example on the site.

If you want to learn about hue in CSS, the post on the MDN Blog describes what hues are, why you might use them, and other practical hints to get started. Check it out if you’d like to read about:

what hues are and why they’re useful
how to use hsl() including:
- the basics of how hsl() works
- playing with hues in CSS
- seeing how to control saturation and lightness
- using variables to change hues in multiple places

MDN Web Docs hue updates

If you want to see the specific PRs I worked on (mostly relating to CSS Colors Module Level 4) here’s the GitHub links:

Hue: docs(CSS): add examples of hue interpolation methods, add hue page
Fx111: color(), lab(), lch(), oklab(), oklch() support
- MDN Content & Browser Compat Data
Fx113: CSS Color lvl 4 features are enabled by default
- MDN Content & Browser Compat Data

You should see plenty more support information and lots more colorful examples on MDN that I hope inspire readers:

<div id="container"></div>

const container = document.getElementById("container");
const loopLength = 80;
// Loop to create 40 div elements
for (let i = 0; i < loopLength; i++) {
  const divElement = document.createElement("div");

  divElement.id = `hsl-${i + 1}`;

  // Calculate the background color based on the loop index
  const hue = Math.round((i / loopLength) * 360);
  const saturation = 50;
  const lightness = 50;

  divElement.textContent = `hsl(${hue} ${saturation} ${lightness})`;
  divElement.style.backgroundColor = `hsl(${hue}, ${saturation}%, ${lightness}%)`;

  // Append the div to the container
  container.appendChild(divElement);
}

There's a live preview of this example on the site.

I already mentioned in the MDN blog post, but I’d like to give a shout out to Yarusome who did a really nice job adding diagrams that explain hue interpolation methods. Big thanks for adding more colors :pray:

Let me know what your thoughts are, what I missed, and if there are some fun ways to use these new features. Share your thoughts below or get in touch on Bluesky.

JavaScript regular expressions reference docs

Wed, 24 May 2023 06:31:11 GMT

The JavaScript regular expressions (regex) documentation had a big update recently thanks to the efforts of Joshua Chen. Josh did the heavy lifting, and I was glad to give some feedback and reviews to land the changes. There are new, dedicated pages for each JS language feature for regular expressions, with information about the syntax and browser compat data, too.

MDN Blog, JavaScript regular expressions

If you want to see everything that’s changed, we published a post on the MDN Blog that covers highlights and specifics of what’s been updated. Check it out if you want to read the guides for creating regular expressions in JavaScript and other pages that cover:

flags that change how a regex is interpreted
assertions to check if a pattern matches a condition (e.g., start of a string)
atoms - the units that make up a regex pattern
other features like quantifiers (*, +, ? etc.) that help you compose patterns

Out of the examples, I highlighted a few in the blog post that I thought were nice and are useful for certain purposes. The one below is nice because it detects strings in specific scripts or writing systems without having to exhaustively specify the characters or ranges of characters that make a script:

const mixedCharacters = "aεЛ";
// I could write out everything ...
// mixedCharacters.match(/[ΑαΒβΓγΔδΕεΖζΗηΘθΙιΚκΛλ... <-- oh no

// Or use a short alias for Greek instead:
mixedCharacters.match(/\p{Script=Grek}/u); // ε
// Or a short name
mixedCharacters.match(/\p{sc=Cyrillic}/u); // Л

GitHub PRs updating JS regex

Here’s the two main GitHub PRs that we worked on to add the updates:

MDN Content: Regex reference (by Josh Cena)
Browser Compat Data: feat(JS): Add JS regex patterns

For the Browser Compat Data, I had to cover a lot of cases across multiple browsers and operating systems. I did this using Browserstack with a codepen like the one below so I could visually check for matches as a kind of smoke test. Of course, you could do asserts with test() and automate this headlessly, but this was the quickest way to check for passing cases and fill in the blanks. Sometimes simply brute-forcing the permutations of a feature is the most foolproof way:

<ol>
  <li id="backreference">backreference: "oneone"</li>
  <li id="capturingGroup">capturing group: "capturing group"</li>
  <li id="characterClass">character class: "tuv xyz"</li>
  <li id="characterClassEscape">character class escape: "1"</li>
  <li id="characterEscape">character escape: "&#9;"</li>
  <li id="disjunction">disjunction: "b"</li>
  <li id="inputBoundaryAssertion">input boundary assertion</li>
  <li id="lookaheadAssertion">lookahead assertion: "one two three"</li>
  <li id="lookbehindAssertion">lookbehind assertion: "one two three"</li>
  <li id="namedBackreference">named backreference: "**bold**"</li>
  <li id="namedCapturingGroup">named capturing group: "**bold**"</li>
  <li id="nonCapturingGroup">non-capturing group: "https://example.com"</li>
  <li id="quantifier">quantifier: "www"</li>
  <li id="unicodeCharacterClassEscape">unicode character class escape: "🍕"</li>
  <li id="wildcard">wildcard: "a"</li>
  <li id="wordBoundaryAssertion">boundary assertion: "word"</li>
</ol>

const backreference = /(one)\1/;
const capturingGroup = /(capturing group)/;
const characterClass = /([xyz])/;
const characterClassEscape = /\d/;
const characterEscape = /\t/;
const disjunction = /a|b/;
const inputBoundaryAssertion = /(^input boundary assertion$)/;
const lookaheadAssertion = /one(?= two)/;
const lookbehindAssertion = /(?<=one )two/;
const namedBackreference = /(?<bold>\*\*)(?<content>.*?)\k<bold>/;
const namedCapturingGroup = /(?<bold>\*\*)(?<content>.*?)\k<bold>/;
const nonCapturingGroup = /(?:https?:\/\/)?example\.com/;
const quantifier = /w{3}/;
const unicodeCharacterClassEscape = /\p{Emoji_Presentation}/u;
const wildcard = /"."/;
const wordBoundaryAssertion = /\bword\b/;

const allRegexFeatures = {
  backreference,
  capturingGroup,
  characterClass,
  characterClassEscape,
  characterEscape,
  disjunction,
  inputBoundaryAssertion,
  lookaheadAssertion,
  lookbehindAssertion,
  namedBackreference,
  namedCapturingGroup,
  nonCapturingGroup,
  quantifier,
  unicodeCharacterClassEscape,
  wildcard,
  wordBoundaryAssertion,
};

// get all list items
const listItems = document.querySelectorAll("li");
// loop through all list items
listItems.forEach((item) => {
  const id = item.id;
  // get the regex feature from the JSON dict
  const regexFeature = allRegexFeatures[id];
  const text = item.textContent;
  // match the regex feature to the text content
  const match = text.match(regexFeature);
  // if there is a match, highlight the match
  if (match) {
    item.innerHTML = text.replace(
      match[0],
      `<span class="match">${match[0]}</span>`,
    );
  }
});

body {
  font-family: monospace;
}
.match {
  background-color: cornflowerblue;
  font-weight: bold;
}

There's a live preview of this example on the site.

If you’re getting started with JavaScript and regular expressions, I hope these resources make the topic a little less scary. Let me know what you think or if I missed anything below or get in touch on Bluesky. Happy /pattern|matching/!

CSS color functions and color spaces

Fri, 05 May 2023 08:33:16 GMT

In March of this year, I was assigned a Firefox 111 release task to document lab(), lch() and color() functions that were shipping in the stable release. This was an interesting one for me to work on and I learned a lot of new things about color spaces, color science, and plenty about color in CSS.

It turns out that color in CSS is a pretty deep topic, and there’s lots of options for declaring and controlling colors that can improve how you code, and how your projects look (including better gradients):

<div class="hsl-named-longer">
  <p>HSL linear gradient</p>
</div>

<div class="lch-named-longer">
  <p>LCH linear gradient</p>
</div>

.hsl-named-longer {
  background: linear-gradient(to right in hsl longer hue, orange, yellow);
}

.lch-named-longer {
  background: linear-gradient(to right in lch longer hue, orange, yellow);
}

There's a live preview of this example on the site.

If you want to see the docs I updated, here’s the links to the GitHub PRs I worked on:

MDN Content: Relnote, examples, and docs for color functions
Browser Compat Data: relnote(Fx111): color(), lab(), lch(), oklab(), oklch() support

It should be apparent that there’s plenty of new ways to specify colors:

.more-color-functions {
  color: hwb(194 0% 0% / 0.5); /* HWB (Hue, Whiteness, Blackness) */
  color: lab(50% 40 59.5 / 0.5); /* LAB (Lightness, A-axis, B-axis) */
  color: lch(52.2% 72.2 50 / 0.5); /* LCH (Lightness, Chroma, Hue) */
  color: oklab(59% 0.1 0.1 / 0.5); /* Oklab (Lightness, A-axis, B-axis) */
  color: oklch(60% 0.15 50 / 0.5); /* Oklch (Lightness, Chroma, Hue) */
}

MDN Blog, CSS Colors (Module 4)

If you want to read more about CSS Colors Module Level 4, I published a post on the MDN Blog that covers color spaces, hues, interpolation, and other interesting topics. Check it out if you’d like to read about:

defining RGB colors in CSS
understanding color spaces
using HSL for choosing hues
what’s new in CSS Colors Module Level 4:
- color spaces and gamuts
- new color functions (functional notation)
- syntax changes for existing color functions
- how gradients in different color spaces
- hue interpolation modes in gradients

Let me know what your thoughts are, what I missed, and if there are some fun ways to use these new features. Share your thoughts below or get in touch on Bluesky.

From Google Analytics to Netlify Analytics

Sat, 27 Aug 2022 10:00:00 GMT

I decided to make the change recently to try out Netlify Analytics in place of Google Analytics. I was initially motivated to improve my website’s performance and eliminate trackers, but I’m also curious about how it is from the maintainer side. In this post, I’ll describe my motivations, what I did to get started, my initial impressions, and things I learned along the way.

What is Netlify Analytics?

Netlify is a cloud development platform for building and deploying websites with other serverless features available on top. In terms of where the company is, they’ve raised $212M in VC funding, they employ around 200 people and operate at ~$23M in annual revenue. The platform has great integrations, notably GitHub compatibility which allows you to easily connect code repositories and rebuild on pull requests, for example. Overall, I find it very convenient to use because of low-friction workflows for previewing incoming changes and quickly deploying.

In 2019, Netlify launched an Analytics service that helps you understand visits to web pages deployed on their platform. Because Netlify run the entire edge infrastructure they use to serve websites and applications, it can provide insights metrics directly from their infrastructure logs.

What’s the benefit of Netlify Analytics?

Insights and analytics are the best ways to understand who is visiting your website and what types of content is being viewed. The problem with Google Analytics is that there are clear privacy concerns with the amount and type of user data being collected, what is being done with it, who owns it and for how long.

There are many privacy-focused analytics tools available that offer better handling and control of user data. Matomo, Plausible, and Fathom are some of the most popular Google Analytics alternatives with a focus on privacy. The catch with all of these tools is they load client-side on the user’s browser when they visit your website and you still end up with a tracker.

Client-side tracking opens the door for device and user fingerprinting and other bad behavior. The number of people who use ad blockers is also growing year over year, completely eliminating the ability for trackers to collect user session data. If you run a technical blog, it would be safe to assume that over half of your readers have ad blockers installed. Privacy-focused analytics tools are a step in the right direction, but maybe user tracking can be fully avoided without sacrificing visibility on website analytics.

The bandwidth needed to load the analytics snippets results in a big performance hit. Google Analytics is added via a script which fetches tracking code from Google’s servers. The code that’s being run at page load can change dynamically depending on the types of data collection active. In my experience of using Google Analytics over the years, it seems that the footprint of the tracking code itself has increased considerably.

Measuring web performance with lighthouse

To measure user experience, I turned to Chrome’s lighthouse for page speed tests. I found their treemap to be a great way of inspecting and visualizing resource sizes beyond inspecting network requests in dev tools. This screenshot shows our baseline, with the JS resources by size from my home page as visualized in a treemap:

There’s a couple of things we can take away from this screenshot:

589 KB: the total size of JS resources
202 KB: the largest resource served is Google Analytics (top-right, blue rectangle)
0 visibility into what the GA script/tag contains
All of the other resources look more-or-less essential, to be inspected later

Migrating from Google Analytics to Netlify Analytics

There’s not much that has to be done to enable Analytics on the Netlify admin panel. Analytics is not part of their free plan, but it can be enabled as a single addon for your account starting at $9 USD per month. After it’s enabled, there’s an Analytics tab in the top right corner of the Netlify admin panel.

The first view that you get is some basic metrics of pageviews over time:

One thing you get from Netlify Analytics that you don’t get from client-side tracking is the top pages and resources not found. If we’re running our own server or cloud deploy, we would be able to see all network requests with much finer detail, but we’re balancing that with the simplicity of a completely managed service with Netlify.

From the resources not found panel, there’s a few things we can take away:

Bots seem to love looking for wordpress resources and logins
.env is what bots look for nowadays, showing how common it is for environment vars & secrets to land on the public internet
TODO: I need to set up redirects to new URLs since I redesigned the site

After Netlify’s Analytics were up and running, I removed the Google Analytics script from my pages and deployed to inspect the results. Here’s a look at the treemap view again after the migration:

We’ve managed to achieve:

202 KB: savings after Google Analytics is removed :white_check_mark:
~35% decrease in page size :white_check_mark:
100% visibility and control over the content with no third-party tracking :white_check_mark:

Incidentally, Chrome’s treemap has an Unused bytes view which shows that considerable parts of the production bundle is unused, but I have no idea what ‘unused’ means in this context or how to interpret the view. If you have some experience using this view, feel free to comment below with hints.

First impressions of Netlify Analytics

I like that I can get analytics inside a tool and admin panel that I’m already using for my ‘production deploys’. The performance benefits are great, with much faster page load times, fewer HTTP requests, and boiling less of the ocean in order to show cats with orbiting emojis. I also like that I can see what resources are missing, that helps with adding redirects for changed URLs.

The details of the analytics are not at the level you would get from Google Analytics and I was hoping for a bit more from a paid plan. I cannot create custom views, funnels, drill-down queries or any other standard view, but I think I have just enough information to make good choices.

The bot traffic is obviously not great that it is mixed in with real traffic and cannot be filtered out, but you are measuring visits from users that would otherwise be missing by the use of ad blockers. In this sense, we’re compensating in the other direction of having too much traffic shown than is realistic, but it has to be kept in mind.

I use this blog as a testbed for web development and I’m always looking to try out new tools to build, deploy and maintain websites. At first, I though $9 USD per month for very basic analytics was a bit steep, but it’s worth it for initial experimentation and the ability to share my experience. My wallet will take a hit for the sake of your privacy here.

My post-purchase rationalization is this: if you consider what you get with Netlify’s free plan with the amount of functionality that comes with it, then free plan, build minutes, previews, user management & analytics is a good deal.

Wrapping up

I have turned the switch from Google Analytics to Netlify Analytics as of a few hours ago, so I will likely revisit this topic in another post in future to see how the experience is longer-term. I’m happy with the results so far, and glad to have a site that is tracker-free, is privacy-friendly and is a bit more resource-efficient.

Thanks for reading! If you have any questions, comments, or suggestions, drop them below.

Jekyll, Amplify, GitHub actions deploys

Thu, 10 Feb 2022 08:33:16 GMT

One tech stack I like is using Jekyll to build static pages with vanilla HTML & CSS, AWS Amplify for deployments, and GitHub actions to pick up broken HTML. This entire setup is designed to be as low-maintenance as possible while remaining customizable and configurable. There’s a few benefits of using Amplify instead of GitHub pages:

Automatically deploy after commits to your main branch
Password protect pages (or branches)
Domain management via Route 53
Private GitHub repository support

Why Wordpress can be insecure

The first website I built in the mid ’90s was a simple collection of static HTML pages I used for sharing audio files. I don’t remember what kind of tooling I used to build it, but I think it involved FTP and probably had a lot of handwritten HTML. Cool. 😐

I started to use WordPress around 2005, which was a big improvement at first. I learned a lot by digging into PHP, JavaScript, managing a server and learning how SEO works. WordPress ended up being my go-to platform for about a decade right up until the point I got mercilessly hacked into oblivion.

After a thorough postmortem of the hacking incident, I narrowed the cause down to two possibilities:

An advanced persistent threat conducted a targeted cyber attack and pivoted laterally through my mainframe
Someone automated a tool like WPScan to look for insecure WP sites and walked in the back door

The sprawling ecosystem of rarely maintained PHP and JavaScript plugins¹ written by third parties makes it super simple to install unaudited code on your server. The end result for unlucky WP users is that your website gets PWNd after installing a responsive image carousel.

Why Jekyll is great for building static websites

I noticed Jekyll was being used on a lot of websites and developer documentation. I like to try out new tools quite often, so I decided to take a look for myself. The benefits started to become really obvious after a couple of days of using it, but I really enjoy it for these reasons:

No server-side complexity to serve pages or maintain
Markdown for your pages and blog content
Liquid HTML templating language
Fast build times & fast page load speed
Ruby is fun and easy to learn

I’m very happy with this setup right now as I can truly focus on the content like so many platforms and frameworks promise but never really deliver.

Getting started with Jekyll

To get started with this stack, create a new GitHub repository with the name awesome_jekyll_site (this can also be a private repository). The project setup should look like this:

gem install jekyll bundler
git clone git@github.com:{your_gh_user}/awesome_jekyll_site.git
jekyll new awesome_jekyll_site --force && cd awesome_jekyll_site
bundle exec jekyll s

A server is now running locally with your awesome new pages on http://127.0.0.1:4000:

Deploying Jekyll pages to AWS Amplify

In the AWS console, select the Amplify service and click New App -> Host web app. In the “From your existing code” section, select GitHub and click Continue.

Grant AWS Amplify access to your GitHub repository and choose the awesome_jekyll_site repo. Keep the main branch as the default and click Next.

Keep the default build configuration and click Next, review your settings and click Save and deploy. Your new site will be publicly visible at a URL in the following format:

https://{branchname}.{app_id}.amplifyapp.com

Adding a domain to these pages is simple, especially if you already have one registered via Route 53. In your Amplify app, navigate to Domain management and click Add domain.

I’m already using bsmth.de so I am excluding the root and adding my Jekyll demo pages as a subdomain. Once you’ve chosen your awesome domain, click Save.

Adding GitHub actions to deployments FTW

At this point, we have a simple Jekyll blog with automated deploys, and a custom domain with SSL certs applied. We’re in a good place in terms of keeping maintenance to a minimum, but there’s a great workflow improvement I use to catch errors before they land on public pages.

For this step, we’ll use a GitHub action with the fantastic Ruby gem html-proofer. This linter catches broken links (internal and external), missing alt tags for images, malformed HTML and more.

On GitHub, navigate to your awesome_jekyll_site repository, click Actions and select New workflow. Click set up a workflow yourself and paste the following YAML:

name: Check HTML in PRs

on:
  pull_request:
    branches: [main]
  # Allows the workflow to be run from the Actions tab manually
  workflow_dispatch:

jobs:
  jekyll:
    runs-on: ubuntu-16.04
    steps:
      - name: 🛎 Check out master
        uses: actions/checkout@v2
        with:
          fetch-depth: 1

      - name: 🚀 Cache deps
        uses: actions/cache@v2
        with:
          path: vendor/bundle
          key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
          restore-keys: |
            ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
      - name: 🔨 Build site
        uses: lemonarc/jekyll-action@1.0.0

      - name: 📉 Test HTML
        uses: chabad360/htmlproofer@master
        with:
          directory: "./_site"
          arguments: >
            --assume-extension
            --url-ignore "/example.com|twitter.com/"
            --enforce_https
            --check-html
            --check_opengraph

Click Start commit with the changes on a new branch which opens a pull request. A CI job will start and check if we have any dead or broken links.

Summary

The first CI run will take a few minutes to complete, but once Ruby dependencies are cached, the action takes around 45 seconds to build and test your website.

In this article we’ve learned how to create a basic Jekyll blog, deploy it using AWS Amplify with a domain from Route 53, and added a GitHub action that catches errors on new pull requests.

I hope you found it useful and if you end up building something using this stack, let me know on Bluesky.

There are over 55,000 WordPress plugins available as of January 2020 ↩

bsmth.de

Firefox Enterprise is here

From MDN to Firefox

What is Firefox Enterprise?

What we landed in 158

Building Firefox Enterprise

Building DLP into the browser

Describing policies with schema metadata

Who can run Firefox Enterprise

More to come

Footnotes

PSA: Cache your prettier writes

Caching using the Prettier CLI

Prettier’s cache location

Caching strategies

Performance impact on 14,000 files

Send it to /dev/null

Job well done

See also

Using BCD to spot missing MDN Web Docs gaps

What is BCD?

Using BCD in a project

Detecting missing documentation

Check missing MDN pages

See also

I'm in the 512KB Club

Performant and useful websites

The club promotes usability as a side-effect

Some picks from the 512KB Club

Keeping it performant

See also

2024: MDN HTTP content, GitHub, Firefox

MDN GitHub PRs in 2024

PRs by repository

The year of conventional commits

2024 goals and themes

MDN HTTP documentation area

Mermaid diagrams and shared assets

GitHub chores & maintenance

Firefox release notes

Writing about the web

Getting hands-on with Rust

That’s a wrap

Intl.Segmenter for l10n in JavaScript

What is text segmentation used for?

Intl.Segmenter options and configuration

Japanese locale word count example

That’s a wrap

See also

New exclusive accordions in HTML

How does <details> work?

Using <details name> to create exclusive accordions

Accessibility concerns

That’s a wrap

See also

New JavaScript Set methods

What’s new in Set methods?

What is a JavaScript Set?

Union of two sets

Set intersection

Set symmetric difference

Set difference

Subset, superset, and disjoint from

That’s a wrap

See also

Page Visibility API usage & hints

What’s the Page Visibility API?

How to check page visibility changes

Why page visibility is useful

Session lifecycle in analytics

Managing resources efficiently

Improving user experience

Patterns to avoid with page visibility checks

That’s a wrap

2023: GitHub, Interop, Firefox release notes.

MDN GitHub PRs in 2023

PRs by repository

Trying to stick to conventions

2023 goals and themes

Interop ’23

How does `<details>` work?

Using `<details name>` to create exclusive accordions