[
{
"path": ".github/workflows/static.yml",
"content": "# Simple workflow for deploying static content to GitHub Pages\nname: Deploy static content to Pages\n\non:\n # Runs on pushes targeting the default branch\n push:\n branches: [\"main\"]\n\n # Allows you to run this workflow manually from the Actions tab\n workflow_dispatch:\n\n# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages\npermissions:\n contents: read\n pages: write\n id-token: write\n\n# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.\n# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.\nconcurrency:\n group: \"pages\"\n cancel-in-progress: false\n\njobs:\n # Single deploy job since we're just deploying\n deploy:\n environment:\n name: github-pages\n url: ${{ steps.deployment.outputs.page_url }}\n runs-on: ubuntu-latest\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n - name: Setup Pages\n uses: actions/configure-pages@v5\n - name: Create analytics file\n run: echo \"${{ vars.CLOUDFLARE_ANALYTICS }}\" > public/analytics.template\n - name: Upload artifact\n uses: actions/upload-pages-artifact@v3\n with:\n # Deploy public folder only\n path: './public'\n - name: Deploy to GitHub Pages\n id: deployment\n uses: actions/deploy-pages@v4\n"
},
{
"path": ".gitignore",
"content": ".DS_Store\n*.pem\npublic/analytics.template\n"
},
{
"path": ".hintrc",
"content": "{\n \"extends\": [\n \"development\"\n ],\n \"hints\": {\n \"compat-api/html\": [\n \"default\",\n {\n \"ignore\": [\n \"iframe[loading]\",\n \"nav[popover]\",\n \"button[popovertarget]\",\n \"button[popovertargetaction]\"\n ]\n }\n ],\n \"no-inline-styles\": \"off\",\n \"compat-api/css\": [\n \"default\",\n {\n \"ignore\": [\n \"view-transition-name\",\n \"text-size-adjust\",\n \"text-size-adjust: none\",\n \"overscroll-behavior\",\n \"overscroll-behavior: none\"\n ]\n }\n ]\n }\n}"
},
{
"path": "LICENSE.md",
"content": "MIT License\n\nCopyright (c) 2024 Joeri Sebrechts\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n"
},
{
"path": "README.md",
"content": "# Plain Vanilla\n\nA website demonstrating how to do web development using only vanilla techniques: no tools, no frameworks, just the browser and vanilla web code. The site itself is also built in this way.\n\n## Running\n\nRun the `public/` folder as a static website:\n\n- node: `npx http-server public -c-1`\n- php: `php -S localhost:8000 -t public`\n- python: `python3 -m http.server 8000 --directory public`\n\nOr use the VS Code Live Preview extension to show `public/index.html`.\n\n## Contributing\n\nIssues or PR's welcome!\n\n## Other resources\n\nThese are some other resources demonstrating #notools web development techniques.\n\n- [MDN Learn Web Development](https://developer.mozilla.org/en-US/docs/Learn): a vanilla web development learning path\n- [Odin Project Foundations](https://www.theodinproject.com/paths/foundations/courses/foundations): a vanilla web development course\n- [create-react-app-zero](https://github.com/jsebrech/create-react-app-zero): another project of mine, a no-tools version of create-react-app, to be able to use React without frills\n- [HEX: a No Framework Approach to Building Modern Web Apps](https://medium.com/@metapgmr/hex-a-no-framework-approach-to-building-modern-web-apps-e43f74190b9c): a React-like approach based on vanilla web development techniques\n- [plainJS](https://plainjs.com/): a collection of vanilla javascript functions and plugins to replace the use of jQuery\n- [Web Dev Toolkit](https://gomakethings.com/toolkit/): a collection of vanilla helper functions, boilerplates and libraries\n- [The Modern JavaScipt Tutorial](https://javascript.info/): a step-by-step tutorial to learn vanilla JavaScript\n\n## Attribution\n\nSoft ice icon by [Twemoji](https://github.com/jdecked/twemoji) is licensed under [CC BY 4.0](http://creativecommons.org/licenses/by/4.0/).\n"
},
{
"path": "eslint.config.cjs",
"content": "/* eslint-disable no-undef */\nconst globals = require(\"globals\");\nconst js = require(\"@eslint/js\");\n\nmodule.exports = [\n js.configs.recommended, \n {\n languageOptions: {\n globals: {\n ...globals.browser,\n ...globals.mocha\n },\n ecmaVersion: 2022,\n sourceType: \"module\",\n }\n },\n {\n ignores: [\n \"public/blog/articles/\",\n \"**/lib/\",\n \"**/react/\",\n ]\n }\n];"
},
{
"path": "public/blog/archive.html",
"content": "\n\n\n Plain Vanilla Blog\n \n \n \n \n \n \n\n\n \n \n
\n As I write this paragraph it is my birthday, and it seemed like as good an opportunity as any to start a blog about vanilla web development.\n This blog post will be a bit unusual, as I will be writing it while I'm making the blog's inner workings.\n But before I get around to figuring out and then explaining how it was made, let me start with why.\n
\n\n \n
Origin story
\n
\n I have been building web sites since the late 90's, and over the years there were always two constants:\n (1) browsers were terrible developer platforms, (2) new tools and frameworks built ever taller on top of them.\n The tools were necessary, but their growing complexity frustrated me, and in that frustration lies the origin of this blog.\n
\n
\n A few years ago something unexpected happened: Microsoft moved away from their (underfeatured) Trident browser engine.\n Suddenly there was a new baseline of browsers, a capable baseline. Browsers got good!\n I explored what modern browsers could do as a developer platform, and grew excited with the possibilities\n to treat the browser itself as the framework, without a middleman. \n That eventually led into making the Plain Vanilla website, a framework tutorial for the web standards platform.\n
\n
\n In building this website editorial choices had to be made.\n Trying to explain too much would only confuse people, so the tutorial was trimmed of its fat.\n There is however so much more to explore, and that is where this blog enters the picture.\n Here I will talk about some of the things that didn't find a home in the Plain Vanilla tutorial,\n and document the new things that do.\n
\n \n\n \n
What is a blog anyway?
\n\n
\n Of course, a blog about vanilla web development has to be built vanilla-style.\n That means no build steps, no server-side logic, no frameworks or libraries.\n Bottom line that means throwing up a bunch of HTML pages with an index page linking them together,\n but that by itself isn't enough. The idea is to make a full-fat modern feeling blog,\n something that has what people expect a blog to have. So off I went to look at popular blogs and build a list of features.\n
\n
A modern blog will have ...
\n
\n
One page per article, easy for sharing as a link and discovery by Google.
\n
A welcome page, with one or more hero cards leading to articles and a list of cards for recent articles.
\n
An archive page, with the full history of articles linking to the article pages.
\n
An RSS feed, for the 20 most recent articles, containing the full text.
\n
Comments on every article. This is a big one.
\n
Some colors and imagery, to spruce things up and please the readers.
\n
Easy to author articles. This is also a big one.
\n
\n
The challenge was: how to do all of that within the vanilla constraints that I set myself?
\n \n\n \n
Article-first design
\n\n
\n The core of the blog experience is the article, so getting that right is key and that makes it the best place to start.\n Lacking any kind of generator or server-side routing, each article has to be written as a discrete html page\n in order to be discoverable by Google. Authoring those html pages should be straightforward,\n with minimal boilerplate.\n
\n\n
After careful consideration we present to you, an article page blueprint...
\n \n\n
\n This does several things for me. It keeps the <head> section as minimal as possible.\n It also moves the navigation at the top and bottom into dedicated web components.\n The header component accepts the article's image and title as child elements,\n neatly leaving the main element containing just the article's content and nothing else,\n making it easy to extract (but more on that later).\n
\n
\n When users have scripting disabled they won't get the header navigation, \n but thanks to this CSS they do get a warning: \n @media (scripting: none) { blog-header::before { content: ' ... ' } } \n This approach frees me from thinking about noscript warnings while writing an article.\n
\n
\n Finally, for comments I considered Disqus, but didn't want to include their embed.\n So instead the footer accepts the URL to a mastodon toot about the article,\n and will automatically generate a link that goes there. Given that the blog has a technical audience\n I'm pretty sure they can figure out how to reply over there. This approach can be extended\n to show replies inline on the page\n by calling the Mastodon API, but I didn't tackle that yet. It's somewhat cumbersome to first post an article, \n then toot about it, and then update the article with the toot's URL, but I'll survive.\n Incidentally, I still giggle like a schoolgirl inside my head every time I type the word toot.\n
\n \n\n \n
Organizing files
\n\n
\n Next comes the question how to organize the article files into a coherent structure.\n After thinking it over, this is what I landed on:\n
\n
\n
articles/\n
\n
YYYY-MM-DD-some-blog-title/\n
\n
index.html
\n
image.jpeg
\n
other files used in the article ...
\n
\n
\n
\n
\n
components/: the blog's shared web components
\n
index.html: the main landing page
\n
archive.html: the archives page
\n
index.js/css: shared resources
\n
feed.xml: the RSS feed
\n
\n
\n By wrapping every article and all its resources into a folder, each article can get as messy and complicated as it wants.\n The shared index.js and index.css is separate from that of the main site\n to keep the blog's resources out of the Plain Vanilla site's pages, and vice versa.\n
\n \n\n \n
Building indexes
\n\n
\n You wouldn't think a blog has a need for many indexes, but in fact this modest blog will have three:\n
\n \n
The recent posts section on the main landing page
\n
The recent posts in the RSS feed
\n
The full list of articles in the archive page
\n \n
\n Visually showing an index is not so difficult, as a web component built around a simple <li>-based\n card design can be used to show both the recent posts and the archive page, and was straighforward to style with CSS.\n
\n \n
\n Getting that data in a convenient form however is another matter.\n The RSS feed contains full text contents, so needs a separate step to build from the articles' HTML.\n The recent posts section on the index page thankfully can be built by reading the RSS feed,\n so was trivial to solve with a <blog-latest-posts> web component once the feed was set up.\n The full list of articles however cannot, as the RSS feed would grow too large if it contained all posts.\n So the archive page needs another separate step to build the full list of links from the folder of articles.\n
\n
\n For these build steps I considered various options:\n
\n
\n
❌ Manually keeping the files in sync
\n
\n It sounded like a lot of work, and error-prone, so a hard no on that one.\n
\n
❌ A generator script, and a package.json
\n
\n This is what I would normally go for, relying on a bunch of npm dependencies and a bunch of scripting\n to process the articles into the index files that are needed. \n It felt like cheating to bring in node and its ecosystem, so again this was a no.\n
\n
✅ A separate generator webpage
\n
\n I've wanted to play around with the\n File System API\n for a while, and this seemed a good opportunity.\n Turning the generator into a webpage also leaves options for actually running the web components\n and extracting their dynamically rendered content.\n
\n
\n\n
\n For the generator page I built a dedicated web component that allows opening or dropping the\n local blog/ folder with the newly written or updated articles,\n and then will process those into a feed.xml and index.json.\n The JSON file is used to load the contents of the archive page.\n The RSS feed is particularly tricky, because there is a limited set of tags that it should contain.\n By loading the article's HTML into a DOM parser, and replacing all unsupported tags (like the code viewer web component shown below)\n the HTML can be transformed into something that can be used as RSS feed entry contents.\n
\n
The core logic of the generator extracts the article's metadata and transforms the HTML:
\n \n\n
To give you an idea of what generator.html looks like in use:
\n \n\n
\n The generator JS ended up around 250 lines of code, so not too cumbersome to build or maintain.\n If you're curious about the generator, check out the \n blog's code on Github.\n It can be found in generator.html and generator.js.\n
\n\n
The user experience of writing a blog post then boils down to this:
\n \n
Create an article folder and write the article as HTML
\n
Open the generator page
\n
Drop the blog folder on the generator, it will automatically process the articles
\n
Copy the feed.xml and index.json text to their respective files
\n
Commit and push the changes
\n
Optionally: toot on mastodon, add the toot URL in the page, commit and push
\n ${btn}\n \n `;\n }\n}\ncustomElements.define('my-component', MyComponent);"
},
{
"path": "public/blog/articles/2024-08-25-vanilla-entity-encoding/html.js",
"content": "class Html extends String { }\n\n/** \n * tag a string as html not to be encoded\n * @param {string} str\n * @returns {string}\n */\nexport const htmlRaw = str => new Html(str);\n\n/** \n * entity encode a string as html\n * @param {*} value The value to encode\n * @returns {string}\n */\nexport const htmlEncode = (value) => {\n // avoid double-encoding the same string\n if (value instanceof Html) {\n return value;\n } else {\n // https://stackoverflow.com/a/57448862/20980\n return htmlRaw(\n String(value).replace(/[&<>'\"]/g, \n tag => ({\n '&': '&',\n '<': '<',\n '>': '>',\n \"'\": ''',\n '\"': '"'\n }[tag]))\n );\n }\n}\n\n/** \n * html tagged template literal, auto-encodes entities\n */\nexport const html = (strings, ...values) => \n htmlRaw(String.raw({ raw: strings }, ...values.map(htmlEncode)));\n"
},
{
"path": "public/blog/articles/2024-08-25-vanilla-entity-encoding/index.html",
"content": "\n\n\n Vanilla entity encoding\n \n \n \n\n\n \n \n
Vanilla entity encoding
\n
Joeri Sebrechts
\n \n \n
Good enough
\n
\n When I made the first version of the Plain Vanilla website, there were things that I would have liked\n to spend more time on, but that I felt didn't belong in a Good Enough™ version of the site.\n One of those things was defending against Cross-Site Scripting (XSS).\n
\n
\n XSS is still in the OWASP Top Ten of security issues, \n but it's no longer as prevalent as it used to be. Frameworks have built in a lot of defenses, \n and when using their templating systems you have to go out of your way to inject code into the generated HTML.\n When eschewing frameworks we're reduced to standard templating in our web components, and those offer no defense against XSS.\n
\n
\n Because of this, in the original site the Passing Data example \n on the Components page had an undocumented XSS bug.\n The name field could have scripts injected into it. I felt ambivalent about leaving that bug in.\n On the one hand, the code was very compact and neat by leaving it in.\n On the other hand it made that code a bad example that shouldn't be copied.\n I ended up choosing to leave it as-is because an example doesn't have to be production-grade\n and generating properly encoded HTML was not the point of that specific example.\n 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,\n if Santa really did want to bring his List application to production-level quality.\n
\n\n
The problem
\n
\n The basic problem we need to solve is that vanilla web components end up having a lot of code that looks like this:\n
\n \n
\n If any of foo, bar, baz or xyzzy contain one of the dangerous HTML entities,\n we risk seeing our component break, and worst-case risk seeing an attacker inject a malicious payload into the page.\n Just as a reminder, those dangerous HTML entities are <, >, &, ' and \".\n
\n\n
The fix, take one
\n
\n A naive fix is creating a html-encoding function and using it consistently:\n
\n \n
\n While this does work to defend against XSS, it is verbose and ugly, not pleasant to type and not pleasant to read.\n What really kills it though, is that it assumes attention to detail from us messy humans. We can never forget,\n never ever, to put a htmlEncode() around each and every variable.\n In the real world, that is somewhat unlikely.\n
\n
\n What is needed is a solution that allows us to forget about entity encoding, by doing it automatically\n when we're templating. I drew inspiration from templating libraries that work in-browser and are based on tagged templates, \n like lit-html \n and htm. The quest was on to build the most minimalistic\n html templating function that encoded entities automatically.\n
\n\n
The fix, take two
\n
\n Ideally, the fixed example should look more like this:\n
\n \n
\n The html``tagged template function \n would automatically encode entities, in a way that we don't even have to think about it.\n Even when we nest generated HTML inside of another template, like with ${btn}, it should just magically work.\n It would be so minimal as to disappear in the background, barely impacting readability, maybe even improving it.\n You may be thinking that doing that correctly would involve an impressive amount of code. I must disappoint.\n
\n \n
\n Those couple dozen lines of code are all that is needed. Let's go through it from top to bottom.\n
\n
\n
class Html extends String { }
\n
The Html class is used to mark strings as encoded, so that they won't be encoded again.
\n
export const htmlRaw = str => new Html(str);
\n
Case in point, the htmlRaw function does the marking.
\n
export const htmlEncode = ...
\n
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.
\n
export const html = ...
\n
The tagged template function that binds it together.
\n
\n\n
\n A nice upside of the html template function is that the html-in-template-string Visual Studio Code extension\n can detect it automatically and will syntax highlight the templated HTML. This is what example 3 looked like after I made it:\n
\n\n \n\n
\n Granted, there's still a bunch of boilerplate here, and that getAttribute gets unwieldy.\n 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.\n It's surprising how nice of a development experience web standards can be if you embrace them.\n
\n\n
\n I decided to leave the XSS bug in the Passing Data example, but now the Applications page\n has an explanation about entity encoding documenting this html template function.\n I can only hope people that work their way through the tutorial make it that far.\n For your convenience I also put the HTML templating function in its own separate \n html-literal repo on Github.\n
\n Signals are all the rage right now. Everyone's doing them.\n Angular,\n and Solid,\n and Preact,\n and there are third party packages for just about every framework that doesn't already have them.\n There's even a proposal\n to add them to the language, and if that passes it's just a \n matter of time before all frameworks \n have them built in.\n
\n\n
Living under a rock
\n
\n In case you've been living under a rock, here's the example from Preact's documentation \n that neatly summarizes what signals do:\n
\n \n
\n Simply put, signals wrap values and computations \n in a way that allows us to easily respond to every change to those values and results in a targeted way,\n without having to rerender the entire application in the way that we would do in React.\n In short, signals are an efficient and targeted way to respond to changes without having to do state comparison and DOM-diffing.\n
\n
\n OK, so, if signals are so great, why am I trying to sell you on them on a vanilla web development blog?\n Don't worry! Vanilla web developers can have signals too.\n
\n\n
Just a wrapper
\n
\n Signals are at heart nothing more than a wrapper for a value that sends events when the value changes.\n That's nothing that a little trickery with the not well known but very handy EventTarget base class can't fix for us.\n
\n \n
\n This gets us a very barebones signals experience:\n
\n \n
\n But that's kind of ugly. The new keyword went out of fashion a decade ago,\n and that addEventListener sure is unwieldy.\n So let's add a little syntactic sugar.\n
\n \n
\n Now our barebones example is a lot nicer to use:\n
\n \n
\n The effect(fn) method will call the specified function,\n and also subscribe it to changes in the signal's value.\n
\n
\n It also returns a dispose function that can be used to unregister the effect.\n However, a nice side effect of using EventTarget and browser built-in events as the reactivity primitive\n is that it makes the browser smart enough to garbage collect the signal and its effect when the signal goes out of scope.\n This means less chance for memory leaks even if we never call the dispose function.\n
\n
\n Finally, the toString and valueOf magic methods allow for dropping .value in most places\n that the signal's value gets used. (But not in this example, because the console is far too clever for that.)\n
\n\n
Does not compute
\n
\n This signals implementation is already capable, but at some point it might be handy to have an effect based on more than one signal.\n That means supporting computed values. Where the base signals are a wrapper around a value,\n computed signals are a wrapper around a function.\n
\n \n
\n The computed signal calculates its value from a function.\n It also depends on other signals, and when they change it will recompute its value.\n It's a bit obnoxious to have to pass the signals that it depends on\n as an additional parameter, but hey, I didn't title this article Rich man's signals.\n
\n
\n This enables porting Preact's signals example to vanilla JS.\n
\n \n\n
Can you use it in a sentence?
\n
\n You may be thinking, all these console.log examples are fine and dandy,\n but how do you use this stuff in actual web development?\n This simple adder demonstrates how signals can be combined with web components:\n
\n \n
\n And here's a live demo:\n
\n \n
\n In case you were wondering, the if is there to prevent adding the effect twice\n if connectedCallback is called when the component is already rendered.\n
\n
\n The full poor man's signals code in all its 36 line glory can be found in the tiny-signals repo on Github.\n
\n \n \n \n\n"
},
{
"path": "public/blog/articles/2024-08-30-poor-mans-signals/preact-example.js",
"content": "import { signal, computed, effect } from \"@preact/signals\";\n\nconst name = signal(\"Jane\");\nconst surname = signal(\"Doe\");\nconst fullName = computed(() => `${name.value} ${surname.value}`);\n\n// Logs name every time it changes:\neffect(() => console.log(fullName.value));\n// Logs: \"Jane Doe\"\n\n// Updating `name` updates `fullName`, which triggers the effect again:\nname.value = \"John\";\n// Logs: \"John Doe\"\n"
},
{
"path": "public/blog/articles/2024-08-30-poor-mans-signals/signals.js",
"content": "export class Signal extends EventTarget {\n #value;\n get value () { return this.#value; }\n set value (value) {\n if (this.#value === value) return;\n this.#value = value;\n this.dispatchEvent(new CustomEvent('change')); \n }\n\n constructor (value) {\n super();\n this.#value = value;\n }\n\n effect(fn) {\n fn();\n this.addEventListener('change', fn);\n return () => this.removeEventListener('change', fn);\n }\n\n valueOf () { return this.#value; }\n toString () { return String(this.#value); }\n}\n\nexport class Computed extends Signal {\n constructor (fn, deps) {\n super(fn(...deps));\n for (const dep of deps) {\n if (dep instanceof Signal) \n dep.addEventListener('change', () => this.value = fn(...deps));\n }\n }\n}\n\nexport const signal = _ => new Signal(_);\nexport const computed = (fn, deps) => new Computed(fn, deps);\n"
},
{
"path": "public/blog/articles/2024-08-30-poor-mans-signals/signals1-use.js",
"content": "const name = new Signal('Jane');\nname.addEventListener('change', () => console.log(name.value));\nname.value = 'John';\n// Logs: John"
},
{
"path": "public/blog/articles/2024-08-30-poor-mans-signals/signals1.js",
"content": "class Signal extends EventTarget {\n #value;\n get value () { return this.#value; }\n set value (value) {\n if (this.#value === value) return;\n this.#value = value;\n this.dispatchEvent(new CustomEvent('change')); \n }\n\n constructor (value) {\n super();\n this.#value = value;\n }\n}"
},
{
"path": "public/blog/articles/2024-08-30-poor-mans-signals/signals2-use.js",
"content": "const name = signal('Jane');\nname.effect(() => console.log(name.value));\n// Logs: Jane\nname.value = 'John';\n// Logs: John"
},
{
"path": "public/blog/articles/2024-08-30-poor-mans-signals/signals2.js",
"content": "class Signal extends EventTarget {\n #value;\n get value () { return this.#value; }\n set value (value) {\n if (this.#value === value) return;\n this.#value = value;\n this.dispatchEvent(new CustomEvent('change')); \n }\n\n constructor (value) {\n super();\n this.#value = value;\n }\n\n effect(fn) {\n fn();\n this.addEventListener('change', fn);\n return () => this.removeEventListener('change', fn);\n }\n\n valueOf () { return this.#value; }\n toString () { return String(this.#value); }\n}\n\nconst signal = _ => new Signal(_);\n"
},
{
"path": "public/blog/articles/2024-08-30-poor-mans-signals/signals3-use.js",
"content": "const name = signal('Jane');\nconst surname = signal('Doe');\nconst fullName = computed(() => `${name} ${surname}`, [name, surname]);\n// Logs name every time it changes:\nfullName.effect(() => console.log(fullName.value));\n// -> Jane Doe\n\n// Updating `name` updates `fullName`, which triggers the effect again:\nname.value = 'John';\n// -> John Doe\n"
},
{
"path": "public/blog/articles/2024-08-30-poor-mans-signals/signals3.js",
"content": "class Computed extends Signal {\n constructor (fn, deps) {\n super(fn(...deps));\n for (const dep of deps) {\n if (dep instanceof Signal) \n dep.addEventListener('change', () => this.value = fn(...deps));\n }\n }\n}\n\nconst computed = (fn, deps) => new Computed(fn, deps);\n"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/adder.svelte",
"content": "\n\n\n\n\n
{a} + {b} = {a + b}
"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/bind.js",
"content": "/**\n* Render a template (element or string) to an html fragment \n* while connecting it up to data using Vue-style shorthand binding syntax.\n*\n* - `@click=\"handleClick\"` -> `click` event and `target.handleClick` method\n* - `@change=\"mySignal\"` -> `change` event will set `target.mySignal.value` to e.target.value\n* - `@change=\"myProp\"` -> `change` event will set `target.myProp` to e.target.value\n* - `:textContent=\"text\"` -> elem `textContent` property is set to `this.text` property once\n* (also supports special shorthand `:text` for textContent and `:html` for innerHTML)\n* - `:value=\"mySignal\"` -> elem `value` attribute is bound to the signal `target.mySignal`'s value\n*\n* @param {*} template The template to be bound to an object\n* @param {*} target The object being targeted for binding\n* @returns fragment\n*/\nexport const bind = (template, target) => {\n if (!template.content) {\n const text = template;\n template = document.createElement('template');\n template.innerHTML = text;\n }\n const fragment = template.content.cloneNode(true);\n // iterate over all nodes in the fragment and bind them\n // based on https://hawkticehurst.com/2024/05/bring-your-own-base-class/\n const iterator = document.createNodeIterator(\n fragment,\n NodeFilter.SHOW_ELEMENT,\n {\n // Reject any node that is not an HTML element\n acceptNode: (node) => {\n if (!(node instanceof HTMLElement))\n return NodeFilter.FILTER_REJECT;\n return NodeFilter.FILTER_ACCEPT;\n },\n }\n );\n let node;\n while (node = iterator.nextNode()) {\n if (!node) return;\n const elem = node;\n // list of all properties\n // const properties = getAllProperties(elem);\n // copy NamedNodeMap because we're about to change it\n for (const attr of Array(...node.attributes)) {\n // check for custom event listener attributes\n if (attr.name.startsWith('@')) {\n const event = attr.name.slice(1);\n const property = attr.value;\n let listener;\n // if we're binding the event to a function, call it directly\n if (typeof target[property] === 'function') {\n listener = target[property].bind(target);\n // if we're binding to a signal, set the signal's value\n } else if (typeof target[property] === 'object' && \n typeof target[property].value !== 'undefined') {\n listener = e => target[property].value = e.target.value;\n // fallback: assume we're binding to a property, set the property's value\n } else {\n listener = e => target[property] = e.target.value;\n }\n elem.addEventListener(event, listener);\n // remove (non-standard) attribute from element\n elem.removeAttributeNode(attr);\n // check for custom property/attribute binding attributes\n } else if (attr.name.startsWith(':')) {\n // extract the name and value of the attribute/property\n let name = attr.name.slice(1);\n const property = getPropertyForAttribute(name, target); // properties.values().find(k => k.toLowerCase() === name.toLowerCase());\n const setter = property ?\n () => elem[property] = target[attr.value] :\n () => elem.setAttribute(name, target[attr.value]);\n setter();\n // if we're binding to a signal, listen to updates\n target[attr.value].effect?.(setter);\n // remove (non-standard) attribute from element\n elem.removeAttributeNode(attr);\n }\n }\n }\n return fragment;\n}\n\nfunction getPropertyForAttribute(name, obj) {\n switch (name.toLowerCase()) {\n case 'text': case 'textcontent':\n return 'textContent';\n case 'html': case 'innerhtml':\n return 'innerHTML';\n default:\n for (let prop of Object.getOwnPropertyNames(obj)) {\n if (prop.toLowerCase() === name.toLowerCase()) {\n return prop;\n }\n } \n }\n}"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/bind1.js",
"content": "export const bind = (template) => {\n const fragment = template.content.cloneNode(true);\n // iterate over all nodes in the fragment\n const iterator = document.createNodeIterator(\n fragment,\n NodeFilter.SHOW_ELEMENT,\n {\n // reject any node that is not an HTML element\n acceptNode: (node) => {\n if (!(node instanceof HTMLElement))\n return NodeFilter.FILTER_REJECT;\n return NodeFilter.FILTER_ACCEPT;\n },\n }\n );\n let node;\n while (node = iterator.nextNode()) {\n if (!node) return;\n const elem = node;\n for (const attr of Array(...node.attributes)) {\n // check for event binding directive\n if (attr.name.startsWith('@')) {\n\n // TODO: bind event ...\n \n elem.removeAttributeNode(attr);\n // check for property/attribute binding directive\n } else if (attr.name.startsWith(':')) {\n \n // TODO: bind data ...\n \n elem.removeAttributeNode(attr);\n }\n }\n }\n return fragment;\n}"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/bind2-partial.js",
"content": "export const bind = (template, target) => {\n if (!template.content) {\n const text = template;\n template = document.createElement('template');\n template.innerHTML = text;\n }\n const fragment = template.content.cloneNode(true);\n// ...\n}"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/bind3-partial.js",
"content": "// check for custom event listener attributes\nif (attr.name.startsWith('@')) {\n const event = attr.name.slice(1);\n const property = attr.value;\n let listener;\n // if we're binding the event to a function, call it directly\n if (typeof target[property] === 'function') {\n listener = target[property].bind(target);\n // if we're binding to a signal, set the signal's value\n } else if (typeof target[property] === 'object' && \n typeof target[property].value !== 'undefined') {\n listener = e => target[property].value = e.target.value;\n // fallback: assume we're binding to a property, set the property's value\n } else {\n listener = e => target[property] = e.target.value;\n }\n elem.addEventListener(event, listener);\n // remove (non-standard) attribute from element\n elem.removeAttributeNode(attr);\n}"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/bind4-partial.js",
"content": "// ...\n if (attr.name.startsWith(':')) {\n // extract the name and value of the attribute/property\n let name = attr.name.slice(1);\n const property = getPropertyForAttribute(name, target);\n const setter = property ?\n () => elem[property] = target[attr.value] :\n () => elem.setAttribute(name, target[attr.value]);\n setter();\n // if we're binding to a signal, listen to updates\n if (target[attr.value]?.effect) {\n target[attr.value].effect(setter);\n // if we're binding to a property, listen to the target's updates\n } else if (target.addEventListener) {\n target.addEventListener('change', setter);\n }\n // remove (non-standard) attribute from element\n elem.removeAttributeNode(attr);\n }\n// ...\n\nfunction getPropertyForAttribute(name, obj) {\n switch (name.toLowerCase()) {\n case 'text': case 'textcontent':\n return 'textContent';\n case 'html': case 'innerhtml':\n return 'innerHTML';\n default:\n for (let prop of Object.getOwnPropertyNames(obj)) {\n if (prop.toLowerCase() === name.toLowerCase()) {\n return prop;\n }\n } \n }\n}"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/example-bind3/bind.js",
"content": "export const bind = (template, target) => {\n if (!template.content) {\n const text = template;\n template = document.createElement('template');\n template.innerHTML = text;\n }\n const fragment = template.content.cloneNode(true);\n // iterate over all nodes in the fragment\n const iterator = document.createNodeIterator(\n fragment,\n NodeFilter.SHOW_ELEMENT,\n {\n // reject any node that is not an HTML element\n acceptNode: (node) => {\n if (!(node instanceof HTMLElement))\n return NodeFilter.FILTER_REJECT;\n return NodeFilter.FILTER_ACCEPT;\n },\n }\n );\n let node;\n while (node = iterator.nextNode()) {\n if (!node) return;\n const elem = node;\n for (const attr of Array(...node.attributes)) {\n // check for event binding directive\n if (attr.name.startsWith('@')) {\n // check for custom event listener attributes\n if (attr.name.startsWith('@')) {\n const event = attr.name.slice(1);\n const property = attr.value;\n let listener;\n // if we're binding the event to a function, call it directly\n if (typeof target[property] === 'function') {\n listener = target[property].bind(target);\n // if we're binding to a signal, set the signal's value\n } else if (typeof target[property] === 'object' && \n typeof target[property].value !== 'undefined') {\n listener = e => target[property].value = e.target.value;\n // fallback: assume we're binding to a property, set the property's value\n } else {\n listener = e => target[property] = e.target.value;\n }\n elem.addEventListener(event, listener);\n // remove (non-standard) attribute from element\n elem.removeAttributeNode(attr);\n }\n // check for property/attribute binding directive\n } else if (attr.name.startsWith(':')) {\n\n // TODO: bind data ...\n \n elem.removeAttributeNode(attr);\n }\n }\n }\n return fragment;\n}\n"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/example-bind3/example.html",
"content": "\n\n Binding example\n \n\n\n \n \n \n"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/example-bind3/example.js",
"content": "import { bind } from './bind.js';\nimport { signal } from './signals.js';\n\ncustomElements.define('x-example', class Example extends HTMLElement {\n\n set a(value) { \n this.setAttribute('a', value);\n this.querySelector('label[for=a] span').textContent = value;\n }\n set b(value) {\n this.setAttribute('b', value);\n this.querySelector('label[for=b] span').textContent = value;\n }\n c = signal('');\n\n connectedCallback() {\n this.append(bind(`\n
\n \n \n
\n
\n \n \n
\n
\n \n \n
\n \n
Result:
\n `, this));\n this.c.effect(() => \n this.querySelector('label[for=c] span').textContent = this.c);\n }\n\n onInputA (e) {\n this.a = e.target.value;\n }\n\n onClick() {\n this.querySelector('#result').textContent =\n +this.getAttribute('a') + +this.getAttribute('b') + +this.c;\n }\n});\n"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/example-bind3/signals.js",
"content": "export class Signal extends EventTarget {\n #value;\n get value () { return this.#value; }\n set value (value) {\n if (this.#value === value) return;\n this.#value = value;\n this.dispatchEvent(new CustomEvent('change')); \n }\n\n constructor (value) {\n super();\n this.#value = value;\n }\n\n effect(fn) {\n fn();\n this.addEventListener('change', fn);\n return () => this.removeEventListener('change', fn);\n }\n\n valueOf () { return this.#value; }\n toString () { return String(this.#value); }\n}\n\nexport class Computed extends Signal {\n constructor (fn, deps) {\n super(fn(...deps));\n for (const dep of deps) {\n if (dep instanceof Signal) \n dep.addEventListener('change', () => this.value = fn(...deps));\n }\n }\n}\n\nexport const signal = _ => new Signal(_);\nexport const computed = (fn, deps) => new Computed(fn, deps);\n"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/example-combined/adder.js",
"content": "import { bind } from './bind.js';\nimport { signal, computed } from './signals.js';\nimport { html } from './html.js';\n\ncustomElements.define('x-adder', class Adder extends HTMLElement {\n a = signal();\n b = signal();\n result = computed(() => \n html`${+this.a} + ${+this.b} = ${+this.a + +this.b}`, [this.a, this.b]);\n\n connectedCallback() {\n this.a.value ??= this.getAttribute('a') || 0;\n this.b.value ??= this.getAttribute('b') || 0;\n this.append(bind(html`\n \n \n \n `, this));\n }\n});\n"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/example-combined/bind.js",
"content": "/**\n* Render a template (element or string) to an html fragment \n* while connecting it up to data using Vue-style shorthand binding syntax.\n*\n* - `@click=\"handleClick\"` -> `click` event and `target.handleClick` method\n* - `@change=\"mySignal\"` -> `change` event will set `target.mySignal.value` to e.target.value\n* - `@change=\"myProp\"` -> `change` event will set `target.myProp` to e.target.value\n* - `:textContent=\"text\"` -> elem `textContent` property is set to `this.text` property once\n* (also supports special shorthand `:text` for textContent and `:html` for innerHTML)\n* - `:value=\"mySignal\"` -> elem `value` attribute is bound to the signal `target.mySignal`'s value\n*\n* @param {*} template The template to be bound to an object\n* @param {*} target The object being targeted for binding\n* @returns fragment\n* @license Unlicense\n*/\nexport const bind = (template, target) => {\n if (!template.content) {\n const text = template;\n template = document.createElement('template');\n template.innerHTML = text;\n }\n const fragment = template.content.cloneNode(true);\n // iterate over all nodes in the fragment and bind them\n // based on https://hawkticehurst.com/2024/05/bring-your-own-base-class/\n const iterator = document.createNodeIterator(\n fragment,\n NodeFilter.SHOW_ELEMENT,\n {\n // Reject any node that is not an HTML element\n acceptNode: (node) => {\n if (!(node instanceof HTMLElement))\n return NodeFilter.FILTER_REJECT;\n return NodeFilter.FILTER_ACCEPT;\n },\n }\n );\n let node;\n while (node = iterator.nextNode()) {\n if (!node) return;\n const elem = node;\n for (const attr of Array(...node.attributes)) {\n // check for custom event listener attributes\n if (attr.name.startsWith('@')) {\n const event = attr.name.slice(1);\n const property = attr.value;\n let listener;\n // if we're binding the event to a function, call it directly\n if (typeof target[property] === 'function') {\n listener = target[property].bind(target);\n // if we're binding to a signal, set the signal's value\n } else if (typeof target[property] === 'object' && \n typeof target[property].value !== 'undefined') {\n listener = e => target[property].value = e.target.value;\n // fallback: assume we're binding to a property, set the property's value\n } else {\n listener = e => target[property] = e.target.value;\n }\n elem.addEventListener(event, listener);\n // remove (non-standard) attribute from element\n elem.removeAttributeNode(attr);\n // check for custom property/attribute binding attributes\n } else if (attr.name.startsWith(':')) {\n // extract the name and value of the attribute/property\n let name = attr.name.slice(1);\n const property = getPropertyForAttribute(name, target);\n const setter = property ?\n () => elem[property] = target[attr.value] :\n () => elem.setAttribute(name, target[attr.value]);\n setter();\n // if we're binding to a signal, listen to updates\n target[attr.value].effect?.(setter);\n // remove (non-standard) attribute from element\n elem.removeAttributeNode(attr);\n }\n }\n }\n return fragment;\n}\n\nfunction getPropertyForAttribute(name, obj) {\n switch (name.toLowerCase()) {\n case 'text': case 'textcontent':\n return 'textContent';\n case 'html': case 'innerhtml':\n return 'innerHTML';\n default:\n for (let prop of Object.getOwnPropertyNames(obj)) {\n if (prop.toLowerCase() === name.toLowerCase()) {\n return prop;\n }\n } \n }\n}"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/example-combined/example.html",
"content": "\n\n Binding example\n \n\n\n \n \n \n"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/example-combined/html.js",
"content": "class Html extends String { }\n\n/** \n * tag a string as html not to be encoded\n * @param {string} str\n * @returns {string}\n */\nexport const htmlRaw = str => new Html(str);\n\n/** \n * entity encode a string as html\n * @param {*} value The value to encode\n * @returns {string}\n */\nexport const htmlEncode = (value) => {\n // avoid double-encoding the same string\n if (value instanceof Html) {\n return value;\n } else {\n // https://stackoverflow.com/a/57448862/20980\n return htmlRaw(\n String(value).replace(/[&<>'\"]/g, \n tag => ({\n '&': '&',\n '<': '<',\n '>': '>',\n \"'\": ''',\n '\"': '"'\n }[tag]))\n );\n }\n}\n\n/** \n * html tagged template literal, auto-encodes entities\n */\nexport const html = (strings, ...values) => \n htmlRaw(String.raw({ raw: strings }, ...values.map(htmlEncode)));\n"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/example-combined/signals.js",
"content": "export class Signal extends EventTarget {\n #value;\n get value () { return this.#value; }\n set value (value) {\n if (this.#value === value) return;\n this.#value = value;\n this.dispatchEvent(new CustomEvent('change')); \n }\n\n constructor (value) {\n super();\n this.#value = value;\n }\n\n effect(fn) {\n fn();\n this.addEventListener('change', fn);\n return () => this.removeEventListener('change', fn);\n }\n\n valueOf () { return this.#value; }\n toString () { return String(this.#value); }\n}\n\nexport class Computed extends Signal {\n constructor (fn, deps) {\n super(fn(...deps));\n for (const dep of deps) {\n if (dep instanceof Signal) \n dep.addEventListener('change', () => this.value = fn(...deps));\n }\n }\n}\n\nexport const signal = _ => new Signal(_);\nexport const computed = (fn, deps) => new Computed(fn, deps);\n"
},
{
"path": "public/blog/articles/2024-09-03-unix-philosophy/index.html",
"content": "\n\n\n A unix philosophy for web development\n \n \n \n\n\n \n \n
A unix philosophy for web development
\n
Joeri Sebrechts
\n \n \n
\n Web components have their malcontents. While frameworks have done their best to provide\n a place for web components to fit into their architecture, the suit never fits quite right,\n and framework authors have not been shy about expressing their disappointment.\n Here's Ryan Carniato of SolidJS explaining what's wrong with web components:\n
\n
\n The collection of standards (Custom Elements, HTML Templates, Shadow DOM, and formerly HTML Imports) \n put together to form Web Components on the surface seem like they could be used to replace \n your favourite library or framework. But they are not an advanced templating solution. \n They don't improve your ability to render or update the DOM. \n They don't manage higher-level concerns for you like state management.\n
\n While this criticism is true, perhaps it's besides the point.\n Maybe web components were never meant to solve those problems anyway.\n Maybe there are ways to solve those problems in a way that dovetails with web components as they exist.\n In the main components tutorial I've already explained what they can do,\n now let's see what can be done about the things that they can't do.\n
\n\n
The Unix Philosophy
\n\n
\n The Unix operating system carries with it a culture and philosophy of system design,\n which carries over to the command lines of today's Unix-like systems like Linux and MacOS. \n This philosophy can be summarized as follows:\n
\n
\n
Write programs that do one thing and do it well.
\n
Write programs to work together.
\n
Write programs to handle text streams, because that is a universal interface.
\n
\n
\n What if we look at the various technologies that comprise web components as just programs, \n part of a Unix-like system of web development that we collectively call the browser platform?\n In that system we can do better than text and use the DOM as the universal interface between programs, \n and we can extend the system with a set of single purpose independent \"programs\" (functions) \n that fully embrace the DOM by augmenting it instead of replacing it.\n
\n
\n In a sense this is the most old-school way of building web projects, the one people who \"don't know any better\"\n automatically gravitate to. What us old-school web developers did before Vue and Solid and Svelte, before Angular and React,\n before Knockout and Ember and Backbone, before even jQuery, was have a bunch of functions in utilities.js\n that we copied along from project to project.\n But, you know, sometimes old things can become new again.\n
\n
\n In previous posts I've already covered a html() function for vanilla entity encoding,\n and a signal() function that provides a tiny signals implementation \n that can serve as a lightweight system for state management.\n That still leaves a missing link between the state managed by the signals and the DOM that is rendered from safely entity-encoded HTML.\n What we need is a bind() function that can bind data to DOM elements and bind DOM events back to data.\n
\n\n
Finding inspiration
\n\n
\n In order to bind a template to data, we need a way of describing that behavior in the HTML markup.\n Well-trodden paths are often the best starting place to look for inspiration. I like Vue's template syntax,\n because it is valid HTML but just augmented, and because it is proven. Vue's templates only pretend to be HTML\n because they're actually compiled to JavaScript behind the scenes, but let's start there as an API.\n This is what it looks like:\n
\n
\n
<img :src=\"imageSrc\" />
\n
Bind src to track the value of the imageSrc property of the current component.\n Vue is smart enough to set a property if one exists, and falls back to setting an attribute otherwise.\n (If that confuses you, read about attributes and properties first.)
\n
<button @click=\"doThis\"></button>
\n
Bind the click event to the doThis method of the current component.
\n
\n
\n By chance I came across this article about making a web component base class.\n In the section Declarative interactivity the author shows a way to do the Vue-like event binding syntax\n on a vanilla web component. This is what inspired me to develop the concept into a generic binding function and write this article.\n
\n\n
Just an iterator
\n\n
\n The heart of the binding function is an HTML fragment iterator. \n After all, before we can bind attributes we need to first find the ones that have binding directives.\n
\n \n
\n This code will take an HTML template element, \n clone it to a document fragment, \n and then iterate over all the nodes in the fragment, discovering their attributes. \n Then for each attribute a check is made to see if it's a binding directive (@ or :). \n The node is then bound to data according to the directive attribute (shown here as TODO's), \n and the attribute is removed from the node. At the end the bound fragment is returned for inserting into the DOM.\n
\n
\n The benefit of using a fragment is that it is disconnected from the main DOM, while still offering all of the DOM API's. \n That means we can easily create a node iterator to walk over it and discover all the attributes \n with binding directives, modify those nodes and attributes in-place, and still be sure we're not causing \n DOM updates in the main page until the fragment is inserted there. This makes the bind function very fast.\n
\n
\n If you're thinking \"woah dude, that's a lot of code and a lot of technobabble, I ain't reading all that,\"\n then please, I implore you to read through the code line by line, and you'll see it will all make sense.\n
\n
\n Of course, we also need to have something to bind to, so we need to add a second parameter.\n 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.\n The beginning of our bind function then ends up looking like this:\n
\n \n
That just leaves us the TODO's. We can make those as simple or complicated as we want. I'll pick a middle ground.
\n\n
Binding to events
\n\n
This 20 line handler binds events to methods, signals or properties:
\n \n\n
That probably doesn't explain much, so let me give an example of what this enables:
\n \n \n\n
\n
input#a's input event is handled by calling the onClickA() method.
\n
input#b's input event is handled by assigning e.target.value to the b property.
\n
input#c's input event is handled by setting the value of the c signal.
\n
\n
\n If you're not familiar with the signal() function, check out the tiny signals \n implementation in the previous post. For now you can also just roll with it.\n
\n
Not a bad result for 20 lines of code.
\n\n
Binding to data
\n
\n Having established the pattern for events that automatically update properties, \n we now reverse the polarity to make data values automatically set element properties or attributes.\n
\n \n
\n The getPropertyForAttribute function is necessary because the attributes that contain the directives\n will have names that are case-insensitive, and these must be mapped to property names that are case-sensitive.\n Also, the :text and :html shorthand notations replace the role of v-text\n and v-html in Vue's template syntax.\n
\n
\n When the value of the target's observed property changes, we need to update the bound element's property or attribute.\n This means a triggering 'change' event is needed that is then subscribed to.\n A framework's templating system will compare state across time, and detect the changed values automatically. \n Lacking such a system we need a light-weight alternative.\n
\n
\n When the property being bound to is a signal, this code registers an effect on the signal.\n When the property is just a value, it registers an event listener on the target object,\n making it the responsibility of that target object to dispatch the 'change' event when values change.\n This approach isn't going to get many points for style, but it does work.\n
\n In the article Why I don't use web components \n Svelte's Rich Harris lays out the case against web components. He demonstrates how this simple 9 line Svelte component\n <Adder a={1} b={2}/> becomes an incredible verbose 59 line monstrosity when ported to a vanilla web component.\n
\n \n\n
\n Now that we have assembled our three helper functions html(), signal() and bind()\n 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 <x-adder a=\"1\" b=\"2\"></x-adder>?\n
\n \n \n\n
\n 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. \n And I'm just shooting in the wind here, trying stuff out.\n Somewhere out there could be a minimal set of functions that transforms web components into something resembling a framework,\n and the idea excites me! Who knows, maybe in a few years the web community will return to writing projects in \n vanilla web code, dragging along the modern equivalent of utilities.js from project to project...\n
\n \n
What do you think?
\n \n \n \n\n"
},
{
"path": "public/blog/articles/2024-09-06-how-fast-are-web-components/index.html",
"content": "\n\n\n How fast are web components?\n \n \n \n \n\n\n \n \n
How fast are web components?
\n
Joeri Sebrechts
\n \n \n \n\n
\n It is often said that web components are slow.\n This was also my experience when I first tried building web components a few years ago.\n At the time I was using the Stencil framework, because I didn't feel confident that they could be built well without a framework.\n Performance when putting hundreds of them on a page was so bad that I ended up going back to React.\n
\n
\n But as I've gotten deeper into vanilla web development I started to realize that maybe I was just using it wrong.\n Perhaps web components can be fast, if built in a light-weight way.\n This article is an attempt to settle the question \"How fast are web components?\".\n
\n\n
The lay of the land
\n\n
\n What kinds of questions did I want answered?\n
\n
\n
How many web components can you render on the page in a millisecond?
\n
Does the technique used to built the web component matter, which technique is fastest?
\n
How do web component frameworks compare? I used Lit as the framework of choice as it is well-respected.
\n
How does React compare?
\n
What happens when you combine React with web components?
\n
\n\n
\n To figure out the answer I made a benchmark as a vanilla web page (of course),\n that renders thousands of very simple components containing only <span>.</span>\n and measured the elapsed time. This benchmark was then run on multiple devices and multiple browsers\n to figure out performance characteristics. The ultimate goal of this test is to figure out the absolute best performance\n that can be extracted from the most minimal web component.\n
\n\n
To get a performance range I used two devices for testing:
\n
\n
A Macbook Air M1 running MacOS, to stand in as the \"fast\" device, comparable to a new high end iPhone.
\n
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.
\n
\n
Between these devices is a 7x CPU performance gap.
\n\n
The test
\n\n
\n The test is simple: render thousands of components using a specific technique, \n call requestAnimationFrame() repeatedly until they actually render,\n then measure elapsed time. This produces a components per millisecond number.\n
\n
The techniques being compared:
\n
\n
innerHTML: each web component renders its content by assigning to this.innerHTML
\n
append: each web component creates the span using document.createElement and then appends it to itself
\n
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
\n
shadow + innerHTML: the same as innerHTML, except each component has a shadow DOM
\n
shadow + append: the same as append, except each component has a shadow DOM
\n
template + append: each web component renders its content by cloning a template and appending it
\n
textcontent: each web component directly sets its textContent property, instead of adding a span (making the component itself be the span)\n
direct: appends spans instead of custom elements, to be able to measure custom element overhead
\n
lit: each web component is rendered using the lit framework, in the way that its documentation recommends
\n
react pure: rendering in React as a standard React component, to have a baseline for comparison to mainstream web development
\n
react + wc: each React component wraps the append-style web component
\n
(norender): same as other strategies, except the component is only created but not added to the DOM, to separate out component construction cost
\n
\n
\n This test was run on M1 in Brave, Chrome, Edge, Firefox and Safari. And on Chi in Chrome and Firefox.\n It was run for 10 iterations and a geometric mean was taken of the results.\n
\n\n
The results
\n\n
First, let's compare techniques. The number here is components per millisecond, so higher is better.
\n \n
Author's note: the numbers from the previous version of this article are crossed out.
\n
\n \n
Chrome on M1
\n
technique
components/ms
\n \n \n
innerHTML
143 135
\n
append
233 239
\n
append (buffered)
228 239
\n
shadow + innerHTML
132 127
\n
shadow + append
183 203
\n
template + append
181 198
\n
textcontent
345
\n
direct
461
\n
lit
133 137
\n
react pure
275 338
\n
react + wc
172 212
\n
append (norender)
1393
\n
shadow (norender)
814
\n
direct (norender)
4277
\n
lit (norender)
880
\n \n
\n\n
\n \n
Chrome on Chi, best of three
\n
technique
components/ms
\n \n \n
innerHTML
25 29
\n
append
55 55
\n
append (buffered)
56 59
\n
shadow + innerHTML
24 26
\n
shadow + append
36 47
\n
template + append
45 46
\n
textcontent
81
\n
direct
116
\n
lit
30 33
\n
react pure
77 87
\n
react + wc
45 52
\n
append (norender)
434
\n
shadow (norender)
231
\n
direct (norender)
1290
\n
lit (norender)
239
\n \n
\n\n
\n One relief right off the bat is that even the slowest implementation on the slow device renders 100.000 components in 4 seconds.\n React is roughly in the same performance class as well-written web components.\n That means for a typical web app performance is not a reason to avoid web components.\n
\n \n\n
\n As far as web component technique goes, the performance delta between the fastest and the slowest technique is around 2x,\n so again for a typical web app that difference will not matter. Things that slow down web components\n are shadow DOM and innerHTML. Appending directly created elements or cloned templates and avoiding shadow DOM is the right strategy\n for a well-performing web component that needs to end up on the page thousands of times.\n
\n\n
\n On the slow device the Lit framework is a weak performer, probably due to its use of shadow DOM and JS-heavy approaches.\n 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,\n it benefits from not having to initialize the web component class instances.\n Consequently, when wrapping web components inside React components we see React's performance advantage disappear, and that it adds a performance tax.\n In the grand scheme of things however, the differences between React and optimized web components remains small.\n
\n\n
\n The fast device is up to 5x faster than the slow device in Chrome, depending on the technique used,\n so it is really worth testing applications on slow devices to get an idea of the range of performance.\n
\n\n
\n Next, let's compare browsers:\n
\n\n
\n \n
M1, append, best of three
\n
browser
components/ms
\n \n \n
Brave
146 145
\n
Chrome
233 239
\n
Edge
224 237
\n
Firefox
232 299
\n
Safari
260 239
\n \n
\n\n
\n \n
Chi, append, best of three
\n
browser
components/ms
\n \n \n
Chrome
55 55
\n
Firefox
180 77
\n \n
\n\n
\n Brave is really slow, probably because of its built-in ad blocking. Ad blocking extensions also slow down the other browsers by a lot.\n Safari, Chrome and Edge end up in roughly the same performance bucket. Firefox is the best performer overall.\n Using the \"wrong\" browser can halve the performance of a machine.\n
\n
\n Author's note:\n 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.\n
\n
\n There is a large performance gap when you compare the slowest technique on the slowest browser on the slowest device,\n with its fastest opposite combo. Specifically, there is a 16x performance gap:\n
\n
\n
textContent, Firefox on M1: 430 components/ms
\n
Shadow DOM + innerHTML, Chrome on Chi: 26 components/ms
\n
\n
\n That means it becomes worthwhile to carefully consider technique when having to support a wide range of browsers and devices,\n because a bad combination may lead to a meaningfully degraded user experience.\n And of course, you should always test your web app on a slow device to make sure it still works ok.\n
\n \n
Bottom line
\n\n
\n I feel confident now that web components can be fast enough for almost all use cases where someone might consider React instead.\n
\n
\n However, it does matter how they are built. Shadow DOM should not be used for smaller often used web components,\n and the contents of those smaller components should be built using append operations instead of innerHTML.\n The use of web component frameworks might impact their performance significantly,\n and given how easy it is to write vanilla web components I personally don't see the point behind Lit or Stencil. YMMV.\n
\n\n
\n The full benchmark code and results can be found on Github.\n
\n * \n * Shows the error if loading fails:\n * \n * \n * \n * \n * @license MIT\n */\nexport class ErrorBoundary extends HTMLElement {\n\n /**\n * Find the nearest error boundary to the sender element and make it show an error\n * @param {*} sender The element that sends the error\n * @param {*} error Error or string, the error to show\n */\n static showError(sender, error) {\n if (!error) throw new Error('ErrorBoundary.showError: expected two arguments but got one');\n const boundary = sender.closest('x-error-boundary');\n if (boundary) {\n boundary.error = error;\n } else {\n console.error('unable to find x-error-boundary to show error');\n console.error(error);\n }\n }\n\n #error;\n #errorSlot;\n #contentSlot;\n\n get error() {\n return this.#error;\n }\n\n set error(error) {\n if (!this.#errorSlot) return;\n this.#error = error;\n this.#errorSlot.style.display = error ? 'contents' : 'none';\n this.#contentSlot.style.display = !error ? 'contents' : 'none';\n if (error) {\n this.#errorSlot.assignedElements().forEach(element => {\n if (Object.hasOwn(element, 'error')) {\n element.error = error;\n } else {\n element.setAttribute('error', error?.message || error);\n }\n });\n this.dispatchEvent(new CustomEvent('error', { detail: error }));\n }\n }\n\n constructor() {\n super();\n this.attachShadow({ mode: 'open' });\n\n this.#errorSlot = document.createElement('slot');\n this.#errorSlot.style.display = 'none';\n this.#errorSlot.name = 'error';\n // default error message\n this.#errorSlot.textContent = 'Something went wrong.';\n this.#contentSlot = document.createElement('slot');\n this.shadowRoot.append(this.#errorSlot, this.#contentSlot);\n }\n\n reset() {\n this.error = null;\n }\n\n connectedCallback() {\n this.style.display = 'contents';\n }\n}\n\nexport const registerErrorBoundary = () => customElements.define('x-error-boundary', ErrorBoundary);\n"
},
{
"path": "public/blog/articles/2024-09-09-sweet-suspense/example/components/error-message.js",
"content": "class ErrorMessage extends HTMLElement {\n connectedCallback() {\n this.update();\n }\n\n static get observedAttributes() {\n return ['error'];\n }\n \n attributeChangedCallback() {\n this.update();\n }\n \n update() {\n const errorMsg = this.getAttribute('error') || '';\n this.textContent = errorMsg;\n }\n}\n\nexport const registerErrorMessage = () => customElements.define('x-error-message', ErrorMessage);\n"
},
{
"path": "public/blog/articles/2024-09-09-sweet-suspense/example/components/hello-world/hello-world.js",
"content": "import { Suspense } from '../suspense.js';\nimport { later } from './later.js';\n\nclass HelloWorldComponent extends HTMLElement {\n connectedCallback() {\n this.innerHTML = `\n
Hello world!
\n \n \n `;\n const btnLoad = this.querySelector('button#load');\n btnLoad.onclick = () => {\n // simulate loading of data\n Suspense.waitFor(this, later(1000));\n };\n const btnError = this.querySelector('button#error');\n btnError.onclick = () => {\n // simulate loading of data that ends in an error\n Suspense.waitFor(this, later(1000).then(() => { throw new Error('An error, as expected.'); }));\n }\n }\n}\n\nexport default function register() {\n customElements.define('x-hello-world', HelloWorldComponent);\n}\n"
},
{
"path": "public/blog/articles/2024-09-09-sweet-suspense/example/components/hello-world/later.js",
"content": "export function later(delay) {\n return new Promise(function(resolve) {\n setTimeout(resolve, delay);\n });\n}"
},
{
"path": "public/blog/articles/2024-09-09-sweet-suspense/example/components/lazy.js",
"content": "import { Suspense } from './suspense.js';\n\n/**\n * A vanilla version of React's lazy() function\n * inspired by https://css-tricks.com/an-approach-to-lazy-loading-custom-elements/\n * \n * Usage: \n * \n * Will load default function from ./components//.js and execute it.\n * Only direct children are lazy-loaded, and only on initial DOM insert.\n * \n * Pass the root attribute to modify the path to load relative to the current document.\n * \n * \n * Put the lazy-path attribute on a custom element to specify the path to the JS file to load.\n * \n * @license MIT\n */\nclass Lazy extends HTMLElement {\n connectedCallback() {\n this.style.display = 'contents';\n this.#loadLazy();\n }\n\n /**\n * Find direct child custom elements that need loading, then load them\n */\n #loadLazy() {\n const elements = \n [...this.children].filter(_ => _.localName.includes('-'));\n const unregistered = \n elements.filter(_ => !customElements.get(_.localName));\n if (unregistered.length) {\n Suspense.waitFor(this, \n ...unregistered.map(_ => this.#loadElement(_))\n ); \n }\n }\n\n /**\n * Load a custom element\n * @param {*} element \n * @returns {Promise} a promise that settles when loading completes or fails\n */\n #loadElement(element) {\n // does the element advertise its own path?\n let url = element.getAttribute('lazy-path');\n if (!url) {\n // strip leading x- off the name\n const cleanName = element.localName.replace(/^x-/, '').toLowerCase();\n // root directory to load from, relative to current document\n const rootDir = this.getAttribute('root') || './components/';\n // assume component is in its own folder\n url = `${rootDir}${cleanName}/${cleanName}.js`;\n }\n // dynamically import, then register if not yet registered\n return import(new URL(url, document.location)).then(module => \n !customElements.get(element.localName) && module && module.default());\n }\n}\n\nexport const registerLazy = () => customElements.define('x-lazy', Lazy);\n"
},
{
"path": "public/blog/articles/2024-09-09-sweet-suspense/example/components/suspense.js",
"content": "import { ErrorBoundary } from './error-boundary.js';\n\n/**\n * A vanilla version of React's Suspense\n * \n * Usage:\n * \n * \n *
Loading...
\n *
\n * While it loads it shows the fallback:\n * \n *
\n * \n * \n * @license MIT\n */\nexport class Suspense extends HTMLElement {\n\n /**\n * Find the nearest suspense to the sender element and make it wait for the promises to complete.\n * @param {*} sender The element that sends the promise\n * @param {...Promise} promises \n */\n static waitFor(sender, ...promises) {\n const suspense = sender.closest('x-suspense');\n if (suspense) suspense.addPromises(...promises);\n }\n\n #fallbackSlot;\n #contentSlot;\n #waitingForPromise;\n\n set #loading(isLoading) {\n if (!this.#fallbackSlot) return;\n this.#fallbackSlot.style.display = isLoading ? 'contents' : 'none';\n this.#contentSlot.style.display = !isLoading ? 'contents' : 'none';\n }\n\n constructor() {\n super();\n this.attachShadow({ mode: 'open' });\n\n this.#fallbackSlot = document.createElement('slot');\n this.#fallbackSlot.style.display = 'none';\n this.#fallbackSlot.name = 'fallback';\n this.#contentSlot = document.createElement('slot');\n this.shadowRoot.append(this.#fallbackSlot, this.#contentSlot);\n }\n\n connectedCallback() {\n this.style.display = 'contents';\n }\n\n /**\n * Wait for one or more promises to settle, showing fallback content\n * @param {...Promise} promises \n */\n addPromises(...promises) {\n if (!promises.length) return;\n this.#loading = true;\n // combine into previous promises if there are any\n const newPromise = this.#waitingForPromise = \n Promise.allSettled([...promises, this.#waitingForPromise]);\n // wait for all promises to complete\n newPromise.then(settled => {\n // if no more promises were added, we're done\n if (newPromise === this.#waitingForPromise) {\n this.#loading = false;\n // if a promise failed, show an error\n const failed = settled.find(_ => _.status === 'rejected');\n if (failed) ErrorBoundary.showError(this, failed.reason);\n }\n });\n }\n}\n\nexport const registerSuspense = () => customElements.define('x-suspense', Suspense);\n"
},
{
"path": "public/blog/articles/2024-09-09-sweet-suspense/example/index.html",
"content": "\n\n \n Lazy, Suspense and Error Boundary example\n \n \n \n \n \n \n \n"
},
{
"path": "public/blog/articles/2024-09-09-sweet-suspense/example/index.js",
"content": "import { registerLazy } from './components/lazy.js';\nimport { registerSuspense } from './components/suspense.js';\nimport { registerErrorBoundary } from './components/error-boundary.js';\nimport { registerErrorMessage } from './components/error-message.js';\n\ncustomElements.define('x-demo', class extends HTMLElement {\n\n constructor() {\n super();\n registerLazy();\n registerSuspense();\n registerErrorBoundary();\n registerErrorMessage();\n }\n\n connectedCallback() {\n this.innerHTML = `\n
\n I was reading Addy Osmani and Hassan Djirdeh's book Building Large Scale Web Apps.\n (Which, by the way, I can definitely recommend.) In it they cover all the ways to make a React app sing at scale.\n The chapter on Modularity was especially interesting to me, because JavaScript modules\n are a common approach to modularity in both React and vanilla web code.\n
\n
\n In that chapter on Modularity there was one particular topic that caught my eye,\n and it was the use of lazy() and Suspense, paired with an ErrorBoundary.\n These are the primitives that React gives us to asynchronously load UI components and their data on-demand while showing a fallback UI,\n and replace the UI with an error message when something goes wrong.\n If you're not familiar, here's a good overview page.\n
\n
\n It was at that time that I was visited by the imp of the perverse, which posed to me a simple challenge:\n can you bring React's lazy loading primitives to vanilla web components?\n To be clear, there are many \n ways to \n load web components \n lazily. \n This is well-trodden territory. What wasn't out there was a straight port of lazy, suspense and error boundary. \n The idea would not let me go. So here goes nothing.\n
\n\n
Lazy
\n\n
\n The idea and execution of React's lazy is simple. Whenever you want to use a component in your code,\n but you don't want to actually fetch its code yet until it needs to be rendered, wrap it using the lazy() function: \n const MarkdownPreview = lazy(() => import('./MarkdownPreview.js')); \n
\n
\n React will automatically \"suspend\" rendering when it first bumps into this lazy component until the component has loaded, and then continue automatically.\n
\n
\n This works in React because the markup of a component only looks like HTML, \n but is actually JavaScript in disguise, better known as JSX.\n With web components however, the markup that the component is used in is actually HTML,\n where there is no import() and no calling of functions.\n That means our vanilla lazy cannot be a JavaScript function, but instead it must be an HTML custom element: \n <x-lazy><x-hello-world></x-hello-world></x-lazy>\n
\n\n
\n The basic setup is simple, when the lazy component is added to the DOM,\n we'll scan for children that have a '-' in the name and therefore are custom elements,\n see if they're not yet defined, and load and define them if so.\n By using display: contents we can avoid having the <x-lazy> impact layout.\n
\n \n\n
\n To actually load the element, we'll have to first find the JS file to import, and then run its register function.\n 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.\n The following code uses a heuristic that assumes components are in a ./components/ subfolder of the current document\n and follow a consistent file naming scheme:\n
\n \n\n
\n One could get a lot more creative however, and for example use an \n import map \n to map module names to files. This I leave as an exercise for the reader.\n
\n\n
Suspense
\n\n
\n While the lazy component is loading, we can't show it yet. This is true for custom elements just as much as for React.\n That means we need a wrapper component that will show a fallback UI as long as any components in its subtree are loading,\n the <x-suspense> component. This starts out as a tale of two slots. When the suspense element is loading it shows the fallback, otherwise the content.\n
\n\n \n \n\n
\n The trick now is, how to we get loading = true to happen?\n In Plain Vanilla's applications page I showed how a React context can be simulated using the element.closest() API.\n We can use the same mechanism to create a generic API that will let our suspense wait on a promise to complete.\n
\n\n \n\n
\n Suspense.waitFor will call the nearest ancestor <x-suspense>\n to a given element, and give it a set of promises that it should wait on.\n This API can then be called from our <x-lazy> component.\n Note that #loadElement returns a promise that completes when the custom element is loaded or fails to load.\n
\n \n
\n The nice thing about the promise-based approach is that we can give it any promise, just like we would with React's suspense.\n For example, when loading data in a custom element that is in the suspense's subtree, we can call the exact same API: \n Suspense.waitFor(this, fetch(url).then(...))\n
\n\n
Error boundary
\n\n
\n Up to this point, we've been assuming everything always works. This is Spartasoftware, it will never \"always work\".\n What we need is a graceful way to intercept failed promises that are monitored by the suspense,\n and show an error message instead. That is the role that React's error boundary plays.\n
\n
\n The approach is similar to suspense:\n
\n \n
\n And the code is also quite similar to suspense:\n
\n \n\n
\n Similar to suspense, this has an API ErrorBoundary.showError() that can be called\n from anywhere inside the error boundary's subtree to show an error that occurs.\n The suspense component is then modified to call this API when it bumps into a rejected promise.\n To hide the error, the reset() method can be called on the error boundary element.\n
\n
\n Finally, the error setter will set the error as a property or attribute\n on all children in the error slot, which enables customizing the error message's behavior based on the error object's properties\n by creating a custom <x-error-message> component.\n
\n\n
Conclusion
\n\n
\n Finally, we can bring all of this together in a single example,\n that combines lazy, suspense, error boundary, a customized error message, and a lazy-loaded hello-world component.\n
\n\n \n \n\n
\n For the complete example's code, as well as the lazy, suspense and error-boundary components,\n check out the sweet-suspense repo on Github.\n
\n \n \n \n\n"
},
{
"path": "public/blog/articles/2024-09-09-sweet-suspense/lazy1.js",
"content": "customElements.define('x-lazy', class extends HTMLElement {\n connectedCallback() {\n this.style.display = 'contents';\n this.#loadLazy();\n }\n\n #loadLazy() {\n const elements = \n [...this.children].filter(_ => _.localName.includes('-'));\n const unregistered = \n elements.filter(_ => !customElements.get(_.localName));\n unregistered.forEach(_ => this.#loadElement(_));\n }\n\n #loadElement(element) {\n // TODO: load the custom element\n }\n});\n"
},
{
"path": "public/blog/articles/2024-09-09-sweet-suspense/lazy2-partial.js",
"content": " #loadElement(element) {\n // strip leading x- off the name\n const cleanName = element.localName.replace(/^x-/, '').toLowerCase();\n // assume component is in its own folder\n const url = `./components/${cleanName}/${cleanName}.js`;\n // dynamically import, then register if not yet registered\n return import(new URL(url, document.location)).then(module => \n !customElements.get(element.localName) && module && module.default());\n }"
},
{
"path": "public/blog/articles/2024-09-09-sweet-suspense/lazy3-partial.js",
"content": " #loadLazy() {\n const elements = \n [...this.children].filter(_ => _.localName.includes('-'));\n const unregistered = \n elements.filter(_ => !customElements.get(_.localName));\n if (unregistered.length) {\n Suspense.waitFor(this, \n ...unregistered.map(_ => this.#loadElement(_))\n );\n }\n }"
},
{
"path": "public/blog/articles/2024-09-09-sweet-suspense/suspense1-partial.html",
"content": "\n
Loading...
\n \n"
},
{
"path": "public/blog/articles/2024-09-09-sweet-suspense/suspense1.js",
"content": "export class Suspense extends HTMLElement {\n #fallbackSlot;\n #contentSlot;\n\n set loading(isLoading) {\n if (!this.#fallbackSlot) return;\n this.#fallbackSlot.style.display = isLoading ? 'contents' : 'none';\n this.#contentSlot.style.display = !isLoading ? 'contents' : 'none';\n }\n\n constructor() {\n super();\n this.attachShadow({ mode: 'open' });\n\n this.#fallbackSlot = document.createElement('slot');\n this.#fallbackSlot.style.display = 'none';\n this.#fallbackSlot.name = 'fallback';\n this.#contentSlot = document.createElement('slot');\n this.shadowRoot.append(this.#fallbackSlot, this.#contentSlot);\n }\n\n connectedCallback() {\n this.style.display = 'contents';\n }\n}\ncustomElements.define('x-suspense', Suspense);"
},
{
"path": "public/blog/articles/2024-09-09-sweet-suspense/suspense2-partial.js",
"content": " static waitFor(sender, ...promises) {\n const suspense = sender.closest('x-suspense');\n if (suspense) suspense.addPromises(...promises);\n }\n\n addPromises(...promises) {\n if (!promises.length) return;\n this.loading = true;\n // combine into previous promises if there are any\n const newPromise = this.#waitingForPromise = \n Promise.allSettled([...promises, this.#waitingForPromise]);\n // wait for all promises to complete\n newPromise.then(_ => {\n // if no newer promises were added, we're done\n if (newPromise === this.#waitingForPromise) {\n this.loading = false;\n }\n });\n }"
},
{
"path": "public/blog/articles/2024-09-16-life-and-times-of-a-custom-element/defined/example.html",
"content": "\n\n \n \n defining the custom element\n \n \n \n
\n\n \n \n"
},
{
"path": "public/blog/articles/2024-09-16-life-and-times-of-a-custom-element/index.html",
"content": "\n\n\n The life and times of a web component\n \n \n \n\n\n \n \n
The life and times of a web component
\n
Joeri Sebrechts
\n \n \n
\n When first taught about the wave-particle duality of light most people's brains does a double take.\n How can light be two different categories of things at the same time, both a wave and a particle? That's just weird.\n The same thing happens with web components, confusing people when they first try to learn them and run into their Document-JavaScript duality.\n The component systems in frameworks are typically JavaScript-first, only using the DOM as an outlet for their visual appearance.\n Web components however — or custom elements to be precise — can start out in either JavaScript or the document, and are married to neither.\n
\n\n
Just the DOM please
\n\n
\n Do you want to see the minimal JavaScript code needed to set up an <x-example> custom element?\n Here it is:\n
\n
\n
\n No, that's not a typo. Custom elements can be used just fine without any JavaScript.\n Consider this example of an <x-tooltip> custom element that is HTML and CSS only:\n
\n \n \n
\n For the curious, here is the example.css, but it is not important here.\n
\n
\n Such elements are called undefined custom elements.\n Before custom elements are defined in the window by calling customElements.define() they always start out in this state.\n There is no need to actually define the custom element if it can be solved in a pure CSS way.\n In fact, many \"pure CSS\" components found online can be solved by such custom elements,\n by styling the element itself and its ::before and ::after pseudo-elements.\n
\n\n
A question of definition
\n\n
\n The CSS-only representation of the custom element can be progressively enhanced by connecting it up to a JavaScript counterpart,\n a custom element class. This is a class that inherits from HTMLElement and allows the custom element\n to implement its own logic.\n
\n \n \n
\n What happens to the elements already in the markup at the moment customElements.define()\n is called is an element upgrade. The browser will take all custom elements already in the document,\n and create an instance of the matching custom element class that it connects them to.\n 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.\n
\n
\n Element upgrades occur for existing custom elements in the document when customElements.define() is called,\n and for all new custom elements with that tag name created afterwards (e.g. using document.createElement('x-example')).\n It does not occur automatically for detached custom elements (not part of the document) that were created before the element was defined.\n Those can be upgraded retroactively by calling customElements.upgrade().\n
\n\n
\n So far, this is the part of the lifecycle we've seen:\n
\n The constructor as shown in the example above is optional, but if it is specified then it has a number of gotcha's:\n
\n
\n
It must start with a call to super().
\n
It should not make DOM changes yet, as the element is not yet guaranteed to be connected to the DOM.
\n
\n This includes reading or modifying its own DOM properties, like its attributes.\n The tricky part is that in the constructor the element might already be in the DOM,\n so setting attributes might work. Or it might give an error. It's best to avoid DOM interaction altogether in the constructor.\n
\n
It should initialize its state, like class properties
\n
\n But work done in the constructor should be minimized and maximally postponed until connectedCallback.\n
\n
\n\n
Making connections
\n\n
\n After being constructed, if the element was already in the document, its connectedCallback() handler is called.\n 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.\n In this handler DOM changes can be made, and in the example above the status attribute is set to demonstrate this.\n
\n
\n The connectedCallback() handler is part of what is known in the HTML standard as custom element reactions:\n These reactions allow the element to respond to various changes to the DOM:\n
\n
\n
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.
\n
disconnectedCallback() is called when the element is removed from the document.
\n
adoptedCallback() is called when the element is moved to a new document. (You are unlikely to need this in practice.)
\n
attributeChangedCallback() is called when an attribute is changed, but only for the attributes listed in its observedAttributes property.
\n
\n
\n There are also special reactions for form-associated custom elements, \n but those are a rabbit hole beyond the purview of this blog post.\n
\n
\n There are more gotcha's to these reactions:\n
\n
\n
connectedCallback() and disconnectedCallback() can be called multiple times
\n
\n This can occur when the element is moved around in the document.\n These handlers should be written in such a way that it is harmless to run them multiple times,\n e.g. by doing an early exit when it is detected that connectedCallback() was already run.\n
\n
attributeChangedCallback() can be called before connectedCallback()
\n
\n For all attributes already set when the element in the document is upgraded,\n the attributeChangedCallback() handler will be called first,\n and only after this connectedCallback() is called.\n The unpleasant consequence is that any attributeChangedCallback that tries to update DOM structures\n created in connectedCallback can produce errors.\n
\n
attributeChangedCallback() is only called for attribute changes, not property changes.
\n
\n Attribute changes can be done in Javascript by calling element.setAttribute('name', 'value').\n DOM attributes and class properties can have the same name, but are not automatically linked.\n Generally for this reason it is better to avoid having attributes and properties with the same name.\n
\n
\n\n
\n The lifecycle covered up to this point for elements that start out in the initial document:\n
\n So far we've covered one half of the Document-JavaScript duality, for custom elements starting out in the document,\n and only after that becoming defined and gaining a JavaScript counterpart.\n It is however also possible to reverse the flow, and start out from JavaScript.\n
\n
\n This is the minimal code to create a custom element in JavaScript: document.createElement('x-example').\n 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\n as if it was part of the original HTML markup.\n
\n
\n If it is inserted, and after insertion the element becomes defined, then it will behave as described above.\n Things are however different if the element remains detached:\n
\n
\n
The detached element will not be automatically upgraded when it is defined.
\n
\n The constructor or reactions will not be called. It will be automatically upgraded when it is inserted into the document.\n It can also be upgraded explicitly by calling customElements.upgrade().\n
\n
If the detached element is already defined when it is created, it will be upgraded automatically.
\n
The constructor() and attributeChangedCallback() will be called. Because it is not yet part of the document connectedCallback() won't be.
\n
\n
\n By now no doubt you are a bit confused. Here's an interactive playground that lets you test\n what happens to elements as they go through their lifecycle, both for those in the initial document and those created dynamically.\n
\n \n\n
Here are some interesting things to try out:
\n
\n
Create, then Define, and you will see that the created element is not upgraded automatically because it is detached from the document.
\n
Create, then Connect, then Define, and you will see that the element is upgraded automatically because it is in the document.
\n
Define, then Create, and you will see that the element is upgraded as soon as it is created (constructed appears in the reactions).
\n
\n
\n I tried writing a flowchart of all possible paths through the lifecycle that can be seen in this example,\n but it got so unwieldy that I think it's better to just play around with the example until a solid grasp develops.\n
\n\n
In the shadows
\n\n
\n Adding shadow DOM creates yet another wrinkle in the lifecycle.\n 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().\n Because the shadow DOM is immediately available for DOM operations, that makes it possible to do those DOM operations in the constructor.\n
\n
\n In this next interactive example you can see what happens when the shadow DOM becomes attached.\n The x-shadowed element will immediately attach a shadow DOM in its constructor,\n which happens when the element is upgraded automatically after defining.\n The x-shadowed-later element postpones adding a shadow DOM until a link is clicked,\n so the element first starts out as a non-shadowed custom element, and adds a shadow DOM later.\n
\n\n \n \n\n
\n While adding a shadow DOM can be done at any point, it is a one-way operation.\n Once added the shadow DOM will replace the element's original contents, and this cannot be undone.\n
\n\n
Keeping an eye out
\n\n
\n So far we've mostly been dealing with initial setup of the custom element,\n but a major part of the lifecycle is responding to changes as they occur.\n Here are some of the major ways that custom elements can respond to DOM changes:\n
\n
\n
connectedCallback and disconnectedCallback to handle DOM insert and remove of the element itself.
\n
attributeChangedCallback to handle attribute changes of the element.
\n
For shadowed custom elements, the slotchange event can be used to detect when children are added and removed in a <slot>.
\n
Saving the best for last, MutationObserver can be used to monitor DOM subtree changes, as well as attribute changes.
\n
\n
\n MutationObserver in particular is worth exploring, because it is a swiss army knife for monitoring the DOM.\n Here's an example of a counter that automatically updates when new child elements are added:\n
\n \n \n\n
\n There is still more to tell, but already I can feel eyes glazing over and brains turning to mush,\n so I will keep the rest for another day.\n
\n\n \n\n
\n Phew, that was a much longer story than I originally set out to write, but custom elements have surprising intricacy.\n I hope you found it useful, and if not at least you got to see some code and click some buttons.\n It's all about the clicking of the buttons.\n
\n I have a confession to make. At the end of the Plain Vanilla tutorial's Applications page\n a challenge was posed to the reader: port react.dev's final example \n Scaling Up with Reducer and Context to vanilla web code.\n Here's the confession: until today I had never actually ported over that example myself.\n
\n
\n That example demonstrates a cornucopia of React's featureset.\n Richly interactive UI showing a tasks application, making use of a context to lift the task state up,\n and a reducer that the UI's controls dispatch to. React's DOM-diffing algorithm gets a real workout \n because each task in the list can be edited independently from and concurrently with the other tasks. \n It is an intricate and impressive demonstration. Here it is in its interactive glory:\n
\n \n
\n But I lied. That interactive example is actually the vanilla version and it is identical.\n If you want to verify that it is in fact identical, check out the original React example.\n And with that out of the way, let's break apart the vanilla code.\n
\n\n
Project setup
\n\n
The React version has these code files that we will need to port:
\n
\n
public/index.html
\n
src/styles.css
\n
src/index.js: imports the styles, bootstraps React and renders the App component
\n
src/App.js: renders the context's TasksProvider containing the AddTask and TaskList components
\n
src/AddTask.js: renders the simple form at the top to add a new task
\n
src/TaskList.js: renders the list of tasks
\n
\n
\n To make things fun, I chose the same set of files with the same filenames for the vanilla version.\n Here's index.html:\n
\n \n
\n The only real difference is that it links to index.js and styles.css.\n The stylesheet was copied verbatim, but for the curious here's a link to styles.css.\n
\n \n
Get to the code
\n\n
\n index.js is where it starts to get interesting.\n Compare the React version to the vanilla version:\n
\n \n \n
\n Bootstrapping is different but also similar. All of the web components are imported first to load them,\n and then the <tasks-app> component is rendered to the page.\n
\n
\n The App.js code also bears more than a striking resemblance:\n
\n \n \n\n
\n What I like about the code so far is that it feels React-like. I generally find programming against React's API pleasing,\n but I don't like the tooling, page weight and overall complexity baggage that it comes with.\n
\n\n
Adding context
\n\n
\n The broad outline of how to bring a React-like context to a vanilla web application is\n already explained in the passing data deeply section \n of the main Plain Vanilla tutorial, so I won't cover that again here.\n What adds spice in this specific case is that the React context uses a reducer,\n a function that accepts the old tasks and an action to apply to them, and returns the new tasks to show throughout the application.\n
\n
\n Thankfully, the React example's reducer function and initial state were already vanilla JS code,\n so those come along for the ride unchanged and ultimately the vanilla context is a very straightforward custom element:\n
\n\n \n\n
\n The actual context component is very bare bones, as it only needs to store the tasks,\n emit change events for the other components to subscribe to, and provide a dispatch method \n for those components to call that will use the reducer function to update the tasks.\n
\n\n
Adding tasks
\n\n
\n The AddTask component ends up offering more of a challenge. It's a stateful component with event listeners that dispatches to the reducer:\n
\n \n
\n The main wrinkle this adds for the vanilla web component is that the event listener on the button element\n cannot be put inline with the markup. Luckily the handling of the input is much simplified\n because we can rely on it keeping its state automatically, a convenience owed to not using a virtual DOM.\n Thanks to the groundwork in the context component the actual dispatching of the action is easy:\n
\n \n
\n Fascinating to me is that index.js, App.js, TasksContext.js and AddTask.js\n are all fewer lines of code in the vanilla version than their React counterpart while remaining functionally equivalent. \n
\n\n
Hard mode
\n
\n The TaskList component is where React starts really pulling its weight.\n The React version is clean and straightforward and juggles a lot of state with a constantly updating task list UI.\n
\n \n\n
\n This proved to be a real challenge to port. The vanilla version ended up being a lot more verbose\n because it has to do all the same DOM-reconciliation in explicit logic managed by the update() methods\n of <task-list> and <task-item>.\n
\n \n
\n Some interesting take-aways:\n
\n
\n
\n The <task-list> component's update() method implements a poor man's version of React reconciliation,\n merging the current state of the tasks array into the child nodes of the <ul>.\n In order to do this, it has to store a key on each list item, just like React requires, and here it becomes obvious why that is.\n Without the key we can't find the existing <li> nodes that match up to task items,\n and so would have to recreate the entire list. By adding the key it becomes possible to update the list in-place,\n modifying task items instead of recreating them so that they can keep their on-going edit state.\n
\n
\n That reconciliation code is very generic however, and it is easy to imagine a fully generic repeat()\n function that converts an array of data to markup on the page. In fact, the Lit framework contains exactly that.\n For brevity's sake this code doesn't go quite that far.\n
\n
\n The <task-item> component cannot do what the React code does: create different markup depending on the current state.\n Instead it creates the union of the markup across the various states, and then in the update()\n shows the right subset of elements based on the current state.\n
\n A peculiar result of this porting challenge is that the vanilla version ends up being roughly \n the same number of lines of code as the React version. The React code is still overall less verbose (all those querySelectors, oy!),\n but it has its own share of boilerplate that disappears in the vanilla version.\n This isn't a diss against React, it's more of a compliment to how capable browsers have gotten that vanilla web components\n can carry us so far.\n
\n
\n If I could have waved a magic wand, what would have made the vanilla version simpler?\n
\n
\n
\n All of those querySelector calls get annoying. The alternatives are building the markup easily with innerHTML\n and then fishing out references to the created elements using querySelector, or building the elements one by one verbosely using createElement,\n but then easily having a reference to them. Either of those ends up very verbose. \n An alternative templating approach that makes it easy to create elements and get a reference to them would be very welcome.\n
\n
\n As long as we're dreaming, I'm jealous of how easy it is to add the event listeners in JSX.\n A real expression language in HTML templates that supports data and event binding and data-conditional markup would be very neat\n and would take away most of the reason to still find a framework's templating language more convenient.\n Web components are a perfectly fine alternative to React components, they just lack an easy built-in templating mechanism.\n
\n
\n Browsers could get a little smarter about how they handle DOM updates during event handling.\n In the logic that sorts the <li> to the right order in the list, \n the if condition before insertBefore proved necessary because the browser\n didn't notice that the element was already placed where it needed to be inserted,\n and click events would get lost as a consequence.\n I've even noticed that assigning a textContent to a button mid-click will make Safari\n lose track of that button's click event. All of that can be worked around with clever reconciliation logic,\n but that's code that belongs in the browser, not in JavaScript.\n
\n
\n
\n All in all though, I'm really impressed with vanilla JS. I call it unreasonably effective because it is\n jarring just how capable the built-in abilities of browsers are, and just how many web developers despite that \n still default to web frameworks for every new project. Maybe one day...\n
\n Ryan Carniato shared a hot take a few days ago, Web Components Are Not the Future.\n As hot takes tend to do, it got some responses, like Nolan Lawson's piece Web components are okay,\n or Cory LaViska's Web Components Are Not the Future — They're the Present.\n They do an excellent job of directly engaging Ryan's arguments, so I'm not going to do that here.\n Instead I want to talk about my lived experience of web development, and where I hope it is headed in the future.\n Take it in the spirit it is intended, one of optimism and possibility.\n
\n\n
A galaxy far, far away
\n
\n So I've been making web sites since a long time ago, since before CSS and HTML4.\n I say this not to humblebrag, but to explain that I was here for all of it.\n Every time when the definition of modern web development changed I would update my priors, following along.\n
\n
\n For the longest time making web pages do anything except show text and images was an exercise in frustration.\n Browsers were severely lacking in features, were wildly incompatible with web standards and each other,\n and the tools that web developers needed to bring them to order were missing or lacking.\n I built my share of vanilla JS components back in the IE6 days, and it made me dream of a better way.\n When frameworks first started coming on the scene with that better way, adding missing features, abstracting away incompatibility,\n and providing better tooling, I was ready for them. I was all-in.\n
\n
\n 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\n 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.\n 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.\n I helped rewrite a bunch of frontends in Angular v2 and React, \n and found myself sucked into constant forced maintenance when their architecture and ecosystems churned.\n
\n
\n Did I make bad choices? Even in hindsight I would say I picked the right choices for the time.\n Time just moved on.\n
\n\n
The cost of change
\n
\n This lived experience taught me a strong awareness of rates of change in dependencies, and the costs they impose.\n I imagine a web page as a thin old man sitting astride a tall pile of dependencies, each changing at their own pace.\n Some dependencies are stable for decades, like HTML's core set of elements, or CSS 2's set of layout primitives. \n They're so stable that we don't even consider them dependencies, they're just the web.\n
\n
\n Other dependencies change every few years, like module systems, or new transpiled languages, \n or the preferred build and bundling tool of the day, or what framework is in vogue.\n Then there are the dependencies that change yearly, like major framework and OS releases.\n Finally there are the dependencies that change constantly, like the many packages that contribute\n to a typical web application built with a popular framework.\n
\n
\n As a web developer who loves their user, taking on those dependencies creates a Solomon's choice.\n Either you keep up with the churn, and spend a not insignificant amount of your day working and reworking code\n that already works, instead of working on the things your user cares about. \n Or, you stick it out for as long as you can on old versions, applying ever more workarounds to get \n old framework releases and their outdated build and CLI tools to work in new OS and ecosystem environments,\n slowly boiling a frog that will at some point force a deep rewrite, again at the expense of the user.\n
\n
\n Which is not to say the frameworks don't add value. They absolutely do, and they keep getting better. \n Writing new code on a new framework is a steadily rising tide of developer experience. \n But let us not pretend these benefits don't come at a cost.\n Wherever there is a codebase too complicated to understand and maintain yourself, wherever there is a set of build tools \n that must be kept compatible with changes in operating systems and ecosystems,\n there is a shelf life. Sooner or later the makers of every framework and of every tool will move on,\n 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.\n
\n
\n I hold this truth to be self-evident: the larger the abstraction layer a web developer uses on top of web standards,\n the shorter the shelf life of their codebase becomes, and the more they will feel the churn.\n
\n\n
The rising tide
\n
\n Why do modern web projects built with modern frameworks depend on so much stuff?\n At first there was no other option. Interacting with the DOM was painful, \n and web frameworks rightly made choices to keep component systems outside the DOM, minimizing and abstracting away those interactions\n in increasingly clever DOM reconciliation strategies. Supporting the brittle browsers and slow devices of the day required many workarounds and polyfills,\n and web frameworks rightly added intricate tools to build, bundle and minify the user's code.\n
\n
\n They needed a way to bring dependencies into those build systems, and sanely settled on the convention of node modules\n and the NPM ecosystem. It got easy to add more dependencies, and just as water always finds the easy way down,\n dependencies found the easy way in. As the abstraction layer grew the load time cost imposed by it grew right along,\n and so we got server-side rendering, client-side hydration, lazy loading, and many other load time reduction strategies.\n
\n
\n DOM-diffing, synthetic event systems, functional components, JSX, reactive data layers, server-side rendering and streaming, bundlers, tree shaking, \n 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 —\n 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.\n And all of those things are downstream from the decision to abstract away the browser,\n a decision once made in good faith and for good reasons. A decision which now needs revisiting.\n
\n
\n Browsers were not standing still. They saw what web developers were doing in userland to compensate \n 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.\n When Microsoft bid IE a well-deserved farewell on June 15, 2022 a tipping point was reached.\n 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.\n It wasn't a great platform, not as cleanly designed or complete as the API's of the popular frameworks,\n but it was Good Enough™ as a foundation, and that was all that mattered.\n
\n\n
Holding my breath
\n\n
\n I was very excited for what would happen in the framework ecosystem. There was a golden opportunity for frameworks \n to tear down their abstraction layers, make something far simpler, far more closely aligned with the base web platform. \n They could have a component system built on top of web components,\n leveraging browser events and built-in DOM API's. All the frameworks could become cross-compatible, \n easily plugging into each other's data layers and components while preserving what makes them unique.\n The page weights would shrink by an order of magnitude with so much infrastructure code removed,\n and that in combination with the move to HTTP/3 could make build tools optional.\n It would do less, so inevitably be worse in some ways, but sometimes worse is better.\n
\n
\n I gave a talk about how good the browser's platform had gotten, \n showing off a version of Create React App that didn't need any build tools\n and was extremely light-weight, and the developer audience was just as excited as I was.\n And I held my breath waiting on framework churn to for once go in the other direction, towards simplicity...\n
\n
\n But nothing happened. In fact, the major frameworks kept building up their abstraction layers instead of building down.\n We got React Server Components and React Compiler, exceedingly clever, utterly incomprehensible, \n workarounds for self-imposed problems caused by overengineering.\n Web developers don't seem to mind, but they struggle quietly with how to keep up with these tools and deliver good user experiences. \n The bigger the abstraction layer gets, the more they feel the churn.\n
\n
\n The irony is not lost on me that now the framework authors also feel the churn in their dependencies,\n struggling to adapt to web components as foundational technology. React 19 is supposed to finally support web components\n in a way that isn't incredibly painful, or so they say, we'll see. I confess to feeling some satisfaction\n in their struggle. The shoe is on the other foot. Welcome to modern web development.\n
\n \n
The road ahead
\n\n
\n What the frameworks are doing, that's fine for them, and they can keep doing it. \n But I'm done with all that unless someone is paying me to do it.\n They're on a fundamentally different path from where I want web development to go, from how I want to make web pages.\n The web is what ships to the browser. Reducing the distance between what the developer writes and what ships to the browser\n is valuable and necessary. This blog and this site are my own stake in the ground for this idea, \n showing just how much you can get done without any framework code or build tools at all. \n But let's be honest: web components are not a framework, no matter how hard I tried to explain them as one.\n
\n\n
\n
Comparing web components to React is like comparing a good bicycle with a cybertruck.
\n
They do very different things, and they're used by different people with very, very different mindsets.
\n I want a motorbike, not a cybertruck. I still want frameworks, only much lighter. \n Frameworks less than 10 KB in size, that are a thin layer on top of web standards\n but still solve the problems that frameworks solve. I call this idea the interoperable web framework:\n
\n
\n
Its components are just web components.
\n
Its events are just DOM events.
\n
Its templates are just HTML templates.
\n
It doesn't need to own the DOM that its components take part in.
\n
Its data and event binding works on all HTML elements, built-in or custom, made with the framework or with something else.
\n
It can be easily mixed together on a page with other interoperable web frameworks, with older versions of itself, or with vanilla code.
\n
It doesn't need its own build tools.
\n
\n
\n I just feel it on my bones such a thing can be built now. Maybe I'm wrong and Ryan Carniato is right.\n 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.\n Some existing solutions like Lit are close, but none are precisely what I am looking for. \n I would love to see a community of vanilla developers come together to figure out what that could look like,\n running experiments and iterating on the results. For now I will just keep holding my breath, waiting for the tide to come in.\n
\n In the earlier article the unreasonable effectiveness of vanilla JS\n I explained a vanilla web version of the React tutorial example Scaling up with Reducer and Context.\n That example used a technique for context based on Element.closest().\n While that way of obtaining a context is very simple, which definitely has its merits,\n it also has some downsides:\n
\n
\n
It cannot be used from inside a shadow DOM to find a context that lives outside of it without clumsy workarounds.
\n
It requires a custom element to be the context.
\n
There has to be separate mechanism to subscribe to context updates.
\n
\n
\n There is in fact, or so I learned recently, a better and more standard way to solve this\n known as the context protocol. \n It's not a browser feature, but a protocol for how to implement a context in web components.\n
\n
\n This is how it works: the consumer starts by dispatching a context-request event.\n
\n \n
\n The event will travel up the DOM tree (bubbles = true), piercing any shadow DOM boundaries (composed = true),\n until it reaches a listener that responds to it. This listener is attached to the DOM by a context provider.\n The context provider uses the e.context property to detect whether it should respond,\n then calls e.callback with the appropriate context value.\n Finally it calls e.stopPropagation() so the event will stop bubbling up the DOM tree.\n
\n
\n This whole song and dance is guaranteed to happen synchronously, which enables this elegant pattern:\n
\n \n
\n If no provider is registered the event's callback is never called and the default value will be used instead.\n
\n
\n Instead of doing a one-off request for a context's value it's also possible to subscribe to updates\n by setting its subscribe property to true.\n Every time the context's value changes the callback will be called again.\n To ensure proper cleanup the subscribing element has to unsubscribe on disconnect.\n
\n \n
\n It is recommended, but not required, to listen for and call unsubscribe functions in one-off requests,\n just in case a provider is overzealously creating subscriptions.\n However, this is not necessary when using only spec-compliant providers.\n
\n \n
\n Providers are somewhat more involved to implement.\n There are several spec-compliant libraries that implement them,\n like @lit/context \n and wc-context.\n A very minimal implementation is this one:\n
\n \n
\n This minimal provider can then be used in a custom element like this:\n
\n \n
\n Which would be used on a page like this, with <my-subscriber> requesting \n the theme by dispatching a context-request event.\n
\n \n
\n Notice in the above example that the theme-toggle context is providing a function.\n This unlocks a capability for dependency injection where API's to control page behavior\n are provided by a context to any subscribing custom element.\n
\n
\n Don't let this example mislead you however. A provider doesn't actually need a dedicated custom element,\n and can be attached to any DOM node, even the body element itself.\n This means a context can be provided or consumed from anywhere on the page.\n
\n \n
\n And because there can be more than one event listener on a page,\n there can be more than one provider providing the same context.\n The first one to handle the event will win.\n
\n
\n Here's an example that illustrates a combination of a global provider attached to the body (top panel),\n and a local provider using a <theme-context> (bottom panel).\n Every time the <theme-toggle> is reparented it resubscribes to the theme from the nearest provider.\n
\n \n \n\n
\n The full implementation of this protocol can be found in the tiny-context repo on Github.\n
\n I'm typing this up in Visual Studio Code, after realizing I should probably explain how I use it to make this site.\n But the whole idea behind Plain Vanilla is no build, no framework, no tools.\n And VS Code is definitely a tool. So what gives?\n
\n
\n 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.\n The first category, like npm or typescript, impose continued maintenance on the project because they form a direct dependency.\n The second category, like VS Code or git, are easily replaced without impacting the project's ability to be edited.\n There's a tension between the ability to get things done faster, and the burden created by additional dependencies.\n For this project I draw the line in accepting the second category while rejecting the first.\n
\n
Setting up a profile
\n
\n I use VS Code for framework-based work projects as well as vanilla web development.\n To keep those two realms neatly separated I've set up a separate Vanilla profile. \n In that profile is a much leaner suite of extensions, configured for only vanilla web development.\n
\n
\n
ESLint, to automatically lint the JS code while editing
\n
webhint, to lint the HTML and CSS code, and detect accessibility issues
\n
html-in-template-string, to syntax highlight HTML template strings
\n
Todo Tree, to keep track of TODO's while doing larger changes
\n
Live Preview, to get a live preview of the page that I'm working on
\n
VS Code Counter, for quick comparative line counts when porting framework code to vanilla
\n
Intellicode, for simple code completion
\n
Codeium, for AI-assisted code completion, works great for web component boilerplate
\n
\n
\n Modern web development can be very overburdened by tools, sometimes all but requiring the latest Macbook Pro with decadent amounts of RAM\n just to edit a basic project. The combination of a no build plain vanilla codebase with a lean VS Code profile guarantees quick editing,\n even on my oldest and slowest laptops.\n
\n
Linting
\n
\n Nobody's perfect, myself included, so something needs to be scanning the code for goofs.\n The first linting tool that's set up is ESLint. The VS Code extension regrettably does not come bundled with an eslint installation,\n so this has to be installed explicitly. By doing it once globally this can be reused across vanilla web projects.\n
\n
npm install -g eslint @eslint/js globals
\n
\n Because I use nvm to manage node versions the global eslint install was not automatically detectable.\n This required setting a NODE_PATH in .zshrc that VS Code then picked up.\n
\n
export NODE_PATH=$(npm root -g)
\n
\n In addition, in order to lint successfully it needs a configuration file, located in the project's root.\n
\n \n
\n Setting the ecmaVersion to 2022 ensures that I don't accidentally use newer and unsupported Javascript features,\n like in this example trying to use ES2024's v flag in regular expressions.\n This version could be set to whatever browser compatibility a project requires.\n
\n \n
\n The ignores blocks excludes external libraries to placate my OCD that wants to see zero errors or warnings reported by eslint project-wide.\n The article folders are excluded for a similar reason, because they contain a lot of incomplete and deliberately invalid example JS files.\n
\n
\n The webhint extension is installed to do automatic linting on HTML and CSS.\n Luckily it out of the box comes bundled with a webhint installation and applies the default development ruleset.\n A nice thing about this extension is that it reports accessibility issues.\n
\n \n
\n Only a few tweaks were made to the webhint configuration to again get to that all-important zero warnings count.\n
\n \n\n
html-in-template-string
\n
\n I've mentioned it before in the entity encoding article,\n but this neat little extension formats HTML inside tagged template strings in web component JS code.\n
\n \n\n
Live Preview
\n
\n The center piece for a smooth editing workflow is the Live Preview extension.\n I can right-click on any HTML file in the project and select \"Show Preview\" to get a live preview of the page.\n This preview automatically refreshes when files are saved. Because vanilla web pages always load instantly\n this provides the hot-reloading workflow from framework projects, except even faster and with zero setup.\n The only gotcha is that all paths in the site have to be relative paths so the previewed page can resolve them.\n
\n \n
\n The preview's URL can be pasted into a \"real browser\" to debug tricky javascript issues\n and do compatibility testing. Very occasionally I'll need to spin up a \"real server\", \n but most of the code in my vanilla projects is written with only a Live Preview tab open.\n
\n
\n Previewing is also how I get a realtime view of unit tests while working on components or infrastructure code,\n by opening the tests web page and selecting the right test suite to hot reload while editing.\n
\n\n
Bonus: working offline
\n
\n Because I live at the beach and work in the big city I regularly need to take long train rides with spotty internet connection.\n Like many developers I cannot keep web API's in my head and have to look them up regularly while coding.\n To have a complete offline vanilla web development setup with me at all times I use devdocs.io.\n All my projects folders are set up to sync automatically with Syncthing, \n so whatever I was doing on the desktop can usually be smoothly continued offline on the laptop \n without having to do any prep work to make that possible.\n
\n \n\n
\n There, that's my lean vanilla web development setup.\n What should I add to this, or do differently? Feel free to let me know.\n
\n If you go to a typical website built with a framework, you'll see a lot of this:\n
\n \n
\n Those long cryptic filenames are not meant to discourage casual snooping.\n They're meant to ensure the filename is changed every time a single byte in that file changes,\n because the site is using far-future expire headers, \n a technique where the browser is told to cache files indefinitely, until the end of time.\n On successive page loads those resources will then always be served from cache.\n The only drawback is having to change the filename each time the file's contents change, \n but a framework's build steps typically take care of that.\n
\n
\n For vanilla web sites, this strategy doesn't work. By abandoning a build step there is no way to automatically generate filenames,\n and unless nothing makes you happier than renaming all files manually every time you deploy a new version,\n we have to look towards other strategies.\n
\n\n
How caching works
\n\n
\n Browser cache behavior is complicated, and a deep dive into the topic deserves its own article.\n However, very simply put, what you'll see is mostly these response headers:\n
\n
\n
Cache-Control
\n
\n
\n The cache control response header determines whether the browser should cache the response, and how long it should serve the response from cache.\n
\n
Cache-Control: public, max-age: 604800
\n
\n This will cache the resource and only check if there's a new version after one week.\n
\n
\n
Age
\n
\n
\n The max-age directive does not measure age from the time that the response is received,\n but from the time that the response was originally served:\n
\n
Age: 10
\n
\n This response header indicates the response was served on the origin server 10 seconds ago.\n
\n
\n
Etag
\n
\n
\n The Etag header is a unique hash of the resource's contents, an identifier for that version of the resource.\n
\n When the browser requests that resource again from the server, knowing the Etag it can pass an If-None-Match\n header with the Etag's value. If the resource has not changed it will still have the same Etag value,\n and the server will respond with 304 Not Modified. \n
\n The Last-Modified header works similarly to Etag, except instead of sending a hash of the contents,\n it sends a timestamp of when the resource was last changed. \n Like Etag's If-None-Match it is matched by the If-Modified-Since header when requesting the resource from the server again.\n
\n
\n
\n\n
\n With that basic review of caching headers, let's look at some strategies for making good use of them in vanilla web projects.\n
\n\n
Keeping it simple: GitHub Pages
\n\n
\n The simplest strategy is what GitHub Pages does: cache files for 10 minutes.\n Every file that's downloaded has Cache-Control: max-age headers that make it expire 10 minutes into the future.\n After that if the file is loaded again it will be requested from the network.\n The browser will add If-None-Match or If-Modified-Since headers\n to allow the server to avoid sending the file if it hasn't been changed, saving bytes but not a roundtrip.\n
\n
\n If you want to see it in action, just open the browser devtools and reload this page.\n
\n \n
\n Visitors never get a page that is more than 10 minutes out of date,\n and as they navigate around the site they mostly get fast cache-served responses.\n However, on repeat visits they will get a slow first-load experience.\n 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.\n Well, for 10 minutes at least.\n
\n\n
Extending cache durations
\n
\n While the 10 minute cache policy is ok for HTML content and small JS and CSS files,\n it can be improved by increasing cache times on large resources like libraries and images.\n By using a caching proxy that allows setting rules on specific types or folders of files we can increase the cache duration.\n For sites proxied through Cloudflare, \n their cache customization settings \n can be used to set these resource-specific policies.\n
\n
\n By setting longer cache durations on some resources, we can ensure they're served from local cache more often.\n 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.\n For example, by appending a unique query parameter:\n
\n The awkward aspect of having to change the referred URL in every place that a changed file is used\n makes extending cache durations inconvenient for files that are changed often or are referred in many places.\n
\n
\n Also, applying such policies to JavaScript or CSS becomes a minefield,\n because a mismatched combination of JS or CSS files could end up in the browser cache indefinitely,\n breaking the website for the user until URL's are changed or their browser cache is cleared.\n 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.\n
\n\n
Complete control with service workers
\n\n
\n A static web site can take complete control over its cache behavior by using a service worker.\n The service worker intercepts every network request and then decides whether to serve it from a local cache or from the network.\n For example, here's a service worker that will cache all resources indefinitely, until its version is changed:\n
\n \n
\n This recreates the far-future expiration strategy but does it client-side, inside the service worker.\n Because only the version at the top of the sw.js file needs to be updated when the site's contents change,\n this becomes practical to do without adding a build step. However, because the service worker intercepts network requests\n 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.\n (And no, the above service worker code hasn't been baked in production, so be careful when copying it to your own site.)\n
\n \n
Wrapping up
\n
\n Setting sane cache policies meant to optimize page load performance is one of the things typically in the domain\n of full-fat frameworks or application servers. But, abandoning build steps and server-side logic does not necessarily \n have to mean having poor caching performance. There are multiple strategies with varying amounts of cache control,\n and there is probably a suitable strategy for any plain vanilla site.\n
\n
\n Last but not least, an even better way to speed up page loading is to keep the web page itself light.\n Using a plain vanilla approach to pages with zero dependencies baked into the page weight\n already puts you in pole position for good page load performance, before caching even enters the picture.\n
\n \n \n \n\n"
},
{
"path": "public/blog/articles/2024-12-16-caching-vanilla-sites/sw.js",
"content": "let cacheName = 'cache-worker-v1';\n// these are automatically cached when the site is first loaded\nlet initialAssets = [\n './',\n 'index.html',\n 'index.js',\n 'index.css',\n 'manifest.json',\n 'android-chrome-512x512.png',\n 'favicon.ico',\n 'apple-touch-icon.png',\n 'styles/reset.css',\n // the rest will be auto-discovered\n];\n\n// initial bundle (on first load)\nself.addEventListener('install', (event) => {\n event.waitUntil(\n caches.open(cacheName).then((cache) => {\n return cache.addAll(initialAssets);\n })\n );\n});\n\n// clear out stale caches after service worker update\nself.addEventListener('activate', (event) => {\n event.waitUntil(\n caches.keys().then((cacheNames) => {\n return Promise.all(\n cacheNames.map((cacheName) => {\n if (cacheName !== self.cacheName) {\n return caches.delete(cacheName);\n }\n })\n );\n })\n );\n});\n\n// default to fetching from cache, fallback to network\nself.addEventListener('fetch', (event) => {\n const url = new URL(event.request.url);\n\n // other origins bypass the cache\n if (url.origin !== location.origin) {\n networkOnly(event);\n // default to fetching from cache, and updating asynchronously\n } else {\n staleWhileRevalidate(event);\n }\n});\n\nconst networkOnly = (event) => {\n event.respondWith(fetch(event.request));\n}\n\n// fetch events are serviced from cache if possible, but also updated behind the scenes\nconst staleWhileRevalidate = (event) => {\n event.respondWith(\n caches.match(event.request).then(cachedResponse => {\n const networkUpdate = \n fetch(event.request).then(networkResponse => {\n caches.open(cacheName).then(\n cache => cache.put(event.request, networkResponse));\n return networkResponse.clone();\n }).catch(_ => /*ignore because we're probably offline*/_);\n return cachedResponse || networkUpdate;\n })\n );\n}"
},
{
"path": "public/blog/articles/2025-01-01-new-years-resolve/example-index.js",
"content": "import { registerAvatarComponent } from './components/avatar.js';\nconst app = () => {\n registerAvatarComponent();\n}\ndocument.addEventListener('DOMContentLoaded', app);\n"
},
{
"path": "public/blog/articles/2025-01-01-new-years-resolve/index.html",
"content": "\n\n\n New year's resolve\n \n \n \n \n\n\n \n \n
New year's resolve
\n
Joeri Sebrechts
\n \n \n
\n Today I was looking at what I want to write about in the coming year,\n and while checking out custom element micro-frameworks came across import.meta.resolve\n in the documentation for the Ponys micro-framework. \n That one simple trick is part of the essential toolbox that allows skipping build-time bundling,\n unlocking the vanilla web development achievement in the browser.\n
\n
\n We need this toolbox because the build-time bundler does a lot of work for us:\n
\n
\n
Combining JS and CSS files to avoid slow page loads.
\n
Resolving paths to the JS and CSS dependencies so we can have clean import statements.
\n
Optimizing the bundled code, by stripping out whitespace, and removing unused imports thanks to a tree shaking algorithm.
\n
\n
\n It is not immediately apparent how to get these benefits without using a bundler.\n
\n\n
Combining JS and CSS files
\n
\n A typical framework-based web project contains hundreds or thousands of files.\n Having all those files loaded separately on a page load would be intolerably slow,\n hence the need for a bundler to reduce the file count. Even by stripping away third party dependencies\n we can still end up with dozens or hundreds of files constituting a vanilla web project.\n
\n
\n When inspecting a page load in the browser's developer tools, we would then expect to see a lot of this:\n
\n \n
\n The browser would download 6 files at a time and the later requests would block until those files downloaded.\n 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\n was per domain it also led to the popularity of CDN networks which allowed cheating and downloading 12 files at once instead of 6.\n
\n
\n However. It's 2025. What you're likely to see in this modern era is more like this:\n
\n \n
\n 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,\n we now see that all the files that are requested in parallel get downloaded in parallel.\n There's still a small caveat on lossy connections called head-of-line-blocking, fixed in HTTP/3,\n which is presently starting to roll out to web servers across the internet.\n
\n
\n 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.\n We don't need to bundle up the files in a vanilla web project until the file counts get ridiculous.\n
\n\n
Resolving paths
\n\n
\n Another thing that bundlers do is resolving relative paths pointing to imported JS and CSS files.\n See, for example, the elegance of CSS modules for importing styles into a react component from a relative path:\n
\n \n
\n However. It's 2025. And our browsers now have a modern vanilla toolbox for importing.\n When we bootstrap our JS with the magic incantation <script src=\"index.js\" type=\"module\"></script>\n we unlock the magic ability to import JS files using ES module import notation:\n
\n \n
\n Inside of such files we also get access to import.meta.url, the URL of the current JS file,\n and import.meta.resolve(), a function that resolves a path relative to the current file,\n even a path to a CSS file:\n
\n \n
\n While not quite the same as what the bundler does, it still enables accessing any file by its relative path,\n and that in turn allows organizing projects in whatever way we want, for example in a feature-based folder organization.\n All without needing a build step.\n
\n
\n This ability to do relative imports can be super-charged by import maps,\n which decouple the name of what is imported from the path of the file it is imported from,\n again all without involving a build step.\n
\n\n
Optimizing bundled code
\n\n
\n Another thing bundlers can do is optimizing the bundled code, by splitting the payload into things loaded initially,\n and things loaded later on lazily. And also by minifying it, stripping away unnecessary whitespace and comments so it will load faster.\n
\n
\n However. It's 2025. We can transparently enable gzip or brotli compression on the server,\n and as it turns out that gets almost all the benefit of minifying. \n While minifying is nice, gzipping is what we really want, and we can get that without a build step.\n
\n
\n 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.\n I wrote before how React's lazy and suspense can be ported easily to vanilla web components.\n
\n\n
Happy new year!
\n\n
\n Great news! It's 2025, and the browser landscape is looking better than ever. It gives us enough tools that for many web projects\n we can drop the bundler and do just fine. You wouldn't believe it based on what the mainstream frameworks are doing though.\n Maybe 2025 is the year we finally see a wide recognition of just how powerful the browser platform has gotten,\n and a return to old school simplicity in web development practice, away from all those complicated build steps. \n It's my new year's resolve to do my part in spreading the word.\n
\n Web components, a.k.a. custom elements, are HTML elements\n that participate in HTML markup. As such they can have attributes:\n
\n
<my-hello value=\"world\"></my-hello>
\n
\n But, they are also JavaScript objects, and as such they can have object properties.\n
\n
let myHello = document.querySelector('my-hello'); myHello.value = 'foo';
\n
\n And here's the tricky part about that: these are not the same thing!\n In fact, custom element attributes and properties by default have zero relationship between them,\n even when they share a name. Here's a live proof of this fact:\n
\n\n \n \n\n
\n Now, to be fair, we can get at the attribute value just fine from JavaScript:\n
\n\n \n \n\n
\n But what if we would also like it to have a valueproperty?\n What should the relationship between attribute and property be like?\n
\n
\n
Does updating the attribute always update the property?
\n
Does updating the property always update the attribute?
\n
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?
\n
When updates can go either way, how to avoid loops where the property updates the attribute, which updates the property, which...
\n
When is it fine to have just an attribute without a property, or a property without an attribute?
\n
\n\n
\n In framework-based code, we typically don't get a say in these things.\n Frameworks generally like to pretend that attributes and properties are the same thing,\n and they automatically create code to make sure this is the case.\n In vanilla custom elements however, not only do we get to decide these things, we must decide them.\n
\n\n
Going native
\n\n
\n Seasoned developers will intuitively grasp what the sensible relationship between attributes and properties should be.\n This is because built-in HTML elements all implement similar kinds of relationships between their attributes and their properties.\n To explore that in depth, I recommend reading Making Web Component properties behave closer to the platform.\n Without fully restating that article, here's a quick recap:\n
\n
\n
Properties can exist independent of an attribute, but an attribute will typically have a related property.
\n
If changing the attribute updates the property, then updating the property will update the attribute.
\n
Properties reflect either an internal value of an element, or the value of the corresponding attribute.
\n
Assigning a value of an invalid type will coerce the value to the right type, instead of rejecting the change.
\n
Change events are only dispatched for changes by user input, not from programmatic changes to attribute or property.
\n
\n\n
An easy way to get much of this behavior is to make a property wrap around an attribute:
\n\n \n \n\n
\n Notice how updating the property will update the attribute in the HTML representation,\n and how the property's assigned value is coerced into the attribute's string type.\n Attributes are always strings.\n
\n \n
Into the weeds
\n\n
\n Up to this point, things are looking straightforward. But this is web development,\n things are never as straightforward as they seem.\n For instance, what boolean attribute value should make a corresponding boolean property become true?\n The surprising but standard behavior on built-in elements is that \n any attribute value will be interpreted as true, and only the absence of the attribute will be interpreted as false.\n
\n
\n Time for another iteration of our element:\n
\n\n \n \n\n
\n Which leaves us with the last bit of tricky trivia:\n it's possible for the custom element's class to be instantiated and attached to the element\n after the property is assigned. In that case the property's setter is never called,\n and the attribute is not updated.\n
\n \n \n\n
\n This can be avoided by reassigning any previously set properties when the element is connected:\n
\n\n \n\n
In conclusion
\n\n
\n If that seems like a lot of work to do a very simple thing, that is because it is.\n The good news is: we don't have to always do this work.\n
\n
\n When we're using web components as framework components in a codebase that we control,\n we don't have to follow any of these unwritten rules and can keep the web component code as simple as we like.\n However, when using web components as custom elements to be used in HTML markup \n then we do well to follow these best practices to avoid surprises, \n especially when making web components that may be used by others. YMMV.\n
\n
\n In the next article, I'll be looking into custom elements that accept input, and how that adds twists to the plot.\n
\n\n \n \n \n\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo1/index-partial.txt",
"content": ""
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo1/index.html",
"content": "\n\n \n \n \n demo 1\n \n \n \n \n \n \n \n \n \n \n\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo1/input-inline.js",
"content": "customElements.define('input-inline', class extends HTMLElement {\n \n get value() {\n return this.getAttribute('value') ?? '';\n }\n set value(value) {\n this.setAttribute('value', String(value));\n }\n\n get name() {\n return this.getAttribute('name') ?? '';\n }\n set name(v) {\n this.setAttribute('name', String(v));\n }\n \n connectedCallback() {\n this.#update();\n }\n\n static observedAttributes = ['value'];\n attributeChangedCallback() {\n this.#update();\n }\n\n #update() {\n this.style.display = 'inline';\n if (this.textContent !== this.value) {\n this.textContent = this.value;\n }\n this.contentEditable = true;\n }\n});"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo2/index.html",
"content": "\n\n \n \n \n demo 2\n \n \n \n \n \n \n \n \n \n \n\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo2/input-inline-partial.js",
"content": "customElements.define('input-inline', class extends HTMLElement {\n \n #internals;\n\n /* ... */\n\n constructor() {\n super();\n this.#internals = this.attachInternals();\n this.#internals.role = 'textbox';\n }\n \n /* ... */\n\n #update() {\n /* ... */\n this.#internals.setFormValue(this.value);\n }\n\n static formAssociated = true;\n});"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo2/input-inline.js",
"content": "customElements.define('input-inline', class extends HTMLElement {\n \n #internals;\n\n get value() {\n return this.getAttribute('value') ?? '';\n }\n set value(value) {\n this.setAttribute('value', String(value));\n }\n\n get name() {\n return this.getAttribute('name') ?? '';\n }\n set name(v) {\n this.setAttribute('name', String(v));\n }\n\n constructor() {\n super();\n this.#internals = this.attachInternals();\n this.#internals.role = 'textbox';\n }\n \n connectedCallback() {\n this.#update();\n }\n\n static observedAttributes = ['value'];\n attributeChangedCallback() {\n this.#update();\n }\n\n #update() {\n this.style.display = 'inline';\n if (this.textContent !== this.value) {\n this.textContent = this.value;\n }\n this.contentEditable = true;\n this.#internals.setFormValue(this.value);\n }\n\n static formAssociated = true;\n});"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo3/index.html",
"content": "\n\n \n \n \n demo 3\n \n \n \n \n \n \n \n \n \n \n\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo3/input-inline-partial.js",
"content": "customElements.define('input-inline', class extends HTMLElement {\n \n #shouldFireChange = false;\n \n /* ... */\n\n constructor() {\n /* ... */\n this.addEventListener('input', this);\n this.addEventListener('keydown', this);\n this.addEventListener('paste', this);\n this.addEventListener('focusout', this);\n }\n\n handleEvent(e) {\n switch (e.type) {\n // respond to user input (typing, drag-and-drop, paste)\n case 'input':\n this.value = cleanTextContent(this.textContent);\n this.#shouldFireChange = true;\n break;\n // enter key should submit form instead of adding a new line\n case 'keydown':\n if (e.key === 'Enter') {\n e.preventDefault();\n this.#internals.form?.requestSubmit();\n }\n break;\n // prevent pasting rich text (firefox), or newlines (all browsers)\n case 'paste':\n e.preventDefault();\n const text = e.clipboardData.getData('text/plain')\n // replace newlines and tabs with spaces\n .replace(/[\\n\\r\\t]+/g, ' ')\n // limit length of pasted text to something reasonable\n .substring(0, 1000);\n // shadowRoot.getSelection is non-standard, fallback to document in firefox\n // https://stackoverflow.com/a/70523247\n let selection = this.getRootNode()?.getSelection?.() || document.getSelection();\n let range = selection.getRangeAt(0);\n range.deleteContents();\n range.insertNode(document.createTextNode(text));\n // manually trigger input event to restore default behavior\n this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));\n break;\n // fire change event on blur\n case 'focusout':\n if (this.#shouldFireChange) {\n this.#shouldFireChange = false;\n this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));\n }\n break;\n }\n }\n \n /* ... */\n});\n\nfunction cleanTextContent(text) {\n return (text ?? '')\n // replace newlines and tabs with spaces\n .replace(/[\\n\\r\\t]+/g, ' ');\n}\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo3/input-inline.js",
"content": "customElements.define('input-inline', class extends HTMLElement {\n \n #shouldFireChange = false;\n #internals;\n\n get value() {\n return this.getAttribute('value') ?? '';\n }\n set value(value) {\n this.setAttribute('value', String(value));\n }\n\n get name() {\n return this.getAttribute('name') ?? '';\n }\n set name(v) {\n this.setAttribute('name', String(v));\n }\n\n constructor() {\n super();\n this.#internals = this.attachInternals();\n this.#internals.role = 'textbox';\n // add event listeners\n this.addEventListener('input', this);\n this.addEventListener('keydown', this);\n this.addEventListener('paste', this);\n this.addEventListener('focusout', this);\n }\n\n handleEvent(e) {\n switch (e.type) {\n // respond to user input (typing, drag-and-drop, paste)\n case 'input':\n this.value = cleanTextContent(this.textContent);\n this.#shouldFireChange = true;\n break;\n // enter key should submit form instead of adding a new line\n case 'keydown':\n if (e.key === 'Enter') {\n e.preventDefault();\n this.#internals.form?.requestSubmit();\n }\n break;\n // prevent pasting rich text (firefox), or newlines (all browsers)\n case 'paste':\n e.preventDefault();\n const text = e.clipboardData.getData('text/plain')\n // replace newlines and tabs with spaces\n .replace(/[\\n\\r\\t]+/g, ' ')\n // limit length of pasted text to something reasonable\n .substring(0, 1000);\n // shadowRoot.getSelection is non-standard, fallback to document in firefox\n // https://stackoverflow.com/a/70523247\n let selection = this.getRootNode()?.getSelection?.() || document.getSelection();\n let range = selection.getRangeAt(0);\n range.deleteContents();\n range.insertNode(document.createTextNode(text));\n // manually trigger input event to restore default behavior\n this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));\n break;\n // fire change event on blur\n case 'focusout':\n if (this.#shouldFireChange) {\n this.#shouldFireChange = false;\n this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));\n }\n break;\n }\n }\n \n connectedCallback() {\n this.#update();\n }\n\n static observedAttributes = ['value'];\n attributeChangedCallback() {\n this.#update();\n }\n\n #update() {\n this.style.display = 'inline';\n if (cleanTextContent(this.textContent) !== this.value) {\n this.textContent = this.value;\n }\n this.contentEditable = true;\n this.#internals.setFormValue(this.value);\n }\n\n static formAssociated = true;\n});\n\nfunction cleanTextContent(text) {\n return (text ?? '')\n // replace newlines and tabs with spaces\n .replace(/[\\n\\r\\t]+/g, ' ')\n // remove zero width spaces\n .replace(/\\u200B/g, '');\n}\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo4/index.html",
"content": "\n\n \n \n \n demo 4\n \n \n \n \n \n \n \n \n \n \n\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo4/input-inline-partial.js",
"content": "customElements.define('input-inline', class extends HTMLElement {\n \n /* ... */\n\n #formDisabled = false;\n #value;\n\n set value(v) {\n if (this.#value !== String(v)) {\n this.#value = String(v);\n this.#update(); \n }\n }\n get value() {\n return this.#value ?? this.defaultValue;\n }\n\n get defaultValue() {\n return this.getAttribute('value') ?? '';\n }\n set defaultValue(value) {\n this.setAttribute('value', String(value));\n }\n\n set disabled(v) {\n if (v) {\n this.setAttribute('disabled', 'true');\n } else {\n this.removeAttribute('disabled');\n }\n }\n get disabled() {\n return this.hasAttribute('disabled');\n }\n\n set readOnly(v) {\n if (v) {\n this.setAttribute('readonly', 'true');\n } else {\n this.removeAttribute('readonly');\n }\n }\n get readOnly() {\n return this.hasAttribute('readonly');\n }\n\n /* ... */\n\n static observedAttributes = ['value', 'disabled', 'readonly'];\n attributeChangedCallback() {\n this.#update();\n }\n\n #update() {\n this.style.display = 'inline';\n this.textContent = this.value;\n this.#internals.setFormValue(this.value);\n\n const isDisabled = this.#formDisabled || this.disabled;\n this.#internals.ariaDisabled = isDisabled;\n this.#internals.ariaReadOnly = this.readOnly;\n this.contentEditable = !this.readOnly && !isDisabled && 'plaintext-only';\n this.tabIndex = isDisabled ? -1 : 0;\n }\n\n static formAssociated = true;\n\n formResetCallback() {\n this.#value = undefined;\n this.#update();\n }\n \n formDisabledCallback(disabled) {\n this.#formDisabled = disabled;\n this.#update();\n }\n \n formStateRestoreCallback(state) {\n this.#value = state ?? undefined;\n this.#update();\n }\n});\n\n/* ... */"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo4/input-inline.js",
"content": "customElements.define('input-inline', class extends HTMLElement {\n \n #shouldFireChange = false;\n #internals;\n #formDisabled = false;\n #value;\n\n set value(v) {\n if (this.#value !== String(v)) {\n this.#value = String(v);\n this.#update(); \n }\n }\n get value() {\n return this.#value ?? this.defaultValue;\n }\n\n get defaultValue() {\n return this.getAttribute('value') ?? '';\n }\n set defaultValue(value) {\n this.setAttribute('value', String(value));\n }\n\n set disabled(v) {\n if (v) {\n this.setAttribute('disabled', 'true');\n } else {\n this.removeAttribute('disabled');\n }\n }\n get disabled() {\n return this.hasAttribute('disabled');\n }\n\n set readOnly(v) {\n if (v) {\n this.setAttribute('readonly', 'true');\n } else {\n this.removeAttribute('readonly');\n }\n }\n get readOnly() {\n return this.hasAttribute('readonly');\n }\n\n get name() {\n return this.getAttribute('name') ?? '';\n }\n set name(v) {\n this.setAttribute('name', String(v));\n }\n\n constructor() {\n super();\n this.#internals = this.attachInternals();\n this.#internals.role = 'textbox';\n // add event listeners\n this.addEventListener('input', this);\n this.addEventListener('keydown', this);\n this.addEventListener('paste', this);\n this.addEventListener('focusout', this);\n }\n\n handleEvent(e) {\n switch (e.type) {\n // respond to user input (typing, drag-and-drop, paste)\n case 'input':\n this.value = cleanTextContent(this.textContent);\n this.#shouldFireChange = true;\n break;\n // enter key should submit form instead of adding a new line\n case 'keydown':\n if (e.key === 'Enter') {\n e.preventDefault();\n this.#internals.form?.requestSubmit();\n }\n break;\n // prevent pasting rich text (firefox), or newlines (all browsers)\n case 'paste':\n e.preventDefault();\n const text = e.clipboardData.getData('text/plain')\n // replace newlines and tabs with spaces\n .replace(/[\\n\\r\\t]+/g, ' ')\n // limit length of pasted text to something reasonable\n .substring(0, 1000);\n // shadowRoot.getSelection is non-standard, fallback to document in firefox\n // https://stackoverflow.com/a/70523247\n let selection = this.getRootNode()?.getSelection?.() || document.getSelection();\n let range = selection.getRangeAt(0);\n range.deleteContents();\n range.insertNode(document.createTextNode(text));\n // manually trigger input event to restore default behavior\n this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));\n break;\n // fire change event on blur\n case 'focusout':\n if (this.#shouldFireChange) {\n this.#shouldFireChange = false;\n this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));\n }\n break;\n }\n }\n \n connectedCallback() {\n this.#update();\n }\n\n static observedAttributes = ['value', 'disabled', 'readonly'];\n attributeChangedCallback() {\n this.#update();\n }\n\n #update() {\n this.style.display = 'inline';\n if (cleanTextContent(this.textContent) !== this.value) {\n this.textContent = this.value;\n }\n this.#internals.setFormValue(this.value);\n\n const isDisabled = this.#formDisabled || this.disabled;\n this.#internals.ariaDisabled = isDisabled;\n this.#internals.ariaReadOnly = this.readOnly;\n this.contentEditable = !this.readOnly && !isDisabled && 'plaintext-only';\n this.tabIndex = isDisabled ? -1 : 0;\n }\n\n static formAssociated = true;\n\n formResetCallback() {\n this.#value = undefined;\n this.#update();\n }\n \n formDisabledCallback(disabled) {\n this.#formDisabled = disabled;\n this.#update();\n }\n \n formStateRestoreCallback(state) {\n this.#value = state ?? undefined;\n this.#update();\n }\n});\n\nfunction cleanTextContent(text) {\n return (text ?? '')\n // replace newlines and tabs with spaces\n .replace(/[\\n\\r\\t]+/g, ' ')\n // remove zero width spaces\n .replace(/\\u200B/g, '');\n}\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo5/index.html",
"content": "\n\n \n \n \n demo 5\n \n \n \n \n \n \n \n \n \n \n \n\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo5/input-inline.css",
"content": "/* default styling has lowest priority */\n@layer {\n :root {\n --input-inline-border-color: light-dark(rgb(118, 118, 118), rgb(161, 161, 161));\n --input-inline-border-color-hover: light-dark(rgb(78, 78, 78), rgb(200, 200, 200));\n --input-inline-border-color-disabled: rgba(150, 150, 150, 0.5);\n --input-inline-text-color: light-dark(fieldtext, rgb(240, 240, 240));\n --input-inline-text-color-disabled: light-dark(rgb(84, 84, 84), rgb(170, 170, 170));\n --input-inline-bg-color: inherit;\n --input-inline-bg-color-disabled: inherit;\n --input-inline-min-width: 4ch;\n }\n\n input-inline {\n display: inline;\n background-color: var(--input-inline-bg-color);\n color: var(--input-inline-text-color);\n border: 1px dotted var(--input-inline-border-color);\n padding: 2px 3px;\n margin-bottom: -2px;\n border-radius: 3px;\n /* minimum width */\n padding-right: max(3px, calc(var(--input-inline-min-width) - var(--current-length)));\n\n &:hover {\n border-color: var(--input-inline-border-color-hover);\n }\n \n &:disabled {\n border-color: var(--input-inline-border-color-disabled);\n background-color: var(--input-inline-bg-color-disabled);\n color: var(--input-inline-text-color-disabled);\n -webkit-user-select: none;\n user-select: none;\n }\n \n &:focus-visible {\n border-color: transparent;\n outline-offset: 0;\n outline: 2px solid royalblue; /* firefox */\n outline-color: -webkit-focus-ring-color; /* the rest */\n }\n }\n\n @media screen and (-webkit-min-device-pixel-ratio:0) {\n input-inline:empty::before {\n /* fixes issue where empty input-inline shifts left in chromium browsers */\n content: \" \";\n }\n }\n\n}\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo5/input-inline.js",
"content": "customElements.define('input-inline', class extends HTMLElement {\n \n #shouldFireChange = false;\n #internals;\n #formDisabled = false;\n #value;\n\n set value(v) {\n if (this.#value !== String(v)) {\n this.#value = String(v);\n this.#update(); \n }\n }\n get value() {\n return this.#value ?? this.defaultValue;\n }\n\n get defaultValue() {\n return this.getAttribute('value') ?? '';\n }\n set defaultValue(value) {\n this.setAttribute('value', String(value));\n }\n\n set disabled(v) {\n if (v) {\n this.setAttribute('disabled', 'true');\n } else {\n this.removeAttribute('disabled');\n }\n }\n get disabled() {\n return this.hasAttribute('disabled');\n }\n\n set readOnly(v) {\n if (v) {\n this.setAttribute('readonly', 'true');\n } else {\n this.removeAttribute('readonly');\n }\n }\n get readOnly() {\n return this.hasAttribute('readonly');\n }\n\n get name() {\n return this.getAttribute('name') ?? '';\n }\n set name(v) {\n this.setAttribute('name', String(v));\n }\n\n constructor() {\n super();\n this.#internals = this.attachInternals();\n this.#internals.role = 'textbox';\n // add event listeners\n this.addEventListener('input', this);\n this.addEventListener('keydown', this);\n this.addEventListener('paste', this);\n this.addEventListener('focusout', this);\n }\n\n handleEvent(e) {\n switch (e.type) {\n // respond to user input (typing, drag-and-drop, paste)\n case 'input':\n this.value = cleanTextContent(this.textContent);\n this.#shouldFireChange = true;\n break;\n // enter key should submit form instead of adding a new line\n case 'keydown':\n if (e.key === 'Enter') {\n e.preventDefault();\n this.#internals.form?.requestSubmit();\n }\n break;\n // prevent pasting rich text (firefox), or newlines (all browsers)\n case 'paste':\n e.preventDefault();\n const text = e.clipboardData.getData('text/plain')\n // replace newlines and tabs with spaces\n .replace(/[\\n\\r\\t]+/g, ' ')\n // limit length of pasted text to something reasonable\n .substring(0, 1000);\n // shadowRoot.getSelection is non-standard, fallback to document in firefox\n // https://stackoverflow.com/a/70523247\n let selection = this.getRootNode()?.getSelection?.() || document.getSelection();\n let range = selection.getRangeAt(0);\n range.deleteContents();\n range.insertNode(document.createTextNode(text));\n // manually trigger input event to restore default behavior\n this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));\n break;\n // fire change event on blur\n case 'focusout':\n if (this.#shouldFireChange) {\n this.#shouldFireChange = false;\n this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));\n }\n break;\n }\n }\n \n connectedCallback() {\n this.#update();\n }\n\n static observedAttributes = ['value', 'disabled', 'readonly'];\n attributeChangedCallback() {\n this.#update();\n }\n\n #update() {\n this.style.display = 'inline';\n if (cleanTextContent(this.textContent) !== this.value) {\n this.textContent = this.value;\n }\n this.#internals.setFormValue(this.value);\n\n const isDisabled = this.#formDisabled || this.disabled;\n this.#internals.ariaDisabled = isDisabled;\n this.#internals.ariaReadOnly = this.readOnly;\n this.contentEditable = !this.readOnly && !isDisabled && 'plaintext-only';\n this.tabIndex = isDisabled ? -1 : 0;\n\n const length = cleanTextContent(this.textContent).length || 0;\n this.style.setProperty('--current-length', `${length}ch`);\n }\n\n static formAssociated = true;\n\n formResetCallback() {\n this.#value = undefined;\n this.#update();\n }\n \n formDisabledCallback(disabled) {\n this.#formDisabled = disabled;\n this.#update();\n }\n \n formStateRestoreCallback(state) {\n this.#value = state ?? undefined;\n this.#update();\n }\n});\n\nfunction cleanTextContent(text) {\n return (text ?? '')\n // replace newlines and tabs with spaces\n .replace(/[\\n\\r\\t]+/g, ' ')\n // remove zero width spaces\n .replace(/\\u200B/g, '');\n}\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo6/index-partial.txt",
"content": ""
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo6/index.html",
"content": "\n\n \n \n \n demo 6\n \n \n \n \n \n \n
\n \n \n
\n \n \n \n \n\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo6/input-inline-partial.js",
"content": "let VALUE_MISSING_MESSAGE = 'Please fill out this field.';\n(() => {\n const input = document.createElement('input');\n input.required = true;\n input.reportValidity();\n VALUE_MISSING_MESSAGE = input.validationMessage;\n})();\n\nconst isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);\n\ncustomElements.define('input-inline', class extends HTMLElement {\n \n /* ... */\n\n #customValidityMessage = '';\n\n /* ... */\n\n set required(v) {\n if (v) {\n this.setAttribute('required', 'true');\n } else {\n this.removeAttribute('required');\n }\n }\n get required() {\n return this.hasAttribute('required');\n }\n\n /* ... */\n\n static observedAttributes = ['value', 'disabled', 'readonly', 'required'];\n attributeChangedCallback() {\n this.#update();\n }\n\n #update() {\n /* ... */\n\n this.#internals.ariaRequired = this.required;\n this.#updateValidity();\n }\n\n /* ... */\n\n #updateValidity() {\n const state = {};\n let message = '';\n\n // custom validity message overrides all else\n if (this.#customValidityMessage) {\n state.customError = true;\n message = this.#customValidityMessage;\n } else {\n if (this.required && !this.value) {\n state.valueMissing = true;\n message = VALUE_MISSING_MESSAGE;\n }\n \n // add other checks here if needed (e.g., pattern, minLength)\n }\n\n // safari needs a focusable validation anchor to show the validation message on form submit\n // and it must be a descendant of the input\n let anchor = undefined;\n if (isSafari) {\n anchor = this.querySelector('span[aria-hidden]');\n if (!anchor) {\n anchor = document.createElement('span');\n anchor.ariaHidden = true;\n anchor.tabIndex = 0;\n this.append(anchor);\n }\n }\n\n this.#internals.setValidity(state, message, anchor);\n }\n\n checkValidity() {\n this.#updateValidity();\n return this.#internals.checkValidity();\n }\n\n reportValidity() {\n this.#updateValidity();\n return this.#internals.reportValidity();\n }\n\n setCustomValidity(message) {\n this.#customValidityMessage = message ?? '';\n this.#updateValidity();\n }\n\n get validity() {\n return this.#internals.validity;\n }\n\n get validationMessage() {\n return this.#internals.validationMessage;\n }\n\n get willValidate() {\n return this.#internals.willValidate;\n }\n});\n\n/* ... */"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo6/input-inline.css",
"content": "/* default styling has lowest priority */\n@layer {\n :root {\n --input-inline-border-color: light-dark(rgb(118, 118, 118), rgb(161, 161, 161));\n --input-inline-border-color-hover: light-dark(rgb(78, 78, 78), rgb(200, 200, 200));\n --input-inline-border-color-disabled: rgba(150, 150, 150, 0.5);\n --input-inline-text-color: light-dark(fieldtext, rgb(240, 240, 240));\n --input-inline-text-color-disabled: light-dark(rgb(84, 84, 84), rgb(170, 170, 170));\n --input-inline-bg-color: inherit;\n --input-inline-bg-color-disabled: inherit;\n --input-inline-min-width: 4ch;\n }\n\n input-inline {\n display: inline;\n background-color: var(--input-inline-bg-color);\n color: var(--input-inline-text-color);\n border: 1px dotted var(--input-inline-border-color);\n padding: 2px 3px;\n margin-bottom: -2px;\n border-radius: 3px;\n /* minimum width */\n padding-right: max(3px, calc(var(--input-inline-min-width) - var(--current-length)));\n\n &:hover {\n border-color: var(--input-inline-border-color-hover);\n }\n \n &:disabled {\n border-color: var(--input-inline-border-color-disabled);\n background-color: var(--input-inline-bg-color-disabled);\n color: var(--input-inline-text-color-disabled);\n -webkit-user-select: none;\n user-select: none;\n }\n \n &:focus-visible {\n border-color: transparent;\n outline-offset: 0;\n outline: 2px solid royalblue; /* firefox */\n outline-color: -webkit-focus-ring-color; /* the rest */\n }\n }\n\n @media screen and (-webkit-min-device-pixel-ratio:0) {\n input-inline:empty::before {\n /* fixes issue where empty input-inline shifts left in chromium browsers */\n content: \" \";\n }\n }\n\n}\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/demo6/input-inline.js",
"content": "let VALUE_MISSING_MESSAGE = 'Please fill out this field.';\n(() => {\n const input = document.createElement('input');\n input.required = true;\n input.reportValidity();\n VALUE_MISSING_MESSAGE = input.validationMessage;\n})();\n\nconst isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);\n\ncustomElements.define('input-inline', class extends HTMLElement {\n \n #shouldFireChange = false;\n #internals;\n #formDisabled = false;\n #value;\n #customValidityMessage = '';\n\n set value(v) {\n if (this.#value !== String(v)) {\n this.#value = String(v);\n this.#update(); \n }\n }\n get value() {\n return this.#value ?? this.defaultValue;\n }\n\n get defaultValue() {\n return this.getAttribute('value') ?? '';\n }\n set defaultValue(value) {\n this.setAttribute('value', String(value));\n }\n\n set disabled(v) {\n if (v) {\n this.setAttribute('disabled', 'true');\n } else {\n this.removeAttribute('disabled');\n }\n }\n get disabled() {\n return this.hasAttribute('disabled');\n }\n\n set readOnly(v) {\n if (v) {\n this.setAttribute('readonly', 'true');\n } else {\n this.removeAttribute('readonly');\n }\n }\n get readOnly() {\n return this.hasAttribute('readonly');\n }\n\n get name() {\n return this.getAttribute('name') ?? '';\n }\n set name(v) {\n this.setAttribute('name', String(v));\n }\n\n set required(v) {\n if (v) {\n this.setAttribute('required', 'true');\n } else {\n this.removeAttribute('required');\n }\n }\n get required() {\n return this.hasAttribute('required');\n }\n\n constructor() {\n super();\n this.#internals = this.attachInternals();\n this.#internals.role = 'textbox';\n // add event listeners\n this.addEventListener('input', this);\n this.addEventListener('keydown', this);\n this.addEventListener('paste', this);\n this.addEventListener('focusout', this);\n }\n\n handleEvent(e) {\n switch (e.type) {\n // respond to user input (typing, drag-and-drop, paste)\n case 'input':\n this.value = cleanTextContent(this.textContent);\n this.#shouldFireChange = true;\n break;\n // enter key should submit form instead of adding a new line\n case 'keydown':\n if (e.key === 'Enter') {\n e.preventDefault();\n this.#internals.form?.requestSubmit();\n }\n break;\n // prevent pasting rich text (firefox), or newlines (all browsers)\n case 'paste':\n e.preventDefault();\n const text = e.clipboardData.getData('text/plain')\n // replace newlines and tabs with spaces\n .replace(/[\\n\\r\\t]+/g, ' ')\n // limit length of pasted text to something reasonable\n .substring(0, 1000);\n // shadowRoot.getSelection is non-standard, fallback to document in firefox\n // https://stackoverflow.com/a/70523247\n let selection = this.getRootNode()?.getSelection?.() || document.getSelection();\n let range = selection.getRangeAt(0);\n range.deleteContents();\n range.insertNode(document.createTextNode(text));\n // manually trigger input event to restore default behavior\n this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));\n break;\n // fire change event on blur\n case 'focusout':\n if (this.#shouldFireChange) {\n this.#shouldFireChange = false;\n this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));\n }\n break;\n }\n }\n \n connectedCallback() {\n this.#update();\n }\n\n static observedAttributes = ['value', 'disabled', 'readonly', 'required'];\n attributeChangedCallback() {\n this.#update();\n }\n\n #update() {\n this.style.display = 'inline';\n if (cleanTextContent(this.textContent) !== this.value) {\n this.textContent = this.value;\n }\n this.#internals.setFormValue(this.value);\n\n const isDisabled = this.#formDisabled || this.disabled;\n this.#internals.ariaDisabled = isDisabled;\n this.#internals.ariaReadOnly = this.readOnly;\n this.contentEditable = !this.readOnly && !isDisabled && 'plaintext-only';\n this.tabIndex = isDisabled ? -1 : 0;\n\n const length = cleanTextContent(this.textContent).length || 0;\n this.style.setProperty('--current-length', `${length}ch`);\n\n this.#internals.ariaRequired = this.required;\n this.#updateValidity();\n }\n\n static formAssociated = true;\n\n formResetCallback() {\n this.#value = undefined;\n this.#update();\n }\n \n formDisabledCallback(disabled) {\n this.#formDisabled = disabled;\n this.#update();\n }\n \n formStateRestoreCallback(state) {\n this.#value = state ?? undefined;\n this.#update();\n }\n\n #updateValidity() {\n const state = {};\n let message = '';\n\n // custom validity message overrides all else\n if (this.#customValidityMessage) {\n state.customError = true;\n message = this.#customValidityMessage;\n } else {\n if (this.required && !this.value) {\n state.valueMissing = true;\n message = VALUE_MISSING_MESSAGE;\n }\n \n // add other checks here if needed (e.g., pattern, minLength)\n }\n\n // safari needs a focusable validation anchor to show the validation message on form submit\n // and it must be a descendant of the input\n let anchor = undefined;\n if (isSafari) {\n anchor = this.querySelector('span[aria-hidden]');\n if (!anchor) {\n anchor = document.createElement('span');\n anchor.ariaHidden = true;\n anchor.tabIndex = 0;\n this.append(anchor);\n }\n }\n\n this.#internals.setValidity(state, message, anchor);\n }\n\n checkValidity() {\n this.#updateValidity();\n return this.#internals.checkValidity();\n }\n\n reportValidity() {\n this.#updateValidity();\n return this.#internals.reportValidity();\n }\n\n setCustomValidity(message) {\n this.#customValidityMessage = message ?? '';\n this.#updateValidity();\n }\n\n get validity() {\n return this.#internals.validity;\n }\n\n get validationMessage() {\n return this.#internals.validationMessage;\n }\n\n get willValidate() {\n return this.#internals.willValidate;\n }\n});\n\nfunction cleanTextContent(text) {\n return (text ?? '')\n // replace newlines and tabs with spaces\n .replace(/[\\n\\r\\t]+/g, ' ')\n // remove zero width spaces\n .replace(/\\u200B/g, '');\n}\n"
},
{
"path": "public/blog/articles/2025-05-09-form-control/index.html",
"content": "\n\n\n Making a new form control\n \n \n \n \n\n\n \n \n
Making a new form control
\n
Joeri Sebrechts
\n \n \n
\n There are some things that a web developer knows they shouldn't attempt.\n Making clever use of contenteditable. Building custom form controls. Making complicated custom elements without a framework.\n 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?\n
\n
Narrator: it would indeed be that bad.
\n
\n This article is building on the previous one on proper attribute/property relations in custom elements.\n 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.\n The mission is simple: implement a basic version of <input type=\"text\" /> but with display: inline layout.\n
\n\n
A simple element
\n \n
\n Let's start by just throwing something against the wall and playing around with it.\n
\n \n
\n And here's how we use it: \n
\n \n \n\n
\n This is simple, clean, and horribly broken. For one, the form cannot see these controls at all and submits the empty object.\n
\n ElementInternals offers a control surface for setting the behavior of our custom element as part of a form.\n 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.\n By calling this.#internals.setFormValue every time the control's value changes the form will know what value to submit.\n 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.\n
\n\n
Looking for input
\n\n
\n Ostensibly responding to input is just adding a few event listeners in connectedCallback and removing them again in disconnectedCallback.\n But doing it that way quickly gets verbose. An easy alternative is to instead rely on some of the built-in event logic magic,\n namely that events bubble and that objects can be listeners too.\n
\n\n \n \n\n
\n I prefer this pattern because it simplifies the code a lot compared to having separate handler functions.\n Attaching event listeners in the constructor instead of attaching and detaching them in the lifecycle callbacks is another simplification. \n It may seem like blasphemy to never clean up the event listeners, but DOM event listeners\n are weakly bound and garbage collection of the element can still occur with them attached. So this is fine.\n
\n
\n In the event handler logic there's some verbosity to deal with the fallout of working with contenteditable.\n 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.\n
\n
\n With these changes our element will now also emit input and change events just like a built-in HTML form control.\n But, you may have noticed another issue has cropped up. The standard form reset button does not actually reset the form.\n
\n\n
Read the instructions
\n\n
\n You see, when we said static formAssociated = true we entered into a contract to faithfully implement the expected behavior of a form control.\n That means we have a bunch of extra work to do.\n
\n\n \n \n\n
\n There's a LOT going on there. It's too much to explain, so let me sum up.\n
\n
\n
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.
\n
The value property contains only the modified value and does not correspond to an attribute.
\n
The control can be marked disabled or read-only through attribute or property.
\n
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.
\n
\n\n
With some style
\n\n
\n Up to this point we've been using some stand-in styling.\n However, it would be nice to have some default styling that can be bundled with our custom form control.\n Something like this:\n
\n\n \n \n\n
\n The styles are isolated by scoping them to the name of our custom element, \n and the use of @layer puts them at the lowest priority, so that any user style will override the default style,\n just like for the built-in form controls. The use of variables offers an additional way to quickly restyle the control.\n
\n
\n In the styling we also see the importance of properly thinking out disabled and focused state behavior.\n 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.\n
\n
\n We're now past the 150 lines mark, just to get to the low bar of implementing the browser's mandatory form control behavior.\n 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.\n
\n\n
Validation
\n\n
\n Built-in form controls come with a validity API. To get an idea of what it means to implement it \n in a custom form control, let's add one validation attribute: required.\n It doesn't seem like it should take a lot of work, right?\n
\n\n \n \n
\n The code for the example is exactly like it would be for built-in controls:\n
\n \n\n
\n The ElementInternals interface is doing a lot of the work here, but we still have to proxy its methods and properties.\n You can tell however that by this point we're deep in the weeds of custom elements, because of the rough edges.\n
\n
\n
The example is using the input-inline:invalid style instead of :user-invalid because\n :user-invalid is not supported on custom elements yet.
\n
An ugly hack is needed to get the properly localized message for a required field that matches that of built-in controls.
\n
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.
\n
\n\n
In conclusion
\n\n
\n 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,\n but also that it is a path surrounded by peril as well as laborious to travel.\n Whether it is worth doing is in the eye of the beholder.\n
\n
\n Along that path we also learned some lessons on how to handle input in custom elements, and have proven yet again that contenteditable,\n while less painful than it once was, is an attribute that can only be used in anger.\n
\n
\n Regardless, the full source code of the input-inline form control is on GitHub.\n
\n At the code level, it looks something like this:\n
\n\n \n \n\n
\n How this works is that the browser takes a snapshot of the page when we call document.startViewTransition(),\n takes another snapshot after the callback passed to it is done (or the promise it returns fulfills),\n and then figures out how to smoothly animate between the two snapshots, using a fade by default.\n
\n
\n A very nice thing is that by putting a view-transition-name style on an element we can \n make it transition independently from the rest of the page, and we can control that transition through CSS.\n
\n \n \n
\n Now we can see a second square sliding in on the first click, and fading out on the second.\n
\n \n\n
\n That's enough view transition basics for now. If you're curious for more, \n you can learn the rest in the chrome developer documentation.\n
\n\n
Here comes trouble
\n\n
\n Up to this point, we've gotten the fair weather version of view transitions, but there are paper cuts.\n
\n
\n
Firefox doesn't support view transitions at all, so we have to feature-detect.
\n
There is only one actual current View Transitions standard, level 1, but most of the online tutorials talk about the unfinalized level 2.
\n
If there are duplicate values of view-transition-name anywhere on the page, the animations disappear in a puff of duplicate element error smoke.
\n
As always, there's a thing about shadow DOM, but more on that later.
\n
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.
\n
User input is blocked while the view is transitioning, causing frustration when clicks are ignored.
\n
The document.startViewTransition() function only accepts a single callback that returns a single promise.
\n
\n
\n It is the last one that really spells trouble. In a larger single-page web application we'll typically\n find a central routing layer that triggers a number of asynchronous updates every time the route changes.\n Wrapping those asynchronous updates into a single promise can be a challenge,\n as is finding the right place to \"slot in\" a call to document.startViewTransition().\n
\n
\n Also, we probably don't even want to wait for all of the asynchronous updates to complete.\n Leaving the application in an interactive state in between two smaller view transitions is better\n than bundling it all together into one ponderous picture perfect transition animation.\n
\n\n
What React did
\n\n
\n React being React they solve those problems through magic, through exceeding cleverness.\n You can read up on their approach to view transitions, \n but distilling it down it becomes this:\n
\n
\n
Anything that should take part separately in a view transition is wrapped in a <ViewTransition> component.
\n
React will choose unique view-transition-name style values, which DOM elements to set them on, and when to set them.\n This can be controlled through the <ViewTransition>name and key props.
\n
Any updates that should become part of a view transition are wrapped in a startTransition() call.
\n
React automatically figures out when to call document.startViewTransition(), and what updates to put inside the callback.\n It also cleverly avoids starting new transitions when one is already running, so startTransition() can be called from multiple places safely.\n Oh, and by the way, it feature detects, obviously.\n
\n Good luck figuring out how it works, \n or how to troubleshoot when the magic loses its shine.\n But that is the bar, that is the lofty goal of user experience to reach with a dumber and simpler reimagining as vanilla JS.\n So let's get cooking.\n
\n\n
A fresh start
\n\n
\n Our starting point is a barebones implementation of a startTransition()\n function to replace what React's startTransition() does.\n It will fall back to non-animated transitions if our browser doesn't support document.startViewTransition.\n
\n\n \n \n\n \n\n
\n While that takes care of feature-detecting, we can still run into timing issues.\n For example, let's say that instead of toggling we were switching routes,\n and the second route needs to load data prior to animating in.\n
\n We might intuitively choose to do something like this:\n
\n\n \n \n\n
\n But, as you see when trying it out, it doesn't work. Because the startTransition()\n calls end up overlapping each other, the animation is interrupted, and we get a jarring experience.\n 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.\n We also can't solve this by bundling everything into one single big view transition, because that would imply\n blocking user input while a network request completes, which would be a bad user experience.\n
\n
\n React solves all of this in the typical React way. It will smartly choose how to batch work\n into successive calls to document.startViewTransition(). It will take into account where something loads lazily,\n as in the previous example, and batch the work of animating in the content for the fallback in a separate view transition.\n
\n \n
Taking a queue
\n\n
\n Distilling that approach to its essence, the really useful part of React's solution is the queueing and batching of work. \n Any call to startTransition() that occurs while a view transition is running should be queued until after the transition completes,\n and nested calls should have all their updates batched together.\n
\n\n \n\n
\n The QueueingViewTransition implementation is a straightforward batching of callbacks,\n and a single call to document.startViewTransition() that executes them in order.\n It is not included in the text of this article for brevity's sake, but linked at the bottom instead.\n
\n
\n Applying that queueing solution on top of the previous example's unchanged code, \n we suddenly see the magic of clean view transitions between dynamically loading routes.\n
\n\n \n\n
Back to the top
\n\n
\n 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.\n Which brings me to the playground for that learning, a full port of React's tour-de-force <ViewTransition> example to vanilla web code.\n
\n\n \n\n
\n The full code of this example is on GitHub.\n Arguably the 300 lines of code in the lib/ folder of that example constitute a mini-framework,\n but fascinating to me is that you can get so much mileage out of such a small amount of library code,\n with the resulting single-page application being more or less the same number of lines as the React original.\n
\n
\n That example also shows how to do a purely client-side router with clean URLs using pushState().\n This blog post has however gone too long already, so I'll leave that for another time.\n
\n\n
One more thing
\n\n
\n Oh yeah, I promised to talk about the thing with shadow DOM, and I promised a custom element.\n Here is the thing with shadow DOM: when document.startViewTransition() is called from the light DOM,\n it cannot see elements inside the shadow DOM that need to transition independently, \n unless those elements are exposed as DOM parts and a view-transition-name style is set on them in the light DOM.\n
\n
\n If the solution to that intrigues you, it's in the GitHub example repo as well as a <view-transition> custom element.\n If that sounds like a bunch of mumbo jumbo instead, join the club.\n Just one more reason to avoid shadow DOM.\n
\n \n \n\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example1/app.js",
"content": "import { routerEvents, interceptNavigation } from './view-route.js';\n\ncustomElements.define('demo-app', class extends HTMLElement {\n\n #route = '/';\n\n constructor() {\n super();\n interceptNavigation(document.body);\n routerEvents.addEventListener('navigate', (e) => {\n this.#route = e.detail.url;\n this.update();\n });\n }\n\n connectedCallback() {\n this.update();\n }\n\n update() {\n if (this.#route === '/') {\n this.innerHTML = 'This is the homepage. Go to the details page.';\n } else if (this.#route === '/details') {\n this.innerHTML = 'This is the details page. Go to the home page.';\n } else {\n this.innerHTML = `The page ${this.#route} does not exist. Go to the home page.`;\n }\n this.innerHTML += ` Current route: ${this.#route}`;\n }\n});\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example1/index.html",
"content": "\n\n\n Example 1\n \n \n \n \n\n\n \n\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example1/view-route.js",
"content": "export const routerEvents = new EventTarget();\n\nexport const interceptNavigation = (root) => {\n // convert link clicks to navigate events\n root.addEventListener('click', handleLinkClick);\n // convert navigate events to pushState() calls\n routerEvents.addEventListener('navigate', handleNavigate);\n}\n\nconst handleLinkClick = (e) => {\n const a = e.target.closest('a');\n if (a && a.href) {\n e.preventDefault();\n const anchorUrl = new URL(a.href);\n const pageUrl = anchorUrl.pathname + anchorUrl.search + anchorUrl.hash;\n routerEvents.dispatchEvent(new CustomEvent('navigate', { detail: { url: pageUrl, a }}));\n }\n}\n\nconst handleNavigate = (e) => {\n history.pushState(null, null, e.detail.url);\n}\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example2/app.js",
"content": "import { routerEvents, interceptNavigation, matchesRoute } from './view-route.js';\n\ncustomElements.define('demo-app', class extends HTMLElement {\n\n #route = '/';\n\n constructor() {\n super();\n interceptNavigation(document.body);\n routerEvents.addEventListener('popstate', (e) => {\n const matches =\n matchesRoute('/details') || \n matchesRoute('/');\n this.#route = matches?.[1];\n this.update();\n });\n }\n\n connectedCallback() {\n this.update();\n }\n\n update() {\n if (this.#route === '/') {\n this.innerHTML = 'This is the homepage. Go to the details page.';\n } else if (this.#route === '/details') {\n this.innerHTML = 'This is the details page. Go to the home page.';\n } else {\n this.innerHTML = `The page ${this.#route} does not exist. Go to the home page.`;\n }\n this.innerHTML += ` Current route: ${this.#route}`;\n }\n});\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example2/index.html",
"content": "\n\n\n Example 2\n \n \n \n \n\n\n \n\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example2/view-route-partial.js",
"content": "const handleNavigate = (e) => {\n history.pushState(null, null, e.detail.url);\n routerEvents.dispatchEvent(new PopStateEvent('popstate'));\n}\n\n// update routes on popstate (browser back/forward)\nexport const handlePopState = (e) => {\n routerEvents.dispatchEvent(new PopStateEvent('popstate', { state: e.state }));\n}\nwindow.addEventListener('popstate', handlePopState);\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example2/view-route-partial2.js",
"content": "// ...\n\n// all routes will be relative to the document's base path\nconst baseURL = new URL(window.originalHref || document.URL);\nconst basePath = baseURL.pathname.slice(0, baseURL.pathname.lastIndexOf('/'));\n\n// returns an array of regex matches for matched routes, or null\nexport const matchesRoute = (path) => {\n const fullPath = basePath + '(' + path + ')';\n const regex = new RegExp(`^${fullPath.replaceAll('/', '\\\\/')}`, 'gi');\n const relativeUrl = location.pathname;\n return regex.exec(relativeUrl);\n}\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example2/view-route.js",
"content": "export const routerEvents = new EventTarget();\n\n// all routes will be relative to the document's base path\nconst baseURL = new URL(window.originalHref || document.URL);\nconst basePath = baseURL.pathname.slice(0, baseURL.pathname.lastIndexOf('/'));\n\nexport const interceptNavigation = (root) => {\n // convert link clicks to navigate events\n root.addEventListener('click', handleLinkClick);\n // convert navigate events to pushState() calls\n routerEvents.addEventListener('navigate', handleNavigate);\n}\n\nconst handleLinkClick = (e) => {\n const a = e.target.closest('a');\n if (a && a.href) {\n e.preventDefault();\n const anchorUrl = new URL(a.href);\n const pageUrl = basePath + anchorUrl.pathname + anchorUrl.search + anchorUrl.hash;\n routerEvents.dispatchEvent(new CustomEvent('navigate', { detail: { url: pageUrl, a }}));\n }\n}\n\nconst handleNavigate = (e) => {\n history.pushState(null, null, e.detail.url);\n routerEvents.dispatchEvent(new PopStateEvent('popstate'));\n}\n\n// update routes on popstate (browser back/forward)\nexport const handlePopState = (e) => {\n routerEvents.dispatchEvent(new PopStateEvent('popstate', { state: e.state }));\n}\nwindow.addEventListener('popstate', handlePopState);\n\n// returns an array of regex matches for matched routes, or null\nexport const matchesRoute = (path) => {\n const fullPath = path.startsWith('/') ? basePath + '(' + path + ')' : '(' + path + ')';\n const regex = new RegExp(`^${fullPath.replaceAll('/', '\\\\/')}`, 'gi');\n const relativeUrl = location.pathname;\n return regex.exec(relativeUrl);\n}\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example3/app.js",
"content": "import { interceptNavigation } from './view-route.js';\n\ncustomElements.define('demo-app', class extends HTMLElement {\n\n constructor() {\n super();\n interceptNavigation(document.body);\n }\n\n connectedCallback() {\n this.innerHTML = `\n \n This is the homepage. Go to the details page, or\n travel a path of mystery.\n \n \n This is the details page. Go to the home page.\n \n \n The page does not exist. Go to the home page.\n \n `\n }\n});\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example3/index.html",
"content": "\n\n\n Example 3\n \n \n \n \n\n\n \n\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example3/view-route-partial.js",
"content": "// ...\n\ncustomElements.define('view-route', class extends HTMLElement {\n\n #matches = [];\n\n get isActive() {\n return !!this.#matches?.length;\n }\n\n get matches() {\n return this.#matches;\n }\n\n set matches(v) {\n this.#matches = v;\n this.style.display = this.isActive ? 'contents' : 'none';\n if (this.isActive) {\n this.dispatchEvent(new CustomEvent('routechange', { detail: v, bubbles: true }));\n }\n }\n\n connectedCallback() {\n routerEvents.addEventListener('popstate', this);\n this.update();\n }\n\n disconnectedCallback() {\n routerEvents.removeEventListener('popstate', this);\n }\n\n handleEvent(e) {\n this.update();\n }\n\n static get observedAttributes() {\n return ['path'];\n }\n\n attributeChangedCallback() {\n this.update();\n }\n\n update() {\n const path = this.getAttribute('path') || '/';\n this.matches = this.matchesRoute(path) || [];\n }\n\n matchesRoute(path) {\n // '*' triggers fallback route if no other route on the same DOM level matches\n if (path === '*') {\n const activeRoutes = \n Array.from(this.parentNode.getElementsByTagName('view-route')).filter(_ => _.isActive);\n if (!activeRoutes.length) return [location.pathname, '*'];\n // normal routes\n } else {\n return matchesRoute(path);\n }\n return null;\n }\n});\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example3/view-route.js",
"content": "export const routerEvents = new EventTarget();\n\n// all routes will be relative to the document's base path\nconst baseURL = new URL(window.originalHref || document.URL);\nconst basePath = baseURL.pathname.slice(0, baseURL.pathname.lastIndexOf('/'));\n\nexport const interceptNavigation = (root) => {\n // convert link clicks to navigate events\n root.addEventListener('click', handleLinkClick);\n // convert navigate events to pushState() calls\n routerEvents.addEventListener('navigate', handleNavigate);\n}\n\nconst handleLinkClick = (e) => {\n const a = e.target.closest('a');\n if (a && a.href) {\n e.preventDefault();\n const anchorUrl = new URL(a.href);\n const pageUrl = basePath + anchorUrl.pathname + anchorUrl.search + anchorUrl.hash;\n routerEvents.dispatchEvent(new CustomEvent('navigate', { detail: { url: pageUrl, a }}));\n }\n}\n\nconst handleNavigate = (e) => {\n history.pushState(null, null, e.detail.url);\n routerEvents.dispatchEvent(new PopStateEvent('popstate'));\n}\n\n// update routes on popstate (browser back/forward)\nexport const handlePopState = (e) => {\n routerEvents.dispatchEvent(new PopStateEvent('popstate', { state: e.state }));\n}\nwindow.addEventListener('popstate', handlePopState);\n\n// returns an array of regex matches for matched routes, or null\nexport const matchesRoute = (path) => {\n const fullPath = path.startsWith('/') ? basePath + '(' + path + ')' : '(' + path + ')';\n const regex = new RegExp(`^${fullPath.replaceAll('/', '\\\\/')}`, 'gi');\n const relativeUrl = location.pathname;\n return regex.exec(relativeUrl);\n}\n\ncustomElements.define('view-route', class extends HTMLElement {\n\n #matches = [];\n\n get isActive() {\n return !!this.#matches?.length;\n }\n\n get matches() {\n return this.#matches;\n }\n\n set matches(v) {\n this.#matches = v;\n this.style.display = this.isActive ? 'contents' : 'none';\n if (this.isActive) {\n this.dispatchEvent(new CustomEvent('routechange', { detail: v, bubbles: true }));\n }\n }\n\n connectedCallback() {\n routerEvents.addEventListener('popstate', this);\n this.update();\n }\n\n disconnectedCallback() {\n routerEvents.removeEventListener('popstate', this);\n }\n\n handleEvent(e) {\n this.update();\n }\n\n static get observedAttributes() {\n return ['path'];\n }\n\n attributeChangedCallback() {\n this.update();\n }\n\n update() {\n const path = this.getAttribute('path') || '/';\n this.matches = this.matchesRoute(path) || [];\n }\n\n matchesRoute(path) {\n // '*' triggers fallback route if no other route on the same DOM level matches\n if (path === '*') {\n const activeRoutes = \n Array.from(this.parentNode.getElementsByTagName('view-route')).filter(_ => _.isActive);\n if (!activeRoutes.length) return [location.pathname, '*'];\n // normal routes\n } else {\n return matchesRoute(path);\n }\n return null;\n }\n});\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example4/404.html",
"content": "\n\n\n \n\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/example4/index-partial.html",
"content": "\n\n\n \n\n\n \n \n \n\n"
},
{
"path": "public/blog/articles/2025-06-25-routing/index.html",
"content": "\n\n\n Clean client-side routing\n \n \n \n \n \n\n\n \n \n
Clean Client-side Routing
\n
Joeri Sebrechts
\n \n \n
\n The main Plain Vanilla tutorial explains two ways of doing client-side routing.\n Both use old school anchor tags for route navigation.\n First is the traditional multi-page approach described on the Sites page as one HTML file per route,\n great for content sites, not so great for web applications.\n Second is the hash-based routing approach decribed on the Applications page, one custom element per route,\n better for web applications, but not for having clean URLs or having Google index your content.\n
\n
\n In this article I will describe a third way, single-file and single-page but with clean URLs using the pushState API,\n and still using anchor tags for route navigation.\n The conceit of this technique will be that it needs more code, and the tiniest bit of server cooperation.\n
\n
Intercepting anchor clicks
\n
\n 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.\n Our SPA can then respond to these events by updating its routes.\n
\n\n \n\n
\n In an example HTML page we can leverage this to implement routing in a <demo-app></demo-app> element.\n
\n The first thing we're doing in view-route.js is the interceptNavigation() function.\n 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.\n Then it also adds a navigate event listener that will update the browser's URL by calling pushState.\n
\n
\n In app.js we can listen to the same navigate event to actually update the routes.\n Suddenly we've implemented a very basic in-page routing, but there are still a bunch of missing pieces.\n
\n\n
There and back again
\n\n
\n For one, browser back and forward buttons don't actually work.\n We can click and see the URL update in the browser, but the page does not respond.\n In order to do this, we need to start listening to popstate events.\n
\n
\n However, this risks creating diverging code paths for route navigation, one for the navigate event and one for the popstate event.\n Ideally a single event listener responds to both types of navigation.\n A simplistic way of providing a single event to listen can look like this:\n
\n \n
\n Now our views can respond to popstate events and update based on the current route.\n A second question then becomes: what is the current route? The popstate event does not carry that info.\n 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.\n What is needed is a way of easily parsing it, something like this:\n
\n \n
\n The matchesRoute() function accepts a regex to match as the route,\n and will wrap it so it is interpreted relative to the current document's URL,\n making all routes relative to our single page.\n Now we can clean up the application code leveraging these new generic routing features:\n
\n Opening that in a separate tab we can see that the absolute URL neatly updates with the routes,\n that browser back/forwards navigation updates the view, and that inside the view the route is\n relative to the document.\n
\n
\n Because matchesRoute() accepts a regex,\n it can be used to capture route components that are used inside of the view.\n Something like matchesRoute('/details/(?<id>[\\\\w]+)') would\n put the ID in matches.groups.id. It's simple, but it gets the job done.\n
\n\n
Can you use it in a sentence?
\n\n
\n While this rudimentary way of detecting routes works, adding more routes quickly becomes unwieldy.\n It would be nice to instead have a declarative way of wrapping parts of views inside routes.\n Enter: a custom element to wrap each route in the page's markup.\n
\n \n
\n Now we can rewrite our app to be a lot more declarative, while preserving the behavior.\n
\n While things now look like they work perfectly, the illusion is shattered upon reloading the page when it is on the details route.\n To get rid of the 404 error we need a handler that will redirect to the main index page.\n This is typically something that requires server-side logic, locking us out from simple static hosting like GitHub Pages,\n but thanks to the kindness of internet strangers, there is a solution.\n
\n
\n It involves creating a 404.html file that GitHub will load for any 404 error (the tiny bit of server cooperation).\n In this file the route is encoded as a query parameter, the page redirects to index.html,\n and inside that index page the route is restored.\n
\n \n \n\n
\n Adding this last piece to what we already had gets us a complete routing solution for vanilla single page applications\n that are hosted on GitHub Pages. Here's a live example hosted from there:\n
\n \n\n
\n To full code of view-route.js and of this example is on GitHub.\n
\n \n \n\n"
},
{
"path": "public/blog/articles/2025-07-13-history-architecture/index.html",
"content": "\n\n\n The history of web application architecture\n \n \n \n \n \n\n\n \n \n
The history of web application architecture
\n
Joeri Sebrechts
\n \n \n
\n 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.\n That means I was there for the whole ride, the entire history of web application architecture, \n from the before times to the present day.\n So this post will be an overview of the various ways to make a web app, past and present, \n and their relative trade-offs as I experienced them.\n
\n
\n Just to set expectations right: this will cover architectures targeted primarily at proper applications, \n of the sort that work with user data, and where most screens have to be made unique based on that user data.\n Web sites where the different visitors are presented with identical pages are a different beast.\n Although many of these architectures overlap with that use case, it will not be the focus here.\n
\n
\n Also, while I will be mentioning some frameworks, they are equally not the focus.\n Where you see a framework, you can slot in vanilla web development with a bespoke solution.\n
\n
\n This will be a long one, so grab a snack, take some time, and let's get going.\n
\n\n
Before time began
\n
\n Back when people first went online, the ruling architecture was offline-first.\n It looked sort of like this:\n
\n \n
\n Our user would have a proper desktop application, written in C or C++ most likely,\n and that would work with local files on their local file system, all perfectly functional when offline.\n When they wanted to \"go online\" and share their work, they would dial in to the internet,\n start their e-mail client and patiently send an e-mail to their friend or colleague containing \n a copy of their file as an attachment.\n
\n
\n This architecture was very simple, and it worked well in the absence of a reliable and fast internet connection.\n This was a good thing because at the time most people never had a reliable and fast internet connection.\n There were problems though. For one, the bootstrapping problem: how do you get everyone to have the application \n installed so they can open and edit the file they received via e-mail?\n Also, the syncing problem: how are changes kept in sync between multiple devices and users?\n Merging edits from different files that could have weeks of incompatible edits was always \n somewhere between frustrating and impossible.\n
\n\n
Traditional server-side rendering
\n
\n Web applications promised they would solve both problems. At first we built them like this:\n
\n \n
\n The first thing we did was move all of the stuff from all of the users into a central database somewhere online.\n Because this database was shared between the users, it became a lot more easy to keep their changes in sync.\n If one user made an edit to something, everyone else would see it on the next refresh.\n
\n
\n To allow users to actually get at this database we had to give them an application to do it.\n This new-fangled thing called a web application running on a web application server would take http requests\n coming from the user's browser, SQL query the database for the right set of stuff, \n and send back an entire web page. Every click, every submit, it would generate a whole new page.\n
\n
\n Deployment of those early web applications was often suspiciously simple:\n someone would connect via FTP to a server, and copy over the files from their local machine.\n There often weren't even any build steps. There was no step 3.\n
\n
\n On the one hand this architecture was convenient. It solved the bootstrapping problem \n by only demanding that each user have a web browser and an internet connection.\n It also moved all of the application logic over to the server, keeping it neatly in one place.\n Crucially it kept the browser's task minimal, important in an era where browsers were much less capable\n and PC's were orders of magnitude slower than today. If done well, it could even be used to make\n web applications that still worked with JavaScript disabled. My first mobile web app was like that,\n sneakily using HTML forms with multiple submit actions and hidden input fields\n to present interactive navigation through a CRUD interface.\n
\n
\n On the other hand, it had many problems, especially early on. HTML wasn't very good, CSS was in its infancy,\n and early JavaScript was mostly useless. It was hard going building anything at all on the early web.\n On top of that, web developers were a new breed, and they had to relearn many of the architecture lessons their desktop developer\n colleagues had already learned through bitter experience. For example, everyone has heard of the adage\n \"If you don't choose a framework, you'll end up building a worse one yourself.\" That is because for the first few years\n building your own terrible framework as you went was the norm, until everyone wisened up and started preaching this wisdom. \n For sure, my own first experiments in web application development in PHP 3 and 4 were all \n without the benefit of a proper framework.\n
\n
\n Web developers also had to learn lessons that their desktop counterparts never had to contend with.\n Moving the application to the server was convenient, but it exposed it to hackers from all across the world,\n and the early web application landscape was riddled with embarrassing hacks.\n Because the threat level on the internet keeps rising this remains a major headache to this day.\n
\n
\n Another novel problem was having to care a whole lot about connectivity and server uptime.\n Because users literally couldn't do anything at all if they didn't have a connection to a working web server,\n making sure that connection was always there became a pervasive headache.\n Going to a site and seeing an error 500 message was unsurprisingly common in those early years.\n
\n
\n The biggest problems however were throughput, bandwidth and latency. Because almost every click had to reload the whole page,\n doing anything at all in those early web applications was slow, like really, really slow.\n At the time, servers were slow to render the page, networks slow to transport it, and PC's and browsers slow to render.\n That couldn't stand, so something had to change. It was at this point that we saw a fork in the road,\n and the web developer community split up into two schools of thought that each went their own way.\n Although, as you will see, they are drawing closer again.\n
\n\n
Modern server-side rendering
\n\n
\n One branch of the web development tree doubled down on server-side rendering,\n building further on top of the existing server-side frameworks.\n
\n \n
\n They tackled the problems imposed by throughput and latency by\n moving over to a model of partial page updates, where small bits of user-activated JavaScript\n (originally mostly built with jQuery) would update parts of the page with HTML partials\n that they fetched from the server.\n
\n
\n The evolution of this architecture are so called LiveViews.\n This is a design first popularized by the Phoenix framework for the obscure Elixir programming language,\n but quickly adopted in many places.\n
\n
\n It uses framework logic to automatically wire up server-side generated templates with bits of JavaScript\n that will automatically call the server to fetch partial page updates when necessary.\n The developer has the convenience of not thinking about client-side scripting, \n while the users get an interactive user experience similar to a JavaScript-rich frontend.\n Typically the client keeps an open websocket connection to the server,\n so that server-side changes are quickly and automatically streamed into the page as soon as they occur.\n
\n
\n This architecture is conceptually simple to work with as all the logic remains on the server.\n It also doesn't ask much from the browser, good for slow devices and bandwidth-constrained environments.\n As a consequence it finds a sweet spot in mostly static content-driven web sites.\n
\n
\n But nothing is without trade-offs. This design hits the server on almost every interaction and has no path to offline functionality.\n Network latency and reliability are its UX killer, and especially on mobile phones – the main way people interact with web apps these days –\n those can still be a challenge. While this can be mitigated somewhat through browser caching, the limitation is always there.\n After all, the more that page content is dictated by realtime user input, the more necessary it becomes to push logic to the client.\n In cases where the network is good however, it can seem like magic even for highly interactive applications, \n and for that reason it has its diehard fans.\n
\n\n
Client-side rendering
\n
\n There was another branch of web development practice, let's say the ones who were fonder\n of clever architecture, who had a crazy thought: what if we moved rendering data to HTML from the server to the browser?\n They built new frameworks, in JavaScript, designed to run in the browser\n so that the application could be shipped as a whole as part of the initial page load, \n and every navigation would only need to fetch data for the new route.\n In theory this allowed for smaller and less frequent roundtrips to the server,\n and therefore an improvement to the user experience.\n Thanks to a blooming cottage industry of industry insiders advertising its benefits, it became the dominant architecture for new web applications,\n with React as the framework of choice to run inside the browser.\n
\n
\n This method taken to its modern best practice extreme looks like this:\n
\n \n
\n It starts out by moving the application, its framework, and its other dependencies over to the browser.\n When the page is loaded the entire bundle gets loaded, and then pages can be rendered as routes inside of the single-page application.\n Every time a new route needs to be rendered the data gets fetched from the server, not the HTML.\n
\n
\n The web application server's job is now just providing the application bundle as a single HTML page,\n and providing API endpoints for loading JSON data for every route. \n Because those API endpoints naturally end up mirroring the frontend's routes this part usually gets called the backend-for-frontend.\n 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. \n Express on node became a very popular choice, as it allowed a great deal of similarity between browser and server codebases,\n although in practice there's usually not much actual code in common.\n
\n
\n For security reasons – after all, the web application servers are on the increasingly dangerous public internet –\n the best practice became to host backends-for-frontend in a DMZ, a demilitarized zone\n where the assumption has to be that security is temporary and hostile interlopers could arrive at any time.\n In addition, if an organization has multiple frontends (and if they have a mobile app they probably have at least two),\n then this DMZ will contain multiple backends for frontend.\n
\n
\n Because there is only a single database to share between those different BFFs, \n and because of the security risks of connecting to the database from the dangerous DMZ,\n a best practice became to keep the backend-for-frontend focused on just the part of serving the frontend,\n and to wrap the database in a separate thing. This separate microservice\n is an application whose sole job is publishing an API that gatekeeps access to the database.\n This API is usually in a separate network segment, shielded by firewalls or API gateways,\n and it is often built in yet another framework better tailored for building APIs, \n or even in a different programming language like Go or C#.\n
\n
\n Of course, having only one microservice is kind of a lonely affair, \n so even organizations of moderate size would often end up having their backends-for-frontend each talking to multiple microservices.\n
\n
\n That's just too many servers to manage, too many network connections to configure, too many builds to run, \n so people by and large stopped managing their own servers, either for running builds or for runtime hosting.\n Instead they moved to the cloud, where someone else manages the server, and hosted their backends\n as docker containers or serverless functions deployed by git-powered CI/CD pipelines.\n This made some people fabulously wealthy. After all, 74% of Amazon's profit is made from AWS,\n and over a third of Microsoft's from Azure.\n It is no accident that there is a persistent drumbeat that everyone should move everything to the cloud.\n Those margins aren't going to pad themselves.\n
\n
\n Incidentally, microservices as database intermediary are also a thing in the world of server-side rendered applications,\n but in my personal observation those teams seem to choose this strategy less often.\n Equally incidentally, the word serverless in the context of serverless functions was and is highly amusing to me, \n 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.)\n
\n
\n On paper this client-side rendered architecture has many positive qualities. It is highly modular,\n which makes the work easy to split up across developers or teams. It pushes page rendering logic into\n the browser, creating the potential to have a low latency and high quality user experience.\n The layered nature of the backend and limited scope of the internet-facing backend-for-frontend forms\n a solid defensive moat against cyberattacks. And the cloud-hosted infrastructure is low effort to manage and easy to scale.\n A design like this is every architecture astronomer's dream, and I was for a while very enamored with it myself.\n
\n
\n In practice though, it just doesn't work very well. It's just too complicated.\n For larger experienced teams in large organizations it can kind of sort of make sense,\n and it is no surprise that big tech is a heavy proponent of this architecture.\n But step away from web-scale for just a second and there's too many parts to build and deploy and keep track of,\n too many technologies to learn, too many hops a data request has to travel through. \n
\n
\n The application's logic gets smeared out across three or more independent codebases,\n and a lot of overhead is created in keeping all of those in sync.\n Adding a single data field to a type can suddenly become a whole project. For one application I was working on\n I once counted in how many places a particular type was explicitly defined, and the tally reached lucky number 7.\n It is no accident that right around the time that this architecture peaked the use of monorepo tools \n to bundle multiple projects into a single repository peaked as well.\n
\n
\n Go talk to some people just starting out with web development\n and see how lost they get in trying to figure out all of this stuff, \n learning all the technologies comprising the Rube Goldberg machine that produces a webpage at the end.\n See just how little time they have left to dedicate to learning vanilla HTML, CSS and JS, \n arguably the key things a beginner should be focusing on.\n
\n
\n Moreover, the promise that moving the application entirely to the browser would improve the user experience mostly did not pan out.\n 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.\n The slowest quintile of devices and network connections struggled mightily with these heavy JavaScript payloads.\n It was hoped that Moore's law would solve this problem, but the dynamics of how (mobile) device and internet provider markets work\n 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 \n with this architecture, but you're starting from behind. Well, at least for public-facing web applications.\n
\n\n
Client-side rendering with server offload
\n
\n The designers of client-side frameworks were not wholly insensitive to the frustrations of developers \n trying to make client-side rendered single-page applications work well on devices and connections \n that weren't up to the job. They started to offload more and more of the rendering work back to the server.\n In situations where the content of a page is fixed, static site generation can execute\n the client-side framework at build time to pre-render pages to HTML.\n And for situations where content has a dynamic character, server-side rendering was reintroduced \n back into the mix to offload some of the rendering work back to the server.\n
\n
\n The current evolution of these trends is the streaming single-page application:\n
\n \n\n
\n In this architecture the framework runs the show in both backend-for-frontend and in the browser.\n It decides where the rendering happens, and only pushes the work to the browser that must run there.\n When possible the page is shipped prerendered to the browser and the code for the prerendered parts \n is not needed in the client bundle.\n Because some parts of the page are more dynamic than others, they can be rendered on-demand in the server \n and streamed to the browser where they are slotted into the prerendered page.\n The bundle that is shipped to the browser can be kept light-weight because it mostly just needs \n to respond to user input by streaming the necessary page updates from the server over an open websocket connection.\n
\n
\n If that sounds suspiciously like the architecture for modern server-side rendering that I described before,\n that is because it basically is. While a Next.JS codebase is likely to have some\n client-rendered components still, the extreme of a best practice Astro codebase would \n see every last component rendered on the server. \n In doing that they arrive at something functionally no different from LiveView architecture,\n and with a similar set of trade-offs. These architectures are simpler to work with, but they \n perform poorly for dynamic applications on low reliability or high latency connections,\n and they cannot work offline.\n
\n
\n Another major simplication of the architecture is getting rid of the database middleman.\n Microservices and serverless functions are not as hyped as they were, \n people are happy to build so-called monoliths again, \n and frameworks are happy to recommend they do so.\n The meta-frameworks now suggest that the API can be merged into the web application frontend, \n and the framework will know that those parts are only meant to be run on the server.\n This radically simplifies the codebase, we're back to a single codebase for the entire application\n managed by a single framework.\n
\n
\n However, TANSTAAFL. This simplification comes at the expense of other things. The Next.JS documentation may claim\n \"Since Server Components are rendered on the server, you can safely make database queries using an ORM or database client.\"\n 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.\n Defense in depth was a good idea, and we're back to trading security for simplicity.\n There were other reasons that monoliths once fell out of favor. It's like we're now forgetting lessons that were already learned.\n
\n\n
Where does that leave us?
\n\n
\n So, which architecture should you pick? I wish I could tell you,\n but you should have understood by now that the answer was always going to be it depends.\n Riffing on the work of Tolstoy: all web architectures are alike in that they are unhappy in their own unique way.\n
\n
\n In a sense, all of these architectures are also unhappy in the same way:\n there's a whole internet in between the user and their data.\n There's a golden rule in software architecture: you can't beat physics with code.\n We draw the internet on diagrams as a cute little cloud, pretending it is not a physical thing.\n But the internet is wires, and antennas, and satellites, and data centers, and all kinds of physical things and places.\n Sending a signal through all those physical things and places will always be somewhat unreliable and somewhat slow.\n We cannot reliably deliver on the promise of a great user experience as long as we put a cute little cloud \n in between the user and their stuff.\n
\n
\n In the next article I'll be exploring an obscure but very different architecture,\n a crazy thought similar to that of client-side rendering:\n what happens when we move the user's data from the server back into the client?\n What is local-first web application architecture?\n
\n Previously in the history of web application architecture \n I covered the different ways that people have tried to build web applications, and how all of them came with \n their own unique set of drawbacks.\n Also mentioned was how there is one drawback that they all share: \n there is a whole internet between a user and their data,\n and this makes it hard to deliver a top notch user experience.\n
\n\n
Tail latency matters
\n
\n On the surface, it doesn't seem like this should be the case. Networks are fast, right?\n But the truth is, they're only fast for some of the people some of the time.\n
\n
\n Look at the page load numbers (LCP) of this website for the last week (gathered anonymously):\n
\n
\n
P50: 650 ms
\n
P75: 1200 ms
\n
P90: 2148 ms
\n
P99: 10,636 ms
\n
\n
\n While half of the visits see page load times well below a second,\n many see times that are much, much higher. Part of this is due to geography.\n Going through Azure's P50 roundtrip latency times we can see that\n some remote connections, like France to Australia, are in the 250 ms range, data center to data center.\n Azure doesn't disclose P99 latency, but one may assume it is a multiple of the P50 latency.\n
\n
\n But our user isn't sitting in a data center, they're probably on a mobile phone,\n connecting through a slow network. Looking at mozilla's minimum latency numbers \n we can see that it's not unusual to see another 100 ms of roundtrip latency added by the mobile network,\n 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,\n and trying to get some work done, is that the web can slow to a crawl as I pass through dead zones.\n This is in a densely populated area in a rich country on the most expensive cell service provider. \n Most people do not have these same luxuries.\n
\n
\n So it's not unusual to see latencies climb far above the threshold of 100 ms,\n commonly regarded as the threshold for an immediate response.\n For an unlucky minority of users latencies can even climb above half a second.\n This matters because if we have to hit the server to do something with the user's data \n on every click, we will have noticeable and frustrating delay in the interaction.\n To get a feel of this delay, here's a simulator where you can try out roundtrip latencies\n from 50 ms to one second:\n
\n \n
\n Can you tell how much nicer 100 ms and below feel?\n How the buttons actually feel lighter to press?\n By contrast, 500 ms and above of roundtrip latency are just a slog, painful to use.\n The buttons are heavy and cumbersome. This is human psychology at work,\n and these lessons were learned in the desktop era but forgotten and never quite relearned for the web.\n If we put over 100 ms of latency in between a user's click and the resulting effect\n they will feel some degree of frustration, and we know that the internet cannot deliver below 100 ms of roundtrip latency\n except in the luckiest of cases.\n
\n \n
Solutions
\n\n
\n We can use some kind of closer-to-the-user cache,\n in the form of a CDN or a browser cache or a service worker. This allows the content that needs to be loaded \n based on the user's click to be fetched from something that has a better shot at being below that magic 100 ms\n of latency. But this only works if what we need to load can be cached,\n and if we can afford to cache it. For a web application that works with user data, this is typically not the case.\n
\n
\n We can host the application in a georedundant way, have application servers\n across the world and use a georedundant database like Google Spanner or Azure Cosmos DB. \n This quickly gets complicated and expensive, and can only be achieved \n through a great amount of vendor lock-in. Crucially, it probably does not get us past the 100 ms barrier anyway.\n
\n
\n We can render client-side, using JavaScript to create and update the HTML page,\n so that an update on the screen can happen immediately after the user's click.\n But this only works if what the user is doing is not updating a piece of server-side data.\n Otherwise we have to show some kind of loading or saving indicator until the server responds, \n and then we're back to roundtrip latency.\n
\n
\n Bottom line, and once again: the basic problem is that the internet is in between the user and their data.\n So what if we moved the data to the user?\n
\n\n
Local-first
\n\n
\n This concept has been around for a while and it is known as a local-first application.\n To apply it to the web, let's start from the basic design of a client-side rendered web application\n as covered in the previous article:\n
\n \n
\n This design does not need the server for rendering, so it has the theoretical potential to hit 100 ms.\n But because the user's interactions have to fetch data from the remote database and update it as well – \n a database sitting multiple network hops away –\n in practice we rarely actually hit that low latency.\n We can move the data to the user by doing something like this:\n
\n \n
\n The user's data gets duplicated into a local IndexedDB. More than duplicated actually as\n this becomes the only copy of the data that the user will interact with directly.\n The backend-for-frontend and API that used to gatekeep access to this data similarly get moved into the client,\n as part of a service worker. This worker code can be very similar to what the server-side version would be, \n it can even reuse express (although it probably shouldn't).\n Because the service worker's API for all intents and purposes looks like a server-side API to the frontend codebase,\n that frontend can be built in all the usual ways, \n except now with the guarantee that every server roundtrip completes in milliseconds.\n
\n
\n To avoid slow page loads each time the web application is opened\n it also needs to be cached locally as part of the service worker.\n By packaging this as a progressive web app installs become possible onto the user's home screen,\n giving an experience not that unlike installing a native mobile app.\n The application server's job is now reduced to only providing that initial application install,\n and it can become a simple (and free) static web host.\n
\n \n
Here comes trouble
\n
\n Both the application and the data are now running locally,\n meaning the user doesn't need the network at all to get things done.\n This isn't just local-first, it is offline-first.\n But like all things in software architecture, we are trading one set of problems for another.\n
\n
\n There still needs to be a way to get data onto other devices, or to other users,\n or simply backed up into the cloud. That means the service worker also gets the job of\n (asynchronously) uploading changes to a server API which will store it in a database,\n as well as pulling server-side changes back down. The server-side version acts as the master copy,\n and the server-side API gets the thankless job of merging client-side changes with it.\n
\n
\n Not so fast though. Our user might be editing offline for a considerably long time,\n and the data on the server may have been changed in the meanwhile from another device or by another user.\n The job of merging those changes can be ... complicated.\n A good strategy is needed for merging. A possible path is to use CRDT algorithms from a library like \n automerge, as suggested by the local-first article linked above.\n However, for many cases a simpler bespoke algorithm that is aware of the specific data types being merged probably works well enough,\n as I discovered when making an offline-capable work orders web application that used this strategy.\n
\n
\n As the local-first application is now directly talking to this API,\n it needs a way to authenticate. This can be a reason to still have a minimal \n backend-for-frontend on the server. An alternative is to use a separate \n OpenID Connect identity provider with a PKCE authorization flow to obtain an access token.\n PKCE is an authorization flow developed for use by mobile apps but also usable by web apps \n that enables secretless API authentication.\n
\n
\n Another major caveat is that the entire codebase needs to be on the client,\n which necessitates keeping it under a tight performance and size budget.\n Careful curation of dependencies is key, and a javascript footprint that runs in the megabytes is verboten.\n Vanilla web development can be a solution here, with its emphasis on using the platform to its limits\n without bringing in dependencies. A lightweight framework like Lit or Preact will do as well.\n
\n
\n This isn't just a theoretical exercise. The team at Superhuman built their better gmail than gmail \n more or less as described here, using React as the framework, and the thing that sets their web app apart is its blistering speed.\n You can go read how they did it on their blog (part 1, \n part 2) or listen to the retelling on the \n Syntax podcast.\n
\n\n
Loco-first
\n\n
\n But we can push it even further, in theory at least. In the previous iteration of the architecture we still have\n the application-specific database and syncing logic on the server,\n but what if we instead did away with every last piece of server-side application logic?\n
\n \n
\n The syncing engine now gets moved in the client, and what it uploads to the server are just files.\n That means all we need is a generic cloud drive, like Dropbox or Onedrive.\n These cloud drive services often support cross-origin API access with OpenID Connect authentication using PKCE.\n That means the service worker in the client doesn't need any application servers to upload its data\n to the cloud storage.\n
\n
\n The onboarding experience becomes a choice screen where the user picks their cloud drive option.\n The application will redirect the user to the Dropbox or Onedrive or <insert vendor here> login page,\n and obtains an access token using PKCE authorization flow that is persisted locally.\n This token is used to connect to the user's cloud drive from inside the service worker.\n The application will bootstrap itself from whatever files are already in the drive,\n and will regularly synchronize with the current contents of the drive using its service worker logic.\n
\n
\n Instead of a cloud drive, another option is the use of the File System Access API to get a handle to a local folder.\n 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.\n This solution allows the app to have complete privacy, as the user's data never leaves their device\n or network. The caveat is incomplete browser support.\n Come on Safari and Firefox, do your bit, for privacy!\n
\n
\n 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.\n 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.\n If they are, it downloads updates and merges them into the local IndexedDB.\n 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 \n and presenting its copy to merge, it is the service worker going to each device's copy and checking if it needs merging.\n
\n
\n There is no longer a master copy of the data, only one copy per device, all on equal footing,\n with an eventual consistency arising out of the devices merging from each other's copies.\n This is the same philosophy as CRDTs, or of the Operational Transformation algorithm that underpins Google Docs.\n No matter though, when you get deep enough into consistency models (I recommend Aphyr's writings\n or Martin Kleppmann's book), \n you'll realize that there is never such as a thing as a reliable master copy in a distributed system, \n even in cases where there is a central database.\n
\n
\n A multi-user scenario can be realized by our user subscribing to someone else's shared cloud drive folder,\n where the other user shares their copy of the data as read-only. When Alice shares her folder with Bob,\n Bob shares his with Alice, and they both subscribe to each other's updates, \n then they can work on a shared document without ever having given each other direct write access.\n
\n
\n As this application has no servers outside of the lightly loaded static web host, which in 2025 is free to host even at scale,\n the hosting cost drops to zero almost regardless of the number of users. The cloud drive costs are carried by each user individually,\n only responsible for their own share of storage. The only hosting cost to the application's owner would be the domain name.\n The climate footprint is minimal.\n
\n
\n By eliminating the central database and its adjoining server-side logic it also eliminates the main target for hackers.\n Because compromises can only occur one user at a time they lack a sufficient reward for hacking the application.\n On top of that, the only servers are the static web host and the major cloud drive vendors,\n both practically impossible to hack. This web app would be highly secure and remain secure with barely any maintenance.\n
\n
\n This architecture would be a cloud vendor's worst nightmare if it ever became popular,\n as they cannot earn a dime from it (aside from the basic cloud drive pennies).\n Thankfully for them, it is impossible to monetize for the company that builds such a web app as well.\n No server == no revenue opportunity. For now this is just a crazy theoretical exercise, \n far removed from where the leading frontend architecture voices are driving us, \n but the possibility fascinates me.\n
\n Design has never been the part of building for the web that I felt comfortable with.\n I would hide behind the shorthand \"I'm not a designer\" and just use someone else's design,\n or throw something together that I wasn't happy with.\n The original design of Plain Vanilla was shipped very much in that not-happy-with-it mindset.\n
\n
\n So when I decided to finally take a web design course, settling on DesignAcademy.io\n 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. \n This article documents how and why the new design came about.\n
\n
\n The course starts out by making you really think about the content that you want to apply a design to.\n They challenge you to make your web page work as a google doc, so I did precisely that.\n In revisiting the landing page and thinking through its text, about half of the characters were cut,\n without losing any of the meaning.\n
\n
\n Lesson 1: less is more.\n
\n
\n The next challenge the course throws at you is to decide on a style and to gather inspiration for your design.\n What I wanted the design of Plain Vanilla to communicate was a sort of timelessness,\n like a manual from an earlier time, that at the same time feels simple and fresh.\n In looking for inspiration I settled on Swiss style,\n the 1950's minimalist style that manages to feel modern and old at the same time.\n I absolutely adore the old manuals from the 50's, as in the image at the top of this page,\n where minimalist design relying heavily on typography and spacing brings the content to the foreground.\n
\n
\n With this style and many googled-together examples of it as inspiration in hand, I took on the next challenge:\n make a first sketch of the design by simply copy pasting together elements of web sites and imagery\n that inspired you into a rough first outline. The second half of the challenge:\n take that design and layer your content over it. The result of this exercise was the initial redesign.\n Notice how the left half is literally copy pasted together bits of screenshots.\n
\n \n
\n Lesson 2: taking ideas from everywhere is a quick way to get started.\n
\n
\n The rest of the course was a series of design exercises on top of that initial draft, \n to choose fonts, colors, imagery, to apply a grid system and figure out spacing, and to sort out the finer aspects.\n Some elements of the initial redesign survived this process, others didn't, and what I ended up with\n in the final Affinity Designer file is pretty close to the shipping redesign.\n
\n \n
\n Lesson 3: design doesn't have to be intimidating if you have the right process.\n
\n
\n The actual work of translating of the design to code wasn't all that complicated.\n There was already a good baseline of semantic markup, so the redesign ended up mostly constrained\n to central CSS changes. Most of the time was taken up by responsiveness, something absent from the design mockup.\n Many of the final decisions on the exact behavior were made to favor code simplicity.\n This is for example why I decided not to add animations.\n
\n
\n This is also why I chose the popover API as the strategy for having a responsive hamburger menu on small screens.\n While the popover API presently only has 87% support on caniuse.com, I felt that for the audience of this site\n support should be sufficient, and the dramatic code simplification it allowed was undeniable.\n The nav menu works without any JavaScript. It presents as a toggled menu by default,\n and uses CSS to become permanently visible on larger screens.\n
\n \n
\n This was also a good opportunity to revisit the website's content.\n As it turns out, not a lot needed to change. Web standards don't actually change that often.\n I did update some parts where evolving baseline support took away caveats \n (for example, CSS nesting is now safe to use), and added some links to newly baseline \n features like popover, dialog and mutually-exclusive details.\n
\n
\n Lesson 4: when you build on top of web standards, you don't need to do a lot of maintenance.\n
\n
\n In the end, I'm finally happy with the design of Plain Vanilla.\n I still haven't gotten around to adding a dark mode, but it's on the todo list.\n There may be some hiccups with the new design, so if you see any please let me know by making an issue on GitHub.\n Do you like the new design, do you hate it? Please let me know.\n
\n \n \n\n"
},
{
"path": "public/blog/articles/2026-03-01-redesigning-plain-vanilla/nav-menu.html",
"content": "\n"
},
{
"path": "public/blog/articles/2026-03-09-details-matters/example1/index-partial.html",
"content": "\n A summary\n Some details to further explain the summary.\n\n"
},
{
"path": "public/blog/articles/2026-03-09-details-matters/example1/index.html",
"content": "\n\n\n Example 1\n \n \n \n\n\n \n A summary\n Some details to further explain the summary.\n \n\n"
},
{
"path": "public/blog/articles/2026-03-09-details-matters/example2/index-partial.html",
"content": "\n\n A summary\n Some details to further explain the summary.\n\n"
},
{
"path": "public/blog/articles/2026-03-09-details-matters/example2/index.html",
"content": "\n\n\n Example 2\n \n \n \n\n\n \n \n A summary\n Some details to further explain the summary.\n \n\n"
},
{
"path": "public/blog/articles/2026-03-09-details-matters/example3/index-partial.html",
"content": "\n\n \n A summary\n \n \n Some details to further explain the summary.\n\n"
},
{
"path": "public/blog/articles/2026-03-09-details-matters/example3/index.html",
"content": "\n\n\n Example 3\n \n \n \n\n\n \n \n \n A summary\n \n \n Some details to further explain the summary.\n \n\n"
},
{
"path": "public/blog/articles/2026-03-09-details-matters/example4/index-partial.html",
"content": "\n\n \n A summary\n \n \n Some details to further explain the summary.\n And this is another sentence that spends a great deal of time saying nothing.\n"
},
{
"path": "public/blog/articles/2026-03-09-details-matters/example4/index.html",
"content": "\n\n\n Example 4\n \n \n \n\n\n \n \n \n A summary\n \n \n Some details to further explain the summary.\n And this is another sentence that spends a great deal of time saying nothing.\n \n\n"
},
{
"path": "public/blog/articles/2026-03-09-details-matters/example5/index-partial.html",
"content": "\n\n ...\n\n\n ...\n\n\n ...\n"
},
{
"path": "public/blog/articles/2026-03-09-details-matters/example5/index.html",
"content": "\n\n\n Example 4\n \n \n \n\n\n \n \n \n Item 1\n \n \n This is the first item.\n \n \n \n Item 2\n \n \n Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse malesuada lacus ex, sit amet blandit leo lobortis eget.\n \n \n \n Item 3\n \n \n Aha, and yet another item.\n \n\n"
},
{
"path": "public/blog/articles/2026-03-09-details-matters/index.html",
"content": "\n\n\n <details> matters\n \n \n \n \n \n\n\n \n \n
<details> matters
\n
Joeri Sebrechts
\n \n \n
\n The richness of HTML continues to be a delightful surprise.\n
\n
\n For example, take an unassuming element like <details>.\n We've all seen it before. Here it is in its pure form:\n
\n \n \n \n
\n We can merrily click the summary to open and close the details to our heart's content.\n But this is kind of plain-looking. Can we change that triangle into something else?\n
\n \n
\n In a just world, this would work by neatly styling the ::marker pseudo-element,\n but like so often Safari is being annoying. \n Thankfully we can instead replace the marker by removing it with list-style: none; and adding a new summary marker\n on the ::before or ::after pseudo-elements.\n
\n \n
\n And really, the summary element can contain anything at all, inviting our creativity.\n Here's a fancier example that replaces the marker by an animated svg icon.\n
\n \n \n \n
\n There's no reason to stop at decorating the marker though.\n We can make the details element look like anything we want,\n all it takes is the right CSS. If we wanted, we could make it look like a card.\n
\n \n \n
\n One caveat with this example is the ::details-content pseudo-element used to select\n the expanded content area. This is baseline 2025 so still pretty new. For older browsers you can wrap the content \n in a div and style that instead.\n
\n\n
\n But wait, there's more! In baseline 2024 <details> picked up a neat trick\n where all the elements with the same name attribute are mutually exclusive,\n meaning only one can be open at the same time. All we have to do is stack them\n to magically get an accordion.\n
\n \n \n
\n There's no magic code here to make the accordion work aside from the name attributes. \n HTML is doing the magic for us, which means this also happens to be fully keyboard-navigable and accessible.\n The only tricky bit is animating the expanding and collapsing of the cards.\n In this example that is implemented using interpolate-size: allow-keywords,\n which is a Chromium-only trick hopefully coming to other browsers near you.\n Thankfully in those other browsers this is still perfectly functional, just not as smoothly animating.\n
\n
\n By the way, the mutually exclusive <details> elements do not even need to share a parent element.\n These accordion cards could be wrapped in custom elements, or <fieldset> or <form> elements,\n and they would work just fine in all browsers, today. But you'll have to take my word for it.\n After all, I have to leave some exercises up to the reader. 😉\n
\n\n
\n Like I said, the richness of HTML continues to be a delightful surprise.\n If you ask me then <details> has a bright future ahead of it.\n
\n
\n No JavaScript was harmed in the making of this blog post.\n
\n \n \n\n"
},
{
"path": "public/blog/articles/index.json",
"content": "[\n {\n \"slug\": \"2026-03-09-details-matters\",\n \"title\": \" matters\",\n \"summary\": \"An oddball element set to take the main stage.\",\n \"published\": \"2026-03-09\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2026-03-01-redesigning-plain-vanilla\",\n \"title\": \"Redesigning Plain Vanilla\",\n \"summary\": \"Stepping out of my comfort zone.\",\n \"published\": \"2026-03-01\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2025-07-16-local-first-architecture\",\n \"title\": \"Local-first web application architecture\",\n \"summary\": \"Maybe we just need to dig a little deeper (into the client).\",\n \"published\": \"2025-07-16\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2025-07-13-history-architecture\",\n \"title\": \"The history of web application architecture\",\n \"summary\": \"The many different ways of building for the web, and their many frustrations.\",\n \"published\": \"2025-07-13\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2025-06-25-routing\",\n \"title\": \"Clean client-side routing\",\n \"summary\": \"Finding a nice way of doing single-page app routing without a library.\",\n \"published\": \"2025-06-25\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2025-06-12-view-transitions\",\n \"title\": \"Bringing React's to vanilla JS\",\n \"summary\": \"Bringing React's declarative view transitions API to vanilla as a custom element.\",\n \"published\": \"2025-06-12\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2025-05-09-form-control\",\n \"title\": \"Making a new form control\",\n \"summary\": \"Building a form control as a custom element.\",\n \"published\": \"2025-05-09\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2025-04-21-attribute-property-duality\",\n \"title\": \"The attribute/property duality\",\n \"summary\": \"How to work with attributes and properties in custom elements.\",\n \"published\": \"2025-04-21\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2025-01-01-new-years-resolve\",\n \"title\": \"New year's resolve\",\n \"summary\": \"import.meta.resolve and other ways to avoid bundling\",\n \"published\": \"2025-01-01\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2024-12-16-caching-vanilla-sites\",\n \"title\": \"Caching vanilla sites\",\n \"summary\": \"Strategies for cache invalidation on vanilla web sites.\",\n \"published\": \"2024-12-16\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2024-10-20-editing-plain-vanilla\",\n \"title\": \"Editing Plain Vanilla\",\n \"summary\": \"How to set up VS Code for a vanilla web project.\",\n \"published\": \"2024-10-20\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2024-10-07-needs-more-context\",\n \"title\": \"Needs more context\",\n \"summary\": \"A better way to do context for web components.\",\n \"published\": \"2024-10-07\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2024-09-30-lived-experience\",\n \"title\": \"Lived experience\",\n \"summary\": \"Thoughts on the past and future of frameworks, web components and web development.\",\n \"published\": \"2024-09-30\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2024-09-28-unreasonable-effectiveness-of-vanilla-js\",\n \"title\": \"The unreasonable effectiveness of vanilla JS\",\n \"summary\": \"A case study in porting intricate React code to vanilla.\",\n \"published\": \"2024-09-28\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2024-09-16-life-and-times-of-a-custom-element\",\n \"title\": \"The life and times of a web component\",\n \"summary\": \"The entire lifecycle of a web component, from original creation to when a shadow crosses.\",\n \"published\": \"2024-09-16\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2024-09-09-sweet-suspense\",\n \"title\": \"Sweet Suspense\",\n \"summary\": \"React-style lazy loading of web components.\",\n \"published\": \"2024-09-09\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2024-09-06-how-fast-are-web-components\",\n \"title\": \"How fast are web components?\",\n \"summary\": \"Benchmarking the relative performance of different web component techniques.\",\n \"published\": \"2024-09-06\",\n \"updated\": \"2024-09-15\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2024-09-03-unix-philosophy\",\n \"title\": \"A unix philosophy for web development\",\n \"summary\": \"Maybe all web components need to be a light-weight framework is the right set of helper functions.\",\n \"published\": \"2024-09-03\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2024-08-30-poor-mans-signals\",\n \"title\": \"Poor man's signals\",\n \"summary\": \"Signals are all the rage over in frameworkland, so let's bring them to vanilla JS.\",\n \"published\": \"2024-08-30\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2024-08-25-vanilla-entity-encoding\",\n \"title\": \"Vanilla entity encoding\",\n \"summary\": \"The first version of this site didn't use entity encoding in the examples. Now it does.\",\n \"published\": \"2024-08-25\",\n \"author\": \"Joeri Sebrechts\"\n },\n {\n \"slug\": \"2024-08-17-lets-build-a-blog\",\n \"title\": \"Let's build a blog, vanilla-style!\",\n \"summary\": \"Explaining how this vanilla web development blog was built, using nothing but vanilla web techniques.\",\n \"published\": \"2024-08-17\",\n \"updated\": \"2024-08-26\",\n \"author\": \"Joeri Sebrechts\"\n }\n]"
},
{
"path": "public/blog/components/blog-archive.js",
"content": "import { html } from '../../lib/html.js';\n\nclass BlogArchive extends HTMLElement {\n connectedCallback() {\n this.textContent = 'Loading...';\n fetch(import.meta.resolve('../articles/index.json'))\n .then(response => response.json())\n .then(articles => {\n // sort articles by published descending\n articles.sort((a, b) => {\n return -a.published.localeCompare(b.published);\n });\n this.innerHTML = '
\n We can merrily click the summary to open and close the details to our heart's content.\n But this is kind of plain-looking. Can we change that triangle into something else?\n
\n In a just world, this would work by neatly styling the ::marker pseudo-element,\n but like so often Safari is being annoying. \n Thankfully we can instead replace the marker by removing it with list-style: none; and adding a new summary marker\n on the ::before or ::after pseudo-elements.\n
\n
<style>\n details {\n summary {\n list-style: none;\n }\n summary::before {\n content: \"\\1F512\";\n margin: 0 0.3em 0 -0.1em;\n }\n &[open] summary::before {\n content: \"\\1F513\";\n }\n }\n</style>\n<details>\n <summary>A summary</summary>\n Some details to further explain the summary.\n</details>\n
\n
\n And really, the summary element can contain anything at all, inviting our creativity.\n Here's a fancier example that replaces the marker by an animated svg icon.\n
\n There's no reason to stop at decorating the marker though.\n We can make the details element look like anything we want,\n all it takes is the right CSS. If we wanted, we could make it look like a card.\n
<style>\n details {\n border: 1px solid gray;\n max-width: 20em;\n\n summary {\n position: relative;\n list-style: none;\n padding: 0.2em 0.4em;\n user-select: none;\n svg {\n position: absolute;\n right: 0.2em;\n top: 0.3em;\n color: gray;\n rotate: 0;\n transition: rotate 0.3s ease-out;\n }\n }\n\n &[open] {\n summary {\n font-weight: bold;\n svg {\n rotate: 180deg;\n }\n }\n\n &::details-content {\n border-top: 1px solid gray;\n padding: 0.2em 0.4em; \n }\n }\n }\n</style>\n<details>\n <summary>\n A summary\n <svg focusable=\"false\" width=\"24\" height=\"24\" aria-hidden=\"true\">\n <path d=\"M6.34317 7.75732L4.92896 9.17154L12 16.2426L19.0711 9.17157L17.6569 7.75735L12 13.4142L6.34317 7.75732Z\" fill=\"currentColor\" />\n </svg>\n </summary>\n Some details to further explain the summary.\n And this is another sentence that spends a great deal of time saying nothing.\n</details>
\n
\n One caveat with this example is the ::details-content pseudo-element used to select\n the expanded content area. This is baseline 2025 so still pretty new. For older browsers you can wrap the content \n in a div and style that instead.\n
\n\n
\n But wait, there's more! In baseline 2024 <details> picked up a neat trick\n where all the elements with the same name attribute are mutually exclusive,\n meaning only one can be open at the same time. All we have to do is stack them\n to magically get an accordion.\n
<style>\n /* ... details styles repeated from previous example ... */\n\n details + details {\n border-top: none;\n }\n\n @supports (interpolate-size: allow-keywords) {\n :root {\n interpolate-size: allow-keywords;\n }\n\n details::details-content {\n /* allow discrete transitions for the details content (animating to height auto) */\n transition:\n height 0.3s ease,\n content-visibility 0.3s ease allow-discrete;\n /* hide the details content by default */\n height: 0;\n overflow: clip;\n }\n\n /* show the details content when the details is open */\n details[open]::details-content {\n height: auto;\n }\n }\n</style>\n<details name=\"accordion\">\n ...\n</details>\n<details name=\"accordion\">\n ...\n</details>\n<details name=\"accordion\">\n ...\n</details>
\n
\n There's no magic code here to make the accordion work aside from the name attributes. \n HTML is doing the magic for us, which means this also happens to be fully keyboard-navigable and accessible.\n The only tricky bit is animating the expanding and collapsing of the cards.\n In this example that is implemented using interpolate-size: allow-keywords,\n which is a Chromium-only trick hopefully coming to other browsers near you.\n Thankfully in those other browsers this is still perfectly functional, just not as smoothly animating.\n
\n
\n By the way, the mutually exclusive <details> elements do not even need to share a parent element.\n These accordion cards could be wrapped in custom elements, or <fieldset> or <form> elements,\n and they would work just fine in all browsers, today. But you'll have to take my word for it.\n After all, I have to leave some exercises up to the reader. 😉\n
\n\n
\n Like I said, the richness of HTML continues to be a delightful surprise.\n If you ask me then <details> has a bright future ahead of it.\n
\n
\n No JavaScript was harmed in the making of this blog post.\n
\n ]]>\n \n \n <![CDATA[Redesigning Plain Vanilla]]>\n \n https://plainvanillaweb.com/blog/articles/2026-03-01-redesigning-plain-vanilla/\n 2026-03-01T12:00:00.000Z\n 2026-03-01T12:00:00.000Z\n \n \n \n \n Design has never been the part of building for the web that I felt comfortable with.\n I would hide behind the shorthand \"I'm not a designer\" and just use someone else's design,\n or throw something together that I wasn't happy with.\n The original design of Plain Vanilla was shipped very much in that not-happy-with-it mindset.\n \n
\n So when I decided to finally take a web design course, settling on DesignAcademy.io\n 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. \n This article documents how and why the new design came about.\n
\n
\n The course starts out by making you really think about the content that you want to apply a design to.\n They challenge you to make your web page work as a google doc, so I did precisely that.\n In revisiting the landing page and thinking through its text, about half of the characters were cut,\n without losing any of the meaning.\n
\n
\n Lesson 1: less is more.\n
\n
\n The next challenge the course throws at you is to decide on a style and to gather inspiration for your design.\n What I wanted the design of Plain Vanilla to communicate was a sort of timelessness,\n like a manual from an earlier time, that at the same time feels simple and fresh.\n In looking for inspiration I settled on Swiss style,\n the 1950's minimalist style that manages to feel modern and old at the same time.\n I absolutely adore the old manuals from the 50's, as in the image at the top of this page,\n where minimalist design relying heavily on typography and spacing brings the content to the foreground.\n
\n
\n With this style and many googled-together examples of it as inspiration in hand, I took on the next challenge:\n make a first sketch of the design by simply copy pasting together elements of web sites and imagery\n that inspired you into a rough first outline. The second half of the challenge:\n take that design and layer your content over it. The result of this exercise was the initial redesign.\n Notice how the left half is literally copy pasted together bits of screenshots.\n
\n \n
\n Lesson 2: taking ideas from everywhere is a quick way to get started.\n
\n
\n The rest of the course was a series of design exercises on top of that initial draft, \n to choose fonts, colors, imagery, to apply a grid system and figure out spacing, and to sort out the finer aspects.\n Some elements of the initial redesign survived this process, others didn't, and what I ended up with\n in the final Affinity Designer file is pretty close to the shipping redesign.\n
\n \n
\n Lesson 3: design doesn't have to be intimidating if you have the right process.\n
\n
\n The actual work of translating of the design to code wasn't all that complicated.\n There was already a good baseline of semantic markup, so the redesign ended up mostly constrained\n to central CSS changes. Most of the time was taken up by responsiveness, something absent from the design mockup.\n Many of the final decisions on the exact behavior were made to favor code simplicity.\n This is for example why I decided not to add animations.\n
\n
\n This is also why I chose the popover API as the strategy for having a responsive hamburger menu on small screens.\n While the popover API presently only has 87% support on caniuse.com, I felt that for the audience of this site\n support should be sufficient, and the dramatic code simplification it allowed was undeniable.\n The nav menu works without any JavaScript. It presents as a toggled menu by default,\n and uses CSS to become permanently visible on larger screens.\n
\n This was also a good opportunity to revisit the website's content.\n As it turns out, not a lot needed to change. Web standards don't actually change that often.\n I did update some parts where evolving baseline support took away caveats \n (for example, CSS nesting is now safe to use), and added some links to newly baseline \n features like popover, dialog and mutually-exclusive details.\n
\n
\n Lesson 4: when you build on top of web standards, you don't need to do a lot of maintenance.\n
\n
\n In the end, I'm finally happy with the design of Plain Vanilla.\n I still haven't gotten around to adding a dark mode, but it's on the todo list.\n There may be some hiccups with the new design, so if you see any please let me know by making an issue on GitHub.\n Do you like the new design, do you hate it? Please let me know.\n
\n ]]>\n \n \n <![CDATA[Local-first web application architecture]]>\n \n https://plainvanillaweb.com/blog/articles/2025-07-16-local-first-architecture/\n 2025-07-16T12:00:00.000Z\n 2025-07-16T12:00:00.000Z\n \n \n \n \n Previously in the history of web application architecture \n I covered the different ways that people have tried to build web applications, and how all of them came with \n their own unique set of drawbacks.\n Also mentioned was how there is one drawback that they all share: \n there is a whole internet between a user and their data,\n and this makes it hard to deliver a top notch user experience.\n \n\n
Tail latency matters
\n
\n On the surface, it doesn't seem like this should be the case. Networks are fast, right?\n But the truth is, they're only fast for some of the people some of the time.\n
\n
\n Look at the page load numbers (LCP) of this website for the last week (gathered anonymously):\n
\n
\n
P50: 650 ms
\n
P75: 1200 ms
\n
P90: 2148 ms
\n
P99: 10,636 ms
\n
\n
\n While half of the visits see page load times well below a second,\n many see times that are much, much higher. Part of this is due to geography.\n Going through Azure's P50 roundtrip latency times we can see that\n some remote connections, like France to Australia, are in the 250 ms range, data center to data center.\n Azure doesn't disclose P99 latency, but one may assume it is a multiple of the P50 latency.\n
\n
\n But our user isn't sitting in a data center, they're probably on a mobile phone,\n connecting through a slow network. Looking at mozilla's minimum latency numbers \n we can see that it's not unusual to see another 100 ms of roundtrip latency added by the mobile network,\n 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,\n and trying to get some work done, is that the web can slow to a crawl as I pass through dead zones.\n This is in a densely populated area in a rich country on the most expensive cell service provider. \n Most people do not have these same luxuries.\n
\n
\n So it's not unusual to see latencies climb far above the threshold of 100 ms,\n commonly regarded as the threshold for an immediate response.\n For an unlucky minority of users latencies can even climb above half a second.\n This matters because if we have to hit the server to do something with the user's data \n on every click, we will have noticeable and frustrating delay in the interaction.\n To get a feel of this delay, here's a simulator where you can try out roundtrip latencies\n from 50 ms to one second:\n
\n Can you tell how much nicer 100 ms and below feel?\n How the buttons actually feel lighter to press?\n By contrast, 500 ms and above of roundtrip latency are just a slog, painful to use.\n The buttons are heavy and cumbersome. This is human psychology at work,\n and these lessons were learned in the desktop era but forgotten and never quite relearned for the web.\n If we put over 100 ms of latency in between a user's click and the resulting effect\n they will feel some degree of frustration, and we know that the internet cannot deliver below 100 ms of roundtrip latency\n except in the luckiest of cases.\n
\n \n
Solutions
\n\n
\n We can use some kind of closer-to-the-user cache,\n in the form of a CDN or a browser cache or a service worker. This allows the content that needs to be loaded \n based on the user's click to be fetched from something that has a better shot at being below that magic 100 ms\n of latency. But this only works if what we need to load can be cached,\n and if we can afford to cache it. For a web application that works with user data, this is typically not the case.\n
\n
\n We can host the application in a georedundant way, have application servers\n across the world and use a georedundant database like Google Spanner or Azure Cosmos DB. \n This quickly gets complicated and expensive, and can only be achieved \n through a great amount of vendor lock-in. Crucially, it probably does not get us past the 100 ms barrier anyway.\n
\n
\n We can render client-side, using JavaScript to create and update the HTML page,\n so that an update on the screen can happen immediately after the user's click.\n But this only works if what the user is doing is not updating a piece of server-side data.\n Otherwise we have to show some kind of loading or saving indicator until the server responds, \n and then we're back to roundtrip latency.\n
\n
\n Bottom line, and once again: the basic problem is that the internet is in between the user and their data.\n So what if we moved the data to the user?\n
\n\n
Local-first
\n\n
\n This concept has been around for a while and it is known as a local-first application.\n To apply it to the web, let's start from the basic design of a client-side rendered web application\n as covered in the previous article:\n
\n \n
\n This design does not need the server for rendering, so it has the theoretical potential to hit 100 ms.\n But because the user's interactions have to fetch data from the remote database and update it as well – \n a database sitting multiple network hops away –\n in practice we rarely actually hit that low latency.\n We can move the data to the user by doing something like this:\n
\n \n
\n The user's data gets duplicated into a local IndexedDB. More than duplicated actually as\n this becomes the only copy of the data that the user will interact with directly.\n The backend-for-frontend and API that used to gatekeep access to this data similarly get moved into the client,\n as part of a service worker. This worker code can be very similar to what the server-side version would be, \n it can even reuse express (although it probably shouldn't).\n Because the service worker's API for all intents and purposes looks like a server-side API to the frontend codebase,\n that frontend can be built in all the usual ways, \n except now with the guarantee that every server roundtrip completes in milliseconds.\n
\n
\n To avoid slow page loads each time the web application is opened\n it also needs to be cached locally as part of the service worker.\n By packaging this as a progressive web app installs become possible onto the user's home screen,\n giving an experience not that unlike installing a native mobile app.\n The application server's job is now reduced to only providing that initial application install,\n and it can become a simple (and free) static web host.\n
\n \n
Here comes trouble
\n
\n Both the application and the data are now running locally,\n meaning the user doesn't need the network at all to get things done.\n This isn't just local-first, it is offline-first.\n But like all things in software architecture, we are trading one set of problems for another.\n
\n
\n There still needs to be a way to get data onto other devices, or to other users,\n or simply backed up into the cloud. That means the service worker also gets the job of\n (asynchronously) uploading changes to a server API which will store it in a database,\n as well as pulling server-side changes back down. The server-side version acts as the master copy,\n and the server-side API gets the thankless job of merging client-side changes with it.\n
\n
\n Not so fast though. Our user might be editing offline for a considerably long time,\n and the data on the server may have been changed in the meanwhile from another device or by another user.\n The job of merging those changes can be ... complicated.\n A good strategy is needed for merging. A possible path is to use CRDT algorithms from a library like \n automerge, as suggested by the local-first article linked above.\n However, for many cases a simpler bespoke algorithm that is aware of the specific data types being merged probably works well enough,\n as I discovered when making an offline-capable work orders web application that used this strategy.\n
\n
\n As the local-first application is now directly talking to this API,\n it needs a way to authenticate. This can be a reason to still have a minimal \n backend-for-frontend on the server. An alternative is to use a separate \n OpenID Connect identity provider with a PKCE authorization flow to obtain an access token.\n PKCE is an authorization flow developed for use by mobile apps but also usable by web apps \n that enables secretless API authentication.\n
\n
\n Another major caveat is that the entire codebase needs to be on the client,\n which necessitates keeping it under a tight performance and size budget.\n Careful curation of dependencies is key, and a javascript footprint that runs in the megabytes is verboten.\n Vanilla web development can be a solution here, with its emphasis on using the platform to its limits\n without bringing in dependencies. A lightweight framework like Lit or Preact will do as well.\n
\n
\n This isn't just a theoretical exercise. The team at Superhuman built their better gmail than gmail \n more or less as described here, using React as the framework, and the thing that sets their web app apart is its blistering speed.\n You can go read how they did it on their blog (part 1, \n part 2) or listen to the retelling on the \n Syntax podcast.\n
\n\n
Loco-first
\n\n
\n But we can push it even further, in theory at least. In the previous iteration of the architecture we still have\n the application-specific database and syncing logic on the server,\n but what if we instead did away with every last piece of server-side application logic?\n
\n \n
\n The syncing engine now gets moved in the client, and what it uploads to the server are just files.\n That means all we need is a generic cloud drive, like Dropbox or Onedrive.\n These cloud drive services often support cross-origin API access with OpenID Connect authentication using PKCE.\n That means the service worker in the client doesn't need any application servers to upload its data\n to the cloud storage.\n
\n
\n The onboarding experience becomes a choice screen where the user picks their cloud drive option.\n The application will redirect the user to the Dropbox or Onedrive or <insert vendor here> login page,\n and obtains an access token using PKCE authorization flow that is persisted locally.\n This token is used to connect to the user's cloud drive from inside the service worker.\n The application will bootstrap itself from whatever files are already in the drive,\n and will regularly synchronize with the current contents of the drive using its service worker logic.\n
\n
\n Instead of a cloud drive, another option is the use of the File System Access API to get a handle to a local folder.\n 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.\n This solution allows the app to have complete privacy, as the user's data never leaves their device\n or network. The caveat is incomplete browser support.\n Come on Safari and Firefox, do your bit, for privacy!\n
\n
\n 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.\n 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.\n If they are, it downloads updates and merges them into the local IndexedDB.\n 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 \n and presenting its copy to merge, it is the service worker going to each device's copy and checking if it needs merging.\n
\n
\n There is no longer a master copy of the data, only one copy per device, all on equal footing,\n with an eventual consistency arising out of the devices merging from each other's copies.\n This is the same philosophy as CRDTs, or of the Operational Transformation algorithm that underpins Google Docs.\n No matter though, when you get deep enough into consistency models (I recommend Aphyr's writings\n or Martin Kleppmann's book), \n you'll realize that there is never such as a thing as a reliable master copy in a distributed system, \n even in cases where there is a central database.\n
\n
\n A multi-user scenario can be realized by our user subscribing to someone else's shared cloud drive folder,\n where the other user shares their copy of the data as read-only. When Alice shares her folder with Bob,\n Bob shares his with Alice, and they both subscribe to each other's updates, \n then they can work on a shared document without ever having given each other direct write access.\n
\n
\n As this application has no servers outside of the lightly loaded static web host, which in 2025 is free to host even at scale,\n the hosting cost drops to zero almost regardless of the number of users. The cloud drive costs are carried by each user individually,\n only responsible for their own share of storage. The only hosting cost to the application's owner would be the domain name.\n The climate footprint is minimal.\n
\n
\n By eliminating the central database and its adjoining server-side logic it also eliminates the main target for hackers.\n Because compromises can only occur one user at a time they lack a sufficient reward for hacking the application.\n On top of that, the only servers are the static web host and the major cloud drive vendors,\n both practically impossible to hack. This web app would be highly secure and remain secure with barely any maintenance.\n
\n
\n This architecture would be a cloud vendor's worst nightmare if it ever became popular,\n as they cannot earn a dime from it (aside from the basic cloud drive pennies).\n Thankfully for them, it is impossible to monetize for the company that builds such a web app as well.\n No server == no revenue opportunity. For now this is just a crazy theoretical exercise, \n far removed from where the leading frontend architecture voices are driving us, \n but the possibility fascinates me.\n
\n ]]>\n \n \n <![CDATA[The history of web application architecture]]>\n \n https://plainvanillaweb.com/blog/articles/2025-07-13-history-architecture/\n 2025-07-13T12:00:00.000Z\n 2025-07-13T12:00:00.000Z\n \n \n \n \n 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.\n That means I was there for the whole ride, the entire history of web application architecture, \n from the before times to the present day.\n So this post will be an overview of the various ways to make a web app, past and present, \n and their relative trade-offs as I experienced them.\n \n
\n Just to set expectations right: this will cover architectures targeted primarily at proper applications, \n of the sort that work with user data, and where most screens have to be made unique based on that user data.\n Web sites where the different visitors are presented with identical pages are a different beast.\n Although many of these architectures overlap with that use case, it will not be the focus here.\n
\n
\n Also, while I will be mentioning some frameworks, they are equally not the focus.\n Where you see a framework, you can slot in vanilla web development with a bespoke solution.\n
\n
\n This will be a long one, so grab a snack, take some time, and let's get going.\n
\n\n
Before time began
\n
\n Back when people first went online, the ruling architecture was offline-first.\n It looked sort of like this:\n
\n \n
\n Our user would have a proper desktop application, written in C or C++ most likely,\n and that would work with local files on their local file system, all perfectly functional when offline.\n When they wanted to \"go online\" and share their work, they would dial in to the internet,\n start their e-mail client and patiently send an e-mail to their friend or colleague containing \n a copy of their file as an attachment.\n
\n
\n This architecture was very simple, and it worked well in the absence of a reliable and fast internet connection.\n This was a good thing because at the time most people never had a reliable and fast internet connection.\n There were problems though. For one, the bootstrapping problem: how do you get everyone to have the application \n installed so they can open and edit the file they received via e-mail?\n Also, the syncing problem: how are changes kept in sync between multiple devices and users?\n Merging edits from different files that could have weeks of incompatible edits was always \n somewhere between frustrating and impossible.\n
\n\n
Traditional server-side rendering
\n
\n Web applications promised they would solve both problems. At first we built them like this:\n
\n \n
\n The first thing we did was move all of the stuff from all of the users into a central database somewhere online.\n Because this database was shared between the users, it became a lot more easy to keep their changes in sync.\n If one user made an edit to something, everyone else would see it on the next refresh.\n
\n
\n To allow users to actually get at this database we had to give them an application to do it.\n This new-fangled thing called a web application running on a web application server would take http requests\n coming from the user's browser, SQL query the database for the right set of stuff, \n and send back an entire web page. Every click, every submit, it would generate a whole new page.\n
\n
\n Deployment of those early web applications was often suspiciously simple:\n someone would connect via FTP to a server, and copy over the files from their local machine.\n There often weren't even any build steps. There was no step 3.\n
\n
\n On the one hand this architecture was convenient. It solved the bootstrapping problem \n by only demanding that each user have a web browser and an internet connection.\n It also moved all of the application logic over to the server, keeping it neatly in one place.\n Crucially it kept the browser's task minimal, important in an era where browsers were much less capable\n and PC's were orders of magnitude slower than today. If done well, it could even be used to make\n web applications that still worked with JavaScript disabled. My first mobile web app was like that,\n sneakily using HTML forms with multiple submit actions and hidden input fields\n to present interactive navigation through a CRUD interface.\n
\n
\n On the other hand, it had many problems, especially early on. HTML wasn't very good, CSS was in its infancy,\n and early JavaScript was mostly useless. It was hard going building anything at all on the early web.\n On top of that, web developers were a new breed, and they had to relearn many of the architecture lessons their desktop developer\n colleagues had already learned through bitter experience. For example, everyone has heard of the adage\n \"If you don't choose a framework, you'll end up building a worse one yourself.\" That is because for the first few years\n building your own terrible framework as you went was the norm, until everyone wisened up and started preaching this wisdom. \n For sure, my own first experiments in web application development in PHP 3 and 4 were all \n without the benefit of a proper framework.\n
\n
\n Web developers also had to learn lessons that their desktop counterparts never had to contend with.\n Moving the application to the server was convenient, but it exposed it to hackers from all across the world,\n and the early web application landscape was riddled with embarrassing hacks.\n Because the threat level on the internet keeps rising this remains a major headache to this day.\n
\n
\n Another novel problem was having to care a whole lot about connectivity and server uptime.\n Because users literally couldn't do anything at all if they didn't have a connection to a working web server,\n making sure that connection was always there became a pervasive headache.\n Going to a site and seeing an error 500 message was unsurprisingly common in those early years.\n
\n
\n The biggest problems however were throughput, bandwidth and latency. Because almost every click had to reload the whole page,\n doing anything at all in those early web applications was slow, like really, really slow.\n At the time, servers were slow to render the page, networks slow to transport it, and PC's and browsers slow to render.\n That couldn't stand, so something had to change. It was at this point that we saw a fork in the road,\n and the web developer community split up into two schools of thought that each went their own way.\n Although, as you will see, they are drawing closer again.\n
\n\n
Modern server-side rendering
\n\n
\n One branch of the web development tree doubled down on server-side rendering,\n building further on top of the existing server-side frameworks.\n
\n \n
\n They tackled the problems imposed by throughput and latency by\n moving over to a model of partial page updates, where small bits of user-activated JavaScript\n (originally mostly built with jQuery) would update parts of the page with HTML partials\n that they fetched from the server.\n
\n
\n The evolution of this architecture are so called LiveViews.\n This is a design first popularized by the Phoenix framework for the obscure Elixir programming language,\n but quickly adopted in many places.\n
\n
\n It uses framework logic to automatically wire up server-side generated templates with bits of JavaScript\n that will automatically call the server to fetch partial page updates when necessary.\n The developer has the convenience of not thinking about client-side scripting, \n while the users get an interactive user experience similar to a JavaScript-rich frontend.\n Typically the client keeps an open websocket connection to the server,\n so that server-side changes are quickly and automatically streamed into the page as soon as they occur.\n
\n
\n This architecture is conceptually simple to work with as all the logic remains on the server.\n It also doesn't ask much from the browser, good for slow devices and bandwidth-constrained environments.\n As a consequence it finds a sweet spot in mostly static content-driven web sites.\n
\n
\n But nothing is without trade-offs. This design hits the server on almost every interaction and has no path to offline functionality.\n Network latency and reliability are its UX killer, and especially on mobile phones – the main way people interact with web apps these days –\n those can still be a challenge. While this can be mitigated somewhat through browser caching, the limitation is always there.\n After all, the more that page content is dictated by realtime user input, the more necessary it becomes to push logic to the client.\n In cases where the network is good however, it can seem like magic even for highly interactive applications, \n and for that reason it has its diehard fans.\n
\n\n
Client-side rendering
\n
\n There was another branch of web development practice, let's say the ones who were fonder\n of clever architecture, who had a crazy thought: what if we moved rendering data to HTML from the server to the browser?\n They built new frameworks, in JavaScript, designed to run in the browser\n so that the application could be shipped as a whole as part of the initial page load, \n and every navigation would only need to fetch data for the new route.\n In theory this allowed for smaller and less frequent roundtrips to the server,\n and therefore an improvement to the user experience.\n Thanks to a blooming cottage industry of industry insiders advertising its benefits, it became the dominant architecture for new web applications,\n with React as the framework of choice to run inside the browser.\n
\n
\n This method taken to its modern best practice extreme looks like this:\n
\n \n
\n It starts out by moving the application, its framework, and its other dependencies over to the browser.\n When the page is loaded the entire bundle gets loaded, and then pages can be rendered as routes inside of the single-page application.\n Every time a new route needs to be rendered the data gets fetched from the server, not the HTML.\n
\n
\n The web application server's job is now just providing the application bundle as a single HTML page,\n and providing API endpoints for loading JSON data for every route. \n Because those API endpoints naturally end up mirroring the frontend's routes this part usually gets called the backend-for-frontend.\n 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. \n Express on node became a very popular choice, as it allowed a great deal of similarity between browser and server codebases,\n although in practice there's usually not much actual code in common.\n
\n
\n For security reasons – after all, the web application servers are on the increasingly dangerous public internet –\n the best practice became to host backends-for-frontend in a DMZ, a demilitarized zone\n where the assumption has to be that security is temporary and hostile interlopers could arrive at any time.\n In addition, if an organization has multiple frontends (and if they have a mobile app they probably have at least two),\n then this DMZ will contain multiple backends for frontend.\n
\n
\n Because there is only a single database to share between those different BFFs, \n and because of the security risks of connecting to the database from the dangerous DMZ,\n a best practice became to keep the backend-for-frontend focused on just the part of serving the frontend,\n and to wrap the database in a separate thing. This separate microservice\n is an application whose sole job is publishing an API that gatekeeps access to the database.\n This API is usually in a separate network segment, shielded by firewalls or API gateways,\n and it is often built in yet another framework better tailored for building APIs, \n or even in a different programming language like Go or C#.\n
\n
\n Of course, having only one microservice is kind of a lonely affair, \n so even organizations of moderate size would often end up having their backends-for-frontend each talking to multiple microservices.\n
\n
\n That's just too many servers to manage, too many network connections to configure, too many builds to run, \n so people by and large stopped managing their own servers, either for running builds or for runtime hosting.\n Instead they moved to the cloud, where someone else manages the server, and hosted their backends\n as docker containers or serverless functions deployed by git-powered CI/CD pipelines.\n This made some people fabulously wealthy. After all, 74% of Amazon's profit is made from AWS,\n and over a third of Microsoft's from Azure.\n It is no accident that there is a persistent drumbeat that everyone should move everything to the cloud.\n Those margins aren't going to pad themselves.\n
\n
\n Incidentally, microservices as database intermediary are also a thing in the world of server-side rendered applications,\n but in my personal observation those teams seem to choose this strategy less often.\n Equally incidentally, the word serverless in the context of serverless functions was and is highly amusing to me, \n 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.)\n
\n
\n On paper this client-side rendered architecture has many positive qualities. It is highly modular,\n which makes the work easy to split up across developers or teams. It pushes page rendering logic into\n the browser, creating the potential to have a low latency and high quality user experience.\n The layered nature of the backend and limited scope of the internet-facing backend-for-frontend forms\n a solid defensive moat against cyberattacks. And the cloud-hosted infrastructure is low effort to manage and easy to scale.\n A design like this is every architecture astronomer's dream, and I was for a while very enamored with it myself.\n
\n
\n In practice though, it just doesn't work very well. It's just too complicated.\n For larger experienced teams in large organizations it can kind of sort of make sense,\n and it is no surprise that big tech is a heavy proponent of this architecture.\n But step away from web-scale for just a second and there's too many parts to build and deploy and keep track of,\n too many technologies to learn, too many hops a data request has to travel through. \n
\n
\n The application's logic gets smeared out across three or more independent codebases,\n and a lot of overhead is created in keeping all of those in sync.\n Adding a single data field to a type can suddenly become a whole project. For one application I was working on\n I once counted in how many places a particular type was explicitly defined, and the tally reached lucky number 7.\n It is no accident that right around the time that this architecture peaked the use of monorepo tools \n to bundle multiple projects into a single repository peaked as well.\n
\n
\n Go talk to some people just starting out with web development\n and see how lost they get in trying to figure out all of this stuff, \n learning all the technologies comprising the Rube Goldberg machine that produces a webpage at the end.\n See just how little time they have left to dedicate to learning vanilla HTML, CSS and JS, \n arguably the key things a beginner should be focusing on.\n
\n
\n Moreover, the promise that moving the application entirely to the browser would improve the user experience mostly did not pan out.\n 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.\n The slowest quintile of devices and network connections struggled mightily with these heavy JavaScript payloads.\n It was hoped that Moore's law would solve this problem, but the dynamics of how (mobile) device and internet provider markets work\n 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 \n with this architecture, but you're starting from behind. Well, at least for public-facing web applications.\n
\n\n
Client-side rendering with server offload
\n
\n The designers of client-side frameworks were not wholly insensitive to the frustrations of developers \n trying to make client-side rendered single-page applications work well on devices and connections \n that weren't up to the job. They started to offload more and more of the rendering work back to the server.\n In situations where the content of a page is fixed, static site generation can execute\n the client-side framework at build time to pre-render pages to HTML.\n And for situations where content has a dynamic character, server-side rendering was reintroduced \n back into the mix to offload some of the rendering work back to the server.\n
\n
\n The current evolution of these trends is the streaming single-page application:\n
\n \n\n
\n In this architecture the framework runs the show in both backend-for-frontend and in the browser.\n It decides where the rendering happens, and only pushes the work to the browser that must run there.\n When possible the page is shipped prerendered to the browser and the code for the prerendered parts \n is not needed in the client bundle.\n Because some parts of the page are more dynamic than others, they can be rendered on-demand in the server \n and streamed to the browser where they are slotted into the prerendered page.\n The bundle that is shipped to the browser can be kept light-weight because it mostly just needs \n to respond to user input by streaming the necessary page updates from the server over an open websocket connection.\n
\n
\n If that sounds suspiciously like the architecture for modern server-side rendering that I described before,\n that is because it basically is. While a Next.JS codebase is likely to have some\n client-rendered components still, the extreme of a best practice Astro codebase would \n see every last component rendered on the server. \n In doing that they arrive at something functionally no different from LiveView architecture,\n and with a similar set of trade-offs. These architectures are simpler to work with, but they \n perform poorly for dynamic applications on low reliability or high latency connections,\n and they cannot work offline.\n
\n
\n Another major simplication of the architecture is getting rid of the database middleman.\n Microservices and serverless functions are not as hyped as they were, \n people are happy to build so-called monoliths again, \n and frameworks are happy to recommend they do so.\n The meta-frameworks now suggest that the API can be merged into the web application frontend, \n and the framework will know that those parts are only meant to be run on the server.\n This radically simplifies the codebase, we're back to a single codebase for the entire application\n managed by a single framework.\n
\n
\n However, TANSTAAFL. This simplification comes at the expense of other things. The Next.JS documentation may claim\n \"Since Server Components are rendered on the server, you can safely make database queries using an ORM or database client.\"\n 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.\n Defense in depth was a good idea, and we're back to trading security for simplicity.\n There were other reasons that monoliths once fell out of favor. It's like we're now forgetting lessons that were already learned.\n
\n\n
Where does that leave us?
\n\n
\n So, which architecture should you pick? I wish I could tell you,\n but you should have understood by now that the answer was always going to be it depends.\n Riffing on the work of Tolstoy: all web architectures are alike in that they are unhappy in their own unique way.\n
\n
\n In a sense, all of these architectures are also unhappy in the same way:\n there's a whole internet in between the user and their data.\n There's a golden rule in software architecture: you can't beat physics with code.\n We draw the internet on diagrams as a cute little cloud, pretending it is not a physical thing.\n But the internet is wires, and antennas, and satellites, and data centers, and all kinds of physical things and places.\n Sending a signal through all those physical things and places will always be somewhat unreliable and somewhat slow.\n We cannot reliably deliver on the promise of a great user experience as long as we put a cute little cloud \n in between the user and their stuff.\n
\n
\n In the next article I'll be exploring an obscure but very different architecture,\n a crazy thought similar to that of client-side rendering:\n what happens when we move the user's data from the server back into the client?\n What is local-first web application architecture?\n
\n ]]>\n \n \n <![CDATA[Clean client-side routing]]>\n \n https://plainvanillaweb.com/blog/articles/2025-06-25-routing/\n 2025-06-25T12:00:00.000Z\n 2025-06-25T12:00:00.000Z\n \n \n \n \n The main Plain Vanilla tutorial explains two ways of doing client-side routing.\n Both use old school anchor tags for route navigation.\n First is the traditional multi-page approach described on the Sites page as one HTML file per route,\n great for content sites, not so great for web applications.\n Second is the hash-based routing approach decribed on the Applications page, one custom element per route,\n better for web applications, but not for having clean URLs or having Google index your content.\n \n
\n In this article I will describe a third way, single-file and single-page but with clean URLs using the pushState API,\n and still using anchor tags for route navigation.\n The conceit of this technique will be that it needs more code, and the tiniest bit of server cooperation.\n
\n
Intercepting anchor clicks
\n
\n 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.\n Our SPA can then respond to these events by updating its routes.\n
\n\n
export const routerEvents = new EventTarget();\n\nexport const interceptNavigation = (root) => {\n // convert link clicks to navigate events\n root.addEventListener('click', handleLinkClick);\n // convert navigate events to pushState() calls\n routerEvents.addEventListener('navigate', handleNavigate);\n}\n\nconst handleLinkClick = (e) => {\n const a = e.target.closest('a');\n if (a && a.href) {\n e.preventDefault();\n const anchorUrl = new URL(a.href);\n const pageUrl = anchorUrl.pathname + anchorUrl.search + anchorUrl.hash;\n routerEvents.dispatchEvent(new CustomEvent('navigate', { detail: { url: pageUrl, a }}));\n }\n}\n\nconst handleNavigate = (e) => {\n history.pushState(null, null, e.detail.url);\n}\n
\n\n
\n In an example HTML page we can leverage this to implement routing in a <demo-app></demo-app> element.\n
\n
import { routerEvents, interceptNavigation } from './view-route.js';\n\ncustomElements.define('demo-app', class extends HTMLElement {\n\n #route = '/';\n\n constructor() {\n super();\n interceptNavigation(document.body);\n routerEvents.addEventListener('navigate', (e) => {\n this.#route = e.detail.url;\n this.update();\n });\n }\n\n connectedCallback() {\n this.update();\n }\n\n update() {\n if (this.#route === '/') {\n this.innerHTML = 'This is the homepage. <a href=\"/details\">Go to the details page</a>.';\n } else if (this.#route === '/details') {\n this.innerHTML = 'This is the details page. <a href=\"/\">Go to the home page</a>.';\n } else {\n this.innerHTML = `The page ${this.#route} does not exist. <a href=\"/\">Go to the home page</a>.`;\n }\n this.innerHTML += `<br>Current route: ${this.#route}`;\n }\n});\n
\n The first thing we're doing in view-route.js is the interceptNavigation() function.\n 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.\n Then it also adds a navigate event listener that will update the browser's URL by calling pushState.\n
\n
\n In app.js we can listen to the same navigate event to actually update the routes.\n Suddenly we've implemented a very basic in-page routing, but there are still a bunch of missing pieces.\n
\n\n
There and back again
\n\n
\n For one, browser back and forward buttons don't actually work.\n We can click and see the URL update in the browser, but the page does not respond.\n In order to do this, we need to start listening to popstate events.\n
\n
\n However, this risks creating diverging code paths for route navigation, one for the navigate event and one for the popstate event.\n Ideally a single event listener responds to both types of navigation.\n A simplistic way of providing a single event to listen can look like this:\n
\n Now our views can respond to popstate events and update based on the current route.\n A second question then becomes: what is the current route? The popstate event does not carry that info.\n 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.\n What is needed is a way of easily parsing it, something like this:\n
\n
view-route.js (continued):
// ...\n\n// all routes will be relative to the document's base path\nconst baseURL = new URL(window.originalHref || document.URL);\nconst basePath = baseURL.pathname.slice(0, baseURL.pathname.lastIndexOf('/'));\n\n// returns an array of regex matches for matched routes, or null\nexport const matchesRoute = (path) => {\n const fullPath = basePath + '(' + path + ')';\n const regex = new RegExp(`^${fullPath.replaceAll('/', '\\\\/')}`, 'gi');\n const relativeUrl = location.pathname;\n return regex.exec(relativeUrl);\n}\n
\n
\n The matchesRoute() function accepts a regex to match as the route,\n and will wrap it so it is interpreted relative to the current document's URL,\n making all routes relative to our single page.\n Now we can clean up the application code leveraging these new generic routing features:\n
\n
import { routerEvents, interceptNavigation, matchesRoute } from './view-route.js';\n\ncustomElements.define('demo-app', class extends HTMLElement {\n\n #route = '/';\n\n constructor() {\n super();\n interceptNavigation(document.body);\n routerEvents.addEventListener('popstate', (e) => {\n const matches =\n matchesRoute('/details') || \n matchesRoute('/');\n this.#route = matches?.[1];\n this.update();\n });\n }\n\n connectedCallback() {\n this.update();\n }\n\n update() {\n if (this.#route === '/') {\n this.innerHTML = 'This is the homepage. <a href=\"/details\">Go to the details page</a>.';\n } else if (this.#route === '/details') {\n this.innerHTML = 'This is the details page. <a href=\"/\">Go to the home page</a>.';\n } else {\n this.innerHTML = `The page ${this.#route} does not exist. <a href=\"/\">Go to the home page</a>.`;\n }\n this.innerHTML += `<br>Current route: ${this.#route}`;\n }\n});\n
\n Opening that in a separate tab we can see that the absolute URL neatly updates with the routes,\n that browser back/forwards navigation updates the view, and that inside the view the route is\n relative to the document.\n
\n
\n Because matchesRoute() accepts a regex,\n it can be used to capture route components that are used inside of the view.\n Something like matchesRoute('/details/(?<id>[\\\\w]+)') would\n put the ID in matches.groups.id. It's simple, but it gets the job done.\n
\n\n
Can you use it in a sentence?
\n\n
\n While this rudimentary way of detecting routes works, adding more routes quickly becomes unwieldy.\n It would be nice to instead have a declarative way of wrapping parts of views inside routes.\n Enter: a custom element to wrap each route in the page's markup.\n
\n
view-route.js (partial):
// ...\n\ncustomElements.define('view-route', class extends HTMLElement {\n\n #matches = [];\n\n get isActive() {\n return !!this.#matches?.length;\n }\n\n get matches() {\n return this.#matches;\n }\n\n set matches(v) {\n this.#matches = v;\n this.style.display = this.isActive ? 'contents' : 'none';\n if (this.isActive) {\n this.dispatchEvent(new CustomEvent('routechange', { detail: v, bubbles: true }));\n }\n }\n\n connectedCallback() {\n routerEvents.addEventListener('popstate', this);\n this.update();\n }\n\n disconnectedCallback() {\n routerEvents.removeEventListener('popstate', this);\n }\n\n handleEvent(e) {\n this.update();\n }\n\n static get observedAttributes() {\n return ['path'];\n }\n\n attributeChangedCallback() {\n this.update();\n }\n\n update() {\n const path = this.getAttribute('path') || '/';\n this.matches = this.matchesRoute(path) || [];\n }\n\n matchesRoute(path) {\n // '*' triggers fallback route if no other route on the same DOM level matches\n if (path === '*') {\n const activeRoutes = \n Array.from(this.parentNode.getElementsByTagName('view-route')).filter(_ => _.isActive);\n if (!activeRoutes.length) return [location.pathname, '*'];\n // normal routes\n } else {\n return matchesRoute(path);\n }\n return null;\n }\n});\n
\n
\n Now we can rewrite our app to be a lot more declarative, while preserving the behavior.\n
\n
import { interceptNavigation } from './view-route.js';\n\ncustomElements.define('demo-app', class extends HTMLElement {\n\n constructor() {\n super();\n interceptNavigation(document.body);\n }\n\n connectedCallback() {\n this.innerHTML = `\n <view-route path=\"/(?:index.html)?$\">\n This is the homepage. <a href=\"/details\">Go to the details page</a>, or\n travel a <a href=\"/unknown\">path of mystery</a>.\n </view-route>\n <view-route path=\"/details\">\n This is the details page. <a href=\"/\">Go to the home page</a>.\n </view-route>\n <view-route path=\"*\">\n The page does not exist. <a href=\"/\">Go to the home page</a>.\n </view-route>\n `\n }\n});\n
\n While things now look like they work perfectly, the illusion is shattered upon reloading the page when it is on the details route.\n To get rid of the 404 error we need a handler that will redirect to the main index page.\n This is typically something that requires server-side logic, locking us out from simple static hosting like GitHub Pages,\n but thanks to the kindness of internet strangers, there is a solution.\n
\n
\n It involves creating a 404.html file that GitHub will load for any 404 error (the tiny bit of server cooperation).\n In this file the route is encoded as a query parameter, the page redirects to index.html,\n and inside that index page the route is restored.\n
\n Adding this last piece to what we already had gets us a complete routing solution for vanilla single page applications\n that are hosted on GitHub Pages. Here's a live example hosted from there:\n
\n To full code of view-route.js and of this example is on GitHub.\n
\n ]]>\n \n \n <![CDATA[Bringing React's <ViewTransition> to vanilla JS]]>\n \n https://plainvanillaweb.com/blog/articles/2025-06-12-view-transitions/\n 2025-06-12T12:00:00.000Z\n 2025-06-12T12:00:00.000Z\n \n \n \n \n I like React. I really do. It is the default answer for modern web development, and it is that answer for a reason.\n Generally when React adds a feature it is well thought through, within the React system of thinking.\n My one criticism is that React by its nature overthinks things, that dumber and simpler solutions would often be \n on the whole ... better. Less magic, more predictable.\n \n
\n So when I port framework features to vanilla JS, don't take this as a slight of that framework.\n It is meant as an exploration of what dumber and simpler solutions might look like, when built \n on the ground floor of the web's platform instead of the lofty altitudes of big frameworks. \n It is a great way to learn.\n
\n
\n Which brings me of course to today's topic: view transitions, and how to implement them.\n
\n\n
View Transitions 101
\n\n
\n Let's start with the basics: what is a view transition?\n
\n In a supporting browser, what you'll see when you click is a square smoothly transitioning\n between blue and orange on every button click. By supported browser I mean Chrome, Edge or Safari,\n but sadly not yet Firefox, although they're working on it!\n In Firefox you'll see the change, but applied immediately without the animation.\n
\n
\n At the code level, it looks something like this:\n
\n\n
example.js:
function transition() {\n const square1 = document.getElementById('square1');\n if (document.startViewTransition) {\n document.startViewTransition(() => {\n square1.classList.toggle('toggled');\n });\n } else {\n square1.classList.toggle('toggled');\n }\n}\n
\n How this works is that the browser takes a snapshot of the page when we call document.startViewTransition(),\n takes another snapshot after the callback passed to it is done (or the promise it returns fulfills),\n and then figures out how to smoothly animate between the two snapshots, using a fade by default.\n
\n
\n A very nice thing is that by putting a view-transition-name style on an element we can \n make it transition independently from the rest of the page, and we can control that transition through CSS.\n
\n That's enough view transition basics for now. If you're curious for more, \n you can learn the rest in the chrome developer documentation.\n
\n\n
Here comes trouble
\n\n
\n Up to this point, we've gotten the fair weather version of view transitions, but there are paper cuts.\n
\n
\n
Firefox doesn't support view transitions at all, so we have to feature-detect.
\n
There is only one actual current View Transitions standard, level 1, but most of the online tutorials talk about the unfinalized level 2.
\n
If there are duplicate values of view-transition-name anywhere on the page, the animations disappear in a puff of duplicate element error smoke.
\n
As always, there's a thing about shadow DOM, but more on that later.
\n
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.
\n
User input is blocked while the view is transitioning, causing frustration when clicks are ignored.
\n
The document.startViewTransition() function only accepts a single callback that returns a single promise.
\n
\n
\n It is the last one that really spells trouble. In a larger single-page web application we'll typically\n find a central routing layer that triggers a number of asynchronous updates every time the route changes.\n Wrapping those asynchronous updates into a single promise can be a challenge,\n as is finding the right place to \"slot in\" a call to document.startViewTransition().\n
\n
\n Also, we probably don't even want to wait for all of the asynchronous updates to complete.\n Leaving the application in an interactive state in between two smaller view transitions is better\n than bundling it all together into one ponderous picture perfect transition animation.\n
\n\n
What React did
\n\n
\n React being React they solve those problems through magic, through exceeding cleverness.\n You can read up on their approach to view transitions, \n but distilling it down it becomes this:\n
\n
\n
Anything that should take part separately in a view transition is wrapped in a <ViewTransition> component.
\n
React will choose unique view-transition-name style values, which DOM elements to set them on, and when to set them.\n This can be controlled through the <ViewTransition>name and key props.
\n
Any updates that should become part of a view transition are wrapped in a startTransition() call.
\n
React automatically figures out when to call document.startViewTransition(), and what updates to put inside the callback.\n It also cleverly avoids starting new transitions when one is already running, so startTransition() can be called from multiple places safely.\n Oh, and by the way, it feature detects, obviously.\n
\n Good luck figuring out how it works, \n or how to troubleshoot when the magic loses its shine.\n But that is the bar, that is the lofty goal of user experience to reach with a dumber and simpler reimagining as vanilla JS.\n So let's get cooking.\n
\n\n
A fresh start
\n\n
\n Our starting point is a barebones implementation of a startTransition()\n function to replace what React's startTransition() does.\n It will fall back to non-animated transitions if our browser doesn't support document.startViewTransition.\n
\n While that takes care of feature-detecting, we can still run into timing issues.\n For example, let's say that instead of toggling we were switching routes,\n and the second route needs to load data prior to animating in.\n
\n But, as you see when trying it out, it doesn't work. Because the startTransition()\n calls end up overlapping each other, the animation is interrupted, and we get a jarring experience.\n 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.\n We also can't solve this by bundling everything into one single big view transition, because that would imply\n blocking user input while a network request completes, which would be a bad user experience.\n
\n
\n React solves all of this in the typical React way. It will smartly choose how to batch work\n into successive calls to document.startViewTransition(). It will take into account where something loads lazily,\n as in the previous example, and batch the work of animating in the content for the fallback in a separate view transition.\n
\n \n
Taking a queue
\n\n
\n Distilling that approach to its essence, the really useful part of React's solution is the queueing and batching of work. \n Any call to startTransition() that occurs while a view transition is running should be queued until after the transition completes,\n and nested calls should have all their updates batched together.\n
\n\n
view-transition.js:
// the currently animating view transition\nlet currentTransition = null;\n// the next transition to run (after currentTransition completes)\nlet nextTransition = null;\n\n/** start a view transition or queue it for later if one is already animating */\nexport const startTransition = (updateCallback) => {\n if (!updateCallback) updateCallback = () => {};\n // a transition is active\n if (currentTransition && !currentTransition.isFinished) {\n // it is running callbacks, but not yet animating\n if (!currentTransition.isReady) {\n currentTransition.addCallback(updateCallback);\n return currentTransition;\n // it is already animating, queue callback in the next transition\n } else {\n if (!nextTransition) {\n nextTransition = new QueueingViewTransition();\n }\n return nextTransition.addCallback(updateCallback);\n }\n // if no transition is active, start animating the new transition\n } else {\n currentTransition = new QueueingViewTransition();\n currentTransition.addCallback(updateCallback);\n currentTransition.run();\n // after it's done, execute any queued transition\n const doNext = () => {\n if (nextTransition) {\n currentTransition = nextTransition;\n nextTransition = null;\n currentTransition.run();\n currentTransition.finished.finally(doNext);\n } else {\n currentTransition = null;\n }\n }\n currentTransition.finished.finally(doNext);\n return currentTransition;\n }\n}\n\n// ...
\n\n
\n The QueueingViewTransition implementation is a straightforward batching of callbacks,\n and a single call to document.startViewTransition() that executes them in order.\n It is not included in the text of this article for brevity's sake, but linked at the bottom instead.\n
\n
\n Applying that queueing solution on top of the previous example's unchanged code, \n we suddenly see the magic of clean view transitions between dynamically loading routes.\n
\n 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.\n Which brings me to the playground for that learning, a full port of React's tour-de-force <ViewTransition> example to vanilla web code.\n
\n The full code of this example is on GitHub.\n Arguably the 300 lines of code in the lib/ folder of that example constitute a mini-framework,\n but fascinating to me is that you can get so much mileage out of such a small amount of library code,\n with the resulting single-page application being more or less the same number of lines as the React original.\n
\n
\n That example also shows how to do a purely client-side router with clean URLs using pushState().\n This blog post has however gone too long already, so I'll leave that for another time.\n
\n\n
One more thing
\n\n
\n Oh yeah, I promised to talk about the thing with shadow DOM, and I promised a custom element.\n Here is the thing with shadow DOM: when document.startViewTransition() is called from the light DOM,\n it cannot see elements inside the shadow DOM that need to transition independently, \n unless those elements are exposed as DOM parts and a view-transition-name style is set on them in the light DOM.\n
\n
\n If the solution to that intrigues you, it's in the GitHub example repo as well as a <view-transition> custom element.\n If that sounds like a bunch of mumbo jumbo instead, join the club.\n Just one more reason to avoid shadow DOM.\n
\n ]]>\n \n \n <![CDATA[Making a new form control]]>\n \n https://plainvanillaweb.com/blog/articles/2025-05-09-form-control/\n 2025-05-09T12:00:00.000Z\n 2025-05-09T12:00:00.000Z\n \n \n \n \n There are some things that a web developer knows they shouldn't attempt.\n Making clever use of contenteditable. Building custom form controls. Making complicated custom elements without a framework.\n 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?\n \n
Narrator: it would indeed be that bad.
\n
\n This article is building on the previous one on proper attribute/property relations in custom elements.\n 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.\n The mission is simple: implement a basic version of <input type=\"text\" /> but with display: inline layout.\n
\n\n
A simple element
\n \n
\n Let's start by just throwing something against the wall and playing around with it.\n
\n ElementInternals offers a control surface for setting the behavior of our custom element as part of a form.\n 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.\n By calling this.#internals.setFormValue every time the control's value changes the form will know what value to submit.\n 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.\n
\n\n
Looking for input
\n\n
\n Ostensibly responding to input is just adding a few event listeners in connectedCallback and removing them again in disconnectedCallback.\n But doing it that way quickly gets verbose. An easy alternative is to instead rely on some of the built-in event logic magic,\n namely that events bubble and that objects can be listeners too.\n
\n\n
input-inline.js:
customElements.define('input-inline', class extends HTMLElement {\n \n #shouldFireChange = false;\n \n /* ... */\n\n constructor() {\n /* ... */\n this.addEventListener('input', this);\n this.addEventListener('keydown', this);\n this.addEventListener('paste', this);\n this.addEventListener('focusout', this);\n }\n\n handleEvent(e) {\n switch (e.type) {\n // respond to user input (typing, drag-and-drop, paste)\n case 'input':\n this.value = cleanTextContent(this.textContent);\n this.#shouldFireChange = true;\n break;\n // enter key should submit form instead of adding a new line\n case 'keydown':\n if (e.key === 'Enter') {\n e.preventDefault();\n this.#internals.form?.requestSubmit();\n }\n break;\n // prevent pasting rich text (firefox), or newlines (all browsers)\n case 'paste':\n e.preventDefault();\n const text = e.clipboardData.getData('text/plain')\n // replace newlines and tabs with spaces\n .replace(/[\\n\\r\\t]+/g, ' ')\n // limit length of pasted text to something reasonable\n .substring(0, 1000);\n // shadowRoot.getSelection is non-standard, fallback to document in firefox\n // https://stackoverflow.com/a/70523247\n let selection = this.getRootNode()?.getSelection?.() || document.getSelection();\n let range = selection.getRangeAt(0);\n range.deleteContents();\n range.insertNode(document.createTextNode(text));\n // manually trigger input event to restore default behavior\n this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));\n break;\n // fire change event on blur\n case 'focusout':\n if (this.#shouldFireChange) {\n this.#shouldFireChange = false;\n this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));\n }\n break;\n }\n }\n \n /* ... */\n});\n\nfunction cleanTextContent(text) {\n return (text ?? '')\n // replace newlines and tabs with spaces\n .replace(/[\\n\\r\\t]+/g, ' ');\n}\n
\n I prefer this pattern because it simplifies the code a lot compared to having separate handler functions.\n Attaching event listeners in the constructor instead of attaching and detaching them in the lifecycle callbacks is another simplification. \n It may seem like blasphemy to never clean up the event listeners, but DOM event listeners\n are weakly bound and garbage collection of the element can still occur with them attached. So this is fine.\n
\n
\n In the event handler logic there's some verbosity to deal with the fallout of working with contenteditable.\n 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.\n
\n
\n With these changes our element will now also emit input and change events just like a built-in HTML form control.\n But, you may have noticed another issue has cropped up. The standard form reset button does not actually reset the form.\n
\n\n
Read the instructions
\n\n
\n You see, when we said static formAssociated = true we entered into a contract to faithfully implement the expected behavior of a form control.\n That means we have a bunch of extra work to do.\n
\n There's a LOT going on there. It's too much to explain, so let me sum up.\n
\n
\n
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.
\n
The value property contains only the modified value and does not correspond to an attribute.
\n
The control can be marked disabled or read-only through attribute or property.
\n
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.
\n
\n\n
With some style
\n\n
\n Up to this point we've been using some stand-in styling.\n However, it would be nice to have some default styling that can be bundled with our custom form control.\n Something like this:\n
\n The styles are isolated by scoping them to the name of our custom element, \n and the use of @layer puts them at the lowest priority, so that any user style will override the default style,\n just like for the built-in form controls. The use of variables offers an additional way to quickly restyle the control.\n
\n
\n In the styling we also see the importance of properly thinking out disabled and focused state behavior.\n 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.\n
\n
\n We're now past the 150 lines mark, just to get to the low bar of implementing the browser's mandatory form control behavior.\n 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.\n
\n\n
Validation
\n\n
\n Built-in form controls come with a validity API. To get an idea of what it means to implement it \n in a custom form control, let's add one validation attribute: required.\n It doesn't seem like it should take a lot of work, right?\n
\n\n
input-inline.js:
let VALUE_MISSING_MESSAGE = 'Please fill out this field.';\n(() => {\n const input = document.createElement('input');\n input.required = true;\n input.reportValidity();\n VALUE_MISSING_MESSAGE = input.validationMessage;\n})();\n\nconst isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);\n\ncustomElements.define('input-inline', class extends HTMLElement {\n \n /* ... */\n\n #customValidityMessage = '';\n\n /* ... */\n\n set required(v) {\n if (v) {\n this.setAttribute('required', 'true');\n } else {\n this.removeAttribute('required');\n }\n }\n get required() {\n return this.hasAttribute('required');\n }\n\n /* ... */\n\n static observedAttributes = ['value', 'disabled', 'readonly', 'required'];\n attributeChangedCallback() {\n this.#update();\n }\n\n #update() {\n /* ... */\n\n this.#internals.ariaRequired = this.required;\n this.#updateValidity();\n }\n\n /* ... */\n\n #updateValidity() {\n const state = {};\n let message = '';\n\n // custom validity message overrides all else\n if (this.#customValidityMessage) {\n state.customError = true;\n message = this.#customValidityMessage;\n } else {\n if (this.required && !this.value) {\n state.valueMissing = true;\n message = VALUE_MISSING_MESSAGE;\n }\n \n // add other checks here if needed (e.g., pattern, minLength)\n }\n\n // safari needs a focusable validation anchor to show the validation message on form submit\n // and it must be a descendant of the input\n let anchor = undefined;\n if (isSafari) {\n anchor = this.querySelector('span[aria-hidden]');\n if (!anchor) {\n anchor = document.createElement('span');\n anchor.ariaHidden = true;\n anchor.tabIndex = 0;\n this.append(anchor);\n }\n }\n\n this.#internals.setValidity(state, message, anchor);\n }\n\n checkValidity() {\n this.#updateValidity();\n return this.#internals.checkValidity();\n }\n\n reportValidity() {\n this.#updateValidity();\n return this.#internals.reportValidity();\n }\n\n setCustomValidity(message) {\n this.#customValidityMessage = message ?? '';\n this.#updateValidity();\n }\n\n get validity() {\n return this.#internals.validity;\n }\n\n get validationMessage() {\n return this.#internals.validationMessage;\n }\n\n get willValidate() {\n return this.#internals.willValidate;\n }\n});\n\n/* ... */
\n The code for the example is exactly like it would be for built-in controls:\n
\n
<form>\n <p>\n My favorite color is <input-inline name=\"color1\" value=\"green\" required></input-inline>.\n </p>\n <button type=\"submit\">Submit</button>\n <button type=\"reset\">Reset</button>\n</form>
\n\n
\n The ElementInternals interface is doing a lot of the work here, but we still have to proxy its methods and properties.\n You can tell however that by this point we're deep in the weeds of custom elements, because of the rough edges.\n
\n
\n
The example is using the input-inline:invalid style instead of :user-invalid because\n :user-invalid is not supported on custom elements yet.
\n
An ugly hack is needed to get the properly localized message for a required field that matches that of built-in controls.
\n
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.
\n
\n\n
In conclusion
\n\n
\n 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,\n but also that it is a path surrounded by peril as well as laborious to travel.\n Whether it is worth doing is in the eye of the beholder.\n
\n
\n Along that path we also learned some lessons on how to handle input in custom elements, and have proven yet again that contenteditable,\n while less painful than it once was, is an attribute that can only be used in anger.\n
\n
\n Regardless, the full source code of the input-inline form control is on GitHub.\n
\n ]]>\n \n \n <![CDATA[The attribute/property duality]]>\n \n https://plainvanillaweb.com/blog/articles/2025-04-21-attribute-property-duality/\n 2025-04-21T12:00:00.000Z\n 2025-04-21T12:00:00.000Z\n \n \n \n \n Web components, a.k.a. custom elements, are HTML elements\n that participate in HTML markup. As such they can have attributes:\n \n
<my-hello value=\"world\"></my-hello>
\n
\n But, they are also JavaScript objects, and as such they can have object properties.\n
\n
let myHello = document.querySelector('my-hello'); myHello.value = 'foo';
\n
\n And here's the tricky part about that: these are not the same thing!\n In fact, custom element attributes and properties by default have zero relationship between them,\n even when they share a name. Here's a live proof of this fact:\n
\n But what if we would also like it to have a valueproperty?\n What should the relationship between attribute and property be like?\n
\n
\n
Does updating the attribute always update the property?
\n
Does updating the property always update the attribute?
\n
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?
\n
When updates can go either way, how to avoid loops where the property updates the attribute, which updates the property, which...
\n
When is it fine to have just an attribute without a property, or a property without an attribute?
\n
\n\n
\n In framework-based code, we typically don't get a say in these things.\n Frameworks generally like to pretend that attributes and properties are the same thing,\n and they automatically create code to make sure this is the case.\n In vanilla custom elements however, not only do we get to decide these things, we must decide them.\n
\n\n
Going native
\n\n
\n Seasoned developers will intuitively grasp what the sensible relationship between attributes and properties should be.\n This is because built-in HTML elements all implement similar kinds of relationships between their attributes and their properties.\n To explore that in depth, I recommend reading Making Web Component properties behave closer to the platform.\n Without fully restating that article, here's a quick recap:\n
\n
\n
Properties can exist independent of an attribute, but an attribute will typically have a related property.
\n
If changing the attribute updates the property, then updating the property will update the attribute.
\n
Properties reflect either an internal value of an element, or the value of the corresponding attribute.
\n
Assigning a value of an invalid type will coerce the value to the right type, instead of rejecting the change.
\n
Change events are only dispatched for changes by user input, not from programmatic changes to attribute or property.
\n
\n\n
An easy way to get much of this behavior is to make a property wrap around an attribute:
\n Notice how updating the property will update the attribute in the HTML representation,\n and how the property's assigned value is coerced into the attribute's string type.\n Attributes are always strings.\n
\n \n
Into the weeds
\n\n
\n Up to this point, things are looking straightforward. But this is web development,\n things are never as straightforward as they seem.\n For instance, what boolean attribute value should make a corresponding boolean property become true?\n The surprising but standard behavior on built-in elements is that \n any attribute value will be interpreted as true, and only the absence of the attribute will be interpreted as false.\n
\n Which leaves us with the last bit of tricky trivia:\n it's possible for the custom element's class to be instantiated and attached to the element\n after the property is assigned. In that case the property's setter is never called,\n and the attribute is not updated.\n
\n \n
// html:\n<my-hello value=\"world\"></my-hello>\n// js:\nconst myHello = document.querySelector('my-hello');\nmyHello.value = 42; // setter not called before define\ncustomElements.define('my-hello', /* ... */);\nconsole.log(myHello.getAttribute('value')); // -> \"world\"\n
\n\n
\n This can be avoided by reassigning any previously set properties when the element is connected:\n
\n\n
customElements.define('my-hello', class extends HTMLElement {\n get value() {\n return this.getAttribute('value');\n }\n set value(v) {\n this.setAttribute('value', String(v));\n }\n\n get glam() {\n return this.hasAttribute('glam');\n }\n set glam(v) {\n if (v) {\n this.setAttribute('glam', 'true');\n } else {\n this.removeAttribute('glam');\n }\n }\n \n static observedAttributes = ['value', 'glam'];\n attributeChangedCallback() {\n this.textContent = \n `Hello, ${ this.value || 'null' }!` +\n (this.glam ? '!!@#!' : '');\n }\n\n connectedCallback() {\n this.#upgradeProperty('value');\n this.#upgradeProperty('glam');\n }\n\n #upgradeProperty(prop) {\n if (this.hasOwnProperty(prop)) {\n let value = this[prop];\n delete this[prop];\n this[prop] = value;\n }\n }\n});\n
\n\n
In conclusion
\n\n
\n If that seems like a lot of work to do a very simple thing, that is because it is.\n The good news is: we don't have to always do this work.\n
\n
\n When we're using web components as framework components in a codebase that we control,\n we don't have to follow any of these unwritten rules and can keep the web component code as simple as we like.\n However, when using web components as custom elements to be used in HTML markup \n then we do well to follow these best practices to avoid surprises, \n especially when making web components that may be used by others. YMMV.\n
\n
\n In the next article, I'll be looking into custom elements that accept input, and how that adds twists to the plot.\n
\n\n ]]>\n \n \n <![CDATA[New year's resolve]]>\n \n https://plainvanillaweb.com/blog/articles/2025-01-01-new-years-resolve/\n 2025-01-01T12:00:00.000Z\n 2025-01-01T12:00:00.000Z\n \n \n \n \n Today I was looking at what I want to write about in the coming year,\n and while checking out custom element micro-frameworks came across import.meta.resolve\n in the documentation for the Ponys micro-framework. \n That one simple trick is part of the essential toolbox that allows skipping build-time bundling,\n unlocking the vanilla web development achievement in the browser.\n \n
\n We need this toolbox because the build-time bundler does a lot of work for us:\n
\n
\n
Combining JS and CSS files to avoid slow page loads.
\n
Resolving paths to the JS and CSS dependencies so we can have clean import statements.
\n
Optimizing the bundled code, by stripping out whitespace, and removing unused imports thanks to a tree shaking algorithm.
\n
\n
\n It is not immediately apparent how to get these benefits without using a bundler.\n
\n\n
Combining JS and CSS files
\n
\n A typical framework-based web project contains hundreds or thousands of files.\n Having all those files loaded separately on a page load would be intolerably slow,\n hence the need for a bundler to reduce the file count. Even by stripping away third party dependencies\n we can still end up with dozens or hundreds of files constituting a vanilla web project.\n
\n
\n When inspecting a page load in the browser's developer tools, we would then expect to see a lot of this:\n
\n \n
\n The browser would download 6 files at a time and the later requests would block until those files downloaded.\n 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\n was per domain it also led to the popularity of CDN networks which allowed cheating and downloading 12 files at once instead of 6.\n
\n
\n However. It's 2025. What you're likely to see in this modern era is more like this:\n
\n \n
\n 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,\n we now see that all the files that are requested in parallel get downloaded in parallel.\n There's still a small caveat on lossy connections called head-of-line-blocking, fixed in HTTP/3,\n which is presently starting to roll out to web servers across the internet.\n
\n
\n 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.\n We don't need to bundle up the files in a vanilla web project until the file counts get ridiculous.\n
\n\n
Resolving paths
\n\n
\n Another thing that bundlers do is resolving relative paths pointing to imported JS and CSS files.\n See, for example, the elegance of CSS modules for importing styles into a react component from a relative path:\n
\n
layout.tsx (React):
import styles from './styles.module.css'\n \nexport default function Layout({\n children,\n}: {\n children: React.ReactNode\n}) {\n return <section className={styles.dashboard}>{children}</section>\n}
\n
\n However. It's 2025. And our browsers now have a modern vanilla toolbox for importing.\n When we bootstrap our JS with the magic incantation <script src=\"index.js\" type=\"module\"></script>\n we unlock the magic ability to import JS files using ES module import notation:\n
\n Inside of such files we also get access to import.meta.url, the URL of the current JS file,\n and import.meta.resolve(), a function that resolves a path relative to the current file,\n even a path to a CSS file:\n
\n While not quite the same as what the bundler does, it still enables accessing any file by its relative path,\n and that in turn allows organizing projects in whatever way we want, for example in a feature-based folder organization.\n All without needing a build step.\n
\n
\n This ability to do relative imports can be super-charged by import maps,\n which decouple the name of what is imported from the path of the file it is imported from,\n again all without involving a build step.\n
\n\n
Optimizing bundled code
\n\n
\n Another thing bundlers can do is optimizing the bundled code, by splitting the payload into things loaded initially,\n and things loaded later on lazily. And also by minifying it, stripping away unnecessary whitespace and comments so it will load faster.\n
\n
\n However. It's 2025. We can transparently enable gzip or brotli compression on the server,\n and as it turns out that gets almost all the benefit of minifying. \n While minifying is nice, gzipping is what we really want, and we can get that without a build step.\n
\n
\n 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.\n I wrote before how React's lazy and suspense can be ported easily to vanilla web components.\n
\n\n
Happy new year!
\n\n
\n Great news! It's 2025, and the browser landscape is looking better than ever. It gives us enough tools that for many web projects\n we can drop the bundler and do just fine. You wouldn't believe it based on what the mainstream frameworks are doing though.\n Maybe 2025 is the year we finally see a wide recognition of just how powerful the browser platform has gotten,\n and a return to old school simplicity in web development practice, away from all those complicated build steps. \n It's my new year's resolve to do my part in spreading the word.\n
\n ]]>\n \n \n <![CDATA[Caching vanilla sites]]>\n \n https://plainvanillaweb.com/blog/articles/2024-12-16-caching-vanilla-sites/\n 2024-12-16T12:00:00.000Z\n 2024-12-16T12:00:00.000Z\n \n \n \n \n If you go to a typical website built with a framework, you'll see a lot of this:\n \n \n
\n Those long cryptic filenames are not meant to discourage casual snooping.\n They're meant to ensure the filename is changed every time a single byte in that file changes,\n because the site is using far-future expire headers, \n a technique where the browser is told to cache files indefinitely, until the end of time.\n On successive page loads those resources will then always be served from cache.\n The only drawback is having to change the filename each time the file's contents change, \n but a framework's build steps typically take care of that.\n
\n
\n For vanilla web sites, this strategy doesn't work. By abandoning a build step there is no way to automatically generate filenames,\n and unless nothing makes you happier than renaming all files manually every time you deploy a new version,\n we have to look towards other strategies.\n
\n\n
How caching works
\n\n
\n Browser cache behavior is complicated, and a deep dive into the topic deserves its own article.\n However, very simply put, what you'll see is mostly these response headers:\n
\n
\n
Cache-Control
\n
\n
\n The cache control response header determines whether the browser should cache the response, and how long it should serve the response from cache.\n
\n
Cache-Control: public, max-age: 604800
\n
\n This will cache the resource and only check if there's a new version after one week.\n
\n
\n
Age
\n
\n
\n The max-age directive does not measure age from the time that the response is received,\n but from the time that the response was originally served:\n
\n
Age: 10
\n
\n This response header indicates the response was served on the origin server 10 seconds ago.\n
\n
\n
Etag
\n
\n
\n The Etag header is a unique hash of the resource's contents, an identifier for that version of the resource.\n
\n When the browser requests that resource again from the server, knowing the Etag it can pass an If-None-Match\n header with the Etag's value. If the resource has not changed it will still have the same Etag value,\n and the server will respond with 304 Not Modified. \n
\n The Last-Modified header works similarly to Etag, except instead of sending a hash of the contents,\n it sends a timestamp of when the resource was last changed. \n Like Etag's If-None-Match it is matched by the If-Modified-Since header when requesting the resource from the server again.\n
\n
\n
\n\n
\n With that basic review of caching headers, let's look at some strategies for making good use of them in vanilla web projects.\n
\n\n
Keeping it simple: GitHub Pages
\n\n
\n The simplest strategy is what GitHub Pages does: cache files for 10 minutes.\n Every file that's downloaded has Cache-Control: max-age headers that make it expire 10 minutes into the future.\n After that if the file is loaded again it will be requested from the network.\n The browser will add If-None-Match or If-Modified-Since headers\n to allow the server to avoid sending the file if it hasn't been changed, saving bytes but not a roundtrip.\n
\n
\n If you want to see it in action, just open the browser devtools and reload this page.\n
\n \n
\n Visitors never get a page that is more than 10 minutes out of date,\n and as they navigate around the site they mostly get fast cache-served responses.\n However, on repeat visits they will get a slow first-load experience.\n 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.\n Well, for 10 minutes at least.\n
\n\n
Extending cache durations
\n
\n While the 10 minute cache policy is ok for HTML content and small JS and CSS files,\n it can be improved by increasing cache times on large resources like libraries and images.\n By using a caching proxy that allows setting rules on specific types or folders of files we can increase the cache duration.\n For sites proxied through Cloudflare, \n their cache customization settings \n can be used to set these resource-specific policies.\n
\n
\n By setting longer cache durations on some resources, we can ensure they're served from local cache more often.\n 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.\n For example, by appending a unique query parameter:\n
\n The awkward aspect of having to change the referred URL in every place that a changed file is used\n makes extending cache durations inconvenient for files that are changed often or are referred in many places.\n
\n
\n Also, applying such policies to JavaScript or CSS becomes a minefield,\n because a mismatched combination of JS or CSS files could end up in the browser cache indefinitely,\n breaking the website for the user until URL's are changed or their browser cache is cleared.\n 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.\n
\n\n
Complete control with service workers
\n\n
\n A static web site can take complete control over its cache behavior by using a service worker.\n The service worker intercepts every network request and then decides whether to serve it from a local cache or from the network.\n For example, here's a service worker that will cache all resources indefinitely, until its version is changed:\n
\n
let cacheName = 'cache-worker-v1';\n// these are automatically cached when the site is first loaded\nlet initialAssets = [\n './',\n 'index.html',\n 'index.js',\n 'index.css',\n 'manifest.json',\n 'android-chrome-512x512.png',\n 'favicon.ico',\n 'apple-touch-icon.png',\n 'styles/reset.css',\n // the rest will be auto-discovered\n];\n\n// initial bundle (on first load)\nself.addEventListener('install', (event) => {\n event.waitUntil(\n caches.open(cacheName).then((cache) => {\n return cache.addAll(initialAssets);\n })\n );\n});\n\n// clear out stale caches after service worker update\nself.addEventListener('activate', (event) => {\n event.waitUntil(\n caches.keys().then((cacheNames) => {\n return Promise.all(\n cacheNames.map((cacheName) => {\n if (cacheName !== self.cacheName) {\n return caches.delete(cacheName);\n }\n })\n );\n })\n );\n});\n\n// default to fetching from cache, fallback to network\nself.addEventListener('fetch', (event) => {\n const url = new URL(event.request.url);\n\n // other origins bypass the cache\n if (url.origin !== location.origin) {\n networkOnly(event);\n // default to fetching from cache, and updating asynchronously\n } else {\n staleWhileRevalidate(event);\n }\n});\n\nconst networkOnly = (event) => {\n event.respondWith(fetch(event.request));\n}\n\n// fetch events are serviced from cache if possible, but also updated behind the scenes\nconst staleWhileRevalidate = (event) => {\n event.respondWith(\n caches.match(event.request).then(cachedResponse => {\n const networkUpdate = \n fetch(event.request).then(networkResponse => {\n caches.open(cacheName).then(\n cache => cache.put(event.request, networkResponse));\n return networkResponse.clone();\n }).catch(_ => /*ignore because we're probably offline*/_);\n return cachedResponse || networkUpdate;\n })\n );\n}
\n
\n This recreates the far-future expiration strategy but does it client-side, inside the service worker.\n Because only the version at the top of the sw.js file needs to be updated when the site's contents change,\n this becomes practical to do without adding a build step. However, because the service worker intercepts network requests\n 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.\n (And no, the above service worker code hasn't been baked in production, so be careful when copying it to your own site.)\n
\n \n
Wrapping up
\n
\n Setting sane cache policies meant to optimize page load performance is one of the things typically in the domain\n of full-fat frameworks or application servers. But, abandoning build steps and server-side logic does not necessarily \n have to mean having poor caching performance. There are multiple strategies with varying amounts of cache control,\n and there is probably a suitable strategy for any plain vanilla site.\n
\n
\n Last but not least, an even better way to speed up page loading is to keep the web page itself light.\n Using a plain vanilla approach to pages with zero dependencies baked into the page weight\n already puts you in pole position for good page load performance, before caching even enters the picture.\n
\n ]]>\n \n \n <![CDATA[Editing Plain Vanilla]]>\n \n https://plainvanillaweb.com/blog/articles/2024-10-20-editing-plain-vanilla/\n 2024-10-20T12:00:00.000Z\n 2024-10-20T12:00:00.000Z\n \n \n \n \n I'm typing this up in Visual Studio Code, after realizing I should probably explain how I use it to make this site.\n But the whole idea behind Plain Vanilla is no build, no framework, no tools.\n And VS Code is definitely a tool. So what gives?\n \n
\n 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.\n The first category, like npm or typescript, impose continued maintenance on the project because they form a direct dependency.\n The second category, like VS Code or git, are easily replaced without impacting the project's ability to be edited.\n There's a tension between the ability to get things done faster, and the burden created by additional dependencies.\n For this project I draw the line in accepting the second category while rejecting the first.\n
\n
Setting up a profile
\n
\n I use VS Code for framework-based work projects as well as vanilla web development.\n To keep those two realms neatly separated I've set up a separate Vanilla profile. \n In that profile is a much leaner suite of extensions, configured for only vanilla web development.\n
\n
\n
ESLint, to automatically lint the JS code while editing
\n
webhint, to lint the HTML and CSS code, and detect accessibility issues
\n
html-in-template-string, to syntax highlight HTML template strings
\n
Todo Tree, to keep track of TODO's while doing larger changes
\n
Live Preview, to get a live preview of the page that I'm working on
\n
VS Code Counter, for quick comparative line counts when porting framework code to vanilla
\n
Intellicode, for simple code completion
\n
Codeium, for AI-assisted code completion, works great for web component boilerplate
\n
\n
\n Modern web development can be very overburdened by tools, sometimes all but requiring the latest Macbook Pro with decadent amounts of RAM\n just to edit a basic project. The combination of a no build plain vanilla codebase with a lean VS Code profile guarantees quick editing,\n even on my oldest and slowest laptops.\n
\n
Linting
\n
\n Nobody's perfect, myself included, so something needs to be scanning the code for goofs.\n The first linting tool that's set up is ESLint. The VS Code extension regrettably does not come bundled with an eslint installation,\n so this has to be installed explicitly. By doing it once globally this can be reused across vanilla web projects.\n
\n
npm install -g eslint @eslint/js globals
\n
\n Because I use nvm to manage node versions the global eslint install was not automatically detectable.\n This required setting a NODE_PATH in .zshrc that VS Code then picked up.\n
\n
export NODE_PATH=$(npm root -g)
\n
\n In addition, in order to lint successfully it needs a configuration file, located in the project's root.\n
\n Setting the ecmaVersion to 2022 ensures that I don't accidentally use newer and unsupported Javascript features,\n like in this example trying to use ES2024's v flag in regular expressions.\n This version could be set to whatever browser compatibility a project requires.\n
\n \n
\n The ignores blocks excludes external libraries to placate my OCD that wants to see zero errors or warnings reported by eslint project-wide.\n The article folders are excluded for a similar reason, because they contain a lot of incomplete and deliberately invalid example JS files.\n
\n
\n The webhint extension is installed to do automatic linting on HTML and CSS.\n Luckily it out of the box comes bundled with a webhint installation and applies the default development ruleset.\n A nice thing about this extension is that it reports accessibility issues.\n
\n \n
\n Only a few tweaks were made to the webhint configuration to again get to that all-important zero warnings count.\n
\n I've mentioned it before in the entity encoding article,\n but this neat little extension formats HTML inside tagged template strings in web component JS code.\n
\n \n\n
Live Preview
\n
\n The center piece for a smooth editing workflow is the Live Preview extension.\n I can right-click on any HTML file in the project and select \"Show Preview\" to get a live preview of the page.\n This preview automatically refreshes when files are saved. Because vanilla web pages always load instantly\n this provides the hot-reloading workflow from framework projects, except even faster and with zero setup.\n The only gotcha is that all paths in the site have to be relative paths so the previewed page can resolve them.\n
\n \n
\n The preview's URL can be pasted into a \"real browser\" to debug tricky javascript issues\n and do compatibility testing. Very occasionally I'll need to spin up a \"real server\", \n but most of the code in my vanilla projects is written with only a Live Preview tab open.\n
\n
\n Previewing is also how I get a realtime view of unit tests while working on components or infrastructure code,\n by opening the tests web page and selecting the right test suite to hot reload while editing.\n
\n\n
Bonus: working offline
\n
\n Because I live at the beach and work in the big city I regularly need to take long train rides with spotty internet connection.\n Like many developers I cannot keep web API's in my head and have to look them up regularly while coding.\n To have a complete offline vanilla web development setup with me at all times I use devdocs.io.\n All my projects folders are set up to sync automatically with Syncthing, \n so whatever I was doing on the desktop can usually be smoothly continued offline on the laptop \n without having to do any prep work to make that possible.\n
\n \n\n
\n There, that's my lean vanilla web development setup.\n What should I add to this, or do differently? Feel free to let me know.\n
\n ]]>\n \n \n <![CDATA[Needs more context]]>\n \n https://plainvanillaweb.com/blog/articles/2024-10-07-needs-more-context/\n 2024-10-07T12:00:00.000Z\n 2024-10-07T12:00:00.000Z\n \n \n \n \n In the earlier article the unreasonable effectiveness of vanilla JS\n I explained a vanilla web version of the React tutorial example Scaling up with Reducer and Context.\n That example used a technique for context based on Element.closest().\n While that way of obtaining a context is very simple, which definitely has its merits,\n it also has some downsides:\n \n
\n
It cannot be used from inside a shadow DOM to find a context that lives outside of it without clumsy workarounds.
\n
It requires a custom element to be the context.
\n
There has to be separate mechanism to subscribe to context updates.
\n
\n
\n There is in fact, or so I learned recently, a better and more standard way to solve this\n known as the context protocol. \n It's not a browser feature, but a protocol for how to implement a context in web components.\n
\n
\n This is how it works: the consumer starts by dispatching a context-request event.\n
\n The event will travel up the DOM tree (bubbles = true), piercing any shadow DOM boundaries (composed = true),\n until it reaches a listener that responds to it. This listener is attached to the DOM by a context provider.\n The context provider uses the e.context property to detect whether it should respond,\n then calls e.callback with the appropriate context value.\n Finally it calls e.stopPropagation() so the event will stop bubbling up the DOM tree.\n
\n
\n This whole song and dance is guaranteed to happen synchronously, which enables this elegant pattern:\n
\n
customElements.define('my-component', class extends HTMLElement {\n connectedCallback() {\n let theme = 'light'; // default value\n this.dispatchEvent(\n new ContextRequestEvent('theme', t => theme = t)\n );\n // do something with theme\n }\n});\n
\n
\n If no provider is registered the event's callback is never called and the default value will be used instead.\n
\n
\n Instead of doing a one-off request for a context's value it's also possible to subscribe to updates\n by setting its subscribe property to true.\n Every time the context's value changes the callback will be called again.\n To ensure proper cleanup the subscribing element has to unsubscribe on disconnect.\n
\n
customElements.define('my-component', class extends HTMLElement {\n #unsubscribe;\n connectedCallback() {\n this.dispatchEvent(\n new ContextRequestEvent('theme', (theme, unsubscribe) => {\n this.#unsubscribe = unsubscribe;\n // do something with theme\n }, true)\n );\n }\n disconnectedCallback() {\n this.#unsubscribe?.();\n }\n});\n
\n
\n It is recommended, but not required, to listen for and call unsubscribe functions in one-off requests,\n just in case a provider is overzealously creating subscriptions.\n However, this is not necessary when using only spec-compliant providers.\n
\n
customElements.define('my-component', class extends HTMLElement {\n connectedCallback() {\n let theme = 'light';\n this.dispatchEvent(\n new ContextRequestEvent('theme', (t, unsubscribe) => {\n theme = t;\n unsubscribe?.();\n })\n );\n // do something with theme\n }\n});\n
\n
\n Providers are somewhat more involved to implement.\n There are several spec-compliant libraries that implement them,\n like @lit/context \n and wc-context.\n A very minimal implementation is this one:\n
\n Notice in the above example that the theme-toggle context is providing a function.\n This unlocks a capability for dependency injection where API's to control page behavior\n are provided by a context to any subscribing custom element.\n
\n
\n Don't let this example mislead you however. A provider doesn't actually need a dedicated custom element,\n and can be attached to any DOM node, even the body element itself.\n This means a context can be provided or consumed from anywhere on the page.\n
\n
// loaded with <script type=\"module\" src=\"theme-provider.js\"></script>\n\nimport { ContextProvider } from \"./context-provider.js\";\n\nconst themeProvider = new ContextProvider(document.body, 'theme', 'light');\nconst toggleProvider = new ContextProvider(document.body, 'theme-toggle', () => {\n themeProvider.value = themeProvider.value === 'light' ? 'dark' : 'light';\n});\n
\n
\n And because there can be more than one event listener on a page,\n there can be more than one provider providing the same context.\n The first one to handle the event will win.\n
\n
\n Here's an example that illustrates a combination of a global provider attached to the body (top panel),\n and a local provider using a <theme-context> (bottom panel).\n Every time the <theme-toggle> is reparented it resubscribes to the theme from the nearest provider.\n
\n The full implementation of this protocol can be found in the tiny-context repo on Github.\n
\n ]]>\n \n \n <![CDATA[Lived experience]]>\n \n https://plainvanillaweb.com/blog/articles/2024-09-30-lived-experience/\n 2024-09-30T12:00:00.000Z\n 2024-09-30T12:00:00.000Z\n \n \n \n \n Ryan Carniato shared a hot take a few days ago, Web Components Are Not the Future.\n As hot takes tend to do, it got some responses, like Nolan Lawson's piece Web components are okay,\n or Cory LaViska's Web Components Are Not the Future — They're the Present.\n They do an excellent job of directly engaging Ryan's arguments, so I'm not going to do that here.\n Instead I want to talk about my lived experience of web development, and where I hope it is headed in the future.\n Take it in the spirit it is intended, one of optimism and possibility.\n \n\n
A galaxy far, far away
\n
\n So I've been making web sites since a long time ago, since before CSS and HTML4.\n I say this not to humblebrag, but to explain that I was here for all of it.\n Every time when the definition of modern web development changed I would update my priors, following along.\n
\n
\n For the longest time making web pages do anything except show text and images was an exercise in frustration.\n Browsers were severely lacking in features, were wildly incompatible with web standards and each other,\n and the tools that web developers needed to bring them to order were missing or lacking.\n I built my share of vanilla JS components back in the IE6 days, and it made me dream of a better way.\n When frameworks first started coming on the scene with that better way, adding missing features, abstracting away incompatibility,\n and providing better tooling, I was ready for them. I was all-in.\n
\n
\n 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\n 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.\n 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.\n I helped rewrite a bunch of frontends in Angular v2 and React, \n and found myself sucked into constant forced maintenance when their architecture and ecosystems churned.\n
\n
\n Did I make bad choices? Even in hindsight I would say I picked the right choices for the time.\n Time just moved on.\n
\n\n
The cost of change
\n
\n This lived experience taught me a strong awareness of rates of change in dependencies, and the costs they impose.\n I imagine a web page as a thin old man sitting astride a tall pile of dependencies, each changing at their own pace.\n Some dependencies are stable for decades, like HTML's core set of elements, or CSS 2's set of layout primitives. \n They're so stable that we don't even consider them dependencies, they're just the web.\n
\n
\n Other dependencies change every few years, like module systems, or new transpiled languages, \n or the preferred build and bundling tool of the day, or what framework is in vogue.\n Then there are the dependencies that change yearly, like major framework and OS releases.\n Finally there are the dependencies that change constantly, like the many packages that contribute\n to a typical web application built with a popular framework.\n
\n
\n As a web developer who loves their user, taking on those dependencies creates a Solomon's choice.\n Either you keep up with the churn, and spend a not insignificant amount of your day working and reworking code\n that already works, instead of working on the things your user cares about. \n Or, you stick it out for as long as you can on old versions, applying ever more workarounds to get \n old framework releases and their outdated build and CLI tools to work in new OS and ecosystem environments,\n slowly boiling a frog that will at some point force a deep rewrite, again at the expense of the user.\n
\n
\n Which is not to say the frameworks don't add value. They absolutely do, and they keep getting better. \n Writing new code on a new framework is a steadily rising tide of developer experience. \n But let us not pretend these benefits don't come at a cost.\n Wherever there is a codebase too complicated to understand and maintain yourself, wherever there is a set of build tools \n that must be kept compatible with changes in operating systems and ecosystems,\n there is a shelf life. Sooner or later the makers of every framework and of every tool will move on,\n 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.\n
\n
\n I hold this truth to be self-evident: the larger the abstraction layer a web developer uses on top of web standards,\n the shorter the shelf life of their codebase becomes, and the more they will feel the churn.\n
\n\n
The rising tide
\n
\n Why do modern web projects built with modern frameworks depend on so much stuff?\n At first there was no other option. Interacting with the DOM was painful, \n and web frameworks rightly made choices to keep component systems outside the DOM, minimizing and abstracting away those interactions\n in increasingly clever DOM reconciliation strategies. Supporting the brittle browsers and slow devices of the day required many workarounds and polyfills,\n and web frameworks rightly added intricate tools to build, bundle and minify the user's code.\n
\n
\n They needed a way to bring dependencies into those build systems, and sanely settled on the convention of node modules\n and the NPM ecosystem. It got easy to add more dependencies, and just as water always finds the easy way down,\n dependencies found the easy way in. As the abstraction layer grew the load time cost imposed by it grew right along,\n and so we got server-side rendering, client-side hydration, lazy loading, and many other load time reduction strategies.\n
\n
\n DOM-diffing, synthetic event systems, functional components, JSX, reactive data layers, server-side rendering and streaming, bundlers, tree shaking, \n 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 —\n 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.\n And all of those things are downstream from the decision to abstract away the browser,\n a decision once made in good faith and for good reasons. A decision which now needs revisiting.\n
\n
\n Browsers were not standing still. They saw what web developers were doing in userland to compensate \n 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.\n When Microsoft bid IE a well-deserved farewell on June 15, 2022 a tipping point was reached.\n 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.\n It wasn't a great platform, not as cleanly designed or complete as the API's of the popular frameworks,\n but it was Good Enough™ as a foundation, and that was all that mattered.\n
\n\n
Holding my breath
\n\n
\n I was very excited for what would happen in the framework ecosystem. There was a golden opportunity for frameworks \n to tear down their abstraction layers, make something far simpler, far more closely aligned with the base web platform. \n They could have a component system built on top of web components,\n leveraging browser events and built-in DOM API's. All the frameworks could become cross-compatible, \n easily plugging into each other's data layers and components while preserving what makes them unique.\n The page weights would shrink by an order of magnitude with so much infrastructure code removed,\n and that in combination with the move to HTTP/3 could make build tools optional.\n It would do less, so inevitably be worse in some ways, but sometimes worse is better.\n
\n
\n I gave a talk about how good the browser's platform had gotten, \n showing off a version of Create React App that didn't need any build tools\n and was extremely light-weight, and the developer audience was just as excited as I was.\n And I held my breath waiting on framework churn to for once go in the other direction, towards simplicity...\n
\n
\n But nothing happened. In fact, the major frameworks kept building up their abstraction layers instead of building down.\n We got React Server Components and React Compiler, exceedingly clever, utterly incomprehensible, \n workarounds for self-imposed problems caused by overengineering.\n Web developers don't seem to mind, but they struggle quietly with how to keep up with these tools and deliver good user experiences. \n The bigger the abstraction layer gets, the more they feel the churn.\n
\n
\n The irony is not lost on me that now the framework authors also feel the churn in their dependencies,\n struggling to adapt to web components as foundational technology. React 19 is supposed to finally support web components\n in a way that isn't incredibly painful, or so they say, we'll see. I confess to feeling some satisfaction\n in their struggle. The shoe is on the other foot. Welcome to modern web development.\n
\n \n
The road ahead
\n\n
\n What the frameworks are doing, that's fine for them, and they can keep doing it. \n But I'm done with all that unless someone is paying me to do it.\n They're on a fundamentally different path from where I want web development to go, from how I want to make web pages.\n The web is what ships to the browser. Reducing the distance between what the developer writes and what ships to the browser\n is valuable and necessary. This blog and this site are my own stake in the ground for this idea, \n showing just how much you can get done without any framework code or build tools at all. \n But let's be honest: web components are not a framework, no matter how hard I tried to explain them as one.\n
\n\n
\n
Comparing web components to React is like comparing a good bicycle with a cybertruck.
\n
They do very different things, and they're used by different people with very, very different mindsets.
\n I want a motorbike, not a cybertruck. I still want frameworks, only much lighter. \n Frameworks less than 10 KB in size, that are a thin layer on top of web standards\n but still solve the problems that frameworks solve. I call this idea the interoperable web framework:\n
\n
\n
Its components are just web components.
\n
Its events are just DOM events.
\n
Its templates are just HTML templates.
\n
It doesn't need to own the DOM that its components take part in.
\n
Its data and event binding works on all HTML elements, built-in or custom, made with the framework or with something else.
\n
It can be easily mixed together on a page with other interoperable web frameworks, with older versions of itself, or with vanilla code.
\n
It doesn't need its own build tools.
\n
\n
\n I just feel it on my bones such a thing can be built now. Maybe I'm wrong and Ryan Carniato is right.\n 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.\n Some existing solutions like Lit are close, but none are precisely what I am looking for. \n I would love to see a community of vanilla developers come together to figure out what that could look like,\n running experiments and iterating on the results. For now I will just keep holding my breath, waiting for the tide to come in.\n
\n ]]>\n \n \n <![CDATA[The unreasonable effectiveness of vanilla JS]]>\n \n https://plainvanillaweb.com/blog/articles/2024-09-28-unreasonable-effectiveness-of-vanilla-js/\n 2024-09-28T12:00:00.000Z\n 2024-09-28T12:00:00.000Z\n \n \n \n \n I have a confession to make. At the end of the Plain Vanilla tutorial's Applications page\n a challenge was posed to the reader: port react.dev's final example \n Scaling Up with Reducer and Context to vanilla web code.\n Here's the confession: until today I had never actually ported over that example myself.\n \n
\n That example demonstrates a cornucopia of React's featureset.\n Richly interactive UI showing a tasks application, making use of a context to lift the task state up,\n and a reducer that the UI's controls dispatch to. React's DOM-diffing algorithm gets a real workout \n because each task in the list can be edited independently from and concurrently with the other tasks. \n It is an intricate and impressive demonstration. Here it is in its interactive glory:\n
\n But I lied. That interactive example is actually the vanilla version and it is identical.\n If you want to verify that it is in fact identical, check out the original React example.\n And with that out of the way, let's break apart the vanilla code.\n
\n\n
Project setup
\n\n
The React version has these code files that we will need to port:
\n
\n
public/index.html
\n
src/styles.css
\n
src/index.js: imports the styles, bootstraps React and renders the App component
\n
src/App.js: renders the context's TasksProvider containing the AddTask and TaskList components
\n
src/AddTask.js: renders the simple form at the top to add a new task
\n
src/TaskList.js: renders the list of tasks
\n
\n
\n To make things fun, I chose the same set of files with the same filenames for the vanilla version.\n Here's index.html:\n
\n The only real difference is that it links to index.js and styles.css.\n The stylesheet was copied verbatim, but for the curious here's a link to styles.css.\n
\n \n
Get to the code
\n\n
\n index.js is where it starts to get interesting.\n Compare the React version to the vanilla version:\n
\n
index.js (React):
import React, { StrictMode } from \"react\";\nimport { createRoot } from \"react-dom/client\";\nimport \"./styles.css\";\n\nimport App from \"./App\";\n\nconst root = createRoot(document.getElementById(\"root\"));\nroot.render(\n <StrictMode>\n <App />\n </StrictMode>\n);
\n Bootstrapping is different but also similar. All of the web components are imported first to load them,\n and then the <tasks-app> component is rendered to the page.\n
\n
\n The App.js code also bears more than a striking resemblance:\n
\n
App.js (React):
import AddTask from './AddTask.js';\nimport TaskList from './TaskList.js';\nimport { TasksProvider } from './TasksContext.js';\n\nexport default function TaskApp() {\n return (\n <TasksProvider>\n <h1>Day off in Kyoto</h1>\n <AddTask />\n <TaskList />\n </TasksProvider>\n );\n}\n
\n
App.js (Vanilla):
customElements.define('tasks-app', class extends HTMLElement {\n connectedCallback() {\n this.innerHTML = `\n <tasks-context>\n <h1>Day off in Kyoto</h1>\n <task-add></task-add>\n <task-list></task-list>\n </tasks-context>\n `;\n }\n});\n
\n\n
\n What I like about the code so far is that it feels React-like. I generally find programming against React's API pleasing,\n but I don't like the tooling, page weight and overall complexity baggage that it comes with.\n
\n\n
Adding context
\n\n
\n The broad outline of how to bring a React-like context to a vanilla web application is\n already explained in the passing data deeply section \n of the main Plain Vanilla tutorial, so I won't cover that again here.\n What adds spice in this specific case is that the React context uses a reducer,\n a function that accepts the old tasks and an action to apply to them, and returns the new tasks to show throughout the application.\n
\n
\n Thankfully, the React example's reducer function and initial state were already vanilla JS code,\n so those come along for the ride unchanged and ultimately the vanilla context is a very straightforward custom element:\n
\n The actual context component is very bare bones, as it only needs to store the tasks,\n emit change events for the other components to subscribe to, and provide a dispatch method \n for those components to call that will use the reducer function to update the tasks.\n
\n\n
Adding tasks
\n\n
\n The AddTask component ends up offering more of a challenge. It's a stateful component with event listeners that dispatches to the reducer:\n
\n The main wrinkle this adds for the vanilla web component is that the event listener on the button element\n cannot be put inline with the markup. Luckily the handling of the input is much simplified\n because we can rely on it keeping its state automatically, a convenience owed to not using a virtual DOM.\n Thanks to the groundwork in the context component the actual dispatching of the action is easy:\n
\n Fascinating to me is that index.js, App.js, TasksContext.js and AddTask.js\n are all fewer lines of code in the vanilla version than their React counterpart while remaining functionally equivalent. \n
\n\n
Hard mode
\n
\n The TaskList component is where React starts really pulling its weight.\n The React version is clean and straightforward and juggles a lot of state with a constantly updating task list UI.\n
\n This proved to be a real challenge to port. The vanilla version ended up being a lot more verbose\n because it has to do all the same DOM-reconciliation in explicit logic managed by the update() methods\n of <task-list> and <task-item>.\n
\n
TaskList.js (Vanilla):
customElements.define('task-list', class extends HTMLElement {\n get context() { return this.closest('tasks-context'); }\n \n connectedCallback() {\n this.context.addEventListener('change', () => this.update());\n this.append(document.createElement('ul'));\n this.update();\n }\n\n update() {\n const ul = this.querySelector('ul');\n let before = ul.firstChild;\n this.context.tasks.forEach(task => {\n let li = ul.querySelector(`:scope > [data-key=\"${task.id}\"]`);\n if (!li) {\n li = document.createElement('li');\n li.dataset.key = task.id;\n li.append(document.createElement('task-item'));\n }\n li.firstChild.task = task;\n // move to the right position in the list if not there yet\n if (li !== before) ul.insertBefore(li, before);\n before = li.nextSibling;\n });\n // remove unknown nodes\n while (before) {\n const remove = before;\n before = before.nextSibling;\n ul.removeChild(remove);\n }\n }\n});\n\ncustomElements.define('task-item', class extends HTMLElement {\n #isEditing = false;\n #task;\n set task(task) { this.#task = task; this.update(); }\n get context() { return this.closest('tasks-context'); }\n\n connectedCallback() {\n if (this.querySelector('label')) return;\n this.innerHTML = `\n <label>\n <input type=\"checkbox\" />\n <input type=\"text\" />\n <span></span>\n <button id=\"edit\">Edit</button>\n <button id=\"save\">Save</button>\n <button id=\"delete\">Delete</button>\n </label>\n `;\n this.querySelector('input[type=checkbox]').onchange = e => {\n this.context.dispatch({\n type: 'changed',\n task: {\n ...this.#task,\n done: e.target.checked\n }\n });\n };\n this.querySelector('input[type=text]').onchange = e => {\n this.context.dispatch({\n type: 'changed',\n task: {\n ...this.#task,\n text: e.target.value\n }\n });\n };\n this.querySelector('button#edit').onclick = () => {\n this.#isEditing = true;\n this.update();\n };\n this.querySelector('button#save').onclick = () => {\n this.#isEditing = false;\n this.update();\n };\n this.querySelector('button#delete').onclick = () => {\n this.context.dispatch({\n type: 'deleted',\n id: this.#task.id\n });\n };\n this.context.addEventListener('change', () => this.update());\n this.update();\n }\n\n update() {\n if (this.isConnected && this.#task) {\n this.querySelector('input[type=checkbox]').checked = this.#task.done;\n const inputEdit = this.querySelector('input[type=text]');\n inputEdit.style.display = this.#isEditing ? 'inline' : 'none';\n inputEdit.value = this.#task.text;\n const span = this.querySelector('span');\n span.style.display = this.#isEditing ? 'none' : 'inline';\n span.textContent = this.#task.text;\n this.querySelector('button#edit').style.display = this.#isEditing ? 'none' : 'inline';\n this.querySelector('button#save').style.display = this.#isEditing ? 'inline' : 'none';\n }\n }\n});\n
\n
\n Some interesting take-aways:\n
\n
\n
\n The <task-list> component's update() method implements a poor man's version of React reconciliation,\n merging the current state of the tasks array into the child nodes of the <ul>.\n In order to do this, it has to store a key on each list item, just like React requires, and here it becomes obvious why that is.\n Without the key we can't find the existing <li> nodes that match up to task items,\n and so would have to recreate the entire list. By adding the key it becomes possible to update the list in-place,\n modifying task items instead of recreating them so that they can keep their on-going edit state.\n
\n
\n That reconciliation code is very generic however, and it is easy to imagine a fully generic repeat()\n function that converts an array of data to markup on the page. In fact, the Lit framework contains exactly that.\n For brevity's sake this code doesn't go quite that far.\n
\n
\n The <task-item> component cannot do what the React code does: create different markup depending on the current state.\n Instead it creates the union of the markup across the various states, and then in the update()\n shows the right subset of elements based on the current state.\n
\n A peculiar result of this porting challenge is that the vanilla version ends up being roughly \n the same number of lines of code as the React version. The React code is still overall less verbose (all those querySelectors, oy!),\n but it has its own share of boilerplate that disappears in the vanilla version.\n This isn't a diss against React, it's more of a compliment to how capable browsers have gotten that vanilla web components\n can carry us so far.\n
\n
\n If I could have waved a magic wand, what would have made the vanilla version simpler?\n
\n
\n
\n All of those querySelector calls get annoying. The alternatives are building the markup easily with innerHTML\n and then fishing out references to the created elements using querySelector, or building the elements one by one verbosely using createElement,\n but then easily having a reference to them. Either of those ends up very verbose. \n An alternative templating approach that makes it easy to create elements and get a reference to them would be very welcome.\n
\n
\n As long as we're dreaming, I'm jealous of how easy it is to add the event listeners in JSX.\n A real expression language in HTML templates that supports data and event binding and data-conditional markup would be very neat\n and would take away most of the reason to still find a framework's templating language more convenient.\n Web components are a perfectly fine alternative to React components, they just lack an easy built-in templating mechanism.\n
\n
\n Browsers could get a little smarter about how they handle DOM updates during event handling.\n In the logic that sorts the <li> to the right order in the list, \n the if condition before insertBefore proved necessary because the browser\n didn't notice that the element was already placed where it needed to be inserted,\n and click events would get lost as a consequence.\n I've even noticed that assigning a textContent to a button mid-click will make Safari\n lose track of that button's click event. All of that can be worked around with clever reconciliation logic,\n but that's code that belongs in the browser, not in JavaScript.\n
\n
\n
\n All in all though, I'm really impressed with vanilla JS. I call it unreasonably effective because it is\n jarring just how capable the built-in abilities of browsers are, and just how many web developers despite that \n still default to web frameworks for every new project. Maybe one day...\n
\n ]]>\n \n \n <![CDATA[The life and times of a web component]]>\n \n https://plainvanillaweb.com/blog/articles/2024-09-16-life-and-times-of-a-custom-element/\n 2024-09-16T12:00:00.000Z\n 2024-09-16T12:00:00.000Z\n \n \n \n \n When first taught about the wave-particle duality of light most people's brains does a double take.\n How can light be two different categories of things at the same time, both a wave and a particle? That's just weird.\n The same thing happens with web components, confusing people when they first try to learn them and run into their Document-JavaScript duality.\n The component systems in frameworks are typically JavaScript-first, only using the DOM as an outlet for their visual appearance.\n Web components however — or custom elements to be precise — can start out in either JavaScript or the document, and are married to neither.\n \n\n
Just the DOM please
\n\n
\n Do you want to see the minimal JavaScript code needed to set up an <x-example> custom element?\n Here it is:\n
\n
\n
\n No, that's not a typo. Custom elements can be used just fine without any JavaScript.\n Consider this example of an <x-tooltip> custom element that is HTML and CSS only:\n
\n For the curious, here is the example.css, but it is not important here.\n
\n
\n Such elements are called undefined custom elements.\n Before custom elements are defined in the window by calling customElements.define() they always start out in this state.\n There is no need to actually define the custom element if it can be solved in a pure CSS way.\n In fact, many \"pure CSS\" components found online can be solved by such custom elements,\n by styling the element itself and its ::before and ::after pseudo-elements.\n
\n\n
A question of definition
\n\n
\n The CSS-only representation of the custom element can be progressively enhanced by connecting it up to a JavaScript counterpart,\n a custom element class. This is a class that inherits from HTMLElement and allows the custom element\n to implement its own logic.\n
\n What happens to the elements already in the markup at the moment customElements.define()\n is called is an element upgrade. The browser will take all custom elements already in the document,\n and create an instance of the matching custom element class that it connects them to.\n 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.\n
\n
\n Element upgrades occur for existing custom elements in the document when customElements.define() is called,\n and for all new custom elements with that tag name created afterwards (e.g. using document.createElement('x-example')).\n It does not occur automatically for detached custom elements (not part of the document) that were created before the element was defined.\n Those can be upgraded retroactively by calling customElements.upgrade().\n
\n\n
\n So far, this is the part of the lifecycle we've seen:\n
\n The constructor as shown in the example above is optional, but if it is specified then it has a number of gotcha's:\n
\n
\n
It must start with a call to super().
\n
It should not make DOM changes yet, as the element is not yet guaranteed to be connected to the DOM.
\n
\n This includes reading or modifying its own DOM properties, like its attributes.\n The tricky part is that in the constructor the element might already be in the DOM,\n so setting attributes might work. Or it might give an error. It's best to avoid DOM interaction altogether in the constructor.\n
\n
It should initialize its state, like class properties
\n
\n But work done in the constructor should be minimized and maximally postponed until connectedCallback.\n
\n
\n\n
Making connections
\n\n
\n After being constructed, if the element was already in the document, its connectedCallback() handler is called.\n 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.\n In this handler DOM changes can be made, and in the example above the status attribute is set to demonstrate this.\n
\n
\n The connectedCallback() handler is part of what is known in the HTML standard as custom element reactions:\n These reactions allow the element to respond to various changes to the DOM:\n
\n
\n
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.
\n
disconnectedCallback() is called when the element is removed from the document.
\n
adoptedCallback() is called when the element is moved to a new document. (You are unlikely to need this in practice.)
\n
attributeChangedCallback() is called when an attribute is changed, but only for the attributes listed in its observedAttributes property.
\n
\n
\n There are also special reactions for form-associated custom elements, \n but those are a rabbit hole beyond the purview of this blog post.\n
\n
\n There are more gotcha's to these reactions:\n
\n
\n
connectedCallback() and disconnectedCallback() can be called multiple times
\n
\n This can occur when the element is moved around in the document.\n These handlers should be written in such a way that it is harmless to run them multiple times,\n e.g. by doing an early exit when it is detected that connectedCallback() was already run.\n
\n
attributeChangedCallback() can be called before connectedCallback()
\n
\n For all attributes already set when the element in the document is upgraded,\n the attributeChangedCallback() handler will be called first,\n and only after this connectedCallback() is called.\n The unpleasant consequence is that any attributeChangedCallback that tries to update DOM structures\n created in connectedCallback can produce errors.\n
\n
attributeChangedCallback() is only called for attribute changes, not property changes.
\n
\n Attribute changes can be done in Javascript by calling element.setAttribute('name', 'value').\n DOM attributes and class properties can have the same name, but are not automatically linked.\n Generally for this reason it is better to avoid having attributes and properties with the same name.\n
\n
\n\n
\n The lifecycle covered up to this point for elements that start out in the initial document:\n
\n So far we've covered one half of the Document-JavaScript duality, for custom elements starting out in the document,\n and only after that becoming defined and gaining a JavaScript counterpart.\n It is however also possible to reverse the flow, and start out from JavaScript.\n
\n
\n This is the minimal code to create a custom element in JavaScript: document.createElement('x-example').\n 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\n as if it was part of the original HTML markup.\n
\n
\n If it is inserted, and after insertion the element becomes defined, then it will behave as described above.\n Things are however different if the element remains detached:\n
\n
\n
The detached element will not be automatically upgraded when it is defined.
\n
\n The constructor or reactions will not be called. It will be automatically upgraded when it is inserted into the document.\n It can also be upgraded explicitly by calling customElements.upgrade().\n
\n
If the detached element is already defined when it is created, it will be upgraded automatically.
\n
The constructor() and attributeChangedCallback() will be called. Because it is not yet part of the document connectedCallback() won't be.
\n
\n
\n By now no doubt you are a bit confused. Here's an interactive playground that lets you test\n what happens to elements as they go through their lifecycle, both for those in the initial document and those created dynamically.\n
Create, then Define, and you will see that the created element is not upgraded automatically because it is detached from the document.
\n
Create, then Connect, then Define, and you will see that the element is upgraded automatically because it is in the document.
\n
Define, then Create, and you will see that the element is upgraded as soon as it is created (constructed appears in the reactions).
\n
\n
\n I tried writing a flowchart of all possible paths through the lifecycle that can be seen in this example,\n but it got so unwieldy that I think it's better to just play around with the example until a solid grasp develops.\n
\n\n
In the shadows
\n\n
\n Adding shadow DOM creates yet another wrinkle in the lifecycle.\n 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().\n Because the shadow DOM is immediately available for DOM operations, that makes it possible to do those DOM operations in the constructor.\n
\n
\n In this next interactive example you can see what happens when the shadow DOM becomes attached.\n The x-shadowed element will immediately attach a shadow DOM in its constructor,\n which happens when the element is upgraded automatically after defining.\n The x-shadowed-later element postpones adding a shadow DOM until a link is clicked,\n so the element first starts out as a non-shadowed custom element, and adds a shadow DOM later.\n
\n While adding a shadow DOM can be done at any point, it is a one-way operation.\n Once added the shadow DOM will replace the element's original contents, and this cannot be undone.\n
\n\n
Keeping an eye out
\n\n
\n So far we've mostly been dealing with initial setup of the custom element,\n but a major part of the lifecycle is responding to changes as they occur.\n Here are some of the major ways that custom elements can respond to DOM changes:\n
\n
\n
connectedCallback and disconnectedCallback to handle DOM insert and remove of the element itself.
\n
attributeChangedCallback to handle attribute changes of the element.
\n
For shadowed custom elements, the slotchange event can be used to detect when children are added and removed in a <slot>.
\n
Saving the best for last, MutationObserver can be used to monitor DOM subtree changes, as well as attribute changes.
\n
\n
\n MutationObserver in particular is worth exploring, because it is a swiss army knife for monitoring the DOM.\n Here's an example of a counter that automatically updates when new child elements are added:\n
<!doctype html>\n<html> \n <head>\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1, minimum-scale=1\" />\n <title>custom element with observer</title>\n <style>\n body { font-family: system-ui, sans-serif; margin: 1em; }\n x-wall { display: block; margin-bottom: 1em; }\n </style>\n </head>\n <body>\n <x-wall><x-bottle></x-bottle></x-wall>\n <button onclick=\"add()\">Add one more</button>\n <button onclick=\"location.reload()\">Reload</button>\n\n <script>\n customElements.define('x-wall', class extends HTMLElement {\n connectedCallback() {\n if (this.line) return; // prevent double initialization\n this.line = document.createElement('p');\n this.insertBefore(this.line, this.firstChild);\n new MutationObserver(() => this.update()).observe(this, { childList: true });\n this.update();\n }\n update() {\n const count = this.querySelectorAll('x-bottle').length;\n this.line.textContent = \n `${count} ${count === 1 ? 'bottle' : 'bottles'} of beer on the wall`;\n }\n });\n customElements.define('x-bottle', class extends HTMLElement {\n connectedCallback() { this.textContent = '🍺'; }\n });\n function add() {\n document.querySelector('x-wall').append(\n document.createElement('x-bottle'));\n }\n </script>\n </body>\n</html>
\n\n
\n There is still more to tell, but already I can feel eyes glazing over and brains turning to mush,\n so I will keep the rest for another day.\n
\n\n \n\n
\n Phew, that was a much longer story than I originally set out to write, but custom elements have surprising intricacy.\n I hope you found it useful, and if not at least you got to see some code and click some buttons.\n It's all about the clicking of the buttons.\n
\n ]]>\n \n \n <![CDATA[Sweet Suspense]]>\n \n https://plainvanillaweb.com/blog/articles/2024-09-09-sweet-suspense/\n 2024-09-09T12:00:00.000Z\n 2024-09-09T12:00:00.000Z\n \n \n \n \n I was reading Addy Osmani and Hassan Djirdeh's book Building Large Scale Web Apps.\n (Which, by the way, I can definitely recommend.) In it they cover all the ways to make a React app sing at scale.\n The chapter on Modularity was especially interesting to me, because JavaScript modules\n are a common approach to modularity in both React and vanilla web code.\n \n
\n In that chapter on Modularity there was one particular topic that caught my eye,\n and it was the use of lazy() and Suspense, paired with an ErrorBoundary.\n These are the primitives that React gives us to asynchronously load UI components and their data on-demand while showing a fallback UI,\n and replace the UI with an error message when something goes wrong.\n If you're not familiar, here's a good overview page.\n
\n
\n It was at that time that I was visited by the imp of the perverse, which posed to me a simple challenge:\n can you bring React's lazy loading primitives to vanilla web components?\n To be clear, there are many \n ways to \n load web components \n lazily. \n This is well-trodden territory. What wasn't out there was a straight port of lazy, suspense and error boundary. \n The idea would not let me go. So here goes nothing.\n
\n\n
Lazy
\n\n
\n The idea and execution of React's lazy is simple. Whenever you want to use a component in your code,\n but you don't want to actually fetch its code yet until it needs to be rendered, wrap it using the lazy() function: \n const MarkdownPreview = lazy(() => import('./MarkdownPreview.js')); \n
\n
\n React will automatically \"suspend\" rendering when it first bumps into this lazy component until the component has loaded, and then continue automatically.\n
\n
\n This works in React because the markup of a component only looks like HTML, \n but is actually JavaScript in disguise, better known as JSX.\n With web components however, the markup that the component is used in is actually HTML,\n where there is no import() and no calling of functions.\n That means our vanilla lazy cannot be a JavaScript function, but instead it must be an HTML custom element: \n <x-lazy><x-hello-world></x-hello-world></x-lazy>\n
\n\n
\n The basic setup is simple, when the lazy component is added to the DOM,\n we'll scan for children that have a '-' in the name and therefore are custom elements,\n see if they're not yet defined, and load and define them if so.\n By using display: contents we can avoid having the <x-lazy> impact layout.\n
\n To actually load the element, we'll have to first find the JS file to import, and then run its register function.\n 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.\n The following code uses a heuristic that assumes components are in a ./components/ subfolder of the current document\n and follow a consistent file naming scheme:\n
\n
lazy.js (continued):
#loadElement(element) {\n // strip leading x- off the name\n const cleanName = element.localName.replace(/^x-/, '').toLowerCase();\n // assume component is in its own folder\n const url = `./components/${cleanName}/${cleanName}.js`;\n // dynamically import, then register if not yet registered\n return import(new URL(url, document.location)).then(module => \n !customElements.get(element.localName) && module && module.default());\n }
\n\n
\n One could get a lot more creative however, and for example use an \n import map \n to map module names to files. This I leave as an exercise for the reader.\n
\n\n
Suspense
\n\n
\n While the lazy component is loading, we can't show it yet. This is true for custom elements just as much as for React.\n That means we need a wrapper component that will show a fallback UI as long as any components in its subtree are loading,\n the <x-suspense> component. This starts out as a tale of two slots. When the suspense element is loading it shows the fallback, otherwise the content.\n
\n The trick now is, how to we get loading = true to happen?\n In Plain Vanilla's applications page I showed how a React context can be simulated using the element.closest() API.\n We can use the same mechanism to create a generic API that will let our suspense wait on a promise to complete.\n
\n\n
suspense.js (continued):
static waitFor(sender, ...promises) {\n const suspense = sender.closest('x-suspense');\n if (suspense) suspense.addPromises(...promises);\n }\n\n addPromises(...promises) {\n if (!promises.length) return;\n this.loading = true;\n // combine into previous promises if there are any\n const newPromise = this.#waitingForPromise = \n Promise.allSettled([...promises, this.#waitingForPromise]);\n // wait for all promises to complete\n newPromise.then(_ => {\n // if no newer promises were added, we're done\n if (newPromise === this.#waitingForPromise) {\n this.loading = false;\n }\n });\n }
\n\n
\n Suspense.waitFor will call the nearest ancestor <x-suspense>\n to a given element, and give it a set of promises that it should wait on.\n This API can then be called from our <x-lazy> component.\n Note that #loadElement returns a promise that completes when the custom element is loaded or fails to load.\n
\n The nice thing about the promise-based approach is that we can give it any promise, just like we would with React's suspense.\n For example, when loading data in a custom element that is in the suspense's subtree, we can call the exact same API: \n Suspense.waitFor(this, fetch(url).then(...))\n
\n\n
Error boundary
\n\n
\n Up to this point, we've been assuming everything always works. This is Spartasoftware, it will never \"always work\".\n What we need is a graceful way to intercept failed promises that are monitored by the suspense,\n and show an error message instead. That is the role that React's error boundary plays.\n
\n
\n The approach is similar to suspense:\n
\n
example.html:
<x-error-boundary>\n <p slot=\"error\">Something went wrong</p>\n <x-suspense>\n <p slot=\"fallback\">Loading...</p>\n <x-lazy><x-hello-world></x-hello-world></x-lazy>\n </x-suspense>\n</x-error-boundary>
\n
\n And the code is also quite similar to suspense:\n
\n
export class ErrorBoundary extends HTMLElement {\n\n static showError(sender, error) {\n if (!error) throw new Error('ErrorBoundary.showError: expected two arguments but got one');\n const boundary = sender.closest('x-error-boundary');\n if (boundary) {\n boundary.error = error;\n } else {\n console.error('unable to find x-error-boundary to show error');\n console.error(error);\n }\n }\n\n #error;\n #errorSlot;\n #contentSlot;\n\n get error() {\n return this.#error;\n }\n\n set error(error) {\n if (!this.#errorSlot) return;\n this.#error = error;\n this.#errorSlot.style.display = error ? 'contents' : 'none';\n this.#contentSlot.style.display = !error ? 'contents' : 'none';\n if (error) {\n this.#errorSlot.assignedElements().forEach(element => {\n if (Object.hasOwn(element, 'error')) {\n element.error = error;\n } else {\n element.setAttribute('error', error?.message || error);\n }\n });\n this.dispatchEvent(new CustomEvent('error', { detail: error }));\n }\n }\n\n constructor() {\n super();\n this.attachShadow({ mode: 'open' });\n\n this.#errorSlot = document.createElement('slot');\n this.#errorSlot.style.display = 'none';\n this.#errorSlot.name = 'error';\n // default error message\n this.#errorSlot.textContent = 'Something went wrong.';\n this.#contentSlot = document.createElement('slot');\n this.shadowRoot.append(this.#errorSlot, this.#contentSlot);\n }\n\n reset() {\n this.error = null;\n }\n\n connectedCallback() {\n this.style.display = 'contents';\n }\n}\ncustomElements.define('x-error-boundary', ErrorBoundary);\n
\n\n
\n Similar to suspense, this has an API ErrorBoundary.showError() that can be called\n from anywhere inside the error boundary's subtree to show an error that occurs.\n The suspense component is then modified to call this API when it bumps into a rejected promise.\n To hide the error, the reset() method can be called on the error boundary element.\n
\n
\n Finally, the error setter will set the error as a property or attribute\n on all children in the error slot, which enables customizing the error message's behavior based on the error object's properties\n by creating a custom <x-error-message> component.\n
\n\n
Conclusion
\n\n
\n Finally, we can bring all of this together in a single example,\n that combines lazy, suspense, error boundary, a customized error message, and a lazy-loaded hello-world component.\n
\n For the complete example's code, as well as the lazy, suspense and error-boundary components,\n check out the sweet-suspense repo on Github.\n
\n ]]>\n \n \n <![CDATA[How fast are web components?]]>\n \n https://plainvanillaweb.com/blog/articles/2024-09-06-how-fast-are-web-components/\n 2024-09-06T12:00:00.000Z\n 2024-09-15T12:00:00.000Z\n \n \n \n \n
Author's note
\n
\n This article initially had somewhat different results and conclusions,\n but deficiencies in the original benchmark were pointed out and addressed.\n Where the conclusions were changed from the original article, this is pointed out in the text.\n
\n \n\n
\n It is often said that web components are slow.\n This was also my experience when I first tried building web components a few years ago.\n At the time I was using the Stencil framework, because I didn't feel confident that they could be built well without a framework.\n Performance when putting hundreds of them on a page was so bad that I ended up going back to React.\n
\n
\n But as I've gotten deeper into vanilla web development I started to realize that maybe I was just using it wrong.\n Perhaps web components can be fast, if built in a light-weight way.\n This article is an attempt to settle the question \"How fast are web components?\".\n
\n\n
The lay of the land
\n\n
\n What kinds of questions did I want answered?\n
\n
\n
How many web components can you render on the page in a millisecond?
\n
Does the technique used to built the web component matter, which technique is fastest?
\n
How do web component frameworks compare? I used Lit as the framework of choice as it is well-respected.
\n
How does React compare?
\n
What happens when you combine React with web components?
\n
\n\n
\n To figure out the answer I made a benchmark as a vanilla web page (of course),\n that renders thousands of very simple components containing only <span>.</span>\n and measured the elapsed time. This benchmark was then run on multiple devices and multiple browsers\n to figure out performance characteristics. The ultimate goal of this test is to figure out the absolute best performance\n that can be extracted from the most minimal web component.\n
\n\n
To get a performance range I used two devices for testing:
\n
\n
A Macbook Air M1 running MacOS, to stand in as the \"fast\" device, comparable to a new high end iPhone.
\n
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.
\n
\n
Between these devices is a 7x CPU performance gap.
\n\n
The test
\n\n
\n The test is simple: render thousands of components using a specific technique, \n call requestAnimationFrame() repeatedly until they actually render,\n then measure elapsed time. This produces a components per millisecond number.\n
\n
The techniques being compared:
\n
\n
innerHTML: each web component renders its content by assigning to this.innerHTML
\n
append: each web component creates the span using document.createElement and then appends it to itself
\n
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
\n
shadow + innerHTML: the same as innerHTML, except each component has a shadow DOM
\n
shadow + append: the same as append, except each component has a shadow DOM
\n
template + append: each web component renders its content by cloning a template and appending it
\n
textcontent: each web component directly sets its textContent property, instead of adding a span (making the component itself be the span)\n
direct: appends spans instead of custom elements, to be able to measure custom element overhead
\n
lit: each web component is rendered using the lit framework, in the way that its documentation recommends
\n
react pure: rendering in React as a standard React component, to have a baseline for comparison to mainstream web development
\n
react + wc: each React component wraps the append-style web component
\n
(norender): same as other strategies, except the component is only created but not added to the DOM, to separate out component construction cost
\n
\n
\n This test was run on M1 in Brave, Chrome, Edge, Firefox and Safari. And on Chi in Chrome and Firefox.\n It was run for 10 iterations and a geometric mean was taken of the results.\n
\n\n
The results
\n\n
First, let's compare techniques. The number here is components per millisecond, so higher is better.
\n \n
Author's note: the numbers from the previous version of this article are crossed out.
\n
\n \n
Chrome on M1
\n
technique
components/ms
\n \n \n
innerHTML
143 135
\n
append
233 239
\n
append (buffered)
228 239
\n
shadow + innerHTML
132 127
\n
shadow + append
183 203
\n
template + append
181 198
\n
textcontent
345
\n
direct
461
\n
lit
133 137
\n
react pure
275 338
\n
react + wc
172 212
\n
append (norender)
1393
\n
shadow (norender)
814
\n
direct (norender)
4277
\n
lit (norender)
880
\n \n
\n\n
\n \n
Chrome on Chi, best of three
\n
technique
components/ms
\n \n \n
innerHTML
25 29
\n
append
55 55
\n
append (buffered)
56 59
\n
shadow + innerHTML
24 26
\n
shadow + append
36 47
\n
template + append
45 46
\n
textcontent
81
\n
direct
116
\n
lit
30 33
\n
react pure
77 87
\n
react + wc
45 52
\n
append (norender)
434
\n
shadow (norender)
231
\n
direct (norender)
1290
\n
lit (norender)
239
\n \n
\n\n
\n One relief right off the bat is that even the slowest implementation on the slow device renders 100.000 components in 4 seconds.\n React is roughly in the same performance class as well-written web components.\n That means for a typical web app performance is not a reason to avoid web components.\n
\n \n\n
\n As far as web component technique goes, the performance delta between the fastest and the slowest technique is around 2x,\n so again for a typical web app that difference will not matter. Things that slow down web components\n are shadow DOM and innerHTML. Appending directly created elements or cloned templates and avoiding shadow DOM is the right strategy\n for a well-performing web component that needs to end up on the page thousands of times.\n
\n\n
\n On the slow device the Lit framework is a weak performer, probably due to its use of shadow DOM and JS-heavy approaches.\n 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,\n it benefits from not having to initialize the web component class instances.\n Consequently, when wrapping web components inside React components we see React's performance advantage disappear, and that it adds a performance tax.\n In the grand scheme of things however, the differences between React and optimized web components remains small.\n
\n\n
\n The fast device is up to 5x faster than the slow device in Chrome, depending on the technique used,\n so it is really worth testing applications on slow devices to get an idea of the range of performance.\n
\n\n
\n Next, let's compare browsers:\n
\n\n
\n \n
M1, append, best of three
\n
browser
components/ms
\n \n \n
Brave
146 145
\n
Chrome
233 239
\n
Edge
224 237
\n
Firefox
232 299
\n
Safari
260 239
\n \n
\n\n
\n \n
Chi, append, best of three
\n
browser
components/ms
\n \n \n
Chrome
55 55
\n
Firefox
180 77
\n \n
\n\n
\n Brave is really slow, probably because of its built-in ad blocking. Ad blocking extensions also slow down the other browsers by a lot.\n Safari, Chrome and Edge end up in roughly the same performance bucket. Firefox is the best performer overall.\n Using the \"wrong\" browser can halve the performance of a machine.\n
\n
\n Author's note:\n 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.\n
\n
\n There is a large performance gap when you compare the slowest technique on the slowest browser on the slowest device,\n with its fastest opposite combo. Specifically, there is a 16x performance gap:\n
\n
\n
textContent, Firefox on M1: 430 components/ms
\n
Shadow DOM + innerHTML, Chrome on Chi: 26 components/ms
\n
\n
\n That means it becomes worthwhile to carefully consider technique when having to support a wide range of browsers and devices,\n because a bad combination may lead to a meaningfully degraded user experience.\n And of course, you should always test your web app on a slow device to make sure it still works ok.\n
\n \n
Bottom line
\n\n
\n I feel confident now that web components can be fast enough for almost all use cases where someone might consider React instead.\n
\n
\n However, it does matter how they are built. Shadow DOM should not be used for smaller often used web components,\n and the contents of those smaller components should be built using append operations instead of innerHTML.\n The use of web component frameworks might impact their performance significantly,\n and given how easy it is to write vanilla web components I personally don't see the point behind Lit or Stencil. YMMV.\n
\n\n
\n The full benchmark code and results can be found on Github.\n
\n\n ]]>\n \n \n <![CDATA[A unix philosophy for web development]]>\n \n https://plainvanillaweb.com/blog/articles/2024-09-03-unix-philosophy/\n 2024-09-03T12:00:00.000Z\n 2024-09-03T12:00:00.000Z\n \n \n \n \n Web components have their malcontents. While frameworks have done their best to provide\n a place for web components to fit into their architecture, the suit never fits quite right,\n and framework authors have not been shy about expressing their disappointment.\n Here's Ryan Carniato of SolidJS explaining what's wrong with web components:\n \n
\n The collection of standards (Custom Elements, HTML Templates, Shadow DOM, and formerly HTML Imports) \n put together to form Web Components on the surface seem like they could be used to replace \n your favourite library or framework. But they are not an advanced templating solution. \n They don't improve your ability to render or update the DOM. \n They don't manage higher-level concerns for you like state management.\n
\n While this criticism is true, perhaps it's besides the point.\n Maybe web components were never meant to solve those problems anyway.\n Maybe there are ways to solve those problems in a way that dovetails with web components as they exist.\n In the main components tutorial I've already explained what they can do,\n now let's see what can be done about the things that they can't do.\n
\n\n
The Unix Philosophy
\n\n
\n The Unix operating system carries with it a culture and philosophy of system design,\n which carries over to the command lines of today's Unix-like systems like Linux and MacOS. \n This philosophy can be summarized as follows:\n
\n
\n
Write programs that do one thing and do it well.
\n
Write programs to work together.
\n
Write programs to handle text streams, because that is a universal interface.
\n
\n
\n What if we look at the various technologies that comprise web components as just programs, \n part of a Unix-like system of web development that we collectively call the browser platform?\n In that system we can do better than text and use the DOM as the universal interface between programs, \n and we can extend the system with a set of single purpose independent \"programs\" (functions) \n that fully embrace the DOM by augmenting it instead of replacing it.\n
\n
\n In a sense this is the most old-school way of building web projects, the one people who \"don't know any better\"\n automatically gravitate to. What us old-school web developers did before Vue and Solid and Svelte, before Angular and React,\n before Knockout and Ember and Backbone, before even jQuery, was have a bunch of functions in utilities.js\n that we copied along from project to project.\n But, you know, sometimes old things can become new again.\n
\n
\n In previous posts I've already covered a html() function for vanilla entity encoding,\n and a signal() function that provides a tiny signals implementation \n that can serve as a lightweight system for state management.\n That still leaves a missing link between the state managed by the signals and the DOM that is rendered from safely entity-encoded HTML.\n What we need is a bind() function that can bind data to DOM elements and bind DOM events back to data.\n
\n\n
Finding inspiration
\n\n
\n In order to bind a template to data, we need a way of describing that behavior in the HTML markup.\n Well-trodden paths are often the best starting place to look for inspiration. I like Vue's template syntax,\n because it is valid HTML but just augmented, and because it is proven. Vue's templates only pretend to be HTML\n because they're actually compiled to JavaScript behind the scenes, but let's start there as an API.\n This is what it looks like:\n
\n
\n
<img :src=\"imageSrc\" />
\n
Bind src to track the value of the imageSrc property of the current component.\n Vue is smart enough to set a property if one exists, and falls back to setting an attribute otherwise.\n (If that confuses you, read about attributes and properties first.)
\n
<button @click=\"doThis\"></button>
\n
Bind the click event to the doThis method of the current component.
\n
\n
\n By chance I came across this article about making a web component base class.\n In the section Declarative interactivity the author shows a way to do the Vue-like event binding syntax\n on a vanilla web component. This is what inspired me to develop the concept into a generic binding function and write this article.\n
\n\n
Just an iterator
\n\n
\n The heart of the binding function is an HTML fragment iterator. \n After all, before we can bind attributes we need to first find the ones that have binding directives.\n
\n
export const bind = (template) => {\n const fragment = template.content.cloneNode(true);\n // iterate over all nodes in the fragment\n const iterator = document.createNodeIterator(\n fragment,\n NodeFilter.SHOW_ELEMENT,\n {\n // reject any node that is not an HTML element\n acceptNode: (node) => {\n if (!(node instanceof HTMLElement))\n return NodeFilter.FILTER_REJECT;\n return NodeFilter.FILTER_ACCEPT;\n },\n }\n );\n let node;\n while (node = iterator.nextNode()) {\n if (!node) return;\n const elem = node;\n for (const attr of Array(...node.attributes)) {\n // check for event binding directive\n if (attr.name.startsWith('@')) {\n\n // TODO: bind event ...\n \n elem.removeAttributeNode(attr);\n // check for property/attribute binding directive\n } else if (attr.name.startsWith(':')) {\n \n // TODO: bind data ...\n \n elem.removeAttributeNode(attr);\n }\n }\n }\n return fragment;\n}
\n
\n This code will take an HTML template element, \n clone it to a document fragment, \n and then iterate over all the nodes in the fragment, discovering their attributes. \n Then for each attribute a check is made to see if it's a binding directive (@ or :). \n The node is then bound to data according to the directive attribute (shown here as TODO's), \n and the attribute is removed from the node. At the end the bound fragment is returned for inserting into the DOM.\n
\n
\n The benefit of using a fragment is that it is disconnected from the main DOM, while still offering all of the DOM API's. \n That means we can easily create a node iterator to walk over it and discover all the attributes \n with binding directives, modify those nodes and attributes in-place, and still be sure we're not causing \n DOM updates in the main page until the fragment is inserted there. This makes the bind function very fast.\n
\n
\n If you're thinking \"woah dude, that's a lot of code and a lot of technobabble, I ain't reading all that,\"\n then please, I implore you to read through the code line by line, and you'll see it will all make sense.\n
\n
\n Of course, we also need to have something to bind to, so we need to add a second parameter.\n 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.\n The beginning of our bind function then ends up looking like this:\n
\n
export const bind = (template, target) => {\n if (!template.content) {\n const text = template;\n template = document.createElement('template');\n template.innerHTML = text;\n }\n const fragment = template.content.cloneNode(true);\n// ...\n}
\n
That just leaves us the TODO's. We can make those as simple or complicated as we want. I'll pick a middle ground.
\n\n
Binding to events
\n\n
This 20 line handler binds events to methods, signals or properties:
\n
// check for custom event listener attributes\nif (attr.name.startsWith('@')) {\n const event = attr.name.slice(1);\n const property = attr.value;\n let listener;\n // if we're binding the event to a function, call it directly\n if (typeof target[property] === 'function') {\n listener = target[property].bind(target);\n // if we're binding to a signal, set the signal's value\n } else if (typeof target[property] === 'object' && \n typeof target[property].value !== 'undefined') {\n listener = e => target[property].value = e.target.value;\n // fallback: assume we're binding to a property, set the property's value\n } else {\n listener = e => target[property] = e.target.value;\n }\n elem.addEventListener(event, listener);\n // remove (non-standard) attribute from element\n elem.removeAttributeNode(attr);\n}
\n\n
That probably doesn't explain much, so let me give an example of what this enables:
input#a's input event is handled by calling the onClickA() method.
\n
input#b's input event is handled by assigning e.target.value to the b property.
\n
input#c's input event is handled by setting the value of the c signal.
\n
\n
\n If you're not familiar with the signal() function, check out the tiny signals \n implementation in the previous post. For now you can also just roll with it.\n
\n
Not a bad result for 20 lines of code.
\n\n
Binding to data
\n
\n Having established the pattern for events that automatically update properties, \n we now reverse the polarity to make data values automatically set element properties or attributes.\n
\n
// ...\n if (attr.name.startsWith(':')) {\n // extract the name and value of the attribute/property\n let name = attr.name.slice(1);\n const property = getPropertyForAttribute(name, target);\n const setter = property ?\n () => elem[property] = target[attr.value] :\n () => elem.setAttribute(name, target[attr.value]);\n setter();\n // if we're binding to a signal, listen to updates\n if (target[attr.value]?.effect) {\n target[attr.value].effect(setter);\n // if we're binding to a property, listen to the target's updates\n } else if (target.addEventListener) {\n target.addEventListener('change', setter);\n }\n // remove (non-standard) attribute from element\n elem.removeAttributeNode(attr);\n }\n// ...\n\nfunction getPropertyForAttribute(name, obj) {\n switch (name.toLowerCase()) {\n case 'text': case 'textcontent':\n return 'textContent';\n case 'html': case 'innerhtml':\n return 'innerHTML';\n default:\n for (let prop of Object.getOwnPropertyNames(obj)) {\n if (prop.toLowerCase() === name.toLowerCase()) {\n return prop;\n }\n } \n }\n}
\n
\n The getPropertyForAttribute function is necessary because the attributes that contain the directives\n will have names that are case-insensitive, and these must be mapped to property names that are case-sensitive.\n Also, the :text and :html shorthand notations replace the role of v-text\n and v-html in Vue's template syntax.\n
\n
\n When the value of the target's observed property changes, we need to update the bound element's property or attribute.\n This means a triggering 'change' event is needed that is then subscribed to.\n A framework's templating system will compare state across time, and detect the changed values automatically. \n Lacking such a system we need a light-weight alternative.\n
\n
\n When the property being bound to is a signal, this code registers an effect on the signal.\n When the property is just a value, it registers an event listener on the target object,\n making it the responsibility of that target object to dispatch the 'change' event when values change.\n This approach isn't going to get many points for style, but it does work.\n
\n In the article Why I don't use web components \n Svelte's Rich Harris lays out the case against web components. He demonstrates how this simple 9 line Svelte component\n <Adder a={1} b={2}/> becomes an incredible verbose 59 line monstrosity when ported to a vanilla web component.\n
\n
<script>\n export let a;\n export let b;\n</script>\n\n<input type=\"number\" bind:value={a}>\n<input type=\"number\" bind:value={b}>\n\n<p>{a} + {b} = {a + b}</p>
\n\n
\n Now that we have assembled our three helper functions html(), signal() and bind()\n 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 <x-adder a=\"1\" b=\"2\"></x-adder>?\n
\n
import { bind } from './bind.js';\nimport { signal, computed } from './signals.js';\nimport { html } from './html.js';\n\ncustomElements.define('x-adder', class Adder extends HTMLElement {\n a = signal();\n b = signal();\n result = computed(() => \n html`${+this.a} + ${+this.b} = ${+this.a + +this.b}`, [this.a, this.b]);\n\n connectedCallback() {\n this.a.value ??= this.getAttribute('a') || 0;\n this.b.value ??= this.getAttribute('b') || 0;\n this.append(bind(html`\n <input type=\"number\" :value=\"a\" @input=\"a\" />\n <input type=\"number\" :value=\"b\" @input=\"b\" />\n <p :html=\"result\"></p>\n `, this));\n }\n});\n
\n 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. \n And I'm just shooting in the wind here, trying stuff out.\n Somewhere out there could be a minimal set of functions that transforms web components into something resembling a framework,\n and the idea excites me! Who knows, maybe in a few years the web community will return to writing projects in \n vanilla web code, dragging along the modern equivalent of utilities.js from project to project...\n
\n \n
What do you think?
\n ]]>\n \n \n <![CDATA[Poor man's signals]]>\n \n https://plainvanillaweb.com/blog/articles/2024-08-30-poor-mans-signals/\n 2024-08-30T12:00:00.000Z\n 2024-08-30T12:00:00.000Z\n \n \n \n \n Signals are all the rage right now. Everyone's doing them.\n Angular,\n and Solid,\n and Preact,\n and there are third party packages for just about every framework that doesn't already have them.\n There's even a proposal\n to add them to the language, and if that passes it's just a \n matter of time before all frameworks \n have them built in.\n \n\n
Living under a rock
\n
\n In case you've been living under a rock, here's the example from Preact's documentation \n that neatly summarizes what signals do:\n
\n
import { signal, computed, effect } from \"@preact/signals\";\n\nconst name = signal(\"Jane\");\nconst surname = signal(\"Doe\");\nconst fullName = computed(() => `${name.value} ${surname.value}`);\n\n// Logs name every time it changes:\neffect(() => console.log(fullName.value));\n// Logs: \"Jane Doe\"\n\n// Updating `name` updates `fullName`, which triggers the effect again:\nname.value = \"John\";\n// Logs: \"John Doe\"\n
\n
\n Simply put, signals wrap values and computations \n in a way that allows us to easily respond to every change to those values and results in a targeted way,\n without having to rerender the entire application in the way that we would do in React.\n In short, signals are an efficient and targeted way to respond to changes without having to do state comparison and DOM-diffing.\n
\n
\n OK, so, if signals are so great, why am I trying to sell you on them on a vanilla web development blog?\n Don't worry! Vanilla web developers can have signals too.\n
\n\n
Just a wrapper
\n
\n Signals are at heart nothing more than a wrapper for a value that sends events when the value changes.\n That's nothing that a little trickery with the not well known but very handy EventTarget base class can't fix for us.\n
\n
class Signal extends EventTarget {\n #value;\n get value () { return this.#value; }\n set value (value) {\n if (this.#value === value) return;\n this.#value = value;\n this.dispatchEvent(new CustomEvent('change')); \n }\n\n constructor (value) {\n super();\n this.#value = value;\n }\n}
\n
\n This gets us a very barebones signals experience:\n
\n
const name = new Signal('Jane');\nname.addEventListener('change', () => console.log(name.value));\nname.value = 'John';\n// Logs: John
\n
\n But that's kind of ugly. The new keyword went out of fashion a decade ago,\n and that addEventListener sure is unwieldy.\n So let's add a little syntactic sugar.\n
\n
class Signal extends EventTarget {\n #value;\n get value () { return this.#value; }\n set value (value) {\n if (this.#value === value) return;\n this.#value = value;\n this.dispatchEvent(new CustomEvent('change')); \n }\n\n constructor (value) {\n super();\n this.#value = value;\n }\n\n effect(fn) {\n fn();\n this.addEventListener('change', fn);\n return () => this.removeEventListener('change', fn);\n }\n\n valueOf () { return this.#value; }\n toString () { return String(this.#value); }\n}\n\nconst signal = _ => new Signal(_);\n
\n
\n Now our barebones example is a lot nicer to use:\n
\n
const name = signal('Jane');\nname.effect(() => console.log(name.value));\n// Logs: Jane\nname.value = 'John';\n// Logs: John
\n
\n The effect(fn) method will call the specified function,\n and also subscribe it to changes in the signal's value.\n
\n
\n It also returns a dispose function that can be used to unregister the effect.\n However, a nice side effect of using EventTarget and browser built-in events as the reactivity primitive\n is that it makes the browser smart enough to garbage collect the signal and its effect when the signal goes out of scope.\n This means less chance for memory leaks even if we never call the dispose function.\n
\n
\n Finally, the toString and valueOf magic methods allow for dropping .value in most places\n that the signal's value gets used. (But not in this example, because the console is far too clever for that.)\n
\n\n
Does not compute
\n
\n This signals implementation is already capable, but at some point it might be handy to have an effect based on more than one signal.\n That means supporting computed values. Where the base signals are a wrapper around a value,\n computed signals are a wrapper around a function.\n
\n
class Computed extends Signal {\n constructor (fn, deps) {\n super(fn(...deps));\n for (const dep of deps) {\n if (dep instanceof Signal) \n dep.addEventListener('change', () => this.value = fn(...deps));\n }\n }\n}\n\nconst computed = (fn, deps) => new Computed(fn, deps);\n
\n
\n The computed signal calculates its value from a function.\n It also depends on other signals, and when they change it will recompute its value.\n It's a bit obnoxious to have to pass the signals that it depends on\n as an additional parameter, but hey, I didn't title this article Rich man's signals.\n
\n
\n This enables porting Preact's signals example to vanilla JS.\n
\n
const name = signal('Jane');\nconst surname = signal('Doe');\nconst fullName = computed(() => `${name} ${surname}`, [name, surname]);\n// Logs name every time it changes:\nfullName.effect(() => console.log(fullName.value));\n// -> Jane Doe\n\n// Updating `name` updates `fullName`, which triggers the effect again:\nname.value = 'John';\n// -> John Doe\n
\n\n
Can you use it in a sentence?
\n
\n You may be thinking, all these console.log examples are fine and dandy,\n but how do you use this stuff in actual web development?\n This simple adder demonstrates how signals can be combined with web components:\n
\n
import { signal, computed } from './signals.js';\n\ncustomElements.define('x-adder', class extends HTMLElement {\n a = signal(1);\n b = signal(2);\n result = computed((a, b) => `${a} + ${b} = ${+a + +b}`, [this.a, this.b]);\n\n connectedCallback() {\n if (this.querySelector('input')) return;\n\n this.innerHTML = `\n <input type=\"number\" name=\"a\" value=\"${this.a}\">\n <input type=\"number\" name=\"b\" value=\"${this.b}\">\n <p></p>\n `;\n this.result.effect(\n () => this.querySelector('p').textContent = this.result);\n this.addEventListener('input', \n e => this[e.target.name].value = e.target.value);\n }\n});\n
\n In case you were wondering, the if is there to prevent adding the effect twice\n if connectedCallback is called when the component is already rendered.\n
\n
\n The full poor man's signals code in all its 36 line glory can be found in the tiny-signals repo on Github.\n
\n When I made the first version of the Plain Vanilla website, there were things that I would have liked\n to spend more time on, but that I felt didn't belong in a Good Enough™ version of the site.\n One of those things was defending against Cross-Site Scripting (XSS).\n
\n
\n XSS is still in the OWASP Top Ten of security issues, \n but it's no longer as prevalent as it used to be. Frameworks have built in a lot of defenses, \n and when using their templating systems you have to go out of your way to inject code into the generated HTML.\n When eschewing frameworks we're reduced to standard templating in our web components, and those offer no defense against XSS.\n
\n
\n Because of this, in the original site the Passing Data example \n on the Components page had an undocumented XSS bug.\n The name field could have scripts injected into it. I felt ambivalent about leaving that bug in.\n On the one hand, the code was very compact and neat by leaving it in.\n On the other hand it made that code a bad example that shouldn't be copied.\n I ended up choosing to leave it as-is because an example doesn't have to be production-grade\n and generating properly encoded HTML was not the point of that specific example.\n 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,\n if Santa really did want to bring his List application to production-level quality.\n
\n\n
The problem
\n
\n The basic problem we need to solve is that vanilla web components end up having a lot of code that looks like this:\n
\n If any of foo, bar, baz or xyzzy contain one of the dangerous HTML entities,\n we risk seeing our component break, and worst-case risk seeing an attacker inject a malicious payload into the page.\n Just as a reminder, those dangerous HTML entities are <, >, &, ' and \".\n
\n\n
The fix, take one
\n
\n A naive fix is creating a html-encoding function and using it consistently:\n
\n While this does work to defend against XSS, it is verbose and ugly, not pleasant to type and not pleasant to read.\n What really kills it though, is that it assumes attention to detail from us messy humans. We can never forget,\n never ever, to put a htmlEncode() around each and every variable.\n In the real world, that is somewhat unlikely.\n
\n
\n What is needed is a solution that allows us to forget about entity encoding, by doing it automatically\n when we're templating. I drew inspiration from templating libraries that work in-browser and are based on tagged templates, \n like lit-html \n and htm. The quest was on to build the most minimalistic\n html templating function that encoded entities automatically.\n
\n\n
The fix, take two
\n
\n Ideally, the fixed example should look more like this:\n
\n The html``tagged template function \n would automatically encode entities, in a way that we don't even have to think about it.\n Even when we nest generated HTML inside of another template, like with ${btn}, it should just magically work.\n It would be so minimal as to disappear in the background, barely impacting readability, maybe even improving it.\n You may be thinking that doing that correctly would involve an impressive amount of code. I must disappoint.\n
\n
class Html extends String { }\n\n/** \n * tag a string as html not to be encoded\n * @param {string} str\n * @returns {string}\n */\nexport const htmlRaw = str => new Html(str);\n\n/** \n * entity encode a string as html\n * @param {*} value The value to encode\n * @returns {string}\n */\nexport const htmlEncode = (value) => {\n // avoid double-encoding the same string\n if (value instanceof Html) {\n return value;\n } else {\n // https://stackoverflow.com/a/57448862/20980\n return htmlRaw(\n String(value).replace(/[&<>'\"]/g, \n tag => ({\n '&': '&',\n '<': '<',\n '>': '>',\n \"'\": ''',\n '\"': '"'\n }[tag]))\n );\n }\n}\n\n/** \n * html tagged template literal, auto-encodes entities\n */\nexport const html = (strings, ...values) => \n htmlRaw(String.raw({ raw: strings }, ...values.map(htmlEncode)));\n
\n
\n Those couple dozen lines of code are all that is needed. Let's go through it from top to bottom.\n
\n
\n
class Html extends String { }
\n
The Html class is used to mark strings as encoded, so that they won't be encoded again.
\n
export const htmlRaw = str => new Html(str);
\n
Case in point, the htmlRaw function does the marking.
\n
export const htmlEncode = ...
\n
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.
\n
export const html = ...
\n
The tagged template function that binds it together.
\n
\n\n
\n A nice upside of the html template function is that the html-in-template-string Visual Studio Code extension\n can detect it automatically and will syntax highlight the templated HTML. This is what example 3 looked like after I made it:\n
\n\n \n\n
\n Granted, there's still a bunch of boilerplate here, and that getAttribute gets unwieldy.\n 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.\n It's surprising how nice of a development experience web standards can be if you embrace them.\n
\n\n
\n I decided to leave the XSS bug in the Passing Data example, but now the Applications page\n has an explanation about entity encoding documenting this html template function.\n I can only hope people that work their way through the tutorial make it that far.\n For your convenience I also put the HTML templating function in its own separate \n html-literal repo on Github.\n
\n \n \n\n \n\n \n\n\n"
},
{
"path": "public/index.js",
"content": "import { registerCodeViewerComponent } from \"./components/code-viewer/code-viewer.js\";\nimport { registerTabPanelComponent } from \"./components/tab-panel/tab-panel.js\";\n\nconst app = async () => {\n registerCodeViewerComponent();\n registerTabPanelComponent();\n const { registerAnalyticsComponent } = await import(\"./components/analytics/analytics.js\");\n registerAnalyticsComponent();\n}\n\ndocument.addEventListener('DOMContentLoaded', app);\n"
},
{
"path": "public/lib/html.js",
"content": "class Html extends String { }\n\n/** \n * tag a string as html not to be encoded\n * @param {string} str\n * @returns {string}\n */\nexport const htmlRaw = str => new Html(str);\n\n/** \n * entity encode a string as html\n * @param {*} value The value to encode\n * @returns {string}\n */\nexport const htmlEncode = (value) => {\n // avoid double-encoding the same string\n if (value instanceof Html) {\n return value;\n } else {\n // https://stackoverflow.com/a/57448862/20980\n return htmlRaw(\n String(value).replace(/[&<>'\"]/g, \n tag => ({\n '&': '&',\n '<': '<',\n '>': '>',\n \"'\": ''',\n '\"': '"'\n }[tag]))\n );\n }\n}\n\n/** \n * html tagged template literal, auto-encodes entities\n */\nexport const html = (strings, ...values) => \n htmlRaw(String.raw({ raw: strings }, ...values.map(htmlEncode)));\n"
},
{
"path": "public/lib/speed-highlight/LICENSE",
"content": "Creative Commons Legal Code\n\nCC0 1.0 Universal\n\n CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE\n LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN\n ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS\n INFORMATION ON AN \"AS-IS\" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES\n REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS\n PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM\n THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED\n HEREUNDER.\n\nStatement of Purpose\n\nThe laws of most jurisdictions throughout the world automatically confer\nexclusive Copyright and Related Rights (defined below) upon the creator\nand subsequent owner(s) (each and all, an \"owner\") of an original work of\nauthorship and/or a database (each, a \"Work\").\n\nCertain owners wish to permanently relinquish those rights to a Work for\nthe purpose of contributing to a commons of creative, cultural and\nscientific works (\"Commons\") that the public can reliably and without fear\nof later claims of infringement build upon, modify, incorporate in other\nworks, reuse and redistribute as freely as possible in any form whatsoever\nand for any purposes, including without limitation commercial purposes.\nThese owners may contribute to the Commons to promote the ideal of a free\nculture and the further production of creative, cultural and scientific\nworks, or to gain reputation or greater distribution for their Work in\npart through the use and efforts of others.\n\nFor these and/or other purposes and motivations, and without any\nexpectation of additional consideration or compensation, the person\nassociating CC0 with a Work (the \"Affirmer\"), to the extent that he or she\nis an owner of Copyright and Related Rights in the Work, voluntarily\nelects to apply CC0 to the Work and publicly distribute the Work under its\nterms, with knowledge of his or her Copyright and Related Rights in the\nWork and the meaning and intended legal effect of CC0 on those rights.\n\n1. Copyright and Related Rights. A Work made available under CC0 may be\nprotected by copyright and related or neighboring rights (\"Copyright and\nRelated Rights\"). Copyright and Related Rights include, but are not\nlimited to, the following:\n\n i. the right to reproduce, adapt, distribute, perform, display,\n communicate, and translate a Work;\n ii. moral rights retained by the original author(s) and/or performer(s);\niii. publicity and privacy rights pertaining to a person's image or\n likeness depicted in a Work;\n iv. rights protecting against unfair competition in regards to a Work,\n subject to the limitations in paragraph 4(a), below;\n v. rights protecting the extraction, dissemination, use and reuse of data\n in a Work;\n vi. database rights (such as those arising under Directive 96/9/EC of the\n European Parliament and of the Council of 11 March 1996 on the legal\n protection of databases, and under any national implementation\n thereof, including any amended or successor version of such\n directive); and\nvii. other similar, equivalent or corresponding rights throughout the\n world based on applicable law or treaty, and any national\n implementations thereof.\n\n2. Waiver. To the greatest extent permitted by, but not in contravention\nof, applicable law, Affirmer hereby overtly, fully, permanently,\nirrevocably and unconditionally waives, abandons, and surrenders all of\nAffirmer's Copyright and Related Rights and associated claims and causes\nof action, whether now known or unknown (including existing as well as\nfuture claims and causes of action), in the Work (i) in all territories\nworldwide, (ii) for the maximum duration provided by applicable law or\ntreaty (including future time extensions), (iii) in any current or future\nmedium and for any number of copies, and (iv) for any purpose whatsoever,\nincluding without limitation commercial, advertising or promotional\npurposes (the \"Waiver\"). Affirmer makes the Waiver for the benefit of each\nmember of the public at large and to the detriment of Affirmer's heirs and\nsuccessors, fully intending that such Waiver shall not be subject to\nrevocation, rescission, cancellation, termination, or any other legal or\nequitable action to disrupt the quiet enjoyment of the Work by the public\nas contemplated by Affirmer's express Statement of Purpose.\n\n3. Public License Fallback. Should any part of the Waiver for any reason\nbe judged legally invalid or ineffective under applicable law, then the\nWaiver shall be preserved to the maximum extent permitted taking into\naccount Affirmer's express Statement of Purpose. In addition, to the\nextent the Waiver is so judged Affirmer hereby grants to each affected\nperson a royalty-free, non transferable, non sublicensable, non exclusive,\nirrevocable and unconditional license to exercise Affirmer's Copyright and\nRelated Rights in the Work (i) in all territories worldwide, (ii) for the\nmaximum duration provided by applicable law or treaty (including future\ntime extensions), (iii) in any current or future medium and for any number\nof copies, and (iv) for any purpose whatsoever, including without\nlimitation commercial, advertising or promotional purposes (the\n\"License\"). The License shall be deemed effective as of the date CC0 was\napplied by Affirmer to the Work. Should any part of the License for any\nreason be judged legally invalid or ineffective under applicable law, such\npartial invalidity or ineffectiveness shall not invalidate the remainder\nof the License, and in such case Affirmer hereby affirms that he or she\nwill not (i) exercise any of his or her remaining Copyright and Related\nRights in the Work or (ii) assert any associated claims and causes of\naction with respect to the Work, in either case contrary to Affirmer's\nexpress Statement of Purpose.\n\n4. Limitations and Disclaimers.\n\n a. No trademark or patent rights held by Affirmer are waived, abandoned,\n surrendered, licensed or otherwise affected by this document.\n b. Affirmer offers the Work as-is and makes no representations or\n warranties of any kind concerning the Work, express, implied,\n statutory or otherwise, including without limitation warranties of\n title, merchantability, fitness for a particular purpose, non\n infringement, or the absence of latent or other defects, accuracy, or\n the present or absence of errors, whether or not discoverable, all to\n the greatest extent permissible under applicable law.\n c. Affirmer disclaims responsibility for clearing rights of other persons\n that may apply to the Work or any use thereof, including without\n limitation any person's Copyright and Related Rights in the Work.\n Further, Affirmer disclaims responsibility for obtaining any necessary\n consents, permissions or other rights required for any use of the\n Work.\n d. Affirmer understands and acknowledges that Creative Commons is not a\n party to this document and has no duty or obligation with respect to\n this CC0 or use of the Work.\n"
},
{
"path": "public/lib/speed-highlight/common.js",
"content": "/**\n * Commonly used match pattern\n*/\n\nexport default {\n\tnum: {\n\t\ttype: 'num',\n\t\tmatch: /(\\.e?|\\b)\\d(e-|[\\d.oxa-fA-F_])*(\\.|\\b)/g\n\t},\n\tstr: {\n\t\ttype: 'str',\n\t\tmatch: /([\"'])(\\\\[^]|(?!\\1)[^\\r\\n\\\\])*\\1?/g\n\t},\n\tstrDouble: {\n\t\ttype: 'str',\n\t\tmatch: /\"((?!\")[^\\r\\n\\\\]|\\\\[^])*\"?/g\n\t}\n}\n"
},
{
"path": "public/lib/speed-highlight/index.js",
"content": "/**\n * @module index\n * (Base script)\n*/\n\n/**\n * Default languages supported\n * @typedef {('asm'|'bash'|'bf'|'c'|'css'|'csv'|'diff'|'docker'|'git'|'go'|'html'|'http'|'ini'|'java'|'js'|'jsdoc'|'json'|'leanpub-md'|'log'|'lua'|'make'|'md'|'pl'|'plain'|'py'|'regex'|'rs'|'sql'|'todo'|'toml'|'ts'|'uri'|'xml'|'yaml')} ShjLanguage\n */\n\n/**\n * Themes supported in the browser\n * @typedef {('atom-dark'|'github-dark'|'github-dim'|'dark'|'default'|'github-light'|'visual-studio-dark')} ShjBrowserTheme\n */\n\n/**\n * @typedef {Object} ShjOptions\n * @property {Boolean} [hideLineNumbers=false] Indicates whether to hide line numbers\n */\n\n/**\n * @typedef {('inline'|'oneline'|'multiline')} ShjDisplayMode\n * * `inline` inside `code` element\n * * `oneline` inside `div` element and containing only one line\n * * `multiline` inside `div` element\n */\n\n/**\n * Token types\n * @typedef {('deleted'|'err'|'var'|'section'|'kwd'|'class'|'cmnt'|'insert'|'type'|'func'|'bool'|'num'|'oper'|'str'|'esc')} ShjToken\n */\n\nimport expandData from './common.js';\n\nconst langs = {},\n\tsanitize = (str = '') =>\n\t\tstr.replaceAll('&', '&').replaceAll?.('<', '<').replaceAll?.('>', '>'),\n\t/**\n\t * Create a HTML element with the right token styling\n\t *\n\t * @function\n\t * @ignore\n\t * @param {string} str The content (need to be sanitized)\n\t * @param {ShjToken} [token] The type of token\n\t * @returns A HMTL string\n\t */\n\ttoSpan = (str, token) => token ? `${str}` : str;\n\n/**\n * Find the tokens in the given code and call the given callback\n *\n * @function tokenize\n * @param {string} src The code\n * @param {ShjLanguage|Array} lang The language of the code\n * @param {function(string, ShjToken=):void} token The callback function\n * this function will be given\n * * the text of the token\n * * the type of the token\n */\nexport async function tokenize(src, lang, token) {\n\ttry {\n\t\tlet m,\n\t\t\tpart,\n\t\t\tfirst = {},\n\t\t\tmatch,\n\t\t\tcache = [],\n\t\t\ti = 0,\n\t\t\tdata = typeof lang === 'string' ? (await (langs[lang] ??= import(`./languages/${lang}.js`))) : lang,\n\t\t\t// make a fast shallow copy to bee able to splice lang without change the original one\n\t\t\tarr = [...typeof lang === 'string' ? data.default : lang.sub];\n\n\t\twhile (i < src.length) {\n\t\t\tfirst.index = null;\n\t\t\tfor (m = arr.length; m-- > 0;) {\n\t\t\t\tpart = arr[m].expand ? expandData[arr[m].expand] : arr[m];\n\t\t\t\t// do not call again exec if the previous result is sufficient\n\t\t\t\tif (cache[m] === undefined || cache[m].match.index < i) {\n\t\t\t\t\tpart.match.lastIndex = i;\n\t\t\t\t\tmatch = part.match.exec(src);\n\t\t\t\t\tif (match === null) {\n\t\t\t\t\t\t// no more match with this regex can be disposed\n\t\t\t\t\t\tarr.splice(m, 1);\n\t\t\t\t\t\tcache.splice(m, 1);\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\t\t\t\t\t// save match for later use to decrease performance cost\n\t\t\t\t\tcache[m] = { match, lastIndex: part.match.lastIndex };\n\t\t\t\t}\n\t\t\t\t// check if it the first match in the string\n\t\t\t\tif (cache[m].match[0] && (cache[m].match.index <= first.index || first.index === null))\n\t\t\t\t\tfirst = {\n\t\t\t\t\t\tpart: part,\n\t\t\t\t\t\tindex: cache[m].match.index,\n\t\t\t\t\t\tmatch: cache[m].match[0],\n\t\t\t\t\t\tend: cache[m].lastIndex\n\t\t\t\t\t}\n\t\t\t}\n\t\t\tif (first.index === null)\n\t\t\t\tbreak;\n\t\t\ttoken(src.slice(i, first.index), data.type);\n\t\t\ti = first.end;\n\t\t\tif (first.part.sub)\n\t\t\t\tawait tokenize(first.match, typeof first.part.sub === 'string' ? first.part.sub : (typeof first.part.sub === 'function' ? first.part.sub(first.match) : first.part), token);\n\t\t\telse\n\t\t\t\ttoken(first.match, first.part.type);\n\t\t}\n\t\ttoken(src.slice(i, src.length), data.type);\n\t}\n\tcatch {\n\t\ttoken(src);\n\t}\n}\n\n/**\n * Highlight a string passed as argument and return it\n * @example\n * elm.innerHTML = await highlightText(code, 'js');\n *\n * @async\n * @function highlightText\n * @param {string} src The code\n * @param {ShjLanguage} lang The language of the code\n * @param {Boolean} [multiline=true] If it is multiline, it will add a wrapper for the line numbering and header\n * @param {ShjOptions} [opt={}] Customization options\n * @returns {Promise} The highlighted string\n */\nexport async function highlightText(src, lang, multiline = true, opt = {}) {\n\tlet tmp = ''\n\tawait tokenize(src, lang, (str, type) => tmp += toSpan(sanitize(str), type))\n\n\treturn multiline\n\t\t? `
\n A real-world application will often have complex markup in the web components, filled with variables based on user input.\n This creates a risk for Cross-Site Scripting.\n In fact, eagle-eyed readers may have noticed in the Passing Data example of the Components page that a XSS bug snuck in.\n By entering the following as a name, the output of list.js would have code injected: <button onclick=\"alert('gotcha')\">oops</button>\n
\n
Go ahead and return to that page to try it ...
\n
\n To solve this we need to encode dangerous HTML entities while plugging variables into HTML markup, something frameworks often do automatically in their templating layer.\n This html`` literal function can be used to do this automatically in a vanilla codebase:\n
\n State is the source of truth of what the application should show.\n It is the data that gets turned into markup on the page by the application's logic.\n
\n
\n In web frameworks state is often carefully managed so that it lives outside of the DOM,\n and then rendered into the DOM using a view layer.\n Every time the state is modified, the view layer rerenders the current view based on the new state, updating the DOM behind the scenes to match the new view.\n In this design the DOM is just a view on the state, but does not actually contain the state.\n
\n
\n In vanilla web development however, state and view are merged together inside of a web component.\n The component carries its state in attributes and properties, making it part of the DOM,\n and it updates its appearance based on changes in that state in a self-contained way.\n In this design the DOM ends up being the owner of the state, not just a view on that state.\n
\n
Take for example a simple counter:
\n \n\n \n \n \n \n \n \n \n \n \n \n \n\n
\n The <x-counter> component carries its state in the #count property,\n it provides an API for safely changing the state with the increment() method, \n and it always updates its appearance when the state is changed using the update() method.\n
\n\n
Lifting state up
\n
\n Putting state inside of web components as attributes and properties at first can seem simple,\n but when scaling this up to more complex hierarchies of components it quickly becomes difficult to manage.\n This means care must be taken to organize state across the component hierarchy in the right way.\n
\n
\n Generally speaking, the state management principles laid out in the React documentation are sound and should be followed even for vanilla web development.\n Here they are once again:\n
\n \n
Group related state. If you always update two or more state variables at the same time, consider merging them into a single state variable.
\n
Avoid contradictions in state. When the state is structured in a way that several pieces of state may contradict and “disagree” with each other, you leave room for mistakes. Try to avoid this.
\n
Avoid redundant state. If you can calculate some information from the component's attributes or properties during rendering, you should not put that information into that component's state.
\n
Avoid duplication in state. When the same data is duplicated between multiple state variables, or within nested objects, it is difficult to keep them in sync. Reduce duplication when you can.
\n
Avoid deeply nested state. Deeply hierarchical state is not very convenient to update. When possible, prefer to structure state in a flat way.
\n \n\n
\n Let's look at these principes in action by porting the React lifting state up tutorial example application to vanilla code:\n
\n\n \n\n
\n The implementation is divided across two web components: <x-accordion> and <x-panel>.\n The state is \"lifted up\" from the panels onto the accordion, so that the accordion carries the state for both panels in a single central place.\n
\n
\n Each of the two panels is stateless. It receives its state through the title and active properties.\n When it is active, it shows its children (inside of a slot). When it is not active, it shows a button labeled \"Show\". It always shows the title.\n
\n\n \n\n
\n By contrast, the accordion is where the state for the panels actually lives:\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n
What to pay attention to:
\n
\n
\n The accordion's activeIndex property carries the state, and everything else is derived from that.\n This property becomes the single source of truth for the application, avoiding redundant state.\n
\n
\n An event listener for the show event sent by a panel will set activeIndex to the right value.\n The property setter for activeIndex explicitly calls the update() method to bring the rest of the DOM in sync with the property's new state.\n
\n
\n
\n Finally, take a look at the original implementation of Accordion and Panel in React's tutorial:\n
\n \n
\n Take note of how the state is organized the same across the React and vanilla implementations.\n The differences are in implementation details for state and rendering, not in how the application is structured.\n
\n\n \n\n
Passing data deeply
\n\n
\n While passing state deep into a hierarchy by handing it from parent components to child components via attributes or properties works,\n it can quickly become verbose and inconvenient. This is especially the case if you have to pass those through many components in the middle\n which have no need for that state aside from passing it to their child components, an anti-pattern colloquially known as \"prop drilling\".\n
\n
\n Again we can take inspiration from how popular frameworks like React organize state, by adapting the concept of a context.\n A context holds state at a high level in the component hierarchy, and it can be accessed directly from anywhere in that hierarchy.\n The whole concept of a context is explained in the React passing data deeply tutorial.\n
\n
\n To understand how to apply this concept in vanilla web development let us look at the ThemeContext example from the useContext documentation page.\n Here is an adapted vanilla version that uses a central context to keep track of light or dark theme, toggled by a button.\n
\n\n \n\n
\n In this example a special web component <x-theme-context> is created, whose only job is to keep track of state, provide setters to update that state, and dispatch events when the state changes.\n
\n The x-theme-context component applies the context protocol, a convention for how web components can implement a context pattern.\n It does this by making use of a minimal implementation of the protocol provided in tiny-context.js.\n
\n
\n The context component also uses display: contents to avoid impacting the layout.\n It exists in the DOM hierarchy, but it becomes effectively invisible.\n
\n
\n Instead of useContext every component obtains the nearest theme context by dispatching a context-request event,\n whose callback will be answered by the nearest provider higher up in the DOM that provides the asked for context.\n By passing true as the subscribe parameter the components can subscribe to updates.\n
\n
\n The theme-toggle function is also provided to the button by the context component. This mechanism can be used for dependency injection across web components.\n
\n
\n\n
\n The needs more context article does a deeper dive into the context protocol and the tiny-context implementation of it.\n
\n A way to extend HTML so that instead of having to build all our markup out of <div>, <input>, <span> and friends, \n we can build with higher-level primitives.\n
\n Extending custom elements with reusable markup blocks using the <template> and <slot> tags, for quickly generating complex layouts.\n
\n
\n
\n Those 3 bullets tell you everything and nothing at the same time.\n This probably isn't the first tutorial on Web Components you've seen, and you may find them a confusing topic.\n However, they're not that complicated as long as you build them up step by step ...\n
Let's start with the most basic form, a custom element that says 'hello world!':
\n \n
We can use it in a page like this:
\n \n
Which outputs this page:
\n \n
So what's happening here?
\n
We created a new HTML element, registered as the x-hello-world tag,\n and used it on the page. When we did that, we got the following DOM structure:\n
\n
body (node)\n
\n
x-hello-world (node)\n
\n
'hello world!' (textContent)
\n
\n
\n
\n
\n
\n \n
Explaining the code of the custom element line by line:
\n
\n
class HelloWorldComponent extends HTMLElement {
\n
Every custom element is a class extending HTMLElement. \n In theory it's possible to extend other classes – like HTMLButtonElement to extend a <button> –\n but in practice this doesn't work in Safari.
\n
connectedCallback() {
\n
\n This method is called when our element is added to the DOM,\n which means the element is ready to make DOM updates.\n Note that it may be called multiple times when the element or one of its ancestors is moved around the DOM.\n
\n
this.textContent = 'hello world!';
\n
The this in this case refers to our element, which has the full HTMLElement API,\n including its ancestors Element and Node, on which we can find the textContent property\n which is used to add the 'hello world!' string to the DOM.
For every web component window.customElements.define must be called once to register the custom element's class and associate it with a tag.\n After this line is called the custom element becomes available for use in HTML markup, and existing uses of it in already rendered markup will have their constructors called.
\n While the simple version above works for a quick demo, you'll probably want to do more pretty quickly:\n
\n
\n
Adding DOM elements as children to allow for richer content.
\n
Passing in attributes, and updating the DOM based on changes in those attributes.
\n
Styling the element, preferably in a way that's isolated and scales nicely.
\n
Defining all custom elements from a central place, instead of dumping random script tags in the middle of our markup.
\n
\n
\n To illustrate a way to do those things with custom elements, here's a custom element <x-avatar> that implements\n a simplified version of the HeroUI Avatar component (React):\n
\n\n \n \n
Some key elements that have changed:
\n
\n
The observedAttributes getter returns the element's attributes that when changed cause attributeChangedCallback() to be called by the browser, allowing us to update the UI.
\n
\n The connectedCallback method is written in the assumption that it will be called multiple times.\n This method is in fact called when the element is first added to the DOM, but also when it is moved around.\n
\n
\n The update() method handles initial render as well as updates, centralizing the UI logic.\n Note that this method is written in a defensive way with the if statement, because it may be called from the attributeChangedCallback() method before connectedCallback() creates the <img> element.\n
\n
The exported registerAvatarComponent function allows centralizing the logic that defines all custom elements in an application.
\n
\n
Once rendered this avatar component will have this DOM structure:
\n
\n
body (node)\n
\n
x-avatar (node)\n
\n
img (node)\n
\n
src (attribute)
\n
alt (attribute)
\n
\n
\n
\n
\n
\n
\n
\n
For styling of our component we can use a separate css file:
\n \n
Notice that:
\n
\n
Because we know what the tag of our component is, we can easily scope the styles by prepending them with x-avatar, so they won't conflict with the rest of the page.
\n
Because a custom element is just HTML, we can style based on the element's custom attributes in pure CSS, like the size attribute which resizes the component without any JavaScript.
\n
\n\n
An example that shows the two different sizes on a webpage:
\n \n\n
\n The HTML for this example centralizes the JavaScript and CSS logic to two index files, to make it easier to scale out to more web components.\n This pattern, or a pattern like it, can keep things organized in a web application that is built out of dozens or hundreds of different web components.\n
\n\n \n \n \n \n \n \n \n \n \n \n \n\n
\n The <script> tag in this example has moved into the <head> and picked up a defer attribute.\n This will allow it to download in parallel with the rest of the page, and have it execute right when the page is loaded.\n
\n
\n In index.css the use of the @import keyword may seem surprising as this keyword is often frowned upon for performance reasons.\n However, in modern browsers over HTTP/2 and in particular HTTP/3 the performance penalty of this keyword is not that severe,\n especially because files included with @import now download in parallel.\n
\n Allowing children to be added to a web component is not hard. In fact, it is the default behavior.\n To see how this works, let's extend the avatar example by wrapping it with a badge:\n
\n \n \n \n \n \n \n \n \n \n \n \n \n\n
To clarify, this is the DOM structure that is created:
\n
\n
div (node)\n
\n
x-badge (node)\n
\n
content (attribute)
\n
span (node, showing content)
\n
x-avatar (node)
\n
\n
\n
input (node)
\n
\n
\n
\n\n
The x-avatar component is identical to the previous example, but how does the x-badge work?
\n\n \n \n \n \n \n \n \n \n\n
Some notes on what's happening here:
\n
\n
this.insertBefore
\n
\n
\n Care must be taken to not overwrite the children already added in the markup, for example by assigning to innerHTML. \n In this case the span that shows the badge is inserted before the child elements.\n
\n
\n This also means that for custom elements that should not have children,\n this can be enforced by calling this.innerHTML = '' from connectedCallback().\n
\n
\n
set content(value) {
\n
\n Custom element attributes can only be accessed from JavaScript through the setAttribute() and getAttribute() methods.\n To have a cleaner JavaScript API a setter and getter must be created for a class property that wraps the custom element's content attribute.\n See the index.html above for where this is called.\n
\n Having seen what regular web components look like, we're now ready to jump up to the final difficulty level of web components, \n leveraging the more advanced features of Shadow DOM and HTML templates.\n
\n \n
This can all be brought together in this page layout example, that defines a new <x-header> component:
\n \n \n\n
This is the code for the newly added <x-header> component:
\n \n\n
There's a lot happening in header.js, so let's unpack.
\n The header code starts out by creating an HTML template.\n Templates are fragments of HTML that can be easily cloned and appended to a DOM.\n For complex web components that have a lot of markup, the use of a template is often convenient.\n By instantiating the template outside the class, it can be reused across all instances of the <x-header> component.\n
\n Because this component uses a shadow DOM, it is isolated from the styles of the containing page and starts out unstyled.\n The header.css needs to be imported into the shadow DOM using the <link> tag.\n The special import.meta.resolve trick \n imports the CSS file from the same path as the header.js file.\n
\n
<slot></slot>
\n
\n The <slot> element is where the child elements will go (like the <x-badge> child of <x-header>).\n Putting child elements in a slot is similar to using a children prop in a React component.\n The use of slots is only possible in web components that have a shadow DOM.\n
\n
constructor() {
\n
\n
\n This is the first example that uses a constructor. The constructor is called when the element is first created,\n but before it's ready for DOM interaction. The default behavior of a constructor is to call the parent class's constructor super().\n So if all that is needed is the default HTMLElement constructor behavior then no constructor needs to be specified.\n
\n
\n The reason it is specified here is because the constructor is guaranteed to be called exactly once,\n which makes it the ideal place to attach a shadow DOM.\n
\n
\n
if (!this.shadowRoot) { this.attachShadow({ mode: 'open' });
\n
\n
\n attachShadow attaches a shadow DOM to the current element, an isolated part of the DOM structure with CSS separated from the containing page,\n and optionally with the shadow content hidden away from the parent page's JavaScript context (if mode: 'closed' is set).\n For web components that are used in a known codebase, it is usually more convenient to use them in open mode,\n as is done here. \n
\n
\n if (!this.shadowRoot) { is not strictly necessary, but allows for server-side generated HTML,\n by making use of declarative shadow DOM.\n
\n The shadowRoot property is the root element of the attached shadow DOM, and is rendered into the page as the <x-header> element's content.\n The HTML template is cloned and appended into it.\n
\n
\n The shadow DOM becomes immediately available as soon as attachShadow is called,\n which is why the template can be appended in the constructor, and why the update() method can be called there.\n For custom elements without shadow DOM rendering the element's content should be deferred until connectedCallback().\n
As you can see in header.css, styling the content of a shadow DOM is a bit different:
\n
\n
The :host pseudo-selector applies styles to the element from the light DOM that hosts the shadow DOM (or in other words, to the custom element itself).
\n
The other styles (like h1 in this example) are isolated inside the shadow DOM.
\n
The shadow DOM starts out unstyled, which is why reset.css is imported again.
\n Everything up to this point assumes that data passed between web components is very simple, just simple numeric and string attributes passing down.\n A real world web application however passes complex data such as objects and arrays between parent and child components.\n
\n
\n This example demonstrates the three major ways that data can be passed between web components:\n
\n \n \n
Events
\n
The first way is passing events, usually from child components to their parent component. This is demonstrated by the form at the top of the example.
\n \n
\n Every time the Add button is pressed a CustomEvent of type add is dispatched using the dispatchEvent method.\n The event data's detail property carries the submitted form data.\n
\n
The event is handled one level up:
\n \n
The update() method sends the updated list back down to the <santas-list> and <santas-summary> components, using the next two methods.
\n\n \n\n
Properties
\n
The second way to pass complex data is by using class properties, as exemplified by the <santas-list> component:
\n \n
The list setter calls the update() method to rerender the list.
\n
This is the recommended way to pass complex data to stateful web components.
\n\n
\n The best practice way of implementing attributes, properties and events is subtle and opinionated.\n The article The Attribute-Property Duality dives into this topic in depth,\n and is recommended reading when making web components that will be embedded in third-party sites or are otherwise expected to behave\n like built-in elements.\n
\n\n \n\n
Methods
\n
The third way to pass complex data is by calling a method on the web component, as exemplified by the <santas-summary> component:
\n \n
This is the recommended way to pass complex data to stateless web components.
\n\n
Complete example
\n
Finally then, here is all the code for the Santa's List application:
\n \n With a population of about 2 million, Almaty is Kazakhstan's largest city. From 1929 to 1997, it was its capital city.\n \n \n The name comes from алма, the Kazakh word for \"apple\" and is often translated as \"full of apples\". In fact, the region surrounding Almaty is thought to be the ancestral home of the apple, and the wild Malus sieversii is considered a likely candidate for the ancestor of the modern domestic apple.\n \n `;\n this.querySelectorAll('x-panel').forEach((panel, index) => {\n panel.addEventListener('show', () => {\n this.activeIndex = index;\n });\n })\n this.update();\n }\n\n update() {\n this.querySelectorAll('x-panel').forEach((panel, index) => {\n panel.setAttribute('active', index === this.activeIndex);\n });\n }\n}\n\nexport const registerAccordionComponent = () => {\n customElements.define('x-accordion', Accordion);\n}\n"
},
{
"path": "public/pages/examples/applications/lifting-state-up/components/panel.js",
"content": "class Panel extends HTMLElement {\n constructor() {\n super();\n this.attachShadow({ mode: 'open' });\n }\n\n connectedCallback() {\n this.shadowRoot.innerHTML = `\n \n \n \n \n \n `;\n this.shadowRoot.querySelector('button').onclick = \n () => this.dispatchEvent(new CustomEvent('show'));\n this.update();\n }\n\n static get observedAttributes() { return ['title', 'active']; }\n\n attributeChangedCallback() {\n this.update();\n }\n\n update() {\n const heading = this.shadowRoot.querySelector('h3');\n const slot = this.shadowRoot.querySelector('slot');\n const button = this.shadowRoot.querySelector('button');\n if (heading && slot && button) {\n heading.textContent = this.title;\n slot.style.display = this.getAttribute('active') === 'true' ? 'block' : 'none';\n button.style.display = this.getAttribute('active') === 'true' ? 'none' : 'inline'; \n }\n }\n}\n\nexport const registerPanelComponent =\n () => customElements.define('x-panel', Panel);\n"
},
{
"path": "public/pages/examples/applications/lifting-state-up/index.css",
"content": "body {\n font-family: system-ui, sans-serif;\n}"
},
{
"path": "public/pages/examples/applications/lifting-state-up/index.html",
"content": "\n\n\n \n \n\n\n \n\n"
},
{
"path": "public/pages/examples/applications/lifting-state-up/index.js",
"content": "import { registerAccordionComponent } from './components/accordion.js';\nimport { registerPanelComponent } from './components/panel.js';\n\nconst app = () => {\n registerAccordionComponent();\n registerPanelComponent();\n}\n\ndocument.addEventListener('DOMContentLoaded', app);\n"
},
{
"path": "public/pages/examples/applications/lifting-state-up/react/App.js",
"content": "import { useState } from 'react';\n\nexport default function Accordion() {\n const [activeIndex, setActiveIndex] = useState(0);\n return (\n <>\n
Almaty, Kazakhstan
\n setActiveIndex(0)}\n >\n With a population of about 2 million, Almaty is Kazakhstan's largest city. From 1929 to 1997, it was its capital city.\n \n setActiveIndex(1)}\n >\n The name comes from алма, the Kazakh word for \"apple\" and is often translated as \"full of apples\". In fact, the region surrounding Almaty is thought to be the ancestral home of the apple, and the wild Malus sieversii is considered a likely candidate for the ancestor of the modern domestic apple.\n \n \n );\n}\n\nfunction Panel({\n title,\n children,\n isActive,\n onShow\n}) {\n return (\n \n
For content-driven websites with low interactivity a multi-page approach is best suited.
\n
Abandoning the use of frameworks means writing out those HTML pages from scratch. For this it is important to understand what a good minimal HTML page should look like.
\n \n
An explanation of each element:
\n
\n
<!doctype html>
\n
The doctype is required to have the HTML parsed as HTML5 instead of an older version.
\n
<html lang=\"en\">
\n
The lang attribute is recommended to make sure browsers don't misdetect the language used in the page.
\n
<head><title>
\n
The title will be used for the browser tab and when bookmarking, making it effectively non-optional.
\n
<head><meta charset=\"utf-8\">
\n
\n This is borderline unnecessary, but just to make sure a page is properly interpreted as UTF-8 this line should be included.\n Obviously the editor used to make the page should equally be set to UTF-8.\n
\n
<head><meta name=\"viewport\">
\n
The viewport meta is necessary to have mobile-friendly layout.
The main JavaScript file is in the <head>, and will bootstrap the web components as explained on the components page. The use of defer allows it to download while the rest of the page is loading and get executed at the end.
\n
<body><noscript>
\n
Because web components don't work without JavaScript it is good practice to include a noscript warning to users that have JavaScript disabled. This warning only needs to be on pages with web components. If you don't want to show anything except the warning, see the template pattern below.
\n
<body><header/main/footer>
\n
The page's markup should be organized using HTML landmarks. Landmarks when used properly help organize the page into logical blocks and make the page's structure accessible. Because they are standards-based, compatibility with present and future accessibility products is more likely.
\n
\n
\n Pages that should only show their contents if JavaScript is enabled can use this template pattern:\n
\n\n \n \n \n \n \n \n \n \n \n
Semantics matter
\n\n
\n The markup in the page should default to using semantic HTML, to improve accessibility and SEO.\n Web components should only be used in those cases where the level of complexity and interaction exceeds the capabilities of plain HTML markup.\n
\n
\n Familiarize yourself with these aspects of semantic HTML:\n
\n Being familiar with HTML's set of built-in elements saves time, \n both in avoiding the need for custom elements and in easing implementation of the custom elements that are needed.\n When properly used HTML elements are accessible by default.\n Pay special attention to the newly baseline features that enable complex UI patterns with minimal JavaScript, \n like how popover\n and dialog can be used to implement HTML-native tooltips, dialogs and menus,\n and how the details element can be used to implement accordions.\n
\n A suggested project layout for a vanilla multi-page website:\n
\n
\n
/
\n
The project root contains the files that will not be published, such as README.md, LICENSE or .gitignore.
\n
/public
\n
The public folder is published as-is, without build steps. It is the whole website.
\n
/public/index.html
\n
The main landing page of the website, not particularly different from the other pages, except for its path.
\n
/public/index.[js/css]
\n
\n The main stylesheet and javascript. These contain the shared styles and code for all pages.\n index.js loads and registers the web components used on all pages.\n By sharing these across multiple HTML pages unnecessary duplication and inconsistencies between pages can be avoided.\n
\n
/public/pages/[name].html
\n
\n All of the site's other pages, each including the same index.js and index.css,\n and ofcourse containing the content directly as markup in the HTML, leveraging the web components.\n
\n
/public/components/[name]/
\n
\n One folder per web component, containing a [name].js and [name].css file.\n The .js file is imported into the index.js file to register the web component.\n The .css file is imported into the global index.css or in the shadow DOM, as explained on the styling page.\n
\n
/public/lib/
\n
For all external libraries used as dependencies. See below for how to add and use these dependencies.
\n
/public/styles/
\n
The global styles referenced from index.css, as explained on the styling page.
\n
\n
\n Configuration files for a smoother workflow in programmer's editors also belong in the project's root.\n Most of the development experience of a framework-based project is possible without a build step through editor extensions.\n See the Visual Studio Code setup for this site for an example.\n
\n The old-school routing approach of standard HTML pages and <a> tags to link them together has the advantages of being easily indexed by search engines\n and fully supporting browser history and bookmarking functionality out of the box. 😉\n
At some point you may want to pull in third-party libraries. Without npm and a bundler this is still possible.
\n
Unpkg
\n
\n To use libraries without a bundler they need to be prebuilt in either ESM or UMD format.\n These libraries can be obtained from unpkg.com:\n
\n \n
Browse to unpkg.com/[library]/ (trailing slash matters), for example unpkg.com/microlight/
\n
Look for and download the library js file, which may be in a subfolder, like dist, esm or umd
\n
Place the library file in the lib/ folder
\n \n
Alternatively, the library may be loaded directly from CDN.
\n\n
UMD
\n
\n The UMD module format is an older format for libraries loaded from script tag,\n and it is the most widely supported, especially among older libraries.\n It can be recognized by having typeof define === 'function' && define.amd somewhere in the library JS.\n
\n
To include it in your project:
\n \n
Include it in a script tag: <script src=\"lib/microlight.js\"></script>
\n
Obtain it off the window: const { microlight } = window;
\n \n\n
ESM
\n
\n The ESM module format (also known as JavaScript modules) is the format specified by the ECMAScript standard, and newer or well-behaved libraries will typically provide an ESM build.\n It can be recognized by the use of the export keyword.\n
\n
To include it in your project:
\n
\n
Load it from CDN: import('https://unpkg.com/web-vitals@4.2.2/dist/web-vitals.js').then((webVitals) => ...)
\n
Or load it from a local copy: import webVitals from 'lib/web-vitals.js'
\n
\n\n
imports.js
\n
\n To neatly organize libraries and separate them from the rest of the codebase, they can be loaded and exported from an imports.js file.\n For example, here is a page that uses a UMD build of Day.js and an ESM build of web-vitals:\n
\n \n
The text is rendered by the <x-metrics> component:
\n \n
In the /lib folder we find these files:
\n
\n
web-vitals.js - the ESM build of web-vitals
\n
dayjs/\n
\n
dayjs.min.js - the UMD build of Day.js
\n
relativeTime.js - the UMD build of this Day.js plugin
\n
\n
\n
imports.js
\n
\n
Digging deeper into this last file we see how it bundles loading of third-party dependencies:
\n \n
\n It imports the ESM library directly, but it pulls the UMD libraries off the Window object.\n These are loaded in the HTML.\n
Regrettably not all libraries have a UMD or ESM build, but more and more do.
\n\n
Import Maps
\n \n
\n An alternative to the imports.js approach are import maps.\n These define a unique mapping between importable module name and corresponding library file in a special script tag in the HTML head.\n This allows a more traditional module-based import syntax in the rest of the codebase.\n
\n
The previous example adapted to use import maps:
\n \n \n \n \n \n \n \n \n \n \n \n
Some things to take into account when using import maps:
\n
\n
\n Import maps can only map to ESM modules, so for UMD libraries a wrapper must be provided, \n as with the module.js wrapper for dayjs in this example.\n
\n
\n External import maps of the form <script type=\"importmap\" src=\"importmap.json\"> are not yet supported in all browsers.\n This means the import map must be duplicated in every HTML page.\n
\n
\n The import map must be defined before the index.js script is loaded, preferably from the <head> section.\n
\n
\n Import maps can be used to more easily load libraries from a node_modules folder or from a CDN.\n JSPM generator can be used to quickly create an import map for CDN dependencies.\n Use this with caution, as adding such external dependencies makes a vanilla codebase rely on the continued availability of that service.\n
To keep up with new web standards, keep an eye on these projects:
\n
\n
Baseline keeps track of which features are widely available in browsers and lets you know when they are safe to use.
\n
Interop is a yearly initiative between browser makers to bring new web platform features to all browsers, or fix compatibility of existing ones. Consider it a preview of what will become baseline.
\n Popular testing frameworks are all designed to run in build pipelines.\n However, a plain vanilla web site has no build.\n To test web components an old-fashioned approach can be used: testing in the browser using the Mocha framework.\n
\n\n
For example, these are the live unit tests for the <x-tab-panel> component used to present tabbed source code panels on this site:
\n \n\n
And for ultimate coding inception, here is that tabpanel component showing the testing source code:
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n
Some working notes for how this is set up:
\n
\n
\n The entire code for the unit tests, including the testing libraries, is isolated to a public/tests/ subfolder.\n The tests will therefore be available live by adding /tests to the deployed site's URL.\n If you don't want to deploy the tests on the live website, exclude the tests folder during the deploy step.\n
\n
\n Mocha and Chai are used as test and assertion frameworks, \n because they work in-browser without a build step.\n
\n
\n DOM Testing Library is used to more easily query the DOM. \n The imports-test.js file configures it for vanilla use.\n
\n
\n An important limitation is that DOM Testing Library cannot query inside shadow roots.\n To test something inside a shadow root it is necessary to first query for the containing web component, \n get a handle to its shadowRoot property, and then query inside of that.\n
\n
\n Web Components initialize asynchronously, which can make them tricky to test.\n Use the async methods of DOM Testing Library.\n
\n Modern web applications are built on top of rich tooling for dealing with CSS, relying on plenty of NPM packages and build steps.\n A vanilla web application has to choose a lighter weight path, abandoning the preprocessed modern CSS approaches \n and choosing strategies that are browser native.\n
\n Typography is the keystone of a web site or web application. \n A lean approach like vanilla web development should be matched with a lean approach for typography.\n Modern Font Stacks describes a varied selection of commonly available fonts with good fallbacks,\n avoiding the need to load custom fonts and add external dependencies.\n
\n
This site uses the Geometric Humanist stack for normal text, and the Monospace Code stack for source code.
\n In any real world web project the amount of CSS quickly becomes unwieldy unless it is well-structured.\n Let's look at the toolbox that CSS provides us in modern browsers to provide that structure.\n
\n
\n
@import
\n
\n
\n The most basic structuring technique is separating CSS into multiple files. \n We could add all those files in order as <link> tags into the index.html\n but this quickly becomes unworkable if we have multiple HTML pages.\n Instead it is better to @import them into the index.css where they will still download in parallel. \n
\n
For example, here's the main CSS file for this site:
\n \n
Below is a recommended organization of CSS files.
\n
\n
Custom properties (variables)
\n
\n
CSS variables can be used to define the site's font and theme in a central place.
\n
For example, here are the variables for this site:
\n \n
CSS variables become even more capable when combined with calc().
\n
\n
Custom elements
\n
\n
Styles can be easily scoped to a custom element's tag.
\n
For example, the styles of the avatar component from the components page are all prepended by the x-avatar selector:
\n \n
Custom elements can also have custom attributes that selectors can leverage, as with the [size=lg] style in this example.
\n
\n
Shadow DOM
\n
\n
\n Adding a shadow DOM to a web component further isolates its styles from the rest of the page.\n For example, the x-header component from the previous page styles its h1 element inside its CSS,\n without affecting the containing page or the header's child elements.\n
\n In order to avoid conflicting styles between pages and components we want to scope styles locally by default.\n There are two main ways of achieving that in vanilla web development.\n
\n\n
Prefixed selectors
\n
\n For custom elements that don't have a shadow DOM we can prefix the styles with the tag of the custom element.\n For example, here's a simple web component that uses prefixed selectors to create a local scope:\n
\n Custom elements that use a shadow DOM start out unstyled with a local scope,\n and all styles must be explicitly imported into them. Here is the prefixed example reworked to use a shadow DOM instead.\n
\n The local scoping feature of CSS modules can be replaced by one of the scoping mechanisms described above.\n For instance, let's take the example of CSS modules from the Next.JS 14 documentation:\n
\n \n \n \n \n \n \n \n \n\n
As a vanilla web component, this is what that looks like:
\n \n \n \n \n \n \n \n \n
Because the shadow DOM does not inherit the page's styles, the styles.css must first import the styles that are shared between the page and the shadowed web component.
Let's go over the main page of PostCSS to review its feature set.
\n
\n
Add vendor prefixes to CSS rules using values from Can I Use.
\n
\n Vendor prefixes are no longer needed for most use cases.\n The :fullscreen pseudo-class shown in the example now works across browsers unprefixed.\n
\n
Convert modern CSS into something most browsers can understand.
\n
\n The modern CSS you want to use is most likely already supported.\n The color: oklch() rule shown in the example now works across browsers.\n
\n
CSS Modules
\n
\n See the alternatives described in the previous section.\n
\n
Enforce consistent conventions and avoid errors in your stylesheets with stylelint.
\n
\n The vscode-stylelint extension can be added into Visual Studio Code to get the same linting at develop time,\n without needing it to be baked into a build step.\n
\n
\n
Bottom line: Microsoft's dropping of support for IE11 combined with the continuing improvements of evergreen browsers has made PostCSS largely unnecessary.
Can be approximated by a combination of @import, CSS variables, and the scoping mechanisms described above.
\n
Mixins
\n
Regrettably the CSS mixins feature that will replace this is still in specification.
\n
Operators
\n
In many cases can be replaced by the built-in calc() feature.
\n
\n
Bottom-line: SASS is a lot more powerful than PostCSS, and while many of its features have a vanilla alternative it is not as easy to replace entirely. YMMV whether the added complexity of the SASS preprocessor is worth the additional abilities.
\n \n \n
Up next
\n \n
Learn about making vanilla sites with web components.
';\n\t var el = fragment(markup, test.speed, test.title, test.duration, url);\n\t self.addCodeToggle(el, test.body);\n\t appendToStack(el);\n\t updateStats();\n\t });\n\t runner.on(EVENT_TEST_FAIL, function (test) {\n\t var el = fragment('
', test.title, self.testURL(test));\n\t var stackString; // Note: Includes leading newline\n\n\t var message = test.err.toString(); // <=IE7 stringifies to [Object Error]. Since it can be overloaded, we\n\t // check for the result of the stringifying.\n\n\t if (message === '[object Error]') {\n\t message = test.err.message;\n\t }\n\n\t if (test.err.stack) {\n\t var indexOfMessage = test.err.stack.indexOf(test.err.message);\n\n\t if (indexOfMessage === -1) {\n\t stackString = test.err.stack;\n\t } else {\n\t stackString = test.err.stack.substr(test.err.message.length + indexOfMessage);\n\t }\n\t } else if (test.err.sourceURL && test.err.line !== undefined) {\n\t // Safari doesn't give you a stack. Let's at least provide a source line.\n\t stackString = '\\n(' + test.err.sourceURL + ':' + test.err.line + ')';\n\t }\n\n\t stackString = stackString || '';\n\n\t if (test.err.htmlMessage && stackString) {\n\t el.appendChild(fragment('
%s\\n
%e
', test.err.htmlMessage, stackString));\n\t } else if (test.err.htmlMessage) {\n\t el.appendChild(fragment('
![](\"./articles/2024-08-17-lets-build-a-blog/image.webp\")
\n ![\"Another](\"image.jpeg\")
\n ![\"Bricks](\"image.webp\")
\n ![\"generator](\"generator.webp\")
\n\n ![\"example](\"syntax-highlighting.webp\")
\n\n ![\"ESLint](\"eslinterror.png\")
\n ![\"Webhint](\"webhinterror.png\")
\n ![\"Live](\"live-preview.webp\")
\n ![\"devdocs.io](\"devdocs.webp\")
\n\n ![\"browser](\"vercel.webp\")
\n ![\"browser](\"plainvanilla.webp\")
\n ![\"a](\"http1.png\")
\n ![\"parallel](\"http2.png\")
\n ![\"A](\"react-demo.gif\")
\n ![\"architecture](\"architectures/old-school-desktop.webp\")
\n ![\"architecture](\"architectures/traditional-ssr.webp\")
\n ![\"architecture](\"architectures/liveview.webp\")
\n ![\"Architecture](\"architectures/modern-SPA.webp\")
\n ![\"architecture](\"architectures/streaming-SPA.webp\")
\n\n ![\"architecture](\"architectures/local-first-partial.webp\")
\n ![\"architecture](\"architectures/local-first-full.webp\")
\n ![\"initial](\"sketch-1.webp\")
\n ![\"final](\"sketch-2.webp\")
\n ![\"initial](\"https://plainvanillaweb.com/blog/articles/2026-03-01-redesigning-plain-vanilla/sketch-1.webp\")
\n ![\"final](\"https://plainvanillaweb.com/blog/articles/2026-03-01-redesigning-plain-vanilla/sketch-2.webp\")
\n ![\"architecture](\"https://plainvanillaweb.com/blog/articles/2025-07-16-local-first-architecture/architectures/modern-SPA.webp\")
\n ![\"architecture](\"https://plainvanillaweb.com/blog/articles/2025-07-16-local-first-architecture/architectures/local-first-partial.webp\")
\n ![\"architecture](\"https://plainvanillaweb.com/blog/articles/2025-07-16-local-first-architecture/architectures/local-first-full.webp\")
\n ![\"architecture](\"https://plainvanillaweb.com/blog/articles/2025-07-13-history-architecture/architectures/old-school-desktop.webp\")
\n ![\"architecture](\"https://plainvanillaweb.com/blog/articles/2025-07-13-history-architecture/architectures/traditional-ssr.webp\")
\n ![\"architecture](\"https://plainvanillaweb.com/blog/articles/2025-07-13-history-architecture/architectures/liveview.webp\")
\n ![\"Architecture](\"https://plainvanillaweb.com/blog/articles/2025-07-13-history-architecture/architectures/modern-SPA.webp\")
\n ![\"architecture](\"https://plainvanillaweb.com/blog/articles/2025-07-13-history-architecture/architectures/streaming-SPA.webp\")
\n\n ![\"A](\"https://plainvanillaweb.com/blog/articles/2025-06-12-view-transitions/react-demo.gif\")
\n ![\"browser](\"https://plainvanillaweb.com/blog/articles/2024-12-16-caching-vanilla-sites/vercel.webp\")
\n ![\"browser](\"https://plainvanillaweb.com/blog/articles/2024-12-16-caching-vanilla-sites/plainvanilla.webp\")
\n ![\"ESLint](\"https://plainvanillaweb.com/blog/articles/2024-10-20-editing-plain-vanilla/eslinterror.png\")
\n ![\"Webhint](\"https://plainvanillaweb.com/blog/articles/2024-10-20-editing-plain-vanilla/webhinterror.png\")
\n ![\"Syntax](\"https://plainvanillaweb.com/blog/articles/2024-10-20-editing-plain-vanilla/syntax-highlighting.webp\")
\n\n ![\"Live](\"https://plainvanillaweb.com/blog/articles/2024-10-20-editing-plain-vanilla/live-preview.webp\")
\n ![\"devdocs.io](\"https://plainvanillaweb.com/blog/articles/2024-10-20-editing-plain-vanilla/devdocs.webp\")
\n\n ![\"example](\"https://plainvanillaweb.com/blog/articles/2024-08-25-vanilla-entity-encoding/syntax-highlighting.webp\")
\n\n ![](\"./articles/2026-03-09-details-matters/image.webp\")
\n