Forem: Mehdi M.

When Vite ignores your Browserslist configuration

Mehdi M. — Mon, 26 Dec 2022 11:18:48 +0000

I’m a long time user of Browserslist and Vite and I was pretty convinced they paired very-well. It seems to be the case for both CSS and JavaScript output, but it actually is not for JavaScript.

The issue

Weirdly, it took me ages to notice the JavaScript transformations done by Vite (using ESBuild under the hood) always produce the same result, no matter your Browserslist configuration. Whoops!

In reality, the issue is that ESBuild doesn’t support Browserslist and uses its own fine-grained target system with a different syntax.

Knowing this, we are left with two options to honor our browsers target: maintaining a second list with a compliant ESBuild syntax (passed through Vite build.target), or use the following fix.

The fix in two steps

Fortunately, there’s the browserslist-to-esbuild package (by Marco Fugaro) that is able to properly pass the content of a browserslist file to ESBuild.

The steps described here can also be visualized in a commit of mine.

First, add browserslist-to-esbuild to your project (tested version: 1.2.0):

npm i -D browserslist-to-esbuild

Then, in your vite.config.js file:

import { defineConfig } from 'vite'
import browserslistToEsbuild from 'browserslist-to-esbuild'

export default defineConfig({
  build: {
    target: browserslistToEsbuild(),
  },
})

That’s it! But wait, there’s more…

(Note: another package can do this, but I have not tested it.)

Unsupported JavaScript features

Now that ESBuild properly receives a browserslist config, maybe it will throw an error on compilation if you are trying to use a JavaScript feature unsupported by some of the browsers you target. In my case, I was trying to use top-level await, which is available starting Safari 15 while I want to support Safari starting 12.2 (iOS) or 13.1 (macOS).

 ERROR  [vite:esbuild-transpile] Transform failed with 1 error:                                                                          18:07:46
js/helpers/TopLevelAwait.js:1:0: ERROR: Top-level await is not available in the configured target environment ("chrome100", "edge102", "firefox91", "ios12.2", "safari13.1" + 2 overrides)

I was well aware that some of my target browsers don’t support this feature: I’m actually using top-level await to detect another browser feature, so what I want is top-level await to remain in my code and crash in some browsers. This way, my app knows which workaround to use when the feature is not detected.

Well, we are lucky again, because ESBuild allows to receive a list of “supported” features that will be prioritized over the compilation target coming from browserslist. All we have to do in our Vite configuration is to use the esbuild config entry to set supported['top-level-await'] to true:

export default defineConfig({
  esbuild: {
    /**
     * Prevents ESBuild to throw when using a feature not supported by the
     * list of supported browsers coming from the `browserslist` file.
     */
    supported: {
      'top-level-await': true,
    },
  },
}

Wit this, we can compile without error, and the JavaScript now preserves await at top-level.

With this knowledge in mind, I think it’s safe to say that Vite is only one step away to claim full Browserslist support, and that step is probably that Vite could use browserslist-to-esbuild to make everyone’s life easier.

More on Vite and Browserslist

Actually, Vite doesn’t support Browserslist at all: the only reason it “seems” to work well with CSS is because Vite uses PostCSS, which itself natively uses Browserslist. We could say that Vite supports Browserslist by proxy, for CSS. I’m not the only one who have been confused by this situation.

On the other hand, if your project uses the @vitejs/plugin-legacy, an official Vite plugin helping you supporting browsers outside of Vite browser compatibility list, then Vite will make use of your Browserslist configuration because this plugin uses Babel @babel/preset-env instead of ESBuild, and this Babel plugin uses your Browserslist configuration out of the box in order to define the list of JavaScript transformations that Babel will apply.

As @vitejs/plugin-legacy has explicit browser target documentation and even a ignorebrowserslistconfig option, I’m gonna end by quoting myself with a sentence from the previous section:

Vite is only one step away to claim full Browserslist support, and that step is probably that Vite could use of browserslist-to-esbuild to make everyone’s life easier.

~~Or, for now, two steps away: as mentioned by @kingyue, there’s currently a bug in @vitejs/plugin-legacy (and a fix in review !), causing the Browserslist configuration to be ignored.~~ (Fixed in @vitejs/plugin-legacy 4.0.1.)

watchOS, the wrist and the web for smaller screens

Mehdi M. — Sun, 27 Oct 2019 02:14:49 +0000

I was recently wondering what the web capabilities of Apple watchOS are. Here are my observations while using a Watch Series 5 with watchOS 6, both released in 2019:

There’s no browser app. The only ways to consume web content are by hitting a link from Mail or Messages, or by asking Siri to go to a URL. These actions open the WebKit view (Safari 13). Like on other Apple devices, Messages uses the Open Graph spec to replace URL’s by more readable links.

Page loading duration ranges from a few seconds to more than a minute. It’s hard to predict why as it doesn’t seem linked to the JavaScript weight or to the amount of pictures.
Once loaded, it’s okay-ish to browse a document. It just works and supports a wide range of browsers features (including Grid Layout).
Voice control really helps to input text data, otherwise you’re left drawing letters one by one, which is the last resort fallback.

Holding an arm in front of the eyes and using the other one to browse the web prevents the overall experience to be enjoyable, reminding that watches are good for passive features, short actions and notifications.

And that’s exactly why the Apple Watch is a great device: most apps narrow their scope, putting emphasis on small interactions, and they do it well. Keeping these principles with the web, Apple is just redirecting users to devices where the experience is better (and where the battery lasts longer).

I think keeping the same focus is the way to go while supporting very small viewports on the web. Taking a developer personal website as example, you could limit what’s displayed on such a small screen to the minimal contact informations, a bit like a business card: the name, a small picture or logo and a few contact links (<a href="mailto:…">, <a href="tel:…">). If these informations are already part of your website footer, you’re probably only a few media queries away from a decent result.

When it comes to web development, watchOS requires you to be aware of some specificities, across these four topics: missing features, viewport size, forms and reader mode.

The only official piece of information about web content on watchOS, well hidden in the middle of nowhere, is a WWDC2018 video about preparing web content for watchOS 5 by Apple’s developer Wenson Hsieh. Luckily it’s a great one!

We’ll go through the specific things and then see what it could mean to support smaller viewports in general. Spoiler alert: as often, betting on the fundamentals (semantic HTML, progressive enhancement) wins.

1. Disabled features

On watchOS, there’s no support for:

video playback on the web, but native apps can have it;
Service Workers;
web fonts: watchOS uses San Fransisco Compact, which is optimized for legibility on small sizes. A great decision.

A great use case for Service Workers on a watch could be Push Notifications (they require a Service Worker), but they are currently only available in Chrome, so it’s no big deal for now to not have Service Workers on watchOS.

2. The `<meta name="viewport">`

Apple is helping CSS authors by:

setting on all Watch models the same viewport, 320*357, matching the width of the iPhone SE;
overriding initial-scale to 0.49;
forcing shrink-to-fit to yes (shrink-to-fit=yes) in order to avoid horizontal scrolling.

In other words: the layout of your website stays the same as on the smallest phones and fits the Watch screen without the need to unzoom.

Flexibility is also given as these viewport adaptations can be disabled with (non-standard) <meta name="disabled-adaptations" content="watch">: the viewport then ranges from 272*340 (38 mm Watch) to 368*448 (44 mm) and isn’t automatically shrunk to the viewport anymore, opening the road to custom styles for viewports smaller than 320px.

combined with @media (min-width) on watchOS"/>

This meta is also important to fine-tune websites using responsive images: Eric Portis recommends to disable watchOS viewport adaptations because of the returned DPR (device pixel ratio) being too high, resulting in wasted bandwidth (and thus battery consumption).

3. Forms

Accessibility

Filling a form opens a full screen panel, so arial-label is needed to provide label hints while filling a field.

Of course, don’t forget the <label> tag:

<label for="billing-email">
    The email address where invoices will be sent
    <input type="email" id="billing-email" aria-label="Billing email">
</label>

Fields

<select> and the following <input> types all comes with a dedicated keyboard layout: password, numeric, tel, date, time.

4. Reading articles

Heavy text pages automatically enable the reader mode. Like every reader mode, it relies on proper HTML markup: article, figure, figcaption, blockquote…

Picture description shown below the picture

Unexpectedly, microdata are used to introduce the article metadata in the reader mode. This is awesome!

Dealing with small viewports in general

A few months ago, I started to shape what supporting smaller viewports could be like. Aside from an Apple Watch, there are at least ~~two~~ three other use cases for ~150 px wide viewports:

desktop installed PWA;
smartphones split views;
Firefox macOS allowing to resize the window as low as 450 px by 63 px.

Usually I move a lot of CSS inside @media (min-width: 20em) (20em is generally 320px). Some rules of thumb for smaller viewports:

every CSS rule changing an element position, size, flow or horizontal spacing should be in this min-width media query;
same for decorative assets like background-image;
make sure font-size stays small;
avoid running JavaScript if your app can work without it.

We’re left with a usable HTML document with a basic sense of identity powered by some decoration rules (colours, opacity…).

Here’s a basic example where two elements in the header stack in one column when the viewport is too small, along with background-image removal.

The only CSS changes consist of moving some CSS declarations into a @media rule:

html {
  font-size: 50%;

  @media (min-width: 20em) {
    font-size: 62.5%;
  }
}

.header {
  font-size: 1.2rem;

  @media (min-width: 20em) {
    display: flex;
    justify-content: space-between;

    background: url('bg.png') no-repeat center / 100% auto;
  }
}

Did you know a desktop installed web app can be resized down to 207×117 on macOS? Here’s Can I Stop installed on macOS, with a viewport width below 320 px:

And here is Burokku width a viewport of 371×1 (well, actually 0.77px according to Edge developer tools) on Windows 10 (video):

Finally, big shoutout to Apple’s developers videos website, which contains downloadable videos, high-definition slides (the pictures of this article are mostly from the slides), and a super cool transcription system with links to navigate the video. Worth trying and browsing!

Write CSS variables faster in SCSS

Mehdi M. — Wed, 07 Nov 2018 00:33:08 +0000

Update (October 20th, 2022): while this helper remains cool, I have decided to not use it outside of personal projects. Compared to IDE auto-completion, its benefits might not be worth the cognitive load linked to any additional abstraction.

I love CSS variables (here’s why) but the syntax isn’t very readable to me:

there’s this double hyphen thing in the name: --varName;
the var function is required to access it: color: var(--myColor);.

Crazy. Let’s simplify this with…

The `v()` function!

@function v($var) {
  @return var(--#{$var});
}

Usage

First, define your CSS variables normally:

:root {
  --primary: #000;
  --bg: #fff;
}

Then, use it with v(varName).

html {
  background: v(bg);
  color: v(primary);
}

It generates this:

html {
  background: var(--bg);
  color: var(--primary);
}

That’s only a 4 characters win, but it’s a cool one for readability and you’ll use it often.

That’s it!

Optional second parameter as fallback

As it was pleasely mentioned in the comments, the CSS var() function can take a fallback as second parameter: if the wanted CSS variable isn’t defined or has an understandable value for the browser, this default value will be used.

So, let’s update v() accordingly:

@function v($var, $fallback: null) {
  @if($fallback) {
    @return var(--#{$var}, #{$fallback});
  } @else {
    @return var(--#{$var});
  }
}

Now, let’s write something that benefits from the optional fallback, like a “pin the video in a corner” feature:

One small bit of fun

Do you know that -- is a valid name for a CSS custom property? Unfortunately, it’s hard to declare and use it in SCSS. But the v() helper makes your life a bit easier. ✌️

Other attempts that could have been cool, but…

If you’re wondering how to improve my package, I compiled three unsuccessful attempts in a Gist. Feel free to propose CSS variable tips!

Recover a lost Git stash in two steps

Mehdi M. — Fri, 27 Apr 2018 21:38:58 +0000

Sometimes you end up stashing code, then at some point those stashes get cleaned. And one day, you may encounter the situation I faced this week:

Fine, this code is merged, so let’s delete the related stashes. Done! And… hey… wasn’t this part of the feature supposed to be in the codebase? Is the stash I just deleted lost forever?

Fortunately, I managed to recover lost stashes. I’m not a Git expert, but here’s what worked for me after going through various readings (including some Stack Overflow answers).

Here’s the two-steps recovery procedure.

1. List lost stashes

Let’s run this command for a project where all stashes were trashed:

git fsck --unreachable | grep commit | cut -d ' ' -f3 | xargs git log --merges --no-walk

It returns a list of lost stashes, ordered by date.

To quit the list of stashes, press the Q key.
To navigate in a long stashes list, use up and down arrows.
For Windows user, maybe johnwait’s comment will help you during the battle.

2. Send a lost stash back where it comes from

Let’s use the commit hash of the second stash:

git update-ref refs/stash 4b3fc45c94caadcc87d783064624585c194f4be8 -m "My recovered stash"

And that’s it! You’ll find your stash as usual, using git stash list or by having a look in your favorite Git client.

Gotchas

1. I still can’t see my recovered stash

Retry using the --create-reflog parameter (thanks studoggithub):

git update-ref refs/stash 4b3fc45c94caadcc87d783064624585c194f4be8 --create-reflog -m "My recovered stash"

2. My Git isn’t in English

If your Git isn’t in English, you’ll have to run alias git='LANG=en_GB git' each time you want to recover a set of stashes (thanks mathieuschopfer).

Some advices

Commit messages are healthy

Always use a commit message using git stash save -m "My commit message": without message, the only informations helping to identify a stash are its timestamp and the branch it was saved from, which may not be enough compared to a strong explicit name.

Commit messages also help Git clients:

GitUp, the Git client I use, completely fails at showing unnamed stashes. That’s probably why you can’t create a stash in GitUp without giving it a name, which is great!
The well-known SourceTree succeeds at showing unnamed stashes, but as you can guess, the list isn’t friendly to browse:

Yes, `git stash apply` > `git stash pop`

Unlike git stash pop, git stash apply does not remove the stash from the list of stashes, which can avoid some loss.

Branches > stashes

Finally, I’d recommend to avoid git stash. Instead, try to use a branch. This seems obvious but it only comes to me as I was finding a way to recover a stash: maybe I should use temporary branches instead of stashes. Using the Git Flow method at work, this could have come to my mind before encountering a painful experience.

If you have any stash hint or experience that you want to share, comments are welcome.