Forem: Andrew Bone

The Diplomatic Core: Shared Logic in a Multi-Framework World

Andrew Bone — Wed, 11 Mar 2026 17:30:00 +0000

This is the third part in a tenuously linked series defending JavaScript singletons in a modern world. I've previously written about extending EventTarget to allow for a fully typed, native event bus and how to connect a singleton to React without having to worry about the UI going out of sync or unwanted re-render calls.

Today I'll be looking at how we can use singletons alongside Micro-Frontends (MFEs) in order to allow information and state to be passed around even if you're using different frameworks.

Framework Independence

In a modern and fast-paced work environment, you might find several different teams all working on the same project. While we might hope that everyone across all of those teams uses the same framework to make our lives easier, that is not always possible or cost-effective. Fortunately, that is where micro-frontends come in. They allow a single wrapper in one framework to contain children from another. It is quite common to see the app bar written in one framework to provide global navigation, while the content is written in whatever way the team working on it deems fit.

Because of this, we can often end up in a mess where the same feature is implemented several times across each MFE, simply because communication between different frontends and frameworks is hard. By moving our logic outside of this and calling the same singleton from each MFE, we suddenly have easy communication, and the experience for the end-user feels a lot more unified and succinct.

Implementing Framework Adapters

In my last post, I demonstrated how to create a ToastManager singleton and have it seamlessly connect with React. We are going to use the exact same singleton today, but connect it to a few more things.

Andrew Bone

Mar 4

React: Singletons aren't as evil as you think

#react #webdev #singleton

Comments 4

6 min read

I'm going to be using single-spa for this demo because it is straightforward and offers plenty of examples to work from. This is not a tutorial on single-spa specifically, so I may skip over some of the initial setup.

Adding the Singleton

To add the singleton, I created a directory at the top level called libs/shared-utility/src. This contains the exact code from my last post; no changes were required as the singleton is designed to be framework-agnostic.

To make consumption easier across the project, I set up a path alias so the singleton can be imported consistently. In the vite.config.ts, I added a resolve key to defineConfig:

resolve: {
  alias: {
    "@org/toast-service": resolve(
      __dirname, 
      "libs/shared-utility/src/toast-service.ts"
    )
  }
},

I then mirrored this in the tsconfig.json by adding a custom path:

"paths": {
  "@org/toast-service": ["./libs/shared-utility/src/toast-service.ts"]
}

With these in place, I can now import the singleton from anywhere in the monorepo using a clean, consistent import:

import { toastManager } from "@org/toast-service";

single-spa provides various adapters to support your framework of choice, and since our singleton is now accessible from any of them, we simply need to implement the consumers. I will not be doing a deep dive into the specific build process for each application in this post, but the full implementation details are available in the source code.

In my demonstration, I used React to handle the primary toast display logic, while a variety of other frameworks, all supported by single-spa, are used to trigger the toasts. This illustrates the benefits beautifully the emitting framework does not need to know anything about the receiving framework, as they both communicate solely through the shared singleton.

Live Demonstration

That is more than enough waffle from me; let us have a look at the demo.

Link2Twenty / multi-framework-singleton-demo

Render several MFEs to demonstrate shared singletons

Cross-Framework Singleton Micro Frontends

This is a sample project demonstrating how singletons can be successfully implemented and accessed by different frameworks when using a Micro Frontend (MFE) architecture.

The build is accessible here.

Overview

In a Micro Frontend application, sharing state or utilities across different standalone applications can be challenging. This project shows how a singleton (in this case, a shared Toast Service) can be instantiated once and utilized seamlessly across multiple MFEs built with different web frameworks.

Currently includes standalone triggers for:

React
Vue
SolidJS
Svelte
Preact
Vanilla JS

Inspiration and Context

This project draws inspiration from the concepts discussed in the article: React singletons aren't as evil as you think.

While singletons are sometimes considered an anti-pattern in standard monoliths, they offer a very practical and effective way to manage shared global state (like a toast bus, authentication state, or theme configurations) across disjointed micro frontends…

View on GitHub

Each element with a dotted border is a separate injected frontend. It is not common to have so many different frameworks on a single page, but for the sake of the demo, the more the merrier.

Click on the image or here to try the demo. Every button you see is part of a different framework application (React, Vue, Svelte, Preact, etc.), but they are all communicating with a single shared instance of our ToastManager.

Wrapping up

There we have it. We have the ability to allow multiple different micro-frontends to talk to each other as if they were all the same frontend. I think, if used correctly, this shows how powerful, lightweight and even type-safe the native web can be. Let me know if you have got anything like this in production or even if you have any reservations on this technique.

Thanks for reading! If you'd like to connect, here are my BlueSky and LinkedIn profiles. Come say hi 😊

React: Singletons aren't as evil as you think

Andrew Bone — Wed, 04 Mar 2026 18:43:16 +0000

In the world of React, the humble singleton gets a bit of a bad rap. It is often dismissed as a messy shortcut to global state, one that is difficult to track and even harder to test. But what if I told you the singleton is not the architectural terror you have been led to believe? What if I showed you it is actually powerful, lightweight and remarkably simple to implement? You might think me mad, but I am about to convince you that singletons are not the villains of the story.

The Singleton Scepticism

Historically, if you wanted to pull data from a singleton in React, you often had to wait for the app to re-render for some other reason. You might have seen a manual sync button or a poll used to bridge the gap, but it was rarely pretty.

import { useState, useEffect, useCallback } from 'react';
import SomeSingleton from '@/singletons/some';

export function ReactElement() {
  const [singletonData, setSingletonData] = useState(SomeSingleton.data || null);

  /**
   * Sync singleton and state
   */
  const handleRefresh = useCallback(() => {
    setSingletonData(SomeSingleton.data || null)
  }, []);

  // Trigger refresh every 5 seconds
  useEffect(() => {
    const interval = window.setInterval(handleRefresh, 5000);

    return () => window.clearInterval(interval);
  }, [handleRefresh]);

  return (
    <div>
      <span>{singletonData || 'N/A'}</span>
      <button onClick={handleRefresh}>Manual Refresh</button>
    </div>
  )
}

If this is what you are imagining when I say singletons are easy to implement, I understand the confusion. This is not a good way to implement them and it was not a good way back then either. Let me show you a much nicer approach.

import { useState, useEffect, useCallback } from 'react';
import SomeSingleton from '@/singletons/some';

export function ReactElement() {
  const [singletonData, setSingletonData] = useState(SomeSingleton.data || null);

  // Update the state as soon as things change in the singleton
  useEffect(() => {
    const ac = new AbortController();

    SomeSingleton.addEventListener('change', ({detail})=>{
      setSingletonData(detail);
    }, {signal: ac.signal})

    return () => ac.abort();
  }, []);

  return (
    <div>
      <span>{singletonData || 'N/A'}</span>
    </div>
  )
}

This is already much cleaner, more readable and less prone to falling behind. It does, however, require some work in the singleton to make the events happen and we will get to that shortly.

Even though this is now perfectly usable, there are a few more tips and tricks we can deploy to make it feel like native React state.

The Simplicity of Classes

Classes are native to JavaScript and as such have no extra package bloat to worry about. You simply define your class, initialise it and off you go.

Believe it or not, many parts of the language you probably use every day are classes that can be extended, such as Error, Array, Map or even HTMLElement. Having access to so many pre-made classes means that if we see a behaviour we want to use, we do not have to rewrite it or ship a library for it. We can simply extend the native class and it is there, in the browser, waiting for us.

That is the pitch: classes are powerful because we can extend native behaviour, lightweight because they are built into the engine and easy to implement because the documentation is simply the web spec.

Typed Target Event

Earlier I mentioned wanting our singletons to be able to fire events. We can extend EventTarget to do exactly this. However, if you are using TypeScript (and I hope you are) the native implementation can feel a little loose. I have previously written about how to make EventTarget a bit more type-safe to ensure your messaging remains robust.

Andrew Bone

Feb 28

Type-Safe CustomEvents: Better Messaging with Native APIs

#typescript #eventdriven #webdev

Comments 7

3 min read

A Problem to Solve

Let us come up with a problem that we do not necessarily need to solve, simply to show off what we can do. The problem I have chosen is a toast manager. We definitely do not need to build one from scratch given that sonner and toastify both exist and are excellent, but this will go a lot smoother with a tangible demo.

Building a notification system is the perfect test for our singleton architecture. It needs to be accessible from any part of the application, it must handle its own timers and it should be able to trigger UI updates without being coupled to a specific component tree.

The Singleton

As discussed, we are going to extend my TypedEventTarget class, which itself is built on the native EventTarget class. We are going to need a list of toasts, a method to add toasts, a method to remove toasts early and a timer that will remove toasts after enough time has elapsed. We will also have to fire an event every time the list of toasts has changed. Simple enough.

First, let us define some types. I am doing this in TypeScript but you do not have to; feel free to skip this bit if you prefer.

export interface Toast {
  id: string;
  message: string;
  type: "info" | "success" | "loading" | "error";
  action?: {
    label: string;
    callback: () => void;
  };
}

type ToastEvents = {
  changed: void;
};

Now that we have our types, we know what a toast object looks like and what events will be fired. Let us set up the class next. We know it will extend TypedEventTarget and will have some private internals to hide away.

class ToastManager extends TypedEventTarget<ToastEvents> {
  private _toasts: Toast[] = [];
  private _timers = new Map<string, number>();
}

This is a good start, but our _toasts property is private, meaning we cannot access it from outside the class, and currently we would have to manually dispatch an event every time we update it. Getters and setters to the rescue.

get toasts() {
  return this._toasts;
}

private set toasts(value: Toast[]) {
  this._toasts = [...value];
  this.dispatchEvent("changed");
}

Now we can read our toasts property and even update it internally, but we still cannot control this class externally. We need to add some methods.

// add or update a toast item
add = (toast: Omit<Toast, "id"> & { id?: string }, duration = 3000) => {
  const id = toast.id ?? Math.random().toString(36).substring(2, 9);
  this.clearTimer(id);

  const newToast = { ...toast, id };
  const exists = this.toasts.some((t) => t.id === id);

  if (exists) {
    this.toasts = this.toasts.map((t) => (t.id === id ? newToast : t));
  } else {
    this.toasts = [...this.toasts, newToast];
  }

  if (duration > 0) {
    const timer = window.setTimeout(() => this.remove(id), duration);
    this._timers.set(id, timer);
  }

  return id;
};

// remove a toast and its timer
remove = (id: string) => {
  this.clearTimer(id);
  const index = this.toasts.findIndex(({ id: _id }) => _id === id);

  if (index >= 0) {
    this.toasts = this.toasts.filter(({ id: _id }) => _id !== id);
  }
};

// remove a timer
private clearTimer(id: string) {
  if (this._timers.has(id)) {
    clearTimeout(this._timers.get(id));
    this._timers.delete(id);
  }
}

Finally, we instantiate our class and export it.

export const toastManager = new ToastManager();

I do not know about you, but this does not feel like a lot of code. The addition of TypeScript means we get the safety net of auto-completion and type checking without the bloat of a heavy library.

The Connection

When I showed you how to connect to a singleton with a useEffect earlier, I mentioned that it did not quite feel like it was a natural part of React. This is where useSyncExternalStore comes in. It allows us to define a subscription to an external source and a function to retrieve a snapshot of that state, handling the synchronisation for us.

First, we need to create the functions to pass to the hook.

import { toastManager } from '@/singletons/toastManager';

// Add an event listener
const subscribe = (callback: () => void) => {
  const ac = new AbortController();

  toastManager.addEventListener("changed", callback, {
    signal: ac.signal,
  });

  return () => ac.abort();
};

// Get the state
const getSnapshot = () => toastManager.toasts;

Now we can put it all together inside a component.

import { useSyncExternalStore } from 'react';

export default function ToastContainer() {
  const toastList = useSyncExternalStore(subscribe, getSnapshot);

  return (
    <ul>
      {toastList.map(({id, message}) => (<li key={id}>{message}</li>))}
    </ul>
  );
}

This is a somewhat simplistic implementation, but it demonstrates the core principle. We have full access to the data inside the singleton and it triggers a React render cycle whenever the internal state updates. By using useSyncExternalStore, we ensure that our UI is always in sync with our source of truth, without having to manually manage state variables or worry about stale closures.

The Demo

There we have it: a toast manager singleton that feeds into React whenever it needs to, allowing for the controlling and monitoring of toasts from anywhere in the application. I have not gone as far as making a feature-complete product and it certainly will not win any awards for its looks, but please do enjoy the demo.

Closing words

Have I convinced you, or are you still against singletons? Perhaps you were already a fan. I am happy to continue the discussion in the comments. You might be surprised to know that the new, at the time of writing, TanStack Hotkeys actually works in a similar way, with a singleton controller connected to React, or indeed any other library.

Thanks for reading! If you'd like to connect, here are my BlueSky and LinkedIn profiles. Come say hi 😊

Type-Safe CustomEvents: Better Messaging with Native APIs

Andrew Bone — Sat, 28 Feb 2026 21:49:00 +0000

The native EventTarget is a hidden gem for internal messaging. It is built-in, fast and stays out of your way. However, the standard CustomEvent interface is a bit of a "black box" for TypeScript. Usually, you end up casting e as CustomEvent<MyData> every time you want to access your data.

We can do better. By wrapping the target and the event creation, we can have a completely type-safe event bus with zero runtime overhead.

The Problem

When you dispatch a CustomEvent, the data is tucked away in the detail property. Out of the box, addEventListener has no idea what that detail contains, forcing you to manually type your listeners.

The Solution: TypedEventTarget

We can use a generic map to link event names to their specific CustomEvent payloads.

type EventListener<E extends Event> = (evt: E) => void;

interface EventListenerObject<E extends Event> {
  handleEvent(evt: CustomEvent<E>): void;
}

// The type of our listener receives the CustomEvent with our specific data
type TEL<E> = EventListener<CustomEvent<E>> | EventListenerObject<CustomEvent<E>>;

export class TypedEventTarget<M extends Record<string, unknown>> {
  private readonly target = new EventTarget();

  addEventListener<K extends keyof M>(
    type: K & string,
    listener: TEL<M[K]>,
    options?: boolean | AddEventListenerOptions,
  ) {
    // We cast to EventListenerOrEventListenerObject because the browser expects the base Event type
    this.target.addEventListener(type, listener as EventListenerOrEventListenerObject, options);
  }

  removeEventListener<K extends keyof M>(
    type: K & string,
    listener: TEL<M[K]>,
    options?: boolean | EventListenerOptions,
  ) {
    this.target.removeEventListener(type, listener as EventListenerOrEventListenerObject, options);
  }

  // A helper to ensure we always dispatch a properly formatted CustomEvent
  dispatchEvent<K extends keyof M>(type: K, ...args: M[K] extends void ? [detail?: undefined] : [detail: M[K]]) {
    const [detail] = args;

    return this.target.dispatchEvent(new CustomEvent(String(type), { detail }));
  }
}

Of course this is only a base class, we'll need to extend it in order to use it with our own data.

Real-world usage

Let's imagine a situation where we want to track an online shopping cart. We want to be able to make changes to the cart from anywhere in the site, but we don't want the UI or the total price to go out of sync.

import { TypedEventTarget } from './TypedEventTarget';

export interface CartItem {
  id: string;
  name: string;
  price: number;
}

// This map defines exactly what data each event emits
type ShoppingCartEvents = {
  'item-added': CartItem;
  'item-removed': { id: string };
  'cart-cleared': void;
};

export default class ShoppingCart extends TypedEventTarget<ShoppingCartEvents> {
  private _items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
    this.dispatchEvent('item-added', item);
  }

  removeItem(id: CartItem['id']) {
    this._items = this._items.filter((item) => item.id !== id);
    this.dispatchEvent('item-removed', { id });
  }

  clear() {
    this._items = [];
    this.dispatchEvent('cart-cleared');
  }

  get items() {
    return this._items;
  }

  get total() {
    return this.items.reduce((sum, item) => sum + item.price, 0);
  }
}

Now that we have a class to store our data, you can see we've added methods that dispatch events automatically. Because these events are strictly typed, we get full autocomplete and safety when listening to them:

shoppingCartSingleton.addEventListener('item-added', (event)=> {
  const item = event.detail; // types know we've got CartItem;

  console.log(item)
});

Demo

Here is a simple demo using the above class.

Signing-off

I've only really touched the surface of what's possible with this technique. We live in a world where there are many mainstream frameworks and each has a different way of doing things. I think we're on the cusp of seeing the return of the generalised singleton: one native JS/TS class that can be connected to the framework of your choice. But that's an opinion for another day and perhaps another post.

Thanks for reading! If you'd like to connect, here are my BlueSky and LinkedIn profiles. Come say hi 😊

[Boost]

Andrew Bone — Thu, 22 Jan 2026 12:27:19 +0000

Andrew Bone

Jan 17

Express Setup: Simple & Scalable

#webdev #node #express #beginners

Comments 8

9 min read

Express Setup: Simple & Scalable

Andrew Bone — Sat, 17 Jan 2026 20:42:48 +0000

There are a few things conventional wisdom has taught us to do when making an Express microservice, from the layout of our source files to how we document the code we're writing. I'll be honest: I haven't always adhered to these conventions. Sometimes, you just need to get code out the door, and all that boilerplate can really slow you down.

In this post, I'll take a quick look at how we're traditionally told to create an Express microservice, explain what I do differently, and walk you through a very simple project to see it all in action.

An Introduction to Express

Express is one of those tools that feels like magic when you first use it. It's a minimal and flexible Node.js framework that makes building web applications and APIs a breeze. Whether you're spinning up a quick prototype or building a production-ready microservice, Express has you covered.

At its core, Express is all about simplicity. It doesn’t force you into a specific structure or way of doing things, which is both its greatest strength and, sometimes, its biggest challenge. With so much freedom, it’s easy to get overwhelmed by all the "best practices" floating around.

Routes

Routes are the backbone of any Express app. They define how your application responds to different HTTP requests. For example, if someone sends a GET request to /users, you might want to return a list of users. Express makes this super simple:

app.get('/users', (req, res) => {
  res.send('Here’s a list of users!');
});

The conventional wisdom is to separate your routes into their own files to keep things organised.

Controllers

Controllers are where the logic lives. They take the requests from your routes, do the heavy lifting (like talking to a database), and send back a response. A typical setup might look like this:

// usersController.js
export const getUsers = (req, res) => {
  res.send('Here’s a list of users!');
};

Then, in your route file, you’d import the controller:

import usersController from './usersController';
app.get('/users', usersController.getUsers);

Middleware

Middleware is one of the coolest parts of Express. Think of it as a series of steps your request goes through before it gets to your route. Middleware can do things like log requests, check authentication or parse JSON bodies.

Here’s a simple example of middleware that logs every request:

app.use((req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next(); // Pass control to the next middleware or route
});

OpenAPI (Swagger)

Documenting your API is one of those things we all know we should do, but it often gets pushed to the bottom of the to-do list. OpenAPI (often referred to as Swagger) is the de facto method for documenting your APIs.

Whilst this is great in theory, the API documentation is quite complex and time-consuming to write and often goes out of sync with the actual API, making debugging a nightmare.

Here’s how you would serve your swagger file from Express:

import swaggerUi from 'swagger-ui-express';
import swaggerDocument from './swagger.json';

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

There are packages that attempt to avoid the desync issue by discerning meaning directly from the code and its comments, but I find these make the code messy and aren't always correct.

A Brief Look at JSDoc

If you’ve ever worked on a project for more than a week, you’ve probably had that moment where you look at a function and think, “What does this even do?” That’s where JSDoc comes in. It’s a simple way to add comments to your code that describe what your functions, classes and variables are supposed to do.

JSDoc is great because it doesn’t just help you remember what your code does, it also helps others (or future you) understand it. Plus, tools like VSCode can use JSDoc comments to provide inline documentation and autocomplete suggestions, which is a huge productivity boost.

Here’s a quick example of what JSDoc looks like:

/**
 * Gets a list of users.
 * @param {Request} req - The request object.
 * @param {Response} res - The response object.
 * @returns {void}
 */
function getUsers(req, res) {
  res.send('Here’s a list of users!');
}

The @param tags describe the parameters the function takes, and the @returns tag explains what the function returns. It’s simple, but it makes a big difference when you’re working on a team or revisiting old code.

I love JSDoc and use it as much as possible. It also has a handy little feature that will generate HTML pages for you based on your comments.

My structure

OK, let's talk about how I go about setting up a project. You'll have noticed my aversion to excessive boilerplate, but it's not entirely avoidable. We're going to set up a little bit of code to start with; then, hopefully, everything else in the project will get easier.

Setting up a project

First things first, we need to actually initialise our project: create a directory and run the init command.

npm init

We’ll be asked a few questions (name, description, etc). Fill these out and, when you're finished, a package.json file will be created for you. This is step one.

Next, we're going to want to install our dependencies. I'll just run down the list for now but I'll explain what each is for as and when we require them.

npm i express
npm i --save-dev @eslint/js clean-jsdoc-theme eslint eslint-config-prettier eslint-plugin-prettier jsdoc prettier

That might feel like we've just installed a lot, but only one of the dependencies is actually required. The rest are all just to make our lives easier.

Linting and formatting your code

When we write code we're prone to mistakes. Even if you're writing code with the help of an AI, we also all write code a little differently. What's clear to one dev might be really hard to read for another. To help mitigate these issues, we can have eslint to look through our code for obvious mistakes and prettier to format our code, making all of our coding styles read similarly even if not exactly the same.

ESLint

ESLint statically analyses your code to quickly find problems. It can catch common errors, enforce style guidelines, and help prevent bugs before they happen. Depending on the rules you want to enforce, your config can be as complex or as simple as you like. As a starting point, I tend to just include a few recommended rules; @eslint/js has js.configs.recommended.rules, for instance. I also link my Prettier config here so ESLint will help keep everything tidy.

Prettier

Prettier is a code formatter that just handles all the boring stuff for you. Instead of arguing about tabs vs spaces or lining everything up perfectly by hand, you just write your code and Prettier makes it look clean and consistent. It’s opinionated (on purpose), so you don’t waste time picking styles, everything just is styled. Again, the rules used can vary depending on where your code is going or who is working on it, but I have some simplistic rules I like to use everywhere.

BaseRoute Class

Earlier I mentioned Routes and Controllers and how it's generally advised to split them up into separate files or even directories. Yeah, I don't do that. I keep my Routes and Controllers together in a single Route Class, which contains all controllers and also attaches itself to the Express app. Let's look at how that works.

export default class BaseRoute {
  constructor(path, router) {
    if (!path) {
      throw new Error('Path is required');
    }

    if (!router) {
      throw new Error('Router is required');
    }

    this.path = path;
    this.router = router;
    this.init();
  }

  /**
   * Initialises the route.
   */
  init() {
    // This method should be overridden in subclasses
    throw new Error('init() method must be implemented in subclass');
  }

  all(path, ...props) {
    this.router.all(`${this.path}${path}`, ...props);
  }

  get(path, ...props) {
    this.router.get(`${this.path}${path}`, ...props);
  }

  post(path, ...props) {
    this.router.post(`${this.path}${path}`, ...props);
  }

  put(path, ...props) {
    this.router.put(`${this.path}${path}`, ...props);
  }

  delete(path, ...props) {
    this.router.delete(`${this.path}${path}`, ...props);
  }

  patch(path, ...props) {
    this.router.patch(`${this.path}${path}`, ...props);
  }

  options(path, ...props) {
    this.router.options(`${this.path}${path}`, ...props);
  }

  head(path, ...props) {
    this.router.head(`${this.path}${path}`, ...props);
  }
}

First we have a constructor that takes a path and a router. The path is the start of the URL, /some/url for instance, that will be used for all endpoints exposed by this class. The router is the Express router; we'll pass that in from outside so we don't have to declare it multiple times.

You'll notice the constructor also calls the init function, but all that does is throw an error telling us we need to implement it.

Extending the base class

When we actually want to add a new Route, we simply have to extend our base class and away we go.

/**
 * Example route for returning simple responses.
 */
class ExampleRoute extends BaseRoute {
  /**
   * Creates an instance of the ExampleRoute class.
   *
   * @param {object} router - The Express router instance.
   */
  constructor(router) {
    super('/example', router);
  }

  init() {
    this.get('', this.simpleResponse);
    this.get('error', this.errorResponse);
  }

  /**
   * @category API
   * @summary GET ./example
   * @desc Returns a simple JSON response.
   *
   * @returns 200 - Success - Returns an object with 'data' and 'error' properties.
   * @returns 500 - Internal Server Error - An error occurred while processing the request.
   *
   * @example Request:
   * GET http://localhost:5000/example
   *
   * @example Success response:
   * {
   *  "data": "Example",
   *  "error": null
   * }
   */
  simpleResponse(req, res) {
    res.json({ data: 'Example', error: null });
  }

  /**
   * @category API
   * @summary GET ./example/error
   * @desc Returns an error response.
   *
   * @returns 500 - Internal Server Error - An error occurred while processing the request.
   *
   * @example Request:
   * GET http://localhost:5000/example/error
   *
   * @example Error response:
   * {
   *  "data": null,
   *  "error": "This is an example error."
   * }
   */
  errorResponse() {
    throw new Error('This is an example error.', { cause: { status: 500 } });
  }
}

export default ExampleRoute;

You will notice I am passing the methods directly, such as this.get('', this.simpleResponse). In these specific examples, it works fine because the controllers don't rely on any internal class state. However, if you want to access other properties or methods within your class using this, you will need to bind the method in the init() function: this.simpleResponse.bind(this).

The majority of this code is JSDoc, which you might think is overkill, but it's going to write our documentation for us and because it's right there next to our routes, we'll probably remember to update it when we update the route.

In order to add this new collection of endpoints our router we simply instantiate the ExampleRoute class in the same file we define our router and pass that router in and that's it.

const app = express();
const router = express.Router();

new ExampleRoute(router);

Defining our Docs

In our JSDoc comments we describe our endpoints to using a set of tags, you can look at the different tags and what they do over on JSDoc's website but here's what we've used and why.

@category: This is brilliant for grouping related routes. If your microservice has multiple classes (e.g., UserRoute, PaymentRoute), setting the category to "API" ensures they all appear together in the generated sidebar.
@summary: A short, one-line description of what the route does. This often appears in the table of contents or headers.
@desc: A more detailed explanation of the logic or requirements for that specific endpoint.
@returns: In a standard function, this describes a JavaScript return value. In our API context, we use it to document HTTP status codes and the expected JSON structure.
@example: This is perhaps the most useful tag. It allows you to provide a "copy-paste" snippet of a request and its expected response, which is invaluable for front-end developers.

Serving our docs

If we had to read through the source code to understand the endpoints, JSDoc would still be useful for code readability, but we would be missing its best feature. We can build a professional webpage from our comments using the jsdoc package and the theme we installed earlier.

Make a config file called jsdoc.config.json

{
  "source": {
    "include": ["."],
    "exclude": ["node_modules", "docs"]
  },
  "opts": {
    "readme": "./README.md",
    "template": "node_modules/clean-jsdoc-theme",
    "destination": "./docs",
    "recurse": true
  }
}

and then modify your package.json file so it has a script called jsdoc (you can name it anything but I've named mine jsdoc). This script will call jsdoc -c jsdoc.config.json and that's it. Simply run the npm command and it will generate a webpage for you that can be hosted with your docs in human readable form.

npm run jsdoc

Simple Example Project

In order to show this layout in a slightly more real world scenario (though still incredibly simplified) I've made a quick project you can look at and the documentation to go alongside it.

Fin

There we have it, the way I tend to write express services. I don't think this way is any 'better' than any other way but it makes sense in my brain. Feel free to share any ways you prefer to write these services in the comments or even tell my ways in which you think this way is worse.

Thanks for reading! If you'd like to connect, here are my BlueSky and LinkedIn profiles. Come say hi 😊

You're Sleeping on DUMB DEV – Why I Knew It Was the Next Big Thing Instantly.

Andrew Bone — Tue, 01 Apr 2025 14:53:46 +0000

It's not just code, it's a paradigm shift in content velocity. True disruptors see the signal in the noise.

Alright team, let's talk. I’ve been navigating the bleeding edge of the tech landscape for years, riding waves others didn't even see forming. And let me tell you, when I saw the announcement for DUMB DEV, something just clicked. While the rest of the echo chamber was probably debating framework nuances, I saw the raw, disruptive power.

This isn't your grandpa's curated content platform. DUMB DEV isn't afraid to challenge the status quo. It leans hard into AI, not as a tool, but as the source. We're talking maximum velocity, minimum friction. Forget signal-to-noise ratio; DUMB DEV is the noise, optimized and scaled.

Infinite Regress™? AI-Enhanced Confusion? These aren't bugs; they're features targeting a completely untapped market quadrant: rapid, low-fidelity information deployment. It’s bold. It’s fearless. It understands that in today's attention economy, fast beats good nine times out of ten. They’re not building a product; they’re building an engine. An engine fueled by pure, unadulterated AI output. This. Is. Scalability.

Look, I get it. Most people won't see it yet. They didn't see it when I was evangelizing Google Wave as the future of collaborative communication (the federation protocols were sick). They scoffed when I explained the genius of Photovine's thematic video chains. I was one of the first beta testers building location-aware filters for Color – the potential was massive. I even defended the Juicero platform (it was never about the juice, guys, it was about the connected kitchen!). I saw the vision behind Clinkle's audio payments before the FUD set in. I still have my Zune somewhere, loaded with podcasts about agile methodologies you've probably never heard of.

Being an early adopter isn't about batting 1.000. It's about recognizing potential disruption before the mainstream catches on. It's about seeing the vectors converging while everyone else is still looking at the dots.

DUMB DEV has those vectors. It’s tapped into the AI zeitgeist with zero apologies and maximum acceleration. Mark my words: the principles behind this, the sheer audacity of it, will ripple through the dev content space.

So yeah, you can keep chasing vanity metrics like "accuracy" and "usefulness." I'll be over here, exploring the DUMB DEV ecosystem, comfortable knowing I got in on the ground floor. Again.

You'll understand eventually. Probably when it's too late.

Stay nimble.

Learning GO: The container types

Andrew Bone — Thu, 27 Mar 2025 16:30:00 +0000

Welcome back to another exploration of Go! This week, we're looking at Go’s three container types: arrays, slices, and maps.

So far, things have been quite easy to follow, but these examples are getting longer and denser. Let’s dive in and make sense of it all.

Arrays

In Go, an array is a sequence of elements with a fixed length. Each element must be of the same type.

var a [5]int

Here, we declare an array with a length of 5, meaning it will always have exactly five elements.

a[4] = 100

We can modify a specific index of an array using square brackets. Here, we’re setting the value at the fourth position (index 4).

fmt.Println("len:", len(a))

To get the length of an array, we use the built-in len function.

b := [5]int{1, 2, 3, 4, 5}

We can initialise an array while declaring it using curly braces.

b := [...]int{1, 2, 3, 4, 5}

By using [...], we allow Go to infer the length based on the initial values.

b := [...]int{100, 3: 400, 500}

Interestingly, we can also specify an index while declaring values. Here, b[3] is 400, and b[4] is 500, leaving b[1] and b[2] as zero values.

Multi-Dimensional Arrays

var twoD [2][3]int  
for i := 0; i < 2; i++ {  
    for j := 0; j < 3; j++ {  
        twoD[i][j] = i + j  
    }  
}

Go supports multi-dimensional arrays. Here, we create a 2×3 array and populate it using nested loops.

twoD := [2][3]int{  
    {1, 2, 3},  
    {4, 5, 6},  
}

Alternatively, we can declare and initialise a multi-dimensional array directly.

Slices

Slices and arrays have a lot in common, but one key difference is that a slice doesn't require its length to be known at build time, it can grow dynamically.

var s []string

This looks familiar from the array example, except we’re not declaring the length. The s slice starts with a length of 0 and is equal to nil.

s = make([]string, 3)  

s[0] = "a"  
s[1] = "b"  
s[2] = "c"

Here, we use the make function to create a slice with an initial length of 3. Each index starts with a zero-valued string, and we can then assign values like a regular array.

NOTE: We can give a slice a capacity, which is its maximum length. By default, this is the same as the length passed into make, but if we pass in a second number, we can change it.

s = append(s, "d")  
s = append(s, "e", "f")

The append function allows us to expand a slice by adding new elements at the end.

c := make([]string, len(s))  
copy(c, s)

Here, we create a new slice of the same length as s using make and copy the contents over using copy.

l := s[2:5]  
l = s[:5]  
l = s[2:]

Slices support the slice operator [:], which allows extracting a portion of the slice between two indexes.

s[2:5] gives elements from index 2 to 4 (index 5 is excluded).
s[:5] is equivalent to s[0:5].
s[2:] is equivalent to s[2:len(s)].

t := []string{"g", "h", "i"}  
t2 := []string{"g", "h", "i"}  

if slices.Equal(t, t2) {  
    fmt.Println("t == t2")  
}

We imported the slices package at the beginning, which allows us to compare slices using slices.Equal.

twoD := make([][]int, 3)  
for i := 0; i < 3; i++ {  
    innerLen := i + 1  
    twoD[i] = make([]int, innerLen)  
    for j := 0; j < innerLen; j++ {  
        twoD[i][j] = i + j  
    }  
}  
fmt.Println("2d: ", twoD)

This took a minute to get my head around, so I'll break it down:

We create a slice with 3 inner slices ([[], [], []]).
Each inner slice is initialised with a length of i + 1 ([[int], [int, int], [int, int, int]]).
Finally, we populate each inner slice by adding i + j at each position ([[0], [1, 2], [2, 3, 4]]).

Maps

Let's move on to maps. You might know them as hashes, dicts, or objects in other languages, but here they're called maps. They allow you to have a key/value pair.

m := make(map[string]int)

Declaring a map is similar, but this time we place the key type in square brackets [string] and the value type outside int.

m["k1"] = 7  
m["k2"] = 13

We set values the same way as an array or slice, but this time the keys are strings rather than indexes.

v1 := m["k1"]  
v3 := m["k3"]

We can retrieve values the same way we set them. If we attempt to read a key that hasn't been set, we get a zero-valued response instead of an error.

fmt.Println("len:", len(m))

The len function still works here and will return how many keys we have set.

delete(m, "k2")  
clear(m)

We have a nice delete function that removes a single key and its value, and a clear function that removes all key-value pairs.

_, prs := m["k2"]

When reading a value from a map, we receive two values. The first is the stored value (or a zero-valued response if the key is missing). The second is a boolean indicating whether the key was present in the map.

n := map[string]int{"foo": 1, "bar": 2}  
n2 := map[string]int{"foo": 1, "bar": 2}  

if maps.Equal(n, n2) {  
    fmt.Println("n == n2")  
}

Again, in this example, we've imported another package, maps, which lets us check if two maps are equivalent.

Wrapping Up

OK, it feels like we're starting to get somewhere now. We're actually learning things that could be useful in real-world applications. Next time, we'll look at functions and what we can do with them.

Thanks for reading! If you have any questions, leave a comment. I'm also considering writing a simple script, let me know if you have any ideas!

If you’d like to connect, here are my Twitter, BlueSky, and LinkedIn profiles. Come say hi 😊.

Learning GO: Loops and Conditionals

Andrew Bone — Thu, 20 Mar 2025 16:30:00 +0000

Let's continue our journey into Go. Last time, we got Go set up in WSL and covered some fundamentals like values, variables, and constants. This time, we'll dive into for loops and conditional blocks, the building blocks of decision-making and iteration in Go. We're working our way through Go by Example if you want to follow along.

At the end of this post, we'll also take a quick detour into running Go programs in Docker using a simple Dockerfile, making them easy to package and run anywhere.

For loops

Our first port of call is the humble for loop. The example we're given has a few different loop types, so let's break them down.

i := 1
for i <= 3 {
    fmt.Println(i)
    i = i + 1
}

Our first loop declares and assigns a variable called i outside the loop using the := syntax we covered last time. It starts at 1, prints the current value of i in each iteration, and increments i by 1. The loop stops when i reaches 4.

While declaring i outside the loop works, it's more common and often clearer to declare it within the loop's initialisation.

for j := 0; j < 3; j++ {
    fmt.Println(j)
}

This second loop is much closer to what I'd expect. The variable j is declared inside the loop, starts at 0, increments after each iteration, and stops when j reaches 3. Each iteration prints the value of j.

for i := range 3 {
    fmt.Println("range", i)
}

This loop iterates 3 times, with i taking the values 0, 1, and 2. It's, in essence, the same as the previous loop just in a neater and more standard way. This is a range loop and we will see this syntax used with arrays and slices later on.

for {
    fmt.Println("loop")
    break
}

Now things are getting interesting. This loop has no stopping condition, so it would run forever, except we use break immediately after Println, stopping it in its tracks. This is useful when you need to conditionally exit a loop at any point.

for n := range 6 {
    if n%2 == 0 {
        continue
    }
    fmt.Println(n)
}

Sneaky example. We're seeing multiple new things here; the modulo operator (%), our first if block, and the continue keyword.

This loop counts from 0 to 5. It checks if n is even using n % 2 == 0. If so, continue skips the rest of the iteration and moves to the next number. Otherwise, it prints n.

In short, it prints only the odd numbers in the range.

Conditionals

Conditionals are a staple of any programming language they allow us to have branching logic based on an input variable. There are two main flavours of conditional blocks: if/else statements and switch statements so let's explore them.

If/else Statements

If statements boil down to expressions that evaluate to either true or false; if the expression is true do something otherwise do something else.

Again in this example we're given several statements so let's look at them one by one.

if 7%2 == 0 {
    fmt.Println("7 is even")
} else {
    fmt.Println("7 is odd")
}

Our friend, the modulo operator, is back. In this example, we're checking if the number 7 is even (it's not) and printing out whether it is or not (again, it's not).

if 8%4 == 0 {
    fmt.Println("8 is divisible by 4")
}

This is basically the same example but shows us that the else section is not required.

if 8%2 == 0 || 7%2 == 0 {
    fmt.Println("either 8 or 7 are even")
}

Here we have an or condition, this will look familiar to you if you've used other languages, allowing the if statement to execute if either condition is true

if num := 9; num < 0 {
    fmt.Println(num, "is negative")
} else if num < 10 {
    fmt.Println(num, "has 1 digit")
} else {
    fmt.Println(num, "has multiple digits")
}

Finally we have an else if example. This allows us to check multiple conditions on an input and execute the first that is true, the else at the end acts as a catch-all for anything that makes it past all other checks. It is worth noting that the scope of the variable num is limited to the if/else block.

I will say I do not like how a variable can be declared in an if statement like this. To me this seems less readable but I guess we can easily rewrite their example like this to avoid that.

num := 9

if num < 0 {
    fmt.Println(num, "is negative")
} else if num < 10 {
    fmt.Println(num, "has 1 digit")
} else {
    fmt.Println(num, "has multiple digits")
}

Go doesn’t have a ternary operator, which is a shame if you're used to it in other languages, but let’s see if we actually miss it.

Switch Statements

A switch statement whilst similar to an if/else block is a little different. It also relies on evaluating an expression but those expressions don't have to be just be true or false they can be anything and we can have a case for each outcome and a default case to catch anything else.

Let's break this example down and see if they've snuck any new things in there.

i := 2
fmt.Print("Write ", i, " as ")
switch i {
case 1:
    fmt.Println("one")
case 2:
    fmt.Println("two")
case 3:
    fmt.Println("three")
}

First example and they've already snuck in some new stuff. Print on fmt prints without ending with a line break and we can comma separate values to append them all together.

Other than that this example is quite straightforward, declare i check if i is 1, 2 or 3 and if it is print out the written word.

switch time.Now().Weekday() {
case time.Saturday, time.Sunday:
    fmt.Println("It's the weekend")
default:
    fmt.Println("It's a weekday")
}

Here, we see our first look at the time package. We appear to be using enums but as we've not learnt about them yet we'll just have to wait. All we need to know is our expression gets the current day of the week and we're using case, with comma separation acting like the or operator, we check to see if it's in the weekend or a weekday.

t := time.Now()
switch {
case t.Hour() < 12:
    fmt.Println("It's before noon")
default:
    fmt.Println("It's after noon")
}

This example is similar to the previous one only our time.Now() call is stored as a variable and we're not passing in an expression to our switch. This shifts the condition checking into the case blocks, making it behave like an if/else statement where the first true case executes.

whatAmI := func(i interface{}) {
    switch t := i.(type) {
    case bool:
        fmt.Println("I'm a bool")
    case int:
        fmt.Println("I'm an int")
    default:
        fmt.Printf("Don't know type %T\n", t)
    }
}

whatAmI(true)
whatAmI(1)
whatAmI("hey")

Okay, I thought they might try to sneak in some extra stuff and here it is, we've got our first reusable function, an interface (whatever that is) and a Printf function.

Let's go slowly through this and work out what's going on. First we have a variable declaration called whatAmI that is a func that take i which is an interface{}.

I wasn't sure on what interface{} meant, so I did a quick search. It seems interface is something we will learn about a little later but interface{} is how you tell Go that we don't know what type will be passed into the function. Think of interface{} as a placeholder that can hold any type of value. We're saying i can be anything.

Next up, we have our switch expression, where we're declaring a new variable called t and storing the type of i in it. This allows us to have our cases be the types we're looking for.

We have 2 cases and a default fallback. The first two cases check if the if i was a bool (true or false) or if it was an int (whole number) and if it's neither the fallback prints out what the type was using Printf. Printf allows formatted output where %T prints a variable's type. We use Printf here because %T isn't directly convertible to a string. We also have to end with an \n to put our line break back in.

Docker

A great way to run Go applications is to package them into Docker images, making them portable across different systems, including Windows, Linux, and macOS. We'll use a multi-stage Dockerfile to build and execute our Go program efficiently.

Why Use a Multi-Stage Dockerfile?

Multi-stage builds help keep the final image small and efficient by separating the build environment from the runtime environment. This reduces unnecessary dependencies in the final image, improving security and performance.

Let's start by writing a Dockerfile.

# Build the GO binary
FROM golang:1.24.1-alpine AS build
COPY ./main.go ./main.go
RUN go build -o /bin/output ./main.go

# Execute the GO binary
FROM scratch
COPY --from=build /bin/output /bin/output
CMD ["/bin/output"]

Build Stage (build)

We start with the official golang:1.24.1-alpine image image. We copy main.go into the container (you can rename this) and compile it to /bin/output.

Runtime Stage

The runtime stage uses FROM scratch, meaning it has no base OS. scratch is an empty image, and nothing else is present. This minimizes the final image size. We use the command COPY --from=build which efficiently copies only the compiled binary from the build stage and set CMD ["/bin/output"] as the entry command.

Building and Running the Docker Image

To build and run the image, use the following commands:

# Build the image (dot specifies the current directory as context)
docker build -t my-go-app:latest .

# Run the container
docker run my-go-app:latest

Signing off

We've covered a lot this time and our programs are becoming more and more sophisticated. We are progressing nicely, and the syntax is proving to be very easy to work with. Next time we'll be looking at arrays, slices and maps. We're really getting somewhere but at the same time we've only just scratched the surface.

Thanks for reading! If you'd like to connect, here are my Twitter, BlueSky, and LinkedIn profiles. Come say hi 😊

Learning GO: A new beginning

Andrew Bone — Fri, 14 Mar 2025 18:50:15 +0000

Learning things is fun so I've decided it's time to learn go and because I enjoy making these little series I thought I'd write about it too.

My first step was to Google 'learning Go', which took me to their getting started page. I'll be using WSL to execute my code, so let's find the install instructions.

I've not installed Go on my system before, so I don't need to remove an existing installation. I can just download the latest Go files and extract them into /usr/local.

wget https://go.dev/dl/go1.24.1.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.1.linux-amd64.tar.gz

Now we need to add the Go binaries to our $PATH variable so we can execute it from anywhere. We should test that Go can be called by running go version at this point.

echo "export PATH=/usr/local/go/bin:\$PATH" >> ~/.bashrc
source ~/.bashrc
go version

Don't forget to tidy up as you go.

rm go1.24.1.linux-amd64.tar.gz

Compared to setting up some other languages, this was refreshingly simple. No weird dependencies or long-winded setups, just download, extract, and go!

Go by Example

Go by Example is a hands-on introduction to Go using annotated example programs. It’s a great starting point to use when tackling any Go project.

There are a few tutorial types available. I've decided to go with "Go by Example" and if I ever get lost I'll head on over to documentation to get unstuck.

Hello, World!

No learning journey is complete without printing 'Hello, World!', it's the rite of passage for every programmer. Let's see what it looks like in Go.

This first section is mostly about executing code, either by running it directly or building it as a binary. But we also get to see our first import and function.

package main

import "fmt"

func main() {
    fmt.Println("hello world")
}

We're importing fmt, which the docs tell me is a string formatting package, and creating a main function as the program's entry point.

To run the program, we simply write go run followed by the location of our program file.

go run ./hello-world.go

To build the program, we do the same but swap run for build. Instead of executing the script directly, this creates a new file we can run without go run.

go build ./hello-world.go
./hello-world

Values

Next up, we're looking at different value types. We have strings, which can be appended using +; integers and floats, which support standard math operators; and booleans, which work exactly as expected

package main

import "fmt"

func main() {
    fmt.Println("go" + "lang")

    fmt.Println("1+1 =", 1+1)
    fmt.Println("7.0/3.0 =", 7.0/3.0)

    fmt.Println(true && false)
    fmt.Println(true || false)
    fmt.Println(!true)
}

Variables and Constants

I've decided to cover variables and constants together since, in my mind, they're pretty similar but we'll see if that holds true.

Variables

To declare a variable we can use the var keyword, interestingly we can declare several variables in one go, though I can imagine this getting hard to read.

Types are inferred, but we can also specify a type and leave the value blank, which initialises the variable as zero-valued. I really like this, it's very developer-friendly. We can have an 'empty' variable that won't throw errors when used.

There's also a shorthand syntax for variable declaration: :=. Instead of writing var age int = 34, we can simply write age := 34.

package main

import "fmt"

func main() {
    var a = "initial"
    fmt.Println(a)

    var b, c int = 1, 2
    fmt.Println(b, c)

    var d = true
    fmt.Println(d)

    var e int
    fmt.Println(e)

    f := "apple"
    fmt.Println(f)
}

Constants

Finally, let's look at constants. A constant can be used anywhere a variable can, but unlike variables, constants cannot be reassigned. It's generally best practice to use constants where possible, as they offer a whole bunch of compile-time optimisations.

As an aside, we're also importing our second package, the math, which provides a range of mathematical functions

package main

import (
    "fmt"
    "math"
)

const s string = "constant"

func main() {
    fmt.Println(s)

    const n = 500000000

    const d = 3e20 / n
    fmt.Println(d)

    fmt.Println(int64(d))

    fmt.Println(math.Sin(n))
}

Signing off

Thank you for coming on this little adventure with me. I'd like to carry on with this series for a little while so if you'd like to follow along, you can press the 'follow' button to be notified of new posts.

Feel free to leave any feedback. If you're also learning in public, drop a link to your series in the comments, I'd love to check it out

Thanks for reading! If you'd like to connect, here are my Twitter, BlueSky, and LinkedIn profiles. Come say hi 😊

Future of CSS: Select styling without the hacks

Andrew Bone — Mon, 10 Mar 2025 20:36:37 +0000

For years the <select> element has been notoriously difficult to style. Developers had to either accept the browser’s default look or resort to JavaScript-heavy solutions. But why has it been this way for so long?

Why Can’t `<select>` Be Styled?

The <select> component is a form control, meaning browsers handle much of its behaviour natively. This includes dropdown logic (have you noticed the options list can overflow the window?), keyboard navigation, and accessibility features. However, because these controls are deeply integrated into the OS, styling has been largely restricted.

Workarounds: From jQuery UI to shadcn/ui

Since native styling wasn’t an option, developers turned to libraries:

jQuery UI (early 2010s): Wrapped <select> in a div, replaced it with a <ul>.
Custom Dropdowns (2015–2022): React/Vue solutions often replaced <select> entirely.
shadcn/ui (modern approach): Uses Radix UI under the hood to create accessible dropdowns.

While these solutions worked, they came with trade-offs: extra JavaScript, potential accessibility issues, and performance overhead.

Enter `base-select`: A New Approach with a Caveat

With the introduction of the base-select property, browsers will allow full CSS styling of <select> without overriding most native functionality. This means:

No need for JavaScript to handle dropdowns.
Full control over appearance while keeping built-in accessibility.
Potentially faster rendering and better performance.

Important Note: The base-select property is currently experimental and only available in Chrome 134+. Browser support is limited, so use this with caution in production environments.

Styling `<select>` with `base-select`

When styling the select element you must add appearance: base-select; to both the select and select::picker(select).

select {
 appearance: base-select;

 &::picker(select) {
  appearance: base-select;
 }
}

This tells the browser to allow the <select> element to be styled by CSS rather than using the system's default appearance.

Understanding ::picker(select): This pseudo-element represents the dropdown listbox (the "picker") of the <select> element. It allows you to style the listbox independently.

There are a few different pseudo-classes and pseudo-elements that are exposed to modify the select element. I've documented a few useful ones down below.

select {
 appearance: base-select;
 /* style the 'button' */

 &::picker(select) {
  appearance: base-select;
  /* style the 'listbox' */
 }

 &::picker-icon {
  /* style the 'button' icon */
 }

 &:not(:open) {
  /* style the 'button' when closed */

  &::picker(select) {
   /* style the 'listbox' when closed */
  }
 }

 &:open {
  /* style the 'button' when open */

  &::picker(select) {
   /* style the 'listbox' when open */
  }
 }

 & option {
  /* style the options */

  &::checkmark {
   /* style the checkmark on the checked option */
  } 

  &:checked {
   /* style the checked option */
  }
 }
}

Demo: CSS-Only shadcn/ui Select

Let’s recreate shadcn/ui’s select component using only CSS. Here’s how we can do it:

Styling the <select> itself to match shadcn/ui’s look.
Customising the dropdown’s appearance.
Ensuring accessibility is maintained.

Remember: This demo only works in Chrome 134+. If you can’t test it, I’ve included a GIF below so you can still see it in action.

Markup

The HTML structure remains simple. The <selectedcontent> element allows us to display and style the selected option separately, and we add a chevron icon to mimic shadcn/ui.

<select>
  <button>
    <selectedcontent></selectedcontent>
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
      <path d="m6 9 6 6 6-6"></path>
    </svg>
  </button>
  <optgroup>
    <label>Fruits</label>
    <option value="" hidden disabled selected>Select a Fruit</option>
    <option>Apple</option>
    <option>Banana</option>
    <option>Blueberry</option>
    <option>Grapes</option>
    <option>Pineapple</option>
  </optgroup>
</select>

Styling the Select Button

To start, we need to apply appearance: base-select and set some basic styles.

select {
 appearance: base-select;
 color: #71717a;
 background-color: transparent;
 width: 180px;
 box-sizing: border-box;
 padding: 0.5rem 0.75rem;
 border: 1px solid #e4e4e7;
 border-radius: calc(0.5rem - 2px);
 box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
 cursor: pointer;
}

Positioning the content and icon:

select > button {
 display: flex;
 width: 100%;
 font-family: inherit;
 color: currentColor;
}

select > button > svg {
 margin: 0 0 0 auto;
 width: 1.2rem;
 height: 1.2rem;
}

Styling the Dropdown Listbox

The listbox must be styled separately, ensuring it appears smoothly when opened. We're using the relatively new starting-style to allow us to animate from display: none.

select::picker(select) {
 appearance: base-select;
 border: 1px solid #e4e4e7;
 padding: 0.25rem;
 margin-top: 0.25rem;
 border-radius: calc(0.5rem - 2px);
 box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1),
  0 2px 4px -2px rgba(0, 0, 0, 0.1);
 cursor: default;
 transition: opacity 225ms ease-in-out, transform 225ms ease-in-out;
 transform-origin: top;
 transform: translateY(0);
 opacity: 1;

 @starting-style {
  transform: translateY(-0.25rem) scale(0.95);
  opacity: 0;
 }
}

Enhancing Accessibility & Interactions

Improve focus visibility and ensure placeholder text stands out:

select:focus-visible {
 outline: 2px solid #a1a1aa;
 outline-offset: -1px;
}

select:has(option:not([hidden]):checked) {
 color: #18181b;
}

Custom Checkmark

We can replace the default checkmark with a custom SVG.

select option::after {
 content: "";
width: 1rem;
 height: 1.5rem;
 margin-left: auto;
 opacity: 0;
 background: center / contain no-repeat
  url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke='%2318181b' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M20 6 9 17l-5-5'%3E%3C/path%3E%3C/svg%3E");
}

select option:checked::after {
 opacity: 1;
}

Conclusion

The <select> component is finally getting the flexibility it deserves. With base-select, we can create beautiful dropdowns without JavaScript. If you're interested in reading more check out the open ui explainer.

What do you think of base-select? Are you excited to ditch JavaScript-heavy dropdowns?

Thanks for reading! If you'd like to connect, here are my Twitter, BlueSky, and LinkedIn profiles. Come say hi 😊

I've revisited and updated this post a few times over the last couple of days to get it somewhere I'm proud of it. I think it's finally there.

Andrew Bone — Thu, 20 Feb 2025 21:15:57 +0000

Dialogs, Popovers & the Top Layer Mess

Andrew Bone ・ Feb 18 '25

#webdev #javascript #frontend

Dialogs, Popovers & the Top Layer Mess

Andrew Bone — Tue, 18 Feb 2025 21:12:06 +0000

Dialogs (or modals) and popovers are essential UI components that interrupt the user's workflow to display critical information or offer interactive elements.

A dialog is a UI element that demands user interaction before proceeding. It is commonly used for confirmations, forms, and critical alerts.

A popover is a lightweight floating UI element that provides contextual actions or extra information, such as dropdowns, tooltips, notifications, and toasts.

Both components help manage interactions without navigating away from the page.

The Problem

The main challenge when using modals and popovers together is managing their stacking order. When a modal is opened while a popover is visible, the popover often gets hidden behind the modal and becomes inert. Even if reopened, the popover stays non-interactive despite appearing above the modal, making it a frustrating issue for users and developers.

GitHub Issues Timeline

Issue #9075 (March 2023): OddBird proposes a way to retrieve the current top layer order.
Issue #9733 (September 2023): keithamus suggests an event to notify when modals or popovers appear.

Real-World Examples

Imagine you have a piece of software that you maintain. You're planning on doing some server maintenance and so place a banner at the top of the screen letting people know about it. A lot of the interactions on your site take place in modals. Suddenly, your banner is hidden!

That's ok though because you're a savvy developer that knows all about the new popover API. Using this, you move the banner to the top layer and place it above the modal, only, it's no longer interactive.

The only way to keep it interactive is to place the banner inside the topmost modal. While this works, it’s cumbersome and impractical, especially without a built-in way to track the top layer.

Here’s an example where you can open multiple dialogs and popovers. Click "Start" to open a modal dialog, then open a popover. You’ll notice the popover becomes inert even though it was opened after the dialog. You can continue to open more dialogs and see the popover fade further and further into the background.

What Can We Do About It?

There are a few ways we can tackle this, but I'll focus on two: updating the spec and tracking the top layer ourselves.

Updating the Spec

As the web is open, we can contribute to improving standards. Proposals for changes to the specification can be submitted to the WHATWG HTML repository. Ensure your suggestion is thoroughly considered to facilitate the process.

A solution I'd like to see is a set of methods and properties added to the document allowing us to interact with the top layer, an event fired when the top layer order changes, and finally, I'd love modals to only inert items lower than themselves in the top layer.

Methods and Properties

document.topLayer.elements: Returns an array of DOM elements where the index relates to position in the top layer.
document.topLayer.bringToFront(el: HTMLElement): Takes an element in the top layer and moves it to the last/highest position.

Events

toplayerchange: An event fired on document.topLayer when the top layer has an element added, removed, or reordered. The event contains an enum specifying the change type.

Inert

I cannot envisage a scenario where you have a popover visually above a modal (due to top layer positioning) that you want to be inert. This feels like a spec oversight that can be addressed.

Handling It Ourselves

One of the issues mentioned earlier was recently resolved, introducing a new event that lets us track top-layer changes. Using this, we can create a polyfill to manage element layering (though fixing the inert issue still requires additional work).

The event we've gained is the toggle event. This fires when a popover, dialog, or details element is toggled. We care about popover and specifically modal dialogs, meaning this event is a little overkill but it'll get the job done.

document.addEventListener(
  "toggle",
  ({ target }) => {
    if (!(target instanceof HTMLDialogElement || target.hasAttribute("popover"))) return;

    if (target.matches(":modal, :popover-open") && document.contains(target)) {
      console.log('toplayerchanged: add')
    } else {
      console.log('toplayerchanged: remove')
    }
  },
  { capture: true }
);

Using this, we can detect when elements are added or removed from the top layer. However, we still need to store them somewhere and ensure elements are removed if they are deleted from the DOM without firing a toggle event.

const topLayerElements = new Set();

document.addEventListener(
  "toggle",
  ({ target }) => {
    if (!(target instanceof HTMLDialogElement || target.hasAttribute("popover"))) return;

    if (target.matches(":modal, :popover-open") && document.contains(target)) {
      topLayerElements.add(target);
      document.dispatchEvent(
        new CustomEvent("toplayerchanged", { detail: "add" })
      );
    } else {
      if (topLayerElements.delete(target)) {
        document.dispatchEvent(
          new CustomEvent("toplayerchanged", { detail: "remove" })
        );
      }
    }
  },
  { capture: true }
);

const observer = new MutationObserver((mutations) => {
  const nodes = mutations.flatMap(({ removedNodes }) => [...removedNodes]);

  for (const node of nodes)
    if (topLayerElements.delete(node)) {
      document.dispatchEvent(
        new CustomEvent("toplayerchanged", { detail: "remove" })
      );
    }
});

observer.observe(document.body, { childList: true, subtree: true });

document.getTopLayerElements = () => [...topLayerElements];

With this, we can run document.getTopLayerElements() to get a list of items in the top layer and listen for a toplayerchanged event on the document to know when the list changes.

Example React Hook

I've created a React Hook that uses the above method to track the top layer. With this information, you can portal and re-promote popovers to help prevent them from getting stuck behind modals.

Check it out here: React Hook for Top Layer Stack Management

Conclusion

These stacking issues make dialogs harder to use effectively, limiting their full potential. By addressing problems like this, we can improve the web and create a more user-friendly experience for everyone. If anyone has any thoughts, ideas, or just wants to talk about the problem more, feel free to leave a comment.

Thanks for reading! If you'd like to connect, here are my Twitter, BlueSky, and LinkedIn profiles. Come say hi 😊

Forem: Andrew Bone

The Diplomatic Core: Shared Logic in a Multi-Framework World

Framework Independence

Implementing Framework Adapters

React: Singletons aren't as evil as you think

Adding the Singleton

Live Demonstration

Link2Twenty / multi-framework-singleton-demo

Render several MFEs to demonstrate shared singletons

Cross-Framework Singleton Micro Frontends

Overview

Inspiration and Context

Wrapping up

React: Singletons aren't as evil as you think

The Singleton Scepticism

The Simplicity of Classes

Typed Target Event

Type-Safe CustomEvents: Better Messaging with Native APIs

A Problem to Solve

The Singleton

The Connection

The Demo

Closing words

Type-Safe CustomEvents: Better Messaging with Native APIs

The Problem

The Solution: TypedEventTarget

Real-world usage

Demo

Signing-off

[Boost]

Express Setup: Simple & Scalable

Express Setup: Simple & Scalable

An Introduction to Express

Routes

Controllers

Middleware

OpenAPI (Swagger)

A Brief Look at JSDoc

My structure

Setting up a project

Linting and formatting your code

ESLint

Prettier

BaseRoute Class

Extending the base class

Defining our Docs

Serving our docs

Simple Example Project

Fin

You're Sleeping on DUMB DEV – Why I Knew It Was the Next Big Thing Instantly.

Learning GO: The container types

Arrays

Multi-Dimensional Arrays

Slices

Maps

Wrapping Up

Learning GO: Loops and Conditionals

For loops

Conditionals

If/else Statements

Switch Statements

Docker

Why Use a Multi-Stage Dockerfile?

Build Stage (build)

Runtime Stage

Building and Running the Docker Image

Signing off

Learning GO: A new beginning

Go by Example

Hello, World!

Values

Variables and Constants

Variables

Constants

Signing off

Future of CSS: Select styling without the hacks

Why Can’t <select> Be Styled?

Workarounds: From jQuery UI to shadcn/ui

Enter base-select: A New Approach with a Caveat

Styling <select> with base-select

Why Can’t `<select>` Be Styled?

Enter `base-select`: A New Approach with a Caveat

Styling `<select>` with `base-select`