Darek Kay

Website themes with uBlock Origin

2024-02-01T11:39:16Z

Browser extensions like Stylish, Stylus or Tampermonkey make it possible to create custom website themes/skins. At the same time, I try to lower the number of add-ons that I use, mostly due to security and performance reasons. Interestingly, the uBlock Origin ad blocker can achieve similar results. We can use the style action operator to adjust the CSS of any website. Let's change the header/footer background color on this blog:

darekkay.com##.inverted:style(background-color: #2e2e2a !important)

With this technique, we can create custom website themes. Here's my dark mode skin for Hacker News:

news.ycombinator.com##body:style(color: #CCCCCC !important; background-color: #1A1A1A !important; )
news.ycombinator.com##table:style(background-color: #2B2B2B !important; )
news.ycombinator.com##input:style(background-color: #DFDFDF !important; )
news.ycombinator.com##table, tr, td, .pagetop, .score:style(color: #CCCCCC !important; )
news.ycombinator.com##td:style(border: 1px solid #2B2B2B !important; background-color: #2B2B2B !important; )
news.ycombinator.com##b:style(color: inherit !important; )
news.ycombinator.com##a, .c00:style(color: #eee !important; )
news.ycombinator.com##.c00 a:style(color: rgb(49, 140, 212) !important; )
news.ycombinator.com##.comhead, .subtext:style(color: #828282 !important; )
news.ycombinator.com##.comhead > a, .subtext > a:style(color: orange !important; )
news.ycombinator.com##.comhead font:style(color: #5a5a5a !important )
news.ycombinator.com##.c5a, .c88, .c9c:style(color: #999 !important; )
news.ycombinator.com##input:style(color: black !important; )
news.ycombinator.com##textarea:style(background-color: #E0E0E0 !important; border-left: 12px solid #CCCCCC !important; )
news.ycombinator.com##font[color="#000000"]:style(color: #a3b72c !important; )

Bonus tip: to synchronize your styles across all devices, consider hosting your rules on GitHub. You can click the "Raw" button and provide the URL as a custom filter list to uBlock Origin. Check out my styling rules and their raw version.

Video subtitles, captions, audio descriptions and transcripts

2023-12-11T14:08:34Z

As I was preparing the requirements for an accessible web video player, there was some confusion around subtitles, closed captions, audio descriptions and transcripts. In this post, I use interactive examples to show the difference. I also provide related success criteria from the Web Content Accessibility Guidelines (WCAG).

Subtitles

Subtitles are text tracks matching only spoken dialogs of an audio track. They are meant for people who perceive the audio but need the text for clarification or language translation, e.g. when watching a movie in a foreign language.

Subtitles are neither required nor sufficient to fulfil WCAG.

00:00:04.300 --> 00:00:07.000
Hello?

Closed captions

Closed captions (CC) are text tracks transcribing the information within an audio track, including dialogs, music and sound effects. They are necessary for viewers who can't perceive the audio to understand what is happening, e.g. deaf or hard of hearing people.

Closed captions are required for videos to fulfil WCAG Level A (SC 1.2.2).

00:00:00.200 --> 00:00:04.000
Suspenseful music playing. Door creaking.

00:00:04.300 --> 00:00:07.000
Female voice: Hello?

Audio descriptions

Audio descriptions are audio tracks describing visual elements of the video content, including setting, costumes, gestured or facial expressions. They help viewers who can't perceive the video to understand what is occurring on screen, e.g. blind or low-vision people.

Audio descriptions are required for videos to fulfil WCAG Level AA (SC 1.2.5).

00:00:00.000 --> 00:00:01.500
An old door opens.

00:00:02.000 --> 00:00:04.000
A decayed room in an abandoned building.

00:00:06.000 --> 00:00:08.000
Sunlight shines through a window.

Transcripts

Transcripts (transcriptions) are text versions of the audio and video content. Descriptive transcripts are needed by people who are deaf-blind and others.

Transcripts are required for videos to fulfil WCAG Level AAA SC 1.2.8.

Suspenseful music is playing.
An old door creaks while it opens.
A decayed room in an abandoned building appears.
Sunlight shines through a window.

Female voice: Hello?

Summary

Subtitles describe dialogs via text.
Closed captions describe the audio track via text.
Audio descriptions describe the video track via audio.
Transcripts describe the video and the audio tracks via text.

For pre-recorded videos containing an audio track, closed captions and audio descriptions are required to fulfil WCAG Level AA.

Building a photography website

2023-10-25T20:49:41Z

Last year, I started a photography hobby. Soon after, I've created a place where I can share some of my work, without any attention-driven algorithms dictating the terms. Here's a technical write-up of my journey.

Motivation

Why should one build a photography website in the first place?

Similar to this blog, I want to reduce my dependency on social media and third-party services. Even if I ignored Instagram's privacy issues and dark patterns, the fact they can delete my account at a whim is unacceptable. In fact, they shadow-banned my first Instagram account because of "suspicious activity". Pixelfed, a federated photo sharing platform, solves many issues of Big Tech. However, I can't guarantee the instance I chose to stand the test of time. Glass has potential, but there are some issues like no way to provide image alt descriptions.

Instead of relying on third-party providers alone, I practice POSSE: I publish photos on my own site and syndicate them to my Pixelfed, Glass and Instagram accounts. This approach brings some further advantages:

Anyone can access my photos, without the need for an account.
People can subscribe via RSS to view my latest photos, without an algorithm-driven feed.
I can use a custom, personalized design.
I can update my photos, e.g. make changes after getting more experienced with RAW development and photo editing.
I can use any aspect ratio. Instagram will often crop the image preview despite choosing "original size" on upload.
I own my content.

Inspiration

Most photography websites are from professional artists who provide a showcase for potential clients. I was looking for a more personal look and feel. Fortunately, some fellow software developers share a photography hobby: Nicolas Hoizey (my favorite site!), Moritz Petersen, Artem Sapegin, Florian Ziegler, Evan Sheehan, Greg Morris, Alan W. Smith, Hidde de Vries (write-up), Shom Bandopadhaya, Jens Comiotto-Mayer, Matthew Howell, Paul Stamatiou, Jesper Reiche, Jamie Dumont, Chuq von Rospach and Matze. All those websites helped me narrow down the features I want for my own portfolio website.

Design

As mentioned, I don't want to convey a business feeling. I want a personal website that sparks joy. I've decided to go for a pinboard design:

The background mimics a corkboard.
The photos get a big white border, simulating printed Polaroid photos.
There are three variants of a sticky tape effect.
The website uses a handwriting font ("Itim").

Previously, I have rotated the photos randomly on every build for some chaos. I loved the effect, but the rotation required the pictures to be interpolated, making them slightly blurry.

I'm sure this design will change over time — check photos.darekkay.com for the current state.

Implementation

Let's get a glimpse into the technical side.

Content management

Similar to this blog, I went with the Eleventy static site generator.

I've decided to index my photos, starting at 0001. For each photograph that I publish, there are five files:

📁 content
└─ 📁 photo
   └─ 📁 0001
      ├─ 📄 0001.11tydata.json
      ├─ 📄 0001.md
      ├─ 🖼️ 0001-medium.jpg
      └─ 🖼️ 0001-small.jpg
      └─ 🖼️ 0001-small.webp

The 11ydata.json file contains the photo metadata. The markdown file contains the actual content: title, alt description, location, publish date and a short text. The small.webp and medium.jpg images are used for the gallery and the preview page respectively. The small.jpg file is used as social image preview card, as WebP support is still lacking.

In the beginning, I was using a single photos.json to store both the metadata and content. Using Eleventy pagination, I didn't have to create dedicated markdown files. As I have started adding short descriptions to my photos, this workflow was no longer viable. But it's still a good alternative for basic photo galleries. Make sure to also check Evan's approach to use the image files as Eleventy templates.

I store the medium and small images as part of the project's Git directory. Git is not the best choice for storing binary files, but it doesn't cause any bottleneck, yet. Each photo triplet is on average 350 kB big. I could use Git LFS, but it's not worth the effort for now.

Loading performance

I've put much thought into the loading behavior to ensure a good user experience even on slow networks. I also wanted to avoid pagination and infinite scroll for the image gallery.

First, every image provides its width and height to prevent layout shifts.

Second, I use lazy loading, a performance strategy to load resources (like images) only when needed. Fortunately, most browsers support native lazy loading for images:

<img loading="lazy" [...] />

Third, the gallery serves WebP images at 75% quality. This saves around 50% of space compared to the original 85% JPEG file. I accept the quality loss for the gallery, but I still use full quality JPEG files on the individual photo pages.

The last technique is to provide a good fallback while images are still being loaded. I provide two fallbacks:

A fixed background color.
BlurHash, a compact representation of an image placeholder (also called "low-quality image placeholder").

While the JavaScript BlurHash script (1.6 kB) is loaded, we see a fixed background color:

After the script has been loaded, the BlurHash placeholder is applied:

Finally, we see the actual image:

Not everyone has JavaScript, despite many developers ignoring this fact. The nice thing about BlurHash is that it's progressively enhanced: without JavaScript, only the fixed-color fallback will be displayed.

If you like BlurHash, check out ThumbHash, which returns more detailed placeholders.

How do we test the loading behavior? Browser network simulations are useful, but not so much for local images, as they will still load almost instantly. Instead, I've created custom Eleventy middleware to delay image loading artificially during testing.

On each page, there is a link to the "previous" and "next" photo. I've implemented this using a custom Eleventy collection:

eleventyConfig.addCollection("photos", (collection) => {
  const photos = filter("content/photo/**")(collection);

  for (let i = 0; i < photos.length; i++) {
    const prevPost = photos[i - 1] || photos[photos.length - 1];
    const nextPost = photos[i + 1] || photos[0];

    photos[i].data["previousPost"] = prevPost;
    photos[i].data["nextPost"] = nextPost;
  }
  return photos;
});

I can then access the page URLs in my layout file:

<a href="{{ previousPost.url }}">Previous photo</a>
<a href="{{ nextPost.url }}">Next photo</a>

RSS

I consider RSS a must for any blog-like website. A photo gallery is no different. Here's my RSS feed. The RSS feed contains the entire post content and the small image preview. I've also styled the RSS feed, so it matches the website design.

Pixelfed, Glass, Flickr and Pinterest also provide RSS feeds.

Accessibility

I care a lot about web accessibility. I've tried my best to make sure anyone can use my website, including people with impairments or disabilities.

An important part is to provide descriptions for every image via an alt attribute. As long as there is no AI to translate a picture and its essence into words (and I don't think we'll get there anytime soon), artists have to handle this themselves. I try to describe what a photo contains, but also the feeling it conveys. This has a great side effect, as it lets me think more about my photos. I must admit, I struggle with this as much as I do with photo titles, but I think this will become easier with more experience.

Apart from that, I've followed the usual path:

Use my experience to ensure accessible implementation.
Check the website with a keyboard and with a screen reader.
Run Evaluatory to check if I've made any obvious mistake.

Pipeline

Here's my workflow pipeline for publishing a new photo, using 05.jpg as an example file:

Most of those steps are automated.

Preparation

In the first step, I strip irrelevant photo metadata using ExifTool. I leave all the data that other photographers might be interested in, e.g. aperture, exposure and ISO:

exiftool -all= -tagsfromfile @ -AllDates -Make -Model -LensModel -Artist \
  -FNumber -ISO -ExposureTime -ExposureProgram -ExposureMode \
  -ExposureCompensation -FocalLength -WhiteBalance -Flash 05.jpg

Next, I use ImageMagick to create two files: a small thumbnail and a medium-size photo:

magick convert -resize x1000> 05.jpg 05-medium.jpg

magick convert -resize x375> 05.jpg 05-small.jpg

The entire pre-processing takes one click using XYplorer, my indispensable Windows file manager.

Metadata update

The next workflow step creates an 11tydata.json file, which contains relevant Exif data and the blurhash.

I use exiftool and jq to create a temporary exif.json file containing the Exif metadata from all photos:

exiftool -ext jpg -json -FileName -all -d %Y-%m-%d content/photo -r \
  | jq 'map(select(.FileName | contains ("medium"))) | map(.+{"id": .FileName[0:4]}) | map(del(.SourceFile,.FileName))' \
  > temp/exif.json

To calculate the blurhash, I use blurhash and sharp:

const sharp = require("sharp");
const { encode } = require("blurhash");

const encodeImageToBlurhash = (path) =>
  new Promise((resolve, reject) => {
    sharp(path)
      .raw()
      .ensureAlpha()
      .resize(32, 32, { fit: "inside" })
      .toBuffer((err, buffer, { width, height }) => {
        if (err) return reject(err);
        resolve(encode(new Uint8ClampedArray(buffer), width, height, 4, 4));
      });
  });

Both results are then normalized and piped into an 11tydata.json file.

With Eleventy 2.0, it's possible to feed Exif image data into the data cascade. This approach eliminates the metadata synchronization step at the cost of having to parse all photos on every build.

Content update

Last but not least, I need to handle the content. A script creates a template markdown file that I then edit manually. While I don't always come up with an image title or description, I will always provide an alternative text as explained in the accessibility section. I include the photo location only if it's relevant.

Further steps

I'm happy to have a place to share my photos that I have full control over. It's also a nice way to see my progress as a photographer. While there are photography areas that I like more than others, I probably won't settle on a certain niche. I might introduce browsable categories someday if the number of photos becomes too overwhelming. I might also introduce filtering photos by camera or lens.

Check out my photos at photos.darekkay.com.

Delaying asset requests in Eleventy

2023-09-29T16:33:48Z

While building my photography portfolio, I've put much effort into optimizing the picture loading behavior. One technique is to provide a visual fallback as long as the images are still loading. First, a static background color included in the markup is displayed. As soon as a tiny script has been loaded, the color placeholder is replaced with a blurred picture representation. Finally, the actual image is shown.

I've noticed it was difficult to test my implementation. On a fast network, the fallback is only visible for a split of a second. The slow network simulation in the browser developer tools doesn't help much:

The JS script is small enough, so I still can't see the fixed color background.
The HTML page itself is delayed as well, which slows down the testing.

My first solution was to write a small Express server, routing my assets and artificially delaying responses. Only later I've learned that Eleventy 2.0 supports request middleware out of the box, so I've migrated my solution. Notice that Eleventy middleware is not yet documented — a GitHub issue was my main source of information.

The middleware API is similar to Express. In the following example, each asset request is delayed by one to five seconds:

const delayMiddleware = async (req, res, next) => {
  if (req.url.endsWith("/") || req.url.endsWith(".html")) {
    // no delay necessary for HTML pages
    return next();
  }

  const timeoutInSeconds = Math.floor(Math.random() * 5) + 1;
  return setTimeout(() => {
    return next();
  }, timeoutInSeconds * 1000);
};

To use custom middleware, we have to include it in the Eleventy configuration file:

module.exports = function (eleventyConfig) {
  eleventyConfig.setServerOptions({
    middleware: [delayMiddleware],
  });
}

I've extracted the delay middleware into a reusable utility that I can use in all my Eleventy projects. In the following example, I'm delaying only JPG files by one to three seconds:

const delayMiddleware = require("@darekkay/11ty/lib/utils/middleware/delay");

eleventyConfig.setServerOptions({
  middleware: [delayMiddleware({
    maxDelayInSeconds: 3,
    applyFilter: (req) => req.url.endsWith("jpg")
  })],
});

My personal one-pager

2023-07-03T19:46:39Z

I've been using "Darek Kay" as my pseudonym since school. My surname was long and difficult to pronounce, so I've been mostly using it in a formal context. Last year, I changed my legal name, which also influenced my online presence. Due to the change, looking up my new name via search engines returned mostly irrelevant results. To make things worse, the top search results included pictures of a wanted fugitive (not kidding). I've decided to build a personal one-pager to prevent identity mistakes. Fortunately, firstnamelastname.com was still available, so here it is: dariuszwinkler.com.

I like reading write-ups about building personal websites, so here's mine.

Content

I consider my new website an entry point for anyone who looks for a brief overview about who I am. The content is short:

My legal name
My pseudonym
My main professions / hobbies with links
A handful of social media links

It's strange to reduce myself to a few keywords, but the external links provide more information.

Tech stack

The website is made with pure HTML and CSS, without JavaScript. I'm not a purist and I love all my over-engineered projects, but there is no need for anything special for a single web page that I'm not planning to update frequently.

I did opt-in for a custom web font, though: "Patrick Hand SC". It fits the playful design.

Bubbles

The overall design is inspired by the blog from Ana Rodrigues. I love the whimsical, hand-drawn look and feel:

I was especially intrigued by the bubbles. To my surprise, the first bubble is done with pure CSS. I've learned that border-radius supports a / notation:

.bubble {
  border-radius: 34% 60% 42% 72%/71% 40% 60% 40%;
}

The specification explains:

The first value is the horizontal radius, the second (is) the vertical radius. If the second value is omitted, it is copied from the first.

The browser support is excellent, including IE9.

My next thought was: can I animate the border radius? You bet!

40% 60% 28% 72% / 71% 40% 60% 29%

I use this technique to turn the bubbles into ellipses on hover/focus.

Background

I wanted a subtle yet interesting background. I like the triangle pattern from Dave Gamache:

I shamelessly copied their idea and drew an SVG pattern:

It took me a few tries to get a random yet balanced pattern. My tip is to draw big triangles first and then fill in smaller triangles. I also think isosceles triangles look better than equilateral triangles.

SEO

I haven't done anything special to boost my site, apart from following best practices. After a few months, Google ranks my website third, right after my LinkedIn and Xing profiles. Bing does better, putting my page first. All in all, I have achieved my goal of making my name searchable.

Conclusion

I'm happy with my little website, and I've learned a few new things along the way. However, my digital garden will remain here at darekkay.com.

Style your RSS feed

2023-06-20T10:02:58Z

RSS is not dead. It is not mainstream, but it's still a thriving protocol, especially among tech users. However, many people do not know what RSS feeds are or how to use them. Most browsers render RSS as raw XML files, which doesn't help users understand what it's all about:

In this post, I'll explain how to style RSS feeds and educate readers at the same time.

XSL(T) to the rescue

This is how the RSS feed for this blog looks like:

To style a raw XML file in a browser, you have to provide styling information. You can do that by attaching an xml-stylesheet processing instruction within the RSS feed:

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet href="/rss.xsl" type="text/xsl"?>
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:media="http://search.yahoo.com/mrss/">
  ...
</feed>

The href attribute specifies a URL to a valid XSL file. You can check out mine for inspiration. Here's the gist:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="3.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:atom="http://www.w3.org/2005/Atom">
  <xsl:output method="html" version="1.0" encoding="UTF-8" indent="yes"/>
  <xsl:template match="/">
  <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
    <head>
      <title>
        RSS Feed | <xsl:value-of select="/atom:feed/atom:title"/>
      </title>
      <link rel="stylesheet" href="/assets/styles.css"/>
    </head>
    <body>
      <p>
        This is an RSS feed. Visit
        <a href="https://aboutfeeds.com">About Feeds</a>
        to learn more and get started. It’s free.
      </p>
      <h1>Recent blog posts</h1>
      <xsl:for-each select="/atom:feed/atom:entry">
        <a>
          <xsl:attribute name="href">
            <xsl:value-of select="atom:link/@href"/>
          </xsl:attribute>
          <xsl:value-of select="atom:title"/>
        </a>
        <xsl:value-of select="atom:summary"/>
        Last updated:
        <xsl:value-of select="substring(atom:updated, 0, 11)" />
      </xsl:for-each>
    </body>
    </html>
  </xsl:template>
</xsl:stylesheet>

This code is inspired by pretty-feed-v3, but I've adopted it for the Atom specification.

The XSL file transforms the XML feed into a valid HTML document that any browser can render. You can use any information included in the XML file and put it into a new markup structure. You can even include content that is not part of the XML feed. A perfect use case is to include a note about what RSS feeds are and how to use them (as shown in the example above).

You can define inline CSS styles with a regular <style> element, but it's also possible to import external CSS files. I've imported my blog's main CSS stylesheet, so I didn't have to write any new code to make the RSS feed match my blog's design.

It's also possible to use XSLT functions to alter values. Here's how I truncate the timestamp to display only the date:

<!-- Full timestamp -->
<xsl:value-of select="atom:updated" />

<!-- Date only -->
<xsl:value-of select="substring(atom:updated, 0, 11)" />

The browser support for XSL transformations is great; unsupported browsers will fall back to the default behavior (progressive enhancement).

Examples

Here are some styled RSS feeds you can check for inspiration:

The XSL files are public, so you can check how those pages have been implemented.

Sitemap

You can apply XSL files to any XML file. Another use case for styled XML files is a website sitemap. Although sitemaps are meant to be consumed by machines (e.g. crawlers), you can style them with little effort. See my sitemap and the respective XSL file as an example. Here's the gist:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:sitemap="http://www.sitemaps.org/schemas/sitemap/0.9">
  <xsl:output method="html" version="1.0" encoding="UTF-8" indent="yes"/>
  <xsl:template match="/">
    <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
      <body>
        <h1>Sitemap</h1>
        <xsl:for-each select="/sitemap:urlset/sitemap:url">
          <a>
            <xsl:attribute name="href">
              <xsl:value-of select="sitemap:loc"/>
            </xsl:attribute>
            <xsl:value-of select="sitemap:loc"/>
          </a>
          Last updated:
          <xsl:value-of select="substring(sitemap:lastmod, 0, 11)" />
        </xsl:for-each>
      </body>
    </html>
  </xsl:template>
</xsl:stylesheet>

Caveat

What happens if a user wants to save a styled XML file? Interestingly, the answer depends on the browser. Chrome and Safari will save the original XML file, but Firefox will store the styled HTML page instead. Most RSS readers expect a feed URL, so this behavior doesn't make a difference. However, I would be careful with XML files that are meant to be downloaded, like OPML files. Kudos to Robb Knight for the observation.

Conclusion

I love RSS, and — according to my stats — many of my readers love it, too. With all the social media walled gardens, I hope for RSS to become more popular. By providing a custom XSL file, you can make your RSS feed look nice and include some information about what RSS actually is.

Fixing long start-up times of the Eleventy dev server

2022-12-22T14:53:41Z

Recently, I've encountered a peculiar issue with Eleventy. The development server stopped working:

eleventy --serve

[11ty] Wrote 92 files in 0.48 seconds (5.2ms each, v1.0.2)
[11ty] Watching…

There were no errors. Everything seemed fine, except for the dev server not being available. I've checked my other Eleventy projects, and all of them shared the same behavior.

I've enabled the Eleventy debug log, but it didn't provide any further insights:

cross-env DEBUG=* eleventy --serve

I've decided to postpone further debugging, but I've accidentally left the Eleventy process running. At some point I've noticed the dev server was running again. Confused by this behavior, I've restarted the server. It turned out that the dev server was actually working, but it required several minutes to launch. What was going on? I couldn't research this issue, as I was sitting on a train with no internet connection. Wait, could this be the root cause? Indeed, later at home I no longer experienced the problem. After turning off my wi-fi I could again reproduce it.

I have found out that this is not an Eleventy issue. It's an issue with Browsersync, which Eleventy < 2.0 uses under the hood. Fortunately, there is a config option to fix the issue:

// .eleventy.js (< 2.0)
module.exports = function (eleventyConfig) {
  eleventyConfig.setBrowserSyncConfig({
    online: false
  });
};

This option will disable some network-related features, like exposing the server in the local network. While sometimes useful, I think it's better to use it as opt-in anyway.

Eleventy 2.0 comes with a custom development server, which probably doesn't have this issue. If you're using @11ty/eleventy-server-browsersync with Eleventy 2.0, use the new setServerOptions function instead:

// .eleventy.js (>= 2.0)
module.exports = function (eleventyConfig) {
  eleventyConfig.setServerOptions({
    module: "@11ty/eleventy-server-browsersync",
    online: false,
  });
};

Handling Enzyme in React 18

2022-03-26T14:12:07Z

React Testing Library (RTL) is arguably superior to Enzyme, due to a shift from testing implementation details to more user-centric unit tests. However, many projects still contain lots of Enzyme tests from the early days, making migration difficult and time-consuming. At my company, we've decided to keep Enzyme for old tests and write all new tests using RTL. This worked out fine, until we had to update React. While the missing support for React 17 can be worked around, making Enzyme ever work with React 18 is unlikely to happen.

Update: An unofficial enzyme-adapter-react-18 has been published in the meantime. It shouldn't be relied on, but it's another possible workaround while migrating away from Enzyme.

Migrating ~700 Enzyme tests at once was not a viable option for our project, so I've explored other approaches to handle Enzyme tests with React 18.

Write a custom adapter

The first idea was to write a custom adapter: a middle-layer class that translates Enzyme API calls to RTL (not to be confused with enzyme-adapter-react). However, the fundamental differences between both libraries make such an adapter difficult (or impossible) to implement.

This is how far I've got until abandoning this approach:

import React from "react";
import { render } from "@testing-library/react";

export const mount = (component) => {
  const { container, rerender } = render(component);
  return {
    find: (matcher) => {
      const nodes = container.querySelectorAll(matcher);
      return {
        length: nodes.length,
        exists: () => nodes.length > 0,
        // NOTE: innerText is not implemented by jsdom
        text: () => nodes[0].innerHTML,
      };
    },

    html: () => container.innerHTML,

    setProps: (props) => {
      const updatedComponent = React.cloneElement(component, props);
      rerender(updatedComponent);
    },
  };
};

Run multiple React versions

Finally, I followed the guide from Vitali Zaidman to keep using React 16 for Jest, while running React 18 for the application itself.

package.json:

{
  "dependencies": {
    "react": "18.0.0",
    "react-16": "npm:react@16.14.0",
    "react-dom": "18.0.0",
    "react-dom-16": "npm:react-dom@16.14.0"
  }
}

jest.config.js:

module.exports = {
  moduleNameMapper: {
    "^react-dom((\\/.*)?)$": "react-dom-16$1",
    "^react((\\/.*)?)$": "react-16$1",
  },
};

This is not a real solution, but it allows us to gradually migrate our Enzyme tests to RTL while being able to use React 17+ without any code change.

Note that this approach won't work if some of your unit tests rely on the React 18 API, e.g. createRoot. You could split your unit tests into two Jest configurations, handling Enzyme tests with React 16 and RTL tests with React 18 respectively.

Running Storybook from a separate folder

2021-12-29T16:42:38Z

After migrating a project to Vite, I've moved my Storybook setup into a separate module — a folder next to the actual app:

📁 project
├─ 📁 app
|  ├─ 📁 src
|  └─ 📄 package.json
└─ 📁 storybook
   ├─ 📁 .storybook
   |  ├─ 📄 main.js
   |  └─ 📄 preview.js
   └─ 📄 package.json

First, I've moved all Storybook dependencies from app/package.json to storybook/package.json and called yarn install. Next, I've moved the .storybook folder and adjusted all relative paths in main.js and preview.js, e.g.:

module.exports = {
-  stories: ["../src/**/__stories__/*.stories.tsx"],
+  stories: ["../../app/src/**/__stories__/*.stories.tsx"],
}

This setup was working fine locally. However, when trying to run build-storybook on my server, I've got the following error (also reported by others):

ModuleParseError: Module parse failed: Unexpected token

You may need an appropriate loader to handle this file type,
  currently no loaders are configured to process this file.

Storybook includes a webpack babel-loader to handle TypeScript and/or JSX files. The issue is with how Storybook determines the project root, which is the path that the babel-loader includes by default.

When calculating the project root, Storybook first searches for the closest parent .git folder. In my local development environment, this path was equal to the common parent of app and storybook. But on my server, I separate the Git repository from my working directory. As a result, the project root was incorrect and babel-loader didn't include the app files.

My workaround was to fix the include value of the babel-loader in the main.js file:

const path = require("path");

module.exports = {
  // ...

  webpackFinal: async (config, { configType }) => {
    const babelLoaderRule = config.module.rules.find(
      (rule) => rule.test.toString() === /\.(mjs|tsx?|jsx?)$/.toString()
    );
    // set correct project root
    babelLoaderRule.include = [path.resolve(__dirname, "../..")];

    return config;
  }
};

This code first finds the babel-loader config by searching for the defined RegExp object (note: in non-TS projects, remove |tsx? to match the Storybook definition). Then, include is changed to the correct project root. In my case, I use ../.. to get to the grandparent of the .storybook folder.

Check out this commit for the exact changes that I did to extract my Storybook module.

Separate Firefox Dark UI theme from website dark mode

2021-12-07T11:46:49Z

I like the default dark color theme in Firefox, but I prefer to view websites in light mode. This distinction has been working until recently, but with Firefox 95, the browser dark theme will enforce dark mode on websites as well. This sounds like a good default, but I want to separate the browser UI from website contents. Fortunately, there is an undocumented setting to change this behavior.

Update: Firefox 100 (desktop) added a UI option to adjust the dark theme behavior. 🎉

Go to "Settings" → "General" → "Website appearance" and choose your preferred setting:

Before Firefox 100 and within Firefox mobile apps, follow the following steps:

Open about:config configuration page.
Edit layout.css.prefers-color-scheme.content-override.

This setting defines how webpages should be rendered:

0: dark mode
1: light mode
2: system's color setting
3: browser theme color

By setting the value to 1, I can keep using the "Dark" Firefox UI theme and continue viewing websites in light mode.

Npm vs. Yarn: Dependency resolution

2021-10-20T08:46:49Z

Both npm and Yarn support dependency version ranges (e.g. ^4.1.1). However, there are some differences in how package managers resolve dependencies, which might lead to inconsistencies between different environments.

In this post I will present the behavior of npm 7.15.1 and Yarn 1.22.4 / 3.0.2.

Changing version ranges

I've set up two projects with the same package.json file:

"dependencies": {
  "kleur": "4.x.x"
}

The version range 4.x.x will be satisfied by any major 4 version, e.g. 4.0.0, 4.1.0 or 4.1.4. In a project without any lock file (package-lock.json, yarn.lock), npm install / yarn install installs the latest kleur version that satisfies our range (4.1.4 at the time of writing):

// package-lock.json
"dependencies": {
  "kleur": {
    "version": "4.1.4"
  }
}

// yarn.lock
kleur@4.x.x:
  version "4.1.4"

Let's now downgrade the dependency version to 4.0.0:

"dependencies": {
  "kleur": "4.0.0"
}

After another install, both package managers switch to version 4.0.0. This makes sense, as our installed version 4.1.4 does not match 4.0.0:

// package-lock.json
"dependencies": {
  "kleur": {
    "version": "4.0.0"
  }
}

// yarn.lock
kleur@4.0.0:
  version "4.0.0"

Now it will get interesting. Let's switch back to 4.x.x:

"dependencies": {
  "kleur": "4.x.x"
}

That's where the package managers handle things differently:

// package-lock.json
"dependencies": {
  "kleur": {
    "version": "4.0.0"
  }
}

// yarn.lock
kleur@4.x.x:
  version "4.1.4"

Npm compares the installed version 4.0.0 with the new version range 4.x.x and finds a match. Hence, the installed version remains at 4.0.0.

On the other hand, Yarn installs 4.1.4 again. I assume that Yarn cannot find a definition "kleur@4.x.x" in yarn.lock, so it treats kleur as if it were a new dependency.

In short, npm matches the actual version, while Yarn matches the version definition. I think this makes Yarn a little more consistent: the result is the same as when deleting yarn.lock.

Workspaces

If you are using workspaces, the resolution differences between npm and yarn will cause even more confusion.

Let's set up a basic workspace project:

├─ 📁 workspace-a
|  └─ 📄 package.json
└─ 📄 package.json

./package.json:

"dependencies": {
  "kleur": "4.0.0"
},
"workspaces": ["workspace-a"]

./workspace-a/package.json:

"dependencies": {
  "kleur": "4.x.x"
}

In this scenario, we get deviations right after the first install:

npm installs only kleur@4.0.0
yarn installs both kleur@4.0.0 (main package) and kleur@4.1.4 (workspace)

// package-lock.json
"dependencies": {
  "kleur": {
    "version": "4.0.0"
  }
}

// yarn.lock
kleur@4.0.0:
  version "4.0.0"

kleur@4.x.x:
  version "4.1.4"

When we look into the directory tree of the Yarn v1 project, we can indeed see two distinct kleur versions:

├─ 📁 node_modules
|  └─ 📁 kleur (4.0.0)
├─ 📁 workspace-a
|  ├─ 📁 node_modules
|  |  └─ 📁 kleur (4.1.4)
|  └─ 📄 package.json
├─ 📄 package.json
└─ 📄 yarn.lock

I guess Yarn enforces consistency by treating workspaces as separate projects, but npm's behavior still feels more reasonable to me.

Conclusion

Differences between a local development environment and a build pipeline can lead to all kinds of issues. One solution is dependency pinning, i.e., using fixed dependency versions. When using version ranges instead, lock files promise to solve the consistency problem. However, there are non-obvious differences between npm and Yarn to keep in mind.

Countercheck unit tests

2021-10-17T16:26:55Z

Test-driven development (TDD) is a good technique for making sure that our code matches the requirements. With frontend unit tests, it is often necessary to countercheck our requirements. In this post I will use React and testing-library, but the underlying problem can be applied to any language and framework.

Let's write a Fruits component that expects an items prop. Here are our requirements:

If the list of fruits is empty, render "No results".
Otherwise, render the list of fruits.

Let's start with some unit tests to cover both use cases:

test("displays a message when the fruit list is empty", () => {
  render(<Fruits items={[]} />);
  expect(screen.getByText("No results")).toBeInTheDocument();
});

test("displays a list of fruits", () => {
  render(<Fruits items={["Apple", "Kiwi"]} />);
  expect(screen.getByText("Apple")).toBeInTheDocument();
});

Do you see any issue with those unit tests? We've covered both requirements, so everything seems fine. Let's continue with the implementation:

const Fruits = ({ items }) => (
  <>
    <div>No results</div>
    {items.map((fruit) => (
      <div key={fruit}>{fruit}</div>
    ))}
  </>
);

Do you see the issue now? This component always renders a "No results" message and all provided fruits. The implementation is incorrect, yet our unit tests didn't catch it. Worse yet, our tests gave us a false sense of security with a 100% test coverage.

The issue is that we have only covered the explicit part of our requirements:

If the list of fruits is empty, render "No results".

However, this statement includes an implicit requirement that we didn't verify:

If the list of fruits is not empty, don't render "No results".

I call this an inverse or countercheck test. Here's how such a unit test can look like:

test("doesn't display a message when the fruit list is non-empty", () => {
  render(<Fruits items={["Apple", "Kiwi"]} />);
  expect(screen.queryByText("No results")).not.toBeInTheDocument();
});

Be extra-careful when testing for the absence of elements. A typo in the tested string won't make the test fail, yet the counter-check will become useless. One solution is to extract the string into a constant that is used by multiple tests.

When dealing with binary cases, I like to include countercheck assertions within regular tests to prevent setup duplication, e.g.:

test("displays a list of fruits", () => {
  render(<Fruits items={["Apple", "Kiwi"]} />);
  expect(screen.queryByText("No results")).not.toBeInTheDocument();
  expect(screen.getByText("Apple")).toBeInTheDocument();
});

Finally, here's a proper implementation of the Fruits component that will pass our regular and countercheck tests:

const Fruits = ({ items }) =>
  items.length === 0 ? (
    <div>Loading</div>
  ) : (
    items.map((fruit) => <div key={fruit}>{fruit}</div>)
  );

This issue happens whenever we assert a result partially. It's not unique to frontend unit tests, but it's common with the testing-library approach of checking if a page contains a certain element (queries). Keep counterchecks in mind when writing unit tests.