I was showing some traces to a colleague, and we were looking intently at the considerable gap between the CSS being downloaded, and the website becoming visible.

My hunch was the bundle of <script>s than Next generates were being parsed at the point of CSS rendering, causing the main thread to choke. Incredibly, you still can’t swap async to defer when using the the App Router (despite it being possible with their previous router), which would almost certainly close this gap. But I digress.

He found an option in the “Performance” tab in dev tools called “Enable CSS selector stats (slow)”, which analyses every CSS selector and pops them in a table.

In addition, the trace showed an alarming blob of purple where the main thread locked up under the label of “Recalculate style”. 270ms of delay just to calculate styles.

Goodness, I thought, that’s some tasty low hanging fruit.

Now, I know in my heart that CSS selector performance isn’t something to worry about. I’ve heard it again and again that browsers are incredibly efficient at handling CSS selectors these days, and yet the graph didn’t (appear to) lie; 270ms to recalculate styles on every DOM change and page load. Against my better judgement, on a day where I didn’t have a tonne of other work to do, I felt I had to go deeper.

I was particularly drawn to the column “Match attempts” compared to “Match count”. Some selectors were attempting to match against hundreds of DOM nodes, but still end up not matching many/any elements. This fruit was looking tastier by the second.

The common culprits were any selector ending in *, :last-child, :first-child, :nth-child, which included the infamous owl selector, being used for flow spacing amongst other things.

The penny suddenly dropped onto a piece of knowledge I’d squirrelled away years ago. Selectors are read from right to left in CSS. This form of bottom-up parsing is more efficient for the browser when matching to DOM nodes. However, you can begin to see why a selector like .parent > * + * is flagged as one of the more inefficient ones. Read backwards, the browser sees the selector as follows:

1. * - this matches all elements
2. * + * - this narrows it to all elements that follow another (so almost all elements)
3. .parent > * + * - finally, this narrows it down to any direct children of .parent that follow another child

So this selector attempts to match on every DOM node, but might only actually match five elements on the page.

Now, at this point, I should’ve seen the column marked ‘Elapsed (ms)’ with values such as 0.013 and thought, hmm, that doesn’t seem very long, nor could all the selectors really add up to 270ms. But by now, the low hanging fruit looked far too tasty, and I had a hankering for some refactoring.

I took the table of selectors and calculated which selectors had the greatest difference between match attempts and elements found, and began working through those. A few were fed through our design system, but many came from my codebase.

Through much inversion of control and additional classes/data attributes, I updated almost all instances of :last-child and *. I made a release to our design system fixing the oh-so-inefficient selectors and marvelled at the improvement.

Recalculate style / Before: 270ms / After: 40ms

For a few minutes, I felt like Indiana Jones staring at the holy grail. 230ms of savings from some CSS selector changes. This felt significant. And yet, the niggling phrase of “CSS selector efficiency is not something to worry about in 2024” kept ringing through my head.

I ran the before/after through WebPageTest and to my surprise (and lack of surprise), nothing significant had changed.

It was at this point that the second penny dropped and I realised I’d been duped by a graphing misunderstanding and my own enthusiasm for improving frontend performance. When clicking “Enable CSS selector stats (slow)”, I assumed it took longer to record the rendering process, but would provide the results as if they were not being profiled. I then realised that the graph was showing a big purple blob because I had the checkbox enabled. Suffice to say, I felt like a right doughnut.

I ran it all again without that option enabled and here are the fruits of my labour:

Recalculate style / Before: 11.95ms / After: 10.23ms

Whoop-de-doo

But if, somehow, you’re browsing this site with CSS selector stats enabled, and find it to be a snappy experience, you’re welcome.

use lets you read the value of a promise (or context if you’re that way inclined). It feels like a bit of syntactic sugar, to avoid writing .then() or await within your component, but I’m sure there’s more to it than that.

When is ‘use’ useful?

Take this carousel. Pretty standard stuff at the end of a product page. Definitely shouldn’t be render-blocking, and a prime candidate for deferred loading. We could move the data request into a client-side handler and call useEffect to fetch the data on the client, but finding ways to avoid useEffect becomes a source of personal pride once you’ve worked on a React project for any length of time. This approach has to wait for the whole page to hydrate before it can get to work loading the data.

Instead, we can still begin fetching the data on the server, but combine <Suspense> and use to handle the loading state before resolving it on the client.

What does ‘use’ look like?

Before:

export default async function Page() {
    // Wait for the data to load
    const vehicles = await getVehiclesFromDB();

    return (
        <SimilarVehicles vehicles={vehicles} />
    );
}

export const SimilarVehicles: React.FC<{
    vehicles: VehiclePreview[];
}> = ({ vehicles }) => {
    return (
        <section className={cx(styles.section)}>
            {vehicles.map((vehicle) => (
                <VehicleCard
                    key={vehicle.vehicleId}
                    vehicle={vehicle}
                />
            ))}
        </section>
    );
};

After:

export default async function Page() {
    // Crack on rendering the page
    const vehiclesPromise = getVehiclesFromDB();

    return (
        <Suspense fallback={<LoadingState />}>
            <SimilarVehicles vehiclesPromise={vehiclesPromise} />
        </Suspense>
    );
}

export const SimilarVehicles: React.FC<{
    vehiclesPromise: Promise<VehiclePreview[]>;
}> = ({ vehiclesPromise }) => {
    // Resolve the promise
    const vehicles = use(vehiclesPromise);

    return (
        <section className={cx(styles.section)}>
            {vehicles.map((vehicle) => (
                <VehicleCard
                    key={vehicle.vehicleId}
                    vehicle={vehicle}
                />
            ))}
        </section>
    );
};

How does ‘use’ work?

By continuing to call the vehicles database from the server, we’ve kept our precious server-side secrets safe. But by omitting await, we can crack on with streaming the page to the user much quicker than before.

React pops our fallback component in place, and continues to stream the page in the background until the database call resolves. At that point, the page connection closes and the component inside <Suspense> is rendered. use converts the promise over to our intended data format, and the component renders as expected.

You can even use ErrorBoundary to handle promise failures. Pretty neat.

Does ‘use’ work without JS?

Sadly not. React needs JS at runtime to swap out the loading content with the deferred content. Non-JS users will be left with the loading component for infinity. So this isn’t appropriate for core user journey functionality, or spider-friendly content.

CSS ordering can behave differently in development mode, always ensure to check the build (next build) to verify the final CSS order. Next.js Documentation

Seems like recipe for disaster, right?

Theoretically, this is controllable by the developer:

The CSS order is determined by the order in which you import the stylesheets into your application code. Next.js Documentation

But in the real world, it’s not the case. In development mode, CSS files are named layout.css and page.css etc. and are written in the HTML in that order. However, in a production build, the CSS is outputted in the totally opposite order with a different naming convention.

The issue is, in circumstances where specificity is matched between selectors, the source order of the CSS takes precedence. Not a problem if it’s consistent, but very much a problem if it changes depending on your environment.

Their “solution” also flies in the face of the web platform:

Prefer CSS Modules over global styles

No thanks.

How this is an acceptable ‘feature’ is beyond me. To say that the “order is determined by the order you import the stylesheets”, only holds water if Next consistently renders page → layout, or layout → page. Anyway, Friday afternoon rant over.

How do you fix this mess?

I paired with my good friend and colleague Szymon Pajka on this problem, and after much digging into the import order problem and trialling :where, he suggested we look at CSS Cascade Layers.

Cascade Layers allow developers to create & control multiple ‘layers’ of cascade/specificity. In this example below, we can write our reset styles within a @layer block, and then choose the have them calculated before, or after the theme/components etc. If this CSS was then chunked and split up by a bulid process, it wouldn’t matter which order the files were loaded in, they’d always follow the format of reset, theme, components.

@layer reset, theme, components;

@layer reset {
    /* Reset styles */
}

@layer theme {
    /* Theme styles */
}

@layer components {
    /* Component styles */
}

Any unlayered styles (existing styles without a wrapping layer block), will automatically ‘beat’ any cascade layers you’ve set up. So, rather than wrapping every component in: @layer component {}, we can leave them as unlayered, knowing they’ll beat our reset, theming, design system CSS files.

Amazingly, this also works in SCSS (we did not think it would):

@layer reset, designSystem, theme, utopia, utilities;

@layer reset {
    @import './reset.scss';
}

@layer designSystem {
    @import '@motorway-design-system/src/styles/reset.scss';
    @import '@motorway-design-system/src/styles/base.scss';
}

@layer theme {
    @import '@motorway-design-system/src/styles/theme/light.scss';
}

@layer utopia {
    @import './utopia.scss';
}

@layer utilities {
    @import './utilities';
}

Wrapping the imports keeps the control for these layers in one file, making adoption of the system more straightforward for new engineers, and most importantly, consistent across environments.

Thanks again to Szymon for his help pairing on this. There’s little better than writing CSS with someone else who adores and appreciates the language in the same way you do. 🫶

First up: logs were appearing in Datadog over multiple lines, which broke the stdout formatting rendering the logs unusable. Note, this only happened with the Edge runtime, not the standard Node variation. To solve this, I added a new section to the standard pino config:

const isServer = typeof window === 'undefined';
const isNextEdgeRuntime = process.env.NEXT_RUNTIME === 'edge';

export const config = {	
    // ...standard pino config
    ...(isServer && isNextEdgeRuntime && {
        browser: {
            write: {
                critical: (o: Object) => console.error(JSON.stringify(o)),
                debug: (o: Object) => console.log(JSON.stringify(o)),
                error: (o: Object) => console.error(JSON.stringify(o)),
                fatal: (o: Object) => console.error(JSON.stringify(o)),
                info: (o: Object) => console.log(JSON.stringify(o)),
                trace: (o: Object) => console.log(JSON.stringify(o)),
                warn: (o: Object) => console.warn(JSON.stringify(o)),
            },
        },
    }),
};

const loggerInstance = pino(config);

However, this created a second problem. Despite using console.error, errors were still being reported to Datadog as info, which then failed to trigger alerts and monitors. Not great. The solution was to pass a level parameter into the object; pre-stringification, on the warn and error methods.

const isServer = typeof window === 'undefined';
const isNextEdgeRuntime = process.env.NEXT_RUNTIME === 'edge';

export const config = {	
    // ...standard pino config
    ...(isServer && isNextEdgeRuntime && {
        browser: {
            write: {
                critical: (o: Object) => console.error(JSON.stringify(o)),
                debug: (o: Object) => console.log(JSON.stringify(o)),
                error: (o: Object) => console.error(JSON.stringify({ ...o, level: 'error' })),
                fatal: (o: Object) => console.error(JSON.stringify(o)),
                info: (o: Object) => console.log(JSON.stringify(o)),
                trace: (o: Object) => console.log(JSON.stringify(o)),
                warn: (o: Object) => console.warn(JSON.stringify({ ...o, level: 'warn' })),
            },
        },
    }),
};

const loggerInstance = pino(config);

This tells Datadog to treat the offending logs as errors/warnings, which can then be used to trigger alerts etc.

I’ve had the opportunity to work on a greenfield project recently and was able to trial an alternative approach. A more declarative approach. I’m certainly not the first person to think of this, but I wanted to share my experience. It looks a bit like this:

<button
    type="button"
    data-track="cta"
    data-track-category="homepage"
    data-track-name="heroCta"
>

<form data-track="submit" data-track-category="createAccount">

<a href="..." data-track="click">

Any anchor, form, or button can be marked up with data- attributes that describe the event. Rather than attach a handler to each event, we register one global click and submit event handler on the document. Thanks to event bubbling and event.target.closest, we can easily filter out elements that don’t have the data-track attribute.

Benefits

• This is a substantially more efficient pattern to attaching events to each element, particularly in a re-render heavy framework like React
• Abstracting this functionality allows us to declare less per element. For example, we can read event.target.textContent, rather than re-supply the label on every call-to-action button. We can automatically pull in the href on an anchor once, rather than duplicate the URL in an inline function
• There’s less code to write per component
• We can add new tracking providers without touching every component
• Common values can be set globally, rather than per component. For example, we may wish to pass the current page URL for all events
• This all started in a Next.js project. I’d painstakingly constructed my server/client components to minimise the number of client components. And that would’ve been entirely obliterated with inline tracking functions, that have to exist in a 'use client' file. This approach allowed me to keep as many components as pure server components

Drawbacks

• It’s extra HTML to send over the wire - sending markup for something that is entirely client-side isn’t ideal
• Everything that’s tracked is easier to see in dev-tools - it’s not as if inline functions are hidden, but they’re certainly less obvious. This could be a positive; if you’re not comfortable with someone seeing what’s being tracked, then maybe it shouldn’t be tracked? The tracking sunlight test
• Non-primitives can’t easily be tracked without stringifying JSON

Abstracting the tracking

Rather than calling, say, Google Analytics directly in the global handler, I’ve taken to dispatching a CustomEvent in a consistent format that can be listened to by any number of handlers. For the few times you may need to track something outside of the global handler, you can dispatch a CustomEvent with the same format and it’ll be fed to all the handlers.

Implementation

This is a rough implementation of the concept - I can’t guarantee perfection but it’s broadly what I’ve been using:

const TRACKING_EVENT = 'namespaced:tracking';

// Fire events to all tracking providers
const trackEvent = (eventAction, trackingDetail) => {
    window.dispatchEvent(
        new CustomEvent(TRACKING_EVENT, {
            detail: {
                eventAction,
                trackingDetail,
            },
        }),
    );
};

const globalTrackingHandler = async (event: Event) => {
    // Detect if we're on a trackable element
    const target = (event.target as HTMLElement).closest('[data-track]');
    if (!target) return;

    // Prevent click events from firing on trackable forms
    const action = target.dataset.track;
    if (action === 'submit' && event.type === 'click') return;

    // Extract data from the trackable element
    const category = target.dataset['track-category'];
    const label = target.dataset['track-label'];
    const name = target.dataset['track-name'];
    const url = target.dataset['track-name'] ?? target.getAttribute('href') ?? window.location.href;

    // Pass events to the global tracking helper
    switch (action) {
        case 'click': {
            trackEvent(action, {
                category,
                label,
                name,
                url,
            });
            break;
        }
        case 'submit': {
            const formLabel = target.querySelector('[type="submit"]')?.textContent ?? label;
            const formUrl = target.getAttribute('action') ?? url;
            trackEvent('cta', {
                category,
                label: formLabel,
                name,
                url: formUrl,
            });
            break;
        }
        default:
            break;
    }
};

document.addEventListener('click', globalTrackingHandler);
document.addEventListener('submit', globalTrackingHandler);

const specificTrackingHandler = (event) => {
    const { detail } = event;
    if (!detail) return;
    const { eventAction, trackingDetail } = detail;

    switch (eventAction) {
        case 'click':
            trackClick(trackingDetail);
            break;
        case 'cta':
            trackCta(trackingDetail);
            break;
        default:
            break;
    }
};

window.addEventListener(TRACKING_EVENT, specificTrackingHandler);