DEV Community: Danny Holloran

Uint8Array toBase64 and toHex: Stop Round-Tripping Bytes Through btoa

Danny Holloran — Fri, 25 Sep 2026 10:13:48 +0000

Every codebase that touches binary data has the same little helper buried in a utils folder. It takes a Uint8Array, spreads it into String.fromCharCode, hands the result to btoa, and hopes for the best. Its sibling goes the other way with atob and a charCodeAt loop. And somewhere nearby there's a third helper that maps each byte to toString(16).padStart(2, '0') so you can print a hash.

None of those helpers are wrong, exactly. They're just working around the fact that btoa and atob were designed for strings, not bytes. That gap is now closed: Uint8Array has native methods for base64 and hex, in both directions, and they've been Baseline across current Chrome, Firefox, and Safari since September 2025.

The new methods at a glance

There are six of them, split into three pairs:

bytes.toBase64(options) and Uint8Array.fromBase64(string, options)
bytes.toHex() and Uint8Array.fromHex(string)
target.setFromBase64(string, options) and target.setFromHex(string) for writing into an existing buffer

Here's the old helper next to its replacement:

// Before: works, but only by pretending bytes are Latin-1 characters
function bytesToBase64(bytes) {
  return btoa(String.fromCharCode(...bytes));
}

function base64ToBytes(b64) {
  return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
}

// After
const b64 = bytes.toBase64();
const decoded = Uint8Array.fromBase64(b64);

The "after" version isn't just shorter. The spread in String.fromCharCode(...bytes) passes every byte as a separate function argument, so a large file can blow past the engine's argument limit and throw a RangeError. The native methods don't have that ceiling, and they skip the intermediate "binary string" entirely.

Hex gets the same treatment, which makes Web Crypto output a one-liner:

async function sha256Hex(text) {
  const data = new TextEncoder().encode(text);
  const digest = await crypto.subtle.digest("SHA-256", data);
  return new Uint8Array(digest).toHex();
}

await sha256Hex("hello");
// '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'

Uint8Array.fromHex() goes the other direction and throws a SyntaxError on odd-length strings or non-hex characters, so you get validation for free instead of silently producing NaN bytes.

base64url and padding without string surgery

Standard base64 uses + and /, which break in URLs and filenames. The usual fix is a chain of .replace() calls to swap in - and _ and strip the trailing =. Now it's an option:

const id = crypto.getRandomValues(new Uint8Array(16));

const token = id.toBase64({ alphabet: "base64url", omitPadding: true });
// e.g. 'q3N8y0Zp1VbX-7k2_JmR4g'

Decoding takes the same alphabet option. That makes peeking inside a JWT payload pleasantly boring, since JWT segments are base64url with the padding removed:

function readJwtPayload(jwt) {
  const [, payload] = jwt.split(".");
  const bytes = Uint8Array.fromBase64(payload, { alphabet: "base64url" });
  return JSON.parse(new TextDecoder().decode(bytes));
}

That works because the default lastChunkHandling mode, "loose", accepts a final chunk of two or three characters without padding. If you're validating input you don't control and want to reject anything non-canonical, pass lastChunkHandling: 'strict': the last chunk must then be padded to four characters, and any leftover "overflow bits" must be zero. Decoding also ignores ASCII whitespace, so base64 that was wrapped across lines in a PEM file or an email decodes without a cleanup pass.

One more quiet win: because you're decoding to bytes, not to a string, there's no more InvalidCharacterError from feeding btoa a string with an emoji in it. Encode text with TextEncoder first, then call toBase64(), and UTF-8 just works.

Decoding into memory you already have

The setFrom* methods write into an existing Uint8Array and return { read, written } so you know how much input was consumed and how many bytes landed. That's handy when you're reusing a buffer or decoding base64 that arrives in pieces:

const buffer = new Uint8Array(1024);
let offset = 0;
let pending = "";

function onChunk(text) {
  pending += text;
  const { read, written } = buffer
    .subarray(offset)
    .setFromBase64(pending, { lastChunkHandling: "stop-before-partial" });
  offset += written;
  pending = pending.slice(read);
}

With "stop-before-partial", an incomplete trailing chunk is left alone instead of being decoded early or throwing, so the next network chunk can finish it. The read count tells you exactly where to resume.

When to reach for them (and when not yet)

If your app targets current evergreen browsers, you can use these today and delete the helpers. On the server, check your runtime version before you rip out Buffer.from(x, 'base64'). Node's Buffer still works fine, but these methods give you one API that runs the same in the browser, Deno, Bun, and edge runtimes.

For older targets, feature-detect and fall back:

const toBase64 =
  typeof Uint8Array.prototype.toBase64 === "function"
    ? (bytes) => bytes.toBase64()
    : (bytes) =>
        btoa(Array.from(bytes, (b) => String.fromCharCode(b)).join(""));

Or pull in a polyfill: core-js covers the full set, and the es-arraybuffer-base64 shim does too.

The takeaway is small but satisfying: bytes can finally stay bytes. The next time you reach for btoa, check whether what you actually have is a Uint8Array. If it is, toBase64() is almost certainly the better call. The MDN reference for Uint8Array.fromBase64() covers every option in detail, including the edge cases around padding and overflow bits.

import defer: Lazy Modules Without Going Async

Danny Holloran — Tue, 22 Sep 2026 10:12:03 +0000

Every codebase has that one import. A syntax highlighter, a PDF renderer, a date-formatting library with a locale table the size of a small novel. It sits at the top of a file, it gets evaluated the moment the module graph runs, and it is needed on exactly one code path that most users never hit.

The usual fix is await import(). It works, but it charges rent: the function that needed the module becomes async, and so does its caller, and its caller's caller. You wanted to move some work later in time, and instead you rewrote a call stack. import defer is the piece that was missing, and it is riding along with ES2026.

Linked up front, evaluated on first touch

The syntax is a single keyword in one position:

import defer * as ts from "typescript";

function compileFile(path) {
  // The typescript module graph evaluates here, on first property access.
  return ts.createProgram([path], {});
}

Nothing from typescript runs at startup. The module and its dependencies are still resolved, fetched, parsed, and linked, so a missing file or a bad named import still blows up immediately rather than lurking. What is deferred is evaluation: the top-level code only runs the first time you read a property off ts. If compileFile is never called, that graph never executes.

That distinction is the whole value proposition. import() defers everything, which is why it has to be async. import defer defers only the synchronous part that can safely be moved, so property access stays synchronous and nothing above it needs to change colour.

Only the namespace form works. There is no import defer { createProgram } from "typescript" and no default form, because the namespace object is the thing doing the work — evaluation is triggered by a property read, and a destructured binding has nothing left to intercept.

The parts that will surprise you

The deferred namespace is effectively a proxy, and the list of operations that trip evaluation is broader than "read a property". Reading a key triggers it, but so does "value" in ns, Object.keys(ns), a for...in, Object.getOwnPropertyDescriptor, and even delete ns.value or Object.defineProperty on it — the operation fails, since the namespace is sealed, but evaluation happens anyway. Object.isSealed() and Object.isFrozen() enumerate keys, so those count too.

Which also means this defeats the whole thing:

import defer * as squares from "./squares.js";

const { getSquare } = squares; // evaluates immediately — you read a property

Three behaviours are worth committing to memory:

Top-level await opts out. Reading a property is synchronous, so it cannot wait on an async module. A module containing top-level await is evaluated eagerly, along with whatever its evaluation requires. The rest of the graph can still stay deferred, but do not assume defer bought you anything if the target awaits at the top level.

Side effects move. If a module installs a polyfill, registers a custom element, or patches a global, deferring it means that side effect now happens at an unpredictable moment, or never. Those modules should stay on a plain import.

Evaluation errors are cached and synchronous. If the deferred module throws while initializing, the throw comes out of whatever expression touched the namespace, catchable with a normal try...catch. Every later access rethrows the same error rather than retrying.

One more detail that saves a debugging session: the namespace deliberately does not expose an export named then, even after evaluation. Without that carve-out, handing the namespace to Promise.resolve() would look like a thenable and force evaluation as a side effect of promise resolution.

Where you can actually use it

Tooling got there first, as usual. TypeScript has understood the syntax since 5.9, and Babel, webpack, and Prettier all handle it. Bun and Deno ship it enabled by default. In browsers, V8 has had it behind a flag with an Intent to Ship filed in September 2026, WebKit has it implemented, and Gecko has signalled support — so treat it as landing rather than landed, and check the compatibility table before you rely on it in production.

The honest use case today is server-side and CLI code, where Bun, Deno, and a bundler give you a straight path. Go find the heaviest module on your cold-start path that is only needed conditionally, swap the import, and measure. If it turns out the module has top-level await, or installs something on import, you have learned something useful about your dependency either way.

Turbopack's Persistent Build Cache Only Helps If Your CI Keeps It

Danny Holloran — Mon, 21 Sep 2026 10:06:01 +0000

You upgrade to Next.js 16.3, read that Turbopack's persistent file system cache is now on by default for next build, see a chart claiming up to 5.5x faster builds, push to CI, and watch your pipeline take exactly as long as it did yesterday. Nothing is broken. The feature is doing precisely what it says. The problem is that "persistent" means persisted to a directory, and your build container throws that directory away the moment it exits.

This is the least glamorous kind of performance work: the speedup is real, it's free, and collecting it is an infrastructure chore rather than a code change.

The cache is a directory, not a feature flag

Turbopack has been persisting its incremental compilation cache to disk for next dev since 16.1. In 16.3 the same mechanism graduated for next build, and both are enabled by default:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    turbopackFileSystemCacheForDev: true, // default
    turbopackFileSystemCacheForBuild: true, // default
  },
};

export default nextConfig;

Dev writes to .next/dev/cache/turbopack, builds write to .next/cache/turbopack. On the second build Turbopack reads those entries off disk before compiling anything new, so you only pay for what changed. Vercel's published numbers span a wide range depending on how much of the route graph the change touches: nextjs.org went from 21s cold to 9.2s warm, vercel.com/home from 66s to 46s, and vercel.com/geist from 30s to 5.5s.

Every one of those numbers assumes .next/cache survives between runs. Restoring it in GitHub Actions is a handful of lines:

- uses: actions/cache@v4
  with:
    path: |
      ~/.npm
      ${{ github.workspace }}/.next/cache
    key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.[jt]s', '**/*.[jt]sx') }}
    restore-keys: |
      ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-

The restore-keys fallback matters more than the exact key. If your lockfile is unchanged but source files moved, you still want the previous cache as a starting point instead of a cold compile.

Docker is the case that quietly eats this. A containerized build starts from a clean layer, so unless you explicitly mount a cache or use RUN --mount=type=cache, .next/cache is empty on every single build and Turbopack spends time writing a cache that nothing will ever read. If that describes your setup and you don't plan to fix it, turn the thing off rather than paying for it:

experimental: {
  turbopackFileSystemCacheForBuild: false,
}

That's the actual decision in front of you: persist the directory, or opt out. Leaving it on with nothing to restore is the one configuration that costs you something and returns nothing.

The dev-memory win needs no setup at all

The other half of the release is the part you'll notice without touching any config. Because cached results are now safely on disk, Turbopack can evict them from memory instead of holding every visited route forever. After compiling 50 routes, Vercel measured its own dashboard app dropping from 21.5 GB to 2 GB, and nextjs.org from 4,600 MB to 840 MB.

That's roughly a 90% and 82% reduction, and it lands in a moment when your dev machine is more crowded than it used to be. A coding agent, a TypeScript server, a linter, and a test watcher are all competing for the same RAM as your bundler. Eviction requires the dev file system cache to be enabled, and both are on by default. The escape hatch exists if you're debugging cache behavior itself:

experimental: {
  turbopackMemoryEviction: false, // default is 'auto'
}

Your mileage genuinely varies here. The reduction depends on the size of your route graph, how much of it you touched, and how long the session ran. A three-route side project has nothing to evict.

Two smaller things worth a look

The React Compiler has been stable in Next.js since 16.0, but only as a Babel transform, which meant large apps waited on JS execution during builds. The React team shipped a native Rust port, and Turbopack now wires it up behind an experimental flag with early tests on large apps showing 20-50% compilation wins:

const nextConfig = {
  reactCompiler: true,
  experimental: {
    turbopackRustReactCompiler: true,
  },
};

Turbopack also picked up Vite's import.meta.glob, which is a small quality-of-life upgrade for anyone hand-maintaining a list of content files:

const posts = import.meta.glob("./posts/*.mdx");

for (const path in posts) {
  const post = await posts[path]();
}

Pass eager: true to import each match immediately. It's Turbopack-only, so it won't work if you're still building with --webpack.

Of the four, the build cache is the one with a real chance of being invisible to you. Before you file the 16.3 upgrade as done, go look at whether .next/cache actually survives a CI run. If it doesn't, you've been paying for a cache you never read.

Sources: the Turbopack 16.3 release post, the turbopackFileSystemCache reference, and the CI build caching guide.

CSS reading-flow: Fix the Tab Order Your Layout Broke

Danny Holloran — Sat, 19 Sep 2026 10:06:24 +0000

Put a card grid on a page, give one card grid-row: 1 / 3 so it sits up top as the hero, and the layout looks exactly right. Then press Tab. Focus lands somewhere in the middle of the page, jumps back up to the hero, skips sideways, and generally behaves like it is reading a different document than the one on screen. It is, in a way: the browser follows DOM order, and you just spent an afternoon making the visual order disagree with it.

This has been the standing tax on grid and flexbox since they shipped. order, row-reverse, grid-area, and auto-placement all move boxes around without moving a single node, and sequential focus navigation never got the memo. The usual workaround was positive tabindex, which trades one bug for a worse one. reading-flow and reading-order are the CSS Display Level 4 answer, and they are in browsers now.

The disconnect, in eight lines

Here is the smallest version of the problem. Three links in a flex container, reversed, with one of them reordered on top of that:

.box {
  display: flex;
  flex-direction: row-reverse;
}

.box :nth-child(1) {
  order: 2;
}

Visually you read One, Three, Two. Tab through it and you get One, Two, Three, because that is the source order. Nothing is broken according to the spec, and everything is broken according to the person using a keyboard.

One property fixes it:

.box {
  reading-flow: flex-visual;
}

Focus order becomes One, Three, Two, matching what is on screen in a left-to-right writing mode. If you would rather keep the reversed intent instead of the visual left-to-right sweep, reading-flow: flex-flow gives you Two, Three, One. Both respect order.

Picking the right keyword

reading-flow is set on the container, and the value you want depends on the layout it creates:

normal (the default) keeps DOM order, exactly as before.
flex-visual follows the visual order of flex items, accounting for writing mode.
flex-flow follows the flex-flow direction.
grid-rows walks the grid visually, row by row.
grid-columns walks it column by column.
grid-order follows the modified order when order is applied to grid items, and behaves like normal when it is not.
source-order works in grid, flex, and block containers, and is the one that enables manual overrides.

That last one pairs with reading-order, which is set on the item and takes an integer. It is the escape hatch for the case no keyword describes, such as an absolutely positioned item in a block container that visually sits above everything else:

.wrapper {
  display: block;
  reading-flow: source-order;
}

.wrapper .top {
  reading-order: -1;
}

Focus visits .top first, then falls back to source order for the rest. reading-order only does anything inside a container whose reading-flow is not normal, so the two are always used together.

Why this is not just tabindex with extra steps

You could approximate the flex example with tabindex="1", tabindex="2", tabindex="3" plus an aria-owns attribute to keep the accessibility tree in sync. People have been doing exactly that for years, and it is fragile for a specific reason: positive tabindex values are document-global. Another component elsewhere on the page with tabindex="1" joins the same bucket, and focus starts teleporting between unrelated regions of the page.

reading-flow avoids that by making the container a focus scope owner. Sequential navigation visits every focusable element inside the container before moving on, and the direct children are ordered by the property rather than by any positive tabindex on them, which is ignored for ordering purposes. The reordering also applies to how the container's children are exposed to assistive tech, not just to the Tab key, so the screen reader and the keyboard agree.

One sharp edge worth knowing: an element with display: contents inherits reading-flow from its layout parent and becomes a valid reading flow container itself. If you use display: contents as a wrapper, check your focus order after adding this.

Where support stands

Chrome has shipped both properties since version 137, Safari added support in 26.4, and Firefox still has it behind a flag as of September 2026 — so this is not Baseline yet. It degrades cleanly, though: browsers that do not understand reading-flow simply keep using DOM order, which is what they do today.

That makes it a real progressive enhancement, with one caveat. reading-flow is a fix for the cases where source order genuinely cannot match the visual layout, not a license to stop caring about markup order. Get the DOM close to right first, then reach for this to close the gap that grid and flexbox opened. The MDN pages for reading-flow and reading-order have the full value tables, and Chrome's reading-flow examples are worth tabbing through with your eyes closed.

WebNN: The Only Web API That Can Reach Your NPU

Danny Holloran — Tue, 15 Sep 2026 10:06:00 +0000

There is a piece of silicon in your laptop that your web app has never once used. If you bought a machine in the last couple of years, it almost certainly has an NPU: a small, power-efficient accelerator built specifically for running neural networks. Your OS uses it. Native apps use it. The browser, until recently, had no way to reach it at all.

WebGPU got us closer. Running a model through WebGPU means real hardware acceleration instead of grinding through WASM on the CPU, and for a lot of workloads that is the right answer. But WebGPU targets the GPU, which is the part of your machine that is also busy compositing the page, decoding video, and draining the battery. The NPU exists precisely because inference on a GPU is fast but expensive. WebNN is the standard that closes that gap, and it is currently the only web API that provides access to an NPU.

Where the spec actually stands

The W3C published an updated Candidate Recommendation of the Web Neural Network API on 22 January 2026, following more than a hundred significant changes since the previous snapshot in April 2024. That is a meaningful signal: the operator set and the graph model have stopped churning enough that browser vendors are being formally invited to implement and test.

Support today is Chromium-only, across ChromeOS, Linux, macOS, Windows, and Android. Chrome and Edge have working implementations. Firefox and Safari do not, and the spec needs two independent implementations passing the test suite before it can advance to a full Recommendation. So this is a progressive-enhancement story, not a "rewrite your inference layer" story. Feature-detect and fall back:

async function pickBackend() {
  if (!("ml" in navigator)) return "wasm";

  for (const deviceType of ["npu", "gpu"]) {
    try {
      await navigator.ml.createContext({ deviceType });
      return `webnn:${deviceType}`;
    } catch {
      // context creation throws when that device isn't available
    }
  }
  return "webgpu" in navigator ? "webgpu" : "wasm";
}

The graph model, and why it suits an NPU

WebNN is not a tensor library. You do not write a training loop against it. You describe a computational graph once, hand it to the browser to compile, and then execute it repeatedly with different inputs. MLGraphBuilder is the factory that builds that graph:

const context = await navigator.ml.createContext({ deviceType: "npu" });
const builder = new MLGraphBuilder(context);

const descriptor = { dataType: "float32", shape: [1, 3, 224, 224] };
const input = builder.input("input", descriptor);

const weights = builder.constant(
  { dataType: "float32", shape: [32, 3, 3, 3] },
  new Float32Array(weightData),
);

const conv = builder.conv2d(input, weights, { padding: [1, 1, 1, 1] });
const output = builder.relu(conv);

const graph = await builder.build({ output });

The build step is where the value lives. Because the browser sees the whole graph before it runs anything, it can fuse operations, pick layouts, and hand the result to whatever accelerator the platform exposes — DirectML on Windows, Core ML on Apple platforms, NNAPI-style paths on Android. That whole-graph view is exactly what NPU drivers want, and it is why an imperative, op-by-op API could never have targeted this hardware well.

You probably want this through ONNX Runtime Web

Writing graphs by hand is fine for a demo and miserable for a real model. In practice you reach WebNN through a runtime. ONNX Runtime Web exposes it as an execution provider, so switching backends is a config change:

const session = await ort.InferenceSession.create("./model.onnx", {
  executionProviders: [
    { name: "webnn", deviceType: "npu", powerPreference: "default" },
    "webgpu",
    "wasm",
  ],
  freeDimensionOverrides: { batch: 1, channels: 3, height: 224, width: 224 },
});

Two caveats worth internalizing before you ship this. First, operator coverage: all ONNX operators are supported by the WASM backend, but only a subset are supported by WebGL, WebGPU, and WebNN. Unsupported ops fall back to WASM, which means a model that looks like it is running on the NPU may be silently ping-ponging between backends and performing worse than either pure path. Profile the real model on real hardware; do not trust the backend name in your config. Second, freeDimensionOverrides is not optional decoration — WebNN wants static shapes, and a model with dynamic dimensions will often refuse to compile until you pin them.

Is it worth it yet?

If you are already shipping in-browser inference, WebNN is worth wiring in as the first entry in your execution-provider list. The fallback chain costs you a few lines and the win on a machine with a real NPU is not just speed, it is power: inference that does not spin up the GPU and does not tank battery life on a laptop that is not plugged in.

If you are not shipping inference yet, this is not the reason to start. Both the WebGPU and WebNN backends are still described as experimental, coverage is Chromium-only, and the operator gaps are real. But the direction is clear enough that it belongs on your radar. The ONNX Runtime WebNN docs are the fastest way to try it on a model you already have.

GraphQL @oneOf: Exactly One Input, Enforced by the Schema

Danny Holloran — Mon, 14 Sep 2026 10:05:35 +0000

Every GraphQL schema I've worked on eventually grows a field that can be looked up more than one way. You want a user by ID, or by email, or by username. The type system has no way to say "exactly one of these," so you pick one of two bad options: three root fields that do the same thing, or one field with three nullable arguments and a pile of validation at the top of the resolver.

The second option is the one most teams land on, and it's the one that rots. The schema advertises three optional arguments, which is a lie — two of the three combinations are errors. Your introspection-driven tooling can't see that. Your generated TypeScript types can't see it either, so the client happily compiles code that sends all three and finds out at runtime.

OneOf Input Objects fix this, and as of the September 2025 edition of the spec they are no longer an experiment you have to opt into.

The directive is the whole feature

You mark an input object with @oneOf and the executor enforces that callers supply exactly one field, with a non-null value:

input UserBy @oneOf {
  id: ID
  email: String
  username: String
}

type Query {
  user(by: UserBy!): User
}

Three root fields collapse into one. The constraint lives in the schema instead of in a guard clause, and validation happens before your resolver runs.

Two rules matter when you're writing these. Fields on a @oneOf input must be nullable, and they must not declare defaults. Both fall out of the semantics: a non-null field would be required, which contradicts "pick one," and a default would silently supply a second value. If you try it, your server will reject the schema at build time rather than at query time.

It's worth noting the constraint is about the field being provided, not about it being truthy. Passing { id: null } is a validation error, not a lookup for a null ID. That distinction bites people migrating from hand-rolled validation, where null and "absent" usually got collapsed into the same branch.

It's not just scalars

The more interesting use is polymorphic input. GraphQL has had union types on the output side since forever and nothing equivalent on the input side. @oneOf is the closest thing we have:

type Mutation {
  createPost(elements: [PostElementInput!]!): Post
}

input PostElementInput @oneOf {
  paragraph: ParagraphInput
  blockquote: BlockQuoteInput
  gallery: GalleryInput
}

input ParagraphInput {
  text: String!
}

input GalleryInput {
  imageUrls: [String!]!
  caption: String
}

A block editor sends a heterogeneous list of elements, each one tagged by which field it occupies, and every branch keeps its own required fields. Before this, that shape was a JSON scalar with a comment above it apologizing.

One sharp edge: recursive @oneOf inputs are only valid if some branch can terminate. An input whose single field points back at itself has no finite value a client could ever send, and a spec-compliant server will reject it. If you need recursion, give it an escape hatch — a scalar branch, or route the cycle through a regular nullable input field.

The client story is still catching up

Server support is broad. GraphQL.js v16+, GraphQL Ruby v2.0.21+, GraphQL Java v21.2+, GraphQL.NET v8+, HotChocolate v16+, Strawberry v0.230.0+, graphql-core v3.3.0+, and webonyx/graphql-php v15.21.0+ all ship it. GraphQL.js v17 tightened coercion further, so schemas that quietly relied on ambiguous inputs will now fail earlier and with better messages.

Codegen is the weaker link. The ideal output is a discriminated union:

type UserBy =
  | { id: string; email?: never; username?: never }
  | { id?: never; email: string; username?: never }
  | { id?: never; email?: never; username: string };

That's what you want, because TypeScript will then reject the two-field call at compile time. Whether you actually get it depends on your generator and its config — support has been uneven, and combinations like @oneOf plus the interface output setting have known rough edges. Check what your pipeline emits before assuming the guarantee reaches your client code.

If you're designing a new lookup or mutation input this week, reach for @oneOf first. It's a backward-compatible addition, existing clients keep working, and it moves a rule out of your resolver and into the one place every consumer of your API can already see.

node --test: The Test Runner You Already Have Installed

Danny Holloran — Sat, 12 Sep 2026 10:05:43 +0000

Every new Node library starts the same way. npm init, write two functions, and then spend twenty minutes deciding between Vitest and Jest for a package that has no browser code, no JSX, and no transform pipeline worth speaking of. You install a test framework, a config file, and a transitive dependency tree that dwarfs the thing you're actually testing.

Node has shipped a test runner since v18. It went stable in v20. Most of us kept reaching for the npm install anyway, mostly out of habit, partly because the early version really was thin. That's no longer a fair read of it. The 2026 version has mocking, fake timers, watch mode, coverage output, global setup hooks, and it runs your .ts files without a build step. For a backend library, it's frequently enough.

What you get for zero dependencies

Run node --test in a project with no arguments and it walks the tree looking for files matching a fixed set of patterns: **/*.test.js, **/*-test.js, **/*_test.js, **/test-*.js, **/test.js, and anything under a **/test/ directory. The .cjs and .mjs variants are included too. So are the TypeScript equivalents (.ts, .cts, .mts), unless you pass --no-strip-types.

That last part matters more than it sounds. You can write this and run it directly:

import { describe, it } from "node:test";
import assert from "node:assert/strict";

import { parseDuration } from "./duration.ts";

describe("parseDuration", () => {
  it("handles compound units", () => {
    assert.equal(parseDuration("1h30m"), 5_400_000);
  });

  it("throws on garbage", () => {
    assert.throws(() => parseDuration("soon"), /invalid duration/);
  });
});

No ts-node, no tsx, no build step. Node strips the type annotations and runs the result. The important caveat: it strips, it does not check. You still need tsc --noEmit in CI if you want type errors to fail the build. Type stripping is an execution strategy, not a type checker.

By default each test file runs in its own child process, which gives you real isolation between files without any config. The programmatic run() API exposes this as isolation: 'process' | 'none' if you need to flip it.

The subtest gotcha that catches everyone

This is the one thing worth internalizing before you migrate anything. Tests created inside a bare test() do not wait for their subtests. Suites do.

// Broken: the parent finishes before the subtest resolves,
// and the outstanding subtest is cancelled and marked as a failure.
test("user flow", async (t) => {
  t.test("creates the user", async () => {
    await createUser();
  });
});

// Correct: await each subtest.
test("user flow", async (t) => {
  await t.test("creates the user", async () => {
    await createUser();
  });
});

Inside describe(), siblings are enqueued together and you don't need the await. If you're coming from Jest or Vitest, where nesting always just works, this asymmetry will bite you exactly once and then never again. describe/it is an alias pair for suite/test, so picking the suite style sidesteps the problem entirely.

Mocking and fake timers are already there

The part people most often assume is missing. mock.fn() gives you a spy with call metadata, and t.mock.method() patches an object method and auto-restores it when the test ends, which is the behavior you want and rarely get for free.

test("retries on failure", async (t) => {
  t.mock.timers.enable({ apis: ["setTimeout"] });

  const fetchSpy = t.mock.method(client, "fetch");
  fetchSpy.mock.mockImplementationOnce(() => Promise.reject(new Error("503")));

  const result = withRetry(() => client.fetch("/health"));
  t.mock.timers.tick(1000);

  await result;
  assert.equal(fetchSpy.mock.callCount(), 2);
});

One sharp edge on timers: destructured imports like import { setTimeout } from 'node:timers' are not mockable. Reference the timer functions off the global or the module namespace and it works.

Where it still isn't Vitest

Coverage is real but still behind --experimental-test-coverage. It works, and the lcov reporter plugs straight into Codecov or SonarQube:

node --test --experimental-test-coverage \
  --test-reporter=lcov --test-reporter-destination=lcov.info

Note that the lcov reporter emits no human-readable results, so pair it with a second reporter in CI. Global setup and teardown landed in v24 via --test-global-setup <path>, pointing at a module that exports globalSetup and globalTeardown functions, but it's still marked early development. --watch is likewise experimental.

And there's no JSDOM, no browser mode, no snapshot ecosystem to speak of, no plugin API. If you're testing React components, keep Vitest.

The honest heuristic: for a server-side library, a CLI, or anything where the test story is "call a function, assert on the result," node --test is probably enough, and every dependency you don't add is one you don't have to audit later. Start with the built-in runner and let the project tell you when it's outgrown it.

Svelte Snippets: Reuse Markup Without a New Component

Danny Holloran — Tue, 08 Sep 2026 10:05:15 +0000

You have a card layout that appears twice in the same component: once wrapped in a link, once bare. The markup is identical apart from the wrapper. For years the Svelte answer was to extract Card.svelte, import it, thread props through it, and accept a new file in your tree for six lines of HTML.

That works, but it is a heavy tool for a light problem. A component brings its own module scope, its own props contract, and its own place in the file system. Sometimes you just want the markup twice. Svelte 5's snippets are the smaller tool, and once you see them as functions that return markup, most of the awkwardness in Svelte's old component-composition story goes away.

A snippet is a function, and `{@render}` calls it

The syntax is {#snippet name(params)}...{/snippet} to define, {@render name(args)} to call:

{#snippet figure(image)}
  <figure>
    <img src={image.src} alt={image.caption} width={image.width} height={image.height} />
    <figcaption>{image.caption}</figcaption>
  </figure>
{/snippet}

{#each images as image}
  {#if image.href}
    <a href={image.href}>{@render figure(image)}</a>
  {:else}
    {@render figure(image)}
  {/if}
{/each}

Parameters behave like a normal function signature: any number of them, destructuring, default values. The one exception is rest parameters, which are not supported.

Scope is lexical, and this is the part worth internalizing. A snippet can read anything in scope where it was declared — <script> variables, the current {#each} item — and it is visible to its siblings and their children, but not to anything above it. Declare a snippet inside a <div> and you cannot render it outside that <div>. Snippets can also reference themselves, which makes recursive markup pleasant instead of a <svelte:self> puzzle:

{#snippet countdown(n)}
  {#if n > 0}
    <span>{n}...</span>
    {@render countdown(n - 1)}
  {:else}
    <span>🚀</span>
  {/if}
{/snippet}

They replace slots, and they take the `let:` directive with them

Snippets are values, so passing markup into a component is just passing a prop. There are three shapes for this. You can pass a snippet explicitly like any other prop, declare snippets directly inside the component's tags (Svelte turns those into props automatically), or write plain content inside the tags, which becomes the implicit children snippet:

<Table data={fruits}>
  {#snippet header()}
    <th>fruit</th><th>qty</th><th>price</th>
  {/snippet}

  {#snippet row(d)}
    <td>{d.name}</td><td>{d.qty}</td><td>{d.price}</td>
  {/snippet}
</Table>

Inside Table.svelte, those arrive as ordinary props: let { data, header, row } = $props(), then {@render row(d)} in the loop. Optional ones use {@render children?.()}, or an {#if} block when you want fallback content.

Compare that to the Svelte 4 version, where <slot name="row" let:item /> introduced a variable through a directive whose colon meant the opposite of every other colon in the template, and where the variable from one slot was invisible inside a sibling slot. Snippets are functions, so their parameters are just parameters. Slots still work in Svelte 5 but are deprecated.

If you are migrating, budget for two rough edges. <slot name="header" /> becomes {@render header?.()}, but the corresponding <div slot="header"> on the consumer side is silently ignored rather than erroring — the content simply vanishes. And <Component let:prop> now throws, as does forwarding a slot with directives attached (<slot name="a" slot="a" let:abc>), which was legal in Svelte 4.

Typing and the edges

Snippets have a real type. Import Snippet from svelte and give it a tuple of its parameters:

import type { Snippet } from "svelte";

interface Props {
  data: unknown[];
  children: Snippet;
  row: Snippet<[unknown]>;
}

Add generics="T" to the <script lang="ts"> tag and you can tie data: T[] to row: Snippet<[T]>, so the consumer gets a type error for a mismatched row. That is strictly better than what slots ever offered.

Two extras worth knowing. Top-level snippets can be exported from a <script module> block and imported into other components, as long as they do not touch instance-level state (Svelte 5.5.0 and up). And createRawSnippet builds one programmatically, which you will almost never need but which exists when a library has to.

The rule of thumb: reach for a snippet when you are repeating markup, and for a component when the chunk has its own state, its own styles, or its own reason to be tested. The snippet docs cover the remaining corners.

CSS scroll-state() Queries: Styling Stuck, Snapped, and Scrollable

Danny Holloran — Mon, 07 Sep 2026 10:05:29 +0000

Every codebase I have worked in has the same file somewhere. It is called stickyHeader.js or useIsStuck.ts, and it exists because CSS could tell you an element was position: sticky but never whether it was currently stuck. So you wire up an IntersectionObserver against a one-pixel sentinel div, toggle a class, and hope nobody asks why the shadow flickers on iOS.

The browser has always known the answer. It has to know: it is the thing doing the sticking, the snapping, and the overflowing. Scroll-state container queries are the API that finally exposes that knowledge to the stylesheet.

The three states, and the container that owns them

The mental model is the one you already have from container queries. You mark an element as a container, then style its descendants based on the container's state. The only new part is a container-type value:

.header-wrapper {
  container-type: scroll-state;
  position: sticky;
  top: 0;
}

.header-wrapper > nav {
  transition: box-shadow 0.3s ease;

  @container scroll-state(stuck: top) {
    box-shadow: 0 4px 12px rgb(0 0 0 / 0.15);
  }
}

That is the whole sentinel-div dance, gone. Three descriptors cover most of what you would reach for JavaScript to do:

stuck: top | right | bottom | left — the sticky element is currently pinned to that edge
snapped: x | y | inline | block — this scroll-snap target is the one the scroller has snapped to
scrollable: top | right | bottom | left — there is more content to scroll in that direction

There is also a fourth, scrolled, which reports the direction of the most recent scroll and shipped later than the other three (Chrome 144, January 2026).

The rule that trips everyone up on their first attempt: the container cannot style itself. The element carrying container-type: scroll-state is the sticky or snapping element, and the thing that reacts has to be a child of it. For a snap carousel that means three levels, not two:

scroll container      → scroll-snap-type: x mandatory
  └ snap target       → scroll-snap-align + container-type: scroll-state
      └ child element → @container scroll-state(snapped: x) { ... }

Fading the unsnapped items

Carousels where the centered item is full-strength and its neighbours dim used to require a scroll listener or the scrollsnapchange event. With not in the query you can invert it and write the effect as a single rule on the inactive state:

.testimonials {
  overflow-x: auto;
  scroll-snap-type: x mandatory;
}

.testimonials > article {
  container-type: scroll-state;
  scroll-snap-align: center;
}

.testimonials > article > * {
  transition: opacity 0.4s ease;

  @container not scroll-state(snapped: x) {
    opacity: 0.25;
  }
}

Worth knowing: the snapped query fires like scrollsnapchanging, not scrollsnapchange. It flips as soon as the browser decides which target it is heading for, before the scroll settles. That is usually what you want for visual feedback, and occasionally too eager, in which case the JavaScript event is still the right tool.

Scroll affordances that actually know

The scrollable descriptor solves a problem that was genuinely hard: knowing whether an overflow area has anywhere left to go. Lea Verou's background-attachment: local trick approximated it, and scroll-driven animations approximated it differently, but both were workarounds. Now the gradient just asks:

.pane {
  container-type: scroll-state size;
  overflow: auto;
}

.pane::after {
  content: "";
  position: sticky;
  /* ...pinned overlay spanning the scrollport... */
  opacity: 0;
  transition: opacity 0.3s ease;

  @container scroll-state(scrollable: bottom) {
    opacity: 1;
  }
}

Two details in there are easy to miss. A pseudo-element can query its own originating element's container, which is what makes the single-overlay pattern work. And a single element can be both a size and a scroll-state container, so you are not forced to pick.

Where this actually stands

Support is Chromium-only. As of August 2026, caniuse puts global coverage around 72% with Chrome and Edge 133+, Opera 118+, and Samsung Internet 29+ shipping it. Safari 27 and Firefox 158 still have not, so this is not Baseline and you should not read a blog post that tells you it is.

That is fine for the use cases above, because every one of them is decoration. A shadow that never appears, a dimmed neighbour that stays bright, a gradient that stays hidden: nothing breaks, the carousel still scrolls, the header still sticks. Wrap the enhancement in @supports (container-type: scroll-state) when you need the fallback to be explicit rather than merely harmless, and put @media (prefers-reduced-motion: no-preference) around anything that moves.

What I would not do yet is delete the JavaScript from a component where the stuck state changes behaviour rather than appearance. For the other 90% of cases, this is a stylesheet-sized replacement for a file you have been maintaining for years.

Async Svelte: Using await Directly in Your Components

Danny Holloran — Mon, 31 Aug 2026 08:05:37 +0000

Every Svelte codebase eventually grows a little pile of scaffolding around asynchronous data. A let data = $state(null), an $effect that fetches and assigns, a loading flag, an error flag, and a {#if loading} in the template. Or the {#await} block, which is fine for one promise but nests badly the moment you need two. Either way, you end up writing plumbing rather than describing your UI.

Since Svelte 5.36, you can skip most of that. The await keyword works in three places it previously did not: at the top level of a component's <script>, inside $derived(...), and directly in your markup. It is still behind an experimental flag, but the design is worth understanding now because it changes how you think about loading states.

Turning it on, and what changes

Async Svelte is opt-in. Add experimental.async wherever you configure the compiler, which usually means svelte.config.js:

export default {
  compilerOptions: {
    experimental: {
      async: true,
    },
  },
};

The docs say this flag disappears in Svelte 6, so today's opt-in is tomorrow's default. Once it is on, this is legal:

<script>
  let a = $state(1);
  let b = $state(2);

  async function add(a, b) {
    await new Promise((f) => setTimeout(f, 500));
    return a + b;
  }
</script>

<input type="number" bind:value={a} />
<input type="number" bind:value={b} />

<p>{a} + {b} = {await add(a, b)}</p>

The interesting part is what does not happen. Bump a to 2 and the paragraph does not flash 2 + 2 = 3 while the promise is in flight. Svelte holds the whole update until add(a, b) resolves, then swaps everything at once. That is the headline feature: synchronized updates. You never render a torn UI where half the values are new and half are stale, which is exactly the bug that loading flags exist to paper over.

Updates can also overlap. A fast update lands while a slower earlier one is still running, so a quick keystroke is not stuck behind a slow one.

Concurrency is automatic, waterfalls are not

Two independent await expressions in markup run in parallel, even though they read as sequential:

<p>{await one(x)}</p>
<p>{await two(y)}</p>

Both kick off immediately. The same is not true inside your <script>, where await behaves like ordinary JavaScript and runs top to bottom. Svelte will warn you about this with an await_waterfall warning when you write something like:

let a = $derived(await one(x));
let b = $derived(await two(y));

Here b is not created until a resolves. Once both exist they update independently, but that first pass is a waterfall. If you have seen the same class of bug in a React useEffect chain, this is the familiar shape with a compiler warning attached.

Loading states move into boundaries

With no loading variable to hang a spinner on, placeholder UI moves to <svelte:boundary> and its pending snippet:

<svelte:boundary>
  <p>{await delayed('hello!')}</p>

  {#snippet pending()}
    <p>loading...</p>
  {/snippet}
</svelte:boundary>

The pending snippet shows when the boundary is first created and stays until every await inside it resolves. It deliberately does not reappear for later updates, since those are globally coordinated and rendering a full-page skeleton on every keystroke would be worse than useless.

For subsequent async work, $effect.pending() tells you how many promises are outstanding in the current boundary, not counting child boundaries. That is what you reach for when you want a small "validating..." spinner next to a form field rather than blanking the section. There is also settled(), a promise that resolves once state changes and their async consequences have been flushed to the DOM.

Errors get the same treatment. Anything thrown inside an await expression bubbles to the nearest boundary, where a failed snippet receives the error and a reset function. Worth remembering: boundaries catch errors during rendering and effects, not errors from event handlers or a stray setTimeout.

The parts still in motion

This is experimental, and the docs are direct about it: the details of await handling and $effect.pending() can change outside a semver major. Effect ordering already shifts when the flag is on, with block effects like {#if} and {#each} running before $effect.pre in the same component.

Server rendering works through an awaited render(...), though frameworks handle that for you. Today a boundary with a pending snippet renders that snippet during SSR and skips its contents, with streaming planned but not shipped. Svelte 5.42 also added fork(...), which speculatively runs async work you expect to need soon, and SvelteKit is the intended consumer for preloading on hover or focus.

If you maintain a Svelte app, the useful move right now is not a rewrite. Turn the flag on in a branch, pick one component with the most loading and error bookkeeping, and see how much of it disappears. The await expressions docs and the <svelte:boundary> reference are short enough to read in one sitting.

The Web Locks API: One Tab Does the Work, the Rest Wait

Danny Holloran — Sat, 29 Aug 2026 08:06:30 +0000

A user opens your dashboard, then opens it again in a second tab, then leaves a third one parked on another monitor from yesterday. Their access token expires. All three tabs notice at roughly the same instant, and all three fire a refresh request against your auth endpoint. Two of them get back a rotated refresh token that the third has already invalidated, and now the user is staring at a login screen they did nothing to deserve.

The usual fix is a pile of localStorage flags with timestamps, a BroadcastChannel message, and a comment that says // TODO: this is racy. It is racy. localStorage has no atomic compare-and-set, so two tabs can read "no refresh in progress" in the same tick and both write "refresh in progress." What you actually want is a mutex, and the browser has shipped one since March 2022. It is called the Web Locks API, it is Baseline Widely available, and almost nobody reaches for it.

navigator.locks.request is the whole API

There is one method that matters. You give it a name, a callback, and the browser guarantees that no other code on the same origin — any tab, any iframe, any worker — runs inside a lock with that name at the same time.

await navigator.locks.request("token-refresh", async () => {
  const stored = readToken();
  if (!isExpired(stored)) return stored; // someone else already did it

  const fresh = await fetch("/auth/refresh", { method: "POST" }).then((r) =>
    r.json(),
  );
  writeToken(fresh);
  return fresh;
});

The lock is held for exactly as long as the callback's promise is pending, and it is released when the callback returns or throws. There is no unlock() to forget, and there is no leaked lock if your fetch rejects. That alone makes it safer than any flag-in-storage scheme you would write by hand.

The re-check inside the callback is the part people skip. Three tabs queue on 'token-refresh'. The first one does the network round trip. The second and third get the lock afterward, see a token that is no longer expired, and return immediately. One request, three happy tabs.

Shared locks, and not waiting at all

request() takes an options object, and two of the options carry most of the value.

mode: 'shared' gives you the readers-writer pattern. Any number of shared holders can hold the same name at once, but an exclusive holder blocks all of them. This is the same semantics IndexedDB uses for readonly versus readwrite transactions, and it is the right shape when many tabs read a cached dataset while one occasionally rewrites it.

// Many of these can run concurrently.
navigator.locks.request("catalog", { mode: "shared" }, async () => {
  return readCatalogFromIDB();
});

// This one waits for every reader to finish, then blocks new ones.
navigator.locks.request("catalog", { mode: "exclusive" }, async () => {
  await rewriteCatalogFromIDB(await fetchCatalog());
});

ifAvailable: true flips the behavior from "wait your turn" to "tell me no." The callback still runs, but it receives null instead of a Lock when the lock was already held. That is the leader-election primitive: whichever tab gets the lock becomes the one that owns the WebSocket, or the polling interval, or the background sync, and the others quietly stand down.

navigator.locks.request("sync-leader", { ifAvailable: true }, async (lock) => {
  if (!lock) return; // another tab is the leader

  await new Promise(() => {}); // hold it for the lifetime of this tab
});

That never-resolving promise looks alarming and is actually the idiom. The lock is held until the tab closes or navigates, at which point the browser releases it and a queued tab is promoted automatically. You get failover for free.

There is also signal, which takes an AbortSignal so you can give up after 200ms instead of queueing forever, and steal: true, which forcibly releases whoever holds the lock. Treat steal as a recovery tool for a wedged tab, not a normal control flow — the stolen-from code keeps running and has no idea it lost the lock. Note that signal cannot be combined with steal or ifAvailable; the request rejects with a NotSupportedError if you try.

The edges worth knowing

Locks are scoped per origin and require a secure context, so https:// or localhost only. They do not survive a reload — every lock a document holds is released when that document goes away, which is the behavior you want but also means a lock is never a durable record of anything. Store the actual state in IndexedDB and use the lock only to serialize who writes it.

Deadlock is still your problem. If tab A holds a and waits on b while tab B does the reverse, they both wait forever. Acquire locks in a consistent order, keep the critical section short, and avoid nesting request() calls when you can flatten them.

For debugging, navigator.locks.query() returns { held, pending } arrays with the name, mode, and a clientId for each. Logging that when something feels stuck is usually faster than reasoning about it.

If your app has any of the classic multi-tab bugs — duplicated token refreshes, four WebSockets where you wanted one, an IndexedDB migration that runs twice — this is a smaller fix than the workaround you are currently maintaining. MDN's LockManager reference covers every option in a page you can read in five minutes.

Form-Associated Custom Elements: Web Components That Belong in a Form

Danny Holloran — Sat, 29 Aug 2026 08:06:24 +0000

Custom elements have been shippable for years, but the illusion falls apart the moment you drop one inside a <form>. The value never shows up in FormData. required does nothing. Hitting reset leaves your control sitting there with stale state, and the browser's validation bubble refuses to point at it. So most of us reach for the same workaround: render a hidden <input> inside the component and keep it in sync by hand, forever.

That workaround has been unnecessary for a while now. Form-associated custom elements are Baseline — Chromium, Firefox, and Safari 16.4 and up — and they let a component participate in a form as a first-class control instead of a decoration sitting next to one.

Two lines make it a form control

The whole thing hinges on a static property and one method call:

class RatingInput extends HTMLElement {
  static formAssociated = true;

  #internals;
  #value = "";

  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.attachShadow({ mode: "open" });
  }

  connectedCallback() {
    this.shadowRoot.innerHTML = `
      <div role="radiogroup" aria-label="Rating">
        ${[1, 2, 3, 4, 5]
          .map(
            (n) =>
              `<button part="star" type="button" value="${n}">&#9733;</button>`,
          )
          .join("")}
      </div>
    `;
    this.shadowRoot.addEventListener("click", (e) => {
      if (e.target.matches("button")) this.value = e.target.value;
    });
  }

  get value() {
    return this.#value;
  }

  set value(v) {
    this.#value = String(v);
    this.#internals.setFormValue(this.#value);
  }
}

customElements.define("rating-input", RatingInput);

static formAssociated = true tells the browser to treat the element like a form control: it gets picked up by the owning form, it inherits name, and it becomes eligible for validation. attachInternals() hands back an ElementInternals object, which is the private channel your component uses to talk to the form. Guard it — anything you can do through internals is something you probably do not want page scripts doing on your behalf, which is why it lives in a private field.

setFormValue() is the part that ends the hidden-input era. Pass it a string, a File, or a whole FormData object when one control needs to contribute several named values, and it lands in the submission:

<form id="review">
  <rating-input name="score" required></rating-input>
  <button>Submit</button>
</form>

new FormData(document.getElementById("review")).get("score"); // "4"

The lifecycle you get for free

Being form-associated also opts you into callbacks the browser fires at the right moments, so you stop wiring up listeners for things the platform already knows:

formResetCallback() {
  this.value = '';
}

formDisabledCallback(disabled) {
  this.toggleAttribute('inert', disabled);
}

formStateRestoreCallback(state) {
  this.value = state;
}

formResetCallback runs on form.reset(). formDisabledCallback fires when the element or its enclosing <fieldset> gets disabled, which is the case almost everyone forgets. formStateRestoreCallback is the one that quietly wins arguments in code review: it restores state on back-navigation and session restore, using the optional second argument to setFormValue(value, state). If your control's submission value differs from what the user actually typed — a formatted currency field, say — pass the raw input as that second argument and you get real state restoration instead of an empty box.

Validation the browser actually understands

setValidity() is where custom controls finally stop being second-class:

#validate() {
  const empty = this.hasAttribute('required') && !this.#value;

  this.#internals.setValidity(
    empty ? { valueMissing: true } : {},
    empty ? 'Please choose a rating.' : '',
    this.shadowRoot.querySelector('button'),
  );
}

The first argument is a ValidityStateFlags dictionary using the same flag names as native inputs (valueMissing, rangeUnderflow, customError, and so on). The second is the message. The third — the anchor — is the one people skip and then wonder why nothing appears: it is the element the browser points its validation bubble at. Without an anchor inside your shadow root, Chromium has nowhere to render the message and silently gives up.

Get this right and form.reportValidity(), implicit submit blocking, and the :invalid pseudo-class all work against your component exactly as they do against <input required>.

Styling states without attribute soup

The same ElementInternals object carries a states set, so internal state no longer has to leak out as a reflected attribute:

this.#internals.states.add("rated");
this.#internals.states.delete("rated");

rating-input:state(rated)::part(star) {
  color: gold;
}

:state() has been Baseline since 2024 and composes with :host() and ::part(), which means consumers can style your component's states without you publishing a contract of magic class names.

None of this is new enough to be risky anymore, and it collapses a surprising amount of glue code. Next time you are about to add a hidden input to a component, open the ElementInternals docs on MDN instead and delete it before it exists.