DEV Community: a-dev

CSS corner-shape: squircle in your design today (plus an amazing generator)

a-dev — Tue, 11 Aug 2026 19:09:03 +0000

Let's say you drive a car, and the road makes a turn of 90 degrees, and it has the shape of an ideal circle inscribed in a right angle. As a driver, you will feel this turn as very sharp and in some way even dangerous. But if the road starts to curve in a smoother way, giving you time to slightly turn the wheel, then the turn can become even sharper, but by then you have already lost speed in the process of turning. (That's maybe why I don't like cloverleaf interchanges, compared with smooth ones, but this is another story.) So our eyes prefer smooth curves that change dynamically through the turn, rather than mechanical ones.

No wonder Apple, which is crazy about design and curves, has been using the "squircle" shape in their products for a long time: they wanted a more lively shape than a plain rounded corner gives. Did you know that Nokia phone buttons have a squircle shape too?

And finally all this luxury is becoming available in CSS. For now it is available only in Chromium-based browsers (Chrome and Edge from version 139), but if you want to use it in your design today, you can, at least as a graceful degradation. Or even without degradation, but with some quirks.

Radius vs corner-shape

Long story short, I wanted to use this new property and found out that if I just put in CSS

.card {
  border-radius: 1rem;
  corner-shape: squircle;
}

nothing good will happen, because visually border-radius with 1rem has a different size than a squircle with 1rem. Look at this picture.

It's a big card with border-radius: 7rem and corner-shape: superellipse(3.9), but on the left, corner-shape is disabled (or, just not supported by the browser). The difference is huge.

I mean, if the superellipse is not equal to 1, then corner-shape is not equal to border-radius, and to achieve the same visual effect, you need to adjust the values.

Before I go to the solution, let's talk a bit about this unusual property.

Superellipse, or how curvature continues

I don't want to go deeply into math (for this I recommend you to read the article Understanding CSS corner-shape and the Power of the Superellipse, it has a detailed explanation), I'll just be brief and show the idea.

This is a value that is not a line or some stable constant, but a function that you call with a parameter. That parameter defines the exponent: how much of this type of acceleration the curve should have.

I would say, in reality, if the number is greater than 1, then there is a kind of deceleration at first (remember my example with the road), but then the road goes steep and the curve is sharper. If the number is less than 1, then the curve makes the turn very fast right at the start and then goes gentle.

If the number is equal to 0, the curve is a straight line. Finally, if the number is less than 0, then the curve is concave with the same magnitude as it was with the positive value. But let's say the minimum reasonable value of the superellipse is -3, and the maximum is 5. Notice, the center of these coordinates is a circle, which is equal to 1 (-4 down / +4 up).

Why reasonable? Because if you go beyond these values, it will be hard to see the difference. The formula of superellipse(n) uses the exponent 2^n, so the function of how the curve is drawn is x^(2^n) + y^(2^n) = 1. There is no reason to calculate the curvature that is impossible to see with the naked eye, and for the two corner cases the corner-shape specification already gives us presets: notch and square, which correspond to -Infinity and +Infinity respectively.

Let's see all presets of corner-shape in the value of superellipse(n):

notch: -Infinity (absolutely concave, just a square with a cut corner)
scoop: -1 (concave, just a regular scoop, which fits the squircle)
bevel: 0 (flat, just a line, no curvature)
round: 1 (circle, the same as border-radius)
squircle: 2 (convex, "Apple-style" squircle)
square: +Infinity (absolutely convex, just a regular square)

Funny to know that:

.element {
  /* the same */
  corner-shape: superellipse(-infinity);
  corner-shape: notch;

  /* the same */
  corner-shape: superellipse(infinity);
  corner-shape: square;

  /* the same */
  corner-shape: superellipse(0);
  corner-shape: bevel;

  /* the same */
  corner-shape: superellipse(2);
  corner-shape: squircle;

  /* doesn't make sense, if it's not a dynamic value, just use border-radius */
  corner-shape: superellipse(1);
  corner-shape: round;
}

Fallback or exact fallback

Finally, about fallback. I've made a corner shape generator

👉 https://a-dev.github.io/probes/corner-shape/

And my main idea was not only an interface to find a beautiful shape to fit your design, but also to generate a fallback for browsers that don't support this property.
Look at the screenshot below.

It's the same card, but that's how the CSS looks:

.card {
  border-radius: 1.237rem;
}

@supports (corner-shape: superellipse(3.9)) {
  .card {
    border-radius: 7rem;

    corner-shape: superellipse(3.9);
  }
}

As you can see, it's very important to use @supports, because the border-radius value is drastically different, but the result still looks similar. Looks great, doesn't it?

For ~90% of cases this is enough. If you want to make buttons, inputs, or other UI elements better looking, you can easily use this approach. And while browsers don't support this property, users will just see the usual border-radius.

If you want to use corner shapes with a value less than 1, you already need to use what I call an 'exact fallback', that creates a clip-path with exactly the same shape. It's not a perfect solution: first, it's more code, and second, it cuts off box-shadow, outline, etc. It has its own quirks.

The math around this is not trivial, you can read more about it in the docs (thanks Claude/OpenAI for this description and help in the implementation).

That's it. Choose the shape you like, copy the code and go curve!

P.S., or how to architect this CSS

Not long ago I developed what I called a CSS methodology to work with CSS Modules in the modern world (not every project is ready to use Tailwind, sometimes we want good old CSS), and in this methodology it is very easy to use 'atoms' like these corner shapes in your project, however big and complex it is.

Read more in Atoms, layers, types, tokens: a new CSS methodology built on CSS Modules, and in one of my open source projects I use it in this way: shape.module.css.

Atoms, layers, types, tokens: a new CSS methodology built on CSS Modules

a-dev — Mon, 20 Jul 2026 18:36:22 +0000

I don't dislike Tailwind, but I can't say that I'm in love with it either. I'm keen on the "atomic CSS" part of it, but reading all this mass of short class names in the HTML is a bit of a hard job, don't you find? Especially when it comes from an AI model. Also, I've noticed that models feel free to use anything Tailwind offers, and it's hard to harness them properly.

That was the reason I decided to look for another way to write CSS: one that gives me flexibility, sets clear architectural boundaries for how styles are organized and composed, and is easy to read and maintain.

I chose CSS modules because it can be harnessed and checked very well, plus the they have composes extension. The great part: you can easily debug it. You know, browser DevTools are really good for that.

In this CSS methodology a small set of conventions on top of CSS modules gives you a compact workflow for common component styling: a shared style API, typed variants, observable state, deterministic local overrides, and semantic color theming.

What I'm proposing here is a new CSS architecture (you could also call it a paradigm or a methodology). It's aiming for the same shelf where BEM, OOCSS, SMACSS, and others sit. I respect all of them, but they were invented before components, and most of their rules exist to solve one big problem: scoping styles through naming discipline.

CSS modules already scopes styles mechanically, so all that discipline can be spent on better things: design tokens, cascade layers, compile-time types. The old methodologies taught us how to survive the global namespace. This gets to assume the problem is solved and build on top. Atomic CSS/UnoCSS sits on that shelf too, but on a different branch.

TLDR

It's real CSS all the way down, just better behaved:

Atoms: cx(layout.padM, typography.h1)
Cascade layers
Generated types
data-* state
Two-tier color tokens

And you don't have to adopt it by hand: npx skills add a-dev/skills --skill css-modules-setup --skill css-modules installs the two canonical skills that let an AI agent set the system up and then code in it with you. You read the article, your agent reads the manual.

What I wanted to keep from Tailwind

Frankly speaking, there are two things Tailwind still does better: zero-setup prototyping (this system has a setup cost, paid once per project) and raw CSS bytes at scale. I can live with both trade-offs, prototypes are now easier to make entirely with AI and no one cares what's inside, we only need them to test ideas. This methodology optimizes for maintenance and debugging rather than minimum CSS bytes. If stylesheet size or parse cost actually matters in your project, measure before you commit.

Also, Tailwind gives you names, so you don't have to invent them (naming is genuinely hard). I tried to alleviate this pain with a small set of conventions that both you and the AI can follow.

Some people will say that they prefer Tailwind because everything exists in one file. I'm not that person, because that's exactly what turns PR diffs into soup, especially when it comes to a basic UI component like a button with a lot of variants.

Note that the attached implementation isn't universally applicable for now: it uses Vite and React. The principles can apply elsewhere, but another framework or a vanilla project needs its own setup and verification.

Architecture at a glance

The architecture is simple: global infrastructure defines the selected layer order, color roles, and generated types. A project-defined shared API sits above it. Local component modules consume and override that API.

atoms, ui, and #styles are just the names I picked. Nothing in the system depends on them. A project can use one shared module, role-based modules (layout/typography/spacing/etc.), or a different map entirely. The point is that the shared boundary is written down and its place in the cascade stays predictable.

This methodology doesn't prescribe a spacing or sizing scale. Those values and tokens belong to the project's design system; the methodology only says how styles are organized, composed, checked, and overridden.

Cascade layers: floor and ceiling

In my reference setup, the first piece of the infrastructure is the @layer atoms wrapper. It's the mechanism that makes all the overrides painless.

The rule is simple: for normal author declarations, unlayered styles beat layered ones, regardless of selector specificity. So the reference setup takes three steps. First, declare the layer order once in your global CSS:

/* src/shared/styles/index.css */
@layer reset, base, atoms, ui;

Treat this as a starting map. A project can rename, split, or add layers and module boundaries, as long as there is a single recorded order and it's clear who owns what.

Second, wrap shared styles in their layers: atoms in @layer atoms, UI primitives like a button in @layer ui. Third, don't wrap app components at all: they stay unlayered, so they always win.

That's the whole trick: shared styles are the floor, local styles are the ceiling. Take a local .title that composes an h1 atom with margin: 0, then overrides it with margin-top: 9px. Both selectors are single classes with equal specificity, and without layers the winner would depend on the source order in the final bundle. But with layers, the local rule wins deterministically.

One nuance: layers give you determinism between layers, not inside one. If you combine two atoms that set the same property, the usual source-order rule still applies. In practice, role-based naming makes such clashes rare.

Two-tier color tokens

The other part of the infrastructure was sorting out the mess with colors in the project's styles. After some trial and error, I came to the "severance" of color tokens into two tiers: palette and semantic color roles.

If you use Tailwind, you know this huge palette. It's good (you have a lot of options), but in a real project all those options erode the standard (good design is, above all, repeatability and consistency). Add a light/dark theme to it, and the remaining consistency falls apart in a moment.

In palette.css I keep vars for all the colors in lists of tones:

:root {
  --color-gray-50: oklch(96.6% 0.005 240deg);
  --color-gray-100: oklch(93% 0.008 240deg);
  --color-gray-200: oklch(87% 0.009 240deg);
  --color-gray-900: oklch(18% 0.015 240deg);
  --color-blue-400: oklch(70% 0.14 250deg);
  --color-blue-500: oklch(62% 0.17 250deg);
  --color-blue-600: oklch(54% 0.18 250deg);
  /* ... */
}

And in colors.css I keep vars for the colors that are used in the project, mapped to the palette:

:root {
  --color-text-primary: light-dark(var(--color-gray-900), var(--color-gray-100));
  --color-panel-bg: light-dark(var(--color-gray-50), var(--color-gray-900));
  --color-action-bg: light-dark(var(--color-blue-600), var(--color-blue-500));
  --color-action-text: light-dark(var(--color-gray-50), var(--color-gray-50));
  --color-accent-bg: light-dark(var(--color-blue-400), var(--color-blue-600));
}

Components consume the semantic roles and never touch the raw palette directly. Other token families can exist too; this article only pins down color.

light-dark() reads the active color-scheme, so the global setup needs to connect theme selection to it:

@layer reset, base, atoms, ui;

@import "./vars/colors.css"; /* @import "./palette.css" exists only inside colors.css to keep the dependency chain correct */

@layer base {
  html {
    color-scheme: light dark;
  }

  html[data-theme="light"] {
    color-scheme: light;
  }

  html[data-theme="dark"] {
    color-scheme: dark;
  }
}

data-theme sets by application bootstrap code, an SSR-safe theme script, or the framework integration. Component modules never touch the theme themselves.

TypeScript for CSS

First of all, I want to have type safety for my CSS modules. I use Vite, and it has some problems with CSS modules. I went through several libraries and even started to make my own, but ended up choosing vite-css-modules, the best pick for now. In a nutshell, it fixes composes imports, removes duplicates (yes, Vite creates them easily), fixes HMR and some other bugs, and renders classes in a way that works well. I recommend reading the README of this library, it has some good explanations and examples.

The other thing is a bit opinionated, but I think I'm right in this opinion 😉. In CSS I use kebab-case (.icon-light-s); in a component I use camelCase (styles.iconLightS).

camelCaseOnly is what makes that split real: only the camelCase key exists at runtime.

Generated declarations expose the same shape to TypeScript. Keep in mind that Vite doesn't typecheck, so the error appears only when tsc --noEmit runs.

Here's a complete Vite example. Merge it into your existing config; don't replace the plugin array.

// vite.config.ts
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
import { patchCssModules } from "vite-css-modules";

export default defineConfig({
  css: {
    devSourcemap: true,
    modules: {
      localsConvention: "camelCaseOnly",
    },
  },
  plugins: [
    react(),
    patchCssModules({
      generateSourceTypes: true,
      declarationMap: true,
    }),
  ],
});

Now my-component.module.css.d.ts describes the exported keys, and its declaration map connects them back to the CSS source. And you don’t depend on an editor extension, you can use VS Code, Zed, Vim, etc.

styles.iconLigthS;
// Property 'iconLigthS' does not exist.

I put generated declarations in .gitignore. The dev server regenerates them during development. CI and package lifecycle scripts must generate them before typechecking.

For npm, that order can look like this:

{
  "scripts": {
    "css:generate": "vite-css-modules",
    "css:types": "tsc --noEmit",
    "css:check": "npm run css:generate && npm run css:types"
  }
}

The setup skill writes the equivalent commands for the project's package manager. The reference fixture runs generation, tsc --noEmit, and a production build.

Core: make atoms in CSS Modules

Everything started from the idea of making atoms in CSS Modules. I wanted to have a set of classes that can be used in any component, but can also be easily overridden if needed. That isn't so easy, because importing them is always a problem, but I wanted to find a simple way.

For this, we should create a place where we put our "atoms" and global/common styles that we can use anywhere. I used the src/shared/styles/ folder and created an alias for it: I chose #styles. It's probably not the most popular choice (you'll more commonly see @/shared/styles), but it's shorter, and you’ll soon see why it’s convenient.

In this folder I created:

// src/shared/styles/index.ts

export { default as layout } from "./layout.module.css";
export { default as typography } from "./typography.module.css";
export { default as utils } from "./utils.module.css";
export { cx, type ClassValue } from "./lib/cx";
export { cssVars } from "./lib/css-vars";
// ... and so on, whatever you need. Or only 'atoms.module.css'

An atom is simply a reusable class exposed through the project's shared style API. It can contain one declaration or several related ones.

Then, for example, I created classes like:

/* src/shared/styles/typography.module.css */

@layer atoms {
  .h1 {
    margin: 0;

    font-size: var(--fs-xxl);
    font-weight: 600;
    line-height: 1.27;
    color: var(--color-text-primary);
  }
}

/* src/shared/styles/layout.module.css */

@layer atoms {
  .pad-m {
    padding-inline: 20px;
    padding-block: 16px;
  }

  .bg-top-gradient {
    background: linear-gradient(90deg, var(--color-action-bg) 0%, var(--color-accent-bg) 100%);
  }
}

Then you can use them in your components like this:

import { layout, typography, cx } from "#styles";

function MyComponent() {
  return (
    <div className={cx(layout.padM, layout.bgTopGradient)}>
      <h1 className={typography.h1}>Hello World</h1>
    </div>
  );
}

I personally prefer some verbosity in naming, and that's why I intentionally don't use p4 or anything else common in Tailwind class names, but you can.

And as you may have noticed, I import the cx function, which is a simple helper for combining classes. You can use any library for this, like classix/clsx/classnames. I prefer to import it as cx and not care how it actually works inside. And I use it only for combining component variants, never for dynamic state. I'll tell you why a bit further on.

So what if we need to add some specific design and want to use local styles? This is the moment when it all becomes really great, because you can use local styles and shared atom styles together with composes. (The composes keyword itself is widely supported)

/* src/.../my-component/my-component.module.css */
.root {
  composes: pad-m bg-top-gradient from "#styles/layout.module.css";
  grid-column: 1 / 3;
}

.title {
  composes: h1 from "#styles/typography.module.css";
  margin-top: 9px;
}

Pay attention to the naming: in composes you write class names exactly as they are in the CSS source: kebab-case (pad-m), not camelCase (padM).

And then in your component:

import styles from "./my-component.module.css";

function MyComponent() {
  return (
    <div className={styles.root}>
      <h1 className={styles.title}>Hello World</h1>
    </div>
  );
}

An important detail: composes doesn't create a CSS rule with additional declarations in it. No, it adds a class to the HTML element. In the rendered HTML it looks like this:

<div class="root pad-m bg-top-gradient">
  <h1 class="title h1">Hello World</h1>
</div>

As you can see, you can recreate Tailwind-like classes, but in a more maintainable way. Honestly, I don't think you should do it, because the philosophy of this approach is a bit different: stay close to real CSS, but also have atoms or shared styles that can be used in components and are easy to read and debug.

And if you need to override something, you can do it in your component's local styles, and it looks like the real CSS way. The @layer boundary is what makes that local override reliable.

That was the core of this methodology. The next question is component variants and state.

Class names and data attributes

This one is really opinionated, but it pays off: represent state through the channel that owns its meaning.

Input or state	Representation	Selector
Closed design variant	Typed CSS Module lookup	`.variantPrimary`
Native HTML state	Native attribute or pseudo-class	`:disabled`, `[open]`
Meaningful accessibility state	`aria-*` value	`[aria-pressed="true"]`
Private boolean state	Presence-based `data-*`	`[data-loading]`
Headless-library state	Existing library attribute	Library-defined
Continuous runtime value	Private CSS custom property	`var(--_progress)`

Use data-* only when the state has no native or accessibility representation. If the platform or a headless library already exposes it, style that source directly.

Here's how it looks for a button:

// ui/button.tsx
import type { ComponentPropsWithoutRef } from "react";
import { cx } from "#styles";
import styles from "./button.module.css";

type Variant = "primary" | "secondary" | "outline";
type Size = "s" | "m" | "l";

type ButtonProps = ComponentPropsWithoutRef<"button"> & {
  variant: Variant;
  size: Size;
  loading?: boolean;
};

const VARIANT_CLASS = {
  primary: styles.variantPrimary,
  secondary: styles.variantSecondary,
  outline: styles.variantOutline,
} satisfies Record<Variant, string>;

const SIZE_CLASS = {
  s: styles.sizeS,
  m: styles.sizeM,
  l: styles.sizeL,
} satisfies Record<Size, string>;

export function Button({
  variant,
  size,
  loading = false,
  className,
  disabled,
  children,
  ...buttonProps
}: ButtonProps) {
  return (
    <button
      {...buttonProps}
      className={cx(styles.root, VARIANT_CLASS[variant], SIZE_CLASS[size], className)}
      disabled={disabled || loading}
      data-loading={loading || undefined}
      aria-busy={loading || undefined}
    >
      {children}
    </button>
  );
}

One trap here: loading || undefined. If you write data-loading={false}, React keeps data-loading="false" in the DOM, so the selector [data-loading] still matches it. Passing undefined removes the attribute.

That presence rule is only for boolean data-*. ARIA uses values: aria-pressed="false" is meaningful and must stay in the DOM.

Also note the types: the map and the union can't drift apart. Add "danger" to Variant, and TypeScript underlines VARIANT_CLASS until you add both the class and the entry.

Extending a component becomes a mechanical, compiler-guided task.

And in the CSS module:

/* ui/button.module.css */
@layer ui {
  .root {
    border: none;
    /* ... */
  }

  .root[data-loading] {
    opacity: 0.5;
  }

  .root:disabled {
    cursor: not-allowed;
  }

  .variant-primary {
    background-color: var(--color-action-bg);
    color: var(--color-action-text);
  }

  .variant-secondary {
    background-color: var(--color-panel-bg);
    color: var(--color-text-primary);
  }

  .variant-outline {
    color: var(--color-action-bg);
    background: transparent;
  }

  .size-s {
    padding: 4px 8px;
    font-size: var(--fs-s);
  }

  .size-m {
    padding: 8px 12px;
    font-size: var(--fs-m);
  }

  .size-l {
    padding: 12px 16px;
    font-size: var(--fs-l);
  }
}

A small perk that I really enjoy: state debugging now happens right in the Elements panel. Open DevTools, add data-loading to the button by hand, and you instantly see the loading style, without needing React DevTools or clicking through the app to reproduce the state. It works in the other direction too: when a bug report comes in, you can rebuild the broken state attribute by attribute.

Also, I insist on short names: instead of BEM or repeating the component name, use just root, icon, label, header, item, meta, etc. If you have a component with several variants, you can use variant-primary, variant-secondary; for sizes, size-s, size-m, size-l (yes, I prefer an alpha size scale, it's flexible and easy to read). And if you have a component with several parts, you can use header, body, footer, etc.

And even a year after you last looked at a component, you can quickly tell what's going on in it, because the names describe roles and the state is visible right in the markup.

Skills for setup and continuous work

Of course, these days you also need a good harness for the AI that will work with this system. I made two skills. You can install them with npx skills add a-dev/skills --skill css-modules-setup --skill css-modules, project installation is preferable. The first one, css-modules-setup, is for setting up this whole system, including the vite-css-modules library, the Vite config, and the path alias. It's meant to be invoked explicitly, since setup happens once.

The second one, css-modules, works during everyday coding after the project adopts the methodology (the model can invoke it on its own). If you want to get to the bottom of this methodology, I recommend reading these skills: they're really well documented and have examples.

Think of these skills as a starting point. In recent months I've often found myself adapting different skills to specific projects, and I believe that's the right way to harness AI: tune them to your needs, architecture, and paths. A detailed harness for your project always beats a general one, with better results and fewer hallucinations.

That's it for now. The methodology is young, and I expect it to evolve. I hope this article gives you a good overview of the system and its principles. Please share your opinions and objections. Questions are welcome too.

Choreography of validation: how to make your auth form seamless and usable

a-dev — Sat, 27 Jun 2026 13:24:59 +0000

You know, for users the best login is no login at all. But we still need one, and the most popular is the email/password form. And honestly, most of them are a mess. They nag you too early or too late: red errors when you've already typed a perfectly good email - or before you've typed a single character. I've seen it a lot.

Here I want to share one way to make this better - a very opinionated one. I don't want to drift into the "philosophy of UI", so it's a concrete example on a concrete stack: React, TanStack Form, Zod, and e.g. Better Auth on the backend.

Reward early, punish late

This is the main principle of good validation UX: find the right moment to tell users they messed up. And the right moment to tell them they're back on track.

The most common mistake is being too eager. The form screams "Invalid email!" while you're still typing. That's how the browser's native <input type="email"> behaves, and how most libs do it too with onChange.

I almost always prefer onBlur. It's a fair moment to say: hey, this field has something invalid, please fix it. But the interesting part comes next - what happens while the user is fixing it?

Usually the error just sits there while they retype, and clears only on the next blur, or after they submit. For some libraries that's the default.

Another flavor: some forms show the error only when you click the button. Too late. Especially when the error has nothing to do with the backend and could be caught on the frontend. And it gets worse: you see the error, fix your input, and it stays until you click again. Frustrating, right?
Ok, enough complaining, let's fix it.

Demo: https://a-dev.github.io/probes/validation

Three independent timelines

What helped me was a mental model: "the error" isn't one thing. It has three separate lives: when it's born, when it's shown to the user, and when it dies. We control each one independently.

The birth of an error

The naive approach shows a field's error whenever the value is invalid. Too eager, like we said. Validating only on submit is too lazy. onBlur is a good compromise, but it has its own catch: the error is born the moment you leave the field, even if you typed nothing. Click in, click out, and you get an error for a field you never filled.

Back to our principle. "Punish late" - don't create an error until the user has actually typed something. "Reward early" - once it's born, kill it the moment they start typing again. It feels right: they're actively fixing things, so let's reward that.

TanStack Form 1.x lets us express exactly this with a single onDynamic validator and a custom validationLogic method. Thanks to the team for it - powerful and flexible.

// reward-early-validation.ts
// universal dynamic validation logic
import type { ValidationLogicFn } from "@tanstack/react-form";

export const rewardEarlyPunishLate: ValidationLogicFn = ({
  form,
  validators,
  event,
  runValidation,
}) => {
  // If the form is async, we need to use the async version of the dynamic validator
  const dynamicValidator = event.async ? validators?.onDynamicAsync : validators?.onDynamic;

  // Has the field that triggered this event already surfaced an error? Only then do we re-judge on every keystroke (so the fix is rewarded instantly)
  const fieldHasError =
    !!event.fieldName && (form.getFieldMeta(event.fieldName)?.errors.length ?? 0) > 0;

  const shouldValidate =
    event.type === "submit" || event.type === "blur" || (event.type === "change" && fieldHasError);

  // NOTE: runValidation returns the validator array the form actually runs, and the caller consumes that return value — so we must `return` it, even though the type says `=> void`
  return runValidation({
    validators:
      shouldValidate && dynamicValidator ? [{ fn: dynamicValidator, cause: "dynamic" }] : [],
    form,
  });
};

And the form:

// login-form.tsx
import { useForm } from "@tanstack/react-form";
import { z } from "zod";
import { rewardEarlyPunishLate } from "./reward-early-validation";

function buildLoginSchema() {
  return z.object({
    email: z.email("Enter a valid email address"),
    password: z.string().min(1, "Enter your password"),
  });
}

const form = useForm({
  defaultValues: { email: "", password: "" },
  validationLogic: rewardEarlyPunishLate,
  validators: {
    onDynamic: ({ value }) => toFieldErrors(value), // the single source of error truth
  },
  // ...
});

The validator delegates the checking to a helper that adapts Zod's output into the TanStack Form shape:

function toFieldErrors(values: LoginValues) {
  const result = buildLoginSchema().safeParse(values);
  if (result.success) return undefined;

  // Zod 4's treeifyError gives us a nested tree; we pull the first message per field
  const tree = z.treeifyError(result.error);

  const fields = Object.fromEntries(
    Object.entries(tree.properties ?? {}).flatMap(([fieldName, fieldError]) => {
      const message = fieldError.errors[0];
      return message ? [[fieldName, message]] : [];
    }),
  );

  return Object.keys(fields).length > 0 ? { fields } : undefined;
}

Why not two validators: the onBlur (to catch a field you focus and leave without typing, no change event fires there) and the onChange (to clear the error as you fix it)? It works, but with a nasty side effect: TanStack stores errors per trigger (errorMap.onBlur, errorMap.onChange, …) and flattens them into one errors array. Two validators returning the same message produce duplicates, and, worse, an onChange returning undefined can't clear an onBlur error, so field state and the rendered UI disagree.

Routing both blur and change-while-errored through one validator avoids all that. One trigger, one errorMap entry, no duplicates. And when the value becomes valid, the error clears immediately instead of just hiding.

Note: typing in field B never starts live-validating it just because field A is invalid, the fieldHasError check only applies to the field that triggered the event.

Show the error

The errors now live in field.state.meta.errors. Time to show them with a small hook.

// use-field-display-errors.ts
export function useFieldDisplayErrors(field: AnyFieldApi) {
  const [editing, setEditing] = useState(false);

  // Show errors only once the user has left the field (isTouched) and is not currently re-editing it. Start typing again → hide until the next blur re-judges

  const errors =
    field.state.meta.isTouched && !editing ? getErrorMessages(field.state.meta.errors) : [];

  return {
    errors,
    invalid: errors.length > 0,
    markEditing: () => setEditing(true), // call from input onChange
    markSettled: () => setEditing(false), // call from input onBlur
  };
}

The field component wires the two callbacks into the input's native events:

// input-field.tsx
const { errors, invalid, markEditing, markSettled } = useFieldDisplayErrors(field);

<Input
  value={field.state.value}
  onBlur={() => {
    markSettled();
    field.handleBlur();
  }}
  onChange={(e) => {
    markEditing();
    field.handleChange(e.target.value);
  }}
  invalid={invalid}
/>;

{
  invalid &&
    errors.map((msg) => (
      <Field.Error key={msg} match>
        {msg}
      </Field.Error>
    ));
}

isTouched is doing real work here. Because onDynamic is a form-level validator, a blur runs validation for all fields, not just the blurred one. The isTouched check keeps the still-unvisited fields quiet until the user actually lands on them.

Yes, there's a trade-off: click into a field, click out empty, and you'll see an error. But hiding errors on empty fields is worse - a required field should tell you it's required.

The !editing half is the "calm while you fix it" touch: the message vanishes the instant you start typing and comes back (if still wrong) on the next blur.

getErrorMessages just turns each entry (a string or { message }) into display text. No de-duplication - the single-trigger design can't produce duplicates in the first place. (That would bite you with multiple validators emitting the same message, but we don't have those here).

The death of an error

Some things you can only check on the server. In our example the error comes from Better Auth. It's a verdict on one specific (email, password) pair. So the moment the user edits either field, it's stale, and we remove it.

// use-login.ts
const [formError, setFormError] = useState<LoginError | null>(null);

const form = useForm({
  // ...
  listeners: {
    // The banner reflects a verdict on a credential combination. The moment the user edits either field, that verdict is stale — so clear it
    onChange: () => setFormError(null),
  },
  onSubmit: async ({ value }) => {
    setFormError(null);
    const email = value.email.trim();
    const { error } = await authClient.signIn.email({
      email,
      password: value.password,
      rememberMe: true,
    });

    if (error) {
      // I prefer not to show raw error messages from Better Auth or other auth libraries, because they can be too technical or expose too much information. Instead, we classify the error into a user-friendly message by the error code or status. For example, 400/401 errors should stay deliberately ambiguous so we never reveal which field was wrong
      setFormError(classifyLoginError(error, email));
      return;
    }
    await onNavigate(resolveSafeRedirect(redirectTarget));
  },
});

Same refrain as everywhere: the instant they type, the verdict is gone. Reward the fix.

Finale

Let's weigh the trade-offs.

Starting with cons:
The first one is about implementation. validationLogic doesn't feel fully baked yet - it still has todos about types. It'll surely get polished, which also means the API can still change.

There's a small, intentional gap between state and screen. The !editing check hides the message while the user types, even though the error is still sitting in field.state.meta.errors. Deliberate, calmer UX, but anything reading error state directly during that window sees something the user doesn't.

A server error can vanish before it's even read, if a hurried user starts typing before the banner renders. Trade-off again: rewarding the fix is good, but a message that flashes and disappears is just confusing. Fix: add a short delay before clearing it.

Every run calls buildLoginSchema().safeParse(...), rebuilding the schema each time. On purpose, but still. Trivial for a login form; for something bigger, you might want to cache it.

Only the first error per field shows up. It's a UX choice. Want all of them? Make toFieldErrors return every message.

And now pros:

It feels good. Really good. No nagging, no frustration, no confusion. The user is rewarded for fixing their input, and errors show up exactly when they're useful and vanish the moment they're not.

Clear separation of concerns. "When does an error exist?" (validationLogic), "should we show it now?" (display hook), "is the server verdict still true?" (listener). Three small, separately testable decisions. I like that.

A single onDynamic trigger means no duplicate messages and no drift between field state and screen. And it's reusable, the same validationLogic and display hook can drive any form.

Overall, I picked a very specific stack and solved it there, and as you can see, the cons are mostly about implementation, the pros mostly about UX. The idea ports to other stacks and libraries, though, and I hope it helps you make your auth forms (and not only auth forms) better.

CSS 'overscroll-behavior' rubber banding: the right color behind the page when you pull it

a-dev — Thu, 11 Jun 2026 23:06:19 +0000

I think you all know the overscroll rubber-banding effect: when you scroll past the end of a page, or pull past the top, the content bounces back. It exists in all modern browsers, though each one has its own idea of how far you can pull. Desktop Chrome has a surprisingly long pull - I managed to drag the page by ~70% of the window height. Firefox barely budges, around 10%. Safari, on macOS and mobile, sits comfortably in the middle at 40–50%.

Personally, I find this effect quite enjoyable - it adds a nice touch to the user experience. But it comes with one huge catch: there is no CSS property or API to fill the space 'behind' the content when it's pulled. Yes, you can set a background color on the body, but that only works if your background is one solid color, shared by the header and footer. Which, let's be honest, is not the case for most websites. Some sites just set overscroll-behavior: none and call it a day - but it's a shame to lose such a nice effect over this.

Building a custom pull effect with JS isn't always a good idea either, especially for a simple landing page that doesn't need any special pull actions (calling a server, loading more content, and so on).

Worth mentioning: there is a new proposal, Declarative Overscroll Actions, in the early stages of development. It's not clear yet whether it will give us an easy way to color the overscroll area, but I can see the potential for it somewhere in the future.

So there I was, stuck with a pretty simple landing page with a light-to-dark gradient from header to footer. On my way to solving this problem I ran into a lot of 'stranger things', and here I want to share my small findings on how to make it work more or less right.

You can find a demo here.
The important CSS file is here.

Gradient background

The first idea was to set a background on the body. Not a solid color, but a gradient. Here's the catch: a solid color on <html> or <body> fills the 'bounce' area; a linear-gradient, radial-gradient or conic-gradient does not.

But if you create a pseudo-element like html::before or body::before - it does. Including all types of gradients! With one very annoying issue: it has to be position: fixed. Absolute positioning won't do - the element is positioned relative to the body, so when you pull the page, it gets pulled along with the content.

Fixed positioning solves that, but creates a new problem: the element ignores scrolling completely. So if your gradient goes from light at the top to dark at the bottom, you can't continue the gradient into the overscroll area. At best, you can extend the gradient's outermost colors as solid fills: light at the start, dark at the end. It looks more or less good.

Here I need to stop and bring up one more aggravating circumstance: rubber banding happens on horizontal pulls too. And it often looks worse than the vertical one - designs tend to have differently colored sections, full-bleed photos, and so on. In a perfect world we might fill these areas with some kind of ambient-light effect, and even then I'm not sure it would fit. Honestly, I prefer to turn horizontal overscrolling off. It's a one-liner - overscroll-behavior-x: none on body/html - and no big loss for most websites. What's more, iOS Safari behaves this way by default.

I should stress that conic or radial gradients rarely make sense for overscroll areas anyway, since the pseudo-element is fixed and doesn't react to scroll at all.
Here is the code for the gradient background (white to black, for example):

body::before {
  pointer-events: none;
  content: "";

  position: fixed;
  z-index: -1;
  inset: 0;

  width: 100%;
  height: 100%;

  background-image: linear-gradient(white 0%, white 50%, black 50%, black 100%);
  background-repeat: no-repeat;
}

The important part: I split the gradient at 50% not just for fun - but because the user can pull the page for fun! And this is the first obstacle on the road to perfection. Pull diligently enough in Chrome, and the page moves by 70% of the window height. From both sides! So this approach works - with a big BUT.

Fixed elements

Next, I tried fixed elements that live within the page borders and kind of continue the page into the void. Let's attach them to the header and footer. In reality, I hit the same wall as with the gradient background: absolute positioning is out (pulled along with the content), so they have to be fixed - and fixed elements ignore scroll. You end up splitting them into two halves, and if the user pulls the page by 70% of the window height... you know the drill.

.header::after,
.footer::after {
  content: "";
  position: fixed;
  z-index: -1;
  left: 0;
  width: 100dvw;
  height: 50dvh;
}

header::after {
  top: 0;
  background-color: var(--color-bg-light);
}

footer::after {
  bottom: 0;
  background-color: var(--color-bg-dark);
}

Animation

At this point I remembered that we have a new API for scroll-linked animations. Yes, still early days, but it's already supported in Chrome and Safari (Firefox is on the way). So the idea: move those fixed elements together with the scroll, like this:

/* in addition to the previous code */
header::after,
footer::after {
  transform-origin: top;
  height: 100dvh;
  animation: scale-part;
  animation-timeline: scroll();
}

footer::after {
  animation-direction: alternate-reverse;
}

@keyframes scale-part {
  from {
    transform: scaleY(1);
  }

  to {
    transform: scaleY(0);
  }
}

Note that when the scroll reaches the end of the page, the animation grows the fixed footer block to 100dvh - so even a 70% pull won't break the illusion. Same for the header, but in reverse. Great! Except it doesn't work in Safari. Chrome only... so-so choice.

Safari?

The struggle with Safari led me to change the way the animation works. Instead of scaling a fixed element, let's animate the body background color itself. Why not? The user doesn't see this layer anyway - it sits behind the content and only peeks out at the outermost positions. Note: it’s crucial for Safari to have a background set on the body element, not the html. The CSS is delightfully simple:

body {
  animation: scroll-background;
  animation-timeline: scroll();
}

@keyframes scroll-background {
  from {
    background-color: white;
  }

  to {
    background-color: black;
  }
}

And it works! In Safari! And in Chrome! Firefox...

Universal solution?

I tried different approaches, and at some point I decided to give up on Firefox, for two reasons: it has a short pull and a small share of users (sorry, Firefox - I love you anyway and hope you'll support scroll animations soon). For Firefox we should at least keep a monotone background; better than nothing. I'd recommend the site's main background color, so the fill stays aligned with the design.
The final solution:

html {
  animation: scroll-background;
  animation-timing-function: linear;
  animation-timeline: scroll();
  background-color: black;
}

@keyframes scroll-background {
  from {
    background-color: white;
  }

  to {
    background-color: black;
  }
}

And now, some interesting observations.
Safari is not so simple. Apple loves to push the boundaries of design - literally. At the top of the desktop browser it shows a blurred version of the open page, and of course it uses the defined background color as a base. The animation there is smooth but a bit unpredictable - I suspect the system tries to find a contrasting color for this blurred layer, so the animation is not exactly linear. In mobile Safari, in contrast, the same animation happens at the bottom of the page and looks even more interesting.

Remember that you can control how the animation behaves - at which point of the scroll the colors change - and if you play with it, you can achieve some interesting effects in mobile Safari.

A sober afterword: weaknesses, and what would actually fix this

Time for some cold water. The final solution works, but it is a hack standing on another hack's shoulders and has a few weaknesses:

Repaint cost. Background color on the root is not a compositor-friendly property: every scroll frame triggers paint work on the main thread. The browser might optimize it in some way, since this layer is hidden behind the content, but that's not guaranteed. I checked the performance in Safari and Chrome and it seems fine, even on mobile - but keep it in mind. Scroll-linked animations are not free, especially when they trigger paint work. The fixed-elements approach is more efficient, since it only animates transform.
Short pages break it. If the page doesn't scroll, scroll() has no timeline, the animation never runs, and the fallback background-color: black shows behind a light header. You need a guard for non-scrolling pages.
It only handles vertical overscroll. Horizontal pulls are still a problem.
The content must be fully opaque. Any transparent gap in the body lets the user watch the background morph from white to black mid-scroll. That one is fun to debug.

How could it be solved properly? Honestly - only by the platform. Overscroll is drawn by the browser outside the document, so every CSS trick is, by definition, an illusion stitched to scroll position. Declarative Overscroll Actions is the closest thing on the horizon, since it anchors real, styleable elements into the overscroll area; until something like it ships, a dedicated overscroll-background property remains wishful thinking.

And one last sobering thought: elastic overscroll effectively exists only on macOS and iOS. Windows, Linux and most Android users will never see any of this effort. But this is exactly the kind of detail 99% of visitors will never consciously notice, yet it's what makes a site feel hand-made and cared for. Small win, big smile.
Happy overscrolling!

React Hook to Manage URL Search Params:?mess=less

a-dev — Mon, 03 Feb 2025 16:16:54 +0000

Keeping your page state in sync with URL search params doesn't seem like a big deal (it's definitely not cache invalidation). However, it becomes painful when you have multiple parameters, validation logic, and interdependencies 🙄 between parameters. I once faced this obstacle and created a hook that helped me to solve the problem. And now I want to share it with you. Yes, it's a React hook, yet the idea and DX can be adapted to other frameworks.

Before, I have to say that my react-hook is not a silver bullet. There are couple libraries that you can use, and I admit that they can suit your needs better. I recommend you to check them out:

nuqs - literally state manager for search params. If you want to put JSON in search params, this is your choice. It offers adapters for Next.js, React Router. And documentation is awesome.
tanstack router - not 'just lib', I know. But it's really great and I like that they saw the problem of search params and did some good stuff around it.

The demo

You can click buttons and enter text in the input field here (ignore the decorative landing page — I just had some fun with v0). Notice how the URL changes. If you refresh the page, the state is restored from the URL.
Also, check out the code on GitHub, especially the hook itself.

DX

First, create a Zod schema for the URL search parameters. Suppose you have a catalog page for clothes with filtering and pagination; a basic version of the schema might look like this:

const schema = z
  .object({
    page: z.string().default('1'),
    type: z.enum(['t-shirt', 'jeans', 'jacket']).default('t-shirt'),
    brand: z.array(z.string()).optional(),
    from: z.string().optional(),
    to: z.string().optional(),
  })

type Schema = z.infer<typeof schema>;

Notice, I've added default values for the page and type parameters — it isn't the best practice (more caveats will be discussed later), but it serves well for an example. This means that even if a user visits the page without any search parameters in the URL, the hook will add them to the address. For instance, if you go to this demo link without a query, you will still see ?page=1 in the address bar.

I strictly recommend you add parameters to the link on the page, it helps to avoid unnecessary renders and redirects. But sometimes it's not easy and this small hack could be useful.

The second business logic action that you find in this type filters, is 'dependent changes' — when one parameter changes, another should be changed too. For example, if you change the type to 't-shirt', the brand should be reset to default. It's a common case, and that really why I created this hook.

const beforeUpdateCallback: BeforeUpdateCallback<Schema> = (updatedParams) => {
  if (Object.keys(updatedParams).includes('page')) {
    /*
     * If the user is paginating,
     * leave the rest of the search parameters unchanged.
     */
    return updatedParams;
  }

  if (Object.keys(updatedParams).some((key) => ['type'].includes(key))) {
    /*
     * When the user changes the clothes type,
     * the brand filter should be reset.
     */
    return {
      page: '1',
      brand: [],
      ...updatedParams,
    };
  }

  /*
  * For any other changes, we simply reset pagination to the first page.
  */
  return {
    page: '1',
    ...updatedParams,
  };
};

This callback enhances the user experience by automatically resetting filters and preventing users from landing on non-existent pages when they change the 'type' filter.

The last step is to create and export the hooks:

const {
  URLSearchParamsProvider: ClothesFilterProvider,
  useUpdateURLSearchParams: useUpdateClothesFilter,
  useGetURLSearchParams: useGetClothesFilter,
} = createUrlSearchParams<Schema>({
  zodSchema,
  beforeUpdateCallback,
});

export { ClothesFilterProvider, useUpdateClothesFilter, useGetClothesFilter };

Type note: don't forget to add types of schema. One of the coolest feature is types for your search params.

UX Note: Make sure to debounce your form state updates. If you run the demo locally, you can simulate a longer data-loading time by changing the delay in the clientLoader (for example, set it to 1000ms). It shows how a sluggish search input can feel without proper debouncing

Implementation

Just wrap your clothes page component with ClothesFilterProvider and use the hooks to get and update search params. Here's how:

<ClothesFilterProvider>
  <ClothesPage />
</ClothesFilterProvider>

const ClothesPage: FC = () => {
  const { page, type, brand, from, to } = useGetClothesFilter ();
  const updateFilter = useUpdateClothesFilter();

  return (
    <div>
      <button onClick={() => updateFilter({ page: '2' })}>Go to page 2</button>
      <button onClick={() => updateFilter({ type: 'jeans' })}>Show jeans</button>
      <button onClick={() => updateFilter({ brand: ['nike', 'adidas'] })}>Show Nike and Adidas</button>
      {/* and so on */}
    </div>
  );
};

As you can see, working with arrays in this hook is straightforward. Remember to properly handle array changes, such as filtering when removing items and preserving existing selections. Check out the demo for practical example.

How it's done

Pretty simple. You need methods for encoding and decoding search parameters, some logic for handling array parameters, and a method for updating parameters that will call the callback before any actions. That's it.

One important addition I made but never used is default parameters that can modify the URL on the page loading. For it I use the React useLayoutEffect hook to prevent unnecessary renders. However, as mentioned earlier, I don't consider it as the best practice.

Look more closely at the source code and docs (ai gen) and feel free to ask questions.

In this version, the hook uses react-router v7 (though nothing has changed for v6). I haven’t tried it with Next.js yet, but I suppose it will work if the search-params methods are updated accordingly.

Testing with Playwright: Use i18next Translations in Tests, but not `t('key')`

a-dev — Sun, 05 Jan 2025 18:23:11 +0000

E2E-testing localized applications can be challenging, translations keys can make test code harder to read and maintain. This article demonstrates how to test i18next translations in React app using Playwright, with a simplified approach that avoids translation keys. The idea can be used in any project with i18next or similar libraries.

This approach builds upon concepts from my previous article about using Playwright fixtures for authorization in RBAC applications (Testing with Playwright: Making Authorization Less Painful and More Readable).

Here's a practical example of how it looks in a test:

const LOCALES = ["en", "es", "zh"];

describe("Author page", () => {
  for (let locale of LOCALES) {
    test(`it has a link to articles. {locale: ${locale}}`, async ({ page, tkey }) => {
      await page.goto("/authors/123");
      const link = await page.getByRole("link").nth(0).textContent();
      expect(link).toBe(tkey("Mis articulos", "menu"));
    });
  }
});

The key concept here is using the actual phrase instead of an i18n key for translation. Traditional approaches often use translation keys, which can be hard to read. For example: expect(link).toBe(t("menu.current_user_articles_link"));. This contradicts the principle of writing easily readable tests.

Implementation: Swapping Translation Keys with Phrases

The implementation revolves around using phrases that correspond to translation keys in tests. Here's an example of a typical translation file:

{
  "en": {
    "menu": {
      "current_user_articles_link": "My articles"
    }
  },
  "es": {
    "menu": {
      "current_user_articles_link": "Mis articulos"
    }
  },
  "zh": {
    "menu": {
      "current_user_articles_link": "我的文章"
    }
  }
}

We'll transform this into a swapped JSON format where phrases map to their corresponding keys (using Spanish as the primary language in this example):

{
  "Mis articulos": "menu.current_user_articles_link"
}

To achieve this transformation, we'll create a utility function that swaps keys and values in the JSON files. Here's the implementation using TypeScript and Deno:

import { readdir, readFile, writeFile } from 'node:fs/promises';
import { join } from 'node:path';

const CONSTANTS = {
  DIRECTORY_PATH: 'app/public/locale/es', // Path to locale language files
  SWAPPED_FILE_PATH: 'e2e/fixtures/i18n/es_swapped.json', // Output path for swapped JSON
  FILE_ENCODING: 'utf8',
} as const;

interface TranslationObject {
  [key: string]: string | TranslationObject;
}
type SwappedTranslations = Record<string, Record<string, string>>;

function swapKeysAndValues(obj: TranslationObject): Record<string, string> {
  const swappedObject: Record<string, string> = {};

  function traverseObj(value: unknown, path = ''): void {
    if (value && typeof value === 'object') {
      for (const [key, val] of Object.entries(value)) {
        traverseObj(val, path ? `${path}.${key}` : key);
      }
    } else if (typeof value === 'string') {
      swappedObject[value] = path;
    }
  }

  traverseObj(obj);
  return swappedObject;
}

const JSON_EXTENSION_REGEX = /\.json$/;

async function buildJsonWithNamespaces(): Promise<void> {
  try {
    const files = await readdir(CONSTANTS.DIRECTORY_PATH);
    const result: SwappedTranslations = {};

    for (const file of files) {
      const filePath = join(CONSTANTS.DIRECTORY_PATH, file);
      const fileContent = await readFile(filePath, CONSTANTS.FILE_ENCODING);
      const parsedFileContent = JSON.parse(fileContent) as TranslationObject;
      const swappedContent = swapKeysAndValues(parsedFileContent);
      const key = file.replace(JSON_EXTENSION_REGEX, '');

      result[key] = swappedContent;
    }

    await writeFile(
      CONSTANTS.SWAPPED_FILE_PATH,
      JSON.stringify(result, null, 2),
      CONSTANTS.FILE_ENCODING,
    );

    console.info('✅ Successfully generated swapped translations');
  } catch (error) {
    console.error(
      '❌ Failed to generate swapped translations:',
      error instanceof Error ? error.message : error,
    );
    process.exit(1);
  }
}

console.info('🔄 Converting locale to swapped JSON...');
buildJsonWithNamespaces();

Run this script using: deno run --allow-read --allow-write path_to_swap.ts

Setting Up i18n for Playwright

Now let's create a fixture for i18n in Playwright. This implementation is inspired by the playwright-i18next-fixture library, but with custom modifications for better control:

import * as fs from "node:fs";
import path from "node:path";
import Backend from "i18next-http-backend";
import { initReactI18next } from "react-i18next";
import { test as base } from "@playwright/test";
import { createInstance, type i18n, type TFunction } from "i18next";

const CONFIG = {
  TRANSLATIONS_PATH: "translations_path_to_files/or_api_endpoint",
  SWAPPED_TRANSLATIONS_PATH: "e2e/fixtures/i18n/es_swapped.json",
  LOCAL_STORAGE_KEY: "locale",
  SUPPORTED_LANGUAGES: ["es", "en", "zh"] as const,
  DEFAULT_LANGUAGE: "es",
  NAMESPACES: ["shared", "menu"] as const,
  DEFAULT_NS: "shared",
} as const;

const data = fs.existsSync(CONFIG.SWAPPED_TRANSLATIONS_PATH)
  ? JSON.parse(fs.readFileSync(CONFIG.SWAPPED_TRANSLATIONS_PATH, "utf8"))
  : {};

export function findTranslationByKey(
  key: string,
  namespace: string,
): string | undefined {
  const value = data[namespace][key];
  if (value && typeof value === "string") return value;

  throw new Error(
    `🔴 Translation not found for the namespace "${namespace}" and key "${key}"`,
  );
}

type SupportedLanguage = (typeof CONFIG.SUPPORTED_LANGUAGES)[number];
type Namespace = (typeof CONFIG.NAMESPACES)[number];

export const i18nOptions = {
  plugins: [Backend, initReactI18next],
  options: {
    lng: CONFIG.DEFAULT_LANGUAGE,
    load: "languageOnly",
    ns: CONFIG.NAMESPACES,
    defaultNS: CONFIG.DEFAULT_NS,
    supportedLngs: CONFIG.SUPPORTED_LANGUAGES,
    backend: {
      allowMultiLoading: true,
      loadPath: CONFIG.TRANSLATIONS_PATH,
    },
    react: {
      useSuspense: true,
    },
  },
} as const;

let storedI18n: i18n | undefined;

async function initI18n({
  plugins,
  options,
}: typeof i18nOptions): Promise<i18n> {
  if (!storedI18n?.isInitialized) {
    const i18n = plugins.reduce(
      (i18n, plugin) => i18n.use(plugin),
      createInstance(),
    );
    await i18n.init(options);
    storedI18n = i18n;
    return i18n;
  }
  return storedI18n;
}

export type Tkey = (key: string, namespace?: Namespace) => string;

interface I18nFixtures {
  i18n: i18n;
  t: TFunction;
  tkey: Tkey;
}

/*
  Fixture for i18n functionality. 
  It initializes the i18next instance and checks the language setting
  in the storageState created by Playwright. 
  Similar technique was used in my RBAC example.
  For more details, see my article about authorization testing 
  (https://dev.to/a-dev/testing-with-playwright-how-to-make-authorization-less-painful-and-more-readable-3344)
  and the official Playwright documentation
  (https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state).
*/

export const i18nFixture = base.extend<I18nFixtures>({
  i18n: async ({ storageState }, use) => {
    const i18nInstance = await initI18n(i18nOptions);

    if (storageState) {
      try {
        const data = JSON.parse(
          fs.readFileSync(path.resolve(storageState as string), "utf8"),
        );

        // This example uses localStorage to set the language.
        const localStorage = data?.origins?.[0]?.localStorage;
        const language = localStorage?.find(
          (i) => i.name === CONFIG.LOCAL_STORAGE_KEY,
        )?.value as SupportedLanguage | undefined;

        if (!language) {
          throw new Error(
            `No language setting found in localStorage (key: ${CONFIG.LOCAL_STORAGE_KEY})`,
          );
        }

        if (!CONFIG.SUPPORTED_LANGUAGES.includes(language)) {
          throw new Error(
            `Unsupported language: ${language}. Supported languages: ${CONFIG.SUPPORTED_LANGUAGES.join(", ")}`,
          );
        }

        // Change language if different from current
        if (i18nInstance.language !== language) {
          await i18nInstance.changeLanguage(language);
        }
      } catch (error) {
        throw new Error(`Failed to process storage state: ${error.message}`);
      }
    }

    await use(i18nInstance);
  },
  tkey: async ({ t }, use) => {
    await use((str?: string, namespace = "shared"): string => {
      if (!str) return "⭕ Error: no translation";
      const tkey = findTranslationByKey(str, namespace);
      return t(`${namespace}:${tkey}`);
    });
  },
  t: async ({ i18n }, use) => {
  // The same t function for usual translation keys
    await use(i18n.t);
  },
});

Finally, we can use the i18nFixture in our Playwright tests to handle translations and language settings. To learn more about working with fixtures, check out the official Playwright documentation. I recommend creating an index.ts file that exports all fixtures, which can then be imported into your test files.

import { mergeTests } from '@playwright/test';
import { i18nFixture } from './fixtures/i18n';

const test = mergeTests({
  ...i18nFixture,
});

export { test };

Wish you happy testing with Playwright and i18next! 🚀
If you have any questions or suggestions don't hesitate to comment below.

Testing with Playwright: How to Make Authentication Less Painful and More Readable

a-dev — Mon, 09 Sep 2024 18:11:53 +0000

Playwright is a great tool for e2e-tests and more (we'll discuss this another time). It's easy to write tests for what your website displays, but it becomes much harder when you want to test what your application actually does. Especially when users take many steps to achieve their goals - your tests can grow exponentially, with a thousand lines not being uncommon.

This is where abstractions become necessary. Developers start to use POMs (Page Object Models) and custom fixtures. We'll talk about POMs another time (again), for now, I want to tell you how to create a very handy fixture.

Most complex apps have an authentication level (who is this user?) and an authorization level (what can this user do?). In most cases, this is built with role models (RBAC). It's great if you can test your app features with different users/roles.

You can read about the core concept of authentication in the official docs (which I highly recommend). These solutions are great for cases with one authorization level (e.g., admin), but become verbose when you want to change users in different tests or, for example, run one test (not a whole bunch of tests) for five different roles simultaneously.

Look at what the test might look like after we create this fixture:

// admin
test('that {role: admin} can delete any article', async () => {
  //...
});

// more roles
const ROLES = ['admin', 'owner', 'manager', 'guest'] as const;

for (const role of ROLES) {
  test(`that {role: ${role}} can buy a coffee`, async () => {
    //...
  });
}

// specific user
test('that {email: user-email@example.com} can do whatever they want', async () => {
  //...
});

Looks great, doesn't it?

User-roles database

When I started struggling with multiple roles and different business logic expectations in e2e tests, I realized that a simple object defining users, their roles, and other necessary data would be ideal.
The shape of this object isn't crucial, you can create it as you see fit and then add an algorithm to extract data from it.

type Roles = 'admin' | 'owner' | 'manager' | 'guest';
type TestUsersData = {
  [key in Roles]: {
    email: string;
    password?: string; // Don't store real passwords here.
    // These email/password credentials should be created
    // for test purposes only in a test or dev environment/DB
    data: {
      // This isn't used in authorization,
      // but can be useful in tests
      name: string;
      status?: string;
    }
  };
}

const testUsersData: TestUsersData = {
  admin: {
    email: 'admin@example.com',
    password: 'admin',
    data: {
      name: 'Admin',
      status: 'active'
    }
  },
  owner: {
    email: 'owner@example.com',
    password: 'owner',
    data: {
      name: 'Owner',
      status: 'active'
    }
  },
// ... and so on

I've created a simple function to get user data by role, which returns user credentials for authorization:

import { testUsersData } from './test-users-data';

export function defineTestUser({ role, email, password }: Props) {
  if (!(role || email)) return;

  return {
    email: email ?? (role ? testUsersData[role]?.email : undefined),
    password: password ?? 'default-password', // default password
  };
}

The next important step is to create a method that parses data between curly braces from the test title and returns the data:

export function parseDataFromTestTitle(str: string): Record<string, string> {
  // Match all content between curly braces
  const regex = /{([\s\S]*?)}/g;
  const matches = str.match(regex) || [];

  const combinedObject: Record<string, string> = {};

  // Iterate through each matched set of curly braces
  for (const match of matches) {
    // Remove curly braces and split by comma 
    // to get individual key-value pairs
    const keyValuePairs = match.slice(1, -1).split(',');

    for (const pair of keyValuePairs) {
      // Split by colon and trim whitespace to separate key and value
      const [key, value] = pair.split(':').map((part) => part.trim());

      if (key && value) {
        combinedObject[key] = value;
      }
    }
  }

  return combinedObject;
}

As you can see, the idea is simple: you define a user in the test title, and then you can use this data in the fixture to authenticate.

Fixture

Before we create a fixture, we need to create a helper function to authenticate the user.
In my case, I use a JWT token, so I have a function to get a token by user credentials. For cookie-based authorization, the helper will be even simpler.

import { expect, type Page } from '@playwright/test';

export async function authenticateUser({ page, user }: {page: Page, user: UserType}) {
  // Get favicon - this is a small hack to ensure that Playwright
  // opens the browser and is ready to load the page.
  // You can use any other address, but it should load quickly.
  await page.goto('/favicon.ico');


  // Send a POST request to your backend server for authentication
  const response = await page.request.post('your_backend_api_endpoint/login', {
    data: { user },
    timeout: 30000,
  });

 // Handle errors
  if (response.status() === 401) {
    throw new Error(`🔴 Wrong credentials. Check role, email, or password: ${JSON.stringify(response)}`);
  } else if (!response.ok()) {
    throw new Error(`🔴 Failed to authenticate user. Status: ${response.status()}`);
  }

  // Ensure the response is successful
  expect(response.ok()).toBeTruthy();

  // Extract the authorization token from the response headers
  const token = response.headers().authorization;
  await page.evaluate(
    (token: string) => {
      if (!token) {
        throw new Error('No token received from the server');
      }

      // window.localStorage is used to store the JWT token
      localStorage.setItem('jwt', JSON.stringify(token));
    },
    token,
  );

  return { page };
}

And now (finally!) we can create a fixture.

import { test as base } from '@playwright/test';
import path from 'node:path';
import * as fs from 'node:fs';
// don't forget to import authenticateUser, parseDataFromTestTitle and defineTestUser functions

const authenticateUserFixture = base.extend<{ workerStorageState: string | undefined }>({
  storageState: async ({ workerStorageState }, use) => use(workerStorageState),
  workerStorageState: [
    async ({ browser }, use, testInfo) => {
      // Construct the test title path string and get string
      // from test title and title of parent test.describe
      const allPathString = [
        test.info().titlePath.reverse().join(' + '),
        test.info().title,
      ].join(' + ');
      const dataParsedFromTitle = parseDataFromTestTitle(allPathString);
      const user = defineTestUser(dataParsedFromTitle);
      console.info('🍏 parsed user credentials', user);
      if (!user) {
        await use(undefined);
        return;
      }

      // Define the file path for storing authentication state
      const fileName = path.resolve(
        testInfo.project.outputDir,
        `.auth/${user.email}.json`,
      );

      // Check if the authentication state file exists
      // and is fresh (less than 5 minutes old)
      const stats = fs.existsSync(fileName) ? fs.statSync(fileName) : null;
      if (stats && stats.mtimeMs > new Date().getTime() - 5 * 60 * 1000) {
        const origins = JSON.parse(fs.readFileSync(fileName, 'utf-8'))
          ?.origins[0];

        // And again, here I check JWT token in localStorage,
        // but you can check cookies or any other data
        const localStorage = origins?.localStorage;
        const hasJWTToken = Boolean(
          localStorage?.find((i: Record<string, string>) => i.name === 'jwt')
            ?.value,
        );
        if (origins?.origin === testInfo.project.use.baseURL && hasJWTToken) {
          console.info('🟡 Sign in skipped because token is fresh');
          await use(fileName);
          return;
        }
      }

      // Create a new browser page for authentication
      const page = await browser.newPage({
        storageState: undefined,
        baseURL: testInfo.project.use.baseURL,
      });

      // Authenticate the user and save the storage state
      await authenticateUser({ page, user, locale });
      await page.context().storageState({ path: fileName });
      console.info('[test authentication] 👤 📧', user?.email, locale);
      await page.close();

      await use(fileName);
    },

    // You can use {scope: 'worker'} here, but in this case, 
    // authentication will depend on the worker, 
    // which could be faster but can make it harder 
    // to write tests where credentials change
    { scope: 'test' },
  ],
});

Now you can use this fixture in your tests.
I have many fixtures in my project, so I have a helper function to use them. You can read more about this in the official docs.

// tests/index.ts or wherever you have your tests
import { mergeTests } from '@playwright/test';
import { authenticateUserFixture } from './fixtures/authenticate-user-fixture';

const test = mergeTests(
  authenticateUserFixture,
  // ... other fixtures
)

export { test };

This approach offers several advantages:

Test titles clearly indicate which user or role is being tested.
You can easily test different user roles or specific users without modifying the test code.
The fixture reuses authentication tokens when possible, speeding up test execution.
User credentials and authentication logic are centralized, making updates easier.

By implementing this system, you can significantly reduce the complexity of managing different user roles in your Playwright tests.

Remember, the specific implementation may vary based on your authentication mechanism (JWT, cookies, etc.), but the core concept remains the same. Adapt this approach to fit your project's needs, and enjoy! 🚀

Bonus

I encountered a specific test scenario where I needed to change role in the middle of the test. To address this, I created the 'useUser' fixture.
This fixture differs slightly from the previous one — you don't need to store authentication data in a file, as it operates only within the scope of the test.

export const authenticateUserInContextFixture = base.extend<UseUser, { storageState: string }>({
  useUser: [
    async ({ browser, storageState }, use, workerInfo) => {
      await use(async (userData, options) => {
        const user = defineTestUser(userData);
        if (!user)
          throw Error('🔴 Wrong credentials. Check role, email or password');

        const newContext = await browser.newContext({
          storageState: undefined,
          baseURL: workerInfo.project.use.baseURL,
        });
        const page = await newContext.newPage();
        await authenticateUser({ page, user });
        console.info('[browser-context] 👤 📧', user?.email);

        return page;
      });
    },
    { scope: 'test' },
  ],
});

Don't forget to add this fixture to your tests:

const test = mergeTests(
  authenticateUserFixture,
  authenticateUserInContextFixture,
  // ... other fixtures
)

Now you can use it in your tests.
In this example, I have two contexts within one test: one for a user with the 'reader' role and another for a user with the 'admin' role. The reader can only create comments and cannot delete them, while the admin can delete comments.

import { test } from 'tests/index.ts';

test('useUser fixture in the middle of the test. Start with {role: reader}', async ({
  useUser,
  page,
}) => {
  await page.goto('/articles/1');
  // ... add comment to the article. 
  // Use page.click, page.fill, etc.

  const adminPage = await useUser({ role: 'admin' });
  await adminPage.goto('/articles/1');
  // ... delete comment. 
  // Use adminPage.click, adminPage.fill, etc.

  // You can close the admin user's page if you don't need it anymore
  await adminPage.close();

  // get updated data with reader
  await page.reload({ waitUntil: 'domcontentloaded' });
  // ... check that comment isn't here
});

If you run Playwright with the option to open the browser, you'll see two browser windows: one for the reader and another for the admin. This is particularly useful when you need to test different roles within a single test.