Plain Vanilla Blog

matters

2026-03-09T12:00:00.000Z

The richness of HTML continues to be a delightful surprise.

For example, take an unassuming element like

. We've all seen it before. Here it is in its pure form:


    A summary
    Some details to further explain the summary.

undecorated details

We can merrily click the summary to open and close the details to our heart's content. But this is kind of plain-looking. Can we change that triangle into something else?

replacing the marker

In a just world, this would work by neatly styling the ::marker pseudo-element, but like so often Safari is being annoying. Thankfully we can instead replace the marker by removing it with list-style: none; and adding a new summary marker on the ::before or ::after pseudo-elements.



    A summary
    Some details to further explain the summary.

And really, the summary element can contain anything at all, inviting our creativity. Here's a fancier example that replaces the marker by an animated svg icon.

replacing the marker, but more fancy



    
        A summary
        
    
    Some details to further explain the summary.

There's no reason to stop at decorating the marker though. We can make the details element look like anything we want, all it takes is the right CSS. If we wanted, we could make it look like a card.

card-like appearance



    
        A summary
        
    
    Some details to further explain the summary.
    And this is another sentence that spends a great deal of time saying nothing.

One caveat with this example is the ::details-content pseudo-element used to select the expanded content area. This is baseline 2025 so still pretty new. For older browsers you can wrap the content in a div and style that instead.

But wait, there's more! In baseline 2024

picked up a neat trick where all the elements with the same name attribute are mutually exclusive, meaning only one can be open at the same time. All we have to do is stack them to magically get an accordion.

card-like appearance



    ...


    ...


    ...

There's no magic code here to make the accordion work aside from the name attributes. HTML is doing the magic for us, which means this also happens to be fully keyboard-navigable and accessible. The only tricky bit is animating the expanding and collapsing of the cards. In this example that is implemented using interpolate-size: allow-keywords, which is a Chromium-only trick hopefully coming to other browsers near you. Thankfully in those other browsers this is still perfectly functional, just not as smoothly animating.

By the way, the mutually exclusive

elements do not even need to share a parent element. These accordion cards could be wrapped in custom elements, or

elements, and they would work just fine in all browsers, today. But you'll have to take my word for it. After all, I have to leave some exercises up to the reader. 😉

Like I said, the richness of HTML continues to be a delightful surprise. If you ask me then

has a bright future ahead of it.

No JavaScript was harmed in the making of this blog post.

Redesigning Plain Vanilla

2026-03-01T12:00:00.000Z

Design has never been the part of building for the web that I felt comfortable with. I would hide behind the shorthand "I'm not a designer" and just use someone else's design, or throw something together that I wasn't happy with. The original design of Plain Vanilla was shipped very much in that not-happy-with-it mindset.

So when I decided to finally take a web design course, settling on DesignAcademy.io and had to pick a project to apply the course's learnings to, turning this site's design into something I liked was top of mind. This article documents how and why the new design came about.

The course starts out by making you really think about the content that you want to apply a design to. They challenge you to make your web page work as a google doc, so I did precisely that. In revisiting the landing page and thinking through its text, about half of the characters were cut, without losing any of the meaning.

Lesson 1: less is more.

The next challenge the course throws at you is to decide on a style and to gather inspiration for your design. What I wanted the design of Plain Vanilla to communicate was a sort of timelessness, like a manual from an earlier time, that at the same time feels simple and fresh. In looking for inspiration I settled on Swiss style, the 1950's minimalist style that manages to feel modern and old at the same time. I absolutely adore the old manuals from the 50's, as in the image at the top of this page, where minimalist design relying heavily on typography and spacing brings the content to the foreground.

With this style and many googled-together examples of it as inspiration in hand, I took on the next challenge: make a first sketch of the design by simply copy pasting together elements of web sites and imagery that inspired you into a rough first outline. The second half of the challenge: take that design and layer your content over it. The result of this exercise was the initial redesign. Notice how the left half is literally copy pasted together bits of screenshots.

Lesson 2: taking ideas from everywhere is a quick way to get started.

The rest of the course was a series of design exercises on top of that initial draft, to choose fonts, colors, imagery, to apply a grid system and figure out spacing, and to sort out the finer aspects. Some elements of the initial redesign survived this process, others didn't, and what I ended up with in the final Affinity Designer file is pretty close to the shipping redesign.

Lesson 3: design doesn't have to be intimidating if you have the right process.

The actual work of translating of the design to code wasn't all that complicated. There was already a good baseline of semantic markup, so the redesign ended up mostly constrained to central CSS changes. Most of the time was taken up by responsiveness, something absent from the design mockup. Many of the final decisions on the exact behavior were made to favor code simplicity. This is for example why I decided not to add animations.

This is also why I chose the popover API as the strategy for having a responsive hamburger menu on small screens. While the popover API presently only has 87% support on caniuse.com, I felt that for the audience of this site support should be sufficient, and the dramatic code simplification it allowed was undeniable. The nav menu works without any JavaScript. It presents as a toggled menu by default, and uses CSS to become permanently visible on larger screens.


    
        Welcome
        Components
        Styling
        Sites
        Applications
        Blog

This was also a good opportunity to revisit the website's content. As it turns out, not a lot needed to change. Web standards don't actually change that often. I did update some parts where evolving baseline support took away caveats (for example, CSS nesting is now safe to use), and added some links to newly baseline features like popover, dialog and mutually-exclusive details.

Lesson 4: when you build on top of web standards, you don't need to do a lot of maintenance.

In the end, I'm finally happy with the design of Plain Vanilla. I still haven't gotten around to adding a dark mode, but it's on the todo list. There may be some hiccups with the new design, so if you see any please let me know by making an issue on GitHub. Do you like the new design, do you hate it? Please let me know.

Local-first web application architecture

2025-07-16T12:00:00.000Z

Previously in the history of web application architecture I covered the different ways that people have tried to build web applications, and how all of them came with their own unique set of drawbacks. Also mentioned was how there is one drawback that they all share: there is a whole internet between a user and their data, and this makes it hard to deliver a top notch user experience.

Tail latency matters

On the surface, it doesn't seem like this should be the case. Networks are fast, right? But the truth is, they're only fast for some of the people some of the time.

Look at the page load numbers (LCP) of this website for the last week (gathered anonymously):

P50: 650 ms
P75: 1200 ms
P90: 2148 ms
P99: 10,636 ms

While half of the visits see page load times well below a second, many see times that are much, much higher. Part of this is due to geography. Going through Azure's P50 roundtrip latency times we can see that some remote connections, like France to Australia, are in the 250 ms range, data center to data center. Azure doesn't disclose P99 latency, but one may assume it is a multiple of the P50 latency.

But our user isn't sitting in a data center, they're probably on a mobile phone, connecting through a slow network. Looking at mozilla's minimum latency numbers we can see that it's not unusual to see another 100 ms of roundtrip latency added by the mobile network, and in reality owing to packet loss and TCP retries it can be a lot more. My own experience taking the train into the office, and trying to get some work done, is that the web can slow to a crawl as I pass through dead zones. This is in a densely populated area in a rich country on the most expensive cell service provider. Most people do not have these same luxuries.

So it's not unusual to see latencies climb far above the threshold of 100 ms, commonly regarded as the threshold for an immediate response. For an unlucky minority of users latencies can even climb above half a second. This matters because if we have to hit the server to do something with the user's data on every click, we will have noticeable and frustrating delay in the interaction. To get a feel of this delay, here's a simulator where you can try out roundtrip latencies from 50 ms to one second:

roundtrip latency simulator

Can you tell how much nicer 100 ms and below feel? How the buttons actually feel lighter to press? By contrast, 500 ms and above of roundtrip latency are just a slog, painful to use. The buttons are heavy and cumbersome. This is human psychology at work, and these lessons were learned in the desktop era but forgotten and never quite relearned for the web. If we put over 100 ms of latency in between a user's click and the resulting effect they will feel some degree of frustration, and we know that the internet cannot deliver below 100 ms of roundtrip latency except in the luckiest of cases.

Solutions

We can use some kind of closer-to-the-user cache, in the form of a CDN or a browser cache or a service worker. This allows the content that needs to be loaded based on the user's click to be fetched from something that has a better shot at being below that magic 100 ms of latency. But this only works if what we need to load can be cached, and if we can afford to cache it. For a web application that works with user data, this is typically not the case.

We can host the application in a georedundant way, have application servers across the world and use a georedundant database like Google Spanner or Azure Cosmos DB. This quickly gets complicated and expensive, and can only be achieved through a great amount of vendor lock-in. Crucially, it probably does not get us past the 100 ms barrier anyway.

We can render client-side, using JavaScript to create and update the HTML page, so that an update on the screen can happen immediately after the user's click. But this only works if what the user is doing is not updating a piece of server-side data. Otherwise we have to show some kind of loading or saving indicator until the server responds, and then we're back to roundtrip latency.

Bottom line, and once again: the basic problem is that the internet is in between the user and their data. So what if we moved the data to the user?

Local-first

This concept has been around for a while and it is known as a local-first application. To apply it to the web, let's start from the basic design of a client-side rendered web application as covered in the previous article:

This design does not need the server for rendering, so it has the theoretical potential to hit 100 ms. But because the user's interactions have to fetch data from the remote database and update it as well – a database sitting multiple network hops away – in practice we rarely actually hit that low latency. We can move the data to the user by doing something like this:

The user's data gets duplicated into a local IndexedDB. More than duplicated actually as this becomes the only copy of the data that the user will interact with directly. The backend-for-frontend and API that used to gatekeep access to this data similarly get moved into the client, as part of a service worker. This worker code can be very similar to what the server-side version would be, it can even reuse express (although it probably shouldn't). Because the service worker's API for all intents and purposes looks like a server-side API to the frontend codebase, that frontend can be built in all the usual ways, except now with the guarantee that every server roundtrip completes in milliseconds.

To avoid slow page loads each time the web application is opened it also needs to be cached locally as part of the service worker. By packaging this as a progressive web app installs become possible onto the user's home screen, giving an experience not that unlike installing a native mobile app. The application server's job is now reduced to only providing that initial application install, and it can become a simple (and free) static web host.

Here comes trouble

Both the application and the data are now running locally, meaning the user doesn't need the network at all to get things done. This isn't just local-first, it is offline-first. But like all things in software architecture, we are trading one set of problems for another.

There still needs to be a way to get data onto other devices, or to other users, or simply backed up into the cloud. That means the service worker also gets the job of (asynchronously) uploading changes to a server API which will store it in a database, as well as pulling server-side changes back down. The server-side version acts as the master copy, and the server-side API gets the thankless job of merging client-side changes with it.

Not so fast though. Our user might be editing offline for a considerably long time, and the data on the server may have been changed in the meanwhile from another device or by another user. The job of merging those changes can be ... complicated. A good strategy is needed for merging. A possible path is to use CRDT algorithms from a library like automerge, as suggested by the local-first article linked above. However, for many cases a simpler bespoke algorithm that is aware of the specific data types being merged probably works well enough, as I discovered when making an offline-capable work orders web application that used this strategy.

As the local-first application is now directly talking to this API, it needs a way to authenticate. This can be a reason to still have a minimal backend-for-frontend on the server. An alternative is to use a separate OpenID Connect identity provider with a PKCE authorization flow to obtain an access token. PKCE is an authorization flow developed for use by mobile apps but also usable by web apps that enables secretless API authentication.

Another major caveat is that the entire codebase needs to be on the client, which necessitates keeping it under a tight performance and size budget. Careful curation of dependencies is key, and a javascript footprint that runs in the megabytes is verboten. Vanilla web development can be a solution here, with its emphasis on using the platform to its limits without bringing in dependencies. A lightweight framework like Lit or Preact will do as well.

This isn't just a theoretical exercise. The team at Superhuman built their better gmail than gmail more or less as described here, using React as the framework, and the thing that sets their web app apart is its blistering speed. You can go read how they did it on their blog (part 1, part 2) or listen to the retelling on the Syntax podcast.

Loco-first

But we can push it even further, in theory at least. In the previous iteration of the architecture we still have the application-specific database and syncing logic on the server, but what if we instead did away with every last piece of server-side application logic?

The syncing engine now gets moved in the client, and what it uploads to the server are just files. That means all we need is a generic cloud drive, like Dropbox or Onedrive. These cloud drive services often support cross-origin API access with OpenID Connect authentication using PKCE. That means the service worker in the client doesn't need any application servers to upload its data to the cloud storage.

The onboarding experience becomes a choice screen where the user picks their cloud drive option. The application will redirect the user to the Dropbox or Onedrive or login page, and obtains an access token using PKCE authorization flow that is persisted locally. This token is used to connect to the user's cloud drive from inside the service worker. The application will bootstrap itself from whatever files are already in the drive, and will regularly synchronize with the current contents of the drive using its service worker logic.

Instead of a cloud drive, another option is the use of the File System Access API to get a handle to a local folder. The user can set up this folder as cloud-synced, or they can back it up and copy it to other devices using a method of their choice. This solution allows the app to have complete privacy, as the user's data never leaves their device or network. The caveat is incomplete browser support. Come on Safari and Firefox, do your bit, for privacy!

In a single user scenario, each of their devices uploads its own copy of the data, either as a history of actions or as the latest state. When a device's service worker wants to sync, it checks all of the files of the other devices to see if they have been modified. If they are, it downloads updates and merges them into the local IndexedDB. This is the same work as the previous architecture iteration did in its server-side syncing API, only now in reverse: instead of every device going to the server and presenting its copy to merge, it is the service worker going to each device's copy and checking if it needs merging.

There is no longer a master copy of the data, only one copy per device, all on equal footing, with an eventual consistency arising out of the devices merging from each other's copies. This is the same philosophy as CRDTs, or of the Operational Transformation algorithm that underpins Google Docs. No matter though, when you get deep enough into consistency models (I recommend Aphyr's writings or Martin Kleppmann's book), you'll realize that there is never such as a thing as a reliable master copy in a distributed system, even in cases where there is a central database.

A multi-user scenario can be realized by our user subscribing to someone else's shared cloud drive folder, where the other user shares their copy of the data as read-only. When Alice shares her folder with Bob, Bob shares his with Alice, and they both subscribe to each other's updates, then they can work on a shared document without ever having given each other direct write access.

As this application has no servers outside of the lightly loaded static web host, which in 2025 is free to host even at scale, the hosting cost drops to zero almost regardless of the number of users. The cloud drive costs are carried by each user individually, only responsible for their own share of storage. The only hosting cost to the application's owner would be the domain name. The climate footprint is minimal.

By eliminating the central database and its adjoining server-side logic it also eliminates the main target for hackers. Because compromises can only occur one user at a time they lack a sufficient reward for hacking the application. On top of that, the only servers are the static web host and the major cloud drive vendors, both practically impossible to hack. This web app would be highly secure and remain secure with barely any maintenance.

This architecture would be a cloud vendor's worst nightmare if it ever became popular, as they cannot earn a dime from it (aside from the basic cloud drive pennies). Thankfully for them, it is impossible to monetize for the company that builds such a web app as well. No server == no revenue opportunity. For now this is just a crazy theoretical exercise, far removed from where the leading frontend architecture voices are driving us, but the possibility fascinates me.

The history of web application architecture

2025-07-13T12:00:00.000Z

I'm old enough to remember what it was like. I first got online in 1994, but by then I was using computers for a few years already. That means I was there for the whole ride, the entire history of web application architecture, from the before times to the present day. So this post will be an overview of the various ways to make a web app, past and present, and their relative trade-offs as I experienced them.

Just to set expectations right: this will cover architectures targeted primarily at proper applications, of the sort that work with user data, and where most screens have to be made unique based on that user data. Web sites where the different visitors are presented with identical pages are a different beast. Although many of these architectures overlap with that use case, it will not be the focus here.

Also, while I will be mentioning some frameworks, they are equally not the focus. Where you see a framework, you can slot in vanilla web development with a bespoke solution.

This will be a long one, so grab a snack, take some time, and let's get going.

Before time began

Back when people first went online, the ruling architecture was offline-first. It looked sort of like this:

Our user would have a proper desktop application, written in C or C++ most likely, and that would work with local files on their local file system, all perfectly functional when offline. When they wanted to "go online" and share their work, they would dial in to the internet, start their e-mail client and patiently send an e-mail to their friend or colleague containing a copy of their file as an attachment.

This architecture was very simple, and it worked well in the absence of a reliable and fast internet connection. This was a good thing because at the time most people never had a reliable and fast internet connection. There were problems though. For one, the bootstrapping problem: how do you get everyone to have the application installed so they can open and edit the file they received via e-mail? Also, the syncing problem: how are changes kept in sync between multiple devices and users? Merging edits from different files that could have weeks of incompatible edits was always somewhere between frustrating and impossible.

Traditional server-side rendering

Web applications promised they would solve both problems. At first we built them like this:

The first thing we did was move all of the stuff from all of the users into a central database somewhere online. Because this database was shared between the users, it became a lot more easy to keep their changes in sync. If one user made an edit to something, everyone else would see it on the next refresh.

To allow users to actually get at this database we had to give them an application to do it. This new-fangled thing called a web application running on a web application server would take http requests coming from the user's browser, SQL query the database for the right set of stuff, and send back an entire web page. Every click, every submit, it would generate a whole new page.

Deployment of those early web applications was often suspiciously simple: someone would connect via FTP to a server, and copy over the files from their local machine. There often weren't even any build steps. There was no step 3.

On the one hand this architecture was convenient. It solved the bootstrapping problem by only demanding that each user have a web browser and an internet connection. It also moved all of the application logic over to the server, keeping it neatly in one place. Crucially it kept the browser's task minimal, important in an era where browsers were much less capable and PC's were orders of magnitude slower than today. If done well, it could even be used to make web applications that still worked with JavaScript disabled. My first mobile web app was like that, sneakily using HTML forms with multiple submit actions and hidden input fields to present interactive navigation through a CRUD interface.

On the other hand, it had many problems, especially early on. HTML wasn't very good, CSS was in its infancy, and early JavaScript was mostly useless. It was hard going building anything at all on the early web. On top of that, web developers were a new breed, and they had to relearn many of the architecture lessons their desktop developer colleagues had already learned through bitter experience. For example, everyone has heard of the adage "If you don't choose a framework, you'll end up building a worse one yourself." That is because for the first few years building your own terrible framework as you went was the norm, until everyone wisened up and started preaching this wisdom. For sure, my own first experiments in web application development in PHP 3 and 4 were all without the benefit of a proper framework.

Web developers also had to learn lessons that their desktop counterparts never had to contend with. Moving the application to the server was convenient, but it exposed it to hackers from all across the world, and the early web application landscape was riddled with embarrassing hacks. Because the threat level on the internet keeps rising this remains a major headache to this day.

Another novel problem was having to care a whole lot about connectivity and server uptime. Because users literally couldn't do anything at all if they didn't have a connection to a working web server, making sure that connection was always there became a pervasive headache. Going to a site and seeing an error 500 message was unsurprisingly common in those early years.

The biggest problems however were throughput, bandwidth and latency. Because almost every click had to reload the whole page, doing anything at all in those early web applications was slow, like really, really slow. At the time, servers were slow to render the page, networks slow to transport it, and PC's and browsers slow to render. That couldn't stand, so something had to change. It was at this point that we saw a fork in the road, and the web developer community split up into two schools of thought that each went their own way. Although, as you will see, they are drawing closer again.

Modern server-side rendering

One branch of the web development tree doubled down on server-side rendering, building further on top of the existing server-side frameworks.

They tackled the problems imposed by throughput and latency by moving over to a model of partial page updates, where small bits of user-activated JavaScript (originally mostly built with jQuery) would update parts of the page with HTML partials that they fetched from the server.

The evolution of this architecture are so called LiveViews. This is a design first popularized by the Phoenix framework for the obscure Elixir programming language, but quickly adopted in many places.

It uses framework logic to automatically wire up server-side generated templates with bits of JavaScript that will automatically call the server to fetch partial page updates when necessary. The developer has the convenience of not thinking about client-side scripting, while the users get an interactive user experience similar to a JavaScript-rich frontend. Typically the client keeps an open websocket connection to the server, so that server-side changes are quickly and automatically streamed into the page as soon as they occur.

This architecture is conceptually simple to work with as all the logic remains on the server. It also doesn't ask much from the browser, good for slow devices and bandwidth-constrained environments. As a consequence it finds a sweet spot in mostly static content-driven web sites.

But nothing is without trade-offs. This design hits the server on almost every interaction and has no path to offline functionality. Network latency and reliability are its UX killer, and especially on mobile phones – the main way people interact with web apps these days – those can still be a challenge. While this can be mitigated somewhat through browser caching, the limitation is always there. After all, the more that page content is dictated by realtime user input, the more necessary it becomes to push logic to the client. In cases where the network is good however, it can seem like magic even for highly interactive applications, and for that reason it has its diehard fans.

Client-side rendering

There was another branch of web development practice, let's say the ones who were fonder of clever architecture, who had a crazy thought: what if we moved rendering data to HTML from the server to the browser? They built new frameworks, in JavaScript, designed to run in the browser so that the application could be shipped as a whole as part of the initial page load, and every navigation would only need to fetch data for the new route. In theory this allowed for smaller and less frequent roundtrips to the server, and therefore an improvement to the user experience. Thanks to a blooming cottage industry of industry insiders advertising its benefits, it became the dominant architecture for new web applications, with React as the framework of choice to run inside the browser.

This method taken to its modern best practice extreme looks like this:

It starts out by moving the application, its framework, and its other dependencies over to the browser. When the page is loaded the entire bundle gets loaded, and then pages can be rendered as routes inside of the single-page application. Every time a new route needs to be rendered the data gets fetched from the server, not the HTML.

The web application server's job is now just providing the application bundle as a single HTML page, and providing API endpoints for loading JSON data for every route. Because those API endpoints naturally end up mirroring the frontend's routes this part usually gets called the backend-for-frontend. This job was so different from the old web server's role that a new generation of frameworks sprung up to be a better fit. Express on node became a very popular choice, as it allowed a great deal of similarity between browser and server codebases, although in practice there's usually not much actual code in common.

For security reasons – after all, the web application servers are on the increasingly dangerous public internet – the best practice became to host backends-for-frontend in a DMZ, a demilitarized zone where the assumption has to be that security is temporary and hostile interlopers could arrive at any time. In addition, if an organization has multiple frontends (and if they have a mobile app they probably have at least two), then this DMZ will contain multiple backends for frontend.

Because there is only a single database to share between those different BFFs, and because of the security risks of connecting to the database from the dangerous DMZ, a best practice became to keep the backend-for-frontend focused on just the part of serving the frontend, and to wrap the database in a separate thing. This separate microservice is an application whose sole job is publishing an API that gatekeeps access to the database. This API is usually in a separate network segment, shielded by firewalls or API gateways, and it is often built in yet another framework better tailored for building APIs, or even in a different programming language like Go or C#.

Of course, having only one microservice is kind of a lonely affair, so even organizations of moderate size would often end up having their backends-for-frontend each talking to multiple microservices.

That's just too many servers to manage, too many network connections to configure, too many builds to run, so people by and large stopped managing their own servers, either for running builds or for runtime hosting. Instead they moved to the cloud, where someone else manages the server, and hosted their backends as docker containers or serverless functions deployed by git-powered CI/CD pipelines. This made some people fabulously wealthy. After all, 74% of Amazon's profit is made from AWS, and over a third of Microsoft's from Azure. It is no accident that there is a persistent drumbeat that everyone should move everything to the cloud. Those margins aren't going to pad themselves.

Incidentally, microservices as database intermediary are also a thing in the world of server-side rendered applications, but in my personal observation those teams seem to choose this strategy less often. Equally incidentally, the word serverless in the context of serverless functions was and is highly amusing to me, since it requires just as many servers, if not more. (I know why it's called that way, that doesn't make it any less funny.)

On paper this client-side rendered architecture has many positive qualities. It is highly modular, which makes the work easy to split up across developers or teams. It pushes page rendering logic into the browser, creating the potential to have a low latency and high quality user experience. The layered nature of the backend and limited scope of the internet-facing backend-for-frontend forms a solid defensive moat against cyberattacks. And the cloud-hosted infrastructure is low effort to manage and easy to scale. A design like this is every architecture astronomer's dream, and I was for a while very enamored with it myself.

In practice though, it just doesn't work very well. It's just too complicated. For larger experienced teams in large organizations it can kind of sort of make sense, and it is no surprise that big tech is a heavy proponent of this architecture. But step away from web-scale for just a second and there's too many parts to build and deploy and keep track of, too many technologies to learn, too many hops a data request has to travel through.

The application's logic gets smeared out across three or more independent codebases, and a lot of overhead is created in keeping all of those in sync. Adding a single data field to a type can suddenly become a whole project. For one application I was working on I once counted in how many places a particular type was explicitly defined, and the tally reached lucky number 7. It is no accident that right around the time that this architecture peaked the use of monorepo tools to bundle multiple projects into a single repository peaked as well.

Go talk to some people just starting out with web development and see how lost they get in trying to figure out all of this stuff, learning all the technologies comprising the Rube Goldberg machine that produces a webpage at the end. See just how little time they have left to dedicate to learning vanilla HTML, CSS and JS, arguably the key things a beginner should be focusing on.

Moreover, the promise that moving the application entirely to the browser would improve the user experience mostly did not pan out. As applications built with client-side frameworks like React or Angular grew, the bundle to be shipped in a page load ballooned to megabytes in size. The slowest quintile of devices and network connections struggled mightily with these heavy JavaScript payloads. It was hoped that Moore's law would solve this problem, but the dynamics of how (mobile) device and internet provider markets work mean that it hasn't been, and that it won't be any time soon. It's not impossible to build a great user experience with this architecture, but you're starting from behind. Well, at least for public-facing web applications.

Client-side rendering with server offload

The designers of client-side frameworks were not wholly insensitive to the frustrations of developers trying to make client-side rendered single-page applications work well on devices and connections that weren't up to the job. They started to offload more and more of the rendering work back to the server. In situations where the content of a page is fixed, static site generation can execute the client-side framework at build time to pre-render pages to HTML. And for situations where content has a dynamic character, server-side rendering was reintroduced back into the mix to offload some of the rendering work back to the server.

The current evolution of these trends is the streaming single-page application:

In this architecture the framework runs the show in both backend-for-frontend and in the browser. It decides where the rendering happens, and only pushes the work to the browser that must run there. When possible the page is shipped prerendered to the browser and the code for the prerendered parts is not needed in the client bundle. Because some parts of the page are more dynamic than others, they can be rendered on-demand in the server and streamed to the browser where they are slotted into the prerendered page. The bundle that is shipped to the browser can be kept light-weight because it mostly just needs to respond to user input by streaming the necessary page updates from the server over an open websocket connection.

If that sounds suspiciously like the architecture for modern server-side rendering that I described before, that is because it basically is. While a Next.JS codebase is likely to have some client-rendered components still, the extreme of a best practice Astro codebase would see every last component rendered on the server. In doing that they arrive at something functionally no different from LiveView architecture, and with a similar set of trade-offs. These architectures are simpler to work with, but they perform poorly for dynamic applications on low reliability or high latency connections, and they cannot work offline.

Another major simplication of the architecture is getting rid of the database middleman. Microservices and serverless functions are not as hyped as they were, people are happy to build so-called monoliths again, and frameworks are happy to recommend they do so. The meta-frameworks now suggest that the API can be merged into the web application frontend, and the framework will know that those parts are only meant to be run on the server. This radically simplifies the codebase, we're back to a single codebase for the entire application managed by a single framework.

However, TANSTAAFL. This simplification comes at the expense of other things. The Next.JS documentation may claim "Since Server Components are rendered on the server, you can safely make database queries using an ORM or database client." but that doesn't mean that it's actually safe to allow the part that faces the internet to have a direct line to the database. Defense in depth was a good idea, and we're back to trading security for simplicity. There were other reasons that monoliths once fell out of favor. It's like we're now forgetting lessons that were already learned.

Where does that leave us?

So, which architecture should you pick? I wish I could tell you, but you should have understood by now that the answer was always going to be it depends. Riffing on the work of Tolstoy: all web architectures are alike in that they are unhappy in their own unique way.

In a sense, all of these architectures are also unhappy in the same way: there's a whole internet in between the user and their data. There's a golden rule in software architecture: you can't beat physics with code. We draw the internet on diagrams as a cute little cloud, pretending it is not a physical thing. But the internet is wires, and antennas, and satellites, and data centers, and all kinds of physical things and places. Sending a signal through all those physical things and places will always be somewhat unreliable and somewhat slow. We cannot reliably deliver on the promise of a great user experience as long as we put a cute little cloud in between the user and their stuff.

In the next article I'll be exploring an obscure but very different architecture, a crazy thought similar to that of client-side rendering: what happens when we move the user's data from the server back into the client? What is local-first web application architecture?

Clean client-side routing

2025-06-25T12:00:00.000Z

The main Plain Vanilla tutorial explains two ways of doing client-side routing. Both use old school anchor tags for route navigation. First is the traditional multi-page approach described on the Sites page as one HTML file per route, great for content sites, not so great for web applications. Second is the hash-based routing approach decribed on the Applications page, one custom element per route, better for web applications, but not for having clean URLs or having Google index your content.

In this article I will describe a third way, single-file and single-page but with clean URLs using the pushState API, and still using anchor tags for route navigation. The conceit of this technique will be that it needs more code, and the tiniest bit of server cooperation.

Intercepting anchor clicks

To get a true single-page experience the first thing we have to do is intercept link tag navigation and redirect them to in-page events. Our SPA can then respond to these events by updating its routes.

export const routerEvents = new EventTarget();

export const interceptNavigation = (root) => {
    // convert link clicks to navigate events
    root.addEventListener('click', handleLinkClick);
    // convert navigate events to pushState() calls
    routerEvents.addEventListener('navigate', handleNavigate);
}

const handleLinkClick = (e) => {
    const a = e.target.closest('a');
    if (a && a.href) {
        e.preventDefault();
        const anchorUrl = new URL(a.href);
        const pageUrl = anchorUrl.pathname + anchorUrl.search + anchorUrl.hash;
        routerEvents.dispatchEvent(new CustomEvent('navigate', { detail: { url: pageUrl, a }}));
    }
}

const handleNavigate = (e) => {
    history.pushState(null, null, e.detail.url);
}

In an example HTML page we can leverage this to implement routing in a element.

import { routerEvents, interceptNavigation } from './view-route.js';

customElements.define('demo-app', class extends HTMLElement {

    #route = '/';

    constructor() {
        super();
        interceptNavigation(document.body);
        routerEvents.addEventListener('navigate', (e) => {
            this.#route = e.detail.url;
            this.update();
        });
    }

    connectedCallback() {
        this.update();
    }

    update() {
        if (this.#route === '/') {
            this.innerHTML = 'This is the homepage. Go to the details page.';
        } else if (this.#route === '/details') {
            this.innerHTML = 'This is the details page. Go to the home page.';
        } else {
            this.innerHTML = `The page ${this.#route} does not exist. Go to the home page.`;
        }
        this.innerHTML += `
Current route: ${this.#route}`;
    }
});

example 1

The first thing we're doing in view-route.js is the interceptNavigation() function. It adds an event handler at the top of the DOM that traps bubbling link clicks and turns them into a navigate event instead of the default action of browser page navigation. Then it also adds a navigate event listener that will update the browser's URL by calling pushState.

In app.js we can listen to the same navigate event to actually update the routes. Suddenly we've implemented a very basic in-page routing, but there are still a bunch of missing pieces.

There and back again

For one, browser back and forward buttons don't actually work. We can click and see the URL update in the browser, but the page does not respond. In order to do this, we need to start listening to popstate events.

However, this risks creating diverging code paths for route navigation, one for the navigate event and one for the popstate event. Ideally a single event listener responds to both types of navigation. A simplistic way of providing a single event to listen can look like this:

view-route.js (partial):

const handleNavigate = (e) => {
    history.pushState(null, null, e.detail.url);
    routerEvents.dispatchEvent(new PopStateEvent('popstate'));
}

// update routes on popstate (browser back/forward)
export const handlePopState = (e) => {
    routerEvents.dispatchEvent(new PopStateEvent('popstate', { state: e.state }));
}
window.addEventListener('popstate', handlePopState);

Now our views can respond to popstate events and update based on the current route. A second question then becomes: what is the current route? The popstate event does not carry that info. The window.location value does have that, and it is always updated as we navigate, but because it has the full URL it is cumbersome to parse. What is needed is a way of easily parsing it, something like this:

view-route.js (continued):

// ...

// all routes will be relative to the document's base path
const baseURL = new URL(window.originalHref || document.URL);
const basePath = baseURL.pathname.slice(0, baseURL.pathname.lastIndexOf('/'));

// returns an array of regex matches for matched routes, or null
export const matchesRoute = (path) => {
    const fullPath = basePath + '(' + path + ')';
    const regex = new RegExp(`^${fullPath.replaceAll('/', '\\/')}`, 'gi');
    const relativeUrl = location.pathname;
    return regex.exec(relativeUrl);
}

The matchesRoute() function accepts a regex to match as the route, and will wrap it so it is interpreted relative to the current document's URL, making all routes relative to our single page. Now we can clean up the application code leveraging these new generic routing features:

import { routerEvents, interceptNavigation, matchesRoute } from './view-route.js';

customElements.define('demo-app', class extends HTMLElement {

    #route = '/';

    constructor() {
        super();
        interceptNavigation(document.body);
        routerEvents.addEventListener('popstate', (e) => {
            const matches =
                matchesRoute('/details') || 
                matchesRoute('/');
            this.#route = matches?.[1];
            this.update();
        });
    }

    connectedCallback() {
        this.update();
    }

    update() {
        if (this.#route === '/') {
            this.innerHTML = 'This is the homepage. Go to the details page.';
        } else if (this.#route === '/details') {
            this.innerHTML = 'This is the details page. Go to the home page.';
        } else {
            this.innerHTML = `The page ${this.#route} does not exist. Go to the home page.`;
        }
        this.innerHTML += `
Current route: ${this.#route}`;
    }
});

example 2

Opening that in a separate tab we can see that the absolute URL neatly updates with the routes, that browser back/forwards navigation updates the view, and that inside the view the route is relative to the document.

Because matchesRoute() accepts a regex, it can be used to capture route components that are used inside of the view. Something like matchesRoute('/details/(?[\\w]+)') would put the ID in matches.groups.id. It's simple, but it gets the job done.

Can you use it in a sentence?

While this rudimentary way of detecting routes works, adding more routes quickly becomes unwieldy. It would be nice to instead have a declarative way of wrapping parts of views inside routes. Enter: a custom element to wrap each route in the page's markup.

view-route.js (partial):

// ...

customElements.define('view-route', class extends HTMLElement {

    #matches = [];

    get isActive() {
        return !!this.#matches?.length;
    }

    get matches() {
        return this.#matches;
    }

    set matches(v) {
        this.#matches = v;
        this.style.display = this.isActive ? 'contents' : 'none';
        if (this.isActive) {
            this.dispatchEvent(new CustomEvent('routechange', { detail: v, bubbles: true }));
        }
    }

    connectedCallback() {
        routerEvents.addEventListener('popstate', this);
        this.update();
    }

    disconnectedCallback() {
        routerEvents.removeEventListener('popstate', this);
    }

    handleEvent(e) {
        this.update();
    }

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

    attributeChangedCallback() {
        this.update();
    }

    update() {
        const path = this.getAttribute('path') || '/';
        this.matches = this.matchesRoute(path) || [];
    }

    matchesRoute(path) {
        // '*' triggers fallback route if no other route on the same DOM level matches
        if (path === '*') {
            const activeRoutes = 
                Array.from(this.parentNode.getElementsByTagName('view-route')).filter(_ => _.isActive);
            if (!activeRoutes.length) return [location.pathname, '*'];
        // normal routes
        } else {
            return matchesRoute(path);
        }
        return null;
    }
});

Now we can rewrite our app to be a lot more declarative, while preserving the behavior.

import { interceptNavigation } from './view-route.js';

customElements.define('demo-app', class extends HTMLElement {

    constructor() {
        super();
        interceptNavigation(document.body);
    }

    connectedCallback() {
        this.innerHTML = `
        
            This is the homepage. Go to the details page, or
            travel a path of mystery.
        
        
            This is the details page. Go to the home page.
        
        
            The page does not exist. Go to the home page.
        
        `
    }
});

example 3

404 not found

While things now look like they work perfectly, the illusion is shattered upon reloading the page when it is on the details route. To get rid of the 404 error we need a handler that will redirect to the main index page. This is typically something that requires server-side logic, locking us out from simple static hosting like GitHub Pages, but thanks to the kindness of internet strangers, there is a solution.

It involves creating a 404.html file that GitHub will load for any 404 error (the tiny bit of server cooperation). In this file the route is encoded as a query parameter, the page redirects to index.html, and inside that index page the route is restored.

index.html:

Adding this last piece to what we already had gets us a complete routing solution for vanilla single page applications that are hosted on GitHub Pages. Here's a live example hosted from there:

example 4

To full code of view-route.js and of this example is on GitHub.

Bringing React's to vanilla JS

2025-06-12T12:00:00.000Z

I like React. I really do. It is the default answer for modern web development, and it is that answer for a reason. Generally when React adds a feature it is well thought through, within the React system of thinking. My one criticism is that React by its nature overthinks things, that dumber and simpler solutions would often be on the whole ... better. Less magic, more predictable.

So when I port framework features to vanilla JS, don't take this as a slight of that framework. It is meant as an exploration of what dumber and simpler solutions might look like, when built on the ground floor of the web's platform instead of the lofty altitudes of big frameworks. It is a great way to learn.

Which brings me of course to today's topic: view transitions, and how to implement them.

View Transitions 101

Let's start with the basics: what is a view transition?

example 1

In a supporting browser, what you'll see when you click is a square smoothly transitioning between blue and orange on every button click. By supported browser I mean Chrome, Edge or Safari, but sadly not yet Firefox, although they're working on it! In Firefox you'll see the change, but applied immediately without the animation.

At the code level, it looks something like this:

example.js:

function transition() {
    const square1 = document.getElementById('square1');
    if (document.startViewTransition) {
        document.startViewTransition(() => {
            square1.classList.toggle('toggled');
        });
    } else {
        square1.classList.toggle('toggled');
    }
}

transitions.css:

#square1 {
    background-color: orange;
}
#square1.toggled {
    background-color: blue;
}

How this works is that the browser takes a snapshot of the page when we call document.startViewTransition(), takes another snapshot after the callback passed to it is done (or the promise it returns fulfills), and then figures out how to smoothly animate between the two snapshots, using a fade by default.

A very nice thing is that by putting a view-transition-name style on an element we can make it transition independently from the rest of the page, and we can control that transition through CSS.

example.js:

function transition() {
    const square1 = document.getElementById('square1');
    const square2 = document.getElementById('square2');
    if (document.startViewTransition) {
        document.startViewTransition(() => {
            square1.classList.toggle('toggled');
            square2.classList.toggle('toggled');
        });
    } else {
        square1.classList.toggle('toggled');
        square2.classList.toggle('toggled');
    }
}

transitions.css:

#square2 {
    background-color: green;
    view-transition-name: slide;
    display: none;
}
#square2.toggled {
    display: inline-block;
}
::view-transition-new(slide):only-child {
    animation: 400ms ease-in both slide-in;
}
@keyframes slide-in {
    from { transform: translateY(-200px); }
    to { transform: translateY(0); }
}

Now we can see a second square sliding in on the first click, and fading out on the second.

example 2

That's enough view transition basics for now. If you're curious for more, you can learn the rest in the chrome developer documentation.

Here comes trouble

Up to this point, we've gotten the fair weather version of view transitions, but there are paper cuts.

Firefox doesn't support view transitions at all, so we have to feature-detect.
There is only one actual current View Transitions standard, level 1, but most of the online tutorials talk about the unfinalized level 2.
If there are duplicate values of view-transition-name anywhere on the page, the animations disappear in a puff of duplicate element error smoke.
As always, there's a thing about shadow DOM, but more on that later.
Starting a new view transition when one is already running skips to the end of the previous one, bringing the smooth user experience to a jarring end.
User input is blocked while the view is transitioning, causing frustration when clicks are ignored.
The document.startViewTransition() function only accepts a single callback that returns a single promise.

It is the last one that really spells trouble. In a larger single-page web application we'll typically find a central routing layer that triggers a number of asynchronous updates every time the route changes. Wrapping those asynchronous updates into a single promise can be a challenge, as is finding the right place to "slot in" a call to document.startViewTransition().

Also, we probably don't even want to wait for all of the asynchronous updates to complete. Leaving the application in an interactive state in between two smaller view transitions is better than bundling it all together into one ponderous picture perfect transition animation.

What React did

React being React they solve those problems through magic, through exceeding cleverness. You can read up on their approach to view transitions, but distilling it down it becomes this:

Anything that should take part separately in a view transition is wrapped in a component.
React will choose unique view-transition-name style values, which DOM elements to set them on, and when to set them. This can be controlled through the name and key props.
Any updates that should become part of a view transition are wrapped in a startTransition() call.
React automatically figures out when to call document.startViewTransition(), and what updates to put inside the callback. It also cleverly avoids starting new transitions when one is already running, so startTransition() can be called from multiple places safely. Oh, and by the way, it feature detects, obviously.

When you do all of that, you get magic.

Good luck figuring out how it works, or how to troubleshoot when the magic loses its shine. But that is the bar, that is the lofty goal of user experience to reach with a dumber and simpler reimagining as vanilla JS. So let's get cooking.

A fresh start

Our starting point is a barebones implementation of a startTransition() function to replace what React's startTransition() does. It will fall back to non-animated transitions if our browser doesn't support document.startViewTransition.

export const startTransition = (updateCallback) => {
    if (document.startViewTransition) {
        document.startViewTransition(updateCallback);
    } else {
        const done = Promise.try(updateCallback);
        return {
            updateCallbackDone: done,
            ready: done,
            finished: done,
            skipTransition: () => {}
        };
    }
}

example.js:

import { startTransition } from './view-transition.js';

export function transition() {
    startTransition(() => {
        document.getElementById('square1').classList.toggle('toggled');
        document.getElementById('square2').classList.toggle('toggled');
    });
}

example 3

While that takes care of feature-detecting, we can still run into timing issues. For example, let's say that instead of toggling we were switching routes, and the second route needs to load data prior to animating in.

So with HTML like this:

We might intuitively choose to do something like this:

example.js:

import { startTransition } from './view-transition.js';

let currentRoute = '';

export function navigate() {
    currentRoute = currentRoute === 'route2' ? 'route1' : 'route2';
    updateRoute1();
    updateRoute2();
}

function updateRoute1() {
    startTransition(() => {
        if (currentRoute === 'route1') {
            document.getElementById('route1').classList.add('active');
        } else {
            document.getElementById('route1').classList.remove('active');
        }
    });
}

function updateRoute2() {
    startTransition(() => {
        const route2 = document.getElementById('route2');
        if (currentRoute === 'route2') {
            route2.classList.add('active', 'loading');
            route2.textContent = '...';
            load().then((data) => startTransition(() => {
                route2.textContent = data;
                route2.classList.remove('loading');
            }));
        } else {
            document.getElementById('route2').classList.remove('active');
        }
    });
}

function load() {
    return new Promise((resolve) => {
        setTimeout(() => {
            resolve('Hi!');
        }, 250);
    });
}

example 4

But, as you see when trying it out, it doesn't work. Because the startTransition() calls end up overlapping each other, the animation is interrupted, and we get a jarring experience. While this toy example can be made to work by tuning delays, in the real world those same delays are network-based, so there's no timing-based solution. We also can't solve this by bundling everything into one single big view transition, because that would imply blocking user input while a network request completes, which would be a bad user experience.

React solves all of this in the typical React way. It will smartly choose how to batch work into successive calls to document.startViewTransition(). It will take into account where something loads lazily, as in the previous example, and batch the work of animating in the content for the fallback in a separate view transition.

Taking a queue

Distilling that approach to its essence, the really useful part of React's solution is the queueing and batching of work. Any call to startTransition() that occurs while a view transition is running should be queued until after the transition completes, and nested calls should have all their updates batched together.

view-transition.js:

// the currently animating view transition
let currentTransition = null;
// the next transition to run (after currentTransition completes)
let nextTransition = null;

/** start a view transition or queue it for later if one is already animating */
export const startTransition = (updateCallback) => {
    if (!updateCallback) updateCallback = () => {};
    // a transition is active
    if (currentTransition && !currentTransition.isFinished) {
        // it is running callbacks, but not yet animating
        if (!currentTransition.isReady) {
            currentTransition.addCallback(updateCallback);
            return currentTransition;
        // it is already animating, queue callback in the next transition
        } else {
            if (!nextTransition) {
                nextTransition = new QueueingViewTransition();
            }
            return nextTransition.addCallback(updateCallback);
        }
    // if no transition is active, start animating the new transition
    } else {
        currentTransition = new QueueingViewTransition();
        currentTransition.addCallback(updateCallback);
        currentTransition.run();
        // after it's done, execute any queued transition
        const doNext = () => {
            if (nextTransition) {
                currentTransition = nextTransition;
                nextTransition = null;
                currentTransition.run();
                currentTransition.finished.finally(doNext);
            } else {
                currentTransition = null;
            }
        }
        currentTransition.finished.finally(doNext);
        return currentTransition;
    }
}

// ...

The QueueingViewTransition implementation is a straightforward batching of callbacks, and a single call to document.startViewTransition() that executes them in order. It is not included in the text of this article for brevity's sake, but linked at the bottom instead.

Applying that queueing solution on top of the previous example's unchanged code, we suddenly see the magic of clean view transitions between dynamically loading routes.

example 5

Back to the top

So as I was saying at the top, I like porting framework features to vanilla JS as a way of learning and exploring dumber and simpler solutions. Which brings me to the playground for that learning, a full port of React's tour-de-force example to vanilla web code.

example 6

The full code of this example is on GitHub. Arguably the 300 lines of code in the lib/ folder of that example constitute a mini-framework, but fascinating to me is that you can get so much mileage out of such a small amount of library code, with the resulting single-page application being more or less the same number of lines as the React original.

That example also shows how to do a purely client-side router with clean URLs using pushState(). This blog post has however gone too long already, so I'll leave that for another time.

One more thing

Oh yeah, I promised to talk about the thing with shadow DOM, and I promised a custom element. Here is the thing with shadow DOM: when document.startViewTransition() is called from the light DOM, it cannot see elements inside the shadow DOM that need to transition independently, unless those elements are exposed as DOM parts and a view-transition-name style is set on them in the light DOM.

If the solution to that intrigues you, it's in the GitHub example repo as well as a custom element. If that sounds like a bunch of mumbo jumbo instead, join the club. Just one more reason to avoid shadow DOM.

Making a new form control

2025-05-09T12:00:00.000Z

There are some things that a web developer knows they shouldn't attempt. Making clever use of contenteditable. Building custom form controls. Making complicated custom elements without a framework. But do we really know what we think we know? Why not try to do all three, just for fun? Could it really be that bad?

Narrator: it would indeed be that bad.

This article is building on the previous one on proper attribute/property relations in custom elements. Read that first if you haven't yet. In this piece we're taking it a step further to build a custom element that handles input. The mission is simple: implement a basic version of but with display: inline layout.

A simple element

Let's start by just throwing something against the wall and playing around with it.

customElements.define('input-inline', class extends HTMLElement {
    
    get value() {
        return this.getAttribute('value') ?? '';
    }
    set value(value) {
        this.setAttribute('value', String(value));
    }

    get name() {
        return this.getAttribute('name') ?? '';
    }
    set name(v) {
        this.setAttribute('name', String(v));
    }
    
    connectedCallback() {
        this.#update();
    }

    static observedAttributes = ['value'];
    attributeChangedCallback() {
        this.#update();
    }

    #update() {
        this.style.display = 'inline';
        if (this.textContent !== this.value) {
            this.textContent = this.value;
        }
        this.contentEditable = true;
    }
});

And here's how we use it:


    
        My favorite colors are  
        and .

demo1

This is simple, clean, and horribly broken. For one, the form cannot see these controls at all and submits the empty object.

Form-associated elements

To fix that, we have to make a form-associated custom element. This is done through the magic of the formAssociated property and ElementInternals.

input-inline.js:

customElements.define('input-inline', class extends HTMLElement {
    
    #internals;

    /* ... */

    constructor() {
        super();
        this.#internals = this.attachInternals();
        this.#internals.role = 'textbox';
    }
    
    /* ... */

    #update() {
        /* ... */
        this.#internals.setFormValue(this.value);
    }

    static formAssociated = true;
});

demo2

ElementInternals offers a control surface for setting the behavior of our custom element as part of a form. The this.#internals.role = 'textbox' assignment sets a default role that can be overridden by the element's user through the role attribute or property, just like for built-in form controls. By calling this.#internals.setFormValue every time the control's value changes the form will know what value to submit. But ... while the form does submit the values for our controls now, it does not see the changes we make. That's because we aren't responding to input yet.

Looking for input

Ostensibly responding to input is just adding a few event listeners in connectedCallback and removing them again in disconnectedCallback. But doing it that way quickly gets verbose. An easy alternative is to instead rely on some of the built-in event logic magic, namely that events bubble and that objects can be listeners too.

input-inline.js:

customElements.define('input-inline', class extends HTMLElement {
    
    #shouldFireChange = false;
    
    /* ... */

    constructor() {
        /* ... */
        this.addEventListener('input', this);
        this.addEventListener('keydown', this);
        this.addEventListener('paste', this);
        this.addEventListener('focusout', this);
    }

    handleEvent(e) {
        switch (e.type) {
            // respond to user input (typing, drag-and-drop, paste)
            case 'input':
                this.value = cleanTextContent(this.textContent);
                this.#shouldFireChange = true;
                break;
            // enter key should submit form instead of adding a new line
            case 'keydown':
                if (e.key === 'Enter') {
                    e.preventDefault();
                    this.#internals.form?.requestSubmit();
                }
                break;
            // prevent pasting rich text (firefox), or newlines (all browsers)
            case 'paste':
                e.preventDefault();
                const text = e.clipboardData.getData('text/plain')
                    // replace newlines and tabs with spaces
                    .replace(/[\n\r\t]+/g, ' ')
                    // limit length of pasted text to something reasonable
                    .substring(0, 1000);
                // shadowRoot.getSelection is non-standard, fallback to document in firefox
                // https://stackoverflow.com/a/70523247
                let selection = this.getRootNode()?.getSelection?.() || document.getSelection();
                let range = selection.getRangeAt(0);
                range.deleteContents();
                range.insertNode(document.createTextNode(text));
                // manually trigger input event to restore default behavior
                this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
                break;
            // fire change event on blur
            case 'focusout':
                if (this.#shouldFireChange) {
                    this.#shouldFireChange = false;
                    this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
                }
                break;
        }
    }
    
    /* ... */
});

function cleanTextContent(text) {
    return (text ?? '')
        // replace newlines and tabs with spaces
        .replace(/[\n\r\t]+/g, ' ');
}

demo3

I prefer this pattern because it simplifies the code a lot compared to having separate handler functions. Attaching event listeners in the constructor instead of attaching and detaching them in the lifecycle callbacks is another simplification. It may seem like blasphemy to never clean up the event listeners, but DOM event listeners are weakly bound and garbage collection of the element can still occur with them attached. So this is fine.

In the event handler logic there's some verbosity to deal with the fallout of working with contenteditable. As this code is not the focus of this article, I won't dally on it except to remark that contenteditable is still just as annoying as you thought it was.

With these changes our element will now also emit input and change events just like a built-in HTML form control. But, you may have noticed another issue has cropped up. The standard form reset button does not actually reset the form.

Read the instructions

You see, when we said static formAssociated = true we entered into a contract to faithfully implement the expected behavior of a form control. That means we have a bunch of extra work to do.

input-inline.js:

customElements.define('input-inline', class extends HTMLElement {
    
    /* ... */

    #formDisabled = false;
    #value;

    set value(v) {
        if (this.#value !== String(v)) {
            this.#value = String(v);
            this.#update();    
        }
    }
    get value() {
        return this.#value ?? this.defaultValue;
    }

    get defaultValue() {
        return this.getAttribute('value') ?? '';
    }
    set defaultValue(value) {
        this.setAttribute('value', String(value));
    }

    set disabled(v) {
        if (v) {
            this.setAttribute('disabled', 'true');
        } else {
            this.removeAttribute('disabled');
        }
    }
    get disabled() {
        return this.hasAttribute('disabled');
    }

    set readOnly(v) {
        if (v) {
            this.setAttribute('readonly', 'true');
        } else {
            this.removeAttribute('readonly');
        }
    }
    get readOnly() {
        return this.hasAttribute('readonly');
    }

    /* ... */

    static observedAttributes = ['value', 'disabled', 'readonly'];
    attributeChangedCallback() {
        this.#update();
    }

    #update() {
        this.style.display = 'inline';
        this.textContent = this.value;
        this.#internals.setFormValue(this.value);

        const isDisabled = this.#formDisabled || this.disabled;
        this.#internals.ariaDisabled = isDisabled;
        this.#internals.ariaReadOnly = this.readOnly;
        this.contentEditable = !this.readOnly && !isDisabled && 'plaintext-only';
        this.tabIndex = isDisabled ? -1 : 0;
    }

    static formAssociated = true;

    formResetCallback() {
        this.#value = undefined;
        this.#update();
    }
    
    formDisabledCallback(disabled) {
        this.#formDisabled = disabled;
        this.#update();
    }
    
    formStateRestoreCallback(state) {
        this.#value = state ?? undefined;
        this.#update();
    }
});

/* ... */

demo4

There's a LOT going on there. It's too much to explain, so let me sum up.

The value attribute now corresponds to a defaultValue property, which is the value shown until changed and also the value that the form will reset the field to.
The value property contains only the modified value and does not correspond to an attribute.
The control can be marked disabled or read-only through attribute or property.
The form callbacks are implemented, so the control can be reset to its default value, will restore its last value after back-navigation, and will disable itself when it is in a disabled fieldset.

With some style

Up to this point we've been using some stand-in styling. However, it would be nice to have some default styling that can be bundled with our custom form control. Something like this:

/* default styling has lowest priority */
@layer {
    :root {
        --input-inline-border-color: light-dark(rgb(118, 118, 118), rgb(161, 161, 161));
        --input-inline-border-color-hover: light-dark(rgb(78, 78, 78), rgb(200, 200, 200));
        --input-inline-border-color-disabled: rgba(150, 150, 150, 0.5);
        --input-inline-text-color: light-dark(fieldtext, rgb(240, 240, 240));
        --input-inline-text-color-disabled: light-dark(rgb(84, 84, 84), rgb(170, 170, 170));
        --input-inline-bg-color: inherit;
        --input-inline-bg-color-disabled: inherit;
        --input-inline-min-width: 4ch;
    }

    input-inline {
        display: inline;
        background-color: var(--input-inline-bg-color);
        color: var(--input-inline-text-color);
        border: 1px dotted var(--input-inline-border-color);
        padding: 2px 3px;
        margin-bottom: -2px;
        border-radius: 3px;
        /* minimum width */
        padding-right: max(3px, calc(var(--input-inline-min-width) - var(--current-length)));

        &:hover {
            border-color: var(--input-inline-border-color-hover);
        }
    
        &:disabled {
            border-color: var(--input-inline-border-color-disabled);
            background-color: var(--input-inline-bg-color-disabled);
            color: var(--input-inline-text-color-disabled);
            -webkit-user-select: none;
            user-select: none;
        }
    
        &:focus-visible {
            border-color: transparent;
            outline-offset: 0;
            outline: 2px solid royalblue; /* firefox */
            outline-color: -webkit-focus-ring-color; /* the rest */
        }
    }

    @media screen and (-webkit-min-device-pixel-ratio:0) {
        input-inline:empty::before {
            /* fixes issue where empty input-inline shifts left in chromium browsers */
            content: " ";
        }
    }

}

demo5

The styles are isolated by scoping them to the name of our custom element, and the use of @layer puts them at the lowest priority, so that any user style will override the default style, just like for the built-in form controls. The use of variables offers an additional way to quickly restyle the control.

In the styling we also see the importance of properly thinking out disabled and focused state behavior. The upside and downside of building a custom form control is that we get to implement all the behavior that's normally built-in to the browser.

We're now past the 150 lines mark, just to get to the low bar of implementing the browser's mandatory form control behavior. So, are we done? Well, not quite. There's still one thing that form controls do, and although it's optional it's also kind of required.

Validation

Built-in form controls come with a validity API. To get an idea of what it means to implement it in a custom form control, let's add one validation attribute: required. It doesn't seem like it should take a lot of work, right?

input-inline.js:

let VALUE_MISSING_MESSAGE = 'Please fill out this field.';
(() => {
    const input = document.createElement('input');
    input.required = true;
    input.reportValidity();
    VALUE_MISSING_MESSAGE = input.validationMessage;
})();

const isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);

customElements.define('input-inline', class extends HTMLElement {
    
    /* ... */

    #customValidityMessage = '';

    /* ... */

    set required(v) {
        if (v) {
            this.setAttribute('required', 'true');
        } else {
            this.removeAttribute('required');
        }
    }
    get required() {
        return this.hasAttribute('required');
    }

    /* ... */

    static observedAttributes = ['value', 'disabled', 'readonly', 'required'];
    attributeChangedCallback() {
        this.#update();
    }

    #update() {
        /* ... */

        this.#internals.ariaRequired = this.required;
        this.#updateValidity();
    }

    /* ... */

    #updateValidity() {
        const state = {};
        let message = '';

        // custom validity message overrides all else
        if (this.#customValidityMessage) {
            state.customError = true;
            message = this.#customValidityMessage;
        } else {
            if (this.required && !this.value) {
                state.valueMissing = true;
                message = VALUE_MISSING_MESSAGE;
            }
    
            // add other checks here if needed (e.g., pattern, minLength)
        }

        // safari needs a focusable validation anchor to show the validation message on form submit
        // and it must be a descendant of the input
        let anchor = undefined;
        if (isSafari) {
            anchor = this.querySelector('span[aria-hidden]');
            if (!anchor) {
                anchor = document.createElement('span');
                anchor.ariaHidden = true;
                anchor.tabIndex = 0;
                this.append(anchor);
            }
        }

        this.#internals.setValidity(state, message, anchor);
    }

    checkValidity() {
        this.#updateValidity();
        return this.#internals.checkValidity();
    }

    reportValidity() {
        this.#updateValidity();
        return this.#internals.reportValidity();
    }

    setCustomValidity(message) {
        this.#customValidityMessage = message ?? '';
        this.#updateValidity();
    }

    get validity() {
        return this.#internals.validity;
    }

    get validationMessage() {
        return this.#internals.validationMessage;
    }

    get willValidate() {
        return this.#internals.willValidate;
    }
});

/* ... */

demo6

The code for the example is exactly like it would be for built-in controls:


    
        My favorite color is .

The ElementInternals interface is doing a lot of the work here, but we still have to proxy its methods and properties. You can tell however that by this point we're deep in the weeds of custom elements, because of the rough edges.

The example is using the input-inline:invalid style instead of :user-invalid because :user-invalid is not supported on custom elements yet.
An ugly hack is needed to get the properly localized message for a required field that matches that of built-in controls.
Safari flat-out won't show validation messages on non-shadowed form-associated custom elements if we don't give it an anchor to set them to, requiring another ugly hack.

In conclusion

We've established by now that it is indeed feasible to build a custom form control and have it take part in regular HTML forms, but also that it is a path surrounded by peril as well as laborious to travel. Whether it is worth doing is in the eye of the beholder.

Along that path we also learned some lessons on how to handle input in custom elements, and have proven yet again that contenteditable, while less painful than it once was, is an attribute that can only be used in anger.

Regardless, the full source code of the input-inline form control is on GitHub.

The attribute/property duality

2025-04-21T12:00:00.000Z

Web components, a.k.a. custom elements, are HTML elements that participate in HTML markup. As such they can have attributes:

But, they are also JavaScript objects, and as such they can have object properties.

let myHello = document.querySelector('my-hello'); myHello.value = 'foo';

And here's the tricky part about that: these are not the same thing! In fact, custom element attributes and properties by default have zero relationship between them, even when they share a name. Here's a live proof of this fact:

customElements.define('my-hello', class extends HTMLElement {
    connectedCallback() {
        this.textContent = `Hello, ${ this.value || 'null' }!`;
    }
});

Demo: no connection between attribute and property

Now, to be fair, we can get at the attribute value just fine from JavaScript:

customElements.define('my-hello', class extends HTMLElement {
    connectedCallback() {
        this.textContent = `Hello, ${ this.getAttribute('value') || 'null' }!`;
    }
});

Demo: displaying the attribute

But what if we would also like it to have a value property? What should the relationship between attribute and property be like?

Does updating the attribute always update the property?
Does updating the property always update the attribute?
When updates can go either way, does the property read and update the value of the attribute, or do both attribute and property wrap around a private field on the custom element's class?
When updates can go either way, how to avoid loops where the property updates the attribute, which updates the property, which...
When is it fine to have just an attribute without a property, or a property without an attribute?

In framework-based code, we typically don't get a say in these things. Frameworks generally like to pretend that attributes and properties are the same thing, and they automatically create code to make sure this is the case. In vanilla custom elements however, not only do we get to decide these things, we must decide them.

Going native

Seasoned developers will intuitively grasp what the sensible relationship between attributes and properties should be. This is because built-in HTML elements all implement similar kinds of relationships between their attributes and their properties. To explore that in depth, I recommend reading Making Web Component properties behave closer to the platform. Without fully restating that article, here's a quick recap:

Properties can exist independent of an attribute, but an attribute will typically have a related property.
If changing the attribute updates the property, then updating the property will update the attribute.
Properties reflect either an internal value of an element, or the value of the corresponding attribute.
Assigning a value of an invalid type will coerce the value to the right type, instead of rejecting the change.
Change events are only dispatched for changes by user input, not from programmatic changes to attribute or property.

An easy way to get much of this behavior is to make a property wrap around an attribute:

customElements.define('my-hello', class extends HTMLElement {
    get value() {
        return this.getAttribute('value');
    }
    set value(v) {
        this.setAttribute('value', String(v));
    }
    
    static observedAttributes = ['value'];
    attributeChangedCallback() {
        this.textContent = `Hello, ${ this.value || 'null' }!`;
    }
});

Demo: property wraps attribute

Notice how updating the property will update the attribute in the HTML representation, and how the property's assigned value is coerced into the attribute's string type. Attributes are always strings.

Into the weeds

Up to this point, things are looking straightforward. But this is web development, things are never as straightforward as they seem. For instance, what boolean attribute value should make a corresponding boolean property become true? The surprising but standard behavior on built-in elements is that any attribute value will be interpreted as true, and only the absence of the attribute will be interpreted as false.

Time for another iteration of our element:

customElements.define('my-hello', class extends HTMLElement {
    get value() {
        return this.getAttribute('value');
    }
    set value(v) {
        this.setAttribute('value', String(v));
    }

    get glam() {
        return this.hasAttribute('glam');
    }
    set glam(v) {
        if (v) {
            this.setAttribute('glam', 'true');
        } else {
            this.removeAttribute('glam');
        }
    }
    
    static observedAttributes = ['value', 'glam'];
    attributeChangedCallback() {
        this.textContent = 
            `Hello, ${ this.value || 'null' }!` +
            (this.glam ? '!!@#!' : '');
    }
});

Demo: adding a boolean property

Which leaves us with the last bit of tricky trivia: it's possible for the custom element's class to be instantiated and attached to the element after the property is assigned. In that case the property's setter is never called, and the attribute is not updated.

// html:

// js:
const myHello = document.querySelector('my-hello');
myHello.value = 42; // setter not called before define
customElements.define('my-hello', /* ... */);
console.log(myHello.getAttribute('value')); // -> "world"

This can be avoided by reassigning any previously set properties when the element is connected:

customElements.define('my-hello', class extends HTMLElement {
    get value() {
        return this.getAttribute('value');
    }
    set value(v) {
        this.setAttribute('value', String(v));
    }

    get glam() {
        return this.hasAttribute('glam');
    }
    set glam(v) {
        if (v) {
            this.setAttribute('glam', 'true');
        } else {
            this.removeAttribute('glam');
        }
    }
    
    static observedAttributes = ['value', 'glam'];
    attributeChangedCallback() {
        this.textContent = 
            `Hello, ${ this.value || 'null' }!` +
            (this.glam ? '!!@#!' : '');
    }

    connectedCallback() {
        this.#upgradeProperty('value');
        this.#upgradeProperty('glam');
    }

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

In conclusion

If that seems like a lot of work to do a very simple thing, that is because it is. The good news is: we don't have to always do this work.

When we're using web components as framework components in a codebase that we control, we don't have to follow any of these unwritten rules and can keep the web component code as simple as we like. However, when using web components as custom elements to be used in HTML markup then we do well to follow these best practices to avoid surprises, especially when making web components that may be used by others. YMMV.

In the next article, I'll be looking into custom elements that accept input, and how that adds twists to the plot.

New year's resolve

2025-01-01T12:00:00.000Z

Today I was looking at what I want to write about in the coming year, and while checking out custom element micro-frameworks came across import.meta.resolve in the documentation for the Ponys micro-framework. That one simple trick is part of the essential toolbox that allows skipping build-time bundling, unlocking the vanilla web development achievement in the browser.

We need this toolbox because the build-time bundler does a lot of work for us:

Combining JS and CSS files to avoid slow page loads.
Resolving paths to the JS and CSS dependencies so we can have clean import statements.
Optimizing the bundled code, by stripping out whitespace, and removing unused imports thanks to a tree shaking algorithm.

It is not immediately apparent how to get these benefits without using a bundler.

Combining JS and CSS files

A typical framework-based web project contains hundreds or thousands of files. Having all those files loaded separately on a page load would be intolerably slow, hence the need for a bundler to reduce the file count. Even by stripping away third party dependencies we can still end up with dozens or hundreds of files constituting a vanilla web project.

When inspecting a page load in the browser's developer tools, we would then expect to see a lot of this:

The browser would download 6 files at a time and the later requests would block until those files downloaded. This limitation of HTTP/1 let to not just the solution of bundlers to reduce file count, but because the limitation of 6 parallel downloads was per domain it also led to the popularity of CDN networks which allowed cheating and downloading 12 files at once instead of 6.

However. It's 2025. What you're likely to see in this modern era is more like this:

Because almost all web servers have shifted over to HTTP/2, which no longer has this limitation of only having 6 files in flight at a time, we now see that all the files that are requested in parallel get downloaded in parallel. There's still a small caveat on lossy connections called head-of-line-blocking, fixed in HTTP/3, which is presently starting to roll out to web servers across the internet.

But the long and short of it is this: requesting a lot of files all at once just isn't that big of a problem anymore. We don't need to bundle up the files in a vanilla web project until the file counts get ridiculous.

Resolving paths

Another thing that bundlers do is resolving relative paths pointing to imported JS and CSS files. See, for example, the elegance of CSS modules for importing styles into a react component from a relative path:

layout.tsx (React):

import styles from './styles.module.css'
 
export default function Layout({
  children,
}: {
  children: React.ReactNode
}) {
  return {children}
}

However. It's 2025. And our browsers now have a modern vanilla toolbox for importing. When we bootstrap our JS with the magic incantation we unlock the magic ability to import JS files using ES module import notation:

index.js:

import { registerAvatarComponent } from './components/avatar.js';
const app = () => {
    registerAvatarComponent();
}
document.addEventListener('DOMContentLoaded', app);

Inside of such files we also get access to import.meta.url, the URL of the current JS file, and import.meta.resolve(), a function that resolves a path relative to the current file, even a path to a CSS file:

class Layout extends HTMLElement {
    constructor() {
        super();
        this.attachShadow({ mode: 'open' });
        this.shadowRoot.innerHTML = `
            
            
        `;
    }
}

export const registerLayoutComponent = 
    () => customElements.define('x-layout', Layout);

While not quite the same as what the bundler does, it still enables accessing any file by its relative path, and that in turn allows organizing projects in whatever way we want, for example in a feature-based folder organization. All without needing a build step.

This ability to do relative imports can be super-charged by import maps, which decouple the name of what is imported from the path of the file it is imported from, again all without involving a build step.

Optimizing bundled code

Another thing bundlers can do is optimizing the bundled code, by splitting the payload into things loaded initially, and things loaded later on lazily. And also by minifying it, stripping away unnecessary whitespace and comments so it will load faster.

However. It's 2025. We can transparently enable gzip or brotli compression on the server, and as it turns out that gets almost all the benefit of minifying. While minifying is nice, gzipping is what we really want, and we can get that without a build step.

And lazy loading, that works fine using dynamic import, and with a bit due diligence we can put some of the code behind such an import statement. I wrote before how React's lazy and suspense can be ported easily to vanilla web components.

Happy new year!

Great news! It's 2025, and the browser landscape is looking better than ever. It gives us enough tools that for many web projects we can drop the bundler and do just fine. You wouldn't believe it based on what the mainstream frameworks are doing though. Maybe 2025 is the year we finally see a wide recognition of just how powerful the browser platform has gotten, and a return to old school simplicity in web development practice, away from all those complicated build steps. It's my new year's resolve to do my part in spreading the word.

Caching vanilla sites

2024-12-16T12:00:00.000Z

If you go to a typical website built with a framework, you'll see a lot of this:

Those long cryptic filenames are not meant to discourage casual snooping. They're meant to ensure the filename is changed every time a single byte in that file changes, because the site is using far-future expire headers, a technique where the browser is told to cache files indefinitely, until the end of time. On successive page loads those resources will then always be served from cache. The only drawback is having to change the filename each time the file's contents change, but a framework's build steps typically take care of that.

For vanilla web sites, this strategy doesn't work. By abandoning a build step there is no way to automatically generate filenames, and unless nothing makes you happier than renaming all files manually every time you deploy a new version, we have to look towards other strategies.

How caching works

Browser cache behavior is complicated, and a deep dive into the topic deserves its own article. However, very simply put, what you'll see is mostly these response headers:

Cache-Control

The cache control response header determines whether the browser should cache the response, and how long it should serve the response from cache.

Cache-Control: public, max-age: 604800

This will cache the resource and only check if there's a new version after one week.

Age

The max-age directive does not measure age from the time that the response is received, but from the time that the response was originally served:

Age: 10

This response header indicates the response was served on the origin server 10 seconds ago.

Etag

The Etag header is a unique hash of the resource's contents, an identifier for that version of the resource.

ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

When the browser requests that resource again from the server, knowing the Etag it can pass an If-None-Match header with the Etag's value. If the resource has not changed it will still have the same Etag value, and the server will respond with 304 Not Modified.

If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Last-Modified

The Last-Modified header works similarly to Etag, except instead of sending a hash of the contents, it sends a timestamp of when the resource was last changed. Like Etag's If-None-Match it is matched by the If-Modified-Since header when requesting the resource from the server again.

With that basic review of caching headers, let's look at some strategies for making good use of them in vanilla web projects.

Keeping it simple: GitHub Pages

The simplest strategy is what GitHub Pages does: cache files for 10 minutes. Every file that's downloaded has Cache-Control: max-age headers that make it expire 10 minutes into the future. After that if the file is loaded again it will be requested from the network. The browser will add If-None-Match or If-Modified-Since headers to allow the server to avoid sending the file if it hasn't been changed, saving bytes but not a roundtrip.

If you want to see it in action, just open the browser devtools and reload this page.

Visitors never get a page that is more than 10 minutes out of date, and as they navigate around the site they mostly get fast cache-served responses. However, on repeat visits they will get a slow first-load experience. Also, if the server updates in the middle of a page load then different resources may end up mismatched and belong to a different version of the site, causing unpredictable bugs. Well, for 10 minutes at least.

Extending cache durations

While the 10 minute cache policy is ok for HTML content and small JS and CSS files, it can be improved by increasing cache times on large resources like libraries and images. By using a caching proxy that allows setting rules on specific types or folders of files we can increase the cache duration. For sites proxied through Cloudflare, their cache customization settings can be used to set these resource-specific policies.

By setting longer cache durations on some resources, we can ensure they're served from local cache more often. However, what to do if the resource changes? In those cases we need to modify the fetched URL of the resource every place that it is referred to. For example, by appending a unique query parameter:

The awkward aspect of having to change the referred URL in every place that a changed file is used makes extending cache durations inconvenient for files that are changed often or are referred in many places.

Also, applying such policies to JavaScript or CSS becomes a minefield, because a mismatched combination of JS or CSS files could end up in the browser cache indefinitely, breaking the website for the user until URL's are changed or their browser cache is cleared. For that reason, I don't think it's prudent to do this for anything but files that never change or that have some kind of version marker in their URL.

Complete control with service workers

A static web site can take complete control over its cache behavior by using a service worker. The service worker intercepts every network request and then decides whether to serve it from a local cache or from the network. For example, here's a service worker that will cache all resources indefinitely, until its version is changed:

let cacheName = 'cache-worker-v1';
// these are automatically cached when the site is first loaded
let initialAssets = [
    './',
    'index.html',
    'index.js',
    'index.css',
    'manifest.json',
    'android-chrome-512x512.png',
    'favicon.ico',
    'apple-touch-icon.png',
    'styles/reset.css',
    // the rest will be auto-discovered
];

// initial bundle (on first load)
self.addEventListener('install', (event) => {
    event.waitUntil(
        caches.open(cacheName).then((cache) => {
            return cache.addAll(initialAssets);
        })
    );
});

// clear out stale caches after service worker update
self.addEventListener('activate', (event) => {
    event.waitUntil(
        caches.keys().then((cacheNames) => {
            return Promise.all(
                cacheNames.map((cacheName) => {
                    if (cacheName !== self.cacheName) {
                        return caches.delete(cacheName);
                    }
                })
            );
        })
    );
});

// default to fetching from cache, fallback to network
self.addEventListener('fetch', (event) => {
    const url = new URL(event.request.url);

    // other origins bypass the cache
    if (url.origin !== location.origin) {
        networkOnly(event);
    // default to fetching from cache, and updating asynchronously
    } else {
        staleWhileRevalidate(event);
    }
});

const networkOnly = (event) => {
    event.respondWith(fetch(event.request));
}

// fetch events are serviced from cache if possible, but also updated behind the scenes
const staleWhileRevalidate = (event) => {
    event.respondWith(
        caches.match(event.request).then(cachedResponse => {
            const networkUpdate = 
                fetch(event.request).then(networkResponse => {
                    caches.open(cacheName).then(
                        cache => cache.put(event.request, networkResponse));
                    return networkResponse.clone();
                }).catch(_ => /*ignore because we're probably offline*/_);
            return cachedResponse || networkUpdate;
        })
    );
}

This recreates the far-future expiration strategy but does it client-side, inside the service worker. Because only the version at the top of the sw.js file needs to be updated when the site's contents change, this becomes practical to do without adding a build step. However, because the service worker intercepts network requests to change their behavior there is a risk that bugs could lead to a broken site, so this strategy is only for the careful and well-versed. (And no, the above service worker code hasn't been baked in production, so be careful when copying it to your own site.)

Wrapping up

Setting sane cache policies meant to optimize page load performance is one of the things typically in the domain of full-fat frameworks or application servers. But, abandoning build steps and server-side logic does not necessarily have to mean having poor caching performance. There are multiple strategies with varying amounts of cache control, and there is probably a suitable strategy for any plain vanilla site.

Last but not least, an even better way to speed up page loading is to keep the web page itself light. Using a plain vanilla approach to pages with zero dependencies baked into the page weight already puts you in pole position for good page load performance, before caching even enters the picture.

Editing Plain Vanilla

2024-10-20T12:00:00.000Z

I'm typing this up in Visual Studio Code, after realizing I should probably explain how I use it to make this site. But the whole idea behind Plain Vanilla is no build, no framework, no tools. And VS Code is definitely a tool. So what gives?

There's a difference between tools that sit in between the code and a deployed site, and tools that only act in support of editing or deploying. The first category, like npm or typescript, impose continued maintenance on the project because they form a direct dependency. The second category, like VS Code or git, are easily replaced without impacting the project's ability to be edited. There's a tension between the ability to get things done faster, and the burden created by additional dependencies. For this project I draw the line in accepting the second category while rejecting the first.

Setting up a profile

I use VS Code for framework-based work projects as well as vanilla web development. To keep those two realms neatly separated I've set up a separate Vanilla profile. In that profile is a much leaner suite of extensions, configured for only vanilla web development.

ESLint, to automatically lint the JS code while editing
webhint, to lint the HTML and CSS code, and detect accessibility issues
html-in-template-string, to syntax highlight HTML template strings
Todo Tree, to keep track of TODO's while doing larger changes
Live Preview, to get a live preview of the page that I'm working on
VS Code Counter, for quick comparative line counts when porting framework code to vanilla
Intellicode, for simple code completion
Codeium, for AI-assisted code completion, works great for web component boilerplate

Modern web development can be very overburdened by tools, sometimes all but requiring the latest Macbook Pro with decadent amounts of RAM just to edit a basic project. The combination of a no build plain vanilla codebase with a lean VS Code profile guarantees quick editing, even on my oldest and slowest laptops.

Linting

Nobody's perfect, myself included, so something needs to be scanning the code for goofs. The first linting tool that's set up is ESLint. The VS Code extension regrettably does not come bundled with an eslint installation, so this has to be installed explicitly. By doing it once globally this can be reused across vanilla web projects.

npm install -g eslint @eslint/js globals

Because I use nvm to manage node versions the global eslint install was not automatically detectable. This required setting a NODE_PATH in .zshrc that VS Code then picked up.

export NODE_PATH=$(npm root -g)

In addition, in order to lint successfully it needs a configuration file, located in the project's root.

/eslint.config.cjs:

/* eslint-disable no-undef */
const globals = require("globals");
const js = require("@eslint/js");

module.exports = [
    js.configs.recommended, 
    {
        languageOptions: {
            globals: {
                ...globals.browser,
                ...globals.mocha
            },
            ecmaVersion: 2022,
            sourceType: "module",
        }
    },
    {
        ignores: [
            "public/blog/articles/",
            "**/lib/",
            "**/react/",
        ]
    }
];

Setting the ecmaVersion to 2022 ensures that I don't accidentally use newer and unsupported Javascript features, like in this example trying to use ES2024's v flag in regular expressions. This version could be set to whatever browser compatibility a project requires.

The ignores blocks excludes external libraries to placate my OCD that wants to see zero errors or warnings reported by eslint project-wide. The article folders are excluded for a similar reason, because they contain a lot of incomplete and deliberately invalid example JS files.

The webhint extension is installed to do automatic linting on HTML and CSS. Luckily it out of the box comes bundled with a webhint installation and applies the default development ruleset. A nice thing about this extension is that it reports accessibility issues.

Only a few tweaks were made to the webhint configuration to again get to that all-important zero warnings count.

/.hintrc:

{
  "extends": [
    "development"
  ],
  "hints": {
    "compat-api/html": [
      "default",
      {
        "ignore": [
          "iframe[loading]"
        ]
      }
    ],
    "no-inline-styles": "off"
  }
}

html-in-template-string

I've mentioned it before in the entity encoding article, but this neat little extension formats HTML inside tagged template strings in web component JS code.

Live Preview

The center piece for a smooth editing workflow is the Live Preview extension. I can right-click on any HTML file in the project and select "Show Preview" to get a live preview of the page. This preview automatically refreshes when files are saved. Because vanilla web pages always load instantly this provides the hot-reloading workflow from framework projects, except even faster and with zero setup. The only gotcha is that all paths in the site have to be relative paths so the previewed page can resolve them.

The preview's URL can be pasted into a "real browser" to debug tricky javascript issues and do compatibility testing. Very occasionally I'll need to spin up a "real server", but most of the code in my vanilla projects is written with only a Live Preview tab open.

Previewing is also how I get a realtime view of unit tests while working on components or infrastructure code, by opening the tests web page and selecting the right test suite to hot reload while editing.

Bonus: working offline

Because I live at the beach and work in the big city I regularly need to take long train rides with spotty internet connection. Like many developers I cannot keep web API's in my head and have to look them up regularly while coding. To have a complete offline vanilla web development setup with me at all times I use devdocs.io. All my projects folders are set up to sync automatically with Syncthing, so whatever I was doing on the desktop can usually be smoothly continued offline on the laptop without having to do any prep work to make that possible.

There, that's my lean vanilla web development setup. What should I add to this, or do differently? Feel free to let me know.

Needs more context

2024-10-07T12:00:00.000Z

In the earlier article the unreasonable effectiveness of vanilla JS I explained a vanilla web version of the React tutorial example Scaling up with Reducer and Context. That example used a technique for context based on Element.closest(). While that way of obtaining a context is very simple, which definitely has its merits, it also has some downsides:

It cannot be used from inside a shadow DOM to find a context that lives outside of it without clumsy workarounds.
It requires a custom element to be the context.
There has to be separate mechanism to subscribe to context updates.

There is in fact, or so I learned recently, a better and more standard way to solve this known as the context protocol. It's not a browser feature, but a protocol for how to implement a context in web components.

This is how it works: the consumer starts by dispatching a context-request event.

class ContextRequestEvent extends Event {
    constructor(context, callback, subscribe) {
        super('context-request', {
            bubbles: true,
            composed: true,
        });
        this.context = context;
        this.callback = callback;
        this.subscribe = subscribe;
    }
}

customElements.define('my-component', class extends HTMLElement {
    connectedCallback() {
        this.dispatchEvent(
            new ContextRequestEvent('theme', (theme) => {
                // ...
            })
        );
    }
});

The event will travel up the DOM tree (bubbles = true), piercing any shadow DOM boundaries (composed = true), until it reaches a listener that responds to it. This listener is attached to the DOM by a context provider. The context provider uses the e.context property to detect whether it should respond, then calls e.callback with the appropriate context value. Finally it calls e.stopPropagation() so the event will stop bubbling up the DOM tree.

This whole song and dance is guaranteed to happen synchronously, which enables this elegant pattern:

customElements.define('my-component', class extends HTMLElement {
    connectedCallback() {
        let theme = 'light'; // default value
        this.dispatchEvent(
            new ContextRequestEvent('theme', t => theme = t)
        );
        // do something with theme
    }
});

If no provider is registered the event's callback is never called and the default value will be used instead.

Instead of doing a one-off request for a context's value it's also possible to subscribe to updates by setting its subscribe property to true. Every time the context's value changes the callback will be called again. To ensure proper cleanup the subscribing element has to unsubscribe on disconnect.

customElements.define('my-component', class extends HTMLElement {
    #unsubscribe;
    connectedCallback() {
        this.dispatchEvent(
            new ContextRequestEvent('theme', (theme, unsubscribe) => {
                this.#unsubscribe = unsubscribe;
                // do something with theme
            }, true)
        );
    }
    disconnectedCallback() {
        this.#unsubscribe?.();
    }
});

It is recommended, but not required, to listen for and call unsubscribe functions in one-off requests, just in case a provider is overzealously creating subscriptions. However, this is not necessary when using only spec-compliant providers.

customElements.define('my-component', class extends HTMLElement {
    connectedCallback() {
        let theme = 'light';
        this.dispatchEvent(
            new ContextRequestEvent('theme', (t, unsubscribe) => {
                theme = t;
                unsubscribe?.();
            })
        );
        // do something with theme
    }
});

Providers are somewhat more involved to implement. There are several spec-compliant libraries that implement them, like @lit/context and wc-context. A very minimal implementation is this one:

export class ContextProvider extends EventTarget {
    #value;
    get value() { return this.#value }
    set value(v) { this.#value = v; this.dispatchEvent(new Event('change')); }

    #context;
    get context() { return this.#context }

    constructor(target, context, initialValue = undefined) {
        super();
        this.#context = context;
        this.#value = initialValue;
        this.handle = this.handle.bind(this);
        if (target) this.attach(target);
    }
    
    attach(target) {
        target.addEventListener('context-request', this.handle);
    }

    detach(target) {
        target.removeEventListener('context-request', this.handle);
    }

    /**
     * Handle a context-request event
     * @param {ContextRequestEvent} e 
     */
    handle(e) {
        if (e.context === this.context) {
            if (e.subscribe) {
                const unsubscribe = () => this.removeEventListener('change', update);
                const update = () => e.callback(this.value, unsubscribe);
                this.addEventListener('change', update);
                update();
            } else {
                e.callback(this.value);
            }
            e.stopPropagation();
        }
    }
}

This minimal provider can then be used in a custom element like this:

customElements.define('theme-context', class extends HTMLElement {
    themeProvider = new ContextProvider(this, 'theme', 'light');
    toggleProvider = new ContextProvider(this, 'theme-toggle', () => {
        this.themeProvider.value = this.themeProvider.value === 'light' ? 'dark' : 'light';
    });
    connectedCallback() {
        this.style.display = 'contents';
    }
});

Which would be used on a page like this, with requesting the theme by dispatching a context-request event.

Notice in the above example that the theme-toggle context is providing a function. This unlocks a capability for dependency injection where API's to control page behavior are provided by a context to any subscribing custom element.

Don't let this example mislead you however. A provider doesn't actually need a dedicated custom element, and can be attached to any DOM node, even the body element itself. This means a context can be provided or consumed from anywhere on the page.

// loaded with 

import { ContextProvider } from "./context-provider.js";

const themeProvider = new ContextProvider(document.body, 'theme', 'light');
const toggleProvider = new ContextProvider(document.body, 'theme-toggle', () => {
    themeProvider.value = themeProvider.value === 'light' ? 'dark' : 'light';
});

And because there can be more than one event listener on a page, there can be more than one provider providing the same context. The first one to handle the event will win.

Here's an example that illustrates a combination of a global provider attached to the body (top panel), and a local provider using a (bottom panel). Every time the is reparented it resubscribes to the theme from the nearest provider.

combined example

index.js:

import { ContextRequestEvent } from "./context-request.js";
import "./theme-provider.js"; // global provider on body
import "./theme-context.js"; // element with local provider

customElements.define('theme-demo', class extends HTMLElement {
    connectedCallback() {
        this.innerHTML = `
            
                
            
            
                
                
            
            
        `;
        this.querySelector('button').onclick = reparent;
    }
});

customElements.define('theme-panel', class extends HTMLElement {
    #unsubscribe;

    connectedCallback() {
        this.dispatchEvent(new ContextRequestEvent('theme', (theme, unsubscribe) => {
            this.className = 'panel-' + theme;
            this.#unsubscribe = unsubscribe;
        }, true));
    }

    disconnectedCallback() {
        this.#unsubscribe?.();
    }
});

customElements.define('theme-toggle', class extends HTMLElement {
    #unsubscribe;

    connectedCallback() {
        this.innerHTML = '';
        this.dispatchEvent(new ContextRequestEvent('theme-toggle', (toggle) => {
            this.querySelector('button').onclick = toggle;
        }));
        this.dispatchEvent(new ContextRequestEvent('theme', (theme, unsubscribe) => {
            this.querySelector('button').className = 'button-' + theme;
            this.#unsubscribe = unsubscribe;
        }, true));
    }

    disconnectedCallback() {
        this.#unsubscribe?.();
    }
});

function reparent() {
    const toggle = document.querySelector('theme-toggle');
    const first = document.querySelector('theme-panel#first');
    const second = document.querySelector('theme-panel#second');
    if (toggle.parentNode === second) {
        first.append(toggle);
    } else {
        second.append(toggle);
    }
}

The full implementation of this protocol can be found in the tiny-context repo on Github.

Lived experience

2024-09-30T12:00:00.000Z

Ryan Carniato shared a hot take a few days ago, Web Components Are Not the Future. As hot takes tend to do, it got some responses, like Nolan Lawson's piece Web components are okay, or Cory LaViska's Web Components Are Not the Future — They're the Present. They do an excellent job of directly engaging Ryan's arguments, so I'm not going to do that here. Instead I want to talk about my lived experience of web development, and where I hope it is headed in the future. Take it in the spirit it is intended, one of optimism and possibility.

A galaxy far, far away

So I've been making web sites since a long time ago, since before CSS and HTML4. I say this not to humblebrag, but to explain that I was here for all of it. Every time when the definition of modern web development changed I would update my priors, following along.

For the longest time making web pages do anything except show text and images was an exercise in frustration. Browsers were severely lacking in features, were wildly incompatible with web standards and each other, and the tools that web developers needed to bring them to order were missing or lacking. I built my share of vanilla JS components back in the IE6 days, and it made me dream of a better way. When frameworks first started coming on the scene with that better way, adding missing features, abstracting away incompatibility, and providing better tooling, I was ready for them. I was all-in.

I bought into ExtJS, loved it for a time, and then got a hundred thousand line codebase stuck on ExtJS 3 because version 4 changed things so much that porting was too costly. I then bought into Backbone, loved that too, but had to move on when its principal developer did. I joined a team that bought into AngularJS and got stuck painted into a corner when the Angular team went in a totally different direction for v2. I helped rewrite a bunch of frontends in Angular v2 and React, and found myself sucked into constant forced maintenance when their architecture and ecosystems churned.

Did I make bad choices? Even in hindsight I would say I picked the right choices for the time. Time just moved on.

The cost of change

This lived experience taught me a strong awareness of rates of change in dependencies, and the costs they impose. I imagine a web page as a thin old man sitting astride a tall pile of dependencies, each changing at their own pace. Some dependencies are stable for decades, like HTML's core set of elements, or CSS 2's set of layout primitives. They're so stable that we don't even consider them dependencies, they're just the web.

Other dependencies change every few years, like module systems, or new transpiled languages, or the preferred build and bundling tool of the day, or what framework is in vogue. Then there are the dependencies that change yearly, like major framework and OS releases. Finally there are the dependencies that change constantly, like the many packages that contribute to a typical web application built with a popular framework.

As a web developer who loves their user, taking on those dependencies creates a Solomon's choice. Either you keep up with the churn, and spend a not insignificant amount of your day working and reworking code that already works, instead of working on the things your user cares about. Or, you stick it out for as long as you can on old versions, applying ever more workarounds to get old framework releases and their outdated build and CLI tools to work in new OS and ecosystem environments, slowly boiling a frog that will at some point force a deep rewrite, again at the expense of the user.

Which is not to say the frameworks don't add value. They absolutely do, and they keep getting better. Writing new code on a new framework is a steadily rising tide of developer experience. But let us not pretend these benefits don't come at a cost. Wherever there is a codebase too complicated to understand and maintain yourself, wherever there is a set of build tools that must be kept compatible with changes in operating systems and ecosystems, there is a shelf life. Sooner or later the makers of every framework and of every tool will move on, even if it's just to a new long-term supported release, and the web developers that they served will have to move with them.

I hold this truth to be self-evident: the larger the abstraction layer a web developer uses on top of web standards, the shorter the shelf life of their codebase becomes, and the more they will feel the churn.

The rising tide

Why do modern web projects built with modern frameworks depend on so much stuff? At first there was no other option. Interacting with the DOM was painful, and web frameworks rightly made choices to keep component systems outside the DOM, minimizing and abstracting away those interactions in increasingly clever DOM reconciliation strategies. Supporting the brittle browsers and slow devices of the day required many workarounds and polyfills, and web frameworks rightly added intricate tools to build, bundle and minify the user's code.

They needed a way to bring dependencies into those build systems, and sanely settled on the convention of node modules and the NPM ecosystem. It got easy to add more dependencies, and just as water always finds the easy way down, dependencies found the easy way in. As the abstraction layer grew the load time cost imposed by it grew right along, and so we got server-side rendering, client-side hydration, lazy loading, and many other load time reduction strategies.

DOM-diffing, synthetic event systems, functional components, JSX, reactive data layers, server-side rendering and streaming, bundlers, tree shaking, transpilers and compilers, and all the other complications that you won't find in web standards but you will find in every major web framework — they are the things invented to make the modern web possible, but they are not the web. The web is what ships to the browser. And all of those things are downstream from the decision to abstract away the browser, a decision once made in good faith and for good reasons. A decision which now needs revisiting.

Browsers were not standing still. They saw what web developers were doing in userland to compensate for the deficiencies in browser API's, and they kept improving and growing the platform, a rising tide slowly catching up to what frameworks did. When Microsoft bid IE a well-deserved farewell on June 15, 2022 a tipping point was reached. For the first time the browser platform was so capable that it felt to me like it didn't need so much abstracting away anymore. It wasn't a great platform, not as cleanly designed or complete as the API's of the popular frameworks, but it was Good Enough™ as a foundation, and that was all that mattered.

Holding my breath

I was very excited for what would happen in the framework ecosystem. There was a golden opportunity for frameworks to tear down their abstraction layers, make something far simpler, far more closely aligned with the base web platform. They could have a component system built on top of web components, leveraging browser events and built-in DOM API's. All the frameworks could become cross-compatible, easily plugging into each other's data layers and components while preserving what makes them unique. The page weights would shrink by an order of magnitude with so much infrastructure code removed, and that in combination with the move to HTTP/3 could make build tools optional. It would do less, so inevitably be worse in some ways, but sometimes worse is better.

I gave a talk about how good the browser's platform had gotten, showing off a version of Create React App that didn't need any build tools and was extremely light-weight, and the developer audience was just as excited as I was. And I held my breath waiting on framework churn to for once go in the other direction, towards simplicity...

But nothing happened. In fact, the major frameworks kept building up their abstraction layers instead of building down. We got React Server Components and React Compiler, exceedingly clever, utterly incomprehensible, workarounds for self-imposed problems caused by overengineering. Web developers don't seem to mind, but they struggle quietly with how to keep up with these tools and deliver good user experiences. The bigger the abstraction layer gets, the more they feel the churn.

The irony is not lost on me that now the framework authors also feel the churn in their dependencies, struggling to adapt to web components as foundational technology. React 19 is supposed to finally support web components in a way that isn't incredibly painful, or so they say, we'll see. I confess to feeling some satisfaction in their struggle. The shoe is on the other foot. Welcome to modern web development.

The road ahead

What the frameworks are doing, that's fine for them, and they can keep doing it. But I'm done with all that unless someone is paying me to do it. They're on a fundamentally different path from where I want web development to go, from how I want to make web pages. The web is what ships to the browser. Reducing the distance between what the developer writes and what ships to the browser is valuable and necessary. This blog and this site are my own stake in the ground for this idea, showing just how much you can get done without any framework code or build tools at all. But let's be honest: web components are not a framework, no matter how hard I tried to explain them as one.

Comparing web components to React is like comparing a good bicycle with a cybertruck.

They do very different things, and they're used by different people with very, very different mindsets.

Jeremy Keith

I want a motorbike, not a cybertruck. I still want frameworks, only much lighter. Frameworks less than 10 KB in size, that are a thin layer on top of web standards but still solve the problems that frameworks solve. I call this idea the interoperable web framework:

Its components are just web components.
Its events are just DOM events.
Its templates are just HTML templates.
It doesn't need to own the DOM that its components take part in.
Its data and event binding works on all HTML elements, built-in or custom, made with the framework or with something else.
It can be easily mixed together on a page with other interoperable web frameworks, with older versions of itself, or with vanilla code.
It doesn't need its own build tools.

I just feel it on my bones such a thing can be built now. Maybe I'm wrong and Ryan Carniato is right. After all, he knows a lot more about frameworks than I do. But the more vanilla code that I write the more certain that I feel on this. Some existing solutions like Lit are close, but none are precisely what I am looking for. I would love to see a community of vanilla developers come together to figure out what that could look like, running experiments and iterating on the results. For now I will just keep holding my breath, waiting for the tide to come in.

The unreasonable effectiveness of vanilla JS

2024-09-28T12:00:00.000Z

I have a confession to make. At the end of the Plain Vanilla tutorial's Applications page a challenge was posed to the reader: port react.dev's final example Scaling Up with Reducer and Context to vanilla web code. Here's the confession: until today I had never actually ported over that example myself.

That example demonstrates a cornucopia of React's featureset. Richly interactive UI showing a tasks application, making use of a context to lift the task state up, and a reducer that the UI's controls dispatch to. React's DOM-diffing algorithm gets a real workout because each task in the list can be edited independently from and concurrently with the other tasks. It is an intricate and impressive demonstration. Here it is in its interactive glory:

complete example

But I lied. That interactive example is actually the vanilla version and it is identical. If you want to verify that it is in fact identical, check out the original React example. And with that out of the way, let's break apart the vanilla code.

Project setup

The React version has these code files that we will need to port:

public/index.html
src/styles.css
src/index.js: imports the styles, bootstraps React and renders the App component
src/App.js: renders the context's TasksProvider containing the AddTask and TaskList components
src/AddTask.js: renders the simple form at the top to add a new task
src/TaskList.js: renders the list of tasks

To make things fun, I chose the same set of files with the same filenames for the vanilla version. Here's index.html:

index.html:




    
    
    Document

The only real difference is that it links to index.js and styles.css. The stylesheet was copied verbatim, but for the curious here's a link to styles.css.

Get to the code

index.js is where it starts to get interesting. Compare the React version to the vanilla version:

index.js (React):

import React, { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./styles.css";

import App from "./App";

const root = createRoot(document.getElementById("root"));
root.render(
  
    
  
);

index.js (Vanilla):

import './App.js';
import './AddTask.js';
import './TaskList.js';
import './TasksContext.js';

const render = () => {
    const root = document.getElementById('root');
    root.append(document.createElement('tasks-app'));
}

document.addEventListener('DOMContentLoaded', render);

Bootstrapping is different but also similar. All of the web components are imported first to load them, and then the component is rendered to the page.

The App.js code also bears more than a striking resemblance:

App.js (React):

import AddTask from './AddTask.js';
import TaskList from './TaskList.js';
import { TasksProvider } from './TasksContext.js';

export default function TaskApp() {
  return (
    
      Day off in Kyoto
      
      
    
  );
}

App.js (Vanilla):

customElements.define('tasks-app', class extends HTMLElement {
    connectedCallback() {
        this.innerHTML = `
            
                Day off in Kyoto
                
                
            
        `;
    }
});

What I like about the code so far is that it feels React-like. I generally find programming against React's API pleasing, but I don't like the tooling, page weight and overall complexity baggage that it comes with.

Adding context

The broad outline of how to bring a React-like context to a vanilla web application is already explained in the passing data deeply section of the main Plain Vanilla tutorial, so I won't cover that again here. What adds spice in this specific case is that the React context uses a reducer, a function that accepts the old tasks and an action to apply to them, and returns the new tasks to show throughout the application.

Thankfully, the React example's reducer function and initial state were already vanilla JS code, so those come along for the ride unchanged and ultimately the vanilla context is a very straightforward custom element:

TasksContext.js (Vanilla):

customElements.define('tasks-context', class extends HTMLElement {
    #tasks = structuredClone(initialTasks);
    get tasks() { return this.#tasks; }
    set tasks(tasks) {
        this.#tasks = tasks;
        this.dispatchEvent(new Event('change'));
    }

    dispatch(action) {
        this.tasks = tasksReducer(this.tasks, action);
    }

    connectedCallback() {
        this.style.display = 'contents';
    }
});

function tasksReducer(tasks, action) {
    switch (action.type) {
        case 'added': {
            return [...tasks, {
                id: action.id,
                text: action.text,
                done: false
            }];
        }
        case 'changed': {
            return tasks.map(t => {
                if (t.id === action.task.id) {
                    return action.task;
                } else {
                    return t;
                }
            });
        }
        case 'deleted': {
            return tasks.filter(t => t.id !== action.id);
        }
        default: {
            throw Error('Unknown action: ' + action.type);
        }
    }
}

const initialTasks = [
    { id: 0, text: 'Philosopher’s Path', done: true },
    { id: 1, text: 'Visit the temple', done: false },
    { id: 2, text: 'Drink matcha', done: false }
];

The actual context component is very bare bones, as it only needs to store the tasks, emit change events for the other components to subscribe to, and provide a dispatch method for those components to call that will use the reducer function to update the tasks.

Adding tasks

The AddTask component ends up offering more of a challenge. It's a stateful component with event listeners that dispatches to the reducer:

AddTask.js (React):

import { useState } from 'react';
import { useTasksDispatch } from './TasksContext.js';

export default function AddTask() {
  const [text, setText] = useState('');
  const dispatch = useTasksDispatch();
  return (
    <>
       setText(e.target.value)}
      />
      
    
  );
}

let nextId = 3;

The main wrinkle this adds for the vanilla web component is that the event listener on the button element cannot be put inline with the markup. Luckily the handling of the input is much simplified because we can rely on it keeping its state automatically, a convenience owed to not using a virtual DOM. Thanks to the groundwork in the context component the actual dispatching of the action is easy:

AddTask.js (Vanilla):

customElements.define('task-add', class extends HTMLElement {
    connectedCallback() {
        this.innerHTML = `
            
            
        `;
        this.querySelector('button').onclick = () => {
            const input = this.querySelector('input');
            this.closest('tasks-context').dispatch({
                type: 'added',
                id: nextId++,
                text: input.value
            });
            input.value = '';
        };
    }
})

let nextId = 3;

Fascinating to me is that index.js, App.js, TasksContext.js and AddTask.js are all fewer lines of code in the vanilla version than their React counterpart while remaining functionally equivalent.

Hard mode

The TaskList component is where React starts really pulling its weight. The React version is clean and straightforward and juggles a lot of state with a constantly updating task list UI.

TaskList.js (React):

import { useState } from 'react';
import { useTasks, useTasksDispatch } from './TasksContext.js';

export default function TaskList() {
  const tasks = useTasks();
  return (
    
      {tasks.map(task => (
        
          
        
      ))}
    
  );
}

function Task({ task }) {
  const [isEditing, setIsEditing] = useState(false);
  const dispatch = useTasksDispatch();
  let taskContent;
  if (isEditing) {
    taskContent = (
      <>
         {
            dispatch({
              type: 'changed',
              task: {
                ...task,
                text: e.target.value
              }
            });
          }} />
        
      
    );
  } else {
    taskContent = (
      <>
        {task.text}
        
      
    );
  }
  return (
    
       {
          dispatch({
            type: 'changed',
            task: {
              ...task,
              done: e.target.checked
            }
          });
        }}
      />
      {taskContent}
      
    
  );
}

This proved to be a real challenge to port. The vanilla version ended up being a lot more verbose because it has to do all the same DOM-reconciliation in explicit logic managed by the update() methods of and .

TaskList.js (Vanilla):

customElements.define('task-list', class extends HTMLElement {
    get context() { return this.closest('tasks-context'); }
    
    connectedCallback() {
        this.context.addEventListener('change', () => this.update());
        this.append(document.createElement('ul'));
        this.update();
    }

    update() {
        const ul = this.querySelector('ul');
        let before = ul.firstChild;
        this.context.tasks.forEach(task => {
            let li = ul.querySelector(`:scope > [data-key="${task.id}"]`);
            if (!li) {
                li = document.createElement('li');
                li.dataset.key = task.id;
                li.append(document.createElement('task-item'));
            }
            li.firstChild.task = task;
            // move to the right position in the list if not there yet
            if (li !== before) ul.insertBefore(li, before);
            before = li.nextSibling;
        });
        // remove unknown nodes
        while (before) {
            const remove = before;
            before = before.nextSibling;
            ul.removeChild(remove);
        }
    }
});

customElements.define('task-item', class extends HTMLElement {
    #isEditing = false;
    #task;
    set task(task) { this.#task = task; this.update(); }
    get context() { return this.closest('tasks-context'); }

    connectedCallback() {
        if (this.querySelector('label')) return;
        this.innerHTML = `
            
                
                
                
                
                
                
            
        `;
        this.querySelector('input[type=checkbox]').onchange = e => {
            this.context.dispatch({
                type: 'changed',
                task: {
                    ...this.#task,
                    done: e.target.checked
                }
            });
        };
        this.querySelector('input[type=text]').onchange = e => {
            this.context.dispatch({
                type: 'changed',
                task: {
                    ...this.#task,
                    text: e.target.value
                }
            });
        };
        this.querySelector('button#edit').onclick = () => {
            this.#isEditing = true;
            this.update();
        };
        this.querySelector('button#save').onclick = () => {
            this.#isEditing = false;
            this.update();
        };
        this.querySelector('button#delete').onclick = () => {
            this.context.dispatch({
                type: 'deleted',
                id: this.#task.id
            });
        };
        this.context.addEventListener('change', () => this.update());
        this.update();
    }

    update() {
        if (this.isConnected && this.#task) {
            this.querySelector('input[type=checkbox]').checked = this.#task.done;
            const inputEdit = this.querySelector('input[type=text]');
            inputEdit.style.display = this.#isEditing ? 'inline' : 'none';
            inputEdit.value = this.#task.text;
            const span = this.querySelector('span');
            span.style.display = this.#isEditing ? 'none' : 'inline';
            span.textContent = this.#task.text;
            this.querySelector('button#edit').style.display = this.#isEditing ? 'none' : 'inline';
            this.querySelector('button#save').style.display = this.#isEditing ? 'inline' : 'none';
        }
    }
});

Some interesting take-aways:

The component's update() method implements a poor man's version of React reconciliation, merging the current state of the tasks array into the child nodes of the
- nodes that match up to task items, and so would have to recreate the entire list. By adding the key it becomes possible to update the list in-place, modifying task items instead of recreating them so that they can keep their on-going edit state.
- That reconciliation code is very generic however, and it is easy to imagine a fully generic repeat() function that converts an array of data to markup on the page. In fact, the Lit framework contains exactly that. For brevity's sake this code doesn't go quite that far.
- The component cannot do what the React code does: create different markup depending on the current state. Instead it creates the union of the markup across the various states, and then in the update() shows the right subset of elements based on the current state.
That wraps up the entire code. You can find the ported example on Github.

Some thoughts

A peculiar result of this porting challenge is that the vanilla version ends up being roughly the same number of lines of code as the React version. The React code is still overall less verbose (all those querySelectors, oy!), but it has its own share of boilerplate that disappears in the vanilla version. This isn't a diss against React, it's more of a compliment to how capable browsers have gotten that vanilla web components can carry us so far.

If I could have waved a magic wand, what would have made the vanilla version simpler?
- All of those querySelector calls get annoying. The alternatives are building the markup easily with innerHTML and then fishing out references to the created elements using querySelector, or building the elements one by one verbosely using createElement, but then easily having a reference to them. Either of those ends up very verbose. An alternative templating approach that makes it easy to create elements and get a reference to them would be very welcome.
- As long as we're dreaming, I'm jealous of how easy it is to add the event listeners in JSX. A real expression language in HTML templates that supports data and event binding and data-conditional markup would be very neat and would take away most of the reason to still find a framework's templating language more convenient. Web components are a perfectly fine alternative to React components, they just lack an easy built-in templating mechanism.
- Browsers could get a little smarter about how they handle DOM updates during event handling. In the logic that sorts the
- to the right order in the list, the if condition before insertBefore proved necessary because the browser didn't notice that the element was already placed where it needed to be inserted, and click events would get lost as a consequence. I've even noticed that assigning a textContent to a button mid-click will make Safari lose track of that button's click event. All of that can be worked around with clever reconciliation logic, but that's code that belongs in the browser, not in JavaScript.
All in all though, I'm really impressed with vanilla JS. I call it unreasonably effective because it is jarring just how capable the built-in abilities of browsers are, and just how many web developers despite that still default to web frameworks for every new project. Maybe one day...

The life and times of a web component

2024-09-16T12:00:00.000Z

When first taught about the wave-particle duality of light most people's brains does a double take. How can light be two different categories of things at the same time, both a wave and a particle? That's just weird. The same thing happens with web components, confusing people when they first try to learn them and run into their Document-JavaScript duality. The component systems in frameworks are typically JavaScript-first, only using the DOM as an outlet for their visual appearance. Web components however — or custom elements to be precise — can start out in either JavaScript or the document, and are married to neither.

Just the DOM please

Do you want to see the minimal JavaScript code needed to set up an custom element? Here it is:

No, that's not a typo. Custom elements can be used just fine without any JavaScript. Consider this example of an custom element that is HTML and CSS only:

undefined/example.html

example.html:



    
        
        
        undefined custom element

For the curious, here is the example.css, but it is not important here.

Such elements are called undefined custom elements. Before custom elements are defined in the window by calling customElements.define() they always start out in this state. There is no need to actually define the custom element if it can be solved in a pure CSS way. In fact, many "pure CSS" components found online can be solved by such custom elements, by styling the element itself and its ::before and ::after pseudo-elements.

A question of definition

The CSS-only representation of the custom element can be progressively enhanced by connecting it up to a JavaScript counterpart, a custom element class. This is a class that inherits from HTMLElement and allows the custom element to implement its own logic.

defined/example.html

example.html:



    
        
        defining the custom element
        
    
    
        Custom element:

What happens to the elements already in the markup at the moment customElements.define() is called is an element upgrade. The browser will take all custom elements already in the document, and create an instance of the matching custom element class that it connects them to. This class enables the element to control its own part of the DOM, but also allows it to react to what happens in the DOM.

Element upgrades occur for existing custom elements in the document when customElements.define() is called, and for all new custom elements with that tag name created afterwards (e.g. using document.createElement('x-example')). It does not occur automatically for detached custom elements (not part of the document) that were created before the element was defined. Those can be upgraded retroactively by calling customElements.upgrade().

So far, this is the part of the lifecycle we've seen:

 
    -> define() -> 
    -> automatic upgrade() 
                -> constructor() 
                ->

The constructor as shown in the example above is optional, but if it is specified then it has a number of gotcha's:

It must start with a call to super().
It should not make DOM changes yet, as the element is not yet guaranteed to be connected to the DOM.: This includes reading or modifying its own DOM properties, like its attributes. The tricky part is that in the constructor the element might already be in the DOM, so setting attributes might work. Or it might give an error. It's best to avoid DOM interaction altogether in the constructor.
It should initialize its state, like class properties: But work done in the constructor should be minimized and maximally postponed until connectedCallback.

Making connections

After being constructed, if the element was already in the document, its connectedCallback() handler is called. This handler is normally called only when the element is inserted into the document, but for elements that are already in the document when they are defined it ends up being called as well. In this handler DOM changes can be made, and in the example above the status attribute is set to demonstrate this.

The connectedCallback() handler is part of what is known in the HTML standard as custom element reactions: These reactions allow the element to respond to various changes to the DOM:

connectedCallback() is called when the element is inserted into the document, even if it was only moved from a different place in the same document.
disconnectedCallback() is called when the element is removed from the document.
adoptedCallback() is called when the element is moved to a new document. (You are unlikely to need this in practice.)
attributeChangedCallback() is called when an attribute is changed, but only for the attributes listed in its observedAttributes property.

There are also special reactions for form-associated custom elements, but those are a rabbit hole beyond the purview of this blog post.

There are more gotcha's to these reactions:

connectedCallback() and disconnectedCallback() can be called multiple times: This can occur when the element is moved around in the document. These handlers should be written in such a way that it is harmless to run them multiple times, e.g. by doing an early exit when it is detected that connectedCallback() was already run.
attributeChangedCallback() can be called before connectedCallback(): For all attributes already set when the element in the document is upgraded, the attributeChangedCallback() handler will be called first, and only after this connectedCallback() is called. The unpleasant consequence is that any attributeChangedCallback that tries to update DOM structures created in connectedCallback can produce errors.
attributeChangedCallback() is only called for attribute changes, not property changes.: Attribute changes can be done in Javascript by calling element.setAttribute('name', 'value'). DOM attributes and class properties can have the same name, but are not automatically linked. Generally for this reason it is better to avoid having attributes and properties with the same name.

The lifecycle covered up to this point for elements that start out in the initial document:

 
    -> define() -> 
    -> automatic upgrade() 
                -> [element].constructor()
                -> [element].attributeChangedCallback()
                -> [element].connectedCallback() 
                ->

Flip the script

So far we've covered one half of the Document-JavaScript duality, for custom elements starting out in the document, and only after that becoming defined and gaining a JavaScript counterpart. It is however also possible to reverse the flow, and start out from JavaScript.

This is the minimal code to create a custom element in JavaScript: document.createElement('x-example'). The element does not need to be defined in order to run this code, although it can be, and the resulting node can be inserted into the document as if it was part of the original HTML markup.

If it is inserted, and after insertion the element becomes defined, then it will behave as described above. Things are however different if the element remains detached:

The detached element will not be automatically upgraded when it is defined.: The constructor or reactions will not be called. It will be automatically upgraded when it is inserted into the document. It can also be upgraded explicitly by calling customElements.upgrade().
If the detached element is already defined when it is created, it will be upgraded automatically.: The constructor() and attributeChangedCallback() will be called. Because it is not yet part of the document connectedCallback() won't be.

By now no doubt you are a bit confused. Here's an interactive playground that lets you test what happens to elements as they go through their lifecycle, both for those in the initial document and those created dynamically.

defined2/example.html

Here are some interesting things to try out:

Create, then Define, and you will see that the created element is not upgraded automatically because it is detached from the document.
Create, then Connect, then Define, and you will see that the element is upgraded automatically because it is in the document.
Define, then Create, and you will see that the element is upgraded as soon as it is created (constructed appears in the reactions).

I tried writing a flowchart of all possible paths through the lifecycle that can be seen in this example, but it got so unwieldy that I think it's better to just play around with the example until a solid grasp develops.

In the shadows

Adding shadow DOM creates yet another wrinkle in the lifecycle. At any point in the element's JavaScript half, including in its constructor, a shadow DOM can be attached to the element by calling attachShadow(). Because the shadow DOM is immediately available for DOM operations, that makes it possible to do those DOM operations in the constructor.

In this next interactive example you can see what happens when the shadow DOM becomes attached. The x-shadowed element will immediately attach a shadow DOM in its constructor, which happens when the element is upgraded automatically after defining. The x-shadowed-later element postpones adding a shadow DOM until a link is clicked, so the element first starts out as a non-shadowed custom element, and adds a shadow DOM later.

shadowed/example.html

example.html:



    
        
        shadowed custom element
        
    
    
        <x-shadowed>: undefined, not shadowed
        <x-shadowed-later>: undefined, not shadowed

While adding a shadow DOM can be done at any point, it is a one-way operation. Once added the shadow DOM will replace the element's original contents, and this cannot be undone.

Keeping an eye out

So far we've mostly been dealing with initial setup of the custom element, but a major part of the lifecycle is responding to changes as they occur. Here are some of the major ways that custom elements can respond to DOM changes:

connectedCallback and disconnectedCallback to handle DOM insert and remove of the element itself.
attributeChangedCallback to handle attribute changes of the element.
For shadowed custom elements, the slotchange event can be used to detect when children are added and removed in a .
Saving the best for last, MutationObserver can be used to monitor DOM subtree changes, as well as attribute changes.

MutationObserver in particular is worth exploring, because it is a swiss army knife for monitoring the DOM. Here's an example of a counter that automatically updates when new child elements are added:

observer/example.html

example.html:


 
    
        
        custom element with observer

There is still more to tell, but already I can feel eyes glazing over and brains turning to mush, so I will keep the rest for another day.

Phew, that was a much longer story than I originally set out to write, but custom elements have surprising intricacy. I hope you found it useful, and if not at least you got to see some code and click some buttons. It's all about the clicking of the buttons.

Sweet Suspense

2024-09-09T12:00:00.000Z

I was reading Addy Osmani and Hassan Djirdeh's book Building Large Scale Web Apps. (Which, by the way, I can definitely recommend.) In it they cover all the ways to make a React app sing at scale. The chapter on Modularity was especially interesting to me, because JavaScript modules are a common approach to modularity in both React and vanilla web code.

In that chapter on Modularity there was one particular topic that caught my eye, and it was the use of lazy() and Suspense, paired with an ErrorBoundary. These are the primitives that React gives us to asynchronously load UI components and their data on-demand while showing a fallback UI, and replace the UI with an error message when something goes wrong. If you're not familiar, here's a good overview page.

It was at that time that I was visited by the imp of the perverse, which posed to me a simple challenge: can you bring React's lazy loading primitives to vanilla web components? To be clear, there are many ways to load web components lazily. This is well-trodden territory. What wasn't out there was a straight port of lazy, suspense and error boundary. The idea would not let me go. So here goes nothing.

Lazy

The idea and execution of React's lazy is simple. Whenever you want to use a component in your code, but you don't want to actually fetch its code yet until it needs to be rendered, wrap it using the lazy() function:
const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));

React will automatically "suspend" rendering when it first bumps into this lazy component until the component has loaded, and then continue automatically.

This works in React because the markup of a component only looks like HTML, but is actually JavaScript in disguise, better known as JSX. With web components however, the markup that the component is used in is actually HTML, where there is no import() and no calling of functions. That means our vanilla lazy cannot be a JavaScript function, but instead it must be an HTML custom element:

The basic setup is simple, when the lazy component is added to the DOM, we'll scan for children that have a '-' in the name and therefore are custom elements, see if they're not yet defined, and load and define them if so. By using display: contents we can avoid having the impact layout.

lazy.js:

customElements.define('x-lazy', class extends HTMLElement {
    connectedCallback() {
        this.style.display = 'contents';
        this.#loadLazy();
    }

    #loadLazy() {
        const elements = 
            [...this.children].filter(_ => _.localName.includes('-'));
        const unregistered = 
            elements.filter(_ => !customElements.get(_.localName));
        unregistered.forEach(_ => this.#loadElement(_));
    }

    #loadElement(element) {
        // TODO: load the custom element
    }
});

To actually load the element, we'll have to first find the JS file to import, and then run its register function. By having the function that calls customElements.define as the default export by convention the problem is reduced to finding the path to the JS file. The following code uses a heuristic that assumes components are in a ./components/ subfolder of the current document and follow a consistent file naming scheme:

lazy.js (continued):

    #loadElement(element) {
        // strip leading x- off the name
        const cleanName = element.localName.replace(/^x-/, '').toLowerCase();
        // assume component is in its own folder
        const url = `./components/${cleanName}/${cleanName}.js`;
        // dynamically import, then register if not yet registered
        return import(new URL(url, document.location)).then(module => 
            !customElements.get(element.localName) && module && module.default());
    }

One could get a lot more creative however, and for example use an import map to map module names to files. This I leave as an exercise for the reader.

Suspense

While the lazy component is loading, we can't show it yet. This is true for custom elements just as much as for React. That means we need a wrapper component that will show a fallback UI as long as any components in its subtree are loading, the component. This starts out as a tale of two slots. When the suspense element is loading it shows the fallback, otherwise the content.

example.html:


    Loading...

suspense.js:

export class Suspense extends HTMLElement {
    #fallbackSlot;
    #contentSlot;

    set loading(isLoading) {
        if (!this.#fallbackSlot) return;
        this.#fallbackSlot.style.display = isLoading ? 'contents' : 'none';
        this.#contentSlot.style.display = !isLoading ? 'contents' : 'none';
    }

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

        this.#fallbackSlot = document.createElement('slot');
        this.#fallbackSlot.style.display = 'none';
        this.#fallbackSlot.name = 'fallback';
        this.#contentSlot = document.createElement('slot');
        this.shadowRoot.append(this.#fallbackSlot, this.#contentSlot);
    }

    connectedCallback() {
        this.style.display = 'contents';
    }
}
customElements.define('x-suspense', Suspense);

The trick now is, how to we get loading = true to happen? In Plain Vanilla's applications page I showed how a React context can be simulated using the element.closest() API. We can use the same mechanism to create a generic API that will let our suspense wait on a promise to complete.

suspense.js (continued):

    static waitFor(sender, ...promises) {
        const suspense = sender.closest('x-suspense');
        if (suspense) suspense.addPromises(...promises);
    }

    addPromises(...promises) {
        if (!promises.length) return;
        this.loading = true;
        // combine into previous promises if there are any
        const newPromise = this.#waitingForPromise = 
            Promise.allSettled([...promises, this.#waitingForPromise]);
        // wait for all promises to complete
        newPromise.then(_ => {
            // if no newer promises were added, we're done
            if (newPromise === this.#waitingForPromise) {
                this.loading = false;
            }
        });
    }

Suspense.waitFor will call the nearest ancestor to a given element, and give it a set of promises that it should wait on. This API can then be called from our component. Note that #loadElement returns a promise that completes when the custom element is loaded or fails to load.

lazy.js (continued):

    #loadLazy() {
        const elements = 
            [...this.children].filter(_ => _.localName.includes('-'));
        const unregistered = 
            elements.filter(_ => !customElements.get(_.localName));
        if (unregistered.length) {
            Suspense.waitFor(this, 
                ...unregistered.map(_ => this.#loadElement(_))
            );
        }
    }

The nice thing about the promise-based approach is that we can give it any promise, just like we would with React's suspense. For example, when loading data in a custom element that is in the suspense's subtree, we can call the exact same API:
Suspense.waitFor(this, fetch(url).then(...))

Error boundary

Up to this point, we've been assuming everything always works. This is ~~Sparta~~software, it will never "always work". What we need is a graceful way to intercept failed promises that are monitored by the suspense, and show an error message instead. That is the role that React's error boundary plays.

The approach is similar to suspense:

example.html:


    Something went wrong
    
        Loading...

And the code is also quite similar to suspense:

export class ErrorBoundary extends HTMLElement {

    static showError(sender, error) {
        if (!error) throw new Error('ErrorBoundary.showError: expected two arguments but got one');
        const boundary = sender.closest('x-error-boundary');
        if (boundary) {
            boundary.error = error;
        } else {
            console.error('unable to find x-error-boundary to show error');
            console.error(error);
        }
    }

    #error;
    #errorSlot;
    #contentSlot;

    get error() {
        return this.#error;
    }

    set error(error) {
        if (!this.#errorSlot) return;
        this.#error = error;
        this.#errorSlot.style.display = error ? 'contents' : 'none';
        this.#contentSlot.style.display = !error ? 'contents' : 'none';
        if (error) {
            this.#errorSlot.assignedElements().forEach(element => {
                if (Object.hasOwn(element, 'error')) {
                    element.error = error;
                } else {
                    element.setAttribute('error', error?.message || error);
                }
            });
            this.dispatchEvent(new CustomEvent('error', { detail: error }));
        }
    }

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

        this.#errorSlot = document.createElement('slot');
        this.#errorSlot.style.display = 'none';
        this.#errorSlot.name = 'error';
        // default error message
        this.#errorSlot.textContent = 'Something went wrong.';
        this.#contentSlot = document.createElement('slot');
        this.shadowRoot.append(this.#errorSlot, this.#contentSlot);
    }

    reset() {
        this.error = null;
    }

    connectedCallback() {
        this.style.display = 'contents';
    }
}
customElements.define('x-error-boundary', ErrorBoundary);

Similar to suspense, this has an API ErrorBoundary.showError() that can be called from anywhere inside the error boundary's subtree to show an error that occurs. The suspense component is then modified to call this API when it bumps into a rejected promise. To hide the error, the reset() method can be called on the error boundary element.

Finally, the error setter will set the error as a property or attribute on all children in the error slot, which enables customizing the error message's behavior based on the error object's properties by creating a custom component.

Conclusion

Finally, we can bring all of this together in a single example, that combines lazy, suspense, error boundary, a customized error message, and a lazy-loaded hello-world component.

example/index.js:

import { registerLazy } from './components/lazy.js';
import { registerSuspense } from './components/suspense.js';
import { registerErrorBoundary } from './components/error-boundary.js';
import { registerErrorMessage } from './components/error-message.js';

customElements.define('x-demo', class extends HTMLElement {

    constructor() {
        super();
        registerLazy();
        registerSuspense();
        registerErrorBoundary();
        registerErrorMessage();
    }

    connectedCallback() {
        this.innerHTML = `
            Lazy loading demo
            
            
            
                Click to load..
            
        `;
        const resetBtn = this.querySelector('button#error-reset')
        resetBtn.onclick = () => {
            this.querySelector('x-error-boundary').reset();
            resetBtn.setAttribute('disabled', true);
        };
        const loadBtn = this.querySelector('button#lazy-load');
        loadBtn.onclick = () => {
            this.querySelector('div#lazy-load-div').innerHTML = `
                
                    
                    
                        Loading...
                        
                    
                
            `
            this.querySelector('x-error-boundary').addEventListener('error', _ => {
                resetBtn.removeAttribute('disabled');
            });
            loadBtn.setAttribute('disabled', true);
        };
    }

});

complete example

For the complete example's code, as well as the lazy, suspense and error-boundary components, check out the sweet-suspense repo on Github.

How fast are web components?

2024-09-06T12:00:00.000Z

It is often said that web components are slow. This was also my experience when I first tried building web components a few years ago. At the time I was using the Stencil framework, because I didn't feel confident that they could be built well without a framework. Performance when putting hundreds of them on a page was so bad that I ended up going back to React.

But as I've gotten deeper into vanilla web development I started to realize that maybe I was just using it wrong. Perhaps web components can be fast, if built in a light-weight way. This article is an attempt to settle the question "How fast are web components?".

The lay of the land

What kinds of questions did I want answered?

How many web components can you render on the page in a millisecond?
Does the technique used to built the web component matter, which technique is fastest?
How do web component frameworks compare? I used Lit as the framework of choice as it is well-respected.
How does React compare?
What happens when you combine React with web components?

To figure out the answer I made a benchmark as a vanilla web page (of course), that renders thousands of very simple components containing only . and measured the elapsed time. This benchmark was then run on multiple devices and multiple browsers to figure out performance characteristics. The ultimate goal of this test is to figure out the absolute best performance that can be extracted from the most minimal web component.

To get a performance range I used two devices for testing:

A Macbook Air M1 running MacOS, to stand in as the "fast" device, comparable to a new high end iPhone.
An Asus Chi T300 Core M from 2015 running Linux Mint Cinnamon, to stand in as the "slow" device, comparable to an older low end Android.

Between these devices is a 7x CPU performance gap.

The test

The test is simple: render thousands of components using a specific technique, call requestAnimationFrame() repeatedly until they actually render, then measure elapsed time. This produces a components per millisecond number.

The techniques being compared:

innerHTML: each web component renders its content by assigning to this.innerHTML
append: each web component creates the span using document.createElement and then appends it to itself
append (buffered): same as the append method, except all web components are first buffered to a document fragment which is then appended to the DOM
shadow + innerHTML: the same as innerHTML, except each component has a shadow DOM
shadow + append: the same as append, except each component has a shadow DOM
template + append: each web component renders its content by cloning a template and appending it
textcontent: each web component directly sets its textContent property, instead of adding a span (making the component itself be the span)
direct: appends spans instead of custom elements, to be able to measure custom element overhead
lit: each web component is rendered using the lit framework, in the way that its documentation recommends
react pure: rendering in React as a standard React component, to have a baseline for comparison to mainstream web development
react + wc: each React component wraps the append-style web component
(norender): same as other strategies, except the component is only created but not added to the DOM, to separate out component construction cost

This test was run on M1 in Brave, Chrome, Edge, Firefox and Safari. And on Chi in Chrome and Firefox. It was run for 10 iterations and a geometric mean was taken of the results.

The results

First, let's compare techniques. The number here is components per millisecond, so higher is better.

Author's note: the numbers from the previous version of this article are ~~crossed out~~.

Chrome on M1
technique	components/ms
innerHTML	~~143~~ 135
append	~~233~~ 239
append (buffered)	~~228~~ 239
shadow + innerHTML	~~132~~ 127
shadow + append	~~183~~ 203
template + append	~~181~~ 198
textcontent	345
direct	461
lit	~~133~~ 137
react pure	~~275~~ 338
react + wc	~~172~~ 212
append (norender)	1393
shadow (norender)	814
direct (norender)	4277
lit (norender)	880

Chrome on Chi, best of three
technique	components/ms
innerHTML	25 29
append	55 55
append (buffered)	56 59
shadow + innerHTML	24 26
shadow + append	36 47
template + append	45 46
textcontent	81
direct	116
lit	30 33
react pure	77 87
react + wc	45 52
append (norender)	434
shadow (norender)	231
direct (norender)	1290
lit (norender)	239

One relief right off the bat is that even the slowest implementation on the slow device renders 100.000 components in 4 seconds. React is roughly in the same performance class as well-written web components. That means for a typical web app performance is not a reason to avoid web components.

As far as web component technique goes, the performance delta between the fastest and the slowest technique is around 2x, so again for a typical web app that difference will not matter. Things that slow down web components are shadow DOM and innerHTML. Appending directly created elements or cloned templates and avoiding shadow DOM is the right strategy for a well-performing web component that needs to end up on the page thousands of times.

On the slow device the Lit framework is a weak performer, probably due to its use of shadow DOM and JS-heavy approaches. Meanwhile, pure React is the best performer, because while it does more work in creating the virtual DOM and diffing it to the real DOM, it benefits from not having to initialize the web component class instances. Consequently, when wrapping web components inside React components we see React's performance advantage disappear, and that it adds a performance tax. In the grand scheme of things however, the differences between React and optimized web components remains small.

The fast device is up to 5x faster than the slow device in Chrome, depending on the technique used, so it is really worth testing applications on slow devices to get an idea of the range of performance.

Next, let's compare browsers:

M1, append, best of three
browser	components/ms
Brave	~~146~~ 145
Chrome	~~233~~ 239
Edge	~~224~~ 237
Firefox	~~232~~ 299
Safari	~~260~~ 239

Chi, append, best of three
browser	components/ms
Chrome	55 55
Firefox	~~180~~ 77

Brave is really slow, probably because of its built-in ad blocking. Ad blocking extensions also slow down the other browsers by a lot. Safari, Chrome and Edge end up in roughly the same performance bucket. Firefox is the best performer overall. Using the "wrong" browser can halve the performance of a machine.

Author's note: due to a measurement error in measuring elapsed time, the previous version of this article had Safari as fastest and Firefox as middle of the pack.

There is a large performance gap when you compare the slowest technique on the slowest browser on the slowest device, with its fastest opposite combo. Specifically, there is a 16x performance gap:

textContent, Firefox on M1: 430 components/ms
Shadow DOM + innerHTML, Chrome on Chi: 26 components/ms

That means it becomes worthwhile to carefully consider technique when having to support a wide range of browsers and devices, because a bad combination may lead to a meaningfully degraded user experience. And of course, you should always test your web app on a slow device to make sure it still works ok.

Bottom line

I feel confident now that web components can be fast enough for almost all use cases where someone might consider React instead.

However, it does matter how they are built. Shadow DOM should not be used for smaller often used web components, and the contents of those smaller components should be built using append operations instead of innerHTML. The use of web component frameworks might impact their performance significantly, and given how easy it is to write vanilla web components I personally don't see the point behind Lit or Stencil. YMMV.

The full benchmark code and results can be found on Github.

A unix philosophy for web development

2024-09-03T12:00:00.000Z

Web components have their malcontents. While frameworks have done their best to provide a place for web components to fit into their architecture, the suit never fits quite right, and framework authors have not been shy about expressing their disappointment. Here's Ryan Carniato of SolidJS explaining what's wrong with web components:

The collection of standards (Custom Elements, HTML Templates, Shadow DOM, and formerly HTML Imports) put together to form Web Components on the surface seem like they could be used to replace your favourite library or framework. But they are not an advanced templating solution. They don't improve your ability to render or update the DOM. They don't manage higher-level concerns for you like state management.

Ryan Carniato

While this criticism is true, perhaps it's besides the point. Maybe web components were never meant to solve those problems anyway. Maybe there are ways to solve those problems in a way that dovetails with web components as they exist. In the main components tutorial I've already explained what they can do, now let's see what can be done about the things that they can't do.

The Unix Philosophy

The Unix operating system carries with it a culture and philosophy of system design, which carries over to the command lines of today's Unix-like systems like Linux and MacOS. This philosophy can be summarized as follows:

Write programs that do one thing and do it well.
Write programs to work together.
Write programs to handle text streams, because that is a universal interface.

What if we look at the various technologies that comprise web components as just programs, part of a Unix-like system of web development that we collectively call the browser platform? In that system we can do better than text and use the DOM as the universal interface between programs, and we can extend the system with a set of single purpose independent "programs" (functions) that fully embrace the DOM by augmenting it instead of replacing it.

In a sense this is the most old-school way of building web projects, the one people who "don't know any better" automatically gravitate to. What us old-school web developers did before Vue and Solid and Svelte, before Angular and React, before Knockout and Ember and Backbone, before even jQuery, was have a bunch of functions in utilities.js that we copied along from project to project. But, you know, sometimes old things can become new again.

In previous posts I've already covered a html() function for vanilla entity encoding, and a signal() function that provides a tiny signals implementation that can serve as a lightweight system for state management. That still leaves a missing link between the state managed by the signals and the DOM that is rendered from safely entity-encoded HTML. What we need is a bind() function that can bind data to DOM elements and bind DOM events back to data.

Finding inspiration

In order to bind a template to data, we need a way of describing that behavior in the HTML markup. Well-trodden paths are often the best starting place to look for inspiration. I like Vue's template syntax, because it is valid HTML but just augmented, and because it is proven. Vue's templates only pretend to be HTML because they're actually compiled to JavaScript behind the scenes, but let's start there as an API. This is what it looks like:

: Bind src to track the value of the imageSrc property of the current component. Vue is smart enough to set a property if one exists, and falls back to setting an attribute otherwise. (If that confuses you, read about attributes and properties first.)
: Bind the click event to the doThis method of the current component.

By chance I came across this article about making a web component base class. In the section Declarative interactivity the author shows a way to do the Vue-like event binding syntax on a vanilla web component. This is what inspired me to develop the concept into a generic binding function and write this article.

Just an iterator

The heart of the binding function is an HTML fragment iterator. After all, before we can bind attributes we need to first find the ones that have binding directives.

export const bind = (template) => {
    const fragment = template.content.cloneNode(true);
    // iterate over all nodes in the fragment
    const iterator = document.createNodeIterator(
        fragment,
        NodeFilter.SHOW_ELEMENT,
        {
            // reject any node that is not an HTML element
            acceptNode: (node) => {
                if (!(node instanceof HTMLElement))
                    return NodeFilter.FILTER_REJECT;
                return NodeFilter.FILTER_ACCEPT;
            },
        }
    );
    let node;
    while (node = iterator.nextNode()) {
        if (!node) return;
        const elem = node;
        for (const attr of Array(...node.attributes)) {
            // check for event binding directive
            if (attr.name.startsWith('@')) {

                // TODO: bind event ...
                
                elem.removeAttributeNode(attr);
            // check for property/attribute binding directive
            } else if (attr.name.startsWith(':')) {
                
                // TODO: bind data ...
                
                elem.removeAttributeNode(attr);
            }
        }
    }
    return fragment;
}

This code will take an HTML template element, clone it to a document fragment, and then iterate over all the nodes in the fragment, discovering their attributes. Then for each attribute a check is made to see if it's a binding directive (@ or :). The node is then bound to data according to the directive attribute (shown here as TODO's), and the attribute is removed from the node. At the end the bound fragment is returned for inserting into the DOM.

The benefit of using a fragment is that it is disconnected from the main DOM, while still offering all of the DOM API's. That means we can easily create a node iterator to walk over it and discover all the attributes with binding directives, modify those nodes and attributes in-place, and still be sure we're not causing DOM updates in the main page until the fragment is inserted there. This makes the bind function very fast.

If you're thinking "woah dude, that's a lot of code and a lot of technobabble, I ain't reading all that," then please, I implore you to read through the code line by line, and you'll see it will all make sense.

Of course, we also need to have something to bind to, so we need to add a second parameter. At the same time, it would be nice to just be able to pass in a string and have it auto-converted into a template. The beginning of our bind function then ends up looking like this:

export const bind = (template, target) => {
    if (!template.content) {
        const text = template;
        template = document.createElement('template');
        template.innerHTML = text;
    }
    const fragment = template.content.cloneNode(true);
// ...
}

That just leaves us the TODO's. We can make those as simple or complicated as we want. I'll pick a middle ground.

Binding to events

This 20 line handler binds events to methods, signals or properties:

// check for custom event listener attributes
if (attr.name.startsWith('@')) {
    const event = attr.name.slice(1);
    const property = attr.value;
    let listener;
    // if we're binding the event to a function, call it directly
    if (typeof target[property] === 'function') {
        listener = target[property].bind(target);
    // if we're binding to a signal, set the signal's value
    } else if (typeof target[property] === 'object' && 
                typeof target[property].value !== 'undefined') {
        listener = e => target[property].value = e.target.value;
    // fallback: assume we're binding to a property, set the property's value
    } else {
        listener = e => target[property] = e.target.value;
    }
    elem.addEventListener(event, listener);
    // remove (non-standard) attribute from element
    elem.removeAttributeNode(attr);
}

That probably doesn't explain much, so let me give an example of what this enables:

Binding to events example

import { bind } from './bind.js';
import { signal } from './signals.js';

customElements.define('x-example', class Example extends HTMLElement {

    set a(value) { 
        this.setAttribute('a', value);
        this.querySelector('label[for=a] span').textContent = value;
    }
    set b(value) {
        this.setAttribute('b', value);
        this.querySelector('label[for=b] span').textContent = value;
    }
    c = signal('');

    connectedCallback() {
        this.append(bind(`
            
                
                A = 
            
            
                
                B = 
            
            
                
                C = 
            
            
            Result: 
        `, this));
        this.c.effect(() => 
            this.querySelector('label[for=c] span').textContent = this.c);
    }

    onInputA (e) {
        this.a = e.target.value;
    }

    onClick() {
        this.querySelector('#result').textContent =
            +this.getAttribute('a') + +this.getAttribute('b') + +this.c;
    }
});

input#a's input event is handled by calling the onClickA() method.
input#b's input event is handled by assigning e.target.value to the b property.
input#c's input event is handled by setting the value of the c signal.

If you're not familiar with the signal() function, check out the tiny signals implementation in the previous post. For now you can also just roll with it.

Not a bad result for 20 lines of code.

Binding to data

Having established the pattern for events that automatically update properties, we now reverse the polarity to make data values automatically set element properties or attributes.

// ...
    if (attr.name.startsWith(':')) {
        // extract the name and value of the attribute/property
        let name = attr.name.slice(1);
        const property = getPropertyForAttribute(name, target);
        const setter = property ?
            () => elem[property] = target[attr.value] :
            () => elem.setAttribute(name, target[attr.value]);
        setter();
        // if we're binding to a signal, listen to updates
        if (target[attr.value]?.effect) {
            target[attr.value].effect(setter);
        // if we're binding to a property, listen to the target's updates
        } else if (target.addEventListener) {
            target.addEventListener('change', setter);
        }
        // remove (non-standard) attribute from element
        elem.removeAttributeNode(attr);
    }
// ...

function getPropertyForAttribute(name, obj) {
    switch (name.toLowerCase()) {
        case 'text': case 'textcontent':
            return 'textContent';
        case 'html': case 'innerhtml':
            return 'innerHTML';
        default:
            for (let prop of Object.getOwnPropertyNames(obj)) {
                if (prop.toLowerCase() === name.toLowerCase()) {
                    return prop;
                }
            }   
    }
}

The getPropertyForAttribute function is necessary because the attributes that contain the directives will have names that are case-insensitive, and these must be mapped to property names that are case-sensitive. Also, the :text and :html shorthand notations replace the role of v-text and v-html in Vue's template syntax.

When the value of the target's observed property changes, we need to update the bound element's property or attribute. This means a triggering 'change' event is needed that is then subscribed to. A framework's templating system will compare state across time, and detect the changed values automatically. Lacking such a system we need a light-weight alternative.

When the property being bound to is a signal, this code registers an effect on the signal. When the property is just a value, it registers an event listener on the target object, making it the responsibility of that target object to dispatch the 'change' event when values change. This approach isn't going to get many points for style, but it does work.

Check out the completed bind.js code.

Bringing the band together

In the article Why I don't use web components Svelte's Rich Harris lays out the case against web components. He demonstrates how this simple 9 line Svelte component becomes an incredible verbose 59 line monstrosity when ported to a vanilla web component.






{a} + {b} = {a + b}

Now that we have assembled our three helper functions html(), signal() and bind() on top of the web components baseline, at a total budget of around 150 lines of code, how close can we get for a web component ?

import { bind } from './bind.js';
import { signal, computed } from './signals.js';
import { html } from './html.js';

customElements.define('x-adder', class Adder extends HTMLElement {
    a = signal();
    b = signal();
    result = computed(() => 
        html`${+this.a} + ${+this.b} = ${+this.a + +this.b}`, [this.a, this.b]);

    connectedCallback() {
        this.a.value ??= this.getAttribute('a') || 0;
        this.b.value ??= this.getAttribute('b') || 0;
        this.append(bind(html`
            
            
            
        `, this));
    }
});

combined example

To be fair, that's still twice the lines of code, but it describes clearly what it does, and really that is all you need. And I'm just shooting in the wind here, trying stuff out. Somewhere out there could be a minimal set of functions that transforms web components into something resembling a framework, and the idea excites me! Who knows, maybe in a few years the web community will return to writing projects in vanilla web code, dragging along the modern equivalent of utilities.js from project to project...

What do you think?

Poor man's signals

2024-08-30T12:00:00.000Z

Signals are all the rage right now. Everyone's doing them. Angular, and Solid, and Preact, and there are third party packages for just about every framework that doesn't already have them. There's even a proposal to add them to the language, and if that passes it's just a matter of time before all frameworks have them built in.

Living under a rock

In case you've been living under a rock, here's the example from Preact's documentation that neatly summarizes what signals do:

import { signal, computed, effect } from "@preact/signals";

const name = signal("Jane");
const surname = signal("Doe");
const fullName = computed(() => `${name.value} ${surname.value}`);

// Logs name every time it changes:
effect(() => console.log(fullName.value));
// Logs: "Jane Doe"

// Updating `name` updates `fullName`, which triggers the effect again:
name.value = "John";
// Logs: "John Doe"

Simply put, signals wrap values and computations in a way that allows us to easily respond to every change to those values and results in a targeted way, without having to rerender the entire application in the way that we would do in React. In short, signals are an efficient and targeted way to respond to changes without having to do state comparison and DOM-diffing.

OK, so, if signals are so great, why am I trying to sell you on them on a vanilla web development blog? Don't worry! Vanilla web developers can have signals too.

Just a wrapper

Signals are at heart nothing more than a wrapper for a value that sends events when the value changes. That's nothing that a little trickery with the not well known but very handy EventTarget base class can't fix for us.

class Signal extends EventTarget {
    #value;
    get value () { return this.#value; }
    set value (value) {
        if (this.#value === value) return;
        this.#value = value;
        this.dispatchEvent(new CustomEvent('change')); 
    }

    constructor (value) {
        super();
        this.#value = value;
    }
}

This gets us a very barebones signals experience:

const name = new Signal('Jane');
name.addEventListener('change', () => console.log(name.value));
name.value = 'John';
// Logs: John

But that's kind of ugly. The new keyword went out of fashion a decade ago, and that addEventListener sure is unwieldy. So let's add a little syntactic sugar.

class Signal extends EventTarget {
    #value;
    get value () { return this.#value; }
    set value (value) {
        if (this.#value === value) return;
        this.#value = value;
        this.dispatchEvent(new CustomEvent('change')); 
    }

    constructor (value) {
        super();
        this.#value = value;
    }

    effect(fn) {
        fn();
        this.addEventListener('change', fn);
        return () => this.removeEventListener('change', fn);
    }

    valueOf () { return this.#value; }
    toString () { return String(this.#value); }
}

const signal = _ => new Signal(_);

Now our barebones example is a lot nicer to use:

const name = signal('Jane');
name.effect(() => console.log(name.value));
// Logs: Jane
name.value = 'John';
// Logs: John

The effect(fn) method will call the specified function, and also subscribe it to changes in the signal's value.

It also returns a dispose function that can be used to unregister the effect. However, a nice side effect of using EventTarget and browser built-in events as the reactivity primitive is that it makes the browser smart enough to garbage collect the signal and its effect when the signal goes out of scope. This means less chance for memory leaks even if we never call the dispose function.

Finally, the toString and valueOf magic methods allow for dropping .value in most places that the signal's value gets used. (But not in this example, because the console is far too clever for that.)

Does not compute

This signals implementation is already capable, but at some point it might be handy to have an effect based on more than one signal. That means supporting computed values. Where the base signals are a wrapper around a value, computed signals are a wrapper around a function.

class Computed extends Signal {
    constructor (fn, deps) {
        super(fn(...deps));
        for (const dep of deps) {
            if (dep instanceof Signal) 
                dep.addEventListener('change', () => this.value = fn(...deps));
        }
    }
}

const computed = (fn, deps) => new Computed(fn, deps);

The computed signal calculates its value from a function. It also depends on other signals, and when they change it will recompute its value. It's a bit obnoxious to have to pass the signals that it depends on as an additional parameter, but hey, I didn't title this article Rich man's signals.

This enables porting Preact's signals example to vanilla JS.

const name = signal('Jane');
const surname = signal('Doe');
const fullName = computed(() => `${name} ${surname}`, [name, surname]);
// Logs name every time it changes:
fullName.effect(() => console.log(fullName.value));
// -> Jane Doe

// Updating `name` updates `fullName`, which triggers the effect again:
name.value = 'John';
// -> John Doe

Can you use it in a sentence?

You may be thinking, all these console.log examples are fine and dandy, but how do you use this stuff in actual web development? This simple adder demonstrates how signals can be combined with web components:

import { signal, computed } from './signals.js';

customElements.define('x-adder', class extends HTMLElement {
    a = signal(1);
    b = signal(2);
    result = computed((a, b) => `${a} + ${b} = ${+a + +b}`, [this.a, this.b]);

    connectedCallback() {
        if (this.querySelector('input')) return;

        this.innerHTML = `
            
            
            
        `;
        this.result.effect(
            () => this.querySelector('p').textContent = this.result);
        this.addEventListener('input', 
            e => this[e.target.name].value = e.target.value);
    }
});

And here's a live demo:

adder.html

In case you were wondering, the if is there to prevent adding the effect twice if connectedCallback is called when the component is already rendered.

The full poor man's signals code in all its 36 line glory can be found in the tiny-signals repo on Github.

Vanilla entity encoding

2024-08-25T12:00:00.000Z

Good enough

When I made the first version of the Plain Vanilla website, there were things that I would have liked to spend more time on, but that I felt didn't belong in a Good Enough™ version of the site. One of those things was defending against Cross-Site Scripting (XSS).

XSS is still in the OWASP Top Ten of security issues, but it's no longer as prevalent as it used to be. Frameworks have built in a lot of defenses, and when using their templating systems you have to go out of your way to inject code into the generated HTML. When eschewing frameworks we're reduced to standard templating in our web components, and those offer no defense against XSS.

Because of this, in the original site the Passing Data example on the Components page had an undocumented XSS bug. The name field could have scripts injected into it. I felt ambivalent about leaving that bug in. On the one hand, the code was very compact and neat by leaving it in. On the other hand it made that code a bad example that shouldn't be copied. I ended up choosing to leave it as-is because an example doesn't have to be production-grade and generating properly encoded HTML was not the point of that specific example. It's time however to circle back to that XSS bug and figure out how it would have been solved in a clean and readable way, if Santa really did want to bring his List application to production-level quality.

The problem

The basic problem we need to solve is that vanilla web components end up having a lot of code that looks like this:

class MyComponent extends HTMLElement {
    connectedCallback() {
        const btn = ``;
        this.innerHTML = `
            ${this.getAttribute('bar')}
            
                ${this.getAttribute('xyzzy')}
                ${btn}
            
        `;
    }
}
customElements.define('my-component', MyComponent);

If any of foo, bar, baz or xyzzy contain one of the dangerous HTML entities, we risk seeing our component break, and worst-case risk seeing an attacker inject a malicious payload into the page. Just as a reminder, those dangerous HTML entities are <, >, &, ' and ".

The fix, take one

A naive fix is creating a html-encoding function and using it consistently:

function htmlEncode(s) {
    return s.replace(/[&<>'"]/g,
        tag => ({
            '&': '&',
            '<': '<',
            '>': '>',
            "'": ''',
            '"': '"'
        }[tag]))
}

class MyComponent extends HTMLElement {
    connectedCallback() {
        const btn = ``;
        this.innerHTML = `
            ${htmlEncode(this.getAttribute('bar'))}
            
                ${htmlEncode(this.getAttribute('xyzzy'))}
                ${btn}
            
        `;
    }
}
customElements.define('my-component', MyComponent);

While this does work to defend against XSS, it is verbose and ugly, not pleasant to type and not pleasant to read. What really kills it though, is that it assumes attention to detail from us messy humans. We can never forget, never ever, to put a htmlEncode() around each and every variable. In the real world, that is somewhat unlikely.

What is needed is a solution that allows us to forget about entity encoding, by doing it automatically when we're templating. I drew inspiration from templating libraries that work in-browser and are based on tagged templates, like lit-html and htm. The quest was on to build the most minimalistic html templating function that encoded entities automatically.

The fix, take two

Ideally, the fixed example should look more like this:

import { html } from './html.js';

class MyComponent extends HTMLElement {
    connectedCallback() {
        const btn = html``;
        this.innerHTML = html`
            ${this.getAttribute('bar')}
            
                ${this.getAttribute('xyzzy')}
                ${btn}
            
        `;
    }
}
customElements.define('my-component', MyComponent);

The html`` tagged template function would automatically encode entities, in a way that we don't even have to think about it. Even when we nest generated HTML inside of another template, like with ${btn}, it should just magically work. It would be so minimal as to disappear in the background, barely impacting readability, maybe even improving it. You may be thinking that doing that correctly would involve an impressive amount of code. I must disappoint.

class Html extends String { }

/** 
 * tag a string as html not to be encoded
 * @param {string} str
 * @returns {string}
 */
export const htmlRaw = str => new Html(str);

/** 
 * entity encode a string as html
 * @param {*} value The value to encode
 * @returns {string}
 */
export const htmlEncode = (value) => {
    // avoid double-encoding the same string
    if (value instanceof Html) {
        return value;
    } else {
        // https://stackoverflow.com/a/57448862/20980
        return htmlRaw(
            String(value).replace(/[&<>'"]/g, 
                tag => ({
                    '&': '&',
                    '<': '<',
                    '>': '>',
                    "'": ''',
                    '"': '"'
                }[tag]))
        );
    }
}

/** 
 * html tagged template literal, auto-encodes entities
 */
export const html = (strings, ...values) => 
    htmlRaw(String.raw({ raw: strings }, ...values.map(htmlEncode)));

Those couple dozen lines of code are all that is needed. Let's go through it from top to bottom.

class Html extends String { }: The Html class is used to mark strings as encoded, so that they won't be encoded again.
export const htmlRaw = str => new Html(str);: Case in point, the htmlRaw function does the marking.
export const htmlEncode = ...: The earlier htmlEncode function is still doing useful work, only this time it will mark the resulting string as HTML, and it won't double-encode.
export const html = ...: The tagged template function that binds it together.

A nice upside of the html template function is that the html-in-template-string Visual Studio Code extension can detect it automatically and will syntax highlight the templated HTML. This is what example 3 looked like after I made it:

Granted, there's still a bunch of boilerplate here, and that getAttribute gets unwieldy. But with this syntax highlighting enabled sometimes when I'm working on vanilla web components I forget it's not React and JSX, but just HTML and JS. It's surprising how nice of a development experience web standards can be if you embrace them.

I decided to leave the XSS bug in the Passing Data example, but now the Applications page has an explanation about entity encoding documenting this html template function. I can only hope people that work their way through the tutorial make it that far. For your convenience I also put the HTML templating function in its own separate html-literal repo on Github.

Plain Vanilla Blog

matters

Redesigning Plain Vanilla

Local-first web application architecture

Tail latency matters

Solutions

Local-first

Here comes trouble

Loco-first

The history of web application architecture

Before time began

Traditional server-side rendering

Modern server-side rendering

Client-side rendering

Client-side rendering with server offload

Where does that leave us?

Clean client-side routing

Intercepting anchor clicks

There and back again

Can you use it in a sentence?

404 not found

Bringing React's to vanilla JS

View Transitions 101

Here comes trouble

What React did

A fresh start

Taking a queue

Back to the top

One more thing

Making a new form control

A simple element

Form-associated elements

Looking for input

Read the instructions

With some style

Validation

In conclusion

The attribute/property duality

Going native

Into the weeds

In conclusion

New year's resolve

Combining JS and CSS files

Resolving paths

Optimizing bundled code

Happy new year!

Caching vanilla sites

How caching works

Keeping it simple: GitHub Pages

Extending cache durations

Complete control with service workers

Wrapping up

Editing Plain Vanilla

Setting up a profile

Linting

html-in-template-string

Live Preview

Bonus: working offline

Needs more context

Lived experience

A galaxy far, far away

The cost of change

The rising tide

Holding my breath

The road ahead

The unreasonable effectiveness of vanilla JS

Project setup

Get to the code

Day off in Kyoto

Day off in Kyoto

Adding context

Adding tasks

Hard mode

Some thoughts

The life and times of a web component

Just the DOM please

A question of definition

Making connections

Flip the script

In the shadows