JSON feed for my blog by Matt Hobbs (Nooshu.com)

How a Simple CSP Tweak Turned into an AI Project

2026-06-20T00:00:00Z

Introduction

In this post, I’ll tell the story of how a stray semicolon led me to build an AI-powered tool to make creating Content Security Policies (CSPs) a bit less painful for developers.

I’ve written about CSPs on this blog before:

December 2024: Securing your static website with HTTP response headers
February 2025: Configuring your Content-Security-Policy on your development environment in 11ty

To quote from my 2024 post:

The Content Security Policy (CSP) header is a security feature that protects web applications from attacks like Cross-Site Scripting (XSS) and code injection by controlling the sources from which browsers can load and execute content. If there's only a single response header you implement today, then make it the CSP Response header.

The post has a few more details, so if you are interested you can find the Content-Security-Policy (CSP) section here.

As mentioned in the post, there are already a huge number of tools available on the web for creating CSP’s, but none of them really fit my needs. So, I decided to write my own tool using cursor.ai and host it on the web for everyone to evaluate and use. Note: I've included my referral link so any readers can get 50% off their first month subscription.

It is called CSP Playground⁠. Despite the name, writing a CSP is rarely described as “fun”, and “playground” may be overselling the experience somewhat.

It seemed as sensible a name as any, though. Besides, the domain wasn’t taken and only cost £9, which is cheap enough to make almost any naming decision seem justified!

I briefly considered splashing out on a .security top-level domain (TLD), until Cloudflare Registrar reminded me that the privilege would cost only £1,515 per year.

I suspect telling my wife that we’ve cancelled our summer holiday plans so I can own a particularly niche bit of the internet would have tested the “for richer or poorer” part of our vows rather more thoroughly than intended. 😬

Problem

If any readers have tried to write a CSP “manually”, you will understand how painful it really is! Understanding the very particular syntax is challenging. Although CSP itself does not have to be written on a single line conceptually, when the header is sent over the network, it must not contain any arbitrary line breaks, else it will be classed as invalid. And don’t even get me started on the use of ;, one misplaced semicolon and your browser console will throw a very red looking hissy fit!

There are whole RFC’s dedicated to the specifics of HTTP header fields, that I won’t even pretend to understand! Linked below for a little light reading, if you are struggling to sleep!

Anyway, as I always do, I’ve wandered off on a bit of a tangent.

What I’m basically saying is writing CSP’s is complicated and frustrating (especially for a terrible typist like myself!), So why not make life easier and spend a couple of days in "AI world” and build a tool to make your life easier? You never know, it may even help others too!

Features

Form-based editor for every standard CSP directive: No hand-editing of semicolon syntax
Import from URL: Fetch a policy from headers or meta tags, or detect when none exists
Paste headers or policy: Paste a full HTTP response header block or a single Content-Security-Policy line; the CSP is extracted in the browser and used to pre-fill the form
Real-time security score: Including actionable recommendations that navigate you instantly to the exact directive
Nonce and hash helpers: Generate values and copy ready-to-paste HTML snippets
One-click export: Policy, header line, or server config for Apache, Nginx, Caddy, Cloudflare, Netlify, Vercel, and more
Report-only mode: Option to output the CSP using Content-Security-Policy-Report-Only. Allowing for testing before enforcement
MDN links and inline help: Every directive and sandbox flag links directly to the relevant MDN content
Privacy focused by design: No accounts, no tracking, and no database. Nothing is stored because there’s nowhere to store it
Runs mostly in the browser: Policy editing and paste import stay local; the only server-side processing happens when you explicitly import a URL to fetch your site’s CSP
Free and open-source: MIT licensed at https://csp-playground.dev/, code available on GitHub
Clean design Built on the fantastic utopia.fyi Fluid Design CSS grid built by Clearleft

Audit

Start from a real policy instead of a blank form. Enter a URL and CSP Playground will retrieve the CSP from the response headers or a <meta> tag. Alternatively, you can paste the headers or the policy string directly. Everything stays in the browser, with the exception of URL lookups.

Whichever approach you choose, the editor is pre-populated so you can quickly see what is being enforced.

If the lookup finds problems (duplicates, deprecated directives, odd formatting), it flags them and suggests fixes.

For sites where there is no CSP at all, the tool does not leave a user at in the lurch: it points you to a short guide on why a policy matters and how to start safely, so auditing either an existing policy or a blank slate becomes the first step toward a stronger CSP.

Build

Whether you are starting from scratch or updating an existing policy, you can work through each CSP directive using a structured form. Add sources without worrying about syntax, generate (placeholder) nonces and hashes for inline scripts and styles, and copy ready-to-use HTML snippets.

Every directive links directly to MDN, so the documentation is always one click away when you need it.

Improve

As you edit, CSP Playground scores your policy in real time and highlights improvements you can make. Recommendations are practical, and show the expected score increase, simply click on the recommendation, and it takes you straight to the relevant directive. You can also see your potential score if you applied every suggestion. This makes it a whole lot easier to focus on the changes that matter most, even if you’ve never written a CSP before.

Deploy

When you are happy with your shiny new Content Security Policy, CSP Playground generates the full header and provides config snippets for web servers and hosting platforms:

Apache
Nginx
Caddy
LiteSpeed
Microsoft IIS
Netlify
Cloudflare Pages
Vercel
Traefik
Envoy
more can be added on request, just create an issue

You can also toggle a setting so that the server setup only attaches the CSP header to HTML responses, cutting down on repeated headers across all static assets, where they aren’t required.

Lastly, you can switch to Report-Only mode to test changes before enforcement, with links to MDN guidance to help you roll out your new (or updated) CSP safely.

Result

So, the first test for the tool was the CSP for this very website, after all it’s the reason I built it! As mentioned at the start of the post, the first result of my initial iteration of the tool caught a stray. It must have been live for quite a while, as I haven’t touched the CSP since February 2025. Thankfully, it wasn’t serious, hence why it went unnoticed. The validator picked it up and changed this:

Content-Security-Policy: base-uri 'self';child-src 'self';connect-src 'self' https://challenges.cloudflare.com/;default-src 'none';img-src 'self' https://v1.indieweb-avatar.11ty.dev/;font-src 'self';form-action 'self' https://webmention.io;frame-ancestors 'none';frame-src 'self' https://player.vimeo.com/ https://www.slideshare.net/ https://www.youtube.com/ https://giscus.app/ https://challenges.cloudflare.com/;manifest-src 'self';media-src 'self';object-src 'none';script-src 'self' 'inline-speculation-rules' https://ajax.cloudflare.com https://giscus.app/ https://challenges.cloudflare.com/;script-src-elem 'self' 'inline-speculation-rules' https://ajax.cloudflare.com https://giscus.app/ https://challenges.cloudflare.com/;style-src 'self' 'unsafe-inline' https://giscus.app/;worker-src 'self';

To this:

Content-Security-Policy: base-uri 'self';child-src 'self';connect-src 'self' https://challenges.cloudflare.com/;default-src 'none';img-src 'self' https://v1.indieweb-avatar.11ty.dev/;font-src 'self';form-action 'self' https://webmention.io;frame-ancestors 'none';frame-src 'self' https://player.vimeo.com/ https://www.slideshare.net/ https://www.youtube.com/ https://giscus.app/ https://challenges.cloudflare.com/;manifest-src 'self';media-src 'self';object-src 'none';script-src 'self' 'inline-speculation-rules' https://ajax.cloudflare.com https://giscus.app/ https://challenges.cloudflare.com/;script-src-elem 'self' 'inline-speculation-rules' https://ajax.cloudflare.com https://giscus.app/ https://challenges.cloudflare.com/;style-src 'self' 'unsafe-inline' https://giscus.app/;worker-src 'self'

It took me a little while to spot the difference because the validator simply reported a "semicolon change". If you are able to notice these small changes straight away, congratulations, you’re more observant than I am!

For any readers wondering the only difference is that the trailing semicolon in the second version has been removed. It’s actually entirely optional and has no effect on how the CSP behaves.

I admit it’s hardly a groundbreaking discovery, but it was reassuring to see that the validation functionality was doing exactly what it should.

The next changes it recommended made more of an impact and improved my CSP score. The initial score was 79%. Not bad, but we can do better with only 2 minor changes:

trusted-types (TT)

I must admit I’d never heard of this directive until the tool recommended it.

It's only very recently (February) that it has been marked as Baseline in the MDN documentation due to broad cross browser support across all modern browsers.

It was actually Mozilla who were dragging their feet on this directive, but thankfully changed their stance on it back in 2023. Full support in Firefox was released in version 148 (released 24 February 2026).

If you’re curious about this directive, here’s an ELI5 explanation:

Think of an Aeroplane at an airport.
Before TT: Anybody could walk straight onto the plane.
After TT: Everybody must:
1. Go through security.
2. Have their passport checked.
3. Receive an approved boarding pass.

Only passengers (or potentially executable content in this analogy) with a valid boarding pass are allowed onto the plane.

Trusted Types are the boarding pass.

For readers who are older than 5, you can read all about the Trusted Types API in great depth on MDN.

upgrade-insecure-requests

This directive is pretty self-explanatory given the name. upgrade-insecure-requests instructs a browser to automatically upgrade HTTP requests to HTTPS before loading resources. Resources that do not support HTTPS will fail to load, although this is very rare on the modern web.

By simply adding:

trusted-types 'none'; upgrade-insecure-requests

to my CSP, it bumped the score from 79% up to 87%!

A respectable gain for what was, in the grand scheme of things, barely any work!

Adding upgrade-insecure-requests improves protection against mixed content by upgrading HTTP resources to HTTPS. Meanwhile, trusted-types 'none' does not actually enforce Trusted Types, but it does make the decision to not use them very explicit.

For the moment I have simply disabled the use of Trusted Types in the CSP, but in the future I will likely enable enforcement via the use of:

require-trusted-types-for 'script'; trusted-types default;

Once enforced this will bring the sites CSP score up to 95%! 🎉

Update 1: I tested require-trusted-types-for 'script'; with 'trusted-types default;, but it breaks a few scripts across the site, so have reverted to trusted-types 'none';. I will update once I have resolved the issues. It just goes to show how much testing you need to do when you change your site's CSP! Use Content-Security-Policy-Report-Only if in doubt!

Update 2: It turns out these errors occur because some of these scripts use legacy code, such as:

// or element.innerHTML = `<p>${text}</p>`;
element.innerHTML = '<p>' + text + '</p>';

To properly resolve these issues, you'd need to refactor the scripts to use more standard DOM manipulation methods, like:

const p = document.createElement('p');
p.textContent = text;
element.appendChild(p);

The problem comes when you don't "own" these scripts, e.g. a 3rd-party script. It's just not practical to update these scripts without the original author(s) being involved, as any new version of the script will overwrite the changes.

There is a workaround:

// run this code immediately using an Immediately Invoked Function Expression (IIFE)
(function () {
	// check see if the browser supports the trustedTypes API
	if (window.trustedTypes?.createPolicy) {
		// Create a Trusted Types policy called "default" policy for the browser to use e.g. `trusted-types default;`
		trustedTypes.createPolicy('default', {
			// allow all HTML through e.g. I trust every HTML string. (this is bad!)
			createHTML: (string) => string,
		});
	}
})();

It is critical that this code executes before the browser tries to execute innerHTML, as without the policy the code will fail. Unfortunately, this code has a major security implication: XSS vulnerabilities are no longer prevented.

Given this implication, I'm going to stick to trusted-types 'none'; for the moment, or at least until I look into using DOMPurify to "enable" XSS protection.

Update 3: I have tried a solution using ) on my preview environments, and I'm still seeing a host of little issues like missing images in some functionality, so I'll stick with trusted-types 'none'; for the moment as it's the only otion that works at the moment. It's unfortunate that it really isn't adding much in terms of site security, and it's only there for the "CSP Score", but on the positive side it's been another CSP learning curve for me! So when using the trusted-types directive, you should definetly expect issues with JavaScript that uses legacy code! It could be a while before anyone gets to roll out this directive without issues!

**Update 3: I have tried a solution using DOMPurify on my preview environments, and I'm still seeing a host of little issues like missing images in some functionality. So, I'll stick with for the moment, as it's the only option that works at the moment. It's unfortunate that it really isn't adding much in terms of site security, and it's only there for the "CSP Score", but on the positive side it's been another CSP learning curve for me! So when using the trusted-types directive, you should definitely expect issues with JavaScript that uses legacy code! It could be a while before anyone gets to roll out this directive without issues!

Summary

I promised myself that I wouldn’t make this blog post an epic read this time, so fingers crossed I have kept my promise! If you happen to be interested in my “strategy” and opinion (for what it's worth) on AI assisted coding off the back of this post, I’ve wrote all about it here in my FractalAI: Generating Infinity in the Browser post from April.

Lastly, you can find CSP Playground here, and the GitHub repo for the code here. PRs and Issues welcome!

I hope you find this little tool useful! I’ve enjoyed building it and learning a little more about the world of CSPs, and Trusted Types.

As always, thanks for reading, feedback and comments are welcome. You can contact me here.

Post changelog:

20/06/26: Initial post published.
20/06/26: Reverted require-trusted-types-for 'script'; with trusted-types default; to trusted-types 'none'; because it broke a number of scripts on the site!
20/06/26: Added information about the require-trusted-types-for 'script'; workaround before 3rd-party scripts are updated to use non-legacy DOM methods. Sticking with trusted-types 'none'; for the moment.
21/06/26: I tried to resolve issues with require-trusted-types-for 'script'; with trusted-types default; by using DOMPurify, but there are still other problems that pop up, so still sticking with trusted-types 'none';. I'll chalk this one up to a learning exercise, and leave it as is for now! After all, this post was only supposed to be about CSP Playground, not the Trusted Types directive.

FractalAI: Generating Infinity in the Browser

2026-04-21T00:00:00Z

Why I Built FractalAI

Although AI has been a concept that has been discussed for the past 80 years (Thanks to Alan Turing, and many others), it’s only in the past 5 to 10 years that it has become vastly more powerful. It is currently the hot topic in pretty much every industry on the planet! Software development in particular has already changed drastically, with new tools and AI Models popping up every week. You only have to look at the Stack Overflow Developer Survey 2025 to see how common its usage is in Software development:

84% of developers are using or planning to use AI
51% of professional developers use it daily
61% of professional developers look at it favourably
35% of developers visit Stack Overflow due to AI-related issues

So like it or not, AI is here, and it is here to stay. So to keep up with "the pack” it’s probably a good idea to start learning how to use it, (and more importantly) where to be cautious!

The Constraint: 100% AI-Generated Code

To get to grips with AI and its current limits, I decided to set myself a task: build a new hobby project using only AI. All code, all functionality, and even all the design would be generated by me prompting the AI to tweak and generate the frontend code. This is an excellent way to see how AI handles CSS and general usability. For this, I use an AI Tool called Cursor. There are many tools available, but since subscribing to their pro plan, I’ve seen no real reason to change. Some of the key advantages I see over other AI tools are:

Project-wide context awareness: Cursor understands the entire codebase rather than a single file, which leads to more accurate suggestions and safer large-scale changes across interconnected systems.
Multi-file editing and refactoring: Cursor can apply consistent updates across multiple files in one action, making large refactors and cross-cutting changes significantly more efficient.
AI-driven workflows: Cursor acts as an AI agent that can plan and execute multistep development tasks rather than just offering inline code suggestions.
Context-aware integrated chat: Cursor’s built-in chat has full awareness of the repository and can directly modify code, reducing the need for manual context sharing.
Model flexibility: Cursor allows developers to switch between different AI models, enabling optimisation for performance, cost, or task-specific quality.
Optimised for complex systems: Cursor performs particularly well in large and complex codebases where deeper reasoning and architectural understanding are required.
Faster end-to-end task completion: Cursor often reduces overall development time by completing entire tasks in fewer steps, even if individual code suggestions are not the fastest.
AI-native IDE design: Cursor is built from the ground up as an AI-first environment, enabling tighter integration and more advanced workflows than plugin-based alternatives.

FYI: I’m not sponsored by Cursor, I just love how clean and simple it is too pickup and use! There are many others on the web that you can choose instead!

What FractalAI Actually Does

Well, as you may have guessed already from the name of the blog post, the project I chose to build what a fractal generator 100% built on modern browser technology. The code is all open-source and free for anyone to clone, modify and use as they wish! The code repository is on GitHub here.

The project currently comes with the following features:

Fractal Selection: Choose from 100+ fractal types via dropdown menu.
Adjustable Iterations: Control detail level (10 to 400 iterations).
35+ Colour Schemes: Classic, Fire, Ocean, Rainbow variants, Monochrome, Forest, Sunset, Purple, Cyan, Gold, Ice, Neon, Cosmic, Aurora, Coral, Autumn, Midnight, Emerald, Rose Gold, Electric, Vintage, Tropical, Galaxy, Lava, Arctic, Sakura, Volcanic, Mint, Sunrise, Steel, Prism, Mystic, Amber, and more.
Zoom and Pan: Click and drag to pan, scroll or double-click to zoom.
Real-time Parameter Adjustment: Adjust Julia set constants, scales, and other parameters in real-time.
Screenshot Capture: Save current view as PNG with EXIF metadata.
FPS Monitoring: Real-time frame rate display.
Coordinate Display: View and copy exact fractal coordinates.
Presets System: Quick-load pre-configured fractal views.
Favourites System: Save and manage favourite fractal configurations.
Share & URL State: Share fractals via URL with encoded state.

This was just a copy / paste from the README.md file in the repository, it actually comes with more features that you can read about like Machine Learning-Powered Discovery, Performance Optimizations, and Advanced Features.

I’ve been fascinated with Fractals for many years, I actually dabbled with fractal generation and Web Workers back in January 2010, scarily that’s a whole 16-years ago! That makes me feel very 👴!

The reason fractals have always fascinated me is perfectly summed up in this quote from the godfather of fractals Benoît Mandelbrot:

Bottomless wonders spring from simple rules, which are repeated without end.

I find it simply astounding that a whole infinite world can be rendered by a computer using such "simple" mathematics. For example, the iconic Mandelbrot fractal is all generated via this neat little formula:

z_{n + 1} = z_{n}^{2} + c

Where:

$z_{0} = 0$
$c \in C$ (a complex number)

A point $c$ belongs to the Mandelbrot set if the sequence does not diverge:

n \to \infty lim ∣ z_{n} ∣ \neq \to \infty

Which generates this absolutely stunning image that you can literally zoom in to forever!

The image above really doesn’t do the details of the Mandelbrot justice! So why not take a look around the original setting I used to render it here.

Why the Browser Is Surprisingly Good at Rendering Fractals

What makes the browser surprisingly good at rendering fractals is not just raw capability, but accessibility and reach. A fractal renderer written in the browser can run anywhere instantly with no installation, no setup, and no platform constraints. That is a powerful starting point. Additionaly there's JavaScript, as the language behind this project, it is embedded in every modern browser, making it one of the most widely available execution environments in the world.

This accessibility isn't theoretical, it shows up in everyday life. Just last month, while walking my 8-year-old son home from primary school, he told me about what he had been learning in "Coding Club" using his BBC micro:bit. He was genuinely excited when he said:

Daddy, I’ve been learning all about something called JavaScript!

That moment really highlighted the scale of JavaScript’s reach. It is not just a professional tool, it is something being introduced at a very young age. When I explained that it forms a large part of my own work, it reinforced how deeply embedded it is in both education and industry.

It is remarkable to think that a language first created by Brendan Eich in just 10-days has evolved into a platform capable of driving complex visualisations like fractal rendering!

This, combined with modern browser features such as high-performance JavaScript engines, GPU acceleration through WebGL, and efficient canvas APIs, the browser has become an unexpectedly capable environment for this kind of computationally intensive work.

AI as a Design Partner, Not Just a Tool

I’ve found that AI is most powerful when it is treated as a design partner rather than just a tool for generating code. While it is clearly effective at implementation, its real strength lies in collaboration. You can ask it to plan a feature, and it will respond with probing questions that help clarify intent, constraints, and direction. Those questions are not incidental, they are often the key to shaping a better outcome, giving you the opportunity to guide and refine the approach early in a project.

Because of the breadth of knowledge it draws on, the interaction feels less like issuing instructions and more like a back and forth design "conversation". It becomes a space for exploring ideas, testing assumptions, and iterating quickly before committing to an ideal solution.

This became particularly valuable in areas where I would not usually feel confident, such as design. Rather than treating that as a limitation, I leaned into AI to generate an initial direction. From there, my role shifted to refinement. Once a baseline design was in place, I could make targeted adjustments to the CSS and HTML, either through follow-up prompts or by working directly with insights gathered from the Browser DevTools.

Although I had originally set myself the constraint of not writing any code, I found that introducing precise, real-world context from DevTools significantly improved the quality of the AI’s output (more on this later in the post). By feeding in specific observations rather than abstract instructions, the responses became more relevant, more predictable, and easier to iterate on.

This is where AI moves beyond being a simple tool. It becomes a collaborator that helps shape both the design thinking and the implementation, with you firmly guiding the direction at each step.

The Architecture (Without Writing Code Myself)

This was easily the most engaging part of the process and where the most learning happened. Having the freedom to choose technologies and then observe how AI composes them into a coherent architecture is genuinely insightful, especially when you examine the reasoning behind those decisions.

When you are unsure whether a technology is a good fit for a project, you can quickly create a "throwaway" prototype and evaluate it. That shifts the role of AI from a coding assistant to a decision support tool. You are not just generating output, you are generating evidence.

Over time, this creates a feedback loop where each experiment improves your judgement. You learn what works, what to avoid, and why.

This aligns closely with core Agile principles:

Fail early to surface risk
Iterate quickly to explore options
Learn continuously to improve decisions

If you use AI for anything, use it to accelerate learning. Speed only matters when it leads to better decisions.

Machine Learning Inside the Browser

For many years, I’d wanted to have a play with machine learning (ML), but had never really had the opportunity. With the arrival of browser-based libraries like TensorFlow.js, the idea of running ML directly in the browser suddenly became far more accessible.

In this project, I saw an interesting opportunity to apply it to the “random fractal position” feature. The goal was simple on the surface. A user selects a fractal and a colour scheme, presses a button, and gets a random set of x, y, and z values to explore.

In practice, it was not that simple.

When the AI first implemented this in plain JavaScript, I ran into a fundamental problem. A large proportion of fractal space is effectively empty, which meant most “random” positions resulted in a blank or uninteresting visual. I initially tried constraining the co-ordinates to specific regions, but with over 100 fractals available, this quickly became unmanageable.

So I started thinking differently. Instead of hard-coding “good” regions, what if the system could learn what a good fractal view looks like?

That is where machine learning came in. The idea was to train a lightweight model to recognise visually interesting outputs, effectively teaching the random feature to make better choices over time. Using AI to help generate and iterate on this approach made the experimentation surprisingly fast.

Originally, I explored using TensorFlow.js, but it turned out to be far too heavy for this use case. Even compressed, it added around 450 KB of JavaScript, which is significant given the existing bundle size for all the fractal rendering functionality.

Instead, I opted for Synaptic. It is much smaller at around 45 KB when Brotli compressed, and while it has not seen recent updates, it proved more than capable for what I needed. It also keeps the overall performance profile of the application in check, which was a key consideration.

If required, this approach leaves the door open to swap Synaptic out for a more modern ML library in the future. But for now, it demonstrates something powerful. You can run meaningful machine learning directly in the browser, and use it to enhance user experience in ways that would be difficult to achieve with traditional logic alone.

As mentioned in the README.md file in the GitHub repository it is used for the following functionality:

ML-Based Scoring: Uses Synaptic.js neural network to score fractal configurations.
Hybrid Algorithm: Combines fast heuristic screening with ML refinement.
Personalised Learning: Trains on your favourites to learn your preferences.
"Surprise Me" Feature: Discover interesting new fractal zooms automatically.
Background Training: Model retrains automatically as you add favourites.
Local Storage: ML model and favourites persist in browser storage.

Note: You will find all of this functionality in the “Full-screen view” of the fractal viewer. The standard UI was starting to feel quite crowded, so that ended up being the most sensible place for it.

What Worked Surprisingly Well

Planning

Planning from the AI was excellent. This may be a Cursor-specific feature, but the follow-up questions it asked about how I wanted to approach a problem were a really nice touch. When you are unsure which direction the AI will take, this gives you useful insights early on.

Crafted Prompts

Top AI Tip: Detailed prompts made a huge difference. The more specific I was, the more reliable the output became. In some cases, I even included images or copied exact code from DevTools just to make sure the AI fully understood the context.

I really liked how Anthony Alicea explains AI in his Understanding AI-Assisted Software Development course. He visualises the AI “brain” as a cube, where each smaller blue cube represents a piece of knowledge the AI has learned. It’s a simple idea, but it makes how AI works much easier to grasp.

A visualisation from his course is shown below:

This “knowledge” could include things like:

Documents
Images
External data
Specifications
Examples
Instructions

Your job when prompting the AI is to “sail” across this ocean of knowledge and get to a favourable output on the opposite side. To get better results, you need to give the AI waypoints or "lighthouses" to direct the AI through this ocean of knowledge, your prompts are these "lighthouses". That way, you guide the path it takes, rather than leaving it to figure one out on its own.

So rather than saying:

Build me a website that renders fractals

Be more specific:

Build me a website that renders fractals. Start with a simple Mandelbrot set and use the Canvas API to draw it. I’d also like you to leverage the WebGL API in the visualisation. Make sure the code is well documented and uses modern linting tools like Stylelint and ESLint to keep it maintainable. I also want to use Vite as the local development server…

Now, you might be thinking, that’s a long prompt! It is. But if you want reliable output, you need to give the AI clear instructions to follow. Otherwise, it will just “set sail” across that vast corpus of information and produce something unfocused because it has too much freedom.

If there’s one thing I learned from this project, it’s this: spend time crafting detailed prompts. That’s how you steer the ship across the ocean of information and actually reach the result you want.

Rules

Another useful thing I learned is that you can give the AI a consistent set of rules to follow across every prompt. In Cursor, these live in the .cursor/rules directory in your repository.

In the FractalAI project, I ended up with four sets of rules:

The AI refers to these rules for every prompt, giving it consistent context and guidance. You might notice they look AI-generated, and you’d be right. It’s a bit meta, but I asked Cursor to write the rules it would follow in future prompts.

The thinking behind this was simple: it is far more likely to understand its own instructions than my rambling ones!

I’m not sure if this is specific to Cursor, or if other AIs follow a similar approach. It would be great to see some standardisation here to allow these rules to be portable across multiple AI tools in the future.

If this is already happening, I’d love to know. Please feel free to let me know if you have any information!

Writing Tests

If you are not a fan of writing tests, even though you know you should, AI helps a lot. If it can write the code, it can just as easily write the tests too.

Where a human developer might get tired of writing tests, AI doesn't. That makes it much easier to push towards high coverage and keep things consistent.

And if you enjoy that warm feeling of seeing a wall of green in your terminal's test output, this definitely helps. I’m one of those people:

Can you imagine how long it would take to get 100% coverage across all files, Statements, Branches, Functions, and Lines? That's a lot of work for one (obsessive) person.

Or, a perfect job for AI!

Refactoring

Where AI really excelled in this project was its ability to understand even the smallest details of the codebase. That makes refactoring fast and almost effortless.

For example, I initially used TensorFlow.js, but quickly realised it was too heavy and overly complex for what I needed. So I gave a simple prompt:

Could you swap out TensorFlow.js and use Synaptic instead? The page weight is too high and it’s more complex than required.

The important part here is the added context. By explaining why I wanted the change, I was building up the AI’s understanding of the project.

From just that, it learns that I care about performance and keeping things lightweight, which leads to better, more aligned outputs as the project progresses.

If you combine AI’s ability to refactor quickly with version control like Git, you are onto a winning combination.

You can easily branch and tag different versions of your project to experiment with alternative approaches or technologies. If a refactor does not work out, just roll back to a previous commit, or simply scrap the branch / tag.

One thing to watch out for if you do this is be wary of your node_modules folder. Projects tend to get a bit cranky if the dependencies are not installed correctly. And no, committing node_modules to your repo is not the answer! 🤮

An added bonus when using this technique is if you have good test coverage, you can swap out a technology and quickly run your tests to see what has broken. It makes validating a refactor fast and far less risky.

This is where AI and testing really come into their own. The AI can make sweeping changes, and your tests act as the safety net to catch anything that breaks.

Proof of concepts

At the start of my career in digital marketing, there was a familiar pattern. Most of the budget went on UX and design. By the time it reached the build phase, you would give an estimate and hear, “We don’t have the budget for that.”

Classic waterfall. Siloed teams. And not much left for actually building "the thing".

There was even a running joke that what we really needed was a big “build it” button, so the technology part cost next to nothing.

When it comes to proof of concepts, or spikes as some call them, you are essentially writing throwaway code. This is where that “build it” button starts to feel real.

With a bit of direction on the tech stack and constraints, you can have AI produce a working prototype in hours, not days. Especially when dealing with unfamiliar technologies.

What I’m really saying is that AI is great for testing ideas in code. Going back to the Agile principles I mentioned earlier in the post:

Fail early to surface risk
Iterate quickly to explore options
Learn continuously to improve decisions

These all map perfectly to AI-generated proof of concepts.

Word of warning: be careful using AI-generated code in live / production without proper validation. Make sure it goes through the usual checks like Pull Requests (PRs), Continuous Integration, and Deployment (CI/CD) gates.

If something goes wrong, you can't blame the AI (well you could try, but I doubt it would go down well!)

Rule of thumb: There should always be a human reviewing AI-generated code, especially when sensitive data is involved.

Making unfamiliar things make sense

I’ve touched on this a little in the previous sections, one of AI’s superpowers is being able to explain complex concepts to the user when required. This is especially true when it comes to software development and technologies a user has no experience of before. AI is basically an incredibly patient coach who is always willing to answer your questions, no mater how small or stupid they may be! When combined with a Code UI like VS Code, you are really working with a powerful workflow. Being able to highlight individual rows and blocks of code and get AI to explain exactly what is happening is a dream come true for anyone learning to code in 2026! I know I wish I had it when I was a junior developer, far to many years ago!

Another thing I found really useful is learning through optimisation. You might write a piece of code you understand, then ask the AI:

Are there any edge cases I have missed?
How can I make it more maintainable?
Does this code follow best practices for the framework?
How can I make it more performant?
Will this code perform well if the website is scaled up?
How can I make it easier to read for other developers?
etc…

These kinds of questions help reinforce your understanding, especially around the less obvious parts of a language.

Building momentum

Because I’m so old, I remember when Stack Overflow first appeared back in late 2008. It was a game changer for web development and beyond. A place to ask questions and get a range of answers, some useful, some less so.

I’ve never been one to answer loads of questions, but I do try to go back and share solutions when I find them.

The downside is it breaks your flow. One minute you are productive, the next you are stuck searching for answers, sometimes for hours. And if your problem is niche and not already answered, you could be left waiting days for a response.

With AI built into your code editor, you have all that knowledge and reasoning right at your fingertips. No need to leave the comfort of your IDE or go searching the web for that one insight that leads to a “Eureka” moment.

The result of using AI in this way is simple. Higher productivity, less frustration, and faster learning.

A win all round.

Where AI Fell Short (and Needed Steering)

The definition of insanity

To quote Albert Einstein:

Insanity is doing the same thing over and over again and expecting different results.

At times, this is precisely what using AI felt like. It would get stuck on a particular solution and keep coming back to it, no matter how I rephrased the prompt or tried to steer it in a different direction. It was incredibly frustrating.

The only reliable fix was to start a new chat, which meant losing all the project context, or switch to a different model in Cursor. I usually run in “auto" mode to balance cost and capability, but switching models also meant losing that built up understanding within the AI prompt.

There may be a better way to handle this without resetting everything? Again, if you know, please let me know.

Over-engineering simple problems

If there’s one thing you don’t need to ask AI to do, it’s over engineer a solution. I saw this a lot with CSS. Even simple requirements would take longer than expected and result in far more code than needed.

Take something basic like centring a <div> across all screen sizes.

This is a real example from the Benchmark panel in the top right of the FractalAI UI:

AI output

:root {
  --center-x: 50%;
  --center-y: 50%;
  --translate-center: translate(-50%, -50%);
  --container-display: flex;
  --container-align: center;
  --container-justify: center;
}

.container {
  position: relative;
  display: var(--container-display);
  align-items: var(--container-align);
  justify-content: var(--container-justify);
  height: 100vh;
  width: 100%;
}

.container::before {
  content: "";
  position: absolute;
  inset: 0;
  background: radial-gradient(circle, rgba(0,0,0,0.05), transparent);
  pointer-events: none;
}

.centered {
  position: absolute;
  top: var(--center-y);
  left: var(--center-x);
  transform: var(--translate-center);
  display: grid;
  place-items: center;
  padding: calc(1rem + 2px);
  min-width: clamp(200px, 50%, 400px);
  aspect-ratio: 1 / 1;
  backdrop-filter: blur(8px);
  box-shadow:
    0 2px 4px rgba(0,0,0,0.1),
    0 8px 16px rgba(0,0,0,0.15);
}

@supports (height: 100dvh) {
  .container {
    height: 100dvh;
  }
}

@media (min-width: 768px) {
  .centered {
    transform: translate(calc(-50% + 2px), calc(-50% + 2px));
  }
}

Why use one way to centre a <div> when you can use three!

Flexbox (align-items + justify-content)
Absolute positioning (top / left + transform)
Grid (place-items)

Additionally, it threw in CSS variables that were never reused and @supports queries where they were not needed.

I’d expect a developer with a good grasp of modern CSS to write something more like this:

Flexbox (modern)

.container {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100vh;
}

Grid (modern)

.container {
  display: grid;
  place-items: center;
  height: 100vh;
}

Look how much more maintainable and easier to debug the simpler approach is.

This is definitely something to watch for when reviewing or generating AI code.

Confidently wrong outputs

The tricky thing with AI is how convincing it sounds. Even when it's wrong.

I did not see this much in this project, but I ran into it when I worked for Government Digital Service (GDS). I asked Google Gemini for an overview of the changes from WCAG 2.1 to WCAG 2.2. The response sounded accurate, at least from my perspective as someone who understands the basics of accessibility without being an expert.

But when I shared it with our dedicated accessibility team, it did not hold up. It was full of inaccuracies and false claims.

It is a good reminder not to take AI output at face value, especially on topics you are not deeply familiar with.

Inconsistent outputs between prompts

It’s incredible how much difference a single word in a prompt can make to the output. In this example, I asked the AI to write a test for a hypothetical login function in another project I was working on.

Prompt 1

“Write a test for a login function”

AI Output:

test('login works', () => {
  expect(login('user', 'pass')).toBe(true);
});

Prompt 2

“Write a comprehensive test for a login function”

describe('login', () => {
  it('should succeed with correct credentials', () => {
    expect(login('user', 'pass')).toBe(true);
  });

  it('should fail with incorrect password', () => {
    expect(login('user', 'wrong')).toBe(false);
  });

  it('should fail with empty input', () => {
    expect(login('', '')).toBe(false);
  });
});

Just by adding “comprehensive”, the output is vastly different.

This might seem like a negative, and it is something to be aware of, but it links back to the Crafted Prompts section earlier. Prompt 1 lacks detail, and even Prompt 2 is still pretty vague.

Neither is a great example of how to get the best from AI. It just reinforces the need to be clear and specific in what you are asking for.

One extra word. An entirely different level of quality.

For every project, I work on, web performance is a priority. I see it as the foundation of accessibility, regardless of a user’s device, connection, or location.

During this project, I noticed that unless you explicitly ask for it, performance is not a priority in AI-generated code. In some cases, fractals would not render at all.

As an example, I asked Cursor to find unoptimised code in FractalAI. It highlighted this:

For non line based fractals, ProgressiveRenderer increases iterations on each requestAnimationFrame tick and calls fractalModule.render again to recreate the draw command

This is particularly problematic for the Mandelbrot, and other fractals that are shader based. Using regl, which already calls render() on every requestAnimationFrame, this approach creates a new draw command on every frame. That is extremely inefficient for both CPU and memory.

After prompting, the issue was resolved. Thanks to my visual render tests using Playwright, I could confirm that none of the fractals broke during the optimisation. Another win for visual testing!

This is also something I can automate. As mentioned earlier, Cursor’s Rules feature can enforce performance considerations. Writing a rule for this is now high-up on my to-do list.

Forgetting earlier constraints

This is a surprisingly human like trait of AI. As prompt "conversations" go on, it starts to forget earlier constraints. You often have to repeat yourself or restate key requirements it has quietly ignored.

Over time, parts of the project context seem to drift, much like people forgetting details as time passes.

Going back to the sailing analogy in Crafted Prompts, it is as if the AI loses sight of the waypoint “lighthouses” you set earlier.

Elementary mistakes

This happened more often than I expected. For such an advanced tool, the mistakes were surprisingly basic.

I saw this when asking the AI to update outdated npm packages. A simple prompt like:

Update all npm packages in this project, and run the coverage tests to ensure nothing has broken.

In Cursor, you can see what it is “thinking”, and it frequently searched for package versions from 2023 or 2024. It was not using the latest information.

It was only when I explicitly told it the current year was 2026 did it start checking for up-to-date versions!

This is a good reminder to be explicit when you need current information, especially for dependencies, libraries, and documentation.

Performance Challenges in the Browser

When I first planned this side project, I was quite naïve. My initial idea was to build a 3D fractal renderer in the browser using Three.js. It didn’t take long to realise this wasn’t going to be viable. Even on an M1 MacBook, the frame rate was so low it was effectively unusable.

This is where AI proved its value again. By quickly prototyping the idea, it became obvious in the first iteration that 3D rendering wasn’t going to work. That allowed me to pivot early to a 2D approach using an entirely different WebGL library.

Without that early validation, I could easily have spent far longer trying to optimise something that fundamentally isn’t practical right now. There simply isn’t enough available CPU and GPU power in a typical machine to support real-time 3D fractal rendering in the browser at a usable level.

The key thing to understand with fractals is the sheer volume of maths involved in rendering every single pixel. Each pixel can require hundreds, sometimes thousands, of iterations before you get a final value.

So, even at a relatively modest resolution like a 1810px × 1131px image, that is over 2 million pixels to compute for that single image. Multiply that by hundreds or thousands of calculations per pixel, and you quickly see the scale of the problem.

Without highly optimised code, the browser simply does not stand a chance of keeping up. It becomes less about the idea itself and more about the limits of the hardware running it.

Looking ahead, it is hard not to think about how this changes with more advanced GPU capabilities. If compute continues to accelerate, especially with emerging technologies, calculations at this scale could eventually take milliseconds rather than seconds.

As you zoom deeper into a fractal, the cost per pixel increases. To preserve detail and avoid visual artefacts, the renderer needs to run more iterations for each pixel. Beyond a certain point, the amount of computation required makes real-time interaction impractically slow.

There is also a more fundamental limitation around numerical precision. In the browser, JavaScript numbers use IEEE-754 64-bit double precision, which eventually cannot represent the minuscule coordinate differences needed at very high magnifications.

You can push beyond this using higher precision techniques, such as BigInt-based arithmetic or “double-double” approaches, but that additional precision comes at a significant cost. Each pixel becomes even more expensive to compute, which further impacts performance.

What this all really comes down to is simple. Rendering fractals efficiently in the browser is hard.

That being said, it is one of the quickest ways to max out your CPU and GPU, turn your computer into a heater, and simultaneously watch your electricity bill shoot up!

What Building This Changed About My View of AI

When I started this project, I was sceptical about how useful AI could be for coding. I had used tools like ChatGPT and Google Gemini for research, but never properly explored the coding side.

The term “Vibe coding” didn’t help either. If anything, it put me off. After reading Vibe code is legacy code, the last thing I wanted was to introduce more legacy code into a project. I also find the term itself a bit meaningless, especially after it was named word of the year in 2025. It felt like just another buzzword that would disappear as quickly as it arrived.

We have seen this pattern before. Technologies get hyped as “the future” and then quietly fade away. Anyone remember Google Glass from 2013??

Looking at the defintion of "vibe coding":

Vibe coding is an intuitive, fast paced way of writing code where you prioritise momentum and experimentation over upfront planning, often with the help of tools

I’m pleased to say this project has thoroughly changed my perspective on AI in software development. I still dislike the term “vibe coding”, but the practice behind it is undoubtedly what I found most useful and genuinely exciting while building FractalAI.

As mentioned earlier, if you put strong guard rails in place such as mandatory human reviews for all production PRs, along with solid performance and security practices, AI becomes a genuinely valuable tool for learning and rapid prototyping.

That said, I openly admit this is an idealistic view. In reality, there will always be individuals, companies, and bad actors willing to use AI in ways that harm the web for their own gain.

When it comes to new and exciting technology on the web, it often follows the same familiar pattern. A few people find ways to exploit it for their own benefit, usually at the expense of everyone else.

As Paula Poundstone put it best:

This is why we can’t have nice things.

The Future of AI-Generated Software

If there’s one thing I know about AI-generated software, it’s that it’s not going anywhere. The AI sector is projected to reach $539 billion in 2026, up from $391 billion in 2025. That’s a 38% increase in a single year. Longer term, it’s expected to push into the multi-trillion dollar range.

Spending alone tells the story. Global AI investment hit around $1.5 trillion in 2025, and it’s still accelerating. This isn’t hype, it’s momentum.

At the same time, the risks are evolving just as quickly. A new Claude model, Mythos, from Anthropic has reportedly identified a significant number of vulnerabilities across major operating systems. Some experts believe it shows an unprecedented ability to detect and potentially exploit security weaknesses. Whether that is true or is just scaremongering remains to be seen, but it’s telling that major financial institutions have already been given early access to the model ahead of any public release.

As I’ve said, AI is here to stay. The genie is well and truly out of the bottle.

My plan is simple. Learn as much as possible over the coming months and years. This is happening whether we like it or not, so it makes far more sense to understand its potential and how it’s being used than to ignore it.

If you don’t, you can be sure others in your respective field will be. As this goes far beyond software development. AI’s reach is expanding fast, so buckle up.

Summary

This project was an experiment in what happens when you step back from writing code and let AI take the lead. FractalAI is a fully AI-generated fractal renderer running in the browser, built to explore both the potential and the limits of modern AI-assisted development.

Along the way, it became clear that AI is far more than just a code generator. When used properly, it acts as a design partner, a rapid prototyping tool, and a way to accelerate learning. But it's not perfect. It needs direction, context, and clear constraints to produce reliable results.

The browser turned out to be a surprisingly powerful platform for this kind of work, capable of rendering complex, infinite visuals while even supporting lightweight machine learning. Combined with AI, it creates a feedback loop where ideas can be tested, refined, and understood far faster than traditional approaches.

The biggest takeaway is simple. AI is not replacing developers, it is changing how we work. If you use it well, it becomes a tool for thinking, learning, and making better decisions, not just writing code faster.

Well, there we go, yet another blog post where I’ve somehow written far more than intended! If you’ve made it this far, I’m genuinely impressed. Please accept this virtual gold star as a reward: ⭐

As always, feedback and comments are very welcome. You can contact me here.

FractalAI project

Below, you can find the links to the repository and the live site:

I’m completely open and actively encourage raising PR's and sending me feedback / issues about the project (with, or without AI!).

Post changelog:

21/04/26: Initial post published.

Using Cloudflare Workers and reCAPTCHA v3 for a Static Site Contact Form

2026-03-09T00:00:00Z

Introduction

I recently wrote a blog post that involved using a Cloudflare Worker to serve Brotli 11 compressed HTML rather than the standard uncompressed HTML file. Off the back of this post, I’ve decided to write one about my Cloudflare Worker setup that I use for my Contact Page. In order to stop the spam, I also integrated reCAPTCHA v3 into the form functionality. The form is pretty simple, it asks a visitor for their full name, email address and the message they with to send to me. The Worker then pulls together this information and sends an email to a custom email address that points to my personal email address. This allows me to easily filter messages that come from the site, which I then have the option to reply to if I so wish.

It’s worth noting that this post was heavily inspired by Sia Karamalegos’s post from 2024 about migrating from Netlify to Cloudflare. I had the absolute please of meeting Sia in Amsterdam when I spoke at Performance.now() 2023, she was MC for my talk and I really appreciated her support when I was (quite frankly) freaking out with nerves before the talk!

So why use a serverless endpoint for the contact form? Well, as I’ve mentioned many times before, this blog is a static site built using 11ty and hosted on the Pro plan of Cloudflare Pages. There simply is no backend to point the POST method too, which is required to send the email.

Previous solutions I’ve used

This isn’t the first time I’ve changed the way the contact form works on this blog. I’ve counted 5 alternatives that I have used over the years! Isn’t Git great for tracking history! I certainly wouldn’t be able to remember them all with my terrible memory! So, if you aren’t on Cloudflare, or you would rather not use a Worker for this, then there’s a list of perfectly viable alternatives below:

Netlify Forms

URL: Netlify Forms
Cost: Free+ (depending on the Netlify tier you choose)

Netlify Forms is a built-in form handling service for sites hosted on Netlify. It allows you to collect and manage form submissions from static websites without building or maintaining a backend. Submissions can be viewed in the Netlify dashboard or forwarded via email or webhook. I still think it’s a real shame that Cloudflare doesn't offer a form setup that is as easy to integrate and use as Netlify Forms, although, if it did, I wouldn’t need to be writing this blog post!

Cloudflare Pages Functions + MailChannels

URL: https://developers.cloudflare.com/pages/functions/ & https://www.mailchannels.com/
Cost: Free plan available ($10+ depending on volume-based pricing)

When I initially migrated from Netlify to Cloudflare for hosting I used this setup, that was until MailChannels sunset its free email sending service for Cloudflare Workers users (me), at that point I started looking for other solutions. As you will see below.

Formspree.io

URL: https://formspree.io/
Cost: Free tier available ($15+ a month for paid plans)

Formspree is a hosted form service that lets you collect form submissions without building your own backend server. You simply point your form at Formspree, and it handles sending submissions to your email address or other API endpoints, it comes with built-in spam protection and integrations for various workflows.

Formspark.io (previously Submit Form)

URL: https://formspark.io/
Cost: Free tier available ($9+ a month for paid plans)

Formspark is a basic hosted form backend that lets you accept and manage form submissions without the need for your own backend server. You simply submit forms to Formspark, and it stores (or forwards) the data, with options for email notifications, webhooks, and spam filtering.

Botpoison

URL: https://botpoison.com/
Cost: Free plan available ($4+ per month depending on bot verifications required)

Botpoison is an invisible anti-spam and bot prevention service for web forms that blocks automated submissions without requiring CAPTCHAs or extra steps from users. It works by analysing form interactions and applying proof-of-work challenges and reputation checks to distinguish human traffic from bots. I started using it when I was still receiving contact form spam from my Formspark.io setup.

Resend

URL: https://resend.com/
Cost: Free plan available ($20+ for paid plans)

Resend is a developer-focused email delivery service, providing a simple API and Simple Mail Transfer Protocol (SMTP) interface for sending transactional and broadcast emails from your applications or website. It handles features like deliverability, bounce tracking, suppression lists, and email analytics, so a developer doesn't need to manage email infrastructure themselves and can be integrated with many platforms. Resend is currently part of my email workflow, as I will describe later in the post.

Overview of the setup

My current setup is: Cloudflare Pages Functions (the Worker) + Google reCAPTCHA v3 + Resend for email.

A high-level view of this workflow is:

User populates the contact form with their details and message
reCAPTCHA v3 runs and adds a short-lived verification token
The form POSTs to /api/contact (via the Pages Function, that sits in functions/api/contact.js in the root of my repository
The Pages Function, then:
- verifies the token with Google
- validates the user inputs
- sends the validated inputs via email using Resend
Redirects the user to the “Thank You” page, confirming that the message has been sent.

Google reCAPTCHA v3

I have to say, out of all the things written in this post, researching about how exactly Google reCAPTCHA v3 works, was probably the most fascinating! I really love the fact that it is all invisible to the user, and it is based on a complex (but logical) scoring mechanism. There’s no need for a really frustrating visual CAPTCHA’s that don’t prove you are human, “they prove that you are American!” (I can’t take credit for this quote, that I believe goes to Terence Eden, or at least that's who I remember reading it from!)

So how exactly does reCAPTCHA v3 decide if you are a human? Well, it turns out it analyses a user's behavioural and contextual signals rather than setting a user a visual challenge, and based on those signals it creates a risk score. The biggest signal comes from how the user behaves on the page.

Behavioural analysis of a user's session

reCAPTCHA observes a number of patterns and metrics from a user's interaction with the page, these include:

Mouse movement patterns
Typing speed and rhythm
Scroll behaviour
Click timing and placement
Focus changes between fields or tabs

Us humans are a little messy when using a computer. Our mouse movements curve and wander slightly, we pause without thinking, and our typing comes with the occasional hesitation or uneven rhythm.

Skynet, on the other hand, tends to be a little too perfect. Its mouse paths are often straight, timing is predictable, and its interactions can happen far faster than any real person would manage. Those overly neat patterns are often a strong indicator that automation is at work.

Browser and device fingerprinting

Now, when I think of Browser fingerprinting I often associate it with advertising and companies tracking users across the internet. In all fairness, this is Google we are talking about, so it's very likely that they actually do this! :sad_face:. Browser and device fingerprinting is the way the reCAPTCHA script also examines the environment and device information of where the request is coming from.

Typical signals include:

Browser version and capabilities
Installed fonts and plugins
Screen resolution and device properties
WebGL and Canvas fingerprint signals
Cookie availability
JavaScript execution behaviour
Timezone of client
Language settings

You’d be amazed at how accurate these fingerprints can be. Each piece of information adds a little more entropy, meaning it becomes easier to distinguish one device from another. They are so accurate in fact I know many financial sectors or government departments use them for fraud detection.

You really don’t need to look very far to find libraries like Fingerprint that do this all for you! Look at all the information it captured about you just by clicking this link! And you thought cookie tracking was bad!

Note: There are many other fingerprinting libraries available, I’m not specifically targeting Fingerprint.

So while I disagree with browser and device fingerprinting from a privacy and tracking perspective, it does have its uses when it comes to proving that a “user” is a human and not a bot. In particular, bots often run in headless browsers or minimal environments, which look very different from real user devices.

Network and reputation signals

Due to Google’s global network, it can also delve into global reputation data. It captures:

IP reputation and history
Known bot networks or proxy usage
Data centre IP ranges
Previous abuse patterns linked to the IP or session

So much traffic flows through Googles network globally, it can detect suspicious network traffic surprisingly easily.

Action Context

Google can also score the predicted actions a user is going to make. With reCAPTCHA v3, developers call the library with an action name such as:

login
checkout
signup
comment

From its countless trillions of observations over the years, Google already knows the typical login behaviour for a human (it takes approximately 3–10 seconds). Whereas, a bot can submit hundreds of logins per minute, which is a huge red flag for the use of automation.

Scoring using Machine learning

So what does Google do with all these various signals it captures?

It feeds them into a machine learning algorithm for scoring, which will decide if whatever is interacting is a human or a bot.

Score	Meaning
0.9 to 1.0	Very likely human
0.5	Uncertain
0.0 to 0.3	Very likely bot

At this point, it is then up to your backend to decide what to do with the score it gets back. For example:

0.8+  allow request
0.4–0.8 require MFA
<0.4 block or challenge

In my case, the Cloudflare Worker is my simple serverless backend, and it contains the following code to decide if the form submit is from a human or a bot:

// Verify score (reCAPTCHA v3 returns scores between 0.0 and 1.0)
// Lower scores indicate bot-like behavior. 0.5 is a common threshold, but 0.3 allows more legitimate traffic
if (typeof verifyJson.score === "number" && verifyJson.score < 0.3) {
	return new Response(
		JSON.stringify({
			error: "CAPTCHA verification failed",
			details: `Score too low: ${verifyJson.score}`,
		}),
		{ status: 400, headers: { "content-type": "application/json" } },
	);
}

The code above is saying to reject any score that returns from Google that is under 0.3 (Very likely bot), You could of course easily change this threshold if you found it was being too aggressive with the filtering.

Technical setup

To use reCAPTCHA v3, you must first register your site in the Google reCAPTCHA admin console to obtain two keys.

The “site key” is used on the client-side and allows the browser to request a reCAPTCHA verification token for when a user performs an action. The “secret key” must remain server-side and is used to verify that token with Google.

This means storing the secret securely as an environment variable, for my setup this is done via the Cloudflare Pages build dashboard. The Cloudflare Worker then reads it from the environment variables during the build process.

Once all configured, you can also use the Google reCAPTCHA admin console to:

restrict the key to specific hostnames
configure score thresholds to control how strict the bot detection should be

The contact form (HTML and client-side)

The HTML used for the form is all pretty standard, just remember to make it as accessible as possible! Semantic markup is the key to achieving this! If you are unsure how to do this, there’s an excellent post called Creating Accessible Forms on the WebAIM.org website. The HTML for my contact form looks like this:

<!--
  Contact form: POSTs to the Cloudflare Pages Function at /api/contact.
  Uses novalidate so we can run custom client-side validation and show
  accessible error messages before and after submit.
-->
<form id="fs-frm" action="/api/contact" method="POST" aria-labelledby="page-title" novalidate>
    <!--
	  Error summary: shown when validation fails (client or server).
	  role="alert" announces to screen readers when content appears.
	  tabindex="-1" allows focus to be moved here after submit for accessibility.
	  hidden by default; JS removes the attribute to reveal and populate it.
	-->
    <div id="form-error-summary" class="form-error-summary" role="alert" tabindex="-1" hidden></div>
    <!--
	  Live region for status updates (e.g. "Sending…", success message).
	  role="status" is polite; screen readers announce changes without interrupting.
	-->
    <div id="form-status" class="form-status" role="status"></div>
    <!--
	  Honeypot (spam trap): invisible to users, attractive to bots.
	  - Wrapped in a div with a neutral class (e.g. "abc") so bots don’t skip it.
	  - aria-hidden="true" keeps it out of the accessibility tree.
	  - tabindex="-1" and autocomplete="off" reduce chance a human touches it.
	  - Obscure name so bots don’t recognise it as a honeypot; server rejects if set.
	-->
    <div class="abc" aria-hidden="true">
        <input type="checkbox" name="_its-a-trap!" tabindex="-1" autocomplete="off" />
    </div>
    <!-- Server/worker uses these hidden fields for redirect and email behaviour -->
    <input type="hidden" name="_redirect" value="/contact/thanks/" />
    <input type="hidden" name="_append" value="false" />
    <input type="hidden" name="_email.subject" value="New Message from Nooshu.com" />
    <fieldset>
        <!-- Legend is required for fieldset; visually-hidden keeps layout clean -->
        <legend class="visually-hidden">Contact form</legend>
        <div class="form-group">
            <label for="name" class="required">Full Name:</label>
            <input type="text" id="name" name="name" autocomplete="name" required />
            <span id="name-error" class="form-error" hidden></span>
        </div>
        <div class="form-group">
            <label for="email" class="required">Email:</label>
            <input type="email" id="email" name="email" autocomplete="email" placeholder="hello@example.com" required />
            <span id="email-error" class="form-error" hidden></span>
        </div>
        <div class="form-group">
            <label for="message" class="required">Message:</label>
            <textarea rows="7" id="message" name="message" required></textarea>
            <span id="message-error" class="form-error" hidden></span>
        </div>
    </fieldset>
    <!--
	  reCAPTCHA v3 token: client-side JS runs grecaptcha.execute() and sets
	  this value before submit. Server verifies the token with Google before
	  sending the email.
	-->
    <input type="hidden" name="g-recaptcha-response" value="" />
    <button type="submit">Send Message</button>
</form>

A version with fewer comments is available in this gist on GitHub.

The contact form I use above has the following features:

Honeypot and reCAPTCHA to block spam

I’ve already detailed how Google reCAPTCHA works, so I won’t cover it again here, but a Honeypot is a simple first layer of protection. The basic theory behind a Honeypot is a simple form field hidden from real users but still present in the page markup. Bots that scan the source code often fill in every field they find, including this hidden one. If that field is completed, it is a strong signal that the submission came from a bot, not a human because it isn’t seen in the User Interface (UI), thus allowing the request to be rejected immediately.

Client and server validation to ensure safe input

Form validation is handled in two layers:

On the client side, the form uses novalidate with custom JavaScript to check required fields and validate the email format for the name, email, and message inputs.
On the server-side, the API performs its own validation by checking that required fields are present, enforcing max length limits for each field (name: 200 characters, email: 320 characters, message: 5000 characters), and confirming that a valid reCAPTCHA token is included with the submission.

Accessible error handling and focus management

Accessibility is built into the form by clearly associating it with the page title using aria-labelledby, providing an error summary and status regions with role=“alert" plus role=“status", also marking individual fields with aria-invalid and aria-describedby so errors are properly announced.

Inline error messages use matching IDs for assistive technologies, required fields are clearly indicated with a *, and a visually hidden legend describes the <fieldset>. When errors occur, the browser focus moves to the summary using tabindex="-1” so it can be announced immediately by the screen reader.

UX updates to keep the user informed during submission

The form includes the autocomplete attribute for the name and email fields, allowing users browser the option to suggest information already stored in the browser and pre-fill it for them. Additionally, there's a simple placeholder for the email input, letting a user know what input format is expected.

When the form is submitted, the submit button is temporarily disabled and its label changes to “Sending…” while a status message informs the user that their message is being sent. After the submission is successful, the user is then redirected to the /contact/thanks/ page, as seen in the _redirect input field, the API then returns a 303 redirect to complete the process.

Secure server side processing

The form submits a POST request to /api/contact, handled by a Cloudflare function. Hidden fields such as _redirect, _append, and _email.subject control what happens on submit.

On the server, the submission is sent as an email in both HTML and plain text formats before redirecting the user on success. The endpoint only accepts form-encoded or multipart content types. It also verifies the reCAPTCHA token using the CF-Connecting-IP header when available, and validates required fields and length limits, it then escapes HTML in the email body to ensure the content is safe.

I’d like to think this form is pretty accessible and simple to use, but if you disagree, please do let me know. How very meta! It’s always fun to learn something new!

Simplified CSP

The great thing about not having to use a third-party form service for sending contact form emails (besides the slight reduction in cost), is that it simplifies my Content-Security-Policy. This is because I’m no longer having to establish a connection to an additional third-party. The Cloudflare Worker runs on my instance of Cloudflare pages, so it is embedded in the build. And thankfully there’s no client-side interaction when using Resend, as this all happens via the Cloudflare Worker, no modifications to the CSP required! This may not seem like a big thing, but the less you can rely on a third parties the better! There are numerous examples from the history of the web, where the failure of a third party has had a massive impact on the web:

An interesting point about the Wikipedia link above is you can see how prominent these outages have become over the decades, and also the fact that the placeholder category pages for the 2030s, 2040s, 2050s, and 2060s are already listed! Oh well, those outages are for my grandkids to worry about! 👴🏼

The Cloudflare Worker (Pages Function)

So let’s get onto the final piece of the puzzle: the Cloudflare Worker code. This file sits in the root of my blog under functions/api/contact.js, this translates to the action="/api/contact” in the form code above.

// Import a small helper that escapes HTML characters.
// This prevents user-supplied content (like the message body)
// from breaking HTML or injecting markup when we render it in the email.
import { escapeHtml } from "../../_helpers/escape-html.js";

// Cloudflare Pages Functions export HTTP handlers as named exports.
// `onRequestPost` will be invoked for POST requests to this function's route.
//
// Signature:
// - `request`: the incoming HTTP Request object
// - `env`: environment bindings (secrets, KV, etc.), configured in Cloudflare
export const onRequestPost = async ({ request, env }) => {
	try {
		// 1. Accept only standard HTML form submissions
		// ------------------------------------------------
		// We support:
		// - application/x-www-form-urlencoded  (classic HTML <form method="post">)
		// - multipart/form-data                (forms that include files)
		//
		// Anything else (JSON, etc.) is rejected with 415 Unsupported Media Type.
		const contentType = request.headers.get("content-type") || "";
		if (
			!contentType.includes("application/x-www-form-urlencoded") &&
			!contentType.includes("multipart/form-data")
		) {
			return new Response(
				JSON.stringify({ error: "Unsupported content type" }),
				{
					status: 415,
					headers: { "content-type": "application/json" },
				},
			);
		}

		// Parse the incoming form body. Cloudflare's Request object
		// exposes a `.formData()` helper which returns a FormData instance.
		const form = await request.formData();

		// 2. Honeypot anti-spam field
		// ------------------------------------------------
		// A "honeypot" is an extra hidden field that humans never fill in,
		// but bots often do. If this field is present and non-empty,
		// we treat it as spam and quietly redirect away.
		if (form.get("_its-a-trap!")) {
			// Redirect back to the homepage. We build the URL from the current request
			// so it works correctly across environments (preview, production, etc.).
			const hpUrl = new URL("/", request.url);
			return Response.redirect(hpUrl.toString(), 303);
		}

		// 3. Extract and normalize form fields
		// ------------------------------------------------
		// We pull out the core fields we care about:
		// - name
		// - email
		// - message
		// - _redirect (optional; where to send the user after success)
		//
		// Every value is coerced to string and trimmed to avoid
		// issues with null/undefined and accidental leading/trailing spaces.
		const name = (form.get("name") || "").toString().trim();
		const email = (form.get("email") || "").toString().trim();
		const message = (form.get("message") || "").toString().trim();
		const redirectUrl = (
			form.get("_redirect") || "/contact/thanks/"
		).toString();

		// Basic required-field validation. If any are empty,
		// respond with a 400 Bad Request and a JSON error.
		if (!name || !email || !message) {
			return new Response(
				JSON.stringify({ error: "Missing required fields" }),
				{
					status: 400,
					headers: { "content-type": "application/json" },
				},
			);
		}

		// 4. Length limits (simple validation / abuse mitigation)
		// ------------------------------------------------
		// These caps are deliberately generous but help avoid:
		// - unrealistic payloads
		// - abuse where the form is used as a data pipe
		if (name.length > 200 || email.length > 320 || message.length > 5000) {
			return new Response(JSON.stringify({ error: "Invalid field lengths" }), {
				status: 400,
				headers: { "content-type": "application/json" },
			});
		}

		// 5. CAPTCHA verification (reCAPTCHA v3 or hCaptcha-compatible)
		// ------------------------------------------------
		// The form is expected to include a CAPTCHA token:
		// - reCAPTCHA v3: `g-recaptcha-response`
		// - (optionally) hCaptcha-style: `h-captcha-response`
		//
		// If no token is present, we immediately reject the submission.
		const recaptchaToken =
			form.get("g-recaptcha-response") || form.get("h-captcha-response");
		if (!recaptchaToken) {
			return new Response(
				JSON.stringify({ error: "reCAPTCHA token is required" }),
				{
					status: 400,
					headers: { "content-type": "application/json" },
				},
			);
		}

		// Select the secret key from Cloudflare environment variables.
		// This must be configured in the project/environment:
		// - RECAPTCHA_SECRET_KEY or
		// - RECAPTCHA_SECRET
		const secret = env.RECAPTCHA_SECRET_KEY || env.RECAPTCHA_SECRET;
		if (!secret) {
			// If the secret is missing, that's a server misconfiguration,
			// so we return a 500 Internal Server Error.
			return new Response(
				JSON.stringify({
					error:
						"Server not configured for CAPTCHA (missing RECAPTCHA_SECRET_KEY/RECAPTCHA_SECRET)",
				}),
				{ status: 500, headers: { "content-type": "application/json" } },
			);
		}

		// For better fraud detection, we also send the user's IP to reCAPTCHA.
		// Cloudflare exposes client IP via:
		// - CF-Connecting-IP header
		// - request.cf.clientAddress
		const remoteIp =
			request.headers.get("CF-Connecting-IP") ||
			request.cf?.clientAddress ||
			null;

		// Build the request body for the reCAPTCHA verification endpoint.
		// It expects application/x-www-form-urlencoded payload.
		const verifyParams = new URLSearchParams({
			secret,
			response: recaptchaToken.toString(),
		});
		if (remoteIp) {
			verifyParams.append("remoteip", remoteIp);
		}

		// POST the verification request to Google's reCAPTCHA API.
		const verifyResp = await fetch(
			"https://www.google.com/recaptcha/api/siteverify",
			{
				method: "POST",
				headers: { "content-type": "application/x-www-form-urlencoded" },
				body: verifyParams,
			},
		);

		// If Google's endpoint itself is failing (network issue or 5xx),
		// treat this as a bad gateway (502) and surface a generic error.
		if (!verifyResp.ok) {
			return new Response(
				JSON.stringify({ error: "Failed to verify reCAPTCHA" }),
				{
					status: 502,
					headers: { "content-type": "application/json" },
				},
			);
		}

		// Parse the JSON response from reCAPTCHA.
		// Example structure:
		// {
		//   success: true/false,
		//   score: 0.0-1.0,
		//   hostname: "example.com",
		//   "error-codes": [...]
		// }
		const verifyJson = await verifyResp.json();

		// 5a. Hard failure: verification not successful at all
		// ------------------------------------------------
		// We return a 400 with details about why it failed where possible.
		if (!verifyJson.success) {
			const errorCodes = verifyJson["error-codes"] || [];
			return new Response(
				JSON.stringify({
					error: "CAPTCHA verification failed",
					details:
						errorCodes.length > 0 ? errorCodes.join(", ") : "Unknown error",
				}),
				{ status: 400, headers: { "content-type": "application/json" } },
			);
		}

		// 5b. Soft failure: low reCAPTCHA v3 score
		// ------------------------------------------------
		// reCAPTCHA v3 uses scores instead of explicit "I'm not a robot" prompts.
		// Lower values are more suspicious. Here we reject anything below 0.3.
		// This threshold is a trade-off between blocking bots and not annoying users.
		if (typeof verifyJson.score === "number" && verifyJson.score < 0.3) {
			return new Response(
				JSON.stringify({
					error: "CAPTCHA verification failed",
					details: `Score too low: ${verifyJson.score}`,
				}),
				{ status: 400, headers: { "content-type": "application/json" } },
			);
		}

		// 5c. Optional hostname verification
		// ------------------------------------------------
		// The reCAPTCHA response includes a `hostname` field.
		// We check that the hostname reCAPTCHA saw matches the hostname of our request.
		// This helps prevent token reuse on other domains.
		const requestHost = new URL(request.url).hostname;
		if (
			verifyJson.hostname &&
			verifyJson.hostname !== requestHost &&
			!requestHost.endsWith(`.${verifyJson.hostname}`)
		) {
			// We allow subdomains (e.g. www.example.com vs example.com),
			// but log any unexpected mismatch to server logs for later inspection.
			// This log will show up in Cloudflare function logs.
			console.warn(
				`reCAPTCHA hostname mismatch: expected ${requestHost}, got ${verifyJson.hostname}`,
			);
		}

		// 6. Prepare email content for Resend
		// ------------------------------------------------
		// At this point, the submission has passed:
		// - basic validation
		// - anti-spam honeypot
		// - CAPTCHA checks
		//
		// Now we build an email to send to the site owner via Resend.

		// Fixed "from" address used with Resend.
		// This should be a verified sender domain for your Resend account.
		const fromEmail = "contact@example.com";

		// Allow the subject to be overridden via a hidden form field `_email.subject`,
		// otherwise fall back to a sensible default.
		const subject =
			form.get("_email.subject")?.toString() || "New Message from Nooshu.com";

		// Plain-text body, which is useful for mail clients that don't render HTML, note the use of JavaScript Template literals.
		const textBody = `New contact form submission on nooshu.com

Name: ${name}
Email: ${email}

Message:
${message}`;

		// HTML body with simple markup for better readability.
		// We escape all user-supplied fields to avoid injecting HTML or scripts.
		const htmlBody = `<h2>New contact form submission on nooshu.com</h2><p><strong>Name:</strong> ${escapeHtml(
			name,
		)}<br/><strong>Email:</strong> ${escapeHtml(email)}</p><p><strong>Message:</strong></p><pre style="white-space:pre-wrap">${escapeHtml(
			message,
		)}</pre>`;

		// Pull the Resend API key from Cloudflare environment variables.
		// This must be configured as a secret in the Pages project.
		const apiKey = env.RESEND_API_KEY;
		if (!apiKey) {
			return new Response(
				JSON.stringify({
					error: "Server not configured for email (missing RESEND_API_KEY)",
				}),
				{ status: 500, headers: { "content-type": "application/json" } },
			);
		}

		// 7. Call Resend's email API
		// ------------------------------------------------
		// We issue a POST request to Resend's /emails endpoint with:
		// - from: sender (must be a verified domain)
		// - to: recipient(s) (in this case, the site inbox)
		// - reply_to: the visitor's email address, so "Reply" in your mail client goes to them
		// - subject, text, html: the message content
		const resendResp = await fetch("https://api.resend.com/emails", {
			method: "POST",
			headers: {
				"content-type": "application/json",
				Authorization: `Bearer ${apiKey}`,
			},
			body: JSON.stringify({
				from: `Nooshu Contact <${fromEmail}>`,
				to: ["email@example.com"],
				reply_to: email,
				subject,
				text: textBody,
				html: htmlBody,
			}),
		});

		// If Resend returns a non-2xx status, we surface a 502 to the client
		// and include the raw error body for easier debugging.
		if (!resendResp.ok) {
			const text = await resendResp.text();
			return new Response(
				JSON.stringify({ error: "Email send failed", details: text }),
				{
					status: 502,
					headers: { "content-type": "application/json" },
				},
			);
		}

		// 8. Final redirect on success
		// ------------------------------------------------
		// If everything above succeeds, we redirect the user to a "thank you"
		// page (configurable via the `_redirect` field).
		//
		// We resolve `redirectUrl` relative to the current request URL
		// to avoid hard-coding the origin.
		const finalRedirect = new URL(redirectUrl, request.url);

		// 303 See Other is the canonical way to redirect after a POST,
		// telling the browser to perform a GET to the new URL.
		return Response.redirect(finalRedirect.toString(), 303);
	} catch (err) {
		// 9. Global error handler
		// ------------------------------------------------
		// If anything unexpected blows up (network issues, runtime errors, etc.),
		// we catch it here and return a generic 500 JSON response.
		//
		// The error is stringified so it's at least inspectable in logs / responses,
		// but in a real-world scenario you might want to avoid leaking details
		// to the client and instead only log them server-side.
		return new Response(
			JSON.stringify({ error: "Server error", details: String(err) }),
			{
				status: 500,
				headers: { "content-type": "application/json" },
			},
		);
	}
};

A version with fewer comments is available in this gist on GitHub.

Using Cloudflare Turnstile

After I posted the blog post on Bluesky, Mastodon, and LinkedIn, I had a couple of replies back asking me why I hadn't used Cloudflare's CAPTCHA integration rather than Google's ReCAPTCHA v3. In all honesty I didn't realise Cloudflare had a competing product! So, thanks to Ryan Townsend and Paweł Grzybek for letting me know!

I'm not going to be rewriting the whole blog post, but what I will do is share the client-side JavaScript code (turnstile.js), and the contact.js file for the API that I am using to integrate with Cloudflare Turnstile. Also, any additional changes I had to make.

First the Code:

// Lightweight, dependency-free integration for Cloudflare Turnstile.
// This script:
// - Validates the contact form on the client (for UX only – server still re-validates).
// - Requests an invisible Turnstile token just before submit.
// - Injects the token into a hidden field for the server to verify.
// - Tries hard not to block the user if Turnstile is slow to load.
(function () {
  // Public Turnstile site key for this widget. This is *not* a secret.
  // The matching secret key lives on the server and is used during
  // server-side verification in the Cloudflare Pages Function.
  const SITE_KEY = "0x4AAAAAACpYvR2v9J0i1tr_";

  // The contact form we progressively enhance. If it does not exist
  // (for example, on other pages), bail out early.
  const form = document.getElementById("fs-frm");
  if (!form) return;

  // ---------------------------------------------------------------------------
  // Hidden token field management
  // ---------------------------------------------------------------------------
  // Turnstile posts its token back to the server in a field that we choose.
  // The backend expects this exact name when validating the submission.
  const tokenInputName = "cf-turnstile-response";
  let tokenInput = form.querySelector(`input[name="${tokenInputName}"]`);
  if (!tokenInput) {
    // If the hidden field was not rendered server-side, create it here.
    tokenInput = document.createElement("input");
    tokenInput.type = "hidden";
    tokenInput.name = tokenInputName;
    form.appendChild(tokenInput);
  }

  // ---------------------------------------------------------------------------
  // Accessible error + status UI helpers
  // ---------------------------------------------------------------------------
  const errorSummary = document.getElementById("form-error-summary");
  const formStatus = document.getElementById("form-status");

  // Show a high-level error message above the form and move focus there so
  // screen-reader users (and keyboard users) are notified.
  function showFormError(message) {
    if (errorSummary) {
      errorSummary.textContent = message;
      errorSummary.hidden = false;
      errorSummary.focus();
    }
  }

  // Hide and clear the error summary.
  function clearFormError() {
    if (errorSummary) {
      errorSummary.textContent = "";
      errorSummary.hidden = true;
    }
  }

  // Attach error state to a single field (ARIA attributes + inline message).
  function showFieldError(fieldId, message) {
    const field = document.getElementById(fieldId);
    const errorEl = document.getElementById(fieldId + "-error");
    if (field) {
      field.setAttribute("aria-invalid", "true");
      field.setAttribute("aria-describedby", fieldId + "-error");
    }
    if (errorEl) {
      errorEl.textContent = message;
      errorEl.hidden = false;
    }
  }

  // Clear error state from a single field.
  function clearFieldError(fieldId) {
    const field = document.getElementById(fieldId);
    const errorEl = document.getElementById(fieldId + "-error");
    if (field) {
      field.removeAttribute("aria-invalid");
      field.removeAttribute("aria-describedby");
    }
    if (errorEl) {
      errorEl.textContent = "";
      errorEl.hidden = true;
    }
  }

  // Clear all per-field and summary errors.
  function clearAllErrors() {
    clearFormError();
    ["name", "email", "message"].forEach(clearFieldError);
  }

  // Set a small, live-updating status message (polite ARIA live region).
  function setStatus(message) {
    if (formStatus) {
      formStatus.textContent = message;
    }
  }

  // ---------------------------------------------------------------------------
  // Client-side validation
  // ---------------------------------------------------------------------------
  // This mirrors the server’s validation rules, but is *only* for UX.
  // The server still validates everything again.
  function validateForm() {
    clearAllErrors();
    const errors = [];
    const nameField = form.querySelector("#name");
    const emailField = form.querySelector("#email");
    const messageField = form.querySelector("#message");

    if (!nameField.value.trim()) {
      showFieldError("name", "Please enter your full name.");
      errors.push(nameField);
    }

    if (!emailField.value.trim()) {
      showFieldError("email", "Please enter your email address.");
      errors.push(emailField);
    } else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(emailField.value.trim())) {
      showFieldError("email", "Please enter a valid email address.");
      errors.push(emailField);
    }

    if (!messageField.value.trim()) {
      showFieldError("message", "Please enter a message.");
      errors.push(messageField);
    }

    if (errors.length > 0) {
      const summary =
        errors.length === 1
          ? "There is 1 error in the form."
          : "There are " + errors.length + " errors in the form.";
      showFormError(summary);
      errors[0].focus();
      return false;
    }

    return true;
  }

  // ---------------------------------------------------------------------------
  // Turnstile widget lifecycle
  // ---------------------------------------------------------------------------
  // `widgetId` is the handle returned by turnstile.render.
  // `pendingSubmit` tracks whether we should submit once a token arrives.
  // `submitButton` lets us disable / re-enable the call-to-action button.
  let widgetId = null;
  let pendingSubmit = false;
  let submitButton = null;

  // Called by Turnstile when a token is successfully generated.
  function onTokenReceived(token) {
    tokenInput.value = token;
    // If the user was waiting for the challenge to finish, we can now submit.
    if (pendingSubmit) {
      pendingSubmit = false;
      form.submit();
    }
  }

  // Called when Turnstile hits an error or we decide the widget is unavailable.
  function onTokenError(errorCode) {
    tokenInput.value = "";
    pendingSubmit = false;
    setStatus("");
    console.error("Turnstile error:", errorCode);
    showFormError(
      "Verification failed. Please try again. If you use an ad blocker, you may need to allow Cloudflare on this site."
    );
    if (submitButton) {
      submitButton.disabled = false;
      submitButton.textContent = "Send Message";
    }
    // If we have a widget instance, reset it so the user can try again.
    if (widgetId !== null && typeof turnstile !== "undefined") {
      turnstile.reset(widgetId);
    }
  }

  // Render an invisible Turnstile widget into the placeholder div.
  // The widget itself is not visible – it will run when we call execute().
  function renderTurnstile() {
    const container = document.getElementById("turnstile-container");
    // Only render once, and only on the contact page where the container exists.
    if (!container || widgetId !== null) return;

    if (typeof turnstile !== "undefined") {
      widgetId = turnstile.render(container, {
        sitekey: SITE_KEY,
        // Invisible mode: no explicit checkbox; Cloudflare decides when
        // to prompt for a challenge, if at all.
        size: "invisible",
        // We want full control, so we manually call turnstile.execute(widgetId).
        execution: "execute",
        callback: onTokenReceived,
        "error-callback": onTokenError,
        "expired-callback": function () {
          // Expired tokens are treated as missing; the server will reject them.
          tokenInput.value = "";
        },
      });
    }
  }

  // Wait until the Turnstile script has loaded and the global `turnstile`
  // object is available. We poll for a short period so that a slow network
  // does not permanently block the user.
  function waitForTurnstile() {
    return new Promise((resolve) => {
      if (typeof turnstile !== "undefined") {
        resolve();
        return;
      }
      let attempts = 0;
      const checkInterval = setInterval(() => {
        attempts++;
        if (typeof turnstile !== "undefined") {
          clearInterval(checkInterval);
          resolve();
        } else if (attempts > 100) {
          // Give up after ~10s. At this point we will try to submit
          // without a token and let the server return a clear error.
          clearInterval(checkInterval);
          resolve();
        }
      }, 100);
    });
  }

  // As soon as the page is ready and Turnstile is (hopefully) loaded,
  // render the widget so it is ready by the time the user hits submit.
  waitForTurnstile().then(() => {
    renderTurnstile();
  });

  // ---------------------------------------------------------------------------
  // Submit flow
  // ---------------------------------------------------------------------------
  form.addEventListener("submit", async function (e) {
    // We always take over submission so we can validate + get a token first.
    e.preventDefault();

    if (!validateForm()) return;

    submitButton = form.querySelector('button[type="submit"]');
    if (submitButton) {
      submitButton.disabled = true;
      submitButton.textContent = "Sending…";
    }
    setStatus("Verifying, please wait.");

    // Make sure the Turnstile library has had a chance to load.
    await waitForTurnstile();

    // If we still do not have a widget, try to render one and give the
    // browser a short moment to paint it.
    if (widgetId === null) {
      renderTurnstile();
      await new Promise((resolve) => setTimeout(resolve, 100));
    }

    // If for some reason we already have a valid token (for example,
    // Turnstile auto-ran earlier), we can just submit the form.
    if (tokenInput.value) {
      form.submit();
      return;
    }

    // Normal path: ask Turnstile to run in invisible mode. When it finishes,
    // it will call onTokenReceived, which will submit the form if
    // `pendingSubmit` is true.
    if (widgetId !== null && typeof turnstile !== "undefined") {
      pendingSubmit = true;
      turnstile.execute(widgetId);
    } else {
      // We could not talk to Turnstile at all – surface a clear error.
      console.error("Turnstile widget not available");
      onTokenError("widget-not-available");
    }
  });
})();

A version with fewer comments is available in this gist on GitHub.

Now the updates to the contact.js file that sits in functions/api/ directory.

import { escapeHtml } from '../../_helpers/escape-html.js';

/**
 * Cloudflare Pages Function that powers the contact form.
 *
 * High‑level flow (perfect for a blog diagram):
 *
 * 1. Accept a classic `<form>` POST (urlencoded or multipart).
 * 2. Validate the payload on the server (required fields + length limits).
 * 3. Verify a Cloudflare Turnstile token server‑side.
 * 4. Send a notification email via Resend (HTTPS API call).
 * 5. Redirect the user to a static “thanks” page.
 *
 * The matching HTML form does *not* need JavaScript – the worker stands on its
 * own. Client‑side JS (for validation + Turnstile widget) is purely a UX bonus.
 */
export const onRequestPost = async ({ request, env }) => {
	try {
		// ---------------------------------------------------------------------
		// 1. Only accept traditional browser form submissions
		// ---------------------------------------------------------------------
		// The contact page posts using `application/x-www-form-urlencoded`, but
		// we also support `multipart/form-data` so the handler works with
		// progressive enhancement and file inputs if they ever appear.
		const contentType = request.headers.get('content-type') || '';
		if (!contentType.includes('application/x-www-form-urlencoded') && !contentType.includes('multipart/form-data')) {
			return new Response(JSON.stringify({ error: 'Unsupported content type' }), {
				status: 415,
				headers: { 'content-type': 'application/json' },
			});
		}

		// This gives us a `FormData` instance regardless of which of the two
		// encodings the browser chose.
		const form = await request.formData();

		// ---------------------------------------------------------------------
		// 2. Honeypot – cheap, early bot filter
		// ---------------------------------------------------------------------
		// The form includes a visually hidden checkbox with this wonderfully
		// ugly name. Real users never see or tick it, but naive bots often
		// will. If it has a value, we quietly redirect back to the homepage.
		if (form.get('_its-a-trap!')) {
			const hpUrl = new URL('/', request.url);
			return Response.redirect(hpUrl.toString(), 303);
		}

		const name = (form.get('name') || '').toString().trim();
		const email = (form.get('email') || '').toString().trim();
		const message = (form.get('message') || '').toString().trim();
		const redirectUrl = (form.get('_redirect') || '/contact/thanks/').toString();

		// ---------------------------------------------------------------------
		// 3. Field‑level validation (server‑side, regardless of JS on client)
		// ---------------------------------------------------------------------
		if (!name || !email || !message) {
			return new Response(JSON.stringify({ error: 'Missing required fields' }), {
				status: 400,
				headers: { 'content-type': 'application/json' },
			});
		}

		// Upper bounds on field length keep logs and emails sane and protect
		// downstream services from unexpectedly huge payloads.
		if (name.length > 200 || email.length > 320 || message.length > 5000) {
			return new Response(JSON.stringify({ error: 'Invalid field lengths' }), {
				status: 400,
				headers: { 'content-type': 'application/json' },
			});
		}

		// ---------------------------------------------------------------------
		// 4. Verify Cloudflare Turnstile token (server‑side)
		// ---------------------------------------------------------------------
		// The front‑end Turnstile widget places its token into
		// `cf-turnstile-response`. Without a token, we *always* reject the
		// submission – even if the rest of the payload looks valid.
		const turnstileToken = form.get('cf-turnstile-response');
		if (!turnstileToken) {
			return new Response(JSON.stringify({ error: 'Turnstile token is required' }), {
				status: 400,
				headers: { 'content-type': 'application/json' },
			});
		}

		// The Turnstile secret is never exposed to the client – it lives in
		// Cloudflare Pages environment variables.
		const secret = env.TURNSTILE_SECRET_KEY;
		if (!secret) {
			return new Response(
				JSON.stringify({
					error: 'Server not configured for CAPTCHA (missing TURNSTILE_SECRET_KEY)',
				}),
				{ status: 500, headers: { 'content-type': 'application/json' } }
			);
		}

		// Including the remote IP is optional but recommended; it gives
		// Turnstile a little more context when scoring the request.
		const remoteIp = request.headers.get('CF-Connecting-IP') || request.cf?.clientAddress || null;

		const verifyBody = {
			secret,
			response: turnstileToken.toString(),
		};
		if (remoteIp) {
			verifyBody.remoteip = remoteIp;
		}

		const verifyResp = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
			method: 'POST',
			headers: { 'content-type': 'application/json' },
			body: JSON.stringify(verifyBody),
		});

		if (!verifyResp.ok) {
			return new Response(JSON.stringify({ error: 'Failed to verify Turnstile' }), {
				status: 502,
				headers: { 'content-type': 'application/json' },
			});
		}

		const verifyJson = await verifyResp.json();

		// If Turnstile says “no”, do not send an email – fail fast here.
		if (!verifyJson.success) {
			const errorCodes = verifyJson['error-codes'] || [];
			return new Response(
				JSON.stringify({
					error: 'CAPTCHA verification failed',
					details: errorCodes.length > 0 ? errorCodes.join(', ') : 'Unknown error',
				}),
				{ status: 400, headers: { 'content-type': 'application/json' } }
			);
		}

		// Optional defence‑in‑depth check: ensure the token we received was
		// minted for this hostname (or one of its subdomains).
		const requestHost = new URL(request.url).hostname;
		if (
			verifyJson.hostname &&
			verifyJson.hostname !== requestHost &&
			!requestHost.endsWith(`.${verifyJson.hostname}`)
		) {
			console.warn(`Turnstile hostname mismatch: expected ${requestHost}, got ${verifyJson.hostname}`);
		}

		// ---------------------------------------------------------------------
		// 5. Build notification email payload for Resend
		// ---------------------------------------------------------------------
		// `fromEmail` must be a sender you control and have verified with Resend.
		const fromEmail = 'email@example.com';
		const subject = form.get('_email.subject')?.toString() || 'New Message from Nooshu.com';

		const textBody = `New contact form submission on nooshu.com\n\nName: ${name}\nEmail: ${email}\n\nMessage:\n${message}`;
		const htmlBody = `<h2>New contact form submission on nooshu.com</h2><p><strong>Name:</strong> ${escapeHtml(name)}<br/><strong>Email:</strong> ${escapeHtml(email)}</p><p><strong>Message:</strong></p><pre style="white-space:pre-wrap">${escapeHtml(message)}</pre>`;

		// Resend API key comes from Cloudflare Pages environment variables,
		// never from the client or build‑time `.env`.
		const apiKey = env.RESEND_API_KEY;
		if (!apiKey) {
			return new Response(
				JSON.stringify({
					error: 'Server not configured for email (missing RESEND_API_KEY)',
				}),
				{ status: 500, headers: { 'content-type': 'application/json' } }
			);
		}

		// Call the Resend REST API. In this project we make a single,
		// straightforward `emails` call – no templates, CC/BCC, or attachments.
		const resendResp = await fetch('https://api.resend.com/emails', {
			method: 'POST',
			headers: {
				'content-type': 'application/json',
				Authorization: `Bearer ${apiKey}`,
			},
			body: JSON.stringify({
				from: `Nooshu Contact <${fromEmail}>`,
				to: ['email@example.com'],
				reply_to: email,
				subject,
				text: textBody,
				html: htmlBody,
			}),
		});

		if (!resendResp.ok) {
			const text = await resendResp.text();
			return new Response(JSON.stringify({ error: 'Email send failed', details: text }), {
				status: 502,
				headers: { 'content-type': 'application/json' },
			});
		}

		// ---------------------------------------------------------------------
		// 6. Redirect to “thanks” page
		// ---------------------------------------------------------------------
		// Using a 303 ensures the follow‑up request is a GET, which means
		// browser refreshes do not re‑POST the form.
		const finalRedirect = new URL(redirectUrl, request.url);
		return Response.redirect(finalRedirect.toString(), 303);
	} catch (err) {
		return new Response(JSON.stringify({ error: 'Server error', details: String(err) }), {
			status: 500,
			headers: { 'content-type': 'application/json' },
		});
	}
};

A version with fewer comments is available in this gist on GitHub.

Amazingly, that's really the only two major changes!

The minor changes were:

Footer template: Update my footer with a link to the JavaScript above and the Turnstile JavaScript, e.g. https://challenges.cloudflare.com/turnstile/v0/api.js.
CSP: Modified my _headers file to remove Google from my CSP and add in the challenges URL (https://challenges.cloudflare.com/) to the connect-src, script-src-elem, and frame-src.
CSS: Slightly modify the CSS to remove Google ReCAPTCHA v3 specific styling (.grecaptcha-badge) and add Turnstile CSS (.turnstile-widget).
Secret Keys: RECAPTCHA_SECRET_KEY swapped out for the TURNSTILE_SECRET_KEY in the Cloudflare Pages environment variables settings page.
Contact Form HTML: HTML changes to the contact form added cf-turnstile-response hidden <input> and #turnstile-container <div>.

Why change?

So I've literally done a 180 from Google ReCAPTCHA v3 to Cloudflare Turnstile in less than a week. So why change and what are the differences? The top of my priority list that I admittedly should have considered when integrating Google ReCAPTCHA v3 is privacy! I would rather not subject any readers of the blog to any additional tracking from Google! But there are other differences too:

Area	Cloudflare Turnstile advantage over reCAPTCHA v3	Why it matters
Privacy	Turnstile is positioned as a privacy preserving alternative, and it does not rely on tracking user data across sites for ad retargeting. It also offers Ephemeral IDs, which are short-lived device identifiers that work without cookies or client-side storage.	Better fit for teams with strong privacy, GDPR, or public sector concerns.
Less operational tuning	Turnstile’s server validation is a straightforward success or failure check. By contrast, reCAPTCHA v3 returns a score and Google recommends that you review scores in the admin console and tune thresholds based on your own traffic, starting from 0.5.	Usually simpler to ship and maintain, especially for smaller teams that do not want to spend time calibrating fraud thresholds.
No CAPTCHA experience by default	Turnstile works without showing visitors a CAPTCHA and supports invisible, non-interactive, and managed modes. reCAPTCHA v3 is also frictionless, but Turnstile is explicitly built as a CAPTCHA replacement with more presentation modes for the widget itself.	More control over UX and easier to keep forms feeling clean while still validating traffic.
Can be used on any site without Cloudflare CDN	Turnstile can be embedded into any website, it does not require your traffic to go through Cloudflare or use Cloudflare’s CDN.	Easier adoption if you want the bot check without changing your hosting or edge setup.
Developer-friendly testing	Turnstile provides dummy site keys and secret keys for testing, and Cloudflare documents that these work on localhost and any development domain. Google’s reCAPTCHA FAQ says for v3 you should create a separate key for testing environments, and scores may not be accurate because v3 relies on real traffic.	Usually a smoother local dev and automated test setup.
Free plan positioning	Cloudflare documents Turnstile has a Free plan intended for personal sites, SMBs, dev and test, and most production applications. Google’s FAQ notes quota limits for non-Enterprise reCAPTCHA, and if a v3 key exceeds a monthly quota it may fail open with a static score of 0.9 for the remainder of the month.	Attractive when cost certainty matters or when you want fewer surprises as usage grows.
Extra integration option with Cloudflare security stack	Turnstile supports pre-clearance, letting it issue clearance cookies that can be used across Cloudflare protected domains.	Helpful if you already use Cloudflare WAF or bot controls and want tighter integration.

Summary

Well, that brings us to the end of another blog post, I only went off on a tangent a couple of times! So well done for sticking with my ramblings!

In the end, the goal was to keep the architecture simple while still covering the essentials. The site itself remains fully static, with a lightweight Cloudflare Worker handling form submissions. Spam protection is provided through ~~Google reCAPTCHA v3~~, Cloudflare Turnstile, while validation and accessibility patterns ensure the form behaves reliably for real users. It is a small piece of functionality, but implemented carefully it can be both robust and easy to maintain.

As always, thanks for reading, and I’d love to hear your feedback. You are welcome to contact me either via the contact form (again, very meta! 😏), or via any of the various social channels listed on the site.

Post changelog:

09/03/26: Initial post published.
13/03/26: Updates to give instructions on how to use Cloudflare Turnstile as an alternative to Google reCAPTCHA v3. Thanks again to Ryan Townsend and Paweł Grzybek.

Precompressed HTML at the Edge: Eleventy Meets Cloudflare Workers

2026-02-21T00:00:00Z

Introduction

In 2025, I wrote a series of web performance optimisation blog posts focussing on some of the key fundamental's of Frontend Web Performance:

Caching

Asset fingerprinting and the preload response header in 11ty

Summary

The blog post describes how the I enhanced web performance on my 11ty-built site by combining asset fingerprinting with the HTTP preload hint.

It explains that preload tells the browser to fetch critical resources earlier, but hashed filenames make this difficult to manage manually.

The solution was to generate preload Link headers automatically during the 11ty build. A custom script locates the fingerprinted CSS file and injects the correct preload header into the Cloudflare Pages _headers file.

This speeds up CSS delivery, removes the need for manual updates, and allows the use of long-lived Cache-Control header values such as max-age=31536000 and immutable.

Compression

Cranking Brotli up to 11 with Cloudflare Pro and 11ty.

Summary

The blog post explains how I improved the performance of my 11ty-powered blog after migrating to Cloudflare Pages by using Brotli compression at the highest level (11) for static assets. I also describes the difference between Brotli and gzip, outline how Cloudflare’s Pro plan typically applies a moderate Brotli level (4), and then show how to pre-compress JavaScript files to Brotli level 11. Lastly, serve them correctly both locally and via Cloudflare, and configure Cloudflare’s compression rules so that all assets benefit from the stronger compression to reduce file sizes and improve load performance.

Concatenation

Using an 11ty Shortcode to craft a custom CSS pipeline

Summary

While not strictly about concatenation, it covers related ideas. The post explains how I built a custom CSS pipeline for my 11ty site using a bespoke short code rather than the default bundle plugin.

It details how I preserved local live reload, added content-based fingerprinting for long-term caching, minified CSS with clean-css package, enabled Brotli compression, and used disk and memory caching to prevent unnecessary work.

The build also generates hashed filenames and matching HTML link tags, ensuring production serves fully optimised, cache friendly CSS automatically.

More compression

In this blog post, I’m going to take the compression a little further. I already have CSS and JavaScript Brotli compressed to the highest level (11) and served from Cloudflare Pages. But what about the third and final core technology of the web? Arguably the most important too… The HTML. In this post, I will look at how to compress your HTML to 11 during the 11ty build phase, and what modern technologies you need in order to make this work (it’s not as straightforward as I thought!)

Why HTML Brotli matters?

Before we dive into the details, let’s discuss why Brotli compression is important for HTML. Well, to summarise Brotli compression in one sentence:

Brotli compression reduces file size by intelligently identifying repeated patterns in data and encoding them more efficiently using a combination of modern compression techniques.

This is fantastic for anything with repeating patterns as the bytes saved over the network can be huge! The great thing about HTML is that it has a tonne of repeating patterns (e.g. Markup)! This reduction in file size could potentially equate to:

Improved Web Performance

Lower Time To First Byte impact on slow networks
Improved First Contentful Paint
Improved Largest Contentful Paint
Reduced Total Blocking Time (indirectly)

Every kilobyte saved here multiplies across your traffic volume.

At scale, cost savings add up

Let’s assume you are serving a high traffic website, say the BBC, Google, or GOV.UK. Imagine how much bandwidth could be saved by simply compressing your HTML. Any percentage saving on millions of requests per day is going to mean:

Less bandwidth
Lower CDN egress
Lower cloud costs
Lower carbon footprint

This is a win both commercially and environmentally!

Improved performance on slow and unstable mobile networks

Brotli 11 improves the web for users where they need it the most:

3G connectivity
High latency rural connections
Congested public networks
International access

HTML blocks everything else. If you shrink it aggressively, you unblock the page faster, meaning users get a better experience.

This is a real-world performance gain.

It indirectly improves Core Web Vitals

Smaller HTML means:

Faster DOM construction
Earlier CSS discovery
Earlier JS discovery
Reduced main thread idle gaps

This is especially important for server rendered pages or hybrid Server-side Rendered apps.

Compression cost is paid once for static assets

Yes, level 11 compression is expensive to compute. But this cost is paid back over time. You pay for the CPU time once. Users benefit forever assuming:

the HTML is static and cacheable at the Content Delivery Network (CDN) using long-life caching headers
you automate and pre-compress the HTML at build time

Compression Size Examples v1

Let’s have a look at a huge HTML page on the web. My go-to for this is either the W3C HTML5 Specification page OR NASA’s Astronomy Picture of the Day Archive.

Rather than choose, let’s just compress both!

W3C HTML5 Specification (Single Page)

URL: https://www.w3.org/TR/2011/WD-html5-20110405/Overview.html
Uncompressed size: 4.7 MB
Brotli (Level 11): 590 KB (~88% saving)

That’s an 88 percent reduction in bytes over the network when compressing the HTML with Brotli 11. Not bad for something that takes just over 10-seconds to run.

And yes, that’s 4.7 MB of HTML alone. It’s an absolute beast of a page.

For perspective, that would take around 12 to 15 minutes to download on a 56k modem in the late 90s. Just for the HTML. I might be showing my age here 😭

Nasa’s Astronomy Picture of the Day Archive

URL: https://apod.nasa.gov/apod/archivepix.html
Uncompressed size: 314 KB
Brotli (Level 11): 53 KB (83% saving)

We’ve taken it from roughly a third of a megabyte down to just 53 KB. That is a pretty substantial reduction!

This means faster page loads, lower data usage, and a much smoother experience for anyone on a limited data plan or dealing with patchy connections. A very positive impact, right where it matters most for users.

How is this different from my other compression posts?

So how is this different from the Brotli compression I have mentioned in the previous blog posts?

In Cranking Brotli up to 11 with Cloudflare Pro and 11ty I used a combination of:

Brotli CLI (e.g.brew install brotli)
bash scripts (compress.sh, compress-directory.sh)

In this post, I override the Cloudflare Dashboard's "Compression Rules” (which dynamically compresses HTML at Brotli level 4). The CDN is compressing the HTML on-the-fly when the user’s browser requests it.

What this blog post describes is pre-compression to Brotli 11 at 11ty build time. To do this the workflow is:

Apply Brotli level 11 pre-compression to HTML during the 11ty build on Cloudflare Pages.
_helpers/html-compression.js runs after the site is written to _site.
Each HTML file gets a matching .br file
Use the built-in Node zlib module, so no manual setup, CLI tools, scripts, Cloudflare configuration, or extra dependencies are required.
Take advantage of Cloudflare Pages Functions, which run on Cloudflare Workers. This is a great opportunity to use a modern, fast evolving platform that opens the door to powerful edge capabilities.

What’s the point?

Well, that’s a great question. As some readers may know by default Cloudflare compresses HTML at compression level 4. Now, if we compare this level to the compression level 11 above, let’s have a look at the difference:

Compression Size Examples v2

W3C HTML5 Specification (Single Page)

URL: https://www.w3.org/TR/2011/WD-html5-20110405/Overview.html
Uncompressed size: 4.7 MB
Brotli (Level 4): 729 KB (83% saving)
Compression Time (Level 4): 0.149 seconds
Brotli (Level 11): 590 KB (87% saving)
Brotli (Level 11): 11.717 seconds

Nasa’s Astronomy Picture of the Day Archive

URL: https://apod.nasa.gov/apod/archivepix.html
Uncompressed size: 314 KB
Brotli (Level 4): 66 KB (79%)
Compression Time (Level 4): 0.011 seconds
Brotli (Level 11): 53 KB (83% saving)
Brotli (Level 11): 0.743 seconds

It’s worth noting that I used Paul Calvano's fantastic Compression Tester Tool, to help with this basic analysis.

What you will likely notice is that even for large HTML files the size difference between compression level 4 and compression level 11 isn’t huge, only 12 KB in the W3C HTML5 Specification example. The real difference comes in computation time. Level 4 0.149 seconds verses 11.717 seconds! That’s a 7764% increase in time between Level 4 and Level 11! Although this is an extreme example, you can probably see why Level 11 isn’t used by Cloudflare for on-the-fly compression of HTML assets. Level 4 gives a good balence between file compression versus compression speed. I’m betting countless smart people were involved in the analysis of using Level 4 by default! When you are a company that is literally serving billions of requests per second, this decision really makes a difference in terms of processing power infrastructure and power usage!

Thankfully, the way that I have implemented level 11 compression on my blog, processing time doesn’t really matter. All the HTML is being compressed at 11ty build time. As I said above, the cost of this additional CPU time is paid back over time by users getting a better experience (even if only slightly). Furthermore, remember there’s a slight reduction in storage required on the CDN. From my perspective, if it is low effort after setup, it feels like the right move to implement it.

Problems

As I found out during implementation it isn’t just as simple as compressing the HTML to 11 and setting a static Content-Encoding header for HTML in the _headers file (trust me, I tried it!)

Problem 1: URL Path vs Actual File Path Mismatch

When serving static assets like CSS, JS, or images, there is usually a simple one-to-one relationship between the URL and the file on disk. A request to /css/site.css maps directly to _site/css/site.css. No extra logic is required because the URL path matches the file path exactly. I had no idea, but I soon found out that HTML pages behave differently. A request to / or /blog/post/ does not correspond to a literal file at that path. Instead, the server applies a convention and serves index.html inside that directory. So /blog/post/ actually maps to blog/post/index.html on disk. This mapping happens automatically when Cloudflare serves uncompressed HTML through its very efficient static asset layer.

The problem appears when serving pre-compressed Brotli files. You cannot simply request the same URL and expect the .br file to resolve. Instead, the Cloudflare Function must manually translate the directory style URL into the real file path before appending .br.

For example, / becomes /index.html.br, /blog/post/ becomes /blog/post/index.html.br, and /404.html becomes /404.html.br.

In short, HTML requires explicit path translation because the browser sees a directory style URL while the actual file stored on disk is index.html. The Cloudflare Function must bridge that gap to correctly serve the Brotli 11 compressed version, rather than the uncompressed HTML version.

It actually makes sense now that I think about it, I’ve always just taken the automatic appending of index.html to a URL Path for granted! The fact that as a user on the web doesn’t even have to think about that small detail, shows how well it works! As Dieter Rams once said:

Good design is as little design as possible.

Problem 2: A page full of Wingdings

I’m showing my age again, but for readers who don’t remember early versions of Windows (e.g. 3.1), it came bundled with a font called Wingdings. This True Type font contains many largely recognised shapes and gestures as well as some recognised world symbols.

Wingdings were an early symbol font that experimented with pictographic digital symbols, that would later lead on to ASCII emoticons like :-) & ¯\_(ツ)_/¯, which in turn would progress to the modern world of Emoji’s!

Essentially, what was happening the Cloudflare server was serving raw Brotli compressed HTML files to the browser, expecting it to understand what these (now binary, not text) files were, and how to read and understand them. I was essentially serving the HTML without the following headers:

Content-Type: text/html; charset=UTF-8
Content-Encoding: br
Vary: Accept-Encoding

Here’s a brief explanation of these headers:

Content-Encoding: br: This is telling the browser “What I’m sending you is a Brotli compressed file, you are going to need to decode it before you understand it”.
Content-Type: text/html; charset=UTF-8: This tells the browser what character set ('charset') it should use after decompression, this is essential as this is key to the browser parsing the HTML correctly.
Vary: Accept-Encoding only affects caching (e.g. Content Delivery Networks). It’s basically saying to the cache to store separate versions of this file depending on the Accept-Encoding header.

The result of the above gave me a homepage that looked like the image below (interesting but not exactly readable!):

My Approach

Step 1: Build-time compression

After the site is generated, it moves into a final preparation stage before going live.

During this stage, the system goes through all the finished HTML pages and creates highly compressed versions of them. These compressed files sit alongside the originals and are ready to be served immediately.

Because this happens as part of the 11ty build process, every release automatically includes freshly optimised files. This means the live site can deliver pages faster, with smaller file sizes and no need to compress anything on the fly (e.g. what Cloudflare does with its HTML compression to Brotli level 4).

The result is better performance for users, with no extra overhead once the site is hosted and running on Cloudflare pages.

Step 2: Cloudflare Pages Function for content negotiation

When someone visits a page on the site, a lightweight Cloudflare Function (via a Cloudflare Worker) checks whether a users browser supports modern compression.

If it does, the system serves the Brotli 11 pre compressed version of the page. This keeps file sizes small and pages loading quickly.

If the browser does not support this compression, or if a compressed version is not available, the system simply serves the standard uncompressed version of the HTML instead.

No extra processing happens at this stage. The edge layer (Cloudflare Function + Worker) is only deciding which version of the already prepared files to send. All optimisation work has already been done earlier in the 11ty build process.

The final result is fast delivery, efficient bandwidth use, and a simple, reliable build setup. Everyone wins!

Step 3: The Eleventy build uses Node.js zlib, for seamless integration

As mentioned earlier, this Brotli implementation differs from others I have used. Instead of relying on bash scripts such as compress.sh or compress-directory.sh, it uses Node.js’s built in zlib module. Because zlib is part of Node.js core, it is stable, well maintained, and requires no external dependencies. It has been available since the earliest Node.js releases, so it is a sensible default choice. I may even revisit the other build process in future and consider replacing the remaining bash scripts with a fully Node.js based approach.

Implementation

Next, let’s stop the waffling and get onto the actual implementation, I assume that’s what readers are here for after all!

Core compression utility

Here is the main compression file that is used to compress the HTML to Brotli 11:

/**
 * Core compression utility: Brotli compression for build-time pre-compression.
 *
 * This module is the single source of truth for Brotli in the project. It is used by:
 * - html-compression.js  — compresses all HTML in _site to .br (level 11)
 * - css-manipulation.js  — compresses processed CSS to .br when writing to _site
 * - js-compression.js    — compresses minified JS in _site/js to .br
 *
 * All compression happens during the Eleventy production build (postbuild phase).
 * Pre-compressed .br files are then served via content negotiation in functions/[[path]].js
 * when the client sends Accept-Encoding: br, avoiding any runtime or CDN dynamic compression.
 */

import { brotliCompressSync } from 'zlib';

/**
 * Default Brotli compression level.
 *
 * Brotli levels range from 0 to 11:
 * - 0–3: Fast, lower ratio (typical for dynamic/on-the-fly compression; e.g. CDNs often use 4).
 * - 11:  Maximum ratio, slowest; ideal for static assets compressed once at build time.
 *
 * We use 11 because compression runs only during the build, so CPU cost is paid once per
 * deploy. The resulting .br files are then served as-is with no re-compression at the edge.
 */
export const BROTLI_LEVEL = 11;

/**
 * Compress input data with Brotli.
 *
 * Uses Node's synchronous zlib API so callers can use the function in a simple, blocking
 * way during the build (no need to await). Input is normalized to a Buffer so that
 * strings (e.g. file contents read as UTF-8) and TypedArrays are supported.
 *
 * @param {Buffer | Uint8Array | string} input - Data to compress. If a string, it is
 *   encoded as UTF-8. Buffers and Uint8Array are used as-is (after copying to a Buffer
 *   when necessary via Buffer.from).
 * @param {number} [level=BROTLI_LEVEL] - Compression level 0–11. Defaults to 11 for
 *   maximum ratio. Can be overridden (e.g. via BROTLI_COMPRESSION_LEVEL in css-manipulation).
 * @returns {Buffer} - Compressed data as a Buffer. Callers typically write this to a
 *   file with a .br extension (e.g. index.html.br).
 */
export function brotliCompress(input, level = BROTLI_LEVEL) {
	const buffer = Buffer.isBuffer(input) ? input : Buffer.from(input);
	return brotliCompressSync(buffer, { level });
}

I appreciate that not everyone prefers heavily commented code, so there is also a version in this Gist with minimal comments and improved readability.

HTML compression post-build

The post-build HTML compression file:

/**
 * HTML Brotli compression (postbuild).
 *
 * This module compresses every HTML file in the Eleventy output directory (_site) to
 * Brotli level 11 and writes a corresponding .br file alongside each .html file
 * (e.g. index.html → index.html.br, blog/post/index.html → blog/post/index.html.br).
 *
 * When it runs:
 *   Only during the production postbuild phase, after Eleventy has finished writing
 *   _site. It is invoked from _config/build-events.js in the eleventy.after handler
 *   (alongside JS minification, JS Brotli, and preload header generation).
 *
 * How .br files are served:
 *   The Cloudflare Pages Function functions/[[path]].js performs content negotiation
 *   for HTML document requests. When the client sends Accept-Encoding: br, the Function
 *   fetches the pre-built .br asset (e.g. / → index.html.br) and returns it with
 *   Content-Encoding: br. Clients that do not advertise Brotli support receive the
 *   uncompressed .html from the static asset bucket. No dynamic compression runs at
 *   the edge; this step does all compression once at build time.
 *
 * Uses the core compression utility _helpers/compression.js for the actual Brotli call.
 */

import fs from 'fs';
import path from 'path';

import { brotliCompress, BROTLI_LEVEL } from './compression.js';

/**
 * Recursively find all .html files under a directory.
 *
 * Used to discover every HTML file in _site (root index.html, blog posts, portfolio
 * items, 404.html, etc.). Paths are returned as relative to _site so that we can
 * join them with siteDir for full paths and still have readable relative paths for
 * logging and error messages.
 *
 * @param {string} dir - Absolute or relative directory path to search (e.g. ./_site or a subdir).
 * @param {string[]} [acc=[]] - Accumulator array; results are pushed here during recursion.
 * @returns {string[]} Relative paths to .html files (e.g. ['index.html', 'blog/post/index.html']).
 */
function findHtmlFiles(dir, acc = []) {
	const entries = fs.readdirSync(dir, { withFileTypes: true });
	for (const entry of entries) {
		const fullPath = path.join(dir, entry.name);
		const relPath = path.relative('./_site', fullPath);
		if (entry.isDirectory()) {
			findHtmlFiles(fullPath, acc);
		} else if (entry.isFile() && entry.name.endsWith('.html')) {
			acc.push(relPath);
		}
	}
	return acc;
}

/**
 * Compress all HTML files in _site with Brotli level 11, writing .br files.
 *
 * Call this only after the Eleventy build has completed and _site is fully written.
 * For each .html file: reads content, compresses with brotliCompress (level 11),
 * writes <filename>.br next to the original. Existing .br files are skipped if their
 * mtime is >= the source .html mtime (incremental safety; in a full build all HTML is
 * usually newer, so most files are compressed). Logs counts, total bytes saved, and
 * duration; collects per-file errors without stopping the loop.
 */
export function compressHtmlFiles() {
	const startTime = Date.now();
	console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
	console.log('🚀 PRODUCTION POSTBUILD: Starting HTML Brotli compression');
	console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');

	const siteDir = path.join('./_site');
	if (!fs.existsSync(siteDir)) {
		console.log('⚠️  _site directory not found, skipping HTML compression');
		return;
	}

	const htmlFiles = findHtmlFiles(siteDir);
	if (htmlFiles.length === 0) {
		console.log('⚠️  No HTML files found, skipping compression');
		return;
	}

	let compressedCount = 0;
	let skippedCount = 0;
	let totalOriginal = 0;
	let totalCompressed = 0;
	const errors = [];

	for (const relPath of htmlFiles) {
		const inputPath = path.join(siteDir, relPath);
		const outputPath = `${inputPath}.br`;

		try {
			// Skip writing if .br already exists and is not older than the source .html
			if (fs.existsSync(outputPath)) {
				const inputStats = fs.statSync(inputPath);
				const outputStats = fs.statSync(outputPath);
				if (outputStats.mtime >= inputStats.mtime) {
					skippedCount++;
					continue;
				}
			}

			const fileContent = fs.readFileSync(inputPath);
			const originalSize = fileContent.length;

			const brotliBuffer = brotliCompress(fileContent, BROTLI_LEVEL);
			const compressedSize = brotliBuffer.length;

			fs.writeFileSync(outputPath, brotliBuffer);
			compressedCount++;
			totalOriginal += originalSize;
			totalCompressed += compressedSize;
		} catch (error) {
			errors.push(`❌ ${relPath}: ${error.message}`);
		}
	}

	const totalTime = Date.now() - startTime;
	const savedPercent = totalOriginal > 0 ? ((1 - totalCompressed / totalOriginal) * 100).toFixed(1) : '0';

	console.log(`✅ Compressed ${compressedCount} HTML file(s) (${skippedCount} skipped, up-to-date)`);
	if (compressedCount > 0) {
		console.log(
			`   ${(totalOriginal / 1024).toFixed(1)} KB → ${(totalCompressed / 1024).toFixed(1)} KB (${savedPercent}% smaller)`
		);
	}
	console.log(`   Finished in ${totalTime}ms (${(totalTime / 1000).toFixed(2)}s)`);

	if (errors.length > 0) {
		console.error('\nErrors:');
		errors.forEach(e => console.error(`  ${e}`));
	}

	console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
}

A version with minimal comments and much improved readability is available in a Gist here.

Cloudflare Pages Function for content negotiation

Here we have the Cloudflare Function file that runs in the Cloudflare Worker. It is located in the /functions directory in the root of the repository so it can be detected when Cloudflare Pages builds.

/**
 * Catch-all Cloudflare Pages Function: HTML document content negotiation.
 *
 * This Function runs for every GET and HEAD request that is not handled by a more
 * specific route (e.g. POST /api/contact is handled by functions/api/contact.js).
 * Its job is to serve pre-compressed Brotli (.br) HTML when the client supports it,
 * and otherwise pass through to the static asset bucket (uncompressed HTML).
 *
 * Pre-compressed .br files are produced at build time by _helpers/html-compression.js
 * (postbuild): every .html in _site gets a matching .br (e.g. index.html.br,
 * blog/post/index.html.br). This Function does not compress on the fly; it only
 * chooses which asset to serve and sets the correct response headers.
 *
 * Flow:
 * 1. If the request is not for an HTML document URL (see below), pass through to ASSETS.
 * 2. If the client does not send Accept-Encoding: br, pass through (serve uncompressed HTML).
 * 3. Otherwise, fetch the corresponding .br asset; if missing or error, fall back to ASSETS
 *    for the original request (uncompressed).
 * 4. If .br exists, return it with Content-Encoding: br and no-transform so nothing
 *    re-compresses the body.
 */

async function handleHtmlWithBrotli(request, env) {
	const url = new URL(request.url);
	const pathname = url.pathname;

	// Only treat as HTML document: root (/), directory-style paths ending in /, or 404
	// (Cloudflare Pages maps /404 to /404.html). All other paths (e.g. /script.js,
	// /style.css, /favicon.ico) go straight to static assets; Pages serves .br for
	// static files when available and client sends Accept-Encoding: br.
	const isHtmlDocument = pathname === '/' || pathname.endsWith('/') || pathname === '/404.html';

	if (!isHtmlDocument) {
		return env.ASSETS.fetch(request);
	}

	const acceptsBrotli = request.headers.get('Accept-Encoding')?.includes('br') ?? false;

	if (!acceptsBrotli) {
		return env.ASSETS.fetch(request);
	}

	// Map URL path to the .br file in the asset bucket. Eleventy outputs directory
	// indexes as index.html (e.g. /blog/post/ → blog/post/index.html), so the .br
	// file is <path>index.html.br.
	const brPath =
		pathname === '/' ? '/index.html.br' : pathname === '/404.html' ? '/404.html.br' : `${pathname}index.html.br`;

	const brUrl = new URL(brPath, url.origin);
	const brResponse = await env.ASSETS.fetch(brUrl.toString());

	if (!brResponse.ok) {
		return env.ASSETS.fetch(request);
	}

	// Build response from the .br body with headers that declare Brotli and prevent
	// any downstream re-compression or transformation.
	const headers = new Headers(brResponse.headers);
	headers.set('Content-Encoding', 'br');
	headers.set('Content-Type', 'text/html; charset=UTF-8');
	headers.set('Vary', 'Accept-Encoding');
	// no-transform: tells caches (including Cloudflare) not to re-encode or modify the body
	headers.set('Cache-Control', 'public, max-age=31536000, no-transform');

	return new Response(brResponse.body, {
		status: brResponse.status,
		headers,
		// encodeBody: 'manual' — we are returning the body as-is (already Brotli).
		// Without this, the Workers runtime might try to compress the response again.
		encodeBody: 'manual',
	});
}

export const onRequestGet = async ({ request, env }) => {
	return handleHtmlWithBrotli(request, env);
};

export const onRequestHead = async ({ request, env }) => {
	return handleHtmlWithBrotli(request, env);
};

A version with minimal comments and much better readability is available in a Gist here.

Build lifecycle wiring

This is the main build file I use to build my 11ty blog for production on Cloudflare Pages.

/**
 * Build lifecycle wiring: registers Eleventy before/after hooks for production.
 *
 * This module is the single place where postbuild steps are scheduled. It is loaded
 * from the main Eleventy config (e.g. eleventy.config.js), which calls
 * registerBuildEvents(eleventyConfig). Handlers run only when env.isLocal is false
 * (i.e. production or preview builds); local dev builds skip all of this so that
 * _site is left as plain output and the dev server stays fast.
 *
 * Order of operations:
 * - eleventy.before: clear CSS build cache so CSS is regenerated and Brotli-compressed
 *   from scratch when needed.
 * - eleventy.after: run the production postbuild phase in a fixed order:
 *   1. generatePreloadHeaders() — write Link headers into _headers for CSS (and .br).
 *   2. minifyJavaScriptFiles()   — minify JS in _site/js (must run before Brotli).
 *   3. compressJavaScriptFiles() — Brotli-compress JS to .br.
 *   4. compressHtmlFiles()       — Brotli-compress all HTML in _site to .br.
 *   Then: destroy HTTP/HTTPS global agents to avoid hanging connections, and on
 *   production only force process.exit(0) after a short delay so the process
 *   terminates cleanly on CI/Cloudflare Pages.
 */

import env from '../_data/env.js';
import { clearCssBuildCache } from '../_helpers/css-manipulation.js';
import { generatePreloadHeaders } from '../_helpers/header-generator.js';
import { compressHtmlFiles } from '../_helpers/html-compression.js';
import { compressJavaScriptFiles } from '../_helpers/js-compression.js';
import { minifyJavaScriptFiles } from '../_helpers/js-minify.js';

/**
 * Register eleventy.before and eleventy.after handlers.
 * Only registered when !env.isLocal (production/preview).
 * @param {import("@11ty/eleventy").UserConfig} eleventyConfig
 */
export function registerBuildEvents(eleventyConfig) {
	if (env.isLocal) {
		return;
	}

	// Before build: clear any cached CSS build artifacts so this run produces fresh
	// processed and Brotli-compressed CSS when templates reference CSS.
	eleventyConfig.on('eleventy.before', () => {
		clearCssBuildCache();
	});

	eleventyConfig.on('eleventy.after', async () => {
		console.log('\n═══════════════════════════════════════════════════════════════════════════════');
		console.log('🚀 PRODUCTION POSTBUILD PHASE: Beginning postbuild operations');
		console.log('═══════════════════════════════════════════════════════════════════════════════\n');
		generatePreloadHeaders();
		await minifyJavaScriptFiles();
		compressJavaScriptFiles();
		compressHtmlFiles();
		console.log('\n═══════════════════════════════════════════════════════════════════════════════');
		console.log('✅ PRODUCTION POSTBUILD PHASE: All postbuild operations completed');
		console.log('═══════════════════════════════════════════════════════════════════════════════\n');

		// Tear down Node's default HTTP/HTTPS agents so the process can exit without
		// waiting for keep-alive connections to time out (e.g. on Cloudflare Pages CI).
		console.log('🔧 Forcing cleanup of HTTP connections and timers...');
		await new Promise(resolve => setTimeout(resolve, 100));

		try {
			const http = await import('http');
			const https = await import('https');

			if (http.globalAgent) {
				http.globalAgent.destroy();
				console.log('✅ Destroyed HTTP global agent');
			}
			if (https.globalAgent) {
				https.globalAgent.destroy();
				console.log('✅ Destroyed HTTPS global agent');
			}
		} catch (error) {
			console.warn('⚠️  Could not destroy HTTP agents:', error.message);
		}

		await new Promise(resolve => setTimeout(resolve, 50));
		console.log('✅ HTTP connection cleanup completed');

		// On production builds only, force exit after a short delay so the runner
		// (e.g. Cloudflare Pages) gets a clean exit code and doesn't hang.
		if (env.isProd) {
			console.log('🏁 Production build complete - forcing process exit in 2 seconds...');
			setTimeout(() => {
				console.log('👋 Forcing clean exit now');
				process.exit(0);
			}, 2000);
		}
	});
}

A version with minimal comments and much improved readability is available in a Gist here.

Other Technical details worth mentioning

Here are 4 other small technical details worth explaining as part of the implementation:

Why encodeBody: 'manual' is required

The content we send back to the user's browser is already compressed using Brotli. It is being loaded from a file that has already been compressed in advance.

If we don't tell Cloudflare to leave it alone, it may assume the content is not compressed and try to compress it again. Compressing something that is already compressed can cause problems and may result in a broken or unreadable output, plus it is a waste of CPU time and resources.

By setting encodeBody: ‘manual', we are telling Cloudflare to send the content exactly as it is, without changing it. This ensures the pre-compressed file is delivered correctly to the user's browser.

Why Vary: Accept-Encoding and Cache-Control: no-transform matter

These 2 response headers are critical for making the pre-compression work. I've given details as to why that is below:

Vary: Accept-Encoding: This notifies browsers and CDNs that the response can change depending on what kind of compression the browser supports.

For example, if a browser says it supports Brotli, the cache will store and return the Brotli version for those requests. If another browser doesn't support Brotli, the cache will store and return a different version, such as an uncompressed version. This prevents the wrong format being sent to the wrong browser.

Cache-Control: no-transform: This informs caches and other systems between the server and the user's browser not to modify the content. It asserts that the response should not be compressed again or altered in any way.

Without this setting, a proxy might try to compress the content again, which can cause errors and waste processing power. With this header in place, the already compressed file is stored and delivered exactly as intended.

Incremental build optimisation (runtime check to skip unchanged files)

After the Eleventy build finishes, the post-build step recursively scans through the output folder, such as the _site directory, and checks each HTML file.

Before compressing a file, it checks whether a matching .br file already exists and whether it is up-to-date. If the .br file is the same age or newer than the original file, it is skipped. If the page is new or has been updated, a fresh compressed version is created.

This avoids pages that have not changed being needlessly recompressed, keeping the post build step fast. When only a few pages are updated, the need for recompression is limited.

Why we need a Cloudflare Function instead of just the `_headers` file for HTML Brotli?

1. `_headers` can only change headers, not the file itself

The _headers file lets us add or modify (but not remove) response headers. It doesn't control which file is actually sent back to the browser.

So, when someone visits / or /blog/post/, Cloudflare Pages automatically serves index.html or blog/post/index.html.

If we want to serve the Brotli version of the HTML, we need to send index.html.br instead. But the _headers file has no way to switch the file being served.

2. Setting the header alone is not enough

Even if you add Content-Encoding: br in the static _headers file, the actual file being sent would still be the normal uncompressed version of the HTML.

The browser would see this Brotli header and try to decompress the response. Since the content being sent isn't compressed, it would simply fail and the page would break.

Results

Looking at my build logs I can now see that compressing the HTML to Brotli 11 has had the following results:

📊 HTML Brotli 11 total savings: 123.4 KB (75.2% reduction)

That’s not too bad a saving considering how simple it is to set up and integrate into the 11ty build process! Thankfully, now that it’s done I can just “set it and forget it!”. Let's examine the results from the DevTools Network panel below:

DevTools Before

DevTools After

DevTools After Page Reload

Curiously, when reloading the page with DevTools open, the HTTP status code changes from 200 to 304 and the Brotli compression in the Content-Encoding: br disappears. The reason for this is because either:

The reload request doesn’t contain an Accept-Encoding: br header so the Cloudflare Worker is simply returning the uncompressed version of the HTML file as is expected.
The 304 has no response body, so there’s nothing to show as being compressed.

Difference in build times

Thanks to Thomas Steiner on Mastodon for the reminder. It completely slipped my mind to share the difference in build time before and after adding HTML Brotli compression.

Total Build time before: ~ 2 minutes 58 seconds
Total Build time after: ~ 3 minutes 16 seconds

Compressed: 485 HTML file(s) (0 skipped, up-to-date) Total time: 18.191299 seconds (about 18.19s) to Brotli compress all HTML files.

Summary

By pre-compressing this blog’s HTML during the 11ty build phase, I have reduced the number of bytes sent on each page load. While the savings are small for a low traffic site like mine, at scale across millions of users and billions of requests per day, this approach could deliver meaningful bandwidth reductions and incremental performance improvements. This is especially true where network speed and stability vary globally.

Thank you for reading, I hope you found it useful. Edge Workers are an incredibly powerful technology. I genuinely look forward to using them again in the future.

I always open to feedback and corrections. If you spot anything that needs fixing or is incorrect, please let me know. I will credit you in the post changelog below.

Post changelog:

21/02/26: Initial post published.
24/02/26: Thanks to Thomas Steiner for nudging me to add details about the difference in build times!

Asset fingerprinting and the preload response header in 11ty

2025-09-02T00:00:00Z

This blog post will be building on a number of blog posts that I wrote earlier in the year. These were the posts:

Some insights from my earlier posts may carry over here, so check them out for overlap or a fuller view of my custom CSS pipeline for 11ty.

In this post, I’ll improve performance by adding the preload technique to my blog. First, let’s look at what it is.

Preload basics

In a standard web page load, once requested, the server sends over the HTML document as well as numerous response headers too. The HTML is progressively served to the browser, and it is only when the parser encounters the standard <link src="example.css" rel="stylesheet"> link that the browser requests the CSS file from the server. Therefore, best practice is to place this CSS link as close to the top of the <head> tag as you can. This ensures that the browser sees it quickly and thus starts downloading it as soon as it can. But what if you could give the browser a "hint" as to what is coming up in the document? This is where the Preload hint functionality comes in.

The Preload hint is essentially saying to the browser:

I know you're busy doing other things at the moment, but you should also know that you absolutly will be requiring this file soon in the page load. So stick it at the top of your list to download as soon as you can.

It's important to realise that this is only a "hint", not a mandatory instruction. The browser may choose to entirely ignore it, if for example it has already parsed and discovered the file you wish for it to preload. There are 2 ways in which you can implement a preload.

1. Link in the head

This is probably the easiest way to add a preload to a website. Stick it in the <head>:

<link rel="preload" href="style.css" as="style" />
<link rel="preload" href="main.js" as="script" />

2. Preload link header

This method ensures that the browser is told about what other resources to load along with the HTML document in the form of a response header from the server. The above "Link in the head" functionality looks like this as a response header:

Link: </style.css>; rel=preload; as=style
Link: </main.js>; rel=preload; as=script

Link: </style.css>; rel=preload; as=style, </main.js>; rel=preload; as=script

Both headers give the exact same functionality, it just comes down to readability. I don't believe the single line version give any performance advantages, especially when any form of header compression is applied, e.g. hpack for HTTP/2 or qpack for HTTP/3. But please do let me know if this assumption I'm making isn't true!

In both instances above, we are telling the browser to preload the page’s CSS and JavaScript because they will be required to render the page. You may notice that I phrased it as “will be required”. This is deliberate because it is far too easy to abuse the preload functionality. If you instruct the browser to preload everything, you will likely harm web performance instead of improving it. So only preload assets that are genuinely needed for the page to render. Otherwise, you risk wasting bandwidth on unnecessary resources and slowing down the rendering process. I know Firefox warns you in the DevTools console if an asset has been preloaded but not used during a certain time period, other browsers may do this as well. So always check your browser console for similar messages.

Preload and fingerprinting

There is a small added challenge when using asset fingerprinting with the preload functionality. Since the filename of the CSS or JavaScript changes completely whenever the file contents change, you cannot simply preload index.css or main.js. They will instead be renamed to something like index-362ccd3816.css or main-2fc0e9cad0.js. These are just example names, but the important point is that the file names are unpredictable and will change with each build, assuming the content of the files change. Since nobody wants to update a preload reference by hand every time a file changes, this is where a bit of 11ty scripting magic steps in to save the day.

The Code

In order to roll this functionality into my 11ty build, I created a helper file in my _helpers directory in the root of my blog. This is called header-generator.js. Imaginative name, huh! All functionality related to the header generation will be contained within this file.

It is then imported into my eleventy.config.js like so:

import { generatePreloadHeaders } from './_helpers/header-generator.js';

Now, I only want this code to run in production, and after the 11ty build completes, so I added the following later in the config:

if (IsProduction) {
	eleventyConfig.on('eleventy.after', generatePreloadHeaders);
}

Hopefully, this code is fairly self-explanatory. I'm hooking into the eleventy.after event, which is the point at which my CSS has been Brotli compressed and fingerprinted, and the Link Header is ready to be generated and added to my Cloudflare Pages _headers file (documentation here) before the _site is built. Below is the complete header-generator.js file I am using, with detailed comments to make it easier to follow:

// standard node library imports
import fs from 'fs';
import path from 'path';

// This script generates preload headers for fingerprinted CSS files in the _site/css directory
// and adds them to the global section of the _headers file (/*) in the _site directory.
// It prefers Brotli-compressed files (e.g. *.css.br rather than *.css) if available.
export function generatePreloadHeaders() {
	// Log the start of the process
	console.log('Generating preload headers for CSS files...');
	// This is my CSS directory for my blog
	const cssDir = path.join('./_site', 'css');

	// Check if CSS directory exists
	if (!fs.existsSync(cssDir)) {
		console.log('CSS directory not found, skipping header generation');
		return;
	}

	// Find fingerprinted CSS files (both .css and .css.br). We prefer .css.br if available.
	// Fingerprinted files match the pattern index-[hash].css or index-[hash].css.br
	const cssFiles = fs.readdirSync(cssDir)
		.filter(file => {
			// Match files like index-b9fcfe85ef.css.br or index-b9fcfe85ef.css
			return file.match(/^index-[a-f0-9]{10}\.css(\.br)?$/);
		});

	// Nothing found so exit
	if (cssFiles.length === 0) {
		console.log('No fingerprinted CSS files found, skipping header generation');
		return;
	}

	// Sort to prefer *.br files over *.css files
	// (compression is done via the zlib library in another helper file)
	// both .css and .css.br files exist in the same folder with the same file hash
	// The hash is generated from the unminified and uncompressed CSS file)
	cssFiles.sort((a, b) => {
		// If a is .br and b is not, a comes first
		if (a.endsWith('.br') && !b.endsWith('.br')) return -1;
		// If b is .br and a is not, b comes first
		if (!a.endsWith('.br') && b.endsWith('.br')) return 1;
		return 0;
	});

	// Take the first (preferably .br) file
	const cssFile = cssFiles[0];

	// Construct the path for the Link header
	const cssPath = `/css/${cssFile}`;

	console.log(`Found CSS file: ${cssFile}`);
	// Now we need to read the existing _headers file, add the preload header to the global section (/*),
	// and write it back
	try {
		// Read the source headers file
		const sourceHeadersPath = path.join('./public', '_headers');
		// Set our target headers file
		const targetHeadersPath = path.join('./_site', '_headers');

		// Check if source _headers file exists
		if (!fs.existsSync(sourceHeadersPath)) {
			console.log('Source _headers file not found');
			return;
		}

		// Read the existing headers content
		let headersContent = fs.readFileSync(sourceHeadersPath, 'utf8');

		// Create the preload header
		// Note: 'nopush' prevents Cloudflare from doing HTTP/2 server push
		const preloadHeader = `  Link: <${cssPath}>; rel=preload; as=style; nopush`;

		// Find the global /* rule and add the preload header to it
		// Look for the line that just contains "/*" which is the global section
		const lines = headersContent.split('\n');
		let globalSectionIndex = -1;
		let nextSectionIndex = -1;

		// Find the global section (line that starts with just "/*")
		for (let i = 0; i < lines.length; i++) {
			if (lines[i].trim() === '/*') {
				globalSectionIndex = i;
				break;
			}
		}

		// Find the next section (line that starts with a path)
		if (globalSectionIndex !== -1) {
			for (let i = globalSectionIndex + 1; i < lines.length; i++) {
				if (lines[i].trim() !== '' && !lines[i].startsWith('  ')) {
					nextSectionIndex = i;
					break;
				}
			}
		}
		// If we found the global section, proceed to add or update the Link header
		if (globalSectionIndex !== -1) {
			// Check if a Link header already exists in the global section
			let linkHeaderExists = false;
			// Iterate through the lines in the global section
			for (let i = globalSectionIndex + 1; i < (nextSectionIndex === -1 ? lines.length : nextSectionIndex); i++) {
				// Check for the existance of the Link header
				if (lines[i].includes('Link:')) {
					// Replace existing Link header
					lines[i] = preloadHeader;
					// The Link header exists and has been updated
					linkHeaderExists = true;
					break;
				}
			}

			// If no Link header exists, add one
			if (!linkHeaderExists) {
				// Find the last header line in the global section
				let lastHeaderIndex = globalSectionIndex;
				// Iterate until the next section or end of file
				for (let i = globalSectionIndex + 1; i < (nextSectionIndex === -1 ? lines.length : nextSectionIndex); i++) {
					if (lines[i].trim() !== '' && lines[i].startsWith('  ')) {
						lastHeaderIndex = i;
					}
				}
				// Insert the Link header after the last header
				lines.splice(lastHeaderIndex + 1, 0, preloadHeader);
			}
			// rejoin the modified _headers file
			headersContent = lines.join('\n');
		} else {
			console.log('Could not find global section in _headers file');
			return;
		}

		// Write the updated headers to the _site directory before deployment to Cloudflare pages
		fs.writeFileSync(targetHeadersPath, headersContent);

		console.log(`Generated preload header: Link: <${cssPath}>; rel=preload; as=style; nopush`);

	} catch (error) {
		console.error('Error generating preload headers:', error);
	}
}

For a cleaner version without comments, I’ve uploaded the code to a Gist. Find the code Gist here.

The Cloudflare `_headers` file

This setup is currently working really well, the only minor "issue" that doesn't sit right with me presently is the fact that the Link header sits on the global header path (/*) in the _headers file. This means the Link header is added to all assets served from my blog.

As far as I know, this shouldn't cause any issues, as browsers will just ignore it if on a file type that doesn't support it. But I would like to rectify this in the future.

In my testing with the Cloudflare _headers file, once a header is set in Cloudflare Pages it cannot be removed or overwritten. The only "fixes" I’ve found for this are:

Use a response header transform rule in the Cloudflare dashboard to remove the Link header from all other file types served except CSS.
Look into a Cloudflare Workers solution to examine the server responses at "the edge" and remove them that way.

I will eventually move forward with option 1 as it looks to be the most straight-forward way to do it.

I've mentioned this "minor issue" in the blog post, simply to highlight the fact about not being able to remove headers using the _headers file once they have been set. If anyone knows how to do this using only the _headers file, please let me know. I’d love to learn how.

Summary

All this is now live on this very blog, so using my custom CSS pipeline with 11ty, I now have the following happening before deployment to live:

CSS minified and Brotli compressed to level 11 (highest).
CSS Asset fingerprinting to allow for long life cache-control headers, including immutable.
Preloading of the CSS file to reduce the discovery time and improve page performance.

On a side note: This is probably one of the fastest (and shortest) blog posts I've written in a while! I knew I could do it! 🤣 I hope you found it as enjoyable to read as I did to write. As always, feedback and post corrections are welcome. Spot anything wrong? Please do let me know.

Post changelog:

02/09/25: Initial post published.

Hack to the Future - Frontend

2025-08-26T00:00:00Z

Hack to the Future - Frontend

1. Introduction

Context

So over the last few months at work, I've been conducting interviews to hire Frontend Developers for a number of new projects we have in the pipeline. It was only when looking at CV's that it struck me, a lot of these candidates weren't even born when I first started in my Web Development career! So I thought maybe developers getting into a Frontend Developer career today, may want to learn a bit about what it was like when I first started (that sentence just makes me feel old! 👴)

Looking back at “legacy” practices

Why would we want to look back on legacy best practices on the web? Other than the obvious academic and for general interest reasons?

Studying past best practices and legacy systems is crucial for understanding the evolution of technology and making informed decisions today. By examining the problems old practices were designed to solve, we gain a deeper appreciation for current best practices and avoid repeating past mistakes. As the philosopher George Santayana once said:

Those who cannot remember the past are condemned to repeat it.

This historical perspective also reveals enduring principles like progressive enhancement, which remains vital for creating accessible and resilient systems on the web.

Lessons we can apply today

For developers, understanding past methodologies is essential for properly maintaining and modernising existing systems in the future without causing critical failures. This historical knowledge will ultimately help them navigate the complexities of older codebases, to ensure they make informed decisions about how to update or replace components. Above all, reflecting on the past can help us come up with creative new ideas and prevent us from blindly following new trends. This perspective also provides a comprehensive view of how the web has evolved, grounding our current practices in a deeper understanding of the technology's history.

This process of building on past knowledge is a fundamental aspect of human progress. Just as civilizations learn from historical events to avoid repeating mistakes, developers can learn from the successes and failures of past technological eras. It's how humanity has always evolved. By building upon the accumulated wisdom and experience of those who came before us. By studying the mistakes and triumphs of the past, we improve our own work and contribute to the continuous cycle of innovation and learning that drives our entire industry forward.

2. Setting the Time Circuits to the late 90s

My first website build

In 1998, while working toward my GCSEs, I became interested in art and design, this was partly thanks to having an art teacher as my form tutor throughout secondary school. That influence, combined with the opportunity to take a double art GCSE for the same effort as a single GCSE, made the choice a pretty easy one! GCSE Art, here I come!

At the same time, I was already immersed in the emerging world of the internet, spending many hours online discovering a passion for many areas of computing and online gaming thanks to QuakeWorld Team Fortress, despite the frustration it caused at home by tying up the phone line all hours of the day, oh how I loved my US Robotics 56K modem, with its 120-150 ping! Integrated Services Digital Network (ISDN) or any form of broadband was still many years away for most people!

I was never exactly blessed with traditional artistic talent, painting, drawing, all of those art forms just wasn’t my thing. But I spotted an opportunity to combine my love of technology with the art curriculum. Back then, there were only about 2.4 million websites in existence worldwide. Most businesses and schools (including mine), were firmly offline. So, I proposed building a website for my final art project. To my surprise, my art teacher was absolutely thrilled with the idea. It turned out to be a first for the school and, as I later discovered, a first for the entire exam board too. Shock horror: I was ahead of the curve once. The curve has been safely ahead of me ever since.

I ended up creating a website for a fake record label, complete with a dreadful album cover, fictional artist, and made-up discography. Honestly, I wish I still had it! It was gloriously awful! I don’t recall much, but I remember the site used a <frameset> with three <frame> elements. The top frame displayed the logo, the left frame held the navigation menu, and the main frame was used for the page content.

The logo, by the way, was crafted in a program called 3D Text Studio (or something similar to that) that churned out spectacularly cheesy animated text like this! From a web performance perspective, that single GIF exceeded 2 MB. On a 56K modem, which was the standard connection for most users of the web at the time, that translates to a 6-minute loading time for just that GIF! Fortunately, it was never hosted online and was presented to the examiners directly from my local machine.

Long story short… the examiners loved my little website and I got a double A* Art GCSE for my effort!

So what's all this preamble leading too? Well, this is just a long-winded way to tell you (again) that I'm old… 😭

The late 90s web landscape

There have been some things I've noticed while questioning candidates in interviews recently, many candidates don't have the faintest idea of some old methodologies used in the world of Frontend, especially during the "unstable" periods of the web like the late 90s and early 00s:

Being a Frontend Developer in the late 90s was both fun in terms of innovation, but also exceedingly stressful due to the instability of the web platform! A prime example being cross-browser development. What worked in Netscape, often looked very broken in Internet Explorer (and vice versa)! And if you had clients who were looking for "pixel perfect" designs across all browsers, you were in for a bad time!

Throughout this period, a plethora of methodologies, tools, and workarounds were developed to address deficiencies in the web platform. And that’s what the rest of this post will delve into. Buckle up folks, we are about to time travel to an era when the internet started with the screeching of dial-up noises and I still had brown hair!

3. The Early Web – Layout and Design Practices

Photoshop PSDs as the “single source of truth”

Using Adobe Photoshop Documents (PSD) as a single source of design truth was a very common practice in the early days of web design. This was particularly common when design and development teams were siloed. A designer would create a PSD file that was intended to be precisely what the website would look like in the browser.

Issues

There were no considerations made for page structure, behaviour, and interactions. These fixed layout PSD's encouraged bad practices like:

Fixed page dimensions e.g. 1024px x 768px as a static canvas.
1:1 mapping of Photoshop file to web page, which was rarely achievable, especially given cross-browser inconsistencies with page rendering.
Lack of fluid or responsive design. I realise responsive design wasn't "a thing" at this time, but could it have been adopted sooner if fixed-width PSD workflows hadn't ever taken hold?
The technique was more suited to static layouts, like print design, rather than web design.
There were issues tracking interaction states like anchors with hover, active, disabled, and focus.
Dynamic content was difficult to visualise (e.g., the rendering of different lengths of text in the browser).
Poor accessibility adaptations, (e.g., increased font sizes, high-contrast modes weren’t considered in the design files).

The only way to solve many of these issues would be to create multiple PSD's to hold all these different design assumptions. And in doing so, file management and design revisions would quickly become impractical and prone to being incomplete or inconsistent.

Broken team collaboration

The use of PSD's as the single source of truth broke how teams could collaborate and innovate. This was because:

Developers would often have to interpret or translate the PSD design manually without the help of designers (e.g. due to siloed teams and strict job roles).
Changes in the design required round-trips to designers, rather than being evolved collaboratively in code.
Small team bottlenecks were common e.g. all design or development decisions needed to go through individuals rather than a whole team.
Files became outdated rapidly leading to teams working on outdated designs without realising it.
Designers often came up with designs that simply couldn't be built with the web technologies that existed at the time, especially when their designs were expected to work across different browsers.

Modern Alternatives

I'd like to think that designers using Photoshop for modern web design is a thing of the past, given the vast number of tools and techniques that are way more suited to the job than Photoshop ever was. Modern teams typically use:

Design tokens and internal component libraries as the "single source of truth".
Figma or similar tools with structured, token-aware components.
Living style guides and code-driven prototypes (e.g., Storybook).
Clear handoffs between teams using tools like zeroheight, or integrated design-to-dev platforms.

The advantage of using these modern collaboration tools enables design and development teams to share the same language and source of truth, rooted in reusable, well-tested, and accessible components.

Photoshop PSDs Summary

In the early days of my frontend career, slicing PSDs was second nature, but that workflow is now obsolete. Using Photoshop as a "single source of truth" leads to siloed teams, rigid layouts, and poor collaboration. It ignores responsiveness, accessibility, and the realities of modern web development. Today, tools like Figma, design systems, and component libraries enable faster, more inclusive, and collaborative workflows. If you’re still building from PSDs, it’s time to move on! As the web has evolved, it is imperative that we all do the same.

Frame-Based Layouts

The Frame-based layouts were introduced into browsers to solve a specific set of problems. These were:

To allow static content like navigation menus to remain in place while only the main content of the page gets updated on navigation.
To Reduce the amount of data transferred over the network, since only one part of the page would need to be loaded. This was important at the time as remember in the late 1990s and early 2000s, broadband for most people simply wasn't available. If you were very lucky (and had the money), you'd be able to get an Integrated Services Digital Network (ISDN) line installed in your home, but it was mostly online businesses that had the money (and justification) for this type of connection, even ISDN wasn’t particularly quick. Adjusted for inflation you'd be looking at £60 to £80 per month for a 0.128 Mbps connection!
To simulate a more app-like experience before JavaScript (JS) and CSS became more standardised and mature.

Example

For those curious here's an simple example of an HTML page using frames:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">
<html>
	<head>
		  <title>Simple Frame Example</title>
	</head>
	<!-- Note no Body element: 2 vertical columns -->
	<!-- 30% width the menu.html document -->
	<!-- 70% width for the main content of the page -->
	<frameset cols="30%,70%">
		  <frame src="menu.html" name="menuFrame">
		  <frame src="content.html" name="contentFrame">
	</frameset>
</html>

Notes:

To use <frame> and <frameset> you needed to use a specific HTML 4.01 Frameset DOCTYPE, in the index.html file.
In my example, for a single HTML page you'd have to maintain 3 HTML files (index.html, menu.html, and content.html).
Each frame was like a mini browser window that loaded its own HTML document.

Problems

Unfortunately, there were a number of major issues with Frame-Based Layouts:

Terrible user experience: the use and navigation of frames was confusing for users, since you effectively had multiple browser panes in a single page. The URL bar would often remain static even as the content of the page changed.
Poor Accessibility: Screen readers and other assistive technology struggled to navigate frames, making it incredibly difficult for users with disabilities to understand the page content and overall page structure.
Limited Search Engine Optimisation (SEO) compatibility: Even Search engines of the day struggled to understand the index pages built within frames. This lead to poor visibility in search results, as crawlers frequently failed to understand the relationship between the different frames.
Navigation and Browser Compatibility: Because the back and forward buttons did not consistently produce the desired results, frames disrupted the navigation history, making it difficult for users to find their way around. The fact that different browser vendors weren't aligned with how frames should work in browsers lead to cross-browser issues too.
Bad for security: Frames allowed for security risks like clickjacking. This is where an attacker gets a user to interact with a page that contains malicious content without the user even realising. Modern browsers now include protections to stop these types of security issues.

Modern Alternatives

Modern CSS Layouts: Flexbox and Grid allow for responsive layouts without compromising navigation, accessibility, and SEO.
Single Page Applications (SPAs): Frameworks like React, Angular, and Vue allow developers to load page content dynamically without the need for full-page reloads. Be careful though, these libraries come with their own inherent issues if not used correctly!
Server-Side Rendering and Partial Updates: techniques like server-side includes, AJAX, or component-based rendering to update portions of a page efficiently.

Frame-Based Summary

As mentioned in the introduction at the start of this post, my first website was built using frames! I sincerely hope you never have to maintain a frame-based website! But given the enormity of the internet, it is almost certain websites exist somewhere out there, having been untouched for decades! If you do come across one remember to take a quick peek at the source code, it's like looking back in time! They once served a purpose in the early days of the web but are now considered obsolete. Their usage introduced more problems than they solved, and have been replaced with techniques that are more performant, accessible, and maintainable. Any modern website should be using semantic HTML, CSS-based layouts, and progressive enhancement.

Table-Based Layouts

In the late 1990s and early 2000s table-based layouts were a common technique for building a web page structure: A simple example of what this would look like is below:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <title>Table Layout Example</title>
  <!- Very simple CSS to modify the key elements in the table-based layout -->
  <style>
    body {
      font-family: Arial, sans-serif;
    }
    td {
      padding: 10px;
      border: 1px solid #ccc;
    }
    .header {
      background-color: #f2f2f2;
      text-align: center;
      font-weight: bold;
    }
    .nav {
      background-color: #e0e0e0;
      width: 200px;
      vertical-align: top;
    }
    .content {
      background-color: #ffffff;
      vertical-align: top;
    }
    .footer {
      background-color: #f2f2f2;
      text-align: center;
      font-size: 0.9em;
    }
  </style>
</head>
<body>

<table width="100%" cellspacing="0" cellpadding="0">
  <!-- Header -->
  <tr>
    <td colspan="2" class="header">
      My Table-Based Web Page
    </td>
  </tr>

  <!-- Body -->
  <tr>
    <!-- Navigation -->
    <td class="nav">
      <ul>
        <li><a href="#">Home</a></li>
        <li><a href="#">About</a></li>
        <li><a href="#">Contact</a></li>
      </ul>
    </td>

    <!-- Main Content -->
    <td class="content">
      <h2>Welcome</h2>
      <p>This layout uses an HTML table for structure, which was common before CSS-based layouts became standard.</p>
    </td>
  </tr>

  <!-- Footer -->
  <tr>
    <td colspan="2" class="footer">
      &copy; 2025 Example Company
    </td>
  </tr>
</table>

</body>
</html>

Why was it used?

At the time CSS and layout techniques were inconsistent and unstable across browsers. Developers looking for stability in cross-browser rendering turned to tables in order to do this. At the time, tables offered:

Predictable cross-browser rendering
Control over alignment, spacing, and sizing
Ability to nest elements in a grid-like structure

It was very common to see nested tables and transparent "spacer GIFs" in invisible table cells to control these layouts more precisely. You'd often find logo's, sidebars, navigations, footer, and content areas all laid out within a deeply nested HTML table in order to achieve the layout and design that was required.

Why was it so bad?

The first and hopefully most obvious point is that the <table></table> element was intended for the display of tabular data. The fact that it was used as a workaround for the lack of standardised layout techniques, shows the ingenuity of developers at the time.

Unfortunately, the use of tables for layout came with many considerable downsides, these included:

Semantics: As mentioned, tables should represent structured data, not layout. Misusing them confuses assistive technologies and harms accessibility.
Maintainability: Table-based layouts are challenging to read, modify, or scale. Small changes often require restructuring entire layouts.
Responsiveness: They are rigid and not suited to fluid or responsive design, that was to come a number of years later.
Performance: They delay rendering because browsers need to calculate the entire table layout before painting it to the page.

Is the technique still used?

There are some areas where table-based layouts may still be seen:

Legacy code bases that desperately need to be refactored, I can imagine there are many internal systems across the world where table-based layouts are still used. I’d imagine the conversation about modernising goes something like this… "If it still works, why change it?". Very short-sighted I know!
Table-based layouts are still widely used in emails due to the very limited support for CSS in email clients. It's not always the lack of support, it's the fact that many clients simply strip out any CSS in the process of rendering the email HTML.
- To give you an example of how bad it still is, from Outlook 2007+, Microsoft switched to Microsoft Word as the HTML rendering engine! And it's still in use today with Outlook 365! I did my fair share of HTML emails as a Junior Frontend Developer, the internationalised versions were the worst! Using the same table-based layouts for 19+ languages is never going to work well, especially with languages like German with their huge word length! Sorry… rant over!
They are often still used in PDF generation tools e.g. data-driven print views: invoices etc.

Modern alternatives

Modern CSS offers clean, semantic, and powerful layout tools, including:

Flexbox: One-dimensional layouts (ideal for nav bars, toolbars, etc.)
CSS Grid: Two-dimensional layouts (ideal for full-page layout and complex structures)
Media Queries: Enable responsiveness across devices
Container Queries (still an emerging technology): Context-aware layout changes.

Table-Based Summary

Table-based layouts are a throwback to a bygone era, thankfully! The years of building HTML emails has scared me for life! As they were developed during a period in which CSS was inadequate for the task. Developers had to get creative to wrestle with browser quirks, and tables were the go-to workaround. Thankfully, these days, we’ve moved on to semantic HTML and proper CSS that actually does what we need (for webpages anyway). It’s cleaner, more flexible, and maintainable, and way better for accessibility.

Quirks Mode Layouts

This topic is covered in more detail later in the blog post, but I’ll briefly mention it here for completeness.

It's important to realise that Quirks Mode Layouts weren't only limited to Internet Explorer (IE). It originated with Internet Explorer, but it was not exclusive to IE. Not only that, it later became a cross-browser convention in order to preserve the compatibility with many web pages on the internet. As that's the primary rule to consider when rolling out any new technology changes on the web. Whatever you do, "don't break the web!".

For example, if a vendor released a new browser feature that wasn't backwards compatible with earlier versions of web pages, then you have a major issue as you've just broken the web! I talk about XHTML 2.0 later in the post, as it is a prime example of a proposed technology that would have broken the web. This backwards compatibility was the sole purpose of Quirks mode. It gave modern browsers the ability to switch between:

Quirks Mode: Mimic pre-standards behaviour. Used for old, non-compliant pages.
Standards Mode: Adheres to modern web specifications (W3C and WHATWG standards).
Almost Standards Mode: The same as Standards mode only with one exception, table cell line-height rendering. This was to preserve layouts that used inline images inside HTML tables.

How were layouts triggered?

The browser decided which layout mode to use from the list above purely from the DOCTYPE used on the page. For example:

Trigger Quirks mode

This DOCTYPE will trigger Quirks mode layout:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

It looks valid, but it is missing the system identifier (URL) therefore it is a malformed DOCTYPE so Quirks Mode is triggered. A valid DOCTYPE is given below for comparison:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

That missing URL in the DOCTYPE is vital. Quirks Mode would also be activated if a page did not have a DOCTYPE or was not identical to the valid DOCTYPE given above in any way. IE even had a really nasty habit of triggering Quirks Mode if any character was output in the page source before the DOCTYPE. This included invisible characters and new lines and line returns too! As you can imagine, it made debugging issues an absolute nightmare!

Almost Standards Mode

The following DOCTYPE's will trigger Almost Standards Mode:

HTML 4.01 Transitional (with full system identifier):

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

HTML 4.01 Frameset (with full system identifier):

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">

XHTML 1.0 Transitional:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

XHTML 1.0 Frameset

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">

Standards Mode

And lastly and most importantly for modern web development. This is the DOCTYPE you should be using to trigger standards mode in all modern browsers:

<!DOCTYPE html>

This simplified DOCTYPE was brought in as part of the HTML5 Specification after 6 years of standardisation (2008–2014).

Why was this version created?

As outlined in all the examples above, previous DOCTYPE versions were:

Long
Error-prone
Required both a public and a system identifier
Affected rendering modes (Quirks, Almost Standards, Standards)

In order to solve these issues this the new DOCTYPE:

does not reference a Document Type Definition (DTD) as (HTML5 no longer relies on SGML-based validation).
only has a single purpose: to trigger Standards Mode in all modern browsers.

Quirks Mode Summary

As we have discussed above, Quirks Mode wasn't an IE exclusive layout mode. It was introduced into all browsers in order to "not break the web". To ensure your website uses Standards Mode, use:

<!DOCTYPE html>

And remember it must be the first characters in the source code on the page!

Iframe Embeds for Layouts or Content

If you've already read the Frame-based Layouts section above, then this section will be very similar. Although both are now considered legacy techniques, they come with distinct differences.

Frameset

As I discussed earlier here's example <frameset> code:

<!-- column 1 25% width / column 2 75% width -->
<frameset cols="25%,75%">
	<frame src="nav.html">
	<frame src="main.html">
</frameset>

The <frameset> tag completely replaced the <body> tag and allowed developers to split the browser window into multiple, scrollable, resizable sections.
Each section (<frame>) loaded a separate HTML document (as seen in the code above).
This technique was intended to use them as a layout structure. e.g. different parts of the User interface (UI) came from different HTML documents.
Navigation in one frame would control the content in another frame.

Inline frames (Iframes)

These were introduced later in the HTML 4.01 Transitional specification. Example <iframe> code is found below:

<body>
	<iframe src="content.html"></iframe>
</body>

You will immediately notice the difference, using an <iframe> doesn't replace the <body> tag, it embeds an external HTML page into the original page.

The usage of iframes was to embed content into other pages, not structure the whole layout.
iframes were used to load external or isolated content within a single, self-contained HTML page.

User Experience

Both methods came with issues, but iframes were slightly better but still caused significant problems:

Embeds could be styled and resized, but remained isolated from the parent.
Navigation, SEO, and accessibility were still severely impacted when misused.

Standards and Browser Support

Framesets were deprecated and completely removed from the HTML5 specification, modern browsers either no longer support them or support is very limited without the correct DOCTYPE.

Iframes are still a part of the HTML5 specification, but they come with limited use cases, including:

Secure sandboxing
Third-party embeds

In fact, the performance of iframe embeds has recently been improved by browsers vendors adding support for loading="lazy" on iframes thus allowing the browser to delay loading until the iframe is in the viewport.

Security

Thankfully, iframes are more secure on the modern web thanks to attributes like:

Although the use of iframes still needs careful consideration for content integrity, cross-domain policies, and maintainability. They can still introduce security vulnerabilities such as:

Clickjacking
Cross-site scripting (XSS) exploits.
Cross-origin resource sharing (CORS) exploits.

Can I still use them?

Yes, iframes are still a part of the HTML5 specification, so you can still use them, but you should try to only use them in specific scenarios where required. For example, when you need to embed third-party content into a website. This is often seen in banking on the modern web, when you are paying for something online. The final step of the transaction frequently loads an iframe from your bank asking to verify your purchase, usually via some form of Multi-factor Authentication (MFA) e.g. SMS, banking app approval on your phone. While iframe embeds aren't specifically required for PCI compliance. Many online merchants tend to implement them along with 3D Secure authentication to help reduce PCI scope and exposure.

Modern alternatives

As mentioned in the Frame-Based Layouts section, there are a number of modern alternatives rather than using iframes for page layout, modularisation, and code isolation. These include:

Modern CSS Layouts: Flexbox and Grid allow for responsive layouts without compromising navigation, accessibility, and SEO.
Single Page Applications (SPAs): Frameworks like React, Angular, and Vue allow developers to load page content dynamically without the need for full-page reloads. Be careful though, these libraries come with their own inherent issues if not used correctly!
Server-Side Rendering and Partial Updates: techniques like server-side includes, AJAX, or component-based rendering to update portions of a page efficiently.

Iframe Embeds Summary

Using iframes for modularisation and isolation is now seen as a legacy approach and should generally be avoided on the modern web. That said, they still have a place for things like third-party embeds. I remember the early days of Facebook marketing, iframes were everywhere and an absolute nightmare to work with, especially when trying to get the sizing right within their UI. Urghh!

Pixel-Perfect Design

Pixel-perfect design is a now outdated design approach that was once considered the gold-standard in frontend development. The presented UI on the web page was intended to be a pixel-perfect replica of the design mockups.… If that sounds like a ridiculous and totally unworkable strategy, then I can confirm, yes it was!

What the technique means in practice

Strict visual fidelity: Developers were expected to reproduce every element of a design using the exact measurements, colours and fonts given in a static design file like a Photoshop Document file (PSD).
Close alignment with design tools: The priority while using this technique was to match the layout in the design document, no matter what. Inconsistencies across various browsers, not to mention differing screen sizes and user preferences, frequently made this an impossible task.
Used in fixed-resolution environments: The technique worked reasonably well in the era of desktop-only websites with very few fixed screen sizes (e.g. 800×600, 1024×768).

Why is it considered legacy?

Responsive design is now standard
- Modern devices now range from the size of watches, all the way up to ultra-wide monitors and TV's and everything in between. Pixel perfect design fails on both smaller and larger size screens.
Accessibility and user preferences
- Modern Accessibility-first design requires designs to be flexible in terms of layout and scaling. For example, WCAG 2.2 Success Criterion 1.4.4 expects text to be scaled up to 200% without loss of content or functionality. This simply can't be done when using the pixel-perfect design technique.
Performance and Maintainability:
- It encourages the use of hardcoded CSS rather than using scalable design systems and components.
Modern Design Tools and Systems
- Tools like Figma and Sketch now exist with scalable units, that can create responsive mockups rather than static visuals.
Design Intent Over Exact Replication
- Modern web design focuses on intent and consistency across contexts, prioritising usability and accessibility over pixel-perfect replication by leveraging newly introduced responsive browser technologies.

Can I still use it?

I hate to be the bearer of bad news, but no, you can't. It simply isn't compatible with the modern web, for all the reasons I've given above. You are better off understanding what the technique was trying to achieve and focus on modern-day alternatives.

Modern Alternatives

Use of Design tokens for spacing, colour and typography.
Modern browser layouts like CSS Grid and Flexbox.
Component libraries and Design Systems that abstract repeated patterns.
Focus on the user content, not the dimensions of the UI viewing it.

Pixel-Perfect Summary

Pixel-perfect design was always a terrible design technique that set everyone up to fail with the expectation of pixel accurate designs across browsers and devices. It served its purpose when the web was a lot simpler than it is today. A pixel-perfect design on today's web is a clear indication of an outdated aesthetic, urgently requiring a modern overhaul.

Fixed Pixel Layouts

There's a reason why I've mentioned Fixed Pixel layouts directly after Pixel-Perfect Design. They are related, but have differing concepts. They both emerged in an early era of web design, but they serve different purposes.

Pixel-perfect Design

As you will have just read above, pixel-perfect design emphasises the precise implementation of a design on a website. The output of the website should be identical to the design, down to every pixel. For this reason, it is a philosophy, not a layout strategy.

Fixed Pixel Layouts

Fixed pixel layouts are a layout strategy where all widths, heights, and positions are defined using fixed pixel values (e.g. width: 1024px). This means it the page layout doesn't adapt to different screen sizes or resolutions. They are rigid and non-responsive, and are optimised for a single resolution or screen size. Because of this Fixed Pixel Layouts break on small screen sizes (like mobiles), or large displays. They are very much associated with older websites and legacy intranet tools. If you look at early websites on the web they would often say "Best viewed with Internet Explorer (or Netscape Navigator) at 800×600 (or 1024×768)". These are prime examples of where Fixed Pixel layouts were used.

Fixed Pixel Summary

Fixed pixel layouts and pixel-perfect design are outdated. They are relics from a time when monitor sizes were uniform and browser zooming was uncommon. Pixel-perfect demands you match the design mockup exactly, which usually ends in fragile CSS and breaks the moment someone dares to increase their font size or use a high contrast mode. Fixed pixel layouts take it even further by hard-coding dimensions, making sites fall apart on anything that isn’t a desktop from 2010. Adding to their drawbacks, neither option integrates well with modern accessibility standards, responsive design principles, or current web usage patterns.

CSS Floats for Layout

CSS floats were my go-to layout technique for many years, simply because there really wasn't a viable cross-browser alternative (other than Tables, which I covered earlier in the post). Floats were originally intended to be used for wrapping text around images on a page. They weren't intended to be used for full-page layouts. At the time, designers and developers did this as a creative way to make certain layouts, not because that was the design goal of the CSS specifications.

Common issues

Float-based layouts came with a major issue: fragile designs often required “clearfix” hacks to stop float containers from collapsing.

Example clearfix hacks

Here are a few example hacks that ensured the float container would wrap around the floated elements:

Modern (Recommended):

.clearfix::after {
	content: "";
	display: table;
	clear: both;
}

Usage:

<div class="clearfix container">
	<div style="float: left;">Left</div>
	<div style="float: right;">Right</div>
</div>

Overflow Hidden (Quick Fix):

.container {
	overflow: hidden;
}

This was my personal go to for "clearfix" as it was so simple to add to the CSS. A nasty downside of this method was it would hide any content that needed to overflow outside the float container, so its usage really depended on the design requirements.

Float the Container Itself (Not Recommended):

.container {
	float: left;
	width: 100%;
}

I don't remember really using this method simply because it could interfere with other layout elements on a page and could create unexpected layout shifts during page rendering.

Using display: flow-root (Modern, Clean Alternative):

.container {
	display: flow-root;
}

This is far too modern for me, it didn't exist when I was still building UI's regularly. As, it has been stable in major browsers since January 2020. The advantage of this method is no pseudo-elements or hacks required. This is recommended for use if you are modernising code and want the cleanest approach without adding extra markup. Other float-based issues include:

Poor readability: Additional markup was required just for the container clearfix hacks. This also impacted maintainability too.
Inconsistent behaviour: Floats tended to behave differently depending on the browser in use, although not as problematic as it was, it still requires more testing to ensure cross-browser UI consistency.
Stacking issues: Aligning text, or centring horizontally and vertically, is non-trivial.

Modern Alternatives

As with most of the topics in this section of the post, there are a list of modern alternatives available for float-based layouts.

Flexbox: One-dimensional layouts (ideal for nav bars, toolbars, etc).
CSS Grid: Two-dimensional layouts (ideal for full-page layout and complex structures).
Media Queries: Enable responsiveness across devices
Container Queries (still an emerging technology): Context-aware layout changes.

Performance and Maintainability

Modern layout techniques:

Lead to cleaner and more maintainable code.
Reduce reliance on utility classes for clearing float-specific bugs.
Enhance responsiveness and accessibility by ensuring that the HTML code's structure is more predictable.

Legacy Support Considerations

Floats still appear in legacy code, so understanding them remains important for maintenance and modernisation. However, they should be avoided in greenfield projects unless strictly necessary (I'm open to suggestions if anyone has an idea as to what this necessity might be).

CSS Floats Summary

Using CSS floats for layout is now considered an anti-pattern. While historically important, floats have been replaced with modern layout systems like Flexbox and Grid, which offer cleaner, more maintainable, and more powerful solutions. In the future as the web platform evolves, newer layout techniques such as CSS Subgrid, Container Queries, and Anchor Positioning are also progressing through standardisation and will further improve layout flexibility. Avoiding floats is a key best practice when building or modernising frontend architecture.

Faux Columns

I'm not sure why the French word "Faux" was chosen for this technique, rather than just "false" or "fake", maybe to make it sound more appealing? Or more complex than it actually is? The term works though, as in English, it is used to describe something made to look like something else, which is precisely what this technique did.

What is it?

In the early days of CSS there was no reliable way to make two or more columns stretch to the same height when the content length in the columns varied. This was because floats or inline-block elements don't align their heights, so developers looked for a workaround.

How it worked

It was a clever workaround actually, it typically worked like this:

A background image was applied to the parent container of the floated columns (that designers wanted to look to be equal in height)
This background image was often a vertical gradient or a solid block of colour. This image was then repeated (repeat-y) vertically down the parent container, giving the illusion ("fake") that the columns were of equal height.
As each of the inner floated elements extended due to varying content within, the container background image extended with it. Very clever, huh!

The CSS for this "workaround" was as simple as this:

/* container with the background repeat vertically */
.container {
	background: url('faux-columns.png') repeat-y;
}
/* Note the width of this column, it is important */
.left-column {
	float: left;
	width: 200px;
}
/* Use an identical margin to the width, to "push" the right column into place next to the left column */
.right-column {
	margin-left: 200px;
}

The background image of the container would have 2 sections, one colour for the left column and another for the right column, thus tricking a users eyes into seeing the columns having equal heights!

Check out the Faux Columns A List Apart (ALA) article by Dan Cederholm from January 2004, if you are still unsure how it works, he explained it a lot better than I have!

Limitations

Unfortunately, as with all of these early CSS workarounds, there were limitations. The faux columns technique was no different. These limitations included:

Not adaptable: it required the background image to perfectly match the layout dimensions of the container, and it's inner "columns".
Unresponsive: Exactly what the word says, this only worked for fixed layouts, fluid of more dynamic layouts simply broke the illusion.
Maintenance: The technique was difficult to maintain, since any layout change required editing the CSS, background image, or both.
Poor semantics: Yes, it solved the visual presentation problem, but the underlying code wasn't semantic, the additional <div>'s just for layout purposes, inherently held no semantic meaning.

Modern Alternatives

As you would expect, there are modern alternatives that make this layout trivial:

Flexbox

With Flexbox, it really is this simple:

.container {
  display: flex;
}
.left-column, .right-column {
  flex: 1;
}

CSS Grid

In CSS grid, it's even easier as all child elements in a row are explicitly defined and align by default, no extra CSS required:

.container {
	display: grid;
	grid-template-columns: repeat(2, 1fr); /* 1fr = 1 fraction unit */
}

Can I still use it?

Errr, silly question, no not at all! Look how effortless the modern alternatives above are! Imagine how good it feels to rip out the legacy faux column code from a legacy codebase, and replace it with 1 or 2 lines of CSS!

Faux Columns Summary

The Faux Columns technique was one of those clever hacks we leaned on back when CSS didn’t give designers and developers much to work with. It did the job, but it was fragile and fiddly, and you were always one layout change away from breaking it. These days, it’s more of a historical curiosity. Flexbox and Grid have long since made it obsolete, and with newer tools like Subgrid and Container Queries coming through the standards process, we’ve moved on from trickery to browser tools that are actually built for layout.

Zoom Layouts (using CSS zoom for responsiveness)

Back when responsive design was first emerging, a technique called Zoom Layouts emerged in order to scale whole elements within a UI. This technique emerged because responsive CSS layout techniques were very limited.

Example

An simple example of this is given below:

.container {
	zoom: 0.8;
}

This CSS is easy to understand, it simply scales the entire .container by 80%.

When was it useful?

This technique was useful when you needed to shrink or enlarge an entire layout without refactoring a fixed-width design. It also came in handy when working with legacy layouts that could not adapt with fluid widths or media queries. Lastly, it was used as a workaround before widespread browser support for the transform: scale() CSS property or relative units like rem, em, %, vw, and vh.

Why is it outdated?

There are a number of reasons as to why the Zoom Layout technique is now outdated. These include:

zoom is non-standard and inconsistent: The zoom property isn't a part of any official CSS specification. It is a proprietary feature initially supported by Internet Explorer, then later Chromium-based browsers. Interestingly, Firefox and Safari have never supported the zoom property, making cross-browser layouts using the technique very tricky.
Causes Accessibility issues: zoom does affect the layout scaling, but it doesn't interact well with user-initiated zoom or accessibility scaling preferences. Thus, using this technique can create barriers for users with visual impalements that rely on native browser zooming or OS-level zooming tools.
Breaks layout semantics: zoomed elements don't always reflow correctly, for example text can reflow outside its container, images can become blurry, and form elements may not align correctly when scaled.
Modern CSS has better solutions: As with most outdated techniques in this post, modern browsers now support much better layout techniques and relative units, that make responsive design much more consistent and easier to maintain. These include Flexbox, CSS Grid and rem, em, %, vw, vh units. Along with Media Queries and container queries, this gives developers the ability to adapt individual elements proportionally, rather than resorting to scaling the entire UI.
Performance issues: The use of zoom can cause serious performance issues, especially on low-powered devices since the rescaling causes the browser to scale rasterised layers rather than reflow content natively, which increases UI repaint costs.

Can I still use it?

Seriously, only if you hate your users and love additional maintenance. In practical terms, using it would not be a responsible choice; avoid it. If you come across a critical legacy site using this approach, plan to refactor it with modern techniques. Build your layouts using CSS Grid or Flexbox for flexibility across breakpoints, implement fluid typography with clamp and viewport units, adopt container queries for component-level responsiveness, rely on viewport-based units for consistency, and always test with browser zoom and assistive technologies to ensure accessibility and adaptability for all users.

Zoom Layouts Summary

Using zoom for layout responsiveness is an outdated, non-standard technique that can compromise accessibility, compatibility, and performance. Modern responsive design principles provide far more robust, scalable, and accessible solutions.

If you require a transition approach for legacy systems still using Zoom Layouts, consider refactoring incrementally to CSS Grid and Flexbox combined with relative units like rem or percentages to modernise their responsiveness. Luckily for you, this isn’t the last time you’ll hear about the infamous proprietary zoom property, as it makes quite a few appearances later in the blog post when we dive into those classic IE layout quirks.

Nested ems instead of Pixels

Before the CSS rem unit was added to the CSS Values and Units Module Level 3, developers used the em unit as a responsive strategy to avoid fixed pixel font sizes. Having used it for years I can confirm it was a real pain in the ass to work with (pardon my French!). When using an em unit, both the CSS font size and spacing were sized relative to their immediate parent container.

For example, given this HTML:

<body>
	<div class="container">
		<p class="child">Some text here</p>
	</div>
</body>

And this CSS:

body { font-size: 1em; }
.container { font-size: 1.2em; } /* relative to body */
.child { font-size: 1.2em; } /* relative to .container, so compounded */

Can you guess what the .child font size of the text is in pixels?

Better get your Math(s) hat on, let's go through it!

Default body font size = 16px so 1em x 16px = 16px. The .container DIV is relative to the body font size so: .container font size = 1.2em x 16px = 19.2px. The .child paragraph is relative to the .container font size so: .child font size = 1.2em x 19.2px = 23.04px

That's right, that well-known font size 23.04px!

Now this is just a very basic example, imagine if you include em units for margins and paddings too! And also layer on additional nesting! Hopefully, you are starting to realise how painful em units were to use on a website, especially when the only viable alternatives were percentages (which had the same relative nesting issue and were even less intuitive to use than em), or CSS keywords e.g. font-size: small, medium, large, x-large, etc. As you can see, there weren’t a lot of viable or maintainable options in terms of responsive typography and spacing in the early responsive design era (around 2010-2013).

Why it's outdated?

Complexity and unpredictability: Nested ems lead to compounded calculations as we saw in the simple example I gave above, making sizing unpredictable in deeply nested components. A small change in a parent font size cascades unexpectedly and could completely obliterate your well-crafted layout.
Maintenance overhead: Adjusting layouts or typography with nested ems quickly creates brittle CSS and significant technical debt, especially when ems are used for spacing like margins and padding.
Inconsistent UI scales: Components may render differently in different contexts if they rely on em units, especially in large applications with diverse layout containers.

Modern Alternatives

You can utilise several modern options for nested em units. These include:

rem units for consistent global scaling relative to the root font size
Clamp-based fluid typography for responsive design, for example Utopia.fyi.
CSS custom properties (variables) for consistent, maintainable scales

Can I use them today?

You could, but I have no idea why you would! When more viable alternatives exist today like rem units for global scaling, clamp for fluid typography, and CSS variables for maintainable scales, why make life harder than it needs to be??

Nested ems Summary

Using nested em units is outdated. It adds unnecessary complexity and unpredictability. For modern responsive design you are far better off using rems for consistent global scaling, or taking advantage of the clamp CSS function if you are feeling adventurous. Lastly, you could always use modern CSS variables for more consistent and maintainable code.

Setting the browsers base font size to 62.5%

As a direct follow on from the nested em technique earlier in the post, there was an alternative that developers came up with to simplify the math(s) behind percentages (since they had the same "relative to parent" issue as em's). When developers decided to use percentages for fonts, they often set the font size on the <html> element to:

html { font-size: 62.5%; } /* default font size now 10px not 16px, due to scaling making `em` units easier to work with (base-10 rather than base-16) */
.container { font-size: 1.6em }/*16px*/
.container { font-size: 2.4em }/*24px*/
.container { font-size: 3.6em }/*36px*/

This avoided complicated fractional calculations when using em units:

Without the percentage: 1em = 16px → 24px = 1.5em.
With the percentage: 1em = 10px → 24px = 2.4em.

You still had the problem with nested elements, but that was later fixed by using rem units (root em).

Why are these techniques less common today?

It overrides user defaults: Some users may increase their base font size from 16px for accessibility reasons, hard-coding the base size to 62.5% undermines this user preference.
Modern teams work with rem: Most developers and teams now accept that 1rem = 16px and use design tokens, variables, or a spacing scale instead of forcing a base-10 (62.5% hack) mental model.
Simplicity from Modern tooling: Design systems, utility classes, and CSS variables handle sizing scales more predictably without the 62.5% hack.

Can I still use it today?

No, not really, mainly due to the list of reasons I've given above. font-size: 62.5% was merely a developer convenience hack to make 1em / 1rem equal 10px for easy math(s). Look at the short list of modern alternatives I have listed above instead.

Base font size Summary

As mentioned above, this math(s) hack for easier font sizing is no longer required on the modern web, in fact it should be avoided due to the impact it has on users who change their base font size for accessibility reasons. Look to use one of the more modern techniques mentioned in the "Why are these techniques less common today?" section above.

Fixed-Width Fonts for Responsive Text

Fixed-width fonts are better known as monospaced fonts, they allocate the same horizontal spacing to each character. For example:

.mono-spaced-font {font-family: Courier New,Courier,Lucida Sans Typewriter,Lucida Typewriter,monospace;}

The example provided above demonstrates how to render text in a monospaced font and concurrently defines a monospaced font stack for most web page implementations. The reason I say "most" is because Windows has a 99.73% support for Courier New and OSX has 95.68% support according to CSSFontStack. Which is why it is listed first in the font stack, for the less than 1% of users that don’t support it, the browser will look for Courier and so on, until it gets to the end of the font stack, where it just tells the browser to use any monospace font the system has available.

Historically, monospaced fonts were used for:

Terminal emulation.
Code editors for alignment.
Early web design, where the layout predictability was prioritised over aesthetics or responsiveness.

Why was the technique used in responsive text?

Developers and designers struggled with the web platform's limitations at the time due to a lack of suitable tools. So monospaced text was usually used for:

Consistent character spacing across browsers.
Easier text alignment in table-based layouts.
Simplifying calculations for layout sizing, since browser layout strategies were much less mature than they are today.

Why is the technique outdated?

The technique is now considered outdated for various reasons, including:

It limits design flexibility. Modern responsive design has moved on from fixed typography, as fluid typography is now possible, which is better served by proportional fonts that adapt visually to varying screen sizes and reading contexts.
Monospaced fonts are harder to read, especially for paragraphs or long text blocks. This requirement on the modern web is critical for accessibility-focused design.
Instead of outdated methods, modern CSS offers enhanced tools and support for contemporary layout techniques. Flexbox and CSS Grid, coupled with various typography scaling units like rem, em, vw, vh, and clamp(), enable more predictable and reliable layout control.
There's no performance difference between modern proportional fonts and monospaced fonts, they both have similar browser overhead, so why choose a technique that is harder to maintain and comes with a whole host of other disadvantages?

What's a modern replacement?

There are a number of modern alternatives, some of which we touched on above. These include the use of:

Fluid typography with CSS clamp() and viewport units to ensure text scales responsively across devices.
Proportional fonts with font fallback stacks to optimise readability and layout adaptability.
Only using monospaced fonts for semantic or functional reasons, not aesthetics. Code blocks and tabular data are prime examples of where monospaced fonts should be used to enhance readability of these certain areas of a website. Adventurous designers can even transform a web UI into a retro Terminal window with these elements, though readability must be carefully considered.

Can I still use it?

As stated repeatedly in this section of the blog post, while technically possible, it would be highly illogical to employ this technique. Given the numerous disadvantages outlined earlier in this section, utilising such an antiquated method on the modern web would be ill-advised.

Fixed-Width Fonts Summary

There are so many font options available to developers and designers today. There is no way you should ever use a monospaced font for anything besides sections of code, or possibly text in a data table, depending on what type of data you are wishing to display. In both of these cases, a monospaced font can enhance readability if used correctly.

4. The Plugin Era – Flash and Friends

Flash-Based Content

I distinctly remember having a conversation with a then colleague regarding iOS not supporting Flash content and how it was the beginning of the end of Adobe Flash (Flash) on the web. At the time he refused to believe it, but thankfully for the web, my prediction came true!

What was Flash-based content?

Flash was a proprietary multimedia software platform developed by Adobe. It was used to:

Deliver animations, video, and interactive content via a plugin in the web browser.
Enable rich media applications embedded in websites.
Power early interactive interfaces on the web, this was way before the web platform matured and could support these types of interactivity natively.
I, personally, remember it for flash-based advertisements of which I created many when I was first starting out in web development!

Why was it popular?

Flash was hugely popular at the time due to the fact that:

Cross-browser multimedia support was lacking on the web platform (i.e. no native support)
Advanced vector animation support
In 2005, Flash was the sole method for streaming audio and video on the web, as exemplified by YouTube's reliance on it.
Interaction was programmed through the use of ActionScript. If it sounds very familiar to JS, that's because it is, as they are both based on the ECMAScript Standard. That's a massive oversimplification, but if you are curious, read all about it on Wikipedia.
In the late 1990s there was a popular trend on the web of having completely pointless Flash intros that would load and play automatically before you entered a site. There are countless example of these intros on YouTube if you are interested!

Why was it deprecated?

There are many reasons as to why Flash is now deprecated. These include:

Flash was well-known for serious security vulnerabilities, which were often used for malicious software and browser takeovers.
Flash content often consumed significant CPU and memory, leading to poor performance and excessive battery drain on mobile devices.
As mentioned earlier, Apple refused to support Flash on iOS, citing security, performance, and stability concerns, which contributed heavily to its decline.
Adobe's proprietary Flash technology was incompatible with open web standards, hindering accessibility, interoperability, and sustainability.
Lastly, open web standards and the web platform evolved to replace Flash with native (and non-proprietary) functionality like:
- Native video and audio playback (<video> and <audio> tags)
- CSS animations and transitions
- Canvas and WebGL for interactive graphics and games
- SVG for scalable vector graphics

Flash met its end with the advent of modern web APIs, including HTML5, CSS3, and modern JS.

In 2017 Adobe announced that Flash's end of life would be in 2020. In December 2020 Adobe released the final update for Flash. By January 2021, major browsers disabled Flash by default and eventually blocked Flash content entirely.

Can I still use it?

At last! A straightforward answer to this question: No, it's impossible for you to use Flash on the modern web as Flash content in no longer supported in any modern browser. Simple! RIP Adobe (Macromedia) Flash 1996 to 2020. You won't be missed.

Modern Alternatives

As mentioned above, there are a number of native browser-based alternatives for Flash (HTML5, CSS3, Modern JS) functionality these are: - Native video and audio playback (<video> and <audio> tags) - CSS animations and transitions - Canvas and WebGL for interactive graphics and games - SVG for scalable vector graphics

Scalable Inman Flash Replacement (sIFR)

Before the introduction of the @font-face at-rule, which is defined in the CSS Fonts Module Level 4 specifications, Web Designers and Frontend Developers were desperately seeking to expand the limited number of cross-browser, and cross-operating system fonts that were available on the web. In order to achieve that, a number of workarounds and general ingenious browser hackery were built. From the name of this technique you may also be able to guess the answer for the "Can I still use it?" section!

What is sIFR?

Scalable Inman Flash Replacement (sIFR) was an creative technique that used JS and Flash together to replace HTML text elements with Flash-rendered text. This feature allowed developers to embed custom fonts directly within the Flash file. Consequently, they could modify the HTML text, and the Flash file would dynamically render the updated content.

This workaround was required at the time because there was very limited support for custom web fonts via the use of @font-face. Surprisingly, @font-face was first introduced by Microsoft in Internet Explorer 4 in 1997, using Embedded OpenType (EOT) as the font format. This was proprietary to IE, so no other browsers supported it. Since there wasn't a cross-browser way to use custom fonts, alternative techniques like sIFR emerged.

sIFR Popularity

sIFR emerged in the early to mid-2000s, with its first public version released around 2004-2005. sIFR was widely used until around 2009-2010, especially for headings and branded typography. Its popularity grew during that period due to the technique's preservation of SEO and accessibility advantages. This was because the original HTML text remained in the Document Object Model (DOM), allowing it to still be readable by search engines and assistive technology. And once setup it was simple to update the underlying text and sIFR took care of the rest. There was also the added bonus that the text remained selectable, so could be copied and pasted when needed. It sounds like a great solution, so where did it all go wrong?

Why it's outdated?

There are several reasons why the sIFR technique is now outdated. We covered the main one in the previous "Flash-Based Content" technique above:

It relies on the Adobe Flash Player browser plugin, that is now deprecated and blocked in all major browsers due to security vulnerabilities and performance issues.
It slowed down page performance by increasing page load time, due to having to download the Flash assets.
Although it was partially accessible from an HTML perspective, it certainly wasn't perfect as it introduced accessibility and compatibility issues on devices without Flash support.
Web standards came to the rescue. CSS3 brought with it native cross-browser support for @font-face for custom fonts, without the need for any browser plugins. The new standards supported Web Open Font Format (WOFF and WOFF2) font formats which are a standardised and optimised custom font format for the delivery of fonts on the web. Basically, HTML5 and CSS working together simply removed the need for plugin-based typography workarounds.

Can I still use it?

As I mentioned, above this is a pretty simple question to answer… No, not at all, the removal of Flash from all modern browsers used today guarantees that!

Modern Alternative

There's only one modern alternative that should be used on the web today: @font-face. An example of its usage is given below:

@font-face {
  font-family: "MyCustomFont";
  src: url("fonts/MyCustomFont.eot"); /* IE9 Compat Modes */
  src: url("fonts/MyCustomFont.eot?#iefix") format("embedded-opentype"), /* IE6-IE8 */
       url("fonts/MyCustomFont.woff2") format("woff2"), /* Super modern browsers */
       url("fonts/MyCustomFont.woff") format("woff"), /* Modern browsers */
       url("fonts/MyCustomFont.ttf") format("truetype"); /* Safari, Android, iOS */
  font-weight: normal;
  font-style: normal;
}

Thankfully, modern browsers widely support WOFF, thus, simplifying the above code:

@font-face {
  font-family: "MyCustomFont";
       url("fonts/MyCustomFont.woff2") format("woff2"), /* Super modern browsers */
       url("fonts/MyCustomFont.woff") format("woff"); /* modern browsers */
  font-weight: normal;
  font-style: normal;
}

In fact, any modern web browser that supports WOFF also supports WOFF2. Therefore, the code you should use today is as follows:

@font-face {
  font-family: "MyCustomFont";
       url("fonts/MyCustomFont.woff2") format("woff2");
  font-weight: normal;
  font-style: normal;
}

In all instances above you'd use the custom font like so:

.myfontclass {
	font-family: "MyCustomFont", /* other "fallback" fonts here */;
}

The browser will take care of the rest!

Note: that you should always provide a font fallback in your font-family property, just in case the font file fails to load, or it is accidentally deleted from your server. There is so much more to the use of @font-face. If you are interested in advanced topics around its usage you should definitely check out Zach Leatherman's copious amount of work on the subject over the years!

Cufón

Much like sIFR above, Cufón was created due to the lack of options when it came to using custom fonts on the web. It was popular around the same time as sIFR (late 2000s and early 2010s). It essentially was solving the same problem, but using a different cross-browser technique. Whereas sIFR used Flash, Cufón worked like so:

Fonts were converted into vector graphics, and canvas (or VML for older versions of IE) this was then used to render the text in place.
The JS then replaced the HTML text with the custom font rendered version of the text.
Since it was JS-based, there was no need for any plugins (like Flash).

Why was it used?

As previously noted with sIFR, browser support for CSS @font-face was inadequate or inconsistent at the time. Designers and developers wanted to use custom fonts for branding and stylistic reasons without users having to install a plugin or the fonts locally. Cufón was attractive because it:

Didn't require a plugin for it to work.
Provided near pixel-perfect rendering of the custom font.
Was easy to integrate with minimal JS setup.

Why is it outdated?

Modern browsers all support @font-face, a much better solution as it allows the direct use of web fonts like WOFF or WOFF2 files without the use of JS hacks.
Its usage impacted accessibility. Due to Cufón replacing text in the DOM with rendered graphics, screen readers couldn't interpret these replacements as text, thus degrading a site's accessibility.
Cufón caused web performance issues as the text replacement script was run after page load, which increased page render time, blocked interactivity and degraded the overall performance, especially on slower devices.
Although Cufón attempted to preserve the replaced text in the DOM, the results were often inconsistent, mainly because search engine crawlers at the time had inconsistent results when parsing JS-replaced content.
Cufón didn't work with responsive design, once rendered the Cufón replaced text didn't scale correctly, unless the page was reloaded at the new page size.

Can I still use it?

Although the site is still available here, and the cufon.js script is still available to download. The font generator has been taken down and is no longer maintained. So to get it working you'd need to jump through quite a few hoops! So, what I'm really trying to say is: Yes, you can, but it isn't worthwhile. Even the original author Simo Kinnunen says on the website:

Seriously, though you should be using standard web fonts by now.

Modern Alternatives

Rather than repeat myself, I'll refer you to the same section from the sIFR methodology above.

GIF Text Replacements

Although I am aware that this is not a plug-in, it seemed like the most appropriate section to include it in since we are discussing font replacement techniques. Of all the custom font techniques I've listed, this one is by far the worst in my opinion. The technique was popular in the late 1990s and into the early 2000s, when there were very few other options for using custom fonts on the web.

What is a GIF Text Replacement?

It's a self-explanatory name. In order to use a custom font, a designer would create the static asset (usually via Photoshop or similar), then the developer would cut out the text as a GIF. This image would then be used to replace the HTML text on the page with the image, in order to make it look like a custom font was in use. Example code for this technique can be seen below:

<body>
	<!-- Gif text replacement for a heading -->
	<h1>
		<img src="images/heading-text.gif" alt="Welcome to Our Website">
	</h1>
	<ul>
		<li>
			<!-- Gif text replacement for a navigation link -->
			<a href="/about.html">
				<img src="images/about-link.gif" alt="About Us">
			</a>
		</li>
	</ul>
</body>

Note: Some readers may wonder why a GIF was used instead of a PNG, since both support transparency. The main reason is that Internet Explorer offered poor support for transparent PNGs and required a complicated hack to make them work, which I will explain later in the post.

Why was it so bad?

It was time-consuming and maintenance heavy. Should the design change, then so would all the GIFs that had to be manually cut out of the design files again.
It was bad for Accessibility. Screen readers are unable to process text embedded within GIFs or images that lack meaningful alt text. The absence or outdated nature of alt text therefore created an exclusionary experience for users with visual impairments.
It was bad for SEO. Search engines could not index text within images, thus, harming discoverability, this technique relied on developers ensuring they had accurate alt-text, which isn't always the case.
It was bad for performance. At the time of its popularity, the web was going through a transition period from HTTP/1.0 to HTTP/1.1. Although HTTP/1.1 was better for TCP connections than HTTP/1.0, these TCP connections were very expensive in terms of web performance, and each of these GIF replacements required its own TCP connection, which increased page load times.
It was terrible for responsiveness. Although the responsive web was a few years away when it was popular, the difference between images and text rendering was text's ability to scale across different devices and screen sizes. Images simply couldn't do that, leading to poor rendering and pixelation on some devices.
GIF only supports 256 colours (8-bit) and for the GIF to be transparent, one of those colours would need to be transparent. So if your text had a complex colour palette, it either wouldn't work, or just look terrible.

Can I still use it?

No, it's as simple as that. It's a technique with so many negatives and so few positives, it should be confined to the interesting history of the web platform!

Modern Alternatives

Again, rather than repeat myself, I'll refer you to the same section from the sIFR methodology above.

Adobe AIR

I remember going to a conference around 2007 / 2008, and there was so much hype about Adobe AIR. It was going to be the "next big thing", due to the fact it could enable developers to create rich desktop and mobile apps using only web skills and technologies.

What was Adobe AIR?

The AIR in Adobe AIR stood for Adobe Integrated Runtime. It was a cross-platform runtime developed by Adobe. It allowed developers to use: HTML, JS, Adobe Flash, Flex, and ActionScript. All combined they could run as a standalone desktop or mobile application. It supported Windows and macOS for desktop, and later Android and iOS on mobile.

Furthermore, it also enabled:

Running Flash-based applications outside the browser.
Enabling rich multimedia, animations, and offline capabilities.

Why is it outdated?

It relied on Flash and ActionScript. With flash reaching its end of life in late 2020 due to persistent security vulnerabilities, and the momentum behind open standards like HTML5, CSS3, and JS ES6+. AIR ceased to exist due to the loss of its core technology.
A shift to modern cross-platform frameworks. The market moved towards more efficient and performant technologies like:
- React Native
- Flutter
- Electron (for desktop apps) The advantage of these frameworks is they use native components or JS runtimes, without the heavy reliance on Flash. This offered developers and users greater performance, maintainability, security, and community support.
Lack of Adobe support. Adobe handed AIR over to a subsidiary of Samsung (Harman) in June 2019for ongoing maintenance. Support is still provided by Harman, but only for enterprises with legacy applications that they still rely on, There's no active innovation or features being added to AIR by Harman.
Security concerns. As with Flash in the browser, security was always an ongoing issue, and this continued in AIR since it was the backbone to its core functionality. By continuing to build on AIR, it poses security risks and compatibility limitations with modern browsers and operating systems.
Lack of developer interest and ecosystem. Developers on the modern web tend to favour open ecosystems with an active community for support and updates. Adobe AIR’s ecosystem has completely stagnated.

Can I still use it?

As with any other Flash-based technology, I'm afraid not, it is no longer supported and even if you could, there are more modern open frameworks you could use like, React Native, Flutter, or Electron (for desktop applications). AIR is now history, and if you are using an AIR application within your digital estate, it is strongly recommended you prioritise migration, due to higher maintainability, poor security, and lack of developer availability.

Yahoo Pipes

It is easy to forget just how dominant Yahoo was on the web during the late 1990s. Before Google emerged as the leading search engine, Yahoo was one of the primary gateways to the internet. Its peak influence was between 1996 and 2000, when it played a central role in how people accessed and navigated the web. It was the default starting point for most web users due to its curated directory, news, and email services combined. It was also a technology leader on the web too, as I mention later in the blog post when I look at their extensive JS Library: Yahoo! User Interface (YUI).

I remember using Yahoo Pipes for combining my many RSS feeds at the time, it really was a fantastic visual tool for data manipulation.

What was it?

Yahoo pipes was a visual data mashup tool that allowed users to aggregate, manipulate, and filter data from around the web. It was released in 2007, and it allowed developers (and non-developers) alike to aggregate, manipulate, and filter data from around the web. It provided a drag and drop interface where users could connect various manipulation modules and join them together by creating pipes between modules. You were essentially piping data "through" the tool (hence the name!) and the manipulated date would come out the other end. It was considered highly innovative at the time, and it was used a lot for rapid prototyping.

Why is it outdated?

Have a look at the Yahoo! homepage, and you will see it is the shadow of its former self, it looks to more of a news aggregation service now than a popular search engine. This was because Yahoo decided to make a giant shift in business strategy, moving away from developer tools and open web utilities to concentrate on advertising and media products. Although it was popular with technology enthusiasts, it was never a mainstream product for Yahoo, so the operational expenses vs. usage statistics didn't align with Yahoo's business priorities. Lastly, the web evolved beyond Yahoo Pipes, and it couldn't keep pace with the changes. Modern APIs, JSON-based services, and JS frameworks allowed developers to build similar data transformations programmatically with greater flexibility. Due to all these factors Yahoo Pipes was sadly shut down in 2015.

Can I still use it today?

Nope, it was shutdown by Yahoo in 2015, with no further support or hosting by Yahoo.

Modern Alternatives

While innovative at the time, visual mashups have been replaced by:

Dedicated data transformation tools (e.g. Zapier, Integromat/Make).
Serverless functions (AWS Lambda, Azure Functions, Cloudflare Workers, and Fastly Compute@Edge) for real-time data processing.
Low-code platforms with integrated API management.

The web has also become a lot more complicated regarding Web scraping and feed aggregation. Because anti-scraping measures, authentication, and API rate limits weren't necessary when Yahoo Pipes was created, the techniques it employed didn't support the robust backend processes now required to handle these requirements. Although Yahoo Pipes was innovative at the time, it has long been discontinued and is now considered a obsolete part of web platform history.

PhoneGap / Apache Cordova

The one thing that sticks in my mind when I think about PhoneGap is when I saw a talk from one of the Nitobi engineers back in 2009 / 2010, he said something along the lines of:

We are using PhoneGap to bridge the current gap for developers in creating cross-platform mobile applications. Our goal is for it to become obsolete once native platforms fully support these capabilities.

This really impressed me at the time, spending so much time on a product with the aim for it to become obsolete.

What was PhoneGap?

PhoneGap was a mobile development framework created by a Canadian company called Nitobi in 2009, it was later acquired by Adobe in 2011. PhoneGap allowed web developers to build cross-platform mobile applications, simply, using web technologies: HTML, CSS, and JS. The applications were packaged into native containers allowing them to run as mobile apps, while also having access to device API's via JS.

Why was it required?

At the time of release, the mobile web was incredibly popular and getting bigger month on month. It's important to remember, the first version of the iPhone was released only 2-years before (June 2007). This really was an exciting time in the Web Platform's history. If you wanted to release a cross-platform application at the time and wanted to support Android, iOS, and Windows Phone, you needed developers with knowledge of multiple programming languages:

Android required Java.
iOS required Objective-C.
Windows Phone required C#.

Finding a single developer with all these skills would be incredibly hard, so to build and maintain all 3 platforms usually required a whole team of developers.

One of the main advantages of PhoneGap was that all 3 platforms had a single central codebase, which reduced development time and maintenance.

PhoneGap leveraged Cordova under the hood, which it essentially branded and wrapped for broader adoption.

Why is it outdated?

PhoneGap apps performed poorly. This was especially true for graphics-intensive, or animation-heavy interfaces. This is because PhoneGap apps ran within a WebView container rather than as a native application.
Adobe stopped supporting it. This seems to be a common theme in this blog post… Adobe ended support for PhoneGap in October 2020. At the time developers were advised to either migrate to Apache Cordova or consider other frameworks.
Alternatives evolved. As the mobile platform expanded, so did the availability of other frameworks to help developers build apps. These alternatives included:
1. React Native allowing near-native performance with JS and React paradigms.
2. Flutter enabling high-performance apps with a single Dart codebase and native compilation.
3. Progressive Web Apps (PWAs) reducing the need for wrapping web apps as native apps in many use cases.
4. Capacitor (by Ionic) providing modern native bridging with a streamlined developer experience compared to PhoneGap/Cordova.
PhoneGap's Ecosystem growth stalled. As newer frameworks were released and Adobe stopped supporting it the community moved away and PhoneGap’s plugin ecosystem stagnated.

Can I still use it?

No, there are several alternatives I have listed above that you should consider instead. PhoneGap served its initial purpose as a bridge, enabling developers to build cross-platform mobile applications. As was its mission, It became obsolete when native platforms fully incorporated these capabilities.

Microsoft Silverlight

NOTE: I never used Silverlight (I do remember it being announced) I'm just adding it to the post for completeness.

What is Silverlight?

Silverlight was a rich internet application (RIA) framework introduced by Microsoft in 2007. It was conceptually similar to Adobe Flash, designed to deliver interactive multimedia, animations, and streaming video inside the browser.

It used a subset of the .NET Framework, with applications typically written in C# or VB.NET, and presentation defined using XAML (an XML-based UI markup language). Developers could reuse existing .NET skills, which made Silverlight attractive in Microsoft-centric enterprises.

Silverlight was often used for:

Media streaming (notably Netflix in its early streaming days)
Interactive dashboards and line-of-business web apps
Cross-browser, cross-platform plugins (Windows and Mac were supported, but Linux support lagged)

Why is it considered legacy?

Plugin dependency: By the 2010s browser vendors had moved away from browser plugins in favour of newly developed web platform technologies. Plugins were often unsecure, unstable, and inaccessible.
Limited cross-platform reach: Although Silverlight was well supported on Microsoft platforms (as you would expect!), it also had support on Mac, but it had limited support on Linux (via project Moonlight), and no support on mobile devices (Android, iOS).
Rise of open web standards: HTML5, CSS3, and JavaScript rose so rapidly for audio, video and advanced graphics (via canvas). The use of plugins was no longer required.
End of support: Considering the above points, Microsoft only stopped support in October 2021. Although Browser vendors stopped a long time before: Chrome in 2015, Edge never supported it. Firefox ended support in March 2017.

Can I still use it?

Well, this is another easy one. No, you can't Microsoft have dropped support and no Modern browsers support it either.

Modern Alternatives

The answer to this is basically native web platform API's. Specifics include:

Video Streaming
- HTML5 <video> element with adaptive bitrate streaming (HLS, MPEG-DASH).
- DRM is handled via Encrypted Media Extensions (EME).
For interactive apps and dashboards:
- Modern JavaScript frameworks such as React, Angular, Vue, or Svelte.
- WebAssembly (Wasm) for near-native performance, including options like Blazor (from Microsoft) which lets you run .NET in the browser without plugins.
For graphics, animation, and UI:
- CSS3 animations and transforms for UI transitions.
- Canvas API and WebGL for 2D and 3D graphics.
- SVG for scalable vector graphics.
- WebGPU (emerging) for modern GPU-accelerated rendering.

Silverlight Summary

Silverlight is legacy because it relied on a now-obsolete plugin model, had poor cross-platform support, and was outpaced by open web standards. Today, everything Silverlight did can be done more securely and portably with HTML5, CSS, JavaScript frameworks, and WebAssembly.

Java Applets

NOTE: I never used Java Applets (although I remember them!) I'm just adding it to the post for completeness.

What is Java Applets?

Java Applets were small applications written in Java that could be embedded into web pages and run inside the browser through a special Java Plug-in (based on the NPAPI plugin architecture). Introduced in the mid-1990s, they were part of Sun Microsystems’ vision of “write once, run anywhere” – letting developers build interactive content and complex functionality that browsers of the time (pre-HTML5) could not support natively.

They were often used for:

Interactive educational content and simulations
Online games
Financial tools like mortgage calculators or trading dashboards
Enterprise intranet applications

Why is it considered legacy?

Plugin dependency: To use the Applets this required a user to install the Java Runtime Environment (JRE) plugin and keep it updated. I distinctly remember the update prompt for these nuisance updates!
Security risks: The Java plugin was a frequent target of exploits and malware, leading browsers and enterprises to actively block or disable it.
Performance and user experience: Applets often loaded slowly, had inconsistent UI integration with web pages, and required clunky permission dialogs.
Decline of NPAPI support: Browsers started phasing out NPAPI (the plugin technology Applets relied on). Chrome dropped NPAPI in 2015, Firefox dropped NPAPI in 2017 (except Flash until 2021) , and Microsoft Edge never supported NPAPI.
Official deprecation: Oracle deprecated the Java browser plugin in Java 9 (2017) and removed it entirely in later releases.

Can I still use it?

Nope! Modern browser no longer support it and Oracle stopped supporting the plugin in 2017.

Modern Alternatives

This list is basically native web platform API's. I don't want to repeat myself so refer to the Silverlight Modern Alternatives from earlier in the post.

Java Applet Summary

Java Applets are legacy because they relied on a fragile plugin model that posed significant security risks and is no longer supported by modern browsers. Today, HTML5, JavaScript, and WebAssembly provide richer, faster, and safer alternatives without requiring any plugins.

5. The JavaScript Framework Explosion

DHTML Beginnings (1997)

Dynamic HTML (DHTML) was all the rage around 1997-1998. By combining the primary web technologies: HTML, CSS, JS, and the DOM, developers realised that they could make a web page interactive and "dynamically" update the page without the need to reload the entire page. This new technique was frequently employed for animated HTML elements, such as image rollovers and dynamic navigation menus. It also provided immediate user feedback, particularly for form validation, by checking if the user had entered a valid email, for instance. If not available, then use standard HTML and CSS to show a user-friendly error message.

DHTML wasn't necessarily bad, if implemented in moderation, unfortunately it always seemed like the wild-west. What would work in Internet Explorer 4 (IE4) wouldn't always work in Netscape Navigator because Microsoft and Netscape Communications Corporation (NCC), had different levels of support for JavaScript in fact, Microsoft had their own version of the ECMAScript standard called JScript. This led to lots of maintenance headaches for developers as the solution often involving forking code for different browsers.

Secondly it turned into a bit of Copy / Paste madness. Since any developer could simply "View Source" on a web page and copy the code and add it to their own website, you often ended up with a mishmash of different interactions and animations all over a website! Thankfully, the trend eventually died out!

Can I still use it?

A web developer could technically still use DHTML on the modern web, but doing so would be strongly discouraged for any serious or production-level work. This is because in using it, a developer wouldn’t be following modern best practices like separating concerns with structured HTML, CSS and JS, building accessible and performant interfaces, using modular and maintainable code, or leveraging modern frameworks and tooling that enforce consistency, security and scalability.

Modern alternatives

There are several modern alternatives to DHTML, including:

Using Frameworks like React, Vue, or Svelte
Native browser APIs
Modern CSS techniques
Progressive enhancement and accessibility standards

Early frameworks and libraries

Prototype.js (2005)

Prototype.js version 1.0 was released in February 2005, and was initially developed to help simplify JS tasks in Ruby on Rails (RoR) projects. Its key features were a host of DOM manipulation utilities, AJAX abstraction to make XMLHttpRequest easier to handle cross-browser, Class-based inheritance in the form of a lightweight object-oriented programming (OOP) in JS. But by far its most influential feature was its shorthand DOM element selector $(), later popularised by jQuery.

I remember trying to learn and use Prototype a few times, but as a JS beginner, I found the name confusing. Especially since the prototype object sits at the heart of JavaScript, with almost the whole language hanging off it through things like property and method inheritance.

Can I still use it?

I mean, technically you could, but be warned it hasn't been updated in almost 10-years! Given the significant evolution of JS and the availability of modern, updated alternatives that leverage the latest browser JS APIs, it would not be a wise choice.

Modern Alternatives

It really depends on what a developer was using prototype.js for, as it had quite a range of functionality:

DOM manipulation

AJAX

Utility functions

Templating

Full replacement

Prototype.js was incredibly powerful. My preference would be to utilise several micro-JS libraries for specific functionalities rather than adopting an extensive framework such as React, but that's just my opinion, given the complexity of the React ecosystem.

Script.aculo.us (2005)

Script.aculo.us v1.0 was released in 2005 as an extension to Prototype.js. It built on Prototype.js by delivering a powerful set of visual effects, animations, and UI components. It also featured Drag-and-drop support out of the box, as well as sortable lists and autocompletion widgets. As with Prototype.js, Script.aculo.us popularity was partly because it was bundled with RoR, and it had widespread adoption within the "Rails" community.

I still remember Script.aculo.us for its distinctive URL, its bright, animated homepage, and how it really embodied the spirit of ‘web 2.0,’ making the web feel more alive. It's a library that left a lasting legacy, influencing later libraries like jQuery UI.

Can I still use it?

I really wouldn't recommend it, as it hasn't been updated in over 15 years! However, if you're curious to delve into some web 2.0 history, the site is still live (on HTTP, not HTTPS).

Modern Alternatives

Assuming you are only looking for a JS library for animations:

Dojo Toolkit (2005)

Dojo Toolkit was one of the first major cross-browser toolkits, released in March 2005 with version 0.1. It was developed by Alex Russell and was also maintained by a community of other developers too. It's open-source and still available on GitHub It was one of the earliest frameworks to help build rich web applications by simplifying DOM manipulation, AJAX, event handling, animations and internationalisation (i18n), among many other cutting-edge features. Not only that, it was an early advocate for Asynchronous Module Definition (AMD) and modular JS. Furthermore, it was one of the first JS libraries with strong accessibility (a11y) support. In 2018 Dojo was rewritten as Dojo 2 which supports TypeScript, reactive patterns, virtual DOM, and modern build systems. Dojo 1.x is still in use in some long-running enterprise applications on the web. The last stable release was released in 2022, which was mainly for bug fixes and security updates. New feature development has now shifted purely to Dojo 2+.

Dojo 1.x was incredibly influential for later JS libraries like jQuery, MooTools, Prototype, especially when it came to governance. It was governed by the Dojo Foundation, which later merged with the jQuery Foundation to form the JS Foundation (now part of the OpenJS Foundation).

Can I still Use it?

Version 1.x, would be a bad idea, but you could technically still use the latest version (8.0.0), although that may not be wise either, given there hasn't been a new release in over 3-years. So it's most likely better to stick with more modern framework alternatives.

Modern Alternatives

There are a number of modern alternatives you could consider, keeping in mind that Dojo was very focussed on Accessibility (A11y) and Internationalisation (i18n):

React: Maintained by: Meta (Facebook).
- A11y: Strong support, but it’s developer-driven. ARIA roles and keyboard navigation must be implemented explicitly by developers.
- i18n: Excellent ecosystem (react-intl, formatjs, lingui, etc.)
Vue.js (v3): Maintained by: Evan You and the Vue core team.
- A11y: Good defaults; still developer-led, but accessible components are emerging.
- i18n: vue-i18n is well-maintained and powerful.
Angular: Maintained by: Google
- A11y: Arguably the best among mainstream frameworks. The Angular Material team publishes a11y guidance, and many baked-in best practices exist.
- i18n: Built-in i18n support, including message extraction and compile-time translation.
Svelte / SvelteKit: Maintained by: Rich Harris and the Svelte core team
- A11y: Improving, but not as mature as React or Angular. Accessible components need to be explicitly chosen or built.
- i18n: Community libraries exist (svelte-i18n), but official support is not as comprehensive.

Yahoo! User Interface (YUI) (2006)

YUI was released in February 2006, its first release was version 2.0.0, this is because there was lots of internal development and usage within Yahoo! before it was released publicly. It was originally designed to standardise frontend development at Yahoo and provide the team with a solid cross-browser solution on which the Yahoo team could build feature-rich web applications. It contained a custom loader system that only loaded the components it needed, this was an ingenious approach in the pre-ECMAScript 6 (ES6) module era. Furthermore, it also came with a whole host of feature rich UI widgets, cross-browser abstraction, Event handling, DOM utilities, Animations, CSS Tools (which heavily influencing Normalize.css that was developed later), and it was one of the first libraries (after Dojo 1.x) to prioritise internationalisation (i18n) and accessibility, specifically Accessible Rich Internet Applications (ARIA).

What I remember most about YUI 2.x is just how huge it was! Not just the sheer number of UI modules, but the file size too: 300–350 KB minified, or 90–120 KB gzipped! This was before the widespread availability of fast broadband, and when hardware and browsers were significantly less optimised. A full build of the library could easily exceed those figures, too. This is why Yahoo also provided a combination aware CDN service to help reduce the number of requests made and bundle only the components needed. This was a practice that was way ahead of its time!

Can I still use it?

No, not really, it hasn't been updated since 2014, the reason for this is detailed in this Yahoo Engineering announcement from the time.

Modern alternatives

Given YUI's extensive nature as a framework, and to avoid repetition, I recommend referencing my notes on Prototype.js modern alternatives as an initial guide.

moo.fx (2005)

Moo.fx was a lightweight animation library designed to be unobtrusive and it also worked well with Prototype.js. It focused purely on DOM animations like height transitions and fading etc. It was part of a movement in JS to modularise the codebase for lighter and more responsive interactions. Furthermore, it was a distinct diversion away from larger and heavier animation libraries like Script.aculo.us.

I believe moo.fx was one of the first animation libraries I ever saw. Annoyingly the site hasn't been archived on archive.org. I do remember it having a simple and colourful homepage with examples of the animations you could add by only adding a tiny library to your page (3 KB).

It also had a fantastic URL too "http://moo.fx". What's so cool about the name, you may ask? Well, the .fx country code top-level domain (ccTLD) has now been rendered obsolete and is no longer available. It was originally reserved for Metropolitan France, but it was never officially delegated or made available for registration. France later adopted .fr as its official ccTLD. I can't fathom how Valerio Proietti, the creator of moo.fx, managed to register the name, but it's all true. As proof only a single record can be found on archive.org, dating back to 2007, it links to the site's robots.txt file.

Can I still use it?

I can't even find an archived copy of the homepage, let alone the library itself! So, it definitely falls into the "no, you can't still use it" category!

Modern Alternatives

Assuming we are only looking for a modern animation library, it's best to refer to the list I gave above for Script.aculo.us modern alternatives.

MooTools (2006)

The author of moo.fx, Valerio Proietti wanted more than an animation library. He aimed to develop a complete JS framework with an Object-Oriented Programming, modularity and extensibility as first-class features. Thus, MooTools was born! v1.0 was released in September 2006, and it featured some fantastic features for its lightweight size. These included a modular core, and separate components, you could also include, for extra functionality, an Advanced class system (predating the ES6 class functionality). Powerful DOM manipulation utilities, Ajax handling, effects (moo.fx), and custom events. It was both performant (for the time) and syntactically elegant. Development ceased in the mid-2010's with v1.5 (the final active release). moo.fx and MooTools hold a special place in my memory as one of the first JS libraries I learnt as a Junior developer.

Can I still use it?

Well, the website still exists here, But considering it hasn't been updated since January 2016, it's probably best to look for a modern alternative.

jQuery (core) (2006)

In 2006, a truly revolutionary JS library was released called jQuery. It was developed by the legendary John Resig. It offered a lightweight, chainable API in JS to simplify tasks like DOM traversal, and Ajax, among many other helpful tools and methods in its fantastically written API.

jQuery always prided itself on its easy-to-use API and its ability to abstract away the many cross-browser bugs related to different browser vendors implementation of JS (Mozilla) / JScript (Microsoft). It finally gave developers a "stable" API to start building JS powered websites without all the stress of the cross-browser hacks, and forking of code to make features work in every browser. With jQuery, it just worked!

I must admit, I absolutely adored jQuery (and still do)! The API was so clean and readable. The complete opposite to the DOM and the JS API! This library has saved more than just my code, it’s rescued entire projects and probably saved my sanity in the process! Especially working in Digital Marketing, as I did at the time. In those days, clients were constantly after the newest, flashiest animations, regardless of usability. It was all about chasing trends. And when the client's paying, you just nod and make that already bouncing button pulse and change colour!

Can I still use it?

Finally, I can say "Yes" to this question! Assuming you plan to use v3.x of jQuery, as the 1.x and 2.x branches are no longer supported or maintained. In fact version 4.0 is currently in beta, according to the Support page. Amazingly, almost a full 19-years after its first release, it is still under active maintenance! Not only that, according to the Web Almanac 2024, it's still the most popular JavaScript library in use on the web! Truly impressive work by the jQuery team and community!

Later era frameworks

Ext.js (2007)

Ext.js version 1.0 was released in April 2007. It was initially developed as an extension to the YUI Library before becoming a fully standalone framework. Its key features included a comprehensive suite of rich UI components, a powerful event model, and advanced layout management capabilities that far exceeded most contemporaries. It introduced a highly structured approach to building web applications, with a strong emphasis on reusable widgets and object-oriented design. But by far its most distinctive contribution was its fully integrated, desktop-like component model for the web. Something rarely seen at the time, and which set the tone for many enterprise-grade JS frameworks that followed.

I never used YUI personally, as its sheer size and breadth of functionality simply didn’t align with the kind of work I was doing at the time. As a result, Ext.js (which as mentioned above, was initially built upon YUI) wasn’t on my radar either. That being said, I’ve included it here for completeness, as it clearly played a significant role in the evolution of rich client-side application frameworks. During my research I discovered how Ext.js transformed into an enterprise-grade toolkit under the Sencha brand. Its strong emphasis on data-driven UIs distinguished it from other lightweight libraries of that period.

Can I still use it?

Yes, Ext.js is still a viable option that you can use on the modern web, if you are building a web application. It continues to be actively maintained by Sencha and even offers a React Extension, allowing for seamless integration of Ext.js components into React applications. However, be aware that Ext.js is now a paid library, with a per-year, per-developer licensing model that can be costly. While a free community version exists, it appears to have a very limited feature set.

jQuery UI (2007)

jQuery UI emerged in 2007 as an official companion library to jQuery, at a time when the JS ecosystem was fragmented and riddled with browser inconsistencies. It was developed to bring a unified, extensible suite of widgets, effects, and interactions to the web. jQuery UI offered an easy-to-integrate API that drastically lowered the barrier for implementing rich UI's, with full cross-browser compatibility. It played a crucial role in making dynamic front-end behaviour accessible to developers at all skill levels, becoming a staple in both enterprise and amateur hobbyist applications during the formative years of modern web development.

Although I was a big fan of jQuery and used it extensively across many projects, I never really had the opportunity to use jQuery UI in its entirety. When I did, it was typically for a single component, such as a date picker or drag-and-drop functionality. These components were reliable and well-supported, but required a lot of JS to function, and added complexity that I never felt was acceptable for a single feature. Especially when there were plenty of alternative micro-frameworks available, offering small, focused libraries that solved one problem well. I was far more inclined to take that modular approach than to include an entire suite of UI components unnecessarily.

One resource, I found invaluable at the time, was MicroJS. It hasn’t been updated in quite some time, but it remains a powerful illustration of how easy it is to cherry-pick the exact only the functionality you need, without burdening your page with hundreds of kilobytes of JS.

Can I still use it?

For this question, just as I did with jQuery, my answer is yes, you can still use it. It isn't updated very often, but it is still updated! The last release being in October 2024 with version 1.14.1

To put the enduring popularity of jQuery and jQuery UI into perspective, the 2024 Web Almanac reports that jQuery is still the most-used JS library on the web, appearing on 74% of pages in the dataset analysed. jQuery UI comes in fourth, with a 22% usage rate, Though described as mostly deprecated, it’s a clear reminder of how quickly modern tools become legacy software that must be maintained for decades. The latest release came nearly 18 years after jQuery UI’s first version. That’s an incredible achievement by the jQuery UI team, talk about dedication!

AngularJS (2010)

AngularJS and Angular are fundamentally different frameworks that share a name and lineage but are otherwise entirely different. AngularJS (1.x) was based on a Model-View-Controller (MVC) architecture with two-way data binding written in JS with support for ECMAScript 5 (ES5) and some ECMAScript (ES6) features. Angular (2+) was built entirely differently, it has a component-based architecture boasts stronger modularity, enabling both two-way binding and promoting unidirectional data flow. Another major difference is that Angular is written in TypeScript, a distinct superset of JS, that enables better tooling and type safety like Java and many other languages. Angular remains actively used and maintained on the modern web today.

I distinctly remember when Google released AngularJS because I was in Melbourne, Australia, working at a digital media agency. One of the Tech Directors there was raving about it, and how it was going to change Frontend development entirely. In hindsight, I agree with him, but I, personally, don’t believe it was a positive change. Single Page Apps (SPA’s) have had such a huge negative impact on Web Performance and Accessibility. Plus, a lot of the code in many of these SPA frameworks essentially reinvents functionality that’s already built into the browser and the Web Platform as a whole. Let's not overcomplicate things with framework-managed page state; we have a perfectly good back and forward buttons, thank you very much!

As you can probably tell, I’m not a big fan of SPA's. Admittedly, they have their place under some circumstances; However, I genuinely think they're excessive and unnecessarily complicate frontend web development for most applications. But I guess complex is the new simple, right? Anyway, rant over!

Can I still use it?

AngularJS, no. It is no longer actively maintained. Angular, absolutely, it is still a very popular framework on the modern web, although according to the State of JS 2024 survey, it has been overtaken by Vue.js for usage, for the 2nd year running. Frontend developers can be fickle, often chasing the next shiny framework like a kitten distracted by a dangling set of keys. It will be interesting to see if this decline in Angular usage continues in future JS surveys.

Backbone (2010)

Backbone.js was released in 2010 by Jeremy Ashkenas, who also created Underscore.js and CoffeeScript. As with AngularJS it was one of the first JS libraries that implemented the MVC architecture pattern to client-side JS. The key features of Backbone were its models, collections, views, router, events, and sync functionality that allowed it to easily communicate with RESTful API's.

I've only ever worked on a Backbone project once, and it was a rapid prototype website for a major airline based in Asia. Given the tight timelines and the client’s high design expectations, we ultimately opted for static HTML in the end, as Backbone’s complexity wasn’t advantageous for a rapid prototyping. In hindsight, had it got to the production stage, then I could see the architecture of backbone being very useful.

Can I still use it?

Backbone is nowhere near as popular as modern frameworks like React, Vue, or Angular, It is still mostly in use on legacy systems. The last version released was in April 1st 2025 v1.6.1, but looking through the releases, it seems to only get 1 update per year. According to Wappalyzer it is still in use by around 521,000 websites. The biggest of those being Atlassian. So in my opinion I'd say you should avoid using it and opt for a more popular framework with a more active community. Refer to the modern alternatives I listed for Dojo Toolkit Modern Alternatives as a starting point.

Knockout (2010)

During the early 2010s, Knockout.js was a popular JS library for building dynamic UIs using the Model-View-ViewModel (MVVM) pattern. It offered features like declarative bindings and two-way data synchronisation, which made it easier to keep the UI in sync with underlying data without manually manipulating the DOM. Its simplicity, ease of learning, and lack of required tooling, e.g. just drop in a <script> tag into an HTML page and go, this made it especially appealing at a time when frontend complexity was just beginning to accelerate. Though now largely superseded by modern frameworks, Knockout played a key role in the evolution of reactive web development.

I only used Knockout once for a client in Australia, while I lived there. It was a project that had been passed between offices because it had become a maintenance nightmare. Had it been a better planned build, it would have been a more pleasant experience, but time constraints meant a rapid delivery was prioritised over build quality.

Can I still use it?

The last release was way back in November 2019, so there's no way it should be used on a modern website build. Although, according to Wappalyzer it is still used by almost 43,000 websites. So you are very unlikely to come across it, even in legacy systems.

Modern Alternatives

If you are looking a modern MVVM framework then Vue.js, Svelte, or Aurelia are the way to go as the all fully support the MVVM architectural pattern. But if you aren't bothered about MVVM then refer to the list of modern alternatives I listed for Dojo Toolkit earlier in the post.

6. CSS Workarounds and Browser Quirks

Old CSS practices

Sliding Doors Technique

In the time before border-radius: existed in CSS, this was a legitimate way of “faking” the look of rounded borders. The technique's name reflects its implementation and purpose. (nothing to do with the 1998 film starring Gwyneth Paltrow about getting cheated on!). It was actually a rather ingenious method of creating rounded corners that expanded and contracted both in width and height of the bounding box containing the content. It was also incredibly useful for making your site navigation more interesting. If you are interested in reading all about this technique, check out "Sliding Doors of CSS" and "Sliding Doors of CSS, Part II" on alistapart.com both from October 2003!

If you are old like me, you can just jump back into full nostalgia mode by visiting the final code example here!

Can I still use it?

There's absolutely no need to use it on the modern web, simply use the border-radius CSS property, it comes with all the positives of the sliding door's technique (rounded corners), and none of the negatives (higher maintenance, additional downloads, non-semantic wrapper DIVS used only for presentation). And given its browser support on the modern web, you can go rounded corner crazy!

Image Sprites for Icons

The history of icon sprites is actually quite a fascinating one (for me at least!), since it is essentially rooted in web performance optimisation. The HTTP/1.1 specification (RFC 2616) published in June 1999, specifically says in section 8.1.4 that:

Clients that use persistent connections SHOULD limit the number of simultaneous connections that they maintain to a given server. A single-user client SHOULD NOT maintain more than 2 connections with any server or proxy.

HTTP/1.1 introduced persistent connections, a departure from the one-off connections of HTTP/1.0 (as detailed in section 8.1 of the HTTP/1.1 specification). This innovation understandably raised concerns within the Network Working Group regarding potential increases in server load across the web.

The web was becoming more and more popular every day around that time, with thousands of new websites being launched daily. Remember the Dot-com Bubble that burst in March 2000, it gives you some indication of just how popular the internet had become across the world!

You're probably thinking "what has any of this got to do with image sprites?", well, quite a lot, actually. With HTTP/1.1, every asset on a page meant opening a new TCP connection. So if your site had hundreds of icons, the browser would literally open hundreds of separate connections just to fetch them all (assuming it were allowed to)! And this is why browser connection limits were introduced into browsers. Different browsers chose different limits, but it was usually around 4 to 6 per domain. So in order to reduce the number of TCP connections to download all these image assets, a technique called Image Sprites was invented.

Image Sprites, involved compiling all your small image assets down into a single bigger background image file, then using CSS positioning (and width / height) to essentially mask the image and only show the single image you wanted to show in any particular place. It then only required a single TCP connection to download all the small images (one large image with all the icons), and you'd use some CSS magic to just reposition the background image. This technique was mostly used for image icons, and the CSS for this method would look something like this:

.icon {
  background-image: url('sprite.png');
  background-position: -20px -40px;
  width: 16px;
  height: 16px;
}

Here we have an icon that is 16px by 16px and the icon we want to show is positioned at -20px -40px on the background image. Genius! A working example of image sprites can be found here on CodePen.

Can I still use it?

Again, no need. Image sprites fell out of favour as a technique when more modern techniques like SVG sprites and webfont icons came along.

The technique was also outdated by new web performance technologies like:

But those are topics for another blog post, which I just so happen to have written a little about, so check them out (shameless self-promotion, sorry!)

Vendor Prefixes for CSS

Now I'm pretty sure some readers will be thinking, wait "vendor prefixes for CSS are old best practice??". They really aren't as they are a vital technique to stop new CSS additions from "breaking the web". By slapping on a vendor prefix to a CSS property allows browser vendors to experiment with new CSS features in isolation and then once stabilised in the CSS specifications, and supported by the major browsers, the prefix can be removed in favour of the non-prefixed version. For example, -moz-border-radius changes to border-radius. So just to clarify vendor prefixes aren't old best practice, but the way they are created within website code is. In the distant past you used to have to manually write out each of the prefixed versions to ensure maximum compatibility with all browsers. Can you imagine writing this out manually for all new CSS features you want to use! Example:

.mybox {
  -webkit-border-radius: 10px; /* Chrome, Safari, iOS Safari (early versions) */
  -moz-border-radius: 10px;    /* Firefox (pre-version 4) */
  -ms-border-radius: 10px;     /* Not officially supported, but some old syntax examples include it */
  -o-border-radius: 10px;      /* Old Opera (Presto engine, now obsolete) */
  border-radius: 10px;         /* Standard syntax */
}

What a waste of bytes and time! (I know compression pretty much fixes the bytes issue!) With the popularity of tools like Compass (a Sass Framework), LESS mixins, and Bourbon (a Sass mixin library), or even Stylus with the nib plugin, the issue started to be abstracted away from developers.

Can I still use them?

On the modern web there's simply no need to manually add prefixes. The best practice is to use PostCSS with Autoprefixer. Or if you’re using bundlers like webpack, Vite, or Parcel, they all offer out-of-the-box support for Autoprefixer. Rollup also supports Autoprefixer but requires a plugin. With the use of these tools along with Browserslist frontend developers don't even have to think about prefixes any more (once properly configured). An automation win for all developers!

Heavy Use of !important in CSS

In the early days of CSS the use of !important was a common practice for the enforcement of style overrides. It was often considered a "quick fix" for specificity issues, and used to fix visual inconsistencies in cross-browser scenarios or when using third-party CSS code. However, the overuse of !important is now widely considered a legacy practice that causes major issues with scalability, testability, and maintenance.

Can I still use it?

Yes, It can still be used in certain circumstances e.g. quick debugging, third-party overrides. But a rule of thumb I'd recommend is, if you are using !important for anything outside a small set of circumstances, you likely have bigger problems that need to be addressed first. As having predictable specificity in CSS is critical for the long term "health" of any web UI. Its use is a clear red flag that the project may be difficult to work on, as it’s a distinct frontend code smell.

That being said, If you ever do need to use it, you should clearly document the reason(s) why in the code, so future developers clearly understand why. Without clear documentation on why it is being used, a future developer is likely to remove this legacy CSS practice due to its reputation, potentially disrupting page styling elsewhere on the website.

OldIE hacks

For anyone lucky enough to have missed the joy of building websites for IE 5, 5.5, and 6 (the browser trilogy nobody asked for, released between 1999 and 2001), rest assured, that statement is absolutely, definitely not sarcastic at all. Promise! These versions of IE were just terrible browsers to work with. Microsoft in their infinite wisdom were following their own interpretation of the browser standards that were still in their infancy, and this often creating proprietary features that no other browser vendor followed or implemented.

Bundled with Windows XP, the popular IE6 unfortunately held back web progress for several years. Its standalone release for Windows 98, Windows ME, Windows NT 4.0, and Windows 2000 further cemented its widespread adoption and prolonged influence across the web. This forced Microsoft to innovate in the browser market, or face obsolescence, when a viable and revolutionary competitor finally emerged to finally move the web forwards! Initially launched in 2002 as Phoenix 0.1, a name symbolising its rise from the ashes of Netscape Navigator 9.0.0.6, this browser was renamed Firebird in early 2003, and later that same year became Firefox, the name it retains today.

And as an avid Firefox user for many years, I'm still delighted it is still around as it has its own HTML engine called Gecko. As the modern browser market is very WebKit / Blink dominated. Competition in this area is always a good thing to help drive innovation, and move the web forwards!

So, enough of the dusty old history books, what was so bad about IE6? Oh, dear, where do I even begin? It was less "web browser" and more "digital dumpster fire" with a whole host of issues and annoyances listed below. As for the "Can I still use it?" section, trust me you wouldn't want too! oldIE is thankfully about as common on the modern web as seeing a third-party script that improves web performance! Let us have a look at many oldIE issues in all their glory:

DOCTYPE fragility

If there was a single character before the DOCTYPE in IE6 it would trigger quirks mode (see the Quirks Mode Layouts section earlier in the post for a more detailed explanation). This even included newline, comment, space, or invisible byte characters. As you can imagine this was a nightmare for debugging. And if you weren't in full control of your HTML coming from the server, you were in for a bad time! Quirks mode essentially set the browser into the legacy rendering mode (mostly IE5 behaviour). If that wasn't bad enough, it would also interpret the Box model differently, causing chaos for layouts! Lastly CSS and layout behaviour would be inconsistent or in some cases, totally broken!

zoom: 1 hack

The zoom: 1 hack forced an element into the "hasLayout" rendering mode, which was a proprietary internal rendering concept in IE6 and IE7. For any element that didn't “have layout”, it could:

Collapse when floated
Break rendering of child elements
Overflow improperly
Fail to clear floats
Interrupt margin collapse

I distinctly remember using zoom: 1 a lot with float layouts, which was the main option for CSS layouts at the time. As mentioned above the element would then clear floating elements and also overflow elements correctly.

Underscore Hack

This was a pretty simple hack to target only IE6 and IE7 in quirks mode, any property prefixed by an underscore is ignored by modern browsers, but recognised by IE6 and IE7.

.selector {
	_width: 500px /* targets IE6 / IE7qm */
	width: 500px /* modern browsers */
}

Asterisk Hack

Another simple hack to target IE6 and IE7 that is ignored by modern browsers. It was especially useful for fixing box model issues.

.selector {
	*width: 100px /* targets IE6 & IE7 */
	width: 100px /* modern browsers */
}

Star HTML Hack

A slightly different hack that was added to the start of the selector rather than a property within a selector. It would only target IE6 in standards mode (not quirks mode).

html .selector { /* all browsers including IE6 */
	margin-left: 50px;
}
* html .selector { /* IE6 only - order is important */
	margin-left: 0;
}

Note: The order of the above code is important since IE6 could read both selectors but the second one "wins" due to its position in the cascade.

Child Selector hack

Another straightforward hack to target ONLY modern browsers (not IE6) was:

ul > li { /* not understood by IE6 & IE7 */
	color: rebeccapurple; /* "rebeccapurple" not understood by IE6 & IE7 */
}

IE6 & IE7 didn't understand the child selector, so it simply ignored it.

Note: the colour is also historically significant in the web community as the rebeccapurple CSS color keyword was added as a tribute to web pioneer Eric Meyer's daughter Rebecca who passed away of brain cancer at the age of six. Eric, if I’m ever lucky enough for you to see this post, please know that as a brain cancer survivor myself who has personally seen the impact this terrible disease has on friends and family, my heart truly goes out to you and your family. I am so sorry for what you’ve all been through. Rest in peace, Rebecca.

Double Margin Float Bug

This is a pretty aptly named CSS bug fix, as it does exactly what it says on the tin! Due to IE6's crazy box model interpretation it sometimes liked to double the margin on floated elements.

.floated-element {
	float:left;
	display: inline; /* fix the double margin bug in IE6 */
}

Peekaboo bug fix

IE6 sometimes threw its toys out of the pram when content changed on the page, in these cases it would either render them incorrectly or just make them disappear, hence the name peekaboo!

To fix it, you had to apply "hasLayout" to the element:

.buggy-element {
	zoom: 1; /* trigger hasLayout on the element to fix the peekaboo bug */
}

Transparent PNG fix

IE6 was unable to display the alpha channel (transparency) in PNG files, instead it just interpreted it as a grey, solid background. Combined with rounded corners on a non-solid background colour background, this was a real pain in the backside! Thankfully, IE6 supported CSS filters, allowing Microsoft to offer its proprietary AlphaImageLoader for PNG transparency. There were 2 methods to apply this filter:

.transparent-png {
	behavior: url("iepngfix.htc");
}

The .htc file contained JS logic that dynamically applied Microsoft’s proprietary filter to the PNG elements.

An alternative for background images was this:

.transparent-bg {
	background: none !important;
	filter: progid:DXImageTransform.Microsoft.AlphaImageLoader(
	src='image.png',
	sizingMethod='crop'
	);
}

Yep, how horrible is that! 🤮

But even if you solved the transparency issue your problems weren't over as its usage came with a few caveats:

AlphaImageLoader broke CSS background-position and background-repeat.
The fix didn't work on <img> tags unless additional .htc behaviour hacks were applied!
.htc files could be blocked fairly easily by companies with restrictive internet policies, so it wasn't always guaranteed to work. And if this happened to be one of your clients... well, there goes the whole design!
Lastly these hacks only worked in IE5.5 and IE6, thankfully IE7 supported transparent PNG's so these hacks had to be targeted at IE5.5 and IE6 only.

Lack of IE Developer Tools

I know the bugs above sound frustrating, but one of the biggest issues was the fact that IE6 and IE7 completely lacked any "sane" developer tools to help resolve these issues. Initially, developers had to rely only on alert() or document.write() for debugging! This was where the infamous [object Object] or [object] [object] came from when debugging JS in IE6 and IE7. If you had a JS error that you wanted to investigate, that was just about all the information you were given from alert(). Thankfully, Firebug Lite was released later by the Firebug Working Group. It wasn't developed by Mozilla and it wasn't a browser extension. It was a JS file that you could include in your page or as a bookmarklet to mimic the Firebug debugging tools. It was only later in IE8 that Microsoft included the first native developer tool in IE. You enabled it by pressing F12, it finally allowed developers to use the console functionality that we still use today. Interestingly, F12 to open the browser DevTools still remains the standard across most modern browsers!

IE Conditional Comments

Conditional comments were introduced into Internet Explorer in IE5, released in March 1999. They were introduced to Internet Explorer by Microsoft because IE had its own interpretation of HTML, CSS, and JS that diverged from W3C standards. This made it extremely difficult for Frontend developers to build consistent UI's that worked across all browsers, without resorting to complex and brittle CSS hacks as seen earlier in the post. Conditional comments allowed developers to have the best of both worlds, a fully W3C-compliant CSS file for modern browsers, and a CSS file that only applied to certain versions of Internet Explorer (that contained all the version-specific hacks!).

It's worth noting that each version of IE had its own specific hacks, so you'd often see multiple Conditional Comments in the <head> of a website after the W3C-compliant stylesheet (due to CSS loaded after the modern version taking precedence due to the cascade). The hacks were still there, but they were sectioned off into their own CSS file(s), ready to be removed when the browser was no longer used by the vast majority of site users. There were countless different ways to write conditional comments due to the version logic built into the interpreter. Note that modern browsers ignored them entirely as they were seen as standard HTML comments e.g. ().

Some example conditional comments can be found below:

<!-- Target only Internet Explorer 6 -->
<!--[if IE 6]>
  <link rel="stylesheet" href="styles-ie6.css">
<![endif]-->

<!-- Target IE 7 and lower -->
<!--[if lte IE 7]>
  <link rel="stylesheet" href="styles-ie7-and-below.css">
<![endif]-->

<!-- Target IE 8 only -->
<!--[if IE 8]>
  <link rel="stylesheet" href="styles-ie8.css">
<![endif]-->

<!-- Target IE 9 and above -->
<!--[if gte IE 9]>
  <link rel="stylesheet" href="styles-ie9-and-up.css">
<![endif]-->

<!-- Target any version of IE -->
<!--[if IE]>
  <script src="polyfills-for-ie.js"></script>
<![endif]-->

<!-- Exclude all versions of IE (i.e. target modern browsers only) -->
<!--[if !IE]> -->
  <script src="modern-browser-script.js"></script>
<!-- <![endif]-->

<!-- Combine conditions: Target IE 6 to 8 -->
<!--[if (gte IE 6)&(lte IE 8)]>
  <link rel="stylesheet" href="legacy-ie6-to-ie8.css">
<![endif]-->

Explanation of the Condition Syntax:

IE matches any version of Internet Explorer.
IE 6, IE 7, IE 8, etc. match specific versions.
lte = less than or equal to
gte = greater than or equal to
!IE = not Internet Explorer
- Note the use of the  to properly close in non-IE browsers. This was known as a downlevel-revealed comment.

As you can see from the complexity of the above examples it was fairly simple to target very specific and multiple versions of Internet Explorer. A significant drawback was the increased maintenance burden and the clutter they introduced within the sites' <head> tag.

Thankfully, Microsoft removed the parsing of conditional comments in IE10 and IE11 before they eventually introduced a whole new browser called Microsoft Edge. Edge initially used a proprietary rendering engine called EdgeHTML. However, the browser was subsequently rewritten to incorporate the same open-source engine as Google Chrome. This new version, based on Chromium 79, was released as Microsoft Edge 79 on January 15, 2020.

IE CSS Selector Limit

This issue, of all those detailed in this section, is arguably one of the most random, as well as one of the least noticeable! IE6 to IE9 had a selector limit of 4,095 selectors per stylesheet, now that may sound like a lot, but it was very straightforward to go over this limit, especially when grouping selectors. For Example:

/* This counts as a single selector */
.my-selector {
	margin: 20px;
}

That's all straightforward, but then you look at something like this:

/* This block counts as three selectors */
.button-primary, .button-secondary, .button-tertiary {
	margin: 20px;
}

Once you started grouping selectors for easier maintenance it became far too easy to hit the limit, especially on large websites. If you were a user of Bootstrap or Foundation at the time you could hit this limit unintentionally, without even knowing it!

And that brings me onto my next point: What happened when that limit was reached? Well... nothing really, IE just didn't parse any CSS beyond the 4,095 selector limit. Would it warn you that this was happening? Absolutely not!

Developers were often extremely fortunate if this issue was discovered through testing pages styled later in the stylesheet. Internet Explorer itself, however, would simply fail without any error messages or warnings.

And, to make it even more confusing: it would only impact the specific stylesheet that had exceeded the limit, not the page as a whole. For example:

<link rel="stylesheet" href="base.css">       <!-- 2000 selectors -->
<link rel="stylesheet" href="theme.css">      <!-- 4500 selectors -->
<link rel="stylesheet" href="overrides.css">  <!-- 300 selectors -->

In IE6 - IE9 this is what would happen:

base.css loads perfectly fine, it is under the limit.
theme.css only the first 4095 selectors are parsed, the rest are silently ignored.
overrides.csswould be load fully since it is under the limit.

This behaviour creates a partial styling issue. Elements relying on the theme.css file won't be styled correctly beyond the 4095 selector limit. In such cases, most pages will appear normal until a page attempts to utilise style selectors 4096 through 4500 from the theme file, at which point it will fail without warning. And of course if you were unlucky enough to be working with IE6 or IE7, then you had no developer tools to even debug the issue either!

Solution

So what was the solution? Well, with the invention preprocessors like Sass or tooling like Grunt, Gulp, or PostCSS they could automate the splitting of stylesheets at the 4065 limit.

Or another solution was to supply a simplified UI to IE browsers only and serve those CSS files via IE's Conditional Comments. But can you imagine the maintenance involved in updating multiple different stylesheets? Just for the slightest UI change!

The final approach involved reducing reliance on external stylesheets by inlining critical CSS directly into the <head> of the page, specifically for above-the-fold content (we’ll come back to that strategy later, as it’s not as relevant today). Even thinking about these different maintenance options, and their implications gives me a headache!

OldIE hacks Summary

As you can imagine CSS files around this time were a ~~bit~~ lot of a mess with all these random cross browser hacks and workarounds! Thankfully Microsoft recognised it was an issue so decided to implement conditional comments in IE5-IE9 to make this madness a little easier (in terms of organisation, not coding)

7. Markup of the Past

XHTML 1.1 and 2.0

I remember having a conversation with a friend about how he was converting his website into a new standard that had just come out, this was around 2001 and the new standard was XHTML 1.1. The most obvious difference at the time was the DOCTYPE at the top of the page source. From HTML 4.01 Strict:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
  "http://www.w3.org/TR/html4/strict.dtd">

to:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
  "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

What did XHTML 1.1 aim to achieve?

The goal of this new standard was to modularise XHTML and enforce stricter XML compliance. Its key features were the fact that it was based on XHTML 1.0 Strict but split into modules for better reusability and extensibility. It also required documents to be well-formed XML, and it enforced stricter syntax than HTML like all tags must close, and all attributes must be quoted.

Unfortunately, for XHTML 1.1 it came with a number of limitations that doomed the specification from the start. These included, very little browser support for serving XHTML 1.1 as application/xhtml+xml, it also, more critically broke backwards compatibility in many real-world use cases. And lastly many developers continued to write XHTML but serve it as text/html which entirely defeated the point of writing XHTML in the first place!

Because it never gained wide browser support and required a very strict syntax, it eventually became obsolete and is now mostly of interest for historical or academic reasons.

What did XHTML 2.0 aim to achieve?

XHTML 2.0 was never officially released or used in any production browsers. Had it done so, this would have been the DOCTYPE:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 2.0//EN"
  "http://www.w3.org/MarkUp/DTD/xhtml2.dtd">

Development began on the specification in the early 2000s with the key goals its key goals being:

a clean break from HTML 4 and XHTML 1.x.
planned to introduce entirely new ideas like replacing <a> with <h> for links.
high up on its priority list was for it to be device-agnostic and semantically pure.

The XHTML 2.0 specification ultimately failed for the following reasons:

It lacked practical browser support and Implementation.
HTML5 (developed by WHATWG) gained real traction by improving the existing HTML and maintaining compatibility.
And the gigantic final nail in the XHTML 2.0 specification was its complete lack of backwards compatibility. It broke the entire ecosystem of existing web pages and tools.
The W3C officially halted XHTML 2.0 in July 2009 and shifted efforts to HTML5.

This then brings us onto the modern standard still in use today, and finally a DOCTYPE that was easy to remember! Look how developer-friendly it is:

<!DOCTYPE html>

It is so simple in fact it is case-insensitive and doesn't require a cumbersome URI to the Document Type Definition (DTD), which was there to define the structure, rules, and legal elements and attributes used on a page.

Inline JavaScript

There are 2 distinct methods of using inline JS in an HTML document. They both have specifications in the HTML Standard (WHATWG).

Inline Script Block

The inline block is defined in section 4.12.1 The syntax is simple and familiar. An example usage is as follows:

<!DOCTYPE html>
<html lang="en" class="no-js">
	<head>
		<meta charset="utf-8">
		<title>Title here</title>
		<script>
			document.documentElement.className = document.documentElement.className.replace('no-js', 'js');
		</script>
	</head>
	<body>
		<!-- The script can also be placed in the body too -->
	</body>
</html>

It's perfectly fine to use the inline script block in this way, and it in no way a legacy / outdated technique. But it does come with a few things worth considering before using it. Inline script blocks like this cannot be run async or defer, these attributes only apply when loading external scripts using the src attribute.

Can I still use it?

Yes, you can, but it comes with a few caveats. A script in this position in the <head> executes immediately and synchronously, and it will block page rendering until the JS code completes. So make sure you don't overload an inline script block as your website will pay the price in terms of frontend web performance.

Inline Event Handler or HTML Event Attribute

Inline event handlers are defined in section 3.2.6 and section 8.1 of the HTML Standard (WHATWG) Inline event handlers are now considered a legacy pattern in modern web development. This is due to several reasons, including the security risk posed by JS execution in the global scope, the potential for Cross-Site Scripting (XSS) vulnerabilities, and the way they clutter the code. An example of an inline event handler is below:

<!-- other page code here -->
<ul>
	<li><a onclick="alert('About clicked'); return false;" href="/about">About Us</a></li>
</ul>
<!-- other page code here -->

The simple example above captures the onclick event from the anchor, and instead of taking you to the about page which you would expect it simply brings up an alert box with the "About clicked" string.

There are other reasons why this technique is considered legacy too since they conflict with the principle of separation of concerns, and also make debugging, testing, and the implementation of accessibility best practices harder. Lastly, Content Security Policy (CSP) can also disallow inline event handlers unless explicitly allowed (another big security risk!).

Can I still use it?

No! Don't use this outdated technique to add JS interactivity to your page. Instead you should move towards external scripts and unobtrusive JavaScript. An example of which is given below:

<!-- other page code here -->
<ul>
	<li><a class="myclass" href="/about">About Us</a></li>
</ul>
<!-- other page code here -->

// assuming the element.myclass is already in the DOM
const el = document.querySelector(".myclass");
el.addEventListener('click', () => {
	// Do JS stuff here!
});

This assumes that the myclass element is already in the DOM. If it isn't document.querySelector will return null and result in a TypeError. The safest way to get around this would be to use the DOMContentLoaded event. An example of this given below:

document.addEventListener("DOMContentLoaded", () => {
  const el = document.querySelector(".myclass");
  if (el) {
    el.addEventListener("click", () => {
      // Do JS stuff here!
    });
  }
});

If you're thinking that's a lot of code just to add a click event to a single element! Then you'd be correct, hence why libraries like jQuery were so incredibly popular for event additions and basic DOM manipulation.

Document.write()

I must admit, I don't think I've every actually used Document.write() on a webpage, that's probably because I've never seen a sane reason to use it! It's a JS method provided by the browser’s DOM, that allows you to write HTML or text directly to the page. A simple example is given below:

<script>
	document.write('<h1>Hello, world!</h1>');
</script>

Wherever this code is placed in the page, it will simply output a h1 with the content of Hello, world! Now there's a reason I was so harsh on the method above, and that's because it comes with some horrible side effects. These include the following:

As with any Inline Script Block, it blocks page rendering until the content is written to the page.
It runs synchronously and can block scripts and other resources from loading efficiently.
Lastly, and this has to be the best (and most horrifying feature!). If used after the page has fully loaded, it can erase the entire DOM and replace it with whatever was passed to the method. This would be <h1>Hello, world!</h1> in the example given above.
It's important to consider the security implications of its usage as it is similar to eval()(MDN link in some ways (but not all). Both methods can enable cross-site scripting (XSS) if user input is injected without sanitisation.

When should it be used?

On the modern web the simple answer is never! It's best seen as a historical curiosity that some legacy systems may still use that haven't been modernised yet. It could also be used in elementary educational examples or demos. There are a number of much safer (and robust) modern alternatives that should be used instead. These include:

element.innerHTML (MDN Link).
element.textContent (MDN Link).
document.createElement() (MDN link) in conjunction with appendChild and insertBefore.
Modern frameworks or libraries for manipulating the DOM and updating the UI.

Fixed Viewport Meta Tags

Fixed viewport meta tags were used in early mobile responsive development. An example of what it looks like is below:

<head>
	<title>My Fixed width Mobile Site</title>
	<meta name="viewport" content="width=320, user-scalable=no">
</head>

In the example above the viewport meta tag is telling the browser that:

This website should be rendered at a fixed width of 320px
It should disable user scaling, so the layout is locked to a specific dimension, regardless of the actual screen size.

Why use this approach?

In the early days of mobile development, desktop websites were very difficult to view and interact with on small mobile screens. In order to "fix" this issue, developers often built mobile specific websites, that would sit alongside the desktop website. 320px was a popular width at the time because the first iPhone (iPhone 3G) had a 320px size screen. In order to maintain maximum control over the layout appearance on these mobile devices, developers frequently prevented users from zooming into these sites. These restrictions also helped avoid layout shifts when loading in dynamic viewport sizes e.g. device orientation (portrait vs landscape), zoom or pitch gestures, changes in browser UI elements (address bar or toolbars).

Why was this bad?

There were a number of reasons as to why this technique was bad. The number one being it was terrible for accessibility. A user with a visual impairment, on a mobile site that disabled pinch-to-zoom (user-scalable=no), had no way to read the site's content. Secondly, by dictating a screen width, you are harming both adaptability and making assumptions about a user's device. Devices come in all shapes, sizes, and pixel densities. Mobile, tablet, desktop, and every resolution in-between. There are literally an infinite number of screen dimensions possible, obviously many of those would be impractical for users beyond a certain range, but it's impossible to maintain all these fixed versions so this technique quickly become outdated. Lastly, fixed sizes can lead to performance issues, as they may cause unnecessary UI reflows and repaints when used with older layout methods such as tables or fixed-position elements.

Modern Best Practice

With the development of responsive design practices by Ethan Marcotte in 2010 (Responsive Web Design: A List Apart), fixed layouts quickly fell out of fashion, as with responsive design, you could develop a single UI that worked on all devices, no matter what their screen size or pixel density. One UI to rule them all! It comes with the huge advantages of much less maintenance for developers, and more importantly a huge usability for all users, no matter what device they are viewing a website on. The recommended viewport meta tag for modern websites is this:

<meta name="viewport" content="width=device-width, initial-scale=1">

This tells a user's browser:

to match the screen’s actual width (width=device-width).
to set the base zoom level (initial-scale=1).
to allow users to zoom the viewport (user-scalable=yes this is default if not set)

You may come across fixed layouts in legacy applications, and if you do, you should seriously consider:

Replacing fixed tags with scalable ones.
Refactoring CSS layout logic to use flexible grids, fluid typography, and media queries.
Ensuring accessibility standards are upheld, especially zooming support (up to 200% as specified in WCAG Success Criterion 1.4.4).

Web Safe Fonts Only (before @font-face)

Fonts are arguably the most crucial component of the web. Without them, there would be no content, and consequently, no internet. This fundamental importance explains the extensive nature of the CSS Fonts Module Level 4 documentation. Fonts present a challenge due to their vast variety and subjective nature. What one person finds legible, another may not.

Web-safe fonts are typefaces that are broadly supported and consistently rendered across most web browsers and operating systems, eliminating the need for users to install additional fonts. They are distinguished by three primary characteristics:

They come pre-installed on most devices across all operating systems (Windows, macOS, Linux, iOS, and Android).
They render consistently across browsers, devices, and operating systems.
If a font isn't available on a certain device, there's a viable alternative that can be used by default, this is called "fallback safety".

A common fallback font family using the font-family CSS property is displayed below:

.class {
	font-family: Arial, Helvetica Neue, Helvetica, sans-serif;
}

According to CSS Font Stack this combination of fonts is supported by 99.84% of devices on Windows, and 98.74% on Mac. Notice how it gives the browser a list of fonts, the primary choice being Arial, and if Arial isn't available then Helvetica Neue will be used, all the way down to sans-serif. This is basically saying "if none of the preceding fonts are available, then choose any sans-serif font on the device". This guarantees that a font will always be available on any device, so even though different fonts will be used depending on the operating system, the page content will still be rendered and readable for all users.

Common Web Safe Fonts

Arial
Times New Roman
Verdana
Georgia
Courier New
Trebuchet MS
Lucida Console

The issue with these fonts is that they are very limiting, especially for the Design community. Designers have very strong opinions on fonts, it is their "bread and butter", after all, so that's to be expected! For years, both developers and designers have strived to integrate all fonts, not just web-safe ones, into web development. In doing so many people on the web came up with different ways to allow them to use non-web safe fonts. These include the methods I mentioned earlier in the post:

As mentioned earlier all of these methods worked, but they had limitations, be that with Accessibility, Performance, Maintenance, Security, or SEO.

In order to mitigate thes limitations, a modern, standardised method was required for browsers to load custom fonts.

Enter @font-face

@font-face is a CSS rule that allows web developers to load custom fonts on a webpage. Unlike the methods listed above it's a native browser feature that brings typographic control to the web, while also preserving Accessibility, SEO, Maintenance, Security, and Performance (if implemented correctly).

The @font-face rule has a notable history, as it was initially implemented by Microsoft in Internet Explorer 4 in 1997. At the time it used Embedded OpenType (EOT) fonts. This was a proprietary solution by Microsoft and not a part of the CSS standard at the time, so adoption outside of Microsoft browsers was non-existent. It wasn't until the W3C developed and standardised the CSS Fonts Module Level 3, that browser support across different vendors started to improve.

Although CSS Fonts Module Level 3 work began in the early 2000s, true standardisation took time as browser vendors adopted open formats like TTF, OTF, and later WOFF and WOFF2. The CSS Fonts Module Level 3 was not released as a W3C recommendation until September 2018. The first CSS Fonts Module Level 3 working draft was published in July 2001.

Usage

So how do we actually use @font-face? Well, it's pretty straightforward:

Declaring the font

@font-face {
	font-family: 'MyFont';
	src: url('/fonts/myfont.woff2') format('woff2'),
	   url('/fonts/myfont.woff') format('woff');
	   /* other font formats here */
	font-weight: normal;
	font-style: normal;
}

Although you can define other font formats, this is no longer recommended, since the combination of WOFF and WOFF2 will cover all popular browsers. In fact, depending on your user analytics data, you may even be able to drop to only listing WOFF2, since it is now supported by 96.2% of browsers used on the internet according to Can I Use.

Using the Font

body {
	font-family: 'MyFont', sans-serif;
}

Here is where we apply the custom font to the page elements using standard CSS selectors.

IMPORTANT: note how sans-serif has also been set as a fallback e.g. later in the font list. This is best practice because we are loading an external font file to render the text on the page. If this font no longer exists on the server (or simply fails to load), users will be left with no text, since the external font is missing. This ensures that even if the custom font isn't available it will "fallback" to an appropriate web safe font.

Now there are a number of web performance points that should be considered when using web fonts, but I won't go into them here. Instead, I will point you towards Zach Leat's excellent "The Five Whys of Web Font Loading Performance" article from November 2018, and it also links to his Performance.now() conference talk on the same subject. Well worth a watch if you have a spare 46 minutes!

8. Tools and Workflow Relics

SVN (subversion, largely replaced by Git)

SVN (Subversion) is a centralised version control system that was widely used in the 2000s and early 2010s. It was the first versioning system I used at one of the digital agencies I worked at in the late 2000s. The memories that stick with me most about SVN are:

Every folder and sub-folder had an annoying .svn directory within them. This directory contains all the metadata needed by SVN to manage the versioned files.
Branching and merging in SVN was a painful experience!

Although in all honesty, I haven't used it in over a decade, so both these points may have changed and now be invalid? Actually, I doubt it for backwards compatibility with older SVN repositories.

The key word in the top paragraph above is "centralised". In a version control context that means that with SVN there's a single central repository that all version history and file management operations are built around.

In comparison, Git / GitHub are decentralised repositories. When you clone a repository onto your local machine you have the whole history of all the files, you can modify them while offline then synchronise with other developers code modifications once you're back online.

Legacy Development Practices

If SVN is being used in 2025, it could imply certain things about the codebase and teams working practices. These include:

The tooling being used is likely to be old (e.g. Eclipse plugins, shell scripts).
Continuous Integration (CI) / Continuous Development (CD) is likely to be very basic or missing entirely.
Due to the complexity of the branching and merging process in SVN, this type of workflow will likely be minimal if used at all!

Team Cultural Indicators

There are also red flags in terms of engineering culture if SVN is still being used. It typically indicates that:

The engineering team has a conservative engineering culture.
The team have a risk-averse attitude to change.
The team may have a backlog of technical debt that has accumulated over many years.
Recruitment of developers wanting to use SVN is likely to be challenging, as recent surveys indicate that SVN has 5.18% of the Version Control System (VCS) market share. It is second to Git that dominates with a 93.87% market share. This is also likely to impact retention of developers too, since Git / GitHub are the dominant tools in use in most industries (although, not all) in 2025.

What to look out for

Should you happen to encounter a project that still uses SVN for version control, you should:

Expect resistance to adopt modern workflows (e.g., GitFlow, CI/CD).
Investigate whether the tooling supports migration to Git e.g. git svn or if a full rewrite might be needed.
Evaluate whether SVN is tightly embedded in the build and deployment process.
Prepare yourself for recruitment and retention issues as mentioned above.

Migration

Assuming you've stumbled across a legacy project that uses SVN, and modernisation and migration is a goal for the project. It's worth knowing that:

SVN to Git migration tools exist (git svn or tools like SubGit), but edge cases can be painful.
You will likely need to retrain teams and completely refactor deployment automation.
Start with a small component or project to check see if modularisation is a feasible option.

Can I still use it?

TL;DR: Git / GitHub is the way to go, for modern web development best practice.

Chrome Frame

Chrome Frame was an ambitious project to bridge the gap between modern web standards and the many limitations of old IE versions (IE6 - IE8). It was released by Google as a plugin for IE in late 2009. It essentially embedded the Chrome browser engine into older IE versions, thus allowing the IE / Chrome hybrid to use modern web standards, modern JS frameworks, HTML5 features, all while still being compatible with an IE-centric environment. This proved particularly beneficial for larger enterprise organisations, which were reliant on older versions of IE due to legacy infrastructure and were unable to adopt more modern browsers.

While it sounded great in theory, unfortunately it came with a whole host of downsides, especially when it came to adoption. This included requiring admin access to machines in order to install the plugin, many companies locked-down the use of plugins due to the security risk involved in installation of 3rd-party code, lastly it introduced complexity for IT support teams and Quality Assurance (QA) teams due to the hybrid nature of the rendering engine.

Can I still use it?

No, as it was ultimately deprecated by Google in 2013, and support ended in 2014. The reasons for this were that web standards had improved and IE itself had improved with the release of IE9 and later. A significant change in browser releases was the move to "evergreen browsers". These browsers update automatically in the background, without user intervention. These browser releases were untethered from specific Operating system versions, apart from Safari being a notable exception.

Although Chrome Frame only saw limited success, it certainly helped initiate discussions on migrating from legacy browsers in large enterprise environments.

I distinctly remember when it was announced I thought it would solve all our IE problems (finally!). It was only when it was released that I realised there was no way it would be able to solve the issue because:

It was complex to install (e.g. required admin access)
The majority of users at the time using older versions of IE were likely neither technically capable nor even interested in installing it as a plugin.
1. Note: This isn’t meant to sound elitist, but at the time, most people would have likely identified the internet as the "blue ‘e’ icon" on their desktop. Outside the web development community, few knew (or cared) what a web browser was, let alone which one they used! And I'd say this statement is most likely true with the modern web too!

CSS Resets

Before we get into the details, what is a CSS reset? It's essentially a set of CSS selectors and properties that are used to "reset" all styles across browsers to a common baseline. Think of it as a solid foundation on which to build your website off. In theory if all browsers render elements identically from the start, then the site will be easier to build and maintain because all those nasty minor cross-browser CSS differences will have been dealt with, that's the theory anyway.

Just to be clear, CSS resets are still around, but they have evolved into something more forward-thinking, minimal, and only focussed on common pain points. The first CSS Reset to be released in January 2007 was Eric Meyer’s classic CSS Reset, it quickly became one of the most widely adopted resets to try to standardise styling across the modern browsers at the time, these were Internet Explorer, Firefox, and Safari. It did this by removing all margin, padding, borders, and fonts to a common baseline. It could either be included within your own CSS file, or added as a separate CSS file at the start of your CSS in the <head> tag. The order is crucial because you're establishing a standardised foundation. This allows subsequent CSS files to override these resets, either through direct duplication, leveraging the cascade, or by increasing specificity. For example:

/* Basic Reset of the body styling: Specicifity score 0,0,1 */
body {
	line-height: 1.5;
	font-family: system-ui, sans-serif;
	background: #fff;
	color: #000;
}

/* Here this selector is overriding the one above because it comes after it in the cascade: Specicifity score 0,0,1 */
body {
	font-family: "Comic Sans MS", Impact, sans-serif;
}

/* Here we are using CSS Specicifity to override the page background color: Specicifity score 0,1,1  */
body.colored-background {
	background: #ff0000;
}

This is why ordering your CSS correctly is best to do right at the start of a project. If you bring in a reset file at the end, it will either do nothing at all due to higher specificity CSS selectors before it, or it will completely undo lots of your styling, simply because it “wins” (by coming last in the cascade e.g. it’s the last CSS file loaded).

As mentioned above, CSS resets have evolved over the years. Normalize.css is a very common one in use on the modern web, as it works differently by preserving useful default browser styles and only fixing CSS styles that need to be fixed to maximise CSS consistency across modern browsers.

Other notable mentions are more modern, minimal resets that only focus on certain pain points in cross-browser rendering like box-sizing, responsive images, and font inheritance. These include Andy Bell's: A (more) Modern CSS Reset and Josh Comeau's: A Modern CSS Reset.

Kudos to the authors of CSS Resets! Their dedication makes CSS authoring significantly smoother for millions of developers across the world.

Hover-Only Interactions

Hover-only interactions are a legacy practice that suited desktop-only contexts but fail in today’s multi-device environment. An example of what a hover-only Interaction is:

.button:hover {
	background-color: #ff0000;
}

Hover-only Interactions come with the following issues:

Not accessible on touch devices: Touchscreens do not have a hover state. This means hover-only functionality becomes inaccessible on phones and tablets, leading to broken user experiences.
Not accessible on touch devices: Touchscreens do not have a hover state. This means hover-only functionality becomes inaccessible on phones and tablets, leading to broken user experiences.
Lack of fallback interaction: Many legacy implementations didn't provide alternative means (like a click or focus) to trigger the same behaviour, effectively hiding essential UI or functionality.
Keyboard accessibility problems: Hover interactions are not always accessible via keyboard unless explicitly paired with :focus or JS handling.
Poor progressive enhancement: Relying solely on hover effects often ignored the principle of progressive enhancement, especially when essential content was hidden using CSS unless hovered.
Inconsistent browser behaviour: Legacy browsers had quirks in how they handled hover states, particularly with complex layouts or when mixing JS and CSS interactions.

Modern Best Practice

UI's need to be device-agnostic and align with inclusive design principles. Hover-based interactions should be a supplementary interaction, not the primary interaction. In order to align with modern best practice you should:

Avoid hover-only interactions for essential functionality.
Use :focus alongside :hover, and consider adding :focus-visible to better support keyboard navigation.
Support click or tap events explicitly for mobile compatibility
Provide visible indicators or alternative access methods (e.g. always-visible menus on small screens)

An example in CSS is:

.button:hover,/* mouse users */
.button:focus,/* element focused via click or tab */
.button:focus-visible { /* user likely on keybord, or other assistive technology */
	 background-color: #ff0000;
}

The above can be simplified to avoid redundant styling as combining :focus and :focus-visible can sometimes cause overlapping or unnecessary duplication of visual effects. The recommended approach is to use the following as it keeps your styling clean and scoped, applying just what’s needed based on the user’s input method:

.button:hover,
.button:focus-visible {
	  background-color: #ff0000;
}

By avoiding redundant styling means you reduce:

Overlapping in CSS rules.
Maintenance complexity.
Risk of inconsistent behaviour between browsers.
Slightly less to download.

9. Legacy Web Strategies

Blackhat SEO

Blackhat SEO refers to a collection of techniques that people tried to use to manipulate search engine rankings, mostly in ways that violate search engine guidelines, especially for guidelines laid out by Google.

Intent

So why would people want to use Blackhat SEO? Well, its sole focus was prioritising rapid results over sustainable growth. Consultants selling these techniques were focussing on exploiting weaknesses in search engine algorithms, rather than creating genuine value for users. Being at the top of the Google results page was the primary goal, and companies were willing to try these techniques to get an edge on their competition. That was until search engines got wise to what was happening, and started to penalise sites that employed these techniques.

Examples

Let's look over a few outdated examples and how they worked:

Keyword stuffing: This was essentially stuffing as many keywords into a page in an attempt to trick the search engine into pushing a page to the top of the results for more search engine searches. So even if the keywords weren't at all related to the actual content, they were included anyway. Thankfully, search engines got wise to this tactic and cracked down on sites that used it.
Cloaking: This is where you show different content to search engines than you do to users. Search engines would be shown pages with detailed, keyword-rich content about a specific product in order to trick a search engine into ranking the page highly. But the page shown to users was minimal and mainly promotional with very little or no helpful information on the page related to what it was being ranked on.
Hidden text and links: This is the one I remember the most, using CSS or HTML to hide text on a page that was only intended for search engines. Think white colour text on a white background, it was that simple! It was also straightforward to spot, as you'd get pages where the scrollbar was huge, but the content on the page was very short. The overflow in the vertical direction was the hidden text that you could easily reveal by highlighting the text with your cursor!
Link farms and paid link schemes: This is where companies would create hundreds, or thousands of low-quality content linking back to a specific page, in the hope that the search engine would rank the page highly because of all the backlinks to it. There were (and most likely still are) whole business's setup that promised to get you to the top of search results by essentially spamming the web like this. If you ever had a WordPress blog without the Akismet plug-in, you'd see this rapidly! WordPress was highly vulnerable due to its support for Trackbacks and Pingbacks (XML-RPC). Have a look at any old unmaintained WordPress blog, and you are likely to see this. They were so common at one point that a new term called "splogs" (spam blogs) was created for them. Wired.com wrote a blog post all about them back in September 2006 "Spam + Blogs = Trouble".
Duplicate content: This is a simple strategy, copy another site's high-quality content and pass it off as your own. Thankfully, this now triggers de-ranking in search engines.
Automated content: Basically automating the production of low-quality and spammy content. I anticipate that this technique will see a resurgence, given the recent surge in AI tools.

"This is why we can't have nice things!" The phrase echoes in my ears as I recall all the techniques mentioned above.

Why are they Outdated?

There are a number of reasons why these techniques are no longer used:

Google and other search engines have significantly enhanced their algorithms to identify and penalise such manipulative tactics.
Modern SEO is more geared towards user-first metrics, content relevance, quality, user experience, and even web performance are now taken into account when ranking a web page.
Sites found to be using these Blackhat tactics are almost certain to be heavy penalised and may even be de-indexed completely from search engines.
Companies found to be using these tactics on the modern web are very likely to suffer reputational and credibility damage. Some sectors that are heavily regulated will likely have legal implications too.

Can I still use it?

Fortunately, these blackhat techniques are no longer effective on the web. They are detrimental to both users and the internet, yet some individuals persist in attempting to use them.

For example, Google now ranks web pages on their usability issues, one of these is called Cumulative Layout Shift (CLS). This metric measures the stability of a page while a website is loading, websites that "shift around" while loading (called "jank") aren't scored as highly as those that are more stable.

I recently saw a new SEO technique using JS that would mask an entire page with a transparent element in order to trick the browsers CLS metric into thinking the page was completely stable. After page load this element would be deleted and the page could be interacted as usual. Basically, a modern day cloaking technique aimed at improving a pages Layout Instability API score.

So yes, it still happens and "this is why we still can't have nice things!".

“Above the Fold” obsession

The concept of "above the fold" is an outdated technique. The fold's position is not fixed; rather, it varies depending on the device used to view a web page. If we take this to the extreme. Viewing a website on a desktop widescreen device vs a mobile device, there's never going to be a common "fold" in this situation. Consider the vast number of device widths, ranging from a large desktop widescreen to a mobile device—literally thousands along the x-axis. If you then factor in the viewport height (y-axis), you're looking at millions of possible viewport permutations. Past assumptions are no longer true:

User behaviour: Users scroll instinctively now. The old belief that users don’t scroll is no longer valid.
Web performance evolution: Modern performance metrics (like Largest Contentful Paint (LCP) and Interaction to Next Paint (INP)) reward real user-perceived speed, not just fast above-the-fold content.
Lazy loading and streaming: The web has moved towards prioritising meaningful content dynamically, rather than front-loading everything visible “above the fold”.

Can I still use it?

It depends. “Above the fold optimisation” is an older performance technique that focuses on rendering the visible portion of the page as quickly as possible. When used thoughtfully, it can still improve perceived load speed, especially in critical user flows. However, relying on it too heavily can narrow the focus to just a fragment of the overall experience.

Today, the more effective and sustainable approach is to optimise for end-to-end, user-centric performance. This includes not only what appears first on-screen, but also how quickly the page becomes usable and interactive. A strategy focused on delivering a consistently fast page experience will naturally improve the content visible without scrolling, regardless of the device.

Superseded compatibility approaches

Graceful Degradation

The technique of graceful degradation involves building a website to take advantage of all the modern features of a browser, and once completed add "fall backs" for browsers that don't support modern features.

Examples

An example of graceful degradation is: a developer builds a website where the main layout is using CSS Grid. But if a browser doesn't support Grid it will "fall back" to a simpler layout system like Flexbox or even a float-based layout (depending on the site's browser support requirements).

Another example is a feature-rich, JS-enhanced input form may fall back to a basic HTML form if JS is disabled or fails to load, for example, due to a poor or unstable network connection. In this case, core functionality (such as form submission) remains available, even though advanced features (like real-time validation or dynamic UI elements) are unavailable.

Why is it Legacy?

Graceful degradation is increasingly being considered a legacy approach in modern web development as it has largely been superseded by progressive enhancement which takes the opposite approach.

Why is it outdated?

This assumption of a modern baseline fails to acknowledge the true diversity of browsers and devices currently in use by users. Furthermore, comprehensive testing is challenging due to the difficulty of covering all scenarios involving older or limited browsers. Third, adding "fallbacks" further increases the complexity of an already intricate full-featured initial build. Most importantly, Graceful Degradation negatively impacts accessibility and resilience. Pages employing this technique frequently fail in low-capability environments, such as older browsers, devices, or poor connections.

Can I still use it?

There are a few scenarios where it may still be useful, these include:

Legacy enterprise environments: for example a company that mandates the use of older browsers like Internet Explorer. A notable example of this is Banks and other financial institutions in South Korea. For a country, that ranks 12th on the internet adoption rate for its citizens (97.4% it 2025), it's a pretty surprising legacy issue they are still trying to tackle!
Modernisation: If a website is in a transition phase of being modernised, and it still needs to support older browsers for a limited period.
Non-critical enhancements: If a site has non-critical enhancements like animations or media features that are optional and don't impact access to the site's core content.

What should I use instead?

Progressive Enhancement is now the preferred approach for modern web development, offering a more robust, inclusive, and future-proof way to build websites and web applications. While Graceful Degradation was a useful technique for older browsers, it has now been superseded.

Browser Sniffing

This is the practice of detecting more information about a user's browser, like its specific version number or the operating system it is currently running on. Once detected a developer can use this information to “fork” their code, e.g. make decisions as to what bug workarounds should, or shouldn't be applied. Or even tailor the user experience for a specific version of a browser. Two very common uses of this technique in the past were to redirect a user to the mobile version of the site (when mobile and desktop sites built separately), or even blocking the usage of a site on "unsupported" browsers. An example of how you'd do this in JS is below:

if (navigator.userAgent.includes('Chrome')) {
  // Apply Chrome-specific behaviour or simply block other browsers if you are feeling malicious
}

This code highlights a significant problem with browser sniffing, demonstrating why it's considered an outdated technique. In the code, the whole functionality is decided by the fact that the User-Agent variable in the browser happens to include the string "Chrome". But what happens if Google one day decides to change this string to lowercase "chrome", or even change it completely? Well, the code depending on this detection will break!

Now, you could modify the above code to tackle the case issue like so:

if(navigator.userAgent.toLowerCase().includes('chrome')){
  // Apply Chrome-specific behaviour
}

But as you can see, this has only made the code more complex and fragile.

It's also worth mentioning that this code won't do what you expect it to either, as all Chrome based browser will return true. For example:

Google Chrome
Microsoft Edge (Chromium-based)
Opera (also Chromium-based)
Brave
Vivaldi

At the time of writing each of the User-Agent strings for the above browsers contain: Chrome/115.0.0.0 (as well as other information, that I have removed for the example).

All contain "Chrome" in their User-Agent, so will all run the code.

What's worse is that Chrome on iOS will return false and not run the code. On iOS, all browsers, including what appears to be Chrome on the home screen, are actually forced to use WebKit (Safari). Consequently, "Chrome" in this instance isn't truly Chrome and is not reflected in the User-Agent String.

Other issues

Fragility isn't the only issue seen when using this technique. It can also:

add a maintenance burden for developers, as this logic will need to be updated as browsers evolve.
create browser feature mismatch, two versions of the same browser don't always support the same features.
cause accessibility risks leading to user exclusion. A user on a less-common browser or assistive technologies, could inadvertently receive a degraded experience, or even blocked completely.

Can I still use it?

Realistically, no, you should aim to avoid browser sniffing entirely and instead of asking which browser a user is using, ask what can their browser do? Essentially, you want to be detecting the features that the user's browser can support. For example, to detect if a browser supports the Service Worker API, you can do this:

if ('serviceWorker' in navigator) {
  // The users browser supports the 'serviceWorker' API, so do Service Worker stuff!
}

Browser Sniffing Summary

In summary, browser sniffing is a legacy technique that should be avoided on the modern web. In order to create a more resilient and inclusive web, you should use Feature Detection, Graceful Degradation, and Progressive Enhancement instead.

Modernizr

I was a big fan of Modernizr (with its very Web 2.0 name!). For readers who've not used or heard of it, Modernizr is a HTML5 and CSS3 feature detection library, It does this via browser feature detection, rather than browser user-agent strings, which can be unreliable and misleading. Modernizr actually tests to see if the browser being used supports a whole host of features.

It was released in 2009 at version 1.0, since then, it has had 27 releases, and 300 contributors. So how does it work, and how exactly do you use it? Here's an example of how it detects flexbox support in a user's browser.

// Adds a new test to the Modernizr object under the key 'flexbox'
Modernizr.addTest('flexbox', function () {

  // Create a new HTML div element to test CSS properties on
  var testElement = document.createElement('div');

  // Attempt to set the display property to 'flex'
  testElement.style.display = 'flex';

  // Check if the browser retains the value 'flex' for the display property
  // If supported, the style will remain 'flex'; otherwise, it may remain empty or be changed
  return testElement.style.display === 'flex';
});

And here's how you would use that in your website. There are 2 methods for how you use it:

CSS

Modernizr adds a class to the <html> element, in our case above it would be:

<html class="flexbox"></html> <!-- If the browser supports it. -->
<html class="no-flexbox"></html> <!-- If the browser doesn't supports it.

Thus, you could hang any styles you needed off these classes and tweak the CSS layout for both scenarios, flex support and no flex support.

JavaScript

The other method is to use it in JS by examining the Modernizr object:

if (Modernizr.flexbox) {
  // Flexbox is supported, do Flexbox JS stuff here
} else {
  // Flexbox is not supported, no non Flexbox JS stuff here
}

The great thing about Modernizr is that even thought it supports over 250 feature tests for HTML5, CSS3, and JS APIs, it allows developers to create custom-builds that only detect the features they intend to use. This improves performance in 2 ways:

Less JS to download, parse, then execute.
Fewer bytes sent over the network.

Use cases:

Applying fallback CSS or JS for unsupported features.
Progressive enhancement strategies.
Conditional polyfill loading.
Responsive design tweaks based on feature support (via JS)

Can I still use it?

It's still useful, but it isn't as essential as it once was, this is because:

Browser standardisation has vastly improved since 2009.
Native CSS now support feature queries (@supports).
Feature detection is often built into some JS frameworks.
Support for ancient browsers has declined.

Ironically, Modernizr, despite detecting over 250 features, does not detect JS support itself. This isn't a problem, though, because if you require this functionality it can be added via a single line of JS in the <head> of your page:

<!-- Default setup -->
<html class="no-js">
<head>
  <script>
    document.documentElement.className = document.documentElement.className.replace('no-js', 'js');
  </script>
</head>

By default, the script assumes that the browser doesn't support JS (class="no-js"). When it gets to the inline script tag, the script executes. And as this proves that JS is supported it swaps the no-js class to a js class that can then be used in CSS styling, as you would any other Modernizr CSS class as demonstrated above.

10. Tests and Standards of Yesteryear

Acid2 and Acid3 Tests

The Acid2 and Acid3 tests were really clever ways to test a browser's compliance with the ever-evolving rendering standards at the time. They were both created by the Web Standards Project (WaSP)which was founded in 1998, when the web was a battleground of two main browsers:

Microsoft (Internet Explorer 4 at the time)
Netscape (Netscape Navigator 4.05 at the time)

The Web Standards Project, aimed to promote web standards that made development simpler, more accessible, and future-proofed, by working closely with browser vendors and development toolmakers to achieve this. When the team posted their final blog post in March 2013, their mission was largely complete. It resulted in successfully getting browser vendors to support the standards set by the World Wide Web Consortium (W3C). As of 2025, the W3C remains active in setting new standards to ensure the web continues to support communication, commerce, and knowledge-sharing for all, with a strong focus on accessibility, diversity, and inclusion.

Acid2 (2005)

The Acid2 test was created to test compliance with HTML 4.01, CSS 1 & 2, and PNG rendering standards (e.g. alpha transparency). It did this by focussing on the following key areas of browser rendering:

Box model
Absolute and relative positioning
Float behaviour
Table layout
PNG alpha transparency
Data URLs

This was achieved through a highly innovative browser test: creating a simple cartoon face, similar to a smiling emoji. Depending on how compliant the browser was, influenced how well the face was rendered. It's much simpler if I just show you!

Rendering reference

This is what the output of the test is supposed to look like across all browsers.

Internet Explorer 6

This "face," rendered with IE6, appears as if the individual suffered a severe accident!

Netscape 4.8

Netscape performed similarly to IE6 at the time.

Mozilla Deer Park Alpha 2 (later Firefox 3)

Finally a browser that actually rendered a face!

There are far too many variations and versions of browsers around at the time to list here, but if you are interested in how other browsers rendered the Acid2 test check out this ancient blog post by author Mark "Tarquin" Wilton-Jones. Mark, thank you for safeguarding this significant and captivating piece of web standards history!

Acid3 (2008)

After the success of the Acid2 browser test in putting pressure on browser vendors to improve standards support in their browsers, it was decided by the WaSP team to create another browser test, this time focussing on a different set of browser technologies. These included:

DOM Level 2 and 3
ECMAScript (JS) behaviour
CSS 3 selectors
SVG rendering
Data URIs
Animation timing and rendering
WebFonts via @font-face

Rendering reference

The Acid3 test took a more traditional testing route and simply scored a browser taking the test between 1 (poor support) and 100 (perfect support).

In my opinion, the Acid3 test, while practical and easy to interpret, lacked the entertainment value of the Acid2 facial disfigurement test!

The release of the more challenging Acid3 test coincided with a surge in browser competition, particularly among Firefox, Safari, Opera, and Google Chrome (which was released later in 2008).

Scores

At the time of release (March 2008) the Acid3 scores for each major browser were as follows:

IE7: 12 / 100.
IE8 Beta 1: 18 / 100.
Firefox 2: 50 / 100.
Firefox 3 Beta 4: 71 / 100.
Opera 9.5 Beta: between 60–70 / 100.
Safari 3.1: between 75–90 / 100.
Google Chrome: Not yet released in March 2008.
Google Chrome 0.2 Beta: first release: 77 / 100.
Google Chrome 1.0: 100 / 100.

Google Chrome quickly improved its Acid3 score shortly after its initial release. This rapid improvement was mainly due to its use of the Safari WebKit engine, which already scored 75–90 out of 100 at the time.

Legacy

Neither test is maintained or relevant to the modern web, but they played a key role in pushing browser vendors toward better standards support. Today, browser compliance is measured using the Web Platform Tests (WPT), a much broader and actively maintained suite developed by the vendors themselves with input from WHATWG and W3C.

11. What Still Matters – Progressive Enhancement

Not legacy but often forgotten

Congratulations! You've made it! After discussing countless legacy approaches and techniques best left in the past, you've finally arrived at a truly timeless and Incredibly important methodology. More than two decades after Steve Champeon and Nick Finck introduced it in their talk "Inclusive Web Design For the Future” at SXSW in 2003. The Progressive Enhancement (PE) methodology remains one of the most robust and future-ready methods for modern web development.

What is Progressive Enhancement?

There's a ubiquitous diagram that is always shown whenever PE is mentioned in a blog post. And this blog post will be no different in using it, as it actually explains the concept incredibly well.

Here we have the well known Progressive Enhancement pyramid.

HTML

The HTML is at the bottom of the pyramid as it gives the website a solid foundation on which to build off. The HTML layer is the most resilient layer in the web development stack. Without the HTML there is no content, no links, no images, no website! This layer is by far the most important layer in the pyramid. Just to give you an idea of how resilient HTML is in web browsers, let's take a look at the very first website. Back on Tuesday, August 6, 1991, Sir Tim Berners-Lee, the inventor of the Web, published the very first website! Now, this statistic makes me feel ancient! The first website was published almost 34-years ago, at the time of writing! And what do you notice about the page? Well, most importantly, it still renders correctly, and the content can still be read perfectly well after all this time. If you take a peak at the page's source code, you will notice a few oddities, like:

The complete lack of a DOCTYPE, and no <head> tag.
No links to external stylesheets or JavaScript (they weren't invented yet!)
Anchors existed to link to other pages, but they had a strange NAME=[integer] attribute.
All elements were written in uppercase, e.g. <HEADER>, <BODY>, <TITLE>, <H1>.
Lack of Semantic Markup. This was to come later once the WWW had matured.

To put it into perspective, this website has been around longer than nearly half of the entire global population, that’s over 4 billion people younger than this single page on the internet! Which other digital format on the planet can boast that form of robustness and ease of accessibility? Just think about all the storage media formats that have come and gone in that time:

5.25-inch floppy disk (the disk that was actually floppy)
3.5-inch floppy disk (the 3D "save icon")
CD-ROM / CD-R / CD-RW
MiniDisc (data version)
CompactFlash (CF)
Zip disk
Jazz drive
DVD-ROM / DVD±R / DVD±RW
Blu-ray
HD DVD

The list goes on… The point is clear: if you need a long-term, reliable storage solution that just works, plain HTML on the web is hard to beat! FYI: Of course, these web assets ultimately reside on physical hardware in data centres, but that’s not the point. What matters is the resilience and accessibility the web platform offers, regardless of the underlying infrastructure.

CSS

The second layer in the pyramid is the CSS or the Cascading Style Sheets. When the World Wide Web (W3) was first invented back in the early 90s, CSS simply didn't exist. It wasn't until 1996 / mid-1997 that browsers started to support the CSS Level 1 Specification. The browsers at the time were Internet Explorer 3 and Netscape Navigator 4, both had partial (and mostly buggy implementations). Up until this point the web had been completely "naked" in terms of design. Just pages full of text, images, and the odd animated GIF. Nothing at all like the modern web we see today.

CSS constitutes the second layer of the pyramid because, frankly, it is a "nice to have." Browsers are equipped with default stylesheets (as previously discussed in the CSS Resets section), which enable HTML content to display correctly and remain readable even in the absence of a website's custom styles. A company or brand must ensure their CSS is available for browsers to download so that their website renders correctly. Without it, many users would assume the site is broken, especially given how modern websites are expected to appear. But in the unlikely event the CSS fails to load, users will still receive the HTML content in a perfectly readable format. While it may appear unappealing, it remains fully functional across all current (and all future) web browsers and assistive technologies.

The beauty of Progressive Enhancement lies in establishing a foundational layer (HTML) and then progressively adding desired features. This method ensures that if any subsequent layer fails, the underlying content and functionality remain accessible to users.

A prime example of this browser feature in action is, since April 9, 2006, CSS Naked Day has been observed. Where for a 50-hour period, website owners disable their site's CSS, allowing users to experience the semantic HTML without styling. It started as a push for web standards and semantic markup, and gave site owners an excuse to flaunt their sexy <body>. Gotta love a good HTML pun!

JavaScript

The final layer of the pyramid and the final piece of the Web stack puzzle is JS, this is the interaction layer that is added to a site last after the foundation (HTML) and design (CSS) have been added. It's difficult to believe that just three technologies, all of which have been discussed in this section, form the entirety of the web. There is truly nothing more to it than these three foundational components. Ultimately, the output of both frontend and backend development invariably consists of standard HTML, CSS, and JS. Although a multitude of tools and languages are available for web developers to use, with endless paths to choose from, they eventually all lead to identical HTML, CSS, and JS as their final output. It all comes down to using the right tool and technology for the job!

JS is deliberately placed as the final enhancement layer in the pyramid. This is not incidental. JS, while powerful, is the least resilient layer in the web stack. Its execution depends on multiple fragile components:

the network
the parser
the runtime environment
the integrity of the code itself.

A single misplaced character, for example, an errant semicolon or an undefined variable, can render entire swathes of interaction inoperable. This fragility is not a hypothetical risk. It manifests regularly across production environments all over the web, particularly where sites are heavily reliant on client-side code for core user journeys.

Progressive Enhancement Summary

The modern web has increasingly drifted away from the principles of Progressive Enhancement, often placing JS as the foundation rather than the finishing touch. Single Page Applications are a prime example, where even basic navigation and content rendering require full JS execution. This inversion of the pyramid not only risks total inoperability in degraded environments but also introduces avoidable accessibility and performance issues.

From a resilience and user experience standpoint, over-reliance on JS creates brittleness. Unlike HTML and CSS, which both degrade gracefully, JS fails noisily and catastrophically. If a CSS file fails to load, a page might look plain but will still remain usable. If a JS bundle fails, the entirety of the website's features may be lost, with little to no fallback available.

The web’s reach includes users with:

unreliable networks
older devices
constrained data plans
assistive technologies

A heavy dependence on JS frequently excludes these users or significantly worsens their experience. Progressive Enhancement is not about supporting “no JavaScript” users as a niche edge case. It’s about ensuring a robust baseline that works for everyone, every time, demonstrating empathy for all users regardless of how they access the internet.

While JS is a vital tool in a web developer’s toolkit, it must be handled with care. Its position at the top of the Progressive Enhancement pyramid reflects its power, but also its fragility. It should be used responsibly, with the awareness that its failure often leads to a broken experience. True resilience comes from building upwards from stable foundations, not downwards from brittle interactions.

Importance in government services

Having worked at GDS for 6-years, I can't tell you how many times I had to defend the frontend communities stance on Progressive Enhancement! Thankfully, it's all written in black and white in the Service Manual for all to read. However, some departments and developers found ways to work around the methodology or opted for alternative approaches. This was most likely driven by two things:

A team had made significant progress with their JS dependent service and were expressing concerns about meeting the requirements for their future service assessment(s).
Some Frontend Developers in the department were enthusiastic about adopting the latest client-side frameworks, with less emphasis on assessing their maturity or suitability for the service, and its users.

For point 1 it always amazed me that teams were able to get so far into prototyping for it to become an issue. As depressing as it may be to me, maybe the Service Manual and its guidance isn't as well-known across government as I'd like to believe?

For point 2, I 100% get it, new technology on the web is fun to play with and also to have on your CV / Resume! The real question is whether this new technology is truly the right choice for a critical public service that every UK taxpayer depends on and has a fundamental right to access?

Technology Suitability Check (Progressive Enhancement Focus):

Does the technologies core functionality allow the service to work without JS enabled?
Can the service still function reliably on low-powered or older devices when using this technology?
Is the final output from the technology easily accessible and usable with assistive technologies, regardless of the device used?
Does the technology degrade gracefully in poor network conditions, such as on a 3G connection or in rural areas?
Are all critical user journeys still functional when JS fails to load, or is blocked?

If the answer to any of the questions above is "no", then the technology probably isn't a great fit for a public service that needs to be maintained for years (or even decades!).

The last point in the list above is incredibly important:

Are all critical user journeys still functional when JS fails to load, or is blocked?

I think this is where there was a lot of misunderstanding in terms of Progressive Enhancement in government. I continually strive to highlight that a JavaScript-only journey doesn't require a direct 1-to-1 correlation with its progressively enhanced foundation. As long as for each user journey a user can complete their task, quickly and easily, then the use of JavaScript is fine.

For example, consider a feature-rich JavaScript dashboard built to enter user data into a backend database. If a simple HTML form with a submit button can achieve the same outcome (which it often can), then the dashboard is acceptable only if the HTML form provides a reliable fallback for situations where JavaScript is unavailable, such as when it fails to load due to a limited data plan, a poor connection, or a low specification device.

During a service assessment, the key question is whether the dashboard meaningfully improves data entry and user interaction, or whether it exists purely for the sake of using new technology. Adopting new tools without clear justification is not acceptable for a government service. I consider such an approach to be driven by a desire to boost a developer's CV or LinkedIn profile. E.g. CDD (CV-Driven Development) or LDD (LinkedIn-Driven Development).

12. Lessons for the Future

What these legacy practices teach us today

If there is one takeaway from this post, it is that Frontend Development has never stood still. What counts as best practice today can feel outdated or even “legacy” tomorrow. That constant state of reinvention is what first drew me in back in the late 90s, and it is what continues to excite me now. Backend development always seemed a little too steady, too predictable. Frontend, on the other hand, has always lived on the edge of change.

But what is different today is the scale of change ahead of us. With the rise of Artificial Intelligence (AI), we may be standing on the edge of a shift as significant as the birth of the modern Web itself. Just as the early internet reshaped how we live and work, the combination of AI and the Web could redefine what it even means to build, design, and interact online. The coming years are not just going to be interesting, they could mark a turning point in the history of our craft.

Applying lessons to modern frontend work

Core principle

Choose optimal solutions for the enduring parts of the stack: HTML, CSS, and JavaScript are the stable contract. Prioritise the most straightforward and maintainable approach to delivering clean, accessible HTML, efficient CSS, and lightweight, well scoped JavaScript. The further you move away from those three, the harder accessibility, maintenance, and performance become. Let the browser and the web platform do the heavy lifting.

Practical rules to work by

1. Start from the Web Platform

Prefer native elements and platform features before adding libraries. Use form controls, semantic HTML, CSS layout, media queries, inert, details and summary, dialog, fetch, URLPattern, IntersectionObserver, and Web Components where they fit.

2. Progressive enhancement as a default

Deliver meaningful HTML first, enhance with CSS, then layer JavaScript for interactivity. Critical journeys should still work when scripts fail or load slowly.

3. Ship less code

Adopt a dependency diet. Each abstraction must earn its keep through measurable value. Small utilities over frameworks by default. If a framework is chosen, configure it to output lean HTML, CSS, and JS.

4. Accessibility first, not last

Use semantic structure, proper labels, roles only when needed, visible focus, real buttons and links, reduced motion preferences, and test with keyboard and screen readers. Performance 100% is an accessibility feature.

5. Performance budgets and baselines

Set budgets for bundle size, interaction latency, and memory. Track Core Web Vitals from real users. Fail builds that exceed budgets. Optimise for first input delay, input responsiveness, and low CPU use on mid-range devices.

6. Keep the build simple

Prefer standard tooling that converges to web standards. Use the minimum build steps required. Long pipelines increase failure modes and slow iteration.

7. Design for resilience

Favour server rendering for first paint, hydrate only what is interactive, cache well, and handle partial failure gracefully. Make error states explicit.

8. Document the escape hatches

Where you choose abstractions, document how to reach the underlying HTML, CSS, and JS. Future teams should be able to debug without learning a bespoke stack.

9. Measure before you change

Add observability. Use Real User Monitoring (RUM) to guide work. Optimise the slowest real user paths, not synthetic microbenchmarks.

10. Plan for upgrades

Last, but not least, prefer tools with clear deprecation policies and migration paths. Avoid lock in. Isolate framework code behind simple boundaries so you can replace parts without rewriting the product.

A quick decision test

Can this be done with native HTML or CSS alone?
If not, can a few lines of vanilla JS do it without a dependency?
If not, does a library reduce long term cost and keep output close to the platform?
If a framework is still justified, can it produce accessible HTML by default and degrade gracefully?

Closing thought

Technologies come and go, but the contract with the browser remains. Choose the simplest path that produces high quality HTML, CSS, and JavaScript. The closer you stay to the platform, the easier your product will be to maintain, to make accessible, and to run fast at scale.

Post Summary

I have to admit, my posts always seem to take on a life of their own and end up being longer than I plan. Concise writing might be a goal for another day. If you made it all the way here, congratulations, you’ve officially joined the “end of post club”! I really hope you found this journey as enjoyable to read as it was for me to write. Revisiting these ideas was a real trip down memory lane, and it reminded me of things I hadn’t thought about in years.

Your thoughts and feedback are always welcome. If I’ve overlooked a method or technique you think deserves a mention, let me know and I’ll happily credit you in the changelog. Thanks again for sticking with me to the very end, and if you’d like to share your thoughts, you can do so here.

Post changelog:

26/08/25: Initial post published.
27/08/25: Fixed number ordering of headers.
27/08/25: Added Table of Contents for easier navigation!
28/08/25: Added Silverlight and Java Applets to the post (Thanks to an AI hallucination, regarding browser plugins from the past)
17/09/25: Thanks to Sven Kannengiesser for drawing my attention to the use of ‘here’ anchors. I have now revised them to be contextual and accessible.

Configuring your Content-Security-Policy on your development environment in 11ty

2025-02-04T00:00:00Z

This is just a short post to discuss how I improved my Content-Security-Policy (CSP), on my local development environment in 11ty. This is essentially a follow-on post from my Securing your static website with HTTP response headers I wrote last year.

Note: this post isn’t exclusive to 11ty—it’s just the static site generator I use for this site. The code can be easily adapted for any static site running on a Node.js-based server—or practically any local web server!

Why is this useful?

<rant>It's incredibly useful for me because my Cloudflare build currently takes 7 minutes and 30 seconds to complete! I've no idea why it takes this long, and as of yet I've had absolutely no response from Cloudflare on why this is! What I do know is that something happened on the 19th December 2024 between 12:33AM and 12:19PM because my Cloudflare Pages build time increased by a massive 460%! See the screenshots below for proof of that fact:

Before

Note the date, time, and git hash in the screenshot above: 12:33AM December 19, 2024, hash efd9011. Now let's compare it to the screenshot below:

After

So in this screenshot above, we have the same git hash: efd9011, but 12 hours have passed, it is now 12:19PM December 19, 2024.

Clearly my code hasn't changed because the git hash is the identical and nothing else has been committed, but for some reason my build time has increased by 460%! It's my guess that something changed on Cloudflare's side in this 12-hour period to drastically increase the build time. Even though I posted about it on the Cloudflare Discord server and the Cloudflare Community Forums, I've had no response to tell me what was changed and if it is possible to fix it. So if anyone from Cloudflare is reading, I'm begging you, please, can you investigate what changed in that 12-hours and tell me if there's something I can change to drop my build time back to 1 minute 30 seconds!</rant>

So you're probably asking: "What on earth has any of this got to do with a "Content-Security-Policy" response header? Well, a 1-minute 30-second rebuild time to update my site's CSP in the 11ty _headers file is a reasonable time to wait to test for issues. But waiting 7 minutes 20 seconds for every little change just isn't efficient or workable! Quite frankly it's incredibly frustrating. And if you've ever worked on writing a CSP before you will realise how convoluted and unreasonably lengthy they can become! There had to be a better way to do this, and there is! So let me take you through the node.js / 11ty solution I used below to make my latest CSP changes.

The code

Let's have a look at the code:

// This is my site's Content Security Policy.
// Modify this CSP, don't just copy / paste it! It will break your site!
// You can also use `var` and `let` depending on your coding syntax, they all work
const CSP = `
base-uri 'self';
child-src 'self';
connect-src 'none';
default-src 'none';
img-src 'self' https://v1.indieweb-avatar.11ty.dev/;
font-src 'self';
form-action 'self' https://webmention.io https://submit-form.com/DmOc8anHq;
frame-ancestors 'self';
frame-src 'self' https://player.vimeo.com/ https://www.slideshare.net/ https://www.youtube.com/ https://giscus.app/ https://www.google.com/;manifest-src 'self';
media-src 'self';
object-src 'none';
script-src 'self' https://ajax.cloudflare.com https://giscus.app/ https://www.google.com/ https://www.gstatic.com/;
style-src 'self' https://giscus.app/;
worker-src 'self';`.replaceAll('\n', ' ');
// This is the middleware for our 11ty development server
eleventyConfig.setServerOptions({
	middleware: [(req, res, next) => {
		if (req.url.endsWith('.html') || req.url === '/') {
			res.setHeader('Content-Type', 'text/html; charset=UTF-8');
			res.setHeader('Content-Security-Policy', CSP);
		}
		next();
	}]
});

As you will see I have formatted the CSP using template literals to make the CSP more readable, and thus easier to modify and test on my local environment. You can find the public gist for the code above here.

A couple of notes on this code:

Notice how I removed newlines from the final CSP variable. Using const signals to other developers that it shouldn't change, but since strings are immutable in JavaScript, modifying it using .replace() creates a new valid CSP header string.
I've added detection for both "naked URLs" and those ending in /index.html. This is just for convenience really, as it saves having to add the index.html to URLs before the response header is sent.
Lastly, the above CSP in its current form will break 11ty's live reload functionality because the connect-src in the CSP is set to none which tells the browser to block all network requests initiated by the page.

The following network communication technologies are blocked by this directive:

In order to fix point 3 there are 2 options:

1) Modify the `connect-src` directive

This is the obvious fix for the issue:

// add the following to your CSP variable
connect-src 'self' ws: wss: http://localhost:* ws://localhost:*;

By modifying the connect-src directive, we are allowing connections on localhost via HTTP and WebSockets (which 11ty's live reload script relies on to push updates to the browser without having to reload the whole page). And we are also allowing WebSocket connections that are both encrypted (wss:) and unencrypted (ws:).

2) Modify the `default-src` directive

This is a less obvious fix for the issue:

// add the following to your CSP variable
default-src 'self' ws: wss: http://localhost:* ws://localhost:*;

The reason this works is that default-src is the "fallback" directive. So assuming your connect-src is set to self then the following ws: wss: http://localhost:* ws://localhost:*; would still be followed because the directive is falling back to default-src.

IMPORTANT: don't use default-src if your connect-src is set to none! The value of none will still block all connections and override the default-src settings.

The advantage of modifying the default-src directive is that it will be applied to other directives like script-src and img-src. So it really depends on your CSP requirements for your local development environment! For most readers, I'd guess modifying the connect-src directive will be enough. But I've added both options for completeness.

Summary

Believe it or not, I kept the blog post short this time! I hope this code snippet makes configuring your 11ty CSP a breeze! As always, thanks for reading and if you have any feedback or comments, please let me know!

Post changelog:

04/02/25: Initial post published.
09/02/25: Thanks to vrugtehagel from discord for his couple of tweaks to the const CSP code. The small changes can be seen in the gist revisions if you are interested.

Lets create a plaintext RSS feed with 11ty

2025-01-29T00:00:00Z

Before writing this blog post I had 3 types of RSS feeds for my blog posts:

In this post, I'm going to add a 4th type: Plaintext.

Origin

A few months ago I was browsing my contacts and past colleagues looking for people to follow for my blogroll page. In doing so I just so happened to remember Terence Eden who I worked with at Government Digital Service (GDS). Terence (or edent, as he is known on most social networks), is a prolific blogger! I honestly don't know where he gets the time to blog so much and work, eat, sleep, blink, and breathe! While looking at the source code of his blog for his RSS feed, I just so happened to notice he had a plaintext version of his RSS feed. At the time it was responding with a 404, so I let him know on Mastodon, and he fixed it in a matter of minutes. Once fixed, I could see how it was formatted, and I set it as a personal challenge to replicate this feature on this blog (once all other more important functionality had been added). Now you may be asking, why would you need a plaintext version? So, let's answer that question first!

Why add a plaintext RSS feed?

Other than a personal challenge, what are the reasons for adding a plaintext version of your RSS feed?

Greater syndication

Now I have no idea how people like to read my content (I'm just very glad they do!). So if there's any way I can make their lives easier by adding multiple formats of the same RSS feed, then I'm happy to do it. After all, I'm always looking for ways to make this blog more open and inclusive. Even if it's only for a handful of readers, then it's worth adding the functionality, as it really is "set it and forget it" once deployed!

Command-line feed readers

I had no idea until I started researching the topic that there are users who use their terminal window as an RSS feed reader. For this they use programs like:

newsboat: "An RSS/Atom feed reader for text terminals" — It looks to have a very active repository on GitHub with 217 forks and 3,100 stars!
Liferea: "Liferea (Linux Feed Reader), a newsreader for GTK/GNOME" — Again an active GitHub repository with 129 forks and 830+ stars. I also noticed the project is over 20 years old (looking at some of the commits)!
RSS Guard: "Feed reader (podcast player and also Gemini protocol client) which supports RSS/ATOM/JSON and many web-based feed services." — another RSS client with an active GitHub repository with 130 forks and 1,800 stars. It's not surprising really considering the number of operating systems it supports!

So if you were in any doubt that plaintext RSS feed users don't exist, then I think the numbers above prove otherwise! (before you get angry, I do realise that not all these three programs users will be plaintext users!).

Privacy and Security Concerns

You only have to look at the Web Almanac 2024's chapters on Privacy and Security to realise how important these two topics are on the modern web. So it's completely understandable that RSS users are concerned about this when they subscribe to RSS feeds. Thankfully, this is where plaintext RSS feeds excel. By using plaintext RSS feeds, users can avoid loading external content such as images or scripts, thus reducing the risk of tracking and also enhancing their privacy.

Accessibility

I've seen accessibility brought up as a plus for plaintext RSS feeds, but honestly, I’m a little sceptical. Sure, a screen reader can read the content easily enough, but when it comes to navigation and overall user experience for someone with accessibility needs, navigating a plaintext feed seems like it’d be a step backwards. Wouldn’t something like HTML or XML, with its semantic markup and built-in navigation, be a way better option? That said, I’m totally open to being wrong here—if I’ve got this all incorrect, feel free to let me know.

Data Efficiency

This one really doesn't need much discussion, really. You can't get much more minimal in terms of bandwidth usage than a plaintext RSS feed. No images, no JavaScript, no markup, just pure content. It certainly makes for an excellent source of content for users with limited internet access or those operating in low-bandwidth environments.

Customisation and Integration

Tools like RSS Fulltext Proxy and Five Filters allow for text extraction from any website to convert partial feeds into full-text. This allows for integration into any feed reader, without plugins, or additional configuration. These are exceptional options if you want to integrate a particular feed into one of your workflows.

Reliability and Readability

You literally can't get a more robust format than plaintext. It is universally supported and small. And in terms of the resulting readability, there's no cookie banners, adverts, or newsletter signup forms that pop up halfway through an article. Thankfully, none of these annoyances are possible in plaintext, so you can consume all the content without interruption. It reminds me of how the World Wide Web used to be before it was commercialised beyond recognition! Take a read of the world's first website, and you get an idea of what Sir Tim Berners-Lee had in mind when he invented it in 1989 at CERN.

The web was originally conceived and developed to meet the demand for automated information-sharing between scientists in universities and institutes around the world.

The WorldWideWeb (W3) is a wide-area hypermedia information retrieval initiative aiming to give universal access to a large universe of documents.

Anyway, enough of the "why's" let's crack on with the 11ty implementation!

The code

eleventy.config.js

First, let's modify the 11ty config file:

Here we are telling 11ty to process .txt files as template files.

eleventyConfig.addTemplateFormats("txt");

Next we need to configure 11ty and tell it how to handle .txt files with a custom handler.

eleventyConfig.addExtension("txt", {
	outputFileExtension: "txt",
	compile: async function (inputContent) {
	  return async (data) => inputContent;
	},
});

The code is fairly self-explanatory outputFileExtension is obvious, the resulting output will have a .txt extension. The compile function is a simple pass-through. It takes the txt input and returns the original content unchanged.

feed.txt.njk

Next up is the template for the plaintext feed output. I'm using Nunjucks as that's the main templating language I use across this blog, but I'm sure you'd be able to any other templating language 11ty supports too. This file sits in my /content/feed/ directory, so 11ty will process it as a njk file in the output.


---
permalink: feed/feed.txt
eleventyComputed:
  layout: null
---
# {{ metadata.title }} - {{ metadata.author.name }} - {{ metadata.description }}
## {{ metadata.fulldescription }}
URL: {{ metadata.url }}

{% for post in collections.posts | reverse -%}
{% if loop.index0 < 10 -%}
--- Start: {{ post.data.title | safe }}
Published on: {{ post.date | readableDate }}
{{ metadata.url }}{{ post.url }}

Main Content:
{{ post.templateContent | striptags(true) | decodeHtmlEntities | safe }}
{% if not loop.last %}
--- End: {{ post.data.title | safe }}



{% endif -%}
{% endif -%}
{% endfor -%}

A Gist for this template is here, if you find that easier to read.

There's a fair amount going on in this template file, but it is essentially:

Setting where I want the feed to sit in my final site output (permalink)
Overriding the default layout dynamically during the build process (layout: null)
Populating the top of the feed with my basic blog metadata.
Looping through all by blog posts in reverse (newest first).
Limiting the number of posts in the feed to 10.
Outputting the parts of each post I want in the feed using Nunjucks and cleaning up the output using various filters, which I will go through next.

Code Notes:

You may be looking at this template and wondering what is going on with all the space between the logic. Well, since this template is outputting plaintext, this is all intentional spacing to make the final output more readable.
I'm using loop.index0 which is the current iteration of the loop but 0 indexed because it was the only way that seemed to work for me to limit the number of posts. I think I must have a weird collections.posts setup somewhere because regardless of what I tried, nothing worked. Likewise, I believe the native slice(0, 10) should do the same thing, but for me, the loop stopped working altogether. I tried debugging it for a couple of hours and eventually stuck with the loop.index0 setup because it actually worked. However, if anyone has any ideas on why the native slice() function on a collections.posts doesn't work, please let me know! I'd love to get to the bottom of what the issue is!
You may notice my use of the -%} in the template, this is me telling Nunjucks to trim any whitespace (spaces, tabs, newlines) directly following the tag. This was required because it was adding numerous new lines in the resulting output. It's when I discover little intricacies in Nunjucks like this, that I realise what a versatile templating language it actually is!

filters

Most of the filters used in the above template are all pretty standard to the Nunjucks language:

I only added one custom 11ty filter for this functionality.

decodeHtmlEntities

For some reason, I had some very odd character encoding issues, and the only way I could resolve the issue was to create a custom 11ty filter to search and replace them throughout the content. I looked through the default Nunjucks filters for a solution, but filters like escape and forceescape didn't work. I could have probably used Nunjucks native replace filter, but that would have cluttered up the template, so decided to move it to an 11ty filter instead:

// clean up the HTML entities in the RSS feed text
eleventyConfig.addFilter("decodeHtmlEntities", function(text) {
	return text.replace(/&([^;]+);/g, function(match, entity) {
			const entities = {
					'amp': '&',
					'apos': "'",
					'lt': '<',
					'gt': '>',
					'quot': '"',
					'nbsp': ' '
			};

			// Handle numeric entities
			if (entity[0] === '#') {
					const code = entity[1] === 'x'
							? parseInt(entity.slice(2), 16)
							: parseInt(entity.slice(1), 10);
					return String.fromCharCode(code);
			}

			return entities[entity] || match;
	});
});

It's basically just a fancy way to search and replace for multiple encoding issues it finds in the plaintext output.

Just to be clear, I wrote a really clunky version that did the same thing as this first. Basically, a chain of text.replaceAll('&', '&').replaceAll(''', "'")... and so on, I think you get the idea.

It worked fine, but then I asked ChatGPT to optimise it, and this is the result it came up with! It's certainly not as readable, but it still does the job, and it also handles numeric entities too! Off the back of this example, I think AI used correctly can be a fantastic teaching tool, especially when it comes to random little filter functions like this.

Adding the feed to your `<head>`

Once you have the feed up and running, it's time to make sure you have it visible to your users by adding it to your pages <head>. It's dead simple, just like your other feeds, only the type is set to text/plain.

<link rel="alternate" href="/feed/feed.txt" type="text/plain" title="Nooshu - Matt Hobbs blog post Plaintext Feed.">

I also have links to all my feed formats in my footer so they are easy to find. So, finally, why not look at the result of the above code now by looking at my plaintext RSS feed.

Sample output

Here's an example of the output from the code above:

# Nooshu - Matt Hobbs - Frontend web developer, turned engineering manager.
## This is the website of Matt Hobbs, who is a Frontend Engineering Manager from Oxfordshire, UK.
URL: https://nooshu.com

--- Start: The Speed Trifecta: 11ty, Brotli 11, and CSS Fingerprinting
Published on: 23 January 2025
https://nooshu.com/blog/2025/01/23/the-speed-trifecta-11ty-brotli-11-and-css-fingerprinting/

Main Content:
So recently, I have written two 11ty related blog posts:

Using an 11ty Shortcode to craft a custom CSS pipeline
Cranking Brotli up to 11 with Cloudflare Pro and 11ty

...more blogpost content here...

Post changelog:

23/01/25: Initial post published.

--- End: The Speed Trifecta: 11ty, Brotli 11, and CSS Fingerprinting

Summary

Whew! Another blog post in the books, and another shiny new feature added—this time, a working plaintext RSS feed! (That’s one more thing off the to-do list—always a win!) Thanks for stopping by! I hope you found this post interesting, maybe even useful? As always, if you’ve got thoughts, or feedback, please let me know!

Post changelog:

29/01/25: Initial post published.

The Speed Trifecta: 11ty, Brotli 11, and CSS Fingerprinting

2025-01-23T00:00:00Z

So recently, I have written two 11ty related blog posts:

If you haven't read them, no problem, they are always there if you're ever struggling to sleep!

TL;DR:

In the first post I look at how I've automated CSS fingerprinting on production (Cloudflare), resulting in the ability to use long-life Cache-Control directives like max-age=31536000 and the immutable browser hint.

In the second post, I look at how you can improve Brotli compression by manually compressing your assets to Brotli setting 11 (max) then serving them via a Cloudflare Pro plan. This gives a significant improvement in file size over the Brotli compression setting of 4 that Cloudflare uses for dynamic (on the fly) compression.

While working on both posts, it dawned on me that blending the approaches they cover would result in the ideal CSS configuration for my little blog. In this post, I'll show you exactly how I've done it. Let's get started!

Original code

So I'm going to be using the code I wrote in the CSS fingerprinting blog post I wrote recently. You can see it below, or in this Gist.

import dotenv from "dotenv";
import CleanCSS from 'clean-css';
import fs from 'fs';
import crypto from 'crypto';
import path from 'path';
dotenv.config();

// create a single instance of the CleanCSS function
// to be used in file loops. Add additional optimisation settings in here.
const cleanCSS = new CleanCSS({
	level: {
		2: {
			removeDuplicateRules: true // turns on removing duplicate rules
		}
	}
});

export function manipulateCSS(eleventyConfig) {
	eleventyConfig.addShortcode("customCSS", async function(cssPath) {
		// output the file with no fingerprinting if on the dev environment
		// (allows auto-reload when the CSS is modified)
		if (process.env.ELEVENTY_ENV === 'development') {
			return `<link rel="stylesheet" href="${cssPath}">`;
		}
		// Using path.join for better cross-platform compatibility
		const inputFile = path.join('./public', cssPath);
		const outputDirectory = path.join('./_site', 'css');
		const cacheDirectory = path.join('./.cache', 'css');

		try {
			// Check if input file exists first
			if (!fs.existsSync(inputFile)) {
				console.error(`Input CSS file not found: ${inputFile}`);
				return '';
			}
			// Ensure both cache and output directories exist
			for (const dir of [cacheDirectory, outputDirectory]) {
				if (!fs.existsSync(dir)) {
					fs.mkdirSync(dir, { recursive: true });
				}
			}
			// Read the input CSS file
			const inputCSS = await fs.promises.readFile(inputFile, 'utf8');
			// Initialises a new hashing instance
			const hash = crypto.createHash('sha256')
				// Feed CSS data into the hash function
				.update(inputCSS)
				// Specify the hash should be returned as a hexadecimal string
				.digest('hex')
				// Only take the first 10 characters of the hash
				.slice(0, 10);

			// Generate our CSS Cache name
			const cacheKey = `${hash}-${cssPath.replace(/[\/\\]/g, '-')}`;
			// This is where the file will be written
			const cachePath = path.join(cacheDirectory, cacheKey);

			// store our manipulated CSS in this variable
			let processedCSS;
			// check we have a cache directory
			if (fs.existsSync(cachePath)) {
				// read the cached CSS file
				processedCSS = await fs.promises.readFile(cachePath, 'utf8');
			} else {
				// Use the memoized cleanCSS instance to minify the input CSS
				processedCSS = cleanCSS.minify(inputCSS).styles;
				await fs.promises.writeFile(cachePath, processedCSS);
			}
			// Split the input file path into its components (directory, filename, extension)
			const parsedPath = path.parse(inputFile);
			// Use path.join for output paths
			const finalFilename = path.join(outputDirectory, `${parsedPath.name}-${hash}${parsedPath.ext}`);
			// Write the optimised CSS to the final output location with the hash in the filename
			await fs.promises.writeFile(finalFilename, processedCSS);

			// path manipulation for final URL
			const hashedPath = finalFilename.replace(path.join('./_site'), '').replace(/\\/g, '/');

			// return our final link element with optimised and fingerprinted CSS.
			return `<link rel="stylesheet" href="${hashedPath}">`;
		} catch (err) {
			console.error("Error processing CSS:", err);
			return "";
		}
	});
}

Install zlib

The first thing we shall do is install the zlib package from npm, as this is what we are going to use to compress the CSS file all the way up to 11 on production.

npm install zlib

Next, we import it into our ESM code above:

import zlib from 'zlib';

Don't worry, I'm not going to go this slow all the way through the code. Feel free to skip straight to the final code if you so wish!

Setting the default compression level

This is a completely optional step, it really depends on how, and where you store all your build variables. But I'm going to be storing the Brotli Compression level I want to use on production both in the JS (as a default to fall back on if the environment variable doesn't exist), and also an environment variable on production. In the JavaScript below, set at 6 to show it can be any value between 0-11 (3 or 4 is what most CDN use for dynamic compression). Cloudflare's compression is set to 4:

// Default Brotli compression level if not set in the environment
const DEFAULT_BROTLI_COMPRESSION_LEVEL = 6;

And also in my .env file in development:

BROTLI_COMPRESSION_LEVEL=11

Now we set our compression level as a constant in our JavaScript for use later in the code:

const brotliCompressionLevel = parseInt(process.env.BROTLI_COMPRESSION_LEVEL || DEFAULT_BROTLI_COMPRESSION_LEVEL, 10);

Since our environment variable is currently set, compression will be set to 11, but if that variable isn't set, it will fall back to 6, the default value set above.

Cloudflare and Brotli

Before we go through the Brotli compression code, it's a good time to mention that Cloudflare does something automatically that is very useful for compressed files. Cloudflare Pages will automatically serve Brotli-compressed files (.br) if available, with no additional configuration required on the Cloudflare side. See the Content Compression Documentation on Cloudflare for more information.

This means we don't need to rename the compressed CSS file from index-hash.css.br back to index-hash.css for a user's browser to recognise it as a CSS file. Handy huh! Don't worry if you don't use Cloudflare Pages, I also have a version written that renames the CSS file back to index-hash-compressed.css for non-Cloudflare Pages, readers.

Important: While testing the documented method above, I could not find a way to confirm that my static compressed version was being served automatically. So in the code below I have removed this assumption and explicitly added my statically compressed version to the <link> tag. Please do let me know if I'm interpreting the documentation for this functionality wrong! As I'd love to see it in action, and also how you verify the .br file is actually being served automatically?

Brotli Compression code

Now that I've covered that bit of (potential) Cloudflare Pages automation, let's have a look at the actual compression code:

// Brotli compression

// The output filename for the compressed file
const brotliFilename = `${finalFilename}.br`;
// Only compress to Brotli if the file doesn't exist
if (!fs.existsSync(brotliFilename)) {
	// Set our zlib options here e.g. compression
	const brotliOptions = {
		level: brotliCompressionLevel // Use the level specified in the environment
	};
	// zlib does it's compression magic!
	const brotliBuffer = zlib.brotliCompressSync(Buffer.from(processedCSS), brotliOptions);
	// Write the compressed code to the output filename defined above
	await fs.promises.writeFile(brotliFilename, brotliBuffer);
}

Generate the CSS `<link>` tag

The last thing to do now is mostly the same as what I had in the original code set out above:

// path manipulation for final URL
const hashedPath = brotliFilename.replace(path.join('./_site'), '').replace(/\\/g, '/');
// return our final link element with optimised and fingerprinted CSS.
return `<link rel="stylesheet" href="${hashedPath}">`;

Only this time I'm modifying the path to the Brotli compressed filename rather than the original uncompressed CSS file! Simple!

On Development: Once added to the 11ty config as per my previous post, my development CSS looks like this:

// uncompressed CSS with no fingerprinting, auto-reload still functioning
<link rel="stylesheet" href="/css/index.css">

On Production: The CSS looks like this:

// Brotli 11 compressed, minified and fingerprinted CSS
<link rel="stylesheet" href="/css/index-b9fcfe85ef.css.br">

This is the version I have running on the site at the moment, why not view the page source and take a look.

Finishing touches

That's the bulk of the work done, but if you were to run this code on production at present you'd get a page full of naked HTML and no styling. This is because the Cloudflare Pages _headers file needs to be modified, as Cloudflare Pages is now serving my Brotli 11 compressed CSS file, not the uncompressed version we had before.

Simply add the following to your _headers file:

/css/*
Content-Encoding: br
Vary: Accept-Encoding
Content-Type: text/css

It's important to remember that this headers file is looking at the path from which the file is served on the production website! It isn't (and can't) use an extension wildcard, as Cloudflare pages doesn't support it. It took me a while to figure this out I must admit!

So for example, The following doesn't work:

*.css
Content-Encoding: br
Vary: Accept-Encoding
Content-Type: text/css

When I first migrated to Cloudflare Pages, I tried it and couldn't work out why it wasn't working. /css/* is basically saying: "Any file that resides in the css directory on production will be served with the following headers".

Lastly, remember to add the following to your Cloudflare Pages environment variables. This can be plaintext if you like, since the variable is only storing a single integer (not a secret API key):

BROTLI_COMPRESSION_LEVEL=11

Once added, you should be good to go!

Final code

As promised, below is the final code that I just described above:

import zlib from 'zlib';
import dotenv from "dotenv";
import CleanCSS from 'clean-css';
import fs from 'fs';
import crypto from 'crypto';
import path from 'path';
dotenv.config();

// An example of how you could add additional CleanCSS settings if required
const cleanCSS = new CleanCSS({
	level: {
		2: {
			removeDuplicateRules: true
		}
	}
});

// Default Brotli compression level if not set in the environment
const DEFAULT_BROTLI_COMPRESSION_LEVEL = 6;

export function manipulateCSS(eleventyConfig) {
	eleventyConfig.addShortcode("customCSS", async function(cssPath) {
		if (process.env.ELEVENTY_ENV === 'development') {
			return `<link rel="stylesheet" href="${cssPath}">`;
		}

		const inputFile = path.join('./public', cssPath);
		const outputDirectory = path.join('./_site', 'css');
		const cacheDirectory = path.join('./.cache', 'css');

		// Get compression level from the environment or use the default
		const brotliCompressionLevel = parseInt(process.env.BROTLI_COMPRESSION_LEVEL || DEFAULT_BROTLI_COMPRESSION_LEVEL, 10);

		try {
			if (!fs.existsSync(inputFile)) {
				console.error(`Input CSS file not found: ${inputFile}`);
				return '';
			}

			for (const dir of [cacheDirectory, outputDirectory]) {
				if (!fs.existsSync(dir)) {
					fs.mkdirSync(dir, { recursive: true });
				}
			}

			const inputCSS = await fs.promises.readFile(inputFile, 'utf8');
			const hash = crypto.createHash('sha256').update(inputCSS).digest('hex').slice(0, 10);

			const cacheKey = `${hash}-${cssPath.replace(/[\/\\]/g, '-')}`;
			const cachePath = path.join(cacheDirectory, cacheKey);

			let processedCSS;
			if (fs.existsSync(cachePath)) {
				processedCSS = await fs.promises.readFile(cachePath, 'utf8');
			} else {
				processedCSS = cleanCSS.minify(inputCSS).styles;
				await fs.promises.writeFile(cachePath, processedCSS);
			}

			const parsedPath = path.parse(inputFile);
			const finalFilename = path.join(outputDirectory, `${parsedPath.name}-${hash}${parsedPath.ext}`);
			await fs.promises.writeFile(finalFilename, processedCSS);

			// Brotli compression

			// The output filename for the compressed file
			const brotliFilename = `${finalFilename}.br`;

			// Only compress to Brotli if the file doesn't exist
			if (!fs.existsSync(brotliFilename)) {
				// Set our zlib options here e.g. compression
				const brotliOptions = {
					level: brotliCompressionLevel // Use the level specified in the environment
				};
				// zlib does it's compression magic!
				const brotliBuffer = zlib.brotliCompressSync(Buffer.from(processedCSS), brotliOptions);
				// Write the compressed code to the output filename defined above
				await fs.promises.writeFile(brotliFilename, brotliBuffer);
			}

			const hashedPath = brotliFilename.replace(path.join('./_site'), '').replace(/\\/g, '/');
			return `<link rel="stylesheet" href="${hashedPath}">`;
		} catch (err) {
			console.error("Error processing CSS:", err);
			return "";
		}
	});
}

And here's a Gist for the code as well!

With file renaming

Now I understand not everyone will want to serve their CSS files using the .br extension. So there's a version below that also renames the file for you back to .css, and adds the -compressed suffix to the filename as well. The rest of the code is identical to the version above:

import zlib from 'zlib';
import dotenv from "dotenv";
import CleanCSS from 'clean-css';
import fs from 'fs';
import crypto from 'crypto';
import path from 'path';
dotenv.config();

// An example of how you could add additional CleanCSS settings if required
const cleanCSS = new CleanCSS({
	level: {
		2: {
			removeDuplicateRules: true
		}
	}
});

// Default Brotli compression level if not set in the environment
const DEFAULT_BROTLI_COMPRESSION_LEVEL = 6;

export function manipulateCSS(eleventyConfig) {
	eleventyConfig.addShortcode("customCSS", async function(cssPath) {
		if (process.env.ELEVENTY_ENV === 'development') {
			return `<link rel="stylesheet" href="${cssPath}">`;
		}

		const inputFile = path.join('./public', cssPath);
		const outputDirectory = path.join('./_site', 'css');
		const cacheDirectory = path.join('./.cache', 'css');

		// Get compression level from the environment or use the default
		const brotliCompressionLevel = parseInt(process.env.BROTLI_COMPRESSION_LEVEL || DEFAULT_BROTLI_COMPRESSION_LEVEL, 10);

		try {
			if (!fs.existsSync(inputFile)) {
				console.error(`Input CSS file not found: ${inputFile}`);
				return '';
			}

			for (const dir of [cacheDirectory, outputDirectory]) {
				if (!fs.existsSync(dir)) {
					fs.mkdirSync(dir, { recursive: true });
				}
			}

			const inputCSS = await fs.promises.readFile(inputFile, 'utf8');
			const hash = crypto.createHash('sha256').update(inputCSS).digest('hex').slice(0, 10);

			const cacheKey = `${hash}-${cssPath.replace(/[\/\\]/g, '-')}`;
			const cachePath = path.join(cacheDirectory, cacheKey);

			let processedCSS;
			if (fs.existsSync(cachePath)) {
				processedCSS = await fs.promises.readFile(cachePath, 'utf8');
			} else {
				processedCSS = cleanCSS.minify(inputCSS).styles;
				await fs.promises.writeFile(cachePath, processedCSS);
			}

			const parsedPath = path.parse(inputFile);
			const finalFilename = path.join(outputDirectory, `${parsedPath.name}-${hash}${parsedPath.ext}`);
			await fs.promises.writeFile(finalFilename, processedCSS);

			// Brotli compression with renaming
			const compressedFilename = path.join(outputDirectory, `${parsedPath.name}-${hash}-compressed${parsedPath.ext}`);
			// Only compress to Brotli if the file doesn't exist
			if (!fs.existsSync(compressedFilename)) {
				// Set our zlib options here e.g. compression
				const brotliOptions = {
					level: brotliCompressionLevel
				};
				// zlib does it's compression magic!
				const brotliBuffer = zlib.brotliCompressSync(Buffer.from(processedCSS), brotliOptions);
				// Write the compressed code to the output filename defined above
				await fs.promises.writeFile(compressedFilename, brotliBuffer);
			}

			const hashedPath = compressedFilename.replace(path.join('./_site'), '').replace(/\\/g, '/');
			return `<link rel="stylesheet" href="${hashedPath}">`;
		} catch (err) {
			console.error("Error processing CSS:", err);
			return "";
		}
	});
}

The Gist for the code above is here.

The above code will do the following:

On Development: It will simply output:

<link rel="stylesheet" href="/css/index.css">

Exactly as it did in the previous version.

On Production: This is the output that will be seen:

<link rel="stylesheet" href="/css/index-b9fcfe85ef-compressed.css">

In this instance, the CSS file has been Brotli compressed to 11, but it has also been renamed with the -compressed suffix and the .br extension has been removed. Technically, you don't need the suffix, but I've added it to emphasise (and remind myself) that it isn't a "standard" CSS file in plain text.

And as I mentioned in the previous CSS Shortcode blog post. You'll now be able to use long cache life headers like:

/[css]/*
Cache-Control: public, max-age=31536000, immutable

Safe in the knowledge that updating your CSS will generate a brand-new filename, effectively nullifying the existing cache. Check out the previous post if you want more details on the above _headers file code for Cloudflare.

Summary

Fantastic! You made it to the end of yet another 11ty blog post of mine, congrats! I'm not sure if there's anything else I can do to optimise my CSS delivery to users at the moment?

Maybe preloading or the Speculation Rules API? Which Cloudflare already supports, and is currently enabled on my site. This functionality is called "Speed Brain" in the Cloudflare dashboard (under the "Speed" then "Content Optimization"). It's worth noting that this functionality is currently in Beta. But I don't think I need to do anything manually to use it, since Cloudflare rolled it out to all plans (including the free plan!), back in September 2024.

But perhaps there are other optimisations I can make? Unknown, unknowns etc… As always, thanks for reading, I hope you found the post useful and if you have any feedback or comments let me know!

Post changelog:

23/01/25: Initial post published.

Using an 11ty Shortcode to craft a custom CSS pipeline

2025-01-12T00:00:00Z

I know I'm still a bit of a 11ty n00b, so I hope this isn't frowned upon in the community, but on rebuilding my blog using 11ty, I decided not to use the standard Bundle plugin that was added in v3.0.0. Instead, I decided to write a custom Shortcode to customise my CSS output. In this blog post, I will go through the code I have written in the hope it will help others and more importantly gather feedback from the community, to see if any improvements can be made to the code. Please do let me know if you have any feedback.

My Requirements

First, what am I hoping to achieve with this Shortcode solution?

Maintain the auto-reload functionality that comes with 11ty when you modify your CSS locally (this is a super helpful feature I've been a big fan of since LiveReload was released back in February 2011, and later BrowserSync).
Filename fingerprinting to allow me to use long-life Cache-Control response headers without having to worry about cache becoming outdated. (e.g. max-age=31536000, immutable)
The ability to optimise my CSS output using the excellent clean-css Node plugin. It does more than just minify! Check out all the optimisations it can help you if you haven't seen them.
Minimal impact on the 11ty build process by leveraging build caching in some way.
Set it and forget it, once it's added It requires minimal (or no ongoing maintenance), apart from updating dependencies, every so often!

The Code

I'll quit the waffling and just show you the code I currently have building my CSS for this site. This code sits in its own file called css-manipulation.js in a _helpers directory in my 11ty root (i.e. the same level as _data).

/**
 * CSS Manipulation Module for Eleventy
 *
 * This module provides CSS processing, minification, and compression functionality
 * for an Eleventy static site generator. It handles:
 * - CSS minification using CleanCSS
 * - Content-based file hashing for cache busting
 * - Brotli compression for optimized delivery
 * - Build-time caching to avoid redundant processing
 * - Concurrent request handling to prevent duplicate work
 */

// Node.js built-in modules for file system operations, path manipulation, and hashing
import crypto from "crypto"; // Used to create SHA-256 hashes of CSS content for cache busting
import fs from "fs"; // File system operations (reading/writing files, checking existence)
import path from "path"; // Cross-platform path manipulation and joining
// Node.js zlib module for Brotli compression
// Brotli is a modern compression algorithm that provides better compression ratios than gzip
import { brotliCompressSync } from "zlib";

// CleanCSS library for CSS minification and optimization
// This performs a wide range of optimizations to reduce file size
import CleanCSS from "clean-css";

// Environment configuration to check if we're in local development mode
import env from "../_data/env.js";

/**
 * CleanCSS Configuration
 *
 * CleanCSS performs multi-level CSS optimization. This configuration enables
 * comprehensive minification while maintaining CSS functionality.
 *
 * Level 1 optimizations (basic cleanups):
 * - cleanupCharsets: Remove unnecessary @charset declarations
 * - normalizeUrls: Normalize and optimize URL() references
 * - optimizeBackground: Optimize background properties
 * - optimizeBorderRadius: Shorten border-radius values
 * - optimizeFilter: Optimize filter() functions
 * - optimizeFont: Optimize font-family declarations
 * - optimizeFontWeight: Convert font-weight to numeric values
 * - optimizeOutline: Optimize outline properties
 * - removeEmpty: Remove empty CSS rules
 * - removeNegativePaddings: Remove invalid negative padding values
 * - removeQuotes: Remove unnecessary quotes from URLs and identifiers
 * - removeWhitespace: Remove unnecessary whitespace
 * - replaceMultipleZeros: Shorten multiple zero values
 * - replaceTimeUnits: Optimize time unit values (e.g., 0s → 0)
 * - replaceZeroUnits: Remove units from zero values (e.g., 0px → 0)
 * - roundingPrecision: Round numeric values to 2 decimal places
 * - selectorsSortingMethod: Sort selectors in a standard order
 * - specialComments: Remove all comments (set to "none")
 * - tidyAtRules: Clean up @-rules
 * - tidyBlockScopes: Clean up block scopes
 * - tidySelectors: Clean up and optimize selectors
 * - transform: Custom transformation function (empty, no custom transforms)
 *
 * Level 2 optimizations (advanced restructuring):
 * - mergeAdjacentRules: Combine adjacent CSS rules with same selectors
 * - mergeIntoShorthands: Convert long-form properties to shorthand
 * - mergeMedia: Combine @media rules with same conditions
 * - mergeNonAdjacentRules: Merge duplicate rules even if not adjacent
 * - mergeSemantically: Disabled to avoid potentially breaking semantic merges
 * - overrideProperties: Remove overridden properties
 * - removeEmpty: Remove empty rules at level 2
 * - reducePadding: Optimize padding values
 * - reducePositions: Optimize position values
 * - reduceTimingFunctions: Optimize animation timing functions
 * - reduceTransforms: Optimize transform functions
 * - restructureRules: Disabled to avoid aggressive restructuring that might break CSS
 * - skipProperties: Empty array means optimize all properties
 *
 * Format options (output formatting):
 * - All breaks set to false: Output as single line (no line breaks)
 * - indentBy: 0 (no indentation for minimal file size)
 * - indentWith: "space" (if indentation were enabled)
 * - All spaces set to false: Remove unnecessary spaces
 * - wrapAt: false (no line wrapping)
 *
 * Other options:
 * - inline: ["none"] - Don't inline any @import rules
 * - rebase: false - Don't rebase URLs (keep original paths)
 * - returnPromise: false - Use synchronous API (we handle async ourselves)
 */
const cleanCSS = new CleanCSS({
	level: {
		1: {
			cleanupCharsets: true,
			normalizeUrls: true,
			optimizeBackground: true,
			optimizeBorderRadius: true,
			optimizeFilter: true,
			optimizeFont: true,
			optimizeFontWeight: true,
			optimizeOutline: true,
			removeEmpty: true,
			removeNegativePaddings: true,
			removeQuotes: true,
			removeWhitespace: true,
			replaceMultipleZeros: true,
			replaceTimeUnits: true,
			replaceZeroUnits: true,
			roundingPrecision: 2,
			selectorsSortingMethod: "standard",
			specialComments: "none",
			tidyAtRules: true,
			tidyBlockScopes: true,
			tidySelectors: true,
			transform: function () {},
		},
		2: {
			mergeAdjacentRules: true,
			mergeIntoShorthands: true,
			mergeMedia: true,
			mergeNonAdjacentRules: true,
			mergeSemantically: false,
			overrideProperties: true,
			removeEmpty: true,
			reducePadding: true,
			reducePositions: true,
			reduceTimingFunctions: true,
			reduceTransforms: true,
			restructureRules: false,
			skipProperties: [],
		},
	},
	format: {
		breaks: {
			afterAtRule: false,
			afterBlockBegins: false,
			afterBlockEnds: false,
			afterComment: false,
			afterProperty: false,
			afterRuleBegins: false,
			afterRuleEnds: false,
			beforeBlockEnds: false,
			betweenSelectors: false,
		},
		indentBy: 0,
		indentWith: "space",
		spaces: {
			aroundSelectorRelation: false,
			beforeBlockBegins: false,
			beforeValue: false,
		},
		wrapAt: false,
	},
	inline: ["none"],
	rebase: false,
	returnPromise: false,
});

/**
 * Default Brotli Compression Level
 *
 * Brotli compression levels range from 0-11:
 * - 0: Fastest, least compression
 * - 11: Slowest, best compression (maximum)
 *
 * Level 11 is used by default for production builds where file size matters
 * more than compression time. This can be overridden via BROTLI_COMPRESSION_LEVEL
 * environment variable.
 */
const DEFAULT_BROTLI_COMPRESSION_LEVEL = 11;

/**
 * In-Memory Build Cache
 *
 * This Map caches CSS processing results during a single build run.
 * It serves two purposes:
 * 1. Prevents re-processing the same CSS file when multiple pages reference it
 * 2. Handles concurrent requests by storing Promises during processing
 *
 * Structure:
 * - Key: cssPath (the original CSS file path)
 * - Value: Either a Promise (if processing is in progress) or an object with:
 *   - hash: Content hash of the CSS file
 *   - processedCSS: The minified CSS string
 *   - htmlOutput: The final HTML <link> tag string
 *
 * This cache is cleared between builds (per-process, not persisted).
 */
const cssBuildCache = new Map();

/**
 * Directory Creation Tracking
 *
 * Tracks which directory combinations have been created during this build.
 * This prevents redundant fs.existsSync() and fs.mkdirSync() calls when
 * multiple CSS files are processed.
 *
 * Structure: Set of strings like "cacheDir:outputDir"
 */
const directoriesCreated = new Set();

/**
 * Main Function: manipulateCSS
 *
 * Registers a custom Eleventy shortcode that processes CSS files.
 * The shortcode can be used in templates like: 
 *
 * Processing Pipeline:
 * 1. Check if in local development mode (skip processing)
 * 2. Check in-memory cache (avoid duplicate processing)
 * 3. Read and hash the CSS file
 * 4. Check disk cache for minified CSS
 * 5. Minify CSS if not cached
 * 6. Write processed CSS with hash-based filename
 * 7. Compress with Brotli
 * 8. Return HTML <link> tag with hashed filename for cache busting
 *
 * @param {object} eleventyConfig - The Eleventy configuration object
 */
export function manipulateCSS(eleventyConfig) {
	/**
	 * Register the "customCSS" shortcode with Eleventy
	 * This makes it available in all templates as 
	 *
	 * @param {string} cssPath - The relative path to the CSS file (from /public directory)
	 * @returns {Promise<string>} - HTML string containing a <link> tag pointing to the processed CSS
	 */
	eleventyConfig.addShortcode("customCSS", async function (cssPath) {
		/**
		 * Stage 1: Local Development Short-Circuit
		 *
		 * In local development, skip all processing to speed up builds.
		 * Just return a simple <link> tag pointing to the original file.
		 * This allows for faster iteration during development.
		 */
		if (env.isLocal) {
			return `<link rel="stylesheet" href="${cssPath}">`;
		}

		/**
		 * Stage 2: In-Memory Cache Check
		 *
		 * Check if we've already processed this CSS file during this build.
		 * This handles the common case where multiple pages reference the same CSS file.
		 *
		 * The cache can contain:
		 * - A Promise: Processing is currently in progress, wait for it
		 * - An object: Processing is complete, return the cached HTML output
		 */
		if (cssBuildCache.has(cssPath)) {
			const cached = cssBuildCache.get(cssPath);
			// If it's a promise (in progress), wait for it
			// This handles concurrent requests - multiple pages calling this shortcode
			// simultaneously for the same CSS file will all wait for the same processing
			if (cached instanceof Promise) {
				return await cached;
			}
			// Otherwise return cached result immediately (already HTML string)
			// This is the fast path for subsequent page builds
			return cached.htmlOutput;
		}

		/**
		 * Stage 3: Initialize Processing
		 *
		 * Set up file paths and configuration for processing.
		 */
		// Construct full paths for input/output/cache directories
		const inputFile = path.join("./public", cssPath); // Source CSS file location
		const outputDirectory = path.join("./_site", "css"); // Where processed CSS goes (build output)
		const cacheDirectory = path.join("./.cache", "css"); // Where minified CSS cache is stored

		/**
		 * Stage 4: Get Brotli Compression Level
		 *
		 * Read compression level from environment variable or use default.
		 * This allows fine-tuning compression vs. speed trade-off per environment.
		 * Higher levels = better compression but slower processing.
		 */
		const brotliCompressionLevel = parseInt(
			process.env.BROTLI_COMPRESSION_LEVEL || DEFAULT_BROTLI_COMPRESSION_LEVEL,
			10, // Base 10 parsing
		);

		/**
		 * Stage 5: Create Processing Promise
		 *
		 * Wrap all processing in an async IIFE (Immediately Invoked Function Expression).
		 * This allows us to:
		 * 1. Handle concurrent requests by caching the Promise itself
		 * 2. Catch errors at the processing level
		 * 3. Return the same Promise to multiple concurrent callers
		 */
		const processingPromise = (async () => {
			try {
				/**
				 * Stage 5.1: Validate Input File Exists
				 *
				 * Check if the source CSS file exists before attempting to process it.
				 * If missing, log an error and return empty string (fails gracefully).
				 */
				if (!fs.existsSync(inputFile)) {
					return "";
				}

				/**
				 * Stage 5.2: Ensure Directories Exist
				 *
				 * Create output and cache directories if they don't exist.
				 * Uses a Set to track which directory combinations have been created
				 * during this build to avoid redundant checks and operations.
				 *
				 * recursive: true ensures parent directories are created if needed.
				 */
				const dirKey = `${cacheDirectory}:${outputDirectory}`;
				if (!directoriesCreated.has(dirKey)) {
					for (const dir of [cacheDirectory, outputDirectory]) {
						if (!fs.existsSync(dir)) {
							fs.mkdirSync(dir, { recursive: true });
						}
					}
					directoriesCreated.add(dirKey);
				}

				/**
				 * Stage 5.3: Read and Hash CSS File
				 *
				 * Read the source CSS file and generate a content-based hash.
				 * The hash is used for:
				 * - Cache busting (filename changes when content changes)
				 * - Disk cache key (identify if we've seen this content before)
				 *
				 * SHA-256 is used for strong collision resistance.
				 * Only first 10 characters of hash are used (sufficient for cache busting).
				 *
				 */
				const inputCSS = await fs.promises.readFile(inputFile, "utf8");
				const hash = crypto
					.createHash("sha256") // Use SHA-256 algorithm
					.update(inputCSS) // Hash the CSS content
					.digest("hex") // Get hexadecimal representation
					.slice(0, 10); // Take first 10 chars (sufficient for uniqueness)
				/**
				 * Stage 5.4: Generate Cache Key and Path
				 *
				 * Create a unique cache key combining:
				 * - The content hash (identifies file contents)
				 * - The file path (normalized to avoid path separator issues)
				 *
				 * This allows different CSS files with same content to share cache,
				 * but also handles edge cases where paths matter.
				 */
				const cacheKey = `${hash}-${cssPath.replace(/[/\\]/g, "-")}`;
				const cachePath = path.join(cacheDirectory, cacheKey);

				/**
				 * Stage 5.5: Minify CSS (or Load from Disk Cache)
				 *
				 * Check if we've already minified this exact CSS content before.
				 * Disk cache persists between builds, so unchanged CSS files don't
				 * need re-minification even after restarting the build process.
				 *
				 * If cached:
				 * - Load the pre-minified CSS from disk
				 * - Skip the expensive minification step
				 *
				 * If not cached:
				 * - Run CleanCSS minification (expensive operation)
				 * - Save result to disk cache for next time
				 */
				let processedCSS;
				if (fs.existsSync(cachePath)) {
					// Cache hit - load pre-minified CSS
					processedCSS = await fs.promises.readFile(cachePath, "utf8");
				} else {
					// Cache miss - minify and save
					processedCSS = cleanCSS.minify(inputCSS).styles;
					await fs.promises.writeFile(cachePath, processedCSS);
				}

				/**
				 * Stage 5.6: Write Processed CSS to Output Directory
				 *
				 * Write the minified CSS to the build output directory with a
				 * hash-based filename. The hash in the filename enables:
				 * - Cache busting (browser cache invalidates when content changes)
				 * - Long-term caching (files with same hash are unchanged)
				 *
				 * Filename format: original-name-hash.css
				 * Example: main-a1b2c3d4e5.css
				 *
				 * Only write if file doesn't exist to avoid redundant disk I/O
				 * (useful when multiple pages reference the same CSS).
				 */
				const parsedPath = path.parse(inputFile); // Parse original filename
				const finalFilename = path.join(
					outputDirectory,
					`${parsedPath.name}-${hash}${parsedPath.ext}`, // name-hash.css
				);
				if (!fs.existsSync(finalFilename)) {
					await fs.promises.writeFile(finalFilename, processedCSS);
				}

				/**
				 * Stage 5.7: Brotli Compression
				 *
				 * Compress the minified CSS using Brotli algorithm.
				 * Brotli provides better compression than gzip, especially for text.
				 *
				 * The .br extension indicates Brotli-compressed files.
				 * Web servers can serve these directly to browsers that support Brotli
				 * (most modern browsers do via Accept-Encoding header).
				 *
				 * Compression happens synchronously (brotliCompressSync) because:
				 * - It's fast enough for build-time processing
				 * - Simplifies error handling
				 * - Build processes typically prefer synchronous operations
				 *
				 * Only compress if file doesn't exist (avoid redundant compression).
				 */
				const brotliFilename = `${finalFilename}.br`; // Add .br extension
				if (!fs.existsSync(brotliFilename)) {
					const brotliOptions = {
						level: brotliCompressionLevel, // Compression level (0-11)
					};
					const brotliBuffer = brotliCompressSync(
						Buffer.from(processedCSS), // Convert string to Buffer
						brotliOptions,
					);
					await fs.promises.writeFile(brotliFilename, brotliBuffer);
				}

				/**
				 * Stage 5.8: Generate Final HTML Output
				 *
				 * Create the HTML <link> tag that will be inserted into the page.
				 * The path is relative to the site root and uses forward slashes
				 * (normalized for web URLs, works on all platforms).
				 *
				 * Note: The HTML references the .br file, assuming the web server
				 * can serve Brotli-compressed files when the browser supports it.
				 * If your server doesn't handle .br files, you may need to modify
				 * this to point to the uncompressed file or configure your server.
				 */
				const hashedPath = brotliFilename
					.replace(path.join("./_site"), "") // Remove build directory prefix
					.replace(/\\/g, "/"); // Normalize path separators for web URLs

				const result = `<link rel="stylesheet" href="${hashedPath}">`;

				/**
				 * Stage 5.9: Cache Result in Memory
				 *
				 * Store the processing result in the in-memory cache for subsequent
				 * calls during this build. This includes:
				 * - hash: For reference/debugging
				 * - processedCSS: In case we need the CSS string later
				 * - htmlOutput: The final HTML tag (what we return)
				 *
				 * Replace the Promise in cache with the actual result object.
				 */
				cssBuildCache.set(cssPath, { hash, processedCSS, htmlOutput: result });
				return result;
			} catch {
				/**
				 * Error Handling
				 *
				 * Catch any errors during processing and fail gracefully.
				 * Return empty string to prevent one CSS file error from breaking the entire build.
				 */
				return "";
			}
		})();

		/**
		 * Stage 6: Handle Concurrent Requests
		 *
		 * Store the processing Promise in the cache BEFORE awaiting it.
		 * This ensures that if multiple pages call this shortcode simultaneously
		 * for the same CSS file, they all get the same Promise and wait for
		 * the same processing to complete (no duplicate work).
		 *
		 * Once processing completes, the Promise in cache is replaced with
		 * the result object (see Stage 5.9).
		 */
		cssBuildCache.set(cssPath, processingPromise);
		return await processingPromise;
	});
}

It's all a little clumsy to have the code only in the blog post, so I've created a gist on GitHub here for easier reading & copying and pasting (should you wish to use or modify it yourself).

Usage

So how would you use this code in 11ty? Let's go through each of the files you'd need to modify.

eleventy.config.js

Just your standard ESM 11ty config file with an import and the execution.

// Custom CSS manipulation
import { manipulateCSS } from './_helpers/css-manipulation.js';

export default async function(eleventyConfig) {
	// All your other 11ty config above...
	// execute the CSS manipulation
	manipulateCSS(eleventyConfig);
	// All your other 11ty config below...
}

.env

It sits in the 11ty root directory and is added to .gitignore.

ELEVENTY_ENV=development

HTML template

I, personally, have my HTML <head> separate and sitting in its own Nunjucks partial, but it will work with any template setup really. This Shortcode is using Nunjucks because that's what I use on this blog. Spaces added in the Nunjucks to stop 11ty just printing the output. The index.css is my one and only CSS file I use on this blog, and it is passed into the Shortcode. It is either used unmodified (in development), or manipulated (in production).

<head>
	{ % customCSS "/css/index.css" % }
</head>

Output

For my development environment the HTML output is:

<head>
	<link rel="stylesheet" href="/css/index.css">
</head>

There's no fingerprinting until it is built on production (in my case Cloudflare Pages). Where the output looks like this:

<head>
	<link rel="stylesheet" href="/css/index-b9fcfe85ef.css">
</head>

As you can see the index.css file that contains all the CSS for this site, now has a unique 10 character hash suffix. If I were to change a single byte of data in the CSS file it will generate an entirely new hash. For those wondering, a sha256 hash using only the first 10 characters still has 1,099,511,627,776 unique combinations, so the likelihood of a collision is pretty slim!

Since the name of my CSS file is now guaranteed to have a unique name I can use the following response headers for my CSS:

_headers file

We can now start to use Cache-Control directives that maximise the time that the CSS is stored in a user's browser cache.

/[css]/*
Cache-Control: public, max-age=31536000, immutable

Here we are telling the user's browser that:

public: This response can be cached by any cache, it isn't restricted to only a private cache (like a user's browser cache). Examples of other caches are CDNs, and proxies.
max-age=31536000: 31536000 seconds is the number of seconds in a year. So, this directive tells caches that they can store and reuse this response for up to a year without the need for revalidation.
immutable: This is a hint to the browser or cache system that the content will never change for the lifetime of the cache. Even if the user reloads the page, the browser won't bother checking with the server for updates.

There's a lot involved in caching on the web, so if you want to know a lot more about this fascinating topic, check out Cache-Control for Civilians by Harry Roberts.

For those wondering about what happens to the old "orphaned" files in the cache, in this instance:

The old file version will stay in the cache for up to 1 year (until the cache duration expires).
But it's more than likely that the browser will clean up the cache before the year expiry time to free up storage space. This is more likely on devices with limited resources like older phones, since devices with limited resources will need to be more aggressive with their resource management.
In either case, this isn't anything a user has to worry about. The browsers will take care of this automatically, although a user can manually clear their browser cache should they wish too.

Summary

There we go, another 11ty blog post! We've reviewed my current CSS setup, which works well for now, but as mentioned earlier, feel free to suggest improvements or point out anything that strays from the "11ty way". As, the path to true enlightenment starts with uncovering the unseen gaps in our (my) understanding. I read that last sentence in Master Yoda's voice! As always, thanks for taking the time to read the post. I hope you found it useful and informative, and if you have any comments or feedback, please do let me know.

Post changelog:

12/01/25: Initial post published.
02/11/25: Updated post and code after shortcode was found to run for every page generation in the build process. This was inefficient and is now limited to a single run per build.

JSON feed for my blog by Matt Hobbs (Nooshu.com)

How a Simple CSP Tweak Turned into an AI Project

Introduction

Problem

Features

Audit

Build

Improve

Deploy

Result

trusted-types (TT)

upgrade-insecure-requests

Summary

FractalAI: Generating Infinity in the Browser

Why I Built FractalAI

The Constraint: 100% AI-Generated Code

What FractalAI Actually Does

Why the Browser Is Surprisingly Good at Rendering Fractals

AI as a Design Partner, Not Just a Tool

The Architecture (Without Writing Code Myself)

Machine Learning Inside the Browser

What Worked Surprisingly Well

Planning

Crafted Prompts

Rules

Writing Tests

Refactoring

Proof of concepts

Making unfamiliar things make sense

Building momentum

Where AI Fell Short (and Needed Steering)

The definition of insanity

Over-engineering simple problems

AI output

Flexbox (modern)

Grid (modern)

Confidently wrong outputs

Inconsistent outputs between prompts

Prompt 1

Prompt 2

Performance blind spots

Forgetting earlier constraints

Elementary mistakes

Performance Challenges in the Browser

What Building This Changed About My View of AI

The Future of AI-Generated Software

Summary

FractalAI project

Using Cloudflare Workers and reCAPTCHA v3 for a Static Site Contact Form

Introduction

Previous solutions I’ve used

Netlify Forms

Cloudflare Pages Functions + MailChannels

Formspree.io

Formspark.io (previously Submit Form)

Botpoison

Resend

Overview of the setup

Google reCAPTCHA v3

Behavioural analysis of a user's session

Browser and device fingerprinting

Network and reputation signals

Action Context

Scoring using Machine learning

Technical setup

The contact form (HTML and client-side)

Honeypot and reCAPTCHA to block spam

Client and server validation to ensure safe input

Accessible error handling and focus management

UX updates to keep the user informed during submission

Secure server side processing

Simplified CSP

The Cloudflare Worker (Pages Function)

Using Cloudflare Turnstile

Why change?

Summary

Precompressed HTML at the Edge: Eleventy Meets Cloudflare Workers

Introduction

Caching

Compression

Why we need a Cloudflare Function instead of just the `_headers` file for HTML Brotli?

1. `_headers` can only change headers, not the file itself

The Cloudflare `_headers` file