DEV Community: Ahmed Mahmoud

Why My Fonts Caused Layout Shift: Field Notes on next/font, size-adjust, and Arabic Fallback Metrics

Ahmed Mahmoud — Thu, 15 Oct 2026 06:00:13 +0000

Headline: Font-driven layout shift is a metrics mismatch, not a download-speed problem — the fallback font the browser paints first occupies a different box than the webfont that replaces it. next/font removes that mismatch automatically for Latin text by generating a size-adjusted fallback @font-face, and it does not remove it for Arabic, where I had to compute the override descriptors myself.

I run a bilingual site with English and Arabic routes. The English routes were visually stable. The Arabic routes jumped on every cold load, and the jump moved the whole right-to-left column, not one line. These are my notes on what was actually happening and what fixed it.

Key takeaways

Font layout shift is a metrics mismatch between the fallback font and the webfont, not a slow-download problem — a faster CDN does not remove it.
next/font self-hosts font files, preloads them per route, and with adjustFontFallback generates a fallback @font-face carrying size-adjust, ascent-override, descent-override, and line-gap-override.
That generated fallback is derived from a Latin system font, so Arabic, Cyrillic, and CJK text still shifts and needs a hand-written fallback @font-face scoped with unicode-range.
font-display: optional removes swap-driven shift entirely: it has a block period of roughly 100 ms and a swap period of zero.
Reproduce a cold load with cache disabled and throttling on — a warm font cache hides this bug on every local test while real users keep hitting it.

What actually causes font-related layout shift?

Font layout shift happens when the fallback font the browser paints during the download occupies a different amount of space than the webfont that replaces it. Cumulative Layout Shift (CLS) — the Core Web Vitals metric that sums unexpected movement of visible elements, where 0.1 or less is the good threshold — records that swap as a shift whenever it moves surrounding content. Download speed does not help: on a cold cache the browser still paints at least one frame with the fallback.

Two numbers decide how big the jump is. The first is average character width: if the fallback is wider, text wraps onto more lines and every block below it moves down. The second is the ascent-to-descent ratio, which sets the height of each line box. A fallback that is only four percent wider than the webfont can still push a paragraph onto an extra line and move a hero image.

font-display: swap — the value next/font uses by default — paints fallback text immediately and swaps in the webfont whenever it arrives. Swap guarantees the text is readable, and it guarantees a shift unless the two fonts have matching metrics.

What does next/font actually do for me, and what doesn't it?

next/font — the font loader built into Next.js since version 13.2, imported as next/font/google or next/font/local — does four things at build time. It downloads and self-hosts the font files from your own origin, so there is no runtime request to fonts.gstatic.com. It emits a <link rel="preload"> for the font files a route uses. It sets font-display: swap. And with adjustFontFallback, which defaults to true, it generates a second @font-face for a local fallback carrying size-adjust, ascent-override, descent-override, and line-gap-override derived from the webfont's own metrics.

Three things next/font does not do. It does not pick a sensible fallback for a non-Latin script, because the generated fallback is based on Arial or Times New Roman. It does not preload a font imported in a component the route never renders. And it does not protect you when your CSS re-declares font-family: Cairo, sans-serif by family name, which drops the generated fallback out of the chain entirely. That last one is the mistake I actually shipped: my Tailwind theme pointed --font-sans at the family name instead of the CSS variable the loader returns.

// app/fonts.ts
import { Inter, Cairo } from 'next/font/google';

export const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-sans',
  adjustFontFallback: true, // default — emits the size-adjusted fallback @font-face
});

export const cairo = Cairo({
  subsets: ['arabic', 'latin'],
  display: 'swap',
  variable: '--font-sans-ar',
});

// Use the variable, never the family name:
// font-family: var(--font-sans), system-ui, sans-serif;

How do size-adjust and the override descriptors remove the shift?

The four descriptors rescale the fallback font so it occupies the same box as the webfont before the swap happens. size-adjust is a @font-face descriptor that multiplies every glyph's advance width and the effective em size by a percentage. ascent-override, descent-override, and line-gap-override replace the font's vertical metrics so line box height stops depending on which font is currently active. Chrome and Firefox have supported all four since 2021, and Safari added them in version 17. Browsers that do not understand the descriptors ignore them, so this is progressive enhancement rather than a compatibility risk.

The ratio Next.js uses — and fontaine, the framework-agnostic plugin that does the same job for Vite and Nuxt — is straightforward: normalise each font's average character width by its units-per-em, divide the webfont's value by the fallback's, then express the webfont's vertical metrics relative to that adjusted em.

// scripts/font-metrics.ts — run once, paste the output into CSS
import fontkit from 'fontkit';

const web = fontkit.openSync('./public/fonts/Cairo-Variable.ttf');
// macOS ships Geeza Pro inside a .ttc collection: pass the PostScript name
const fallback = fontkit.openSync('/System/Library/Fonts/Supplemental/GeezaPro.ttc', 'GeezaPro');

const avg = (f: any) => f['OS/2'].xAvgCharWidth / f.unitsPerEm;
const sizeAdjust = avg(web) / avg(fallback);
const pct = (n: number) => `${(n * 100).toFixed(2)}%`;

console.log({
  sizeAdjust: pct(sizeAdjust),
  ascentOverride: pct(web.ascent / (web.unitsPerEm * sizeAdjust)),
  descentOverride: pct(Math.abs(web.descent) / (web.unitsPerEm * sizeAdjust)),
  lineGapOverride: pct(web.lineGap / (web.unitsPerEm * sizeAdjust)),
});

When should I use font-display: optional instead of swap?

Use font-display: optional when CLS on a route matters more than showing the brand font to first-time visitors. optional gives the font a block period of roughly 100 ms and a swap period of zero: if the file is not ready in time, the browser keeps the fallback for that entire page view and uses the webfont on the next navigation, once it sits in the HTTP cache. No swap means no swap-driven shift, whatever the metrics mismatch.

font-display	Block period	Swap period	Layout shift risk	Use when
`swap`	~100 ms	Infinite	High unless fallback metrics are matched	Body text with a size-adjusted fallback
`optional`	~100 ms	Zero	None from swapping	Display faces, CLS-sensitive routes
`fallback`	~100 ms	~3 s	Medium — swap only inside the window	Compromise between the two above
`block`	~3 s	Infinite	Low shift, but invisible text hurts LCP	Icon fonts where a wrong glyph is worse than no glyph

I kept swap for body text once the fallback metrics matched, and moved the display face to optional.

Why did my Arabic text still shift after all that?

Arabic kept shifting because adjustFontFallback generates its override against a Latin system font, while the font that actually renders Arabic glyphs is a different file with different metrics: Geeza Pro on macOS and iOS, Noto Naskh Arabic or Noto Sans Arabic on Android, Segoe UI or Tahoma on Windows. Arabic system fallbacks also tend to have taller line boxes than Latin ones, so the mismatch appears as vertical movement down an entire right-to-left column rather than one rewrapped line.

The fix is a hand-written fallback @font-face per script, scoped with unicode-range so it only claims Arabic code points, with overrides computed against the real system font instead of Arial.

@font-face {
  font-family: 'Cairo Fallback AR';
  src: local('Geeza Pro'), local('Noto Naskh Arabic'), local('Tahoma');
  /* numbers below are illustrative — generate your own with the script above */
  size-adjust: 96.40%;
  ascent-override: 100.70%;
  descent-override: 34.60%;
  line-gap-override: 0%;
  unicode-range: U+0600-06FF, U+0750-077F, U+08A0-08FF, U+FB50-FDFF, U+FE70-FEFF;
}

[dir='rtl'] body {
  font-family: var(--font-sans-ar), 'Cairo Fallback AR', sans-serif;
}

Two details cost me time here. fontkit.openSync() on a macOS .ttc collection returns the collection rather than a face, so the metrics read back as undefined until you pass the PostScript name as the second argument. And the unicode-range is not decoration: without it the Arabic fallback also claims Latin code points, and English headings inherit an adjustment computed for the wrong script.

Which font files actually get preloaded?

next/font/google preloads only the subsets you declare, and only on routes where the font module is imported. That makes subsets a correctness setting rather than an optimisation — omit it and the build fails with a missing-subsets error unless a default is configured in next.config. It also means importing an Arabic font in the root layout preloads Arabic font files on every English route.

Splitting the font imports per locale segment removed that waste for me: the shared root layout owns the Latin font, and the right-to-left layout segment imports the Arabic one. For weights that appear on a handful of pages, preload: false keeps the @font-face without spending early bandwidth on it. A variable font is usually the better default anyway — one file covering the whole weight axis beats four static weights, each with its own preload tag.

How do I verify the fix instead of guessing?

Reproduce a cold load first: open DevTools, check Disable cache, and throttle the network. With a warm font cache the file resolves from disk before first paint and the shift disappears, which is precisely why this class of bug survives local testing and only shows up in field data.

Then attribute the shift instead of eyeballing it. The Layout Instability API reports every shift together with the nodes responsible:

new PerformanceObserver((list) => {
  for (const entry of list.getEntries() as any[]) {
    if (entry.hadRecentInput) continue;
    console.log(entry.value, entry.sources?.map((s: any) => s.node));
  }
}).observe({ type: 'layout-shift', buffered: true });

entry.sources[0].node points at the element that actually moved, which is what turns CLS is too high into the paragraph under the hero rewraps. The Rendering panel in Chrome DevTools has a Layout Shift Regions toggle that paints the moving areas as they happen. Lighthouse confirms the fix in the lab; only field data from CrUX or your own real-user monitoring confirms it on the devices that count toward Core Web Vitals.

FAQ

Q: Does next/font remove CLS on its own?

A: For Latin text with adjustFontFallback left at its default of true, next/font removes most font-driven layout shift automatically. It does not cover non-Latin scripts, and it stops working the moment your CSS references the font family name directly instead of the CSS variable the loader returns.

Q: Is font-display: optional always better than swap?

A: optional is better for CLS because it never swaps after its roughly 100 ms block period, but first-time visitors may see the fallback font for the entire page view. Use optional for display faces and swap with matched fallback metrics for body text.

Q: Do I still need preconnect to fonts.gstatic.com with next/font/google?

A: No. next/font/google downloads the font files at build time and serves them from your own origin, so there is no runtime connection to Google's CDN to warm up.

Q: Where do I get the ascent, descent, and xAvgCharWidth numbers for a font?

A: Read them from the font binary with fontkit or opentype.js via the hhea and OS/2 tables, or use the published values in @capsizecss/metrics, which ships metrics for common web and system fonts.

Q: Does any of this apply outside Next.js?

A: Yes. fontaine generates the same size-adjusted fallback @font-face for Vite, Nuxt, and webpack projects, and the four descriptors are plain CSS you can write by hand in any stack.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Why My Package Broke in a CommonJS App: Field Notes on require(esm), the exports Map, and the Dual Package Hazard

Ahmed Mahmoud — Mon, 12 Oct 2026 06:00:25 +0000

Headline: Node.js 22.12 and later can require() a synchronous ES module, which removes the original reason most libraries shipped two builds, but it does not remove the dual package hazard and it does not forgive a badly ordered exports map. The three changes that fixed my publish were putting types first and default last in every condition block, keeping exactly one implementation of module-level state, and running publint and @arethetypeswrong/cli in CI before npm publish.

Key takeaways

Node.js 22.12.0 enabled require(esm) by default on the 22.x line, and it has been on by default since Node.js 23.0.0. A CommonJS file can now require() an ES module as long as that module graph contains no top-level await.
require() of an ES module graph that uses top-level await throws ERR_REQUIRE_ASYNC_MODULE, not ERR_REQUIRE_ESM. The two errors mean different things and have different fixes.
The exports field in package.json matches conditions in declaration order and the first match wins, so types must come first and default must come last. Adding exports also blocks every subpath you did not list, which surfaces as ERR_PACKAGE_PATH_NOT_EXPORTED.
The dual package hazard is what happens when one process loads both the CommonJS build and the ES module build of the same package: module-level state exists twice, singletons are no longer single, and instanceof across the two copies returns false.
Named imports from a CommonJS file work only when cjs-module-lexer can statically detect the export names. Exports assigned in a loop are invisible to it, and the consumer must use a default import instead.

The package was a few hundred lines of shared parsing helpers, published as ESM-only because every app I owned was already ESM. The first team to install it ran a CommonJS service, and it failed at boot with ERR_REQUIRE_ESM. My first instinct was to add a CommonJS build, which is the standard answer and also the answer that introduces the worst bug in this whole area.

Can Node.js require() an ES module now?

Yes, on Node.js 22.12.0 and later, and unflagged. require(esm) lets a CommonJS file load an ES module synchronously, returning the module namespace object, with the default export available as the .default property. The feature landed behind --experimental-require-module earlier in the 22.x line and was enabled by default in 22.12.0, and it is on by default in Node.js 23 and 24.

The single hard limit is asynchrony. require() is synchronous by definition, so if the ES module graph being required contains a top-level await anywhere, Node.js cannot finish evaluation before returning and throws ERR_REQUIRE_ASYNC_MODULE.

// app.cjs on Node.js 22.12+
const toolkit = require("@acme/toolkit"); // works if the ESM graph has no top-level await
console.log(toolkit.default);             // the ESM default export

// If it throws ERR_REQUIRE_ASYNC_MODULE, the escape hatch is dynamic import
const mod = await import("@acme/toolkit"); // legal inside an async function in CJS

What this changes in practice: ESM-only is now a defensible choice for a new library targeting Node.js 22.12 and above. What it does not change: bundlers, older runtimes, and tools that still resolve the require condition will keep asking for a CommonJS entry point for a long time.

Why does my exports map resolve to the wrong file?

Because conditional exports are matched top to bottom and the first matching key wins, so ordering is semantics, not style. The types condition must be first or TypeScript may resolve a runtime file before it ever sees the declaration file. The default condition must be last, because it matches everything and shadows any condition placed after it.

{
  "name": "@acme/toolkit",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "react-server": "./dist/index.react-server.js",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "default": "./dist/index.js"
    },
    "./package.json": "./package.json"
  },
  "sideEffects": false
}

Exporting ./package.json explicitly keeps tools that read your manifest at runtime working, because an exports field otherwise makes it unreachable. The react-server condition is what React Server Components resolution uses, and Next.js resolves it for any module imported from a Server Component.

The failure mode people hit hardest is subpath blocking. The moment you add exports, everything not listed is private, and consumers who were deep-importing @acme/toolkit/dist/internal/parse.js get ERR_PACKAGE_PATH_NOT_EXPORTED. That is a breaking change even when nothing else in the package moved.

What is the dual package hazard, and how do I avoid it?

The dual package hazard is the bug where one Node.js process loads both builds of the same package, so every module-level value exists twice. Node.js keeps separate caches for CommonJS and ES modules, so dist/index.js and dist/index.cjs are two distinct modules with two distinct copies of every class, registry, and counter you declared at module scope.

import { Token } from "@acme/toolkit";                 // resolves ./dist/index.js
const { Token: TokenCjs } = require("@acme/toolkit");  // resolves ./dist/index.cjs

new Token("a") instanceof TokenCjs; // false — same name, two classes

It is nasty precisely because it is silent. Nothing throws. A validation check fails for a value that is obviously the right type, or a cache that should be shared reports a miss, and the stack trace points at your logic rather than at your packaging.

Strategy	What you ship	Hazard risk	When I pick it
ESM-only	One ES module build, no `require` condition	None — only one copy can exist	New libraries targeting Node.js 22.12+, and anything holding state or exporting classes
ESM plus a stateless CommonJS wrapper	ES module implementation, plus a small CommonJS file that re-exports it	None, if the wrapper holds no state	Libraries that must keep older CommonJS consumers working
Two full builds	Independently bundled CommonJS and ES module outputs	High — both graphs can load at once	Only for pure functions with zero module-level state and no exported classes

My rule now is simple: if the package exports a class, holds a registry, or memoizes anything at module scope, it ships one implementation.

Why can't I destructure named exports from a CommonJS module?

Because Node.js discovers the named exports of a CommonJS file by static analysis, using cjs-module-lexer, and that analysis only sees assignments it can read literally in the source.

// legacy.cjs — the lexer cannot see these
for (const name of ["parse", "format"]) {
  module.exports[name] = impl[name];
}

// consumer.mjs
import { parse } from "./legacy.cjs";  // SyntaxError: no export named 'parse'

import legacy from "./legacy.cjs";     // works: the whole module.exports object
const { parse } = legacy;              // destructure at runtime instead

If you own the CommonJS file, write the assignments out literally, one exports.parse = ... per name, so the lexer can find them. If you do not own it, default-import the module object and destructure afterwards.

How do I configure TypeScript so the emitted output matches the package format?

Set "module": "nodenext" and "moduleResolution": "nodenext", and let the nearest package.json type field decide how each file is emitted. Under nodenext, a .ts file in a "type": "module" package is an ES module, .mts is always ESM, .cts is always CommonJS, and relative imports need file extensions.

{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "verbatimModuleSyntax": true,
    "declaration": true,
    "outDir": "dist"
  }
}

verbatimModuleSyntax tells TypeScript to emit import and export statements exactly as written, dropping only those marked import type. TypeScript 5.8 taught --module nodenext about require() of an ES module, so a .cts file requiring an ESM dependency is no longer a compile error on runtimes that support it.

The declaration side has its own trap: one .d.ts file cannot describe both formats correctly, because the module kind of a declaration file is inferred the same way as a source file. Dual packages need .d.mts and .d.cts alongside their respective entry points.

How do I verify a package before publishing it?

Run publint and @arethetypeswrong/cli against the packed tarball, then smoke-test both import styles in a real Node.js process. publint lints the manifest for packaging errors such as condition ordering and format mismatches. @arethetypeswrong/cli, invoked as attw, checks that type declarations resolve correctly for every consumer configuration, and it catches masquerading types where a CommonJS entry point is described by an ESM declaration file.

npm pack
npx publint
npx @arethetypeswrong/cli --pack .

# Smoke-test both resolution paths against the real runtime
node --input-type=module -e "import('@acme/toolkit').then(m => console.log(Object.keys(m)))"
node --input-type=commonjs -e "console.log(Object.keys(require('@acme/toolkit')))"

I wire both CLIs into the same CI job that runs the build, so a bad exports map fails the pipeline instead of failing someone else's install. Packaging errors are invisible in your own repository and only ever appear in a consumer's.

FAQ

Q: Does require(esm) mean I can drop my CommonJS build entirely?
A: Only if every consumer runs Node.js 22.12 or later and no bundler in their toolchain insists on the require condition. For a library with unknown consumers, a thin stateless CommonJS wrapper is cheap insurance and carries no dual package hazard.

Q: What is the difference between ERR_REQUIRE_ESM and ERR_REQUIRE_ASYNC_MODULE?
A: ERR_REQUIRE_ESM means the runtime will not load an ES module through require() at all, which on modern Node.js usually points at resolution picking an unexpected file. ERR_REQUIRE_ASYNC_MODULE means the runtime tried and stopped because the module graph uses top-level await.

Q: Why did adding an exports field break my consumers?
A: An exports field makes every path you did not list unreachable, so any consumer deep-importing an internal file now gets ERR_PACKAGE_PATH_NOT_EXPORTED. Publish it as a major version, or list the previously reachable subpaths explicitly during a deprecation window.

Q: Do I still need the main field in package.json?
A: Keep main as a fallback for tooling that predates conditional exports. Node.js ignores main whenever an exports field is present, so it costs nothing and buys compatibility with older bundlers and resolvers.

Q: How do I get __dirname in an ES module?
A: Use import.meta.dirname and import.meta.filename, available since Node.js 20.11 and 21.2. For older runtimes, derive it with fileURLToPath(import.meta.url) from node:url.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Why My LLM Feature Cost More Than It Should: Field Notes on Prompt Caching, Cache Breakpoints, and the Timestamp That Killed Every Hit

Ahmed Mahmoud — Wed, 07 Oct 2026 06:00:09 +0000

Headline: Prompt caching saves money only when the cached prefix is byte-identical across requests, and a single interpolated timestamp in a system prompt is enough to make every call a cache write instead of a cache read. The three things that fixed my bill were ordering the request static-first (tools, then system, then messages), putting the cache_control breakpoint at the end of the stable region, and reading cache_read_input_tokens from every response instead of assuming caching was working.

Key takeaways

Prompt caching is a provider-side store of the processed prefix of a request, so a later request with the identical prefix skips re-processing it. With the Anthropic Messages API it is opt-in per content block: add cache_control: { type: "ephemeral" } to a block and everything up to and including that block becomes the cached prefix. A request may carry at most four breakpoints.
A cache read is billed at 0.1x the base input token price. A five-minute cache write is billed at 1.25x and a one-hour write at 2x. The extra 0.25x paid on a five-minute write is repaid by the first hit inside the window, because each hit saves 0.9x.
The cache key is the exact serialized prefix in the fixed order tools, then system, then messages. A timestamp in the system prompt, a tool array built by iterating a Map, or a swapped model id all invalidate from the point of change onward.
Every Messages API response reports input_tokens, cache_creation_input_tokens, and cache_read_input_tokens. Cache hit rate is read / (read + creation + input), and it is the only honest way to know whether caching is on.
Prompt caching does not reduce output token cost and does not fix a bloated prompt. Deleting four thousand tokens of context nobody reads beats caching them at 0.1x forever.

The feature was a support agent with a large tool schema and a long API reference pinned into the system prompt, which is exactly the shape prompt caching is built for. I added a breakpoint, deployed, and the cost per conversation did not move. The usage object was blunt about it: cache_creation_input_tokens was populated on every single request and cache_read_input_tokens was zero on every single request. I was paying 1.25x to write a cache entry that nothing ever read.

What is prompt caching, and what am I actually paying for?

Prompt caching lets the provider reuse the work it already did on a prefix of your prompt, so identical leading tokens are billed at a steep discount instead of being processed again. It splits your input bill into three separate line items rather than one: fresh uncached input, cache writes, and cache reads. Reading those three numbers is the whole discipline.

Two constraints decide whether a breakpoint does anything at all. The first is the minimum cacheable prefix, which is 1024 tokens on the larger Claude models and 2048 on the smallest ones; below the minimum the cache_control marker is ignored and no error is raised, which looks exactly like caching being broken. The second is the time to live: the default entry lives five minutes and every read refreshes that window, so a steady stream of requests keeps a prefix warm indefinitely without paying to write it again. Passing ttl: "1h" extends the window at a higher write price.

Where do I put the cache breakpoint?

Put the breakpoint on the boundary between what never changes per request and what always changes. The provider serializes tools first, then the system prompt, then messages, so anything you want cached must live before anything volatile. A large tool schema is usually the biggest static block in an agent request and is the best first thing to get behind a breakpoint.

const response = await anthropic.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  tools: TOOLS, // serialized first, so it sits inside the cached prefix
  system: [
    { type: "text", text: AGENT_INSTRUCTIONS },
    {
      type: "text",
      text: API_REFERENCE_DOC,
      cache_control: { type: "ephemeral" }, // breakpoint: cache everything above
    },
  ],
  messages: [{ role: "user", content: question }],
});

console.log(response.usage.cache_creation_input_tokens); // non-zero on the cold call
console.log(response.usage.cache_read_input_tokens);     // non-zero on every warm call

For a multi-turn conversation I use two breakpoints rather than one. The first sits at the end of the tools and system region, which never changes for the life of the deployment. The second sits at the end of the last completed turn, so the growing transcript is cached incrementally and each new turn only pays full price for the tokens the user just added.

Why did my cache hit rate drop to zero?

A cache hit requires the prefix to be identical byte for byte, so anything that varies per request destroys every hit from that point onward. My own failure was one interpolated clock reading in the system prompt, added months earlier so the agent could reason about business hours.

Interpolated volatile values. A timestamp, a request id, a user name, or a session id rendered into the system prompt changes the prefix on every call.
Non-deterministic ordering. A tool array built by iterating an object or a Set, or a JSON body serialized with unstable key order, produces a different prefix from identical data.
Model changes. Cache entries are keyed per model, so moving from one model id to another starts cold, and so does an alias that silently points somewhere new.
Middleware that rewrites the request. A proxy or gateway that injects a header-derived block or reorders messages breaks the prefix even though your application code is unchanged.
Trimming a conversation from the front. Dropping the oldest messages to fit a context budget rewrites the start of the prefix and invalidates everything.

// Breaks every hit: the prefix is different on every request
const system = `You are a support agent. Current time: ${new Date().toISOString()}`;

// Fix: keep the system prompt frozen, move volatile facts after the breakpoint
const system = [
  { type: "text", text: STATIC_INSTRUCTIONS, cache_control: { type: "ephemeral" } },
];
const messages = [
  { role: "user", content: `Current time: ${now}\n\n${question}` },
];

When is a one-hour cache TTL worth 2x the write price?

The break-even point is pure arithmetic on the published multipliers, not a benchmark. A five-minute write costs 0.25x more than an uncached request and each hit saves 0.9x, so the first hit inside the window already pays for the write. A one-hour write costs 1x more, so it needs roughly two hits to come out ahead.

Mode	Write price	Read price	Hits to break even	Where I use it
No caching	1x input	n/a	n/a	Prefixes below the model minimum, or genuinely one-shot calls
Five-minute cache	1.25x input	0.1x input	1	Chat turns and agent loops, where a live user keeps traffic flowing
One-hour cache	2x input	0.1x input	2	A long document reused across a work session, or a batch spread over an hour

Concurrency changes the math in one specific way. The entry is created by the request that writes it, so firing ten cold requests in parallel means paying the write price ten times. When I fan out, I send one warm-up call first and start the fan-out after it returns.

How do I measure cache hits instead of guessing?

Log the three input counters on every response and compute a hit rate, because caching fails silently and looks identical to caching that was never enabled. I emit the ratio as a metric and treat a drop after a deploy as expected rather than alarming, since editing a prompt is by definition a cache invalidation.

const {
  input_tokens: fresh,
  cache_creation_input_tokens: written = 0,
  cache_read_input_tokens: read = 0,
} = response.usage;

const hitRate = read / (read + written + fresh);
logger.info({ fresh, written, read, hitRate }, "llm.usage");

Through the Vercel AI SDK the same numbers arrive under provider metadata instead of a top-level usage object. Marking a message with providerOptions.anthropic.cacheControl sets the breakpoint, and providerMetadata.anthropic on the result carries cacheCreationInputTokens and cacheReadInputTokens. If those fields are absent, the request never reached the provider in a cacheable shape.

What does prompt caching not fix, and how do other providers do it?

Caching is an input-side optimization only. It does not change the model output, it does not reduce output token price, and it does not make a badly scoped prompt cheap. The single biggest cost win I found was not the cache at all; it was deleting a stale section of the reference document that no answer had ever cited.

OpenAI applies prompt caching automatically to prompts above roughly 1024 tokens, with no explicit breakpoint to place, and reports cached tokens in the usage payload.
Google Gemini exposes both implicit caching and an explicit context caching API where you create a cached content handle with its own TTL and reference it by name.
Anthropic is the explicit one: you choose the breakpoints, which costs a design decision and buys precise control over what is cached.

The portable lesson survives all three: structure the request static-first, keep the volatile parts last, and verify with the provider's own token counters.

FAQ

Q: Does prompt caching change the model's output?

A: No. Prompt caching reuses the processed prefix and does not alter sampling, so the same prompt and parameters behave the same whether the prefix was read from cache or processed fresh.

Q: Can another organization read my cached prompt?

A: No. Cache entries are scoped to your own organization and keyed on the exact prefix, so there is no cross-organization sharing of cached content.

Q: Does the five-minute TTL reset on every hit?

A: Yes. Each cache read refreshes the five-minute window, so continuous traffic keeps a prefix alive without ever paying the write price again.

Q: Why do I still see cache creation tokens on every request when nothing changed?

A: Something in the prefix is changing, most often an interpolated value or a non-deterministic key order. Hash the serialized prefix of two consecutive requests and diff the two strings; the difference is always visible once you look at the bytes.

Q: Should I cache tool definitions or the system prompt first?

A: Tools, because they are serialized before the system prompt and are usually the largest static block in an agent request. Placing the breakpoint after the system prompt covers the tools as well, since the cached prefix is everything up to the breakpoint.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Why My TypeScript Typecheck Got Slow: Field Notes on tsgo, Project References, and isolatedDeclarations

Ahmed Mahmoud — Tue, 06 Oct 2026 06:36:41 +0000

Headline: A slow tsc --noEmit is almost never caused by the number of files in a repository; it is caused by how much type instantiation the checker has to do, and --extendedDiagnostics tells you which in about ten seconds. The three changes that cut my typecheck time were measuring before guessing, splitting one whole-repo tsconfig.json into project references built with tsc -b, and running the Go-based native port tsgo as a second checker in CI.

Key takeaways

tsc --noEmit --extendedDiagnostics prints Files, Types, Instantiations, Memory used, and a time breakdown across Parse, Bind, Check, and Emit. Read that output before changing any configuration, because the fix for a slow Parse phase and the fix for a slow Check phase have nothing in common.
Instantiations — the count of times the checker materialises a generic type with concrete arguments — predicts checker cost far better than file count. A project with 2,000 files and millions of instantiations checks slower than one with 8,000 files and few.
tsgo is the TypeScript native port: a rewrite of the compiler and language service in Go, distributed as the @typescript/native-preview npm package and intended to ship as TypeScript 7. It is the only item on this list that speeds up checking without changing a line of your code.
Project references — composite: true in each package plus a references array in the consumer, built with tsc -b — turn one whole-repo check into a graph of independently cacheable checks. They pay off only when the dependency graph is genuinely layered.
isolatedDeclarations, added in TypeScript 5.5, requires explicit type annotations on exported values, and in exchange makes a .d.ts file derivable from a single source file. That is the property that lets declaration emit be parallelised or handed to a non-TypeScript tool.

The first symptom was not CI. It was the moment I started alt-tabbing away during npm run typecheck, which is how a build step quietly stops being part of the inner loop. My assumption was the obvious one — the repository had grown, so of course the compiler was slower. That assumption was wrong, and I only found out because I ran the diagnostics flag before touching the configuration.

Where does tsc actually spend its time?

tsc splits its work into four measurable phases — Parse, Bind, Check, and Emit — and in a large application Check almost always dominates. --extendedDiagnostics prints the split alongside the counts that explain it, so it is the first command to run and the only honest starting point.

npx tsc --noEmit --extendedDiagnostics

# if Check dominates, find the specific hot spots
npx tsc --noEmit --generateTrace .trace
npx @typescript/analyze-trace .trace

--generateTrace writes a Chrome-tracing-format file, and the @typescript/analyze-trace package reads it back as a ranked list of the files and type instantiations that cost the most milliseconds. That ranking is usually surprising: in my case a single utility module exporting inferred return types was responsible for a disproportionate share of the check, and nobody would have guessed it from reading the code.

Two configuration flags are worth confirming before any structural work. skipLibCheck: true stops the compiler from type checking the contents of .d.ts files, which on a large node_modules is often the single cheapest win available; your own source is still checked against those declarations. And types: [] in compilerOptions stops TypeScript from automatically including every package under node_modules/@types, which matters once a repository has accumulated a decade of ambient globals nobody imports.

What is tsgo and should I use it now?

tsgo is a port of the TypeScript compiler and language service from TypeScript to Go, announced by the TypeScript team in March 2025 and published as a preview under the @typescript/native-preview package. The plan the team described is that the native port becomes TypeScript 7 while the existing JavaScript implementation continues as TypeScript 6, so both lines exist during the transition. The team's published benchmarks report order-of-magnitude improvements in check time and editor load time on the repositories they measured.

npm i -D @typescript/native-preview
npx tsgo --noEmit        # same flags you already pass to tsc
npx tsgo --version

I do not treat it as a replacement yet, and neither should you while it carries a preview label. What I do instead is cheap and has caught nothing but time savings so far: add a second, non-blocking CI job that runs tsgo --noEmit next to the real tsc --noEmit job, and compare the error output. When the two agree on every pull request for a month, the preview binary has earned the right to become the blocking one.

The honest limits: the preview does not implement every compiler flag or the full public compiler API, so anything that plugs into TypeScript programmatically — custom transformers, ESLint's type-aware rules through @typescript-eslint, codemod tooling built on ts-morph — still runs against the JavaScript compiler. A native-preview VS Code extension exists for the editor side, and the same caveat applies there.

When do project references actually help?

Project references help when the repository is a layered dependency graph, and do nothing when it is a ball of mud. A composite project emits .d.ts files and a .tsbuildinfo fingerprint, and tsc -b walks the reference graph in dependency order and skips any project whose inputs have not changed. If packages/ui imports packages/core and nothing else, editing packages/ui should never re-check packages/core.

// packages/core/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "rootDir": "src",
    "outDir": "dist"
  }
}

// apps/web/tsconfig.json
{
  "compilerOptions": { "noEmit": true },
  "references": [{ "path": "../../packages/core" }]
}

Three details decide whether this is worth the migration. A referenced project must emit — composite: true implies declaration: true — because the consumer type checks against the emitted .d.ts rather than against source, which is precisely where the caching comes from. Set declarationMap: true or every go-to-definition in your editor lands in a generated declaration file instead of the real implementation. And run tsc -b --verbose once after wiring it up: it names each project it skips as up to date, which is the only direct evidence that the cache is working rather than silently rebuilding everything.

The failure case is worth stating plainly. In a monorepo where every package imports every other package, the reference graph has no layers, every change invalidates every project, and you have added configuration complexity for no cache hits. Fix the import graph first, or skip references entirely.

What does isolatedDeclarations buy?

isolatedDeclarations is a TypeScript 5.5 compiler flag that reports an error whenever a declaration file cannot be produced from one source file in isolation — in practice, whenever an exported value's type is inferred from something in another module. Turning it on is a code change, not just a config change, because it forces explicit annotations on your exports.

// tsconfig.json → { "compilerOptions": { "isolatedDeclarations": true, "declaration": true } }

// error TS9007: Declaration emit for this file requires an explicit type annotation.
export function makeClient(url: string) {
  return { url, get: (p: string) => fetch(url + p) };
}

// accepted: the exported shape is written down, not inferred
export interface Client {
  url: string;
  get: (p: string) => Promise<Response>;
}

export function makeClient(url: string): Client {
  return { url, get: (p) => fetch(url + p) };
}

The payoff is that declaration emit stops needing a whole-program type check, so it can be parallelised per file or delegated to a faster non-TypeScript emitter — the Rust-based oxc toolchain implements exactly this, and bundlers built on it expose it as a .d.ts generation mode. The secondary benefit shows up in the consuming project: an exported function with a written return type is a type the checker reads instead of a type it re-derives.

Where I would enable it: packages that publish declarations, and internal workspace packages consumed via project references. Where I would not: an application's leaf feature code, where the annotation burden is real and there is no .d.ts emit to accelerate.

Which type patterns are expensive?

The expensive patterns are the ones that make the checker do work per call site rather than once. Deeply nested conditional types, recursive template literal types, large unions that get distributed across a mapped type, and long inference chains through schema libraries all share that shape: the cost is paid again everywhere the type is used.

// the return type is re-inferred through the schema at every call site
export const parseUser = (raw: unknown) => UserSchema.parse(raw);

// named once, then read rather than re-derived
export type User = z.infer<typeof UserSchema>;
export const parseUser = (raw: unknown): User => UserSchema.parse(raw);

Two smaller habits move the Instantiations number. Prefer interface X extends A, B over type X = A & B for large object types, because interfaces are resolved lazily and cached by name while intersections are recomputed structurally. And annotate the return type of every exported function, which is the same discipline isolatedDeclarations enforces mechanically.

One clarification that saves a lot of confused debugging: a fast CLI check and a slow editor are not a contradiction. The command line runs tsc once over the whole program, while your editor runs tsserver, which maintains an incremental program around the files you have open and answers completion and hover requests against it. If the CLI is quick and typing is laggy, the problem is in the editor's project scope — open the TS Server log from the command palette and check which tsconfig.json it decided your file belongs to.

Which lever should I pull first?

Change	What it does	Reach for it when
`skipLibCheck: true`	Skips type checking inside `.d.ts` files	Almost always; it is the cheapest single flag
`incremental: true`	Reuses the previous run's `.tsbuildinfo`	Local watch loops, and CI only if you cache the file
`tsgo` (native port)	Runs the same check on the Go compiler	You want speed without code changes; run beside `tsc` first
Project references + `tsc -b`	Per-package caching across a layered graph	A monorepo whose packages form a real DAG
`isolatedDeclarations`	Per-file, parallelisable `.d.ts` emit	You publish packages or declaration emit dominates
Explicit return types on exports	Removes repeated inference at call sites	Instantiations is high relative to file count

The lesson I would keep if I lost the rest: the compiler already reports where its time goes, and I spent two afternoons tuning things that were never the bottleneck because I did not ask it. --extendedDiagnostics costs one command. Run it before you migrate anything.

FAQ

Q: Does skipLibCheck: true hide real errors in my own code?

A: No. It only skips type checking inside .d.ts files; your source is still checked against those declarations. The trade-off is that genuinely conflicting types between two libraries will not be reported.

Q: Is tsgo safe to use as the only typecheck in CI today?

A: Not while it ships as @typescript/native-preview. Run it as a second, non-blocking job alongside tsc --noEmit and compare error output over real pull requests before making it authoritative.

Q: Why is my editor slow when the command-line typecheck is fast?

A: The editor runs tsserver with its own incremental program scoped to the tsconfig.json it matched your file to, which may include far more files than you expect. Open the TS Server log from the command palette to see the resolved project and its file count.

Q: Does incremental: true help in CI?

A: Only if the .tsbuildinfo file is cached and restored between runs. On a clean checkout with no restored cache, the flag costs a small amount of write time and saves nothing.

Q: Do project references speed up next build?

A: They speed up the workspace packages the app consumes, not the app's own check. The common arrangement is to set typescript.ignoreBuildErrors in next.config.ts and run a dedicated typecheck job in parallel, so a type error fails CI without serialising the build behind the checker.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

How I Test an LLM Feature: Field Notes on Golden Sets, LLM-as-Judge, and Eval Gates in CI

Ahmed Mahmoud — Sun, 04 Oct 2026 06:00:13 +0000

Headline: An LLM feature cannot be unit-tested with string equality, because the same prompt returns different text on every call, so I assert on properties of the output instead of the output itself. The three changes that made my AI features safe to refactor were a version-controlled golden set of real inputs, deterministic assertions running before any LLM-as-judge call, and a CI gate on pass-rate regression rather than on a perfect score.

Key takeaways

An eval is a test that runs a prompt against fixed inputs and scores the output on properties rather than on exact text. Evals replace toEqual assertions for any code path whose output comes from a model.
A golden set is a version-controlled file of real inputs paired with the properties their outputs must satisfy. Every production bug I fixed in an AI feature became one more row in that file.
Deterministic assertions — Zod schema validation, required substrings, forbidden strings, numeric ranges — catch most regressions, run in milliseconds, and cost nothing. Run them before any judge call.
LLM-as-judge is a second model call that scores the first model's output against a written rubric. A judge is only trustworthy when its model ID is pinned, its rubric asks binary questions, and its verdicts have been compared against human labels.
Gate CI on regression, not perfection: fail the build when the pass rate drops below a baseline committed to the repository, and treat raising that baseline as a reviewed commit.

I did not plan to build an eval harness. I shipped a route that turns a free-text support message into a structured ticket, and it worked. Weeks later a colleague edited the system prompt for an unrelated reason — a wording tweak in the tone instructions — and the extraction started inventing order IDs for messages that contained none. Every test in the repository still passed, because the only tests were for the code around the model. Nothing in CI was looking at what the model said. That is the gap evals fill.

Why can't I unit-test an LLM feature the normal way?

A large language model is a non-deterministic function, so expect(output).toBe('...') fails for reasons unrelated to correctness. Setting temperature: 0 makes output far more stable but does not make it byte-identical: providers batch requests and floating-point accumulation differs between batches, so no major provider guarantees reproducible tokens. Asserting on exact strings produces a suite that is red on Tuesday and green on Wednesday, which teams learn to ignore within a sprint.

The useful move is to split the code at the model boundary. Prompt assembly, retry logic, output parsing, tool dispatch, and every branch that consumes the parsed result are ordinary deterministic functions and deserve ordinary unit tests. Only the single call that crosses into the model needs an eval. Once the seam exists, the eval asserts on properties that are true of any correct answer: does it parse against the schema, does it stay in the requested language, does it cite only identifiers that appear in the input, does it refuse when the context contains no answer, does it never echo the system prompt.

What is a golden set and where do the cases come from?

A golden set is a version-controlled file of real inputs paired with the properties their outputs must satisfy. Mine started at roughly a dozen cases — one per input shape I could name — and grew every time production surprised me. I do not write synthetic cases when real ones exist, because the cases that catch regressions are the awkward real ones: the empty message, the message written in Arabic, the message that is only an order number, the message that is a prompt-injection attempt pasted out of an email.

Two storage rules have paid for themselves. First, keep the fixtures as JSON or JSONL next to the prompt they test, so the case list is reviewable in a pull request. Second, keep the prompt in its own file rather than in a template literal inside a route handler, so a prompt change and its eval results show up in the same diff.

// evals/ticket-extraction.eval.test.ts
import { describe, it, expect } from 'vitest';
import { generateObject } from 'ai';
import { z } from 'zod';
import cases from './fixtures/tickets.json';
import { TICKET_PROMPT } from '../src/prompts/ticket';

const Ticket = z.object({
  category: z.enum(['billing', 'bug', 'feature', 'other']),
  urgency: z.number().int().min(1).max(5),
  summary: z.string().max(200),
  orderIds: z.array(z.string()),
});

describe('ticket extraction', () => {
  for (const c of cases) {
    it.concurrent(c.name, async () => {
      const { object } = await generateObject({
        model: 'anthropic/claude-sonnet-5', // pinned ID, routed via AI Gateway
        schema: Ticket,
        temperature: 0,
        system: TICKET_PROMPT,
        prompt: c.input,
      });

      expect(object.category).toBe(c.expected.category);
      // grounding: never invent an order ID that is not in the message
      for (const id of object.orderIds) expect(c.input).toContain(id);
    });
  }
});

generateObject from the Vercel AI SDK is doing double duty here: it validates the model output against the Zod schema before returning, so a shape regression throws instead of flowing into an assertion. That is the cheapest eval in the file and it is the one that would have caught my invented-order-ID bug.

When should I use a deterministic check instead of LLM-as-judge?

Use a deterministic check whenever the failure can be expressed as a predicate over the string, and reach for a judge only for properties that require reading comprehension. Deterministic checks are free, instant, and never disagree with themselves; a judge is a second model call with its own error rate and its own bill.

Property to check	Method	Why
Output shape and JSON validity	Deterministic (Zod schema)	Schema validation is exact; a judge adds cost and can only be worse.
Grounding: every ID, price, or quote appears in the input	Deterministic (substring or set check)	Hallucinated identifiers are string-detectable, and this is the most damaging class of error.
Forbidden content: prompt leakage, internal URLs, competitor names	Deterministic (regex denylist)	Safety properties must be exact, not probabilistic.
Language, length, and format constraints	Deterministic	Word counts and script ranges are trivially computable.
Did the answer actually address the question?	LLM-as-judge	Requires comprehension; no predicate expresses it.
Is the answer semantically equivalent to a reference?	LLM-as-judge or embedding similarity	Many correct phrasings exist, so exact matching under-reports success.

How do I keep the LLM judge from drifting?

Treat the judge as production code with a version, not as an oracle. Pin the exact model ID — claude-sonnet-5, never a floating alias — because a silent provider-side model change reads as a quality regression in your product. Ask binary questions instead of 1–10 scores: "does the answer state a refund deadline, yes or no" is reproducible, while "rate helpfulness out of ten" drifts and turns your threshold into an arbitrary number. Keep the rubric in a committed file that is reviewed like any other source. And calibrate: hand-label twenty to thirty outputs yourself, run the judge over the same outputs, and look at where the two disagree. A judge you have never compared to a human is a number, not a measurement. Where budget allows, use a different model family for the judge than for the generator, because models tend to rate their own phrasing style favourably.

const Verdict = z.object({
  grounded: z.boolean(),
  answersQuestion: z.boolean(),
  reason: z.string().max(300),
});

export async function judge(question: string, answer: string, context: string) {
  const { object } = await generateObject({
    model: 'anthropic/claude-sonnet-5', // pinned; bump in a reviewed commit
    schema: Verdict,
    temperature: 0,
    system: JUDGE_RUBRIC, // committed file, binary criteria only
    prompt: `<context>${context}</context>\n<question>${question}</question>\n<answer>${answer}</answer>`,
  });
  return object;
}

The reason field is not decoration. When an eval fails at 2am, a one-line explanation from the judge is the difference between a triageable failure and a red square nobody can interpret.

How do I run evals in CI without paying for every pull request?

Run evals in two tiers. Tier one is a fast subset on every pull request: all deterministic checks plus a handful of representative cases, no judge calls. Tier two is the full set with judging, triggered nightly and on any pull request that touches the prompt or fixture directories — that is a paths filter in the workflow, not a human convention. A documentation-only pull request should cost nothing.

Three details keep tier one honest. Model calls are IO-bound, so run cases concurrently with it.concurrent and cap concurrency below the provider rate limit. Give CI its own API key routed through a single gateway, so eval spend is a legible line item instead of a mystery inside the product budget. And expect genuine flakiness: a case that fails once and passes on retry is a signal about output variance, so I retry a failed case once and only fail the build when it fails twice.

# .github/workflows/evals.yml
name: evals
on:
  pull_request:
    paths: ['src/prompts/**', 'evals/**', 'src/lib/ai/**']
  schedule:
    - cron: '0 3 * * *'

jobs:
  full:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '24' }
      - run: npm ci
      - run: npx vitest run evals --maxConcurrency=4
        env:
          AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_EVAL_KEY }}

What pass rate should fail the build?

Gate on regression rather than on a fixed absolute score. A rule of "100% of evals must pass" fails constantly on borderline cases and gets disabled within a month. Instead I commit an evals/baseline.json holding the current pass rate per suite, and CI fails when the measured rate drops below the baseline by more than a small tolerance. Raising the baseline after a genuine improvement is a normal reviewed commit, which makes quality a ratcheting number that lives in git history rather than a claim in a standup.

Two categories are exempt from the statistics. Schema validity and safety checks — prompt leakage, invented identifiers, denylisted content — hard-fail at zero tolerance, because a single occurrence is a bug rather than a sample. Keeping those separate is what lets the fuzzy score stay fuzzy without anyone arguing that a leak is "within tolerance".

I still do not have a perfect measurement of whether the ticket extractor is good. What I have is a file of the ways it has been wrong, a build that goes red when it gets worse in one of those ways, and permission to refactor the prompt without holding my breath. For a non-deterministic feature, that has turned out to be the whole win.

FAQ

Q: Do I need a dedicated eval framework to start?
A: No. Vitest or the built-in node:test runner plus a JSON fixture file covers the first several months. Tools such as Promptfoo, Evalite, and Braintrust become worth adopting once you want dataset management, run-over-run tracing, and a UI for reviewing judge disagreements.

Q: How many cases should a golden set contain?
A: Start with one case per input shape you can name, which is usually ten to twenty, and grow it from production failures. Coverage of distinct failure modes matters far more than the case count.

Q: Does temperature: 0 make model output deterministic?
A: No. It sharply reduces variance but no major provider guarantees byte-identical output, because request batching changes floating-point accumulation. Assert on properties of the output regardless of temperature.

Q: Should the judge model be the same model that generated the answer?
A: Prefer a different model family when budget allows, since models tend to favour their own phrasing style. If you must reuse the same model, calibrate the judge against human labels before trusting its scores.

Q: How do I stop eval costs from growing with the team?
A: Run deterministic checks first and skip judging any case that already failed one, restrict full runs to prompt-touching pull requests and a nightly schedule, and cache model responses keyed by a hash of prompt file, model ID, and input.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Why My Next.js Client Bundle Was Bigger Than I Thought: Barrel Files, optimizePackageImports, and the 'use client' Boundary

Ahmed Mahmoud — Fri, 25 Sep 2026 06:00:08 +0000

Headline: One 'use client' directive pulls that file's entire import graph into the browser bundle, and a barrel index.ts re-exporting two hundred modules is how that graph gets large without anyone noticing. The changes that actually moved my First Load JS were importing modules by their real path instead of through a barrel, enabling experimental.optimizePackageImports, and pushing the 'use client' boundary down to the leaf that needs it.

Key takeaways

A barrel file is an index.ts whose only job is to re-export other modules. Importing one named symbol from a barrel makes the bundler resolve and evaluate every module that barrel names before it can decide what to delete.
'use client' marks a boundary, not a single file. Every module a client component imports, and every module those import in turn, is compiled into the browser bundle.
experimental.optimizePackageImports in next.config.ts rewrites barrel imports into direct module paths at build time. Next.js already applies it to a built-in list including lucide-react and @mui/icons-material.
"sideEffects": false in a package's package.json permits a bundler to delete unused re-exports. A package that ships CSS must use "sideEffects": ["*.css"] instead, or the stylesheet is tree-shaken away.
next build prints a per-route table whose First Load JS column is the JavaScript a visitor downloads for that route, shared chunks included. @next/bundle-analyzer run with ANALYZE=true tells you which module moved it.

I did not go looking for this. I was reading the route table at the end of a next build and noticed that a marketing page with three paragraphs and a signup form carried almost the same First Load JS as the dashboard. Nothing on that page was heavy. The shared chunk was heavy, because one small client component imported { Button } from a first-party barrel that re-exported the entire component library, icons and charts included.

What actually ends up in a Next.js client bundle?

Everything reachable from a 'use client' module ships to the browser, plus the React and Next.js runtime and the RSC payload for the route. Modules imported only by Server Components do not ship. That is the whole model, and it is why boundary placement matters more than any bundler flag.

The failure mode is a component that is 95% static markup with one interactive control, marked 'use client' at the top of the file. The directive is contagious downward: the date library, the icon set, and the validation schema that file imports all become client code, even though only one button needs a click handler.

// app/dashboard/page.tsx — Server Component: these imports never reach the browser
import { buildReport } from '@/lib/report';   // stays on the server
import { Chart } from './chart';              // client leaf, below

export default async function Page() {
  const data = await buildReport();
  return <Chart data={data} />;
}

// app/dashboard/chart.tsx
'use client';
import { LineChart } from 'heavy-charts';     // only this one ships

One detail saves real bytes: TypeScript type imports are erased, but only if the compiler can tell they are types. Writing import type { User } from './models' guarantees erasure. Turning on verbatimModuleSyntax in tsconfig.json, available since TypeScript 5.0, makes the rule explicit — a plain import is emitted as a runtime import even when every binding it names is a type.

Why do barrel files make bundles big and dev servers slow?

A barrel file forces the bundler to resolve every module it re-exports, even when you use one symbol. In a production build the bundler can often tree-shake the unused ones back out; in development it does not bother, which is why a barrel-heavy app compiles slowly on every cold route request even though the shipped bundle looks fine.

Tree shaking is also not guaranteed. It only happens when the bundler can prove a module has no side effects — no top-level code that mutates anything outside itself. A single re-exported module that registers a polyfill, patches a prototype, or imports a stylesheet at the top level pins itself into the output, and any module it imports comes along.

// components/index.ts — the barrel
export * from './button';
export * from './modal';
export * from './data-table';   // ...and 197 more

// a client component
'use client';
import { Button } from '@/components';        // resolves 200 modules
import { Button } from '@/components/button'; // resolves one

For first-party barrels inside an app, the reliable fix is the second line: import the module directly and delete the barrel, or keep the barrel only for the small stable set of things everything uses. An ESLint no-restricted-imports rule that bans @/components as an import source is what stopped the barrel from growing back in my repo.

What does experimental.optimizePackageImports actually do?

experimental.optimizePackageImports rewrites import { X } from 'pkg' into an import of the specific file inside pkg that defines X, at build time, so the bundler never walks the package's barrel. Next.js applies it automatically to a maintained list of common offenders. Packages outside that list, including your own workspace packages in a monorepo, need to be named explicitly.

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

const nextConfig: NextConfig = {
  experimental: {
    optimizePackageImports: ['@acme/ui', 'react-icons', 'lodash-es'],
  },
  serverExternalPackages: ['sharp'],
};

export default nextConfig;

Two limits are worth knowing before you rely on it. It works on package names, so an internal path alias like @/components is not a candidate — that one you fix by deleting the barrel. And it cannot rewrite a namespace import: import * as Icons from 'react-icons/fa' keeps the whole namespace live because any property access on it is only knowable at runtime. The older modularizeImports option still exists for packages whose file layout needs a manual pattern.

How do I measure client bundle size without fooling myself?

Measure a production build and compare First Load JS per route between two builds of the same app. Development bundles are unminified, un-tree-shaken, and carry HMR machinery, so a number read from next dev means nothing about what users download.

npm i -D @next/bundle-analyzer
ANALYZE=true npm run build

@next/bundle-analyzer wraps the Next.js config and writes separate treemap reports for the client, Node.js, and Edge bundles. Open the client report, switch the size metric from parsed to gzipped, and read the largest rectangles — parsed size misleads about what crosses the network. The rule: change one thing per build. Deep imports, a config flag, and a dynamic import landed together will tell you the total moved and nothing about which change earned it.

I am deliberately not quoting my own before-and-after numbers, because a bundle size delta is a fact about one dependency tree and does not transfer to yours.

Which fix should I reach for?

Approach	What it changes	Reach for it when
Direct module import	Bundler resolves one file instead of a whole barrel	The barrel is first-party or the package is not in the optimize list
`optimizePackageImports`	Named barrel imports rewritten to deep paths at build time	A third-party package with a large barrel and many call sites
Move `'use client'` down	The imported subtree stops being client code at all	A mostly-static component was marked client for one handler
`next/dynamic`	Defers bytes to a second request; total stays the same	Code genuinely not needed for first paint or first interaction
Replace the dependency	Removes the bytes outright	The library duplicates a platform API such as `Intl`

When should I use next/dynamic instead of shrinking an import?

Use next/dynamic when the code is genuinely not needed for the first render — a rich text editor, a map, a charting library behind a tab. It does not make an application smaller in total; it moves bytes later, and a chunk fetched at click time is a chunk the user waits on, which shows up as a worse Interaction to Next Paint rather than a worse Largest Contentful Paint.

'use client';
import dynamic from 'next/dynamic';

const Editor = dynamic(() => import('./editor'), {
  ssr: false,
  loading: () => <div className="h-64 animate-pulse rounded bg-muted" />,
});

In the App Router, ssr: false is only allowed inside a Client Component. Calling dynamic() with ssr: false from a Server Component is a build error, because a Server Component has no client render pass to opt out of. Always pass a loading placeholder with the same height as the real component, or the deferred chunk buys you a layout shift.

Does the server bundle size matter too?

It matters for cold starts, not for the network. A serverless function has to be loaded before it runs, and a large dependency graph makes that slower. serverExternalPackages in next.config.ts — the stable name since Next.js 15, previously experimental.serverComponentsExternalPackages — tells Next.js not to bundle a package and to require it natively at runtime instead. Packages like sharp and most database drivers belong there.

The habit I ended up with is smaller than any of these techniques: read the route table on every build, and treat a jump in First Load JS the same way you treat a failing test. The barrel that cost me a shared chunk was added in a one-line pull request that nobody could have reviewed into suspicion. The build output would have flagged it the same day.

FAQ

Q: Does Turbopack tree-shake barrel files automatically, so this stops mattering?

A: A production build removes many unused re-exports regardless of bundler, but tree shaking still cannot remove a module with top-level side effects, and development builds do not tree-shake at all. Deep imports remain the fix that works in both modes.

Q: Is First Load JS the same as the size of the page's JavaScript?

A: No. First Load JS is the route's own chunk plus the shared chunks every route loads, which is why one bad import in a shared component raises the number on pages that never use it.

Q: Should I set "sideEffects": false in my own workspace package?

A: Yes, if no module in it does anything at import time. If any module imports CSS or registers a global, use the array form — for example "sideEffects": ["*.css"] — so the bundler keeps those files and shakes the rest.

Q: Will deleting barrel files break my public package API?

A: It will if consumers import from the package root, so publish an exports map with subpath entries first and keep the root barrel for one deprecation cycle. Inside a private app there is no such contract, and the barrel can go immediately.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Focus Management in the Next.js App Router: Field Notes on the Route Change That Loses Focus, inert, and Native dialog

Ahmed Mahmoud — Thu, 24 Sep 2026 06:00:13 +0000

Headline: The Next.js App Router announces client-side route changes to screen readers through its built-in route announcer, but it never moves keyboard focus. Focus is left on a link that React just unmounted, so the next Tab press restarts at the top of the document — and the fix is a fifteen-line client component plus one tabIndex={-1}.

Key takeaways

Next.js injects a route announcer on every client-side navigation: a visually hidden aria-live region that reads the new document.title, falling back to the page's h1. It handles announcing; it does not handle focus.
A client-side navigation in the Next.js App Router does not reset keyboard focus. When the activated link unmounts, document.activeElement falls back to <body>, so the user's next Tab starts from the top of the page instead of the new content.
The fix is a client component that watches usePathname() from next/navigation and calls .focus({ preventScroll: true }) on a container carrying tabIndex={-1}. tabIndex={-1} makes a non-interactive element focusable by script without adding it to the Tab order.
inert is a global HTML attribute that removes a subtree from the Tab order, the accessibility tree, and pointer hit testing in one declaration. aria-hidden="true" removes it from the accessibility tree only and leaves every control inside it tabbable.
The native <dialog> element traps focus and renders in the browser top layer only when opened imperatively with showModal(). Rendering <dialog open> in JSX produces a non-modal dialog with no focus trap and no backdrop.

I found this the way most people find accessibility bugs: not with an audit tool, but by unplugging my mouse for an afternoon. Navigating my own dashboard with the keyboard alone, every link left me stranded — the page had changed, and Tab took me back to the site logo. Since the European Accessibility Act became applicable on 28 June 2025, that class of bug also stopped being purely a craft question for a lot of the products I work on.

What does the Next.js App Router already do for screen readers on navigation?

It announces the new page title, and that is all it does. Next.js renders a route announcer element into the DOM — a visually hidden region with aria-live — and writes the new page name into it on each client-side navigation. It reads document.title first and falls back to the text of the page's h1. A screen reader user therefore hears that something changed.

Two gaps are left for application code to close. The first is that the announcement is only as good as the title: a title resolved late by generateMetadata in a streamed segment can land after the announcer fires, so what gets read may be the previous page's name. A distinct, statically resolved title per route is the reliable version. The second gap is bigger, and it is focus.

Where should keyboard focus go after a client-side route change?

Focus belongs at the top of the new main content. A full browser navigation does this for free by resetting focus to the start of the document. A client-side navigation does not, because from the browser's point of view nothing navigated — React replaced some nodes. The link the user activated is one of those nodes, so focus falls to <body> and sequential navigation restarts at the top of the page, walking the entire header again on every click.

'use client';
import { useEffect, useRef } from 'react';
import { usePathname } from 'next/navigation';

export function RouteFocus({ children }: { children: React.ReactNode }) {
  const ref = useRef<HTMLDivElement>(null);
  const pathname = usePathname();
  const first = useRef(true);

  useEffect(() => {
    if (first.current) { first.current = false; return; }  // the browser already focused the document on load
    ref.current?.focus({ preventScroll: true });
  }, [pathname]);

  return <div ref={ref} tabIndex={-1}>{children}</div>;
}

Three details in those fifteen lines earn their place. Skipping the first render matters because on initial load the browser has already put focus at the document start, and stealing it again is noise. preventScroll: true matters because Next.js restores scroll position across navigations and an unguarded .focus() call scrolls the container into view and fights that restoration. And tabIndex={-1} is what makes a plain div focusable by script while staying out of the Tab sequence; without it, .focus() silently does nothing.

I wrap the layout's main region rather than the page, so the focus target still exists while a loading.tsx boundary is rendering:

// app/layout.tsx
<a href="#main" className="skip-link">Skip to content</a>
<Nav />
<RouteFocus>
  <main id="main">{children}</main>
</RouteFocus>

The skip link above it solves the other half of the same problem, and it has two requirements: it must be the first focusable element in the DOM, and it must become visible when focused. A skip link pointing at #main only works if the target can receive focus — which is the tabIndex={-1} rule again.

How do I trap focus in a modal without a focus-trap library?

Use the native <dialog> element and open it with showModal(). HTMLDialogElement.showModal() puts the dialog in the browser's top layer, renders the ::backdrop pseudo-element, makes everything outside it inert, and closes on Escape by firing a cancel event. That is most of the feature set focus-trap packages were written to reimplement in JavaScript.

The trap comes from the method call, not from the markup. A <dialog open> rendered declaratively is a non-modal dialog: no top layer, no backdrop, no focus trap. In React that means driving it from an effect rather than from JSX:

'use client';
import { useEffect, useRef } from 'react';

export function Modal({ open, onClose, children }: {
  open: boolean; onClose: () => void; children: React.ReactNode;
}) {
  const ref = useRef<HTMLDialogElement>(null);

  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    if (open && !el.open) el.showModal();   // focus trap + top layer + ::backdrop
    if (!open && el.open) el.close();
  }, [open]);

  return <dialog ref={ref} onCancel={onClose} onClose={onClose}>{children}</dialog>;
}

Two behaviours still need code from me. Initial focus goes to the first focusable descendant, which is usually a close button, so I put autoFocus on the element I actually want. And focus is not restored on close: I capture document.activeElement before calling showModal() and call .focus() on it after close().

Approach	Traps focus	Escape closes it	Top layer
`<dialog>` opened with `showModal()`	Yes, in the browser	Yes, fires `cancel`	Yes, with `::backdrop`
`<dialog open>` written in JSX	No	No	No
`popover` attribute	No, by design	Yes, light dismiss	Yes
`<div role="dialog">`	Only what you write	Only what you write	No, `z-index` only

The popover attribute is the right choice for menus, tooltips and non-blocking panels precisely because it does not trap focus. Reaching for it to build a confirmation dialog is the mistake I now see most often, because both features shipped close enough together to feel interchangeable.

When should I use inert instead of aria-hidden?

Use inert when the user must not reach the content at all, and aria-hidden only when the content is visible but redundant for assistive technology. They are not interchangeable. aria-hidden="true" hides a subtree from the accessibility tree while leaving every button inside it tabbable, which produces the worst available state: focus lands on a control the screen reader will not describe.

inert is a single global HTML attribute that removes a subtree from the Tab order, the accessibility tree, and pointer hit testing at once. React 19 treats it as a real boolean prop, so inert={isDrawerOpen} compiles to the right thing; React 18 expected a string and warned on a boolean.

<div id="app-shell" inert={isDrawerOpen}>
  {/* every control in here is untabbable and invisible to screen readers */}
</div>
<aside role="dialog" aria-modal="true">{drawer}</aside>

inert — background content behind a custom drawer, off-screen carousel slides, a form section that is temporarily unavailable.
aria-hidden — decorative icons sitting next to a visible text label, content duplicated purely for layout.
display: none — removes the element from layout and both trees; the correct default when content is genuinely not present.

With showModal() none of the three is needed: the browser applies inertness to everything outside the top layer itself.

How do I announce async updates like search results or form errors?

Put the live region in the DOM before the content arrives, then change its text. A screen reader announces changes inside a region it was already observing, so mounting <div aria-live="polite">42 results</div> at the same moment the results arrive typically announces nothing at all.

{/* Always mounted. Only the text inside it changes. */}
<p aria-live="polite" className="sr-only">
  {status === 'loading' ? 'Searching' : `${count} results`}
</p>

Pick the politeness level deliberately. role="status" maps to aria-live="polite" and waits for a pause in speech, which is correct for result counts, saved indicators and toasts. role="alert" maps to aria-live="assertive" and interrupts immediately, which is correct only for validation failures and errors the user must handle now.

For form errors I skip the live region when I can. Moving focus to the first invalid input announces the message through that input's own aria-describedby, and it puts the caret where the fix has to happen. A live region tells the user something is wrong; focus tells them where.

How do I keep keyboard accessibility from regressing in CI?

Automated rule engines catch the markup mistakes and none of the focus mistakes. @axe-core/playwright finds missing labels, contrast failures and invalid ARIA, but it cannot tell you that focus went to <body> after a route change, because that state is perfectly valid HTML. Focus needs explicit assertions:

test('route change moves focus to main', async ({ page }) => {
  await page.goto('/');
  await page.getByRole('link', { name: 'Projects' }).click();
  await expect(page.locator('main')).toBeFocused();
});

test('closing a modal returns focus to its trigger', async ({ page }) => {
  const trigger = page.getByRole('button', { name: 'Delete' });
  await trigger.click();
  await page.keyboard.press('Escape');
  await expect(trigger).toBeFocused();
});

Two tests, one per bug class, covering the two bugs keyboard users actually report. I run an axe scan over the main templates in the same suite for the markup half. Neither replaces the afternoon without a mouse — that is still the check that finds what no rule encodes.

FAQ

Q: Does Next.js move focus on a route change automatically?
A: No. The App Router injects a route announcer that reads the new document title into an aria-live region, but it does not change document.activeElement. Moving focus is application code.

Q: Should tabIndex={-1} go on the h1 or on a wrapper element?
A: A wrapper around main is the more robust target, because it survives pages that have no h1 or that stream one in late. Both are announced; the wrapper cannot go missing.

Q: Is inert safe to ship in 2026?
A: Yes. inert is supported in current Chrome, Edge, Safari and Firefox and has been for several release cycles. React 19 accepts it as a boolean prop, while React 18 required a string value.

Q: Do I still need a focus-trap library?
A: Not for modal dialogs, because <dialog> opened with showModal() traps focus in the browser. A library is still useful for non-dialog patterns such as an embedded wizard step that must contain focus without entering the top layer.

Q: Does aria-hidden stop an element from being focusable?
A: No, and that combination is a bug. aria-hidden="true" removes an element from the accessibility tree while leaving it in the Tab order, so a keyboard user can focus a control no screen reader will describe. Use inert instead.

None of this required a dependency. A fifteen-line client component, one HTML attribute, one native element and two Playwright assertions covered every keyboard bug I could find in an afternoon of not touching my mouse. The App Router gives you the announcement for free. The focus is still yours to move.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Zero-Downtime Postgres Migrations: Field Notes on Expand/Contract, lock_timeout, and the ALTER TABLE That Queued Behind One Slow Query

Ahmed Mahmoud — Mon, 21 Sep 2026 06:00:08 +0000

Headline: A Postgres migration usually takes an app down not because the DDL is slow, but because ALTER TABLE waits for an ACCESS EXCLUSIVE lock and every query that arrives after it waits in the same lock queue. Setting a short lock_timeout, splitting every breaking change into expand/backfill/contract deploys, and running migrations as their own pipeline step removes nearly all of that risk.

Key takeaways

Postgres lock requests queue in arrival order. A pending ALTER TABLE blocked by one long-running SELECT blocks every read and write that arrives behind it, which is why an instant DDL statement can still cause minutes of downtime.
lock_timeout caps how long a statement waits to acquire a lock; statement_timeout caps how long it runs after acquiring one. Setting lock_timeout to a few seconds and retrying makes a migration fail fast instead of freezing traffic.
Expand/contract is a three-deploy pattern: add the new schema alongside the old one, backfill and dual-write, then remove the old schema. It exists because a rolling deploy runs the old and new application versions against the same database at the same time.
Since Postgres 11, ADD COLUMN ... NOT NULL DEFAULT <constant> stores the default in the catalog and does not rewrite the table. A volatile default such as gen_random_uuid() still rewrites every row.
CREATE INDEX CONCURRENTLY does not block writes but cannot run inside a transaction block, so it needs its own migration step, and a failed run leaves an INVALID index that must be dropped before retrying.

The migration that taught me this added one nullable column. It was instant in staging. In production it hung, and the API stopped answering. Nothing about the column was slow — everything queued behind it was.

Why did a migration that runs instantly still take the site down?

Because Postgres queues lock requests in arrival order, and a blocked ALTER TABLE blocks everyone behind it. ALTER TABLE needs an ACCESS EXCLUSIVE lock — the strongest lock level in Postgres, which conflicts with every other lock, including the ACCESS SHARE lock that a plain SELECT takes. If any transaction is already holding a conflicting lock on that table, the ALTER TABLE waits. Postgres does not let later, weaker requests jump the queue, so the next SELECT waits behind the ALTER TABLE, and so does every request after it.

That turns a one-millisecond catalog update into an outage whose length equals the runtime of whatever was already holding the table. The usual culprits are the same three every time: a long analytics SELECT, an idle in transaction session that a web request opened and never committed, and autovacuum running in anti-wraparound mode, which does not yield the way ordinary autovacuum does.

To see it live, join pg_stat_activity against pg_blocking_pids():

SELECT pid, state, wait_event_type, pg_blocking_pids(pid) AS blocked_by,
       now() - xact_start AS xact_age, left(query, 120) AS query
FROM pg_stat_activity
WHERE datname = current_database() AND state <> 'idle'
ORDER BY xact_start;

Any row whose blocked_by array is non-empty is waiting. The PID listed inside that array is the transaction you actually need to deal with.

What is the expand/contract migration pattern?

Expand/contract is a three-deploy sequence that keeps the database compatible with both the old and the new version of the application at every moment. It is required for any rolling or serverless deploy, because during the rollout both versions are serving requests against one database.

Renaming users.full_name to users.display_name with ALTER TABLE ... RENAME COLUMN is instant metadata-only work in Postgres. It is also an outage: every old instance still running SELECT full_name starts erroring the moment it commits. The same rename as expand/contract:

Expand. Add display_name text as a nullable column. Deploy code that writes both columns and still reads full_name. The old version keeps working because the new column is optional.
Backfill. Copy existing rows in batches, then flip reads to display_name and deploy. Both columns are now populated.
Contract. Stop writing full_name, deploy, and only then run ALTER TABLE users DROP COLUMN full_name;. Dropping a column is instant but irreversible in practice, so it goes last and alone.

The rule I follow: a deploy may add optional things or remove unused things, never both, and never anything a currently-running instance depends on.

Which Postgres DDL operations are safe, and which rewrite the whole table?

A table rewrite copies every row into new files while holding ACCESS EXCLUSIVE, which on a large table is an outage of unbounded length. This is the cheat sheet I keep next to the migration folder (Postgres 12 and newer):

Statement	Cost	What I do instead
`ADD COLUMN` nullable, or constant `DEFAULT`	Metadata only (PG 11+)	Run it directly
`ADD COLUMN ... DEFAULT gen_random_uuid()`	Full table rewrite	Add nullable, backfill, then set the default
`ALTER COLUMN TYPE varchar(50) -> text`	Metadata only (binary coercible)	Run it directly
`ALTER COLUMN TYPE int -> bigint`	Full table rewrite	New column, backfill, expand/contract swap
`ALTER COLUMN ... SET NOT NULL`	Full scan under ACCESS EXCLUSIVE	Validated `CHECK` constraint first
`ADD CONSTRAINT ... FOREIGN KEY`	Scans and locks both tables	`NOT VALID`, then `VALIDATE CONSTRAINT`
`CREATE INDEX`	Blocks writes for the whole build	`CREATE INDEX CONCURRENTLY`, own step
`DROP COLUMN`	Metadata only, instant	Safe for the DB, breaks old code — contract only
`RENAME COLUMN`	Metadata only, instant	Never in a live deploy — use expand/contract

The NOT VALID trick is the one I reach for most. Adding a foreign key or check constraint normally scans the entire table while holding a strong lock. Splitting it in two moves the scan out from under that lock:

-- Step 1: instant. New writes are checked, existing rows are not scanned.
ALTER TABLE orders
  ADD CONSTRAINT orders_user_fk FOREIGN KEY (user_id) REFERENCES users(id) NOT VALID;

-- Step 2: scans existing rows under SHARE UPDATE EXCLUSIVE, blocking neither reads nor writes.
ALTER TABLE orders VALIDATE CONSTRAINT orders_user_fk;

The same shape makes a column NOT NULL without a blocking scan. Since Postgres 12, SET NOT NULL can use an already-validated CHECK constraint as proof and skip its own scan:

ALTER TABLE users
  ADD CONSTRAINT users_display_name_nn CHECK (display_name IS NOT NULL) NOT VALID;
ALTER TABLE users VALIDATE CONSTRAINT users_display_name_nn;
ALTER TABLE users ALTER COLUMN display_name SET NOT NULL;  -- no scan, uses the validated CHECK
ALTER TABLE users DROP CONSTRAINT users_display_name_nn;

How do I stop a migration from blocking traffic?

Set lock_timeout before the DDL so the migration gives up instead of parking itself at the head of the lock queue. This is the single highest-value line in my migration setup:

SET lock_timeout = '3s';
SET statement_timeout = '30s';

ALTER TABLE users ADD COLUMN display_name text;

With lock_timeout = '3s', a migration that cannot get its lock within three seconds fails with canceling statement due to lock timeout (SQLSTATE 55P03) and releases the queue. Nothing behind it waits longer than three seconds. Failing is fine: the correct response is to retry, and the third or fourth attempt lands in a gap between long queries.

import { sql } from 'drizzle-orm';

async function withLockRetry(run: () => Promise<void>, attempts = 8) {
  for (let i = 0; i < attempts; i++) {
    try {
      await db.execute(sql`SET lock_timeout = '3s'`);
      return await run();
    } catch (err: any) {
      if (err.code !== '55P03' || i === attempts - 1) throw err;
      await new Promise((r) => setTimeout(r, 2 ** i * 500)); // back off, then try again
    }
  }
}

One caveat: CREATE INDEX CONCURRENTLY cannot run inside a transaction block. Most migration runners wrap each file in a single transaction, so a concurrent index needs a step that skips that wrapper. A failed run leaves an INVALID index behind, which DROP INDEX CONCURRENTLY must remove before you retry.

How do I backfill millions of rows without holding one long transaction?

Backfill in bounded batches, each in its own transaction, with a pause between them. A single UPDATE across a large table holds row locks for its entire runtime, bloats the table with dead tuples faster than autovacuum reclaims them, and grows the WAL enough to make a replica fall behind.

-- One batch. Run repeatedly until it reports 0 rows updated.
WITH batch AS (
  SELECT id FROM users
  WHERE display_name IS NULL
  ORDER BY id
  LIMIT 5000
  FOR UPDATE SKIP LOCKED
)
UPDATE users u
SET display_name = u.full_name
FROM batch
WHERE u.id = batch.id;

FOR UPDATE SKIP LOCKED means the backfill steps over rows that live traffic is currently editing instead of waiting for them; the next pass picks them up. I drive the loop from a script rather than a migration file, so it can be paused, resumed, and monitored:

let moved = 0;
for (;;) {
  const res = await db.execute(BACKFILL_BATCH);   // the SQL above
  if (res.rowCount === 0) break;
  moved += res.rowCount;
  console.log(`backfilled ${moved}`);
  await new Promise((r) => setTimeout(r, 200));    // let replicas and autovacuum catch up
}

The right batch size is the one where a single batch stays well under your statement_timeout and replication lag stays flat. I start at 5,000 rows and adjust from the actual lag graph.

Where should migrations run in a CI/CD pipeline?

Migrations belong in a dedicated pipeline step that runs after the build and before the new version receives traffic — never inside next build, never at application boot. Booting into a migration is the failure mode I see most in serverless projects: every cold-started instance migrates concurrently against the same database.

Drizzle Kit and Prisma Migrate both take a Postgres advisory lock so concurrent runners serialize instead of colliding, which prevents corruption but not the deeper problem — the deploy has no clean place to stop if the migration fails. A separate step does:

# .github/workflows/deploy.yml (abridged)
- name: Migrate
  run: pnpm drizzle-kit migrate
  env:
    DATABASE_URL: ${{ secrets.DIRECT_DATABASE_URL }}   # direct connection, not the pooler

- name: Deploy
  run: vercel deploy --prod --prebuilt

Two details there matter. Migrations must use a direct database connection rather than a transaction-mode pooler, because session-level settings such as SET lock_timeout and advisory locks misbehave when every statement can land on a different backend. And migrations are forward-only: expand/contract already guarantees the previous version runs fine against the new schema, which beats a down script nobody has executed against production data.

FAQ

Q: Do I need expand/contract just to add a column?
A: No. A nullable column, or one with a constant default, is backward compatible: the old version ignores it. Expand/contract is only needed when something existing is renamed, dropped, retyped, or made mandatory.

Q: Can I run CREATE INDEX CONCURRENTLY from Drizzle or Prisma migrations?
A: Yes, but only in a migration step that is not wrapped in a transaction, because Postgres rejects CONCURRENTLY inside a transaction block. Keep it in its own file.

Q: What lock_timeout value should I use?
A: A few seconds. Three seconds wins an ordinary lock race, and no queued request notices it. Pair it with retries and exponential backoff, because a lock timeout is an expected outcome, not an error.

Q: How do I find out what blocked a migration after the fact?
A: Query pg_stat_activity with pg_blocking_pids() while it is happening, and enable log_lock_waits so Postgres writes a log line whenever a session waits longer than deadlock_timeout for a lock.

Q: Are down migrations worth writing?
A: Rarely. Once a migration has run against production data, reverting it usually destroys data the forward version created. Expand/contract keeps every intermediate schema compatible with the adjacent application versions, which is what a rollback needs.

None of this is exotic Postgres knowledge. It is four habits: a short lock_timeout, additive-then-subtractive deploys, batched backfills, and migrations as their own pipeline step. I added them after one instant ALTER TABLE cost me an outage, and I have not had a migration-caused incident since.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

npm Supply-Chain Hardening in 2026: Lifecycle Scripts, minimumReleaseAge, and the Postinstall I Stopped Trusting

Ahmed Mahmoud — Mon, 14 Sep 2026 06:00:09 +0000

Headline: The npm attacks that actually landed over the past two years executed at install time, through lifecycle scripts, within hours of the malicious version being published. Turning dependency lifecycle scripts off by default, refusing versions younger than a few days, and removing long-lived publish tokens from CI blocks most of that path without changing a line of application code.

Key takeaways

npm lifecycle scripts (preinstall, install, postinstall, prepare) are shell commands declared inside a dependency's own package.json and executed by your package manager, with your user's permissions, during npm install — before any of your code runs.
pnpm 10 stopped running dependency lifecycle scripts by default; a package that genuinely needs a build step must be listed in onlyBuiltDependencies. npm has no such default, so I set ignore-scripts=true in .npmrc and allow-list explicitly.
minimumReleaseAge is a cooldown setting — in pnpm, in Renovate, and as Dependabot's cooldown config — that refuses any version published less than N minutes ago. Compromised versions are usually detected and pulled within hours to a few days, so a cooldown absorbs exactly the window in which you would have installed one.
npm provenance attestations prove which repository, commit, and CI workflow produced a tarball. They do not prove the code is benign: a compromised workflow emits perfectly valid provenance.
Trusted publishing over OIDC removes the long-lived npm token from CI. That token is the credential the self-replicating npm worm of 2025 harvested from postinstall scripts in order to publish itself into the maintainer's other packages.

What actually runs on my machine when I type npm install?

npm install executes arbitrary code from your dependency tree before any of your own code runs. A lifecycle script is a command declared in a package's scripts field that the package manager invokes automatically at install time — it inherits your shell environment, your ~/.npmrc, your SSH keys, and whatever cloud credentials sit on disk. There is no sandbox around it by default.

The part I under-weighted for years is that this applies to the whole transitive tree, not just the dependencies I chose. Five direct dependencies routinely resolve to several hundred packages, and any one of them can declare a postinstall.

The first useful step is knowing how many packages in your tree claim that right:

# every package in the installed tree that declares an install-time script
npm query ":attr(scripts, [postinstall])" | jq -r '.[].name'

On pnpm 10 the equivalent is pnpm approve-builds, which lists the packages whose build scripts were blocked and asks which ones to permit. The first time I ran either command on a mature repo, the list was shorter than I feared and less legitimate than I hoped — a handful of native modules that really do compile, and several pure-JavaScript packages running analytics pings.

How do I stop dependency lifecycle scripts from running?

Set ignore-scripts=true in the project's .npmrc for npm and Yarn, or stay on pnpm 10's default of not running dependency scripts, then allow-list the few packages that genuinely need a build step.

# .npmrc — checked into the repo, applies to every install here
ignore-scripts=true

The honest cost: npm's ignore-scripts is not selective. It also disables your own package's scripts, so a repo relying on prepare to install Husky hooks will silently stop doing that. I move those into an explicit npm run setup step that the README and the CI job both call, and run npm rebuild sharp better-sqlite3 for native modules that need compilation.

pnpm's version is narrower and better, because the allow-list is per package rather than all-or-nothing:

{
  "pnpm": {
    "onlyBuiltDependencies": ["esbuild", "sharp", "better-sqlite3"]
  }
}

The heuristic for that list: native addons and binary downloaders (esbuild, playwright) have a real reason to run at install. A pure-JavaScript utility asking for a postinstall does not, and that request is itself the signal.

What is minimumReleaseAge, and why does a release cooldown stop worm-style attacks?

minimumReleaseAge is a package-manager setting that refuses to install any version published more recently than a given number of minutes. pnpm reads it from pnpm-workspace.yaml, Renovate has supported it as a config option for years, and Dependabot exposes the same idea as a cooldown block in dependabot.yml.

# pnpm-workspace.yaml
minimumReleaseAge: 4320          # minutes; 3 days
minimumReleaseAgeExclude:
  - "@my-scope/*"                # our own packages publish and deploy same-day

// renovate.json
{
  "minimumReleaseAge": "3 days",
  "internalChecksFilter": "strict"
}

A cooldown is disproportionately effective because a malicious npm version has a short shelf life. Registry maintainers, scanners, and other developers find these within hours to a couple of days, and the version gets unpublished or deprecated. The cooldown does not make you smarter than the attacker; it makes you later than the people who find them, which is the same outcome for a fraction of the effort.

The trade-off is real: you are deliberately three days behind on everything, including genuine security patches. I keep a documented override — a one-line config exclusion plus a PR that says why — so consciously pulling a same-day CVE fix stays possible and stays visible.

Does npm provenance prove a package is safe?

No. npm provenance is a signed attestation, generated by npm publish --provenance running in a supported CI provider, that links a published tarball to the source repository, commit, and workflow that built it. It proves origin, not intent.

# verify registry signatures and attestations for the installed tree
npm audit signatures

What provenance buys me: a stolen laptop token can no longer publish a tarball that claims to come from our repo and carries a valid attestation, and I can diff a published artifact against the commit it names. What it does not cover: a maintainer who merges a malicious commit, a compromised build workflow, or the several hundred transitive packages that publish no attestation at all.

The complementary control is trusted publishing, where npm exchanges a short-lived OIDC token from the CI run instead of reading a long-lived secret. Token theft is what turned the 2025 npm worm from an incident into a spreading one: its postinstall payload scraped credentials and used them to publish itself into whatever else that maintainer owned. A publish flow with no long-lived token in the environment has nothing to scrape.

What should CI change to reduce the blast radius of a bad install?

Assume one install will eventually execute hostile code, and make that install a boring target.

Use npm ci, never npm install, in CI. npm ci installs strictly from package-lock.json and fails when the lockfile and package.json disagree, removing silent transitive drift between the version a human reviewed and the version CI resolved.

Pin GitHub Actions to a full commit SHA, not a tag. Git tags are mutable, and the 2025 tj-actions/changed-files compromise worked by repointing existing tags at a malicious commit, so everyone pinned to @v4 picked it up automatically.

- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

Keep secrets out of the job that installs dependencies. The install step needs no publish token, no cloud key, no deploy credential. Splitting install/build from publish/deploy into separate jobs, with permissions: contents: read on the first, means an install-time payload runs in a job holding nothing worth stealing.

Commit the lockfile and review its diff. The integrity hash pins bytes, so the lockfile diff is the one place a surprise transitive bump is actually visible to a reviewer.

Which hardening step buys the most safety per unit of pain?

Control	What it stops	What it costs
`ignore-scripts` / `onlyBuiltDependencies`	Install-time code execution from any package in the tree	Native modules break until allow-listed; npm's flag also disables your own scripts
`minimumReleaseAge` cooldown	Freshly published compromised versions, the dominant attack shape	You run N days behind on everything, security patches included
`npm ci` + committed lockfile	Unreviewed transitive drift between review and deploy	Effectively none
Actions pinned to commit SHA	Mutable-tag hijack of your CI pipeline	Bump churn; let Renovate update the SHAs
Trusted publishing (OIDC)	Token theft, and therefore worm-style self-replication	One-time setup; publishing must happen from CI
Provenance + `npm audit signatures`	Tarballs not built from the source they claim	Does not stop malicious source; ecosystem coverage is partial

If I could ship only one of these to a team tomorrow, it would be the cooldown: no allow-list maintenance, no developer behaviour change. Disabling lifecycle scripts is strictly stronger but has a first-week cost while you discover which packages actually needed them.

FAQ

Q: Will ignore-scripts=true break my project?

A: It can, because npm's ignore-scripts also disables your own package's lifecycle scripts such as prepare, which is how Husky installs git hooks. Move those into an explicit npm run setup step and run npm rebuild <package> for native modules that need compiling.

Q: Does pnpm block install scripts by default?

A: Yes. pnpm 10 does not run dependency lifecycle scripts unless the package is listed in onlyBuiltDependencies, and pnpm approve-builds shows which packages were blocked so you can permit them individually.

Q: How long should a release-age cooldown be?

A: Three to seven days covers the detection window for most publicly disclosed npm compromises. Keep a documented override path so an urgent security patch can still be pulled the same day.

Q: Isn't npm audit already covering this?

A: No. npm audit reports known CVEs from published advisories, and a malicious version has no advisory at the moment you would install it. npm audit signatures is a different check that verifies registry signatures and provenance attestations; the two are complementary.

Q: Does the lockfile's integrity hash protect me from a malicious package?

A: The integrity field is a subresource hash guaranteeing you received the same bytes as when the lockfile was written. It protects against tampering between the registry and you; it says nothing about whether those bytes were malicious when published.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Hybrid Search in Postgres with pgvector: Field Notes on HNSW, tsvector, and Why Pure Vector Search Missed Exact Matches

Ahmed Mahmoud — Sun, 06 Sep 2026 15:27:33 +0000

Headline: pgvector is a Postgres extension that adds vector column types and approximate-nearest-neighbour indexes, and used alone it is a mediocre search engine. Every retrieval bug I shipped in a RAG feature was fixed by fusing pgvector similarity with Postgres full-text search through Reciprocal Rank Fusion — not by buying a vector database and not by swapping the embedding model.

My first retrieval pipeline was one ORDER BY embedding <=> $1 LIMIT 5 and a prompt. It demoed well, then failed on the queries people actually type: exact error codes, function names, invoice numbers, product SKUs. Cosine similarity is perfectly happy to return five paragraphs that are about billing when the user typed a literal invoice ID that appears verbatim in exactly one row.

These are the notes from moving that pipeline to hybrid search on Postgres 17 with pgvector 0.8, kept in the same database as the application data.

Key takeaways

pgvector 0.8.0 adds four vector types (vector, halfvec, bit, sparsevec) and two ANN index types (HNSW and IVFFlat) to Postgres. It does not add keyword matching, reranking, or chunking.
Pure vector search fails on exact identifiers. An embedding encodes meaning, so a literal token like ERR_MODULE_NOT_FOUND holds no privileged position in the vector space, while Postgres full-text search matches it exactly.
Reciprocal Rank Fusion combines both retrieval arms without normalising scores. RRF scores each row as the sum of 1 / (k + rank) across arms, with k = 60 as the common default.
HNSW is the default index and IVFFlat is the exception. HNSW builds on an empty table; IVFFlat must be created after the table holds representative rows.
A WHERE clause on an HNSW query can return fewer rows than the LIMIT asks for. The hnsw.iterative_scan setting added in pgvector 0.8.0 is the fix.

What does pgvector actually add to Postgres?

pgvector is a Postgres extension that adds vector column types, distance operators, and approximate-nearest-neighbour indexes to an ordinary Postgres database. You enable it with CREATE EXTENSION vector; and you get four storage types: vector (4-byte floats), halfvec (2-byte floats, added in pgvector 0.7.0), bit (binary quantisation), and sparsevec.

The distance operators are worth memorising, because choosing the wrong one silently degrades ranking instead of throwing: <=> is cosine distance, <-> is L2 distance, <#> is negative inner product, and <+> is L1 distance. OpenAI's text-embedding-3-small and most hosted models return normalised vectors, so I use <=> with a vector_cosine_ops index and stop thinking about it.

The index operator class must match the query operator. An HNSW index built with vector_l2_ops is simply not used by a query ordering on <=>, and Postgres falls back to a sequential scan without complaining. My first "pgvector is slow" investigation was exactly that mismatch, visible in one EXPLAIN ANALYZE.

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE chunks (
  id          bigserial PRIMARY KEY,
  document_id bigint NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
  body        text NOT NULL,
  embedding   vector(1536) NOT NULL,
  tsv         tsvector GENERATED ALWAYS AS (to_tsvector('english', body)) STORED
);

CREATE INDEX chunks_embedding_hnsw
  ON chunks USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);

CREATE INDEX chunks_tsv_gin ON chunks USING gin (tsv);

What pgvector does not give you: tokenisation, keyword matching, reranking, chunking, or query rewriting. It is a similarity index, not a search product.

Why did pure vector search miss exact matches?

Pure vector search misses exact matches because an embedding encodes meaning rather than literal tokens. When a support agent searches for ERR_MODULE_NOT_FOUND, the embedding of that string lands near "module", "import", and "error" in general — near enough to rank a generic troubleshooting page above the one paragraph containing the code verbatim.

Three query shapes broke consistently for me: exact error codes, product SKUs and order numbers, and rare proper nouns such as a customer's company name. All three share a property: the useful signal is a low-frequency token, and averaging it into a 1536-dimension chunk embedding dilutes it into noise.

Chunk size makes it worse. A 1,500-token chunk produces one vector representing the average of everything in it, so a single decisive sentence barely moves the vector. Cutting chunks to roughly 200–400 tokens with a small overlap improved my retrieval more than any embedding-model change I tried.

Postgres full-text search has the opposite failure mode. websearch_to_tsquery('english', 'how do I stop being billed') will not match a document titled "Subscription termination", because no shared stem exists. That complementary failure is the entire argument for hybrid search.

How do I combine full-text and vector search in one SQL query?

Run both searches as separate CTEs, rank each independently, then fuse the ranks with Reciprocal Rank Fusion in a single query. RRF ignores raw scores and uses only position, which is why it needs no tuning: cosine distance lives on roughly 0 to 2, while ts_rank_cd is unbounded, and weighting them directly turns into a magic-constant hunt.

Reciprocal Rank Fusion assigns each row a score of 1 / (k + rank) in every arm it appears in, then sums those scores. k = 60 is the value from the original RRF paper and the one I have never needed to change.

WITH semantic AS (
  SELECT id, RANK() OVER (ORDER BY embedding <=> $1::vector) AS rank
  FROM chunks
  ORDER BY embedding <=> $1::vector
  LIMIT 50
),
keyword AS (
  SELECT c.id, RANK() OVER (ORDER BY ts_rank_cd(c.tsv, q) DESC) AS rank
  FROM chunks c, websearch_to_tsquery('english', $2) q
  WHERE c.tsv @@ q
  ORDER BY ts_rank_cd(c.tsv, q) DESC
  LIMIT 50
)
SELECT c.id, c.body,
       COALESCE(1.0 / (60 + s.rank), 0.0)
     + COALESCE(1.0 / (60 + k.rank), 0.0) AS score
FROM chunks c
LEFT JOIN semantic s ON s.id = c.id
LEFT JOIN keyword  k ON k.id = c.id
WHERE s.id IS NOT NULL OR k.id IS NOT NULL
ORDER BY score DESC
LIMIT 10;

Two details matter. The LEFT JOIN plus COALESCE pattern lets a row win by being strong in one arm alone — that is how the exact SKU match survives even though its embedding ranks nowhere. And websearch_to_tsquery is the right parser for user input: it accepts quoted phrases and -exclusions and never throws a syntax error on hostile input the way to_tsquery does.

I retrieve 50 per arm and return 10. Retrieving 5 per arm produces two disjoint lists and fusion has nothing to fuse.

HNSW or IVFFlat: which pgvector index should I build?

Build HNSW unless index build time or memory is the binding constraint.

Property	HNSW	IVFFlat
Build on empty table	Yes	No — needs representative rows
Build parameters	`m`, `ef_construction`	`lists`
Query-time knob	`hnsw.ef_search` (default 40)	`ivfflat.probes` (default 1)
Build time	Slower	Faster
Index size / memory	Larger	Smaller
Recall per unit latency	Better	Lower at equal latency
Heavy inserts	Handled incrementally	Degrades; needs rebuilds

The knob that actually changes results is hnsw.ef_search, which controls how many candidates the graph traversal keeps. Set it per transaction so a background reindexing job and a user-facing query can use different values.

BEGIN;
SET LOCAL hnsw.ef_search = 100;
-- hybrid query here
COMMIT;

Why does adding a WHERE filter return fewer rows than my LIMIT?

An HNSW query with a WHERE clause can return fewer rows than the LIMIT requests because the index traversal collects ef_search candidates first and the filter is applied afterwards. Ask for 10 chunks belonging to one tenant that owns 0.1% of the table, and most of the 40 default candidates get discarded.

This bit me on a multi-tenant knowledge base, and it is the worst class of bug: no error, no slow query, just quietly thinner context arriving at the model.

Enable iterative scans. pgvector 0.8.0 added hnsw.iterative_scan, which keeps scanning until enough rows survive the filter. Use relaxed_order for throughput, strict_order when exact distance order matters, and cap work with hnsw.max_scan_tuples.
Use a partial index when the filter is a small fixed set of values, e.g. WHERE deleted_at IS NULL.
Raise ef_search as a blunt instrument when the filter is mildly selective.

SET LOCAL hnsw.iterative_scan = 'relaxed_order';
SET LOCAL hnsw.max_scan_tuples = 20000;

What broke in production?

The dimension mismatch is the first error everyone meets: ERROR: expected 1536 dimensions, not 768. A vector(1536) column is a hard constraint, so switching embedding models is a migration, not a config change. Embeddings from different models are not comparable at all — a model swap means a new column, a full backfill, and a cutover, never a partially re-embedded table.

The 2000-dimension index limit surprised me more. pgvector indexes vector columns up to 2,000 dimensions, so text-embedding-3-large at 3,072 dimensions cannot be indexed as a plain vector. Two honest options: store it as halfvec(3072) and index with halfvec_cosine_ops, which pgvector indexes up to 4,000 dimensions and which also halves storage; or request fewer dimensions from the API using the dimensions parameter.

Index builds were slower than expected on a few hundred thousand rows, because the default maintenance_work_mem is far too small for a graph index. Raising maintenance_work_mem and max_parallel_maintenance_workers turned an overnight build into a deploy-window build.

Row width is the quiet one. A vector(1536) value occupies roughly 6 KB, well past the point where Postgres moves the column out of line into TOAST storage, so every row fetch becomes an extra read. Keeping the chunk table narrow and joining to document metadata was worth more than any query rewrite.

Finally, the latency I chased in SQL was not in SQL. Embedding the user's query is a network round trip on every search, and it dominated my P95 long before Postgres did.

FAQ

Q: Do I need a dedicated vector database instead of pgvector?

A: Not for application-scale retrieval in the low millions of chunks. Keeping vectors in Postgres means one backup story, one connection pool, transactional consistency between documents and embeddings, and the ability to join retrieval results against permissions in the same query.

Q: Which distance operator should I use with OpenAI embeddings?

A: Cosine distance, the <=> operator, with an HNSW index created using vector_cosine_ops. The operator class must match the ORDER BY operator or Postgres silently falls back to a sequential scan.

Q: Does hybrid search require two embeddings per chunk?

A: No. It needs one vector column for semantic similarity and one tsvector column for lexical matching. Write the tsvector as a GENERATED ALWAYS AS ... STORED column so it can never drift from the body text.

Q: How many results should I retrieve before passing them to the model?

A: Around 50 candidates per arm, fused with RRF, then the top 5 to 10 fused chunks to the model. Feeding more usually lowers answer quality, because irrelevant context competes with relevant context inside the prompt.

Q: Should I add a reranking step on top of hybrid search?

A: Only after hybrid search is in place and you can measure that the right chunk is retrieved but ranked too low. Reranking cannot recover a chunk that retrieval never returned, so fixing recall first is the higher-leverage move.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Web Workers in the Next.js App Router: Field Notes on import.meta.url, DataCloneError, and What a Worker Cannot Fix

Ahmed Mahmoud — Sat, 05 Sep 2026 06:00:11 +0000

Headline: A Web Worker is a background JavaScript thread with no DOM access, and it only improves responsiveness when the bottleneck is your own CPU-bound code — not React rendering. I moved three features off the main thread in a Next.js App Router app, and every bug I hit came from serialization, bundler paths, or React StrictMode spawning a second worker I never terminated.

I had a client-side CSV importer that froze the tab for several seconds on large files. My first instinct was to memoize harder. That was wrong: the freeze was one long task inside my own parsing code, and no amount of useMemo moves work off the thread it already runs on. A Web Worker does.

A Web Worker is a separate JavaScript thread the browser runs alongside the main thread, with its own global scope, no DOM access, and communication only through message passing. I have since moved three features into workers in a Next.js 16 App Router app — CSV parsing, client-side image resizing, and a fuzzy search index. These are the notes I wish I had on day one.

Key takeaways

A Web Worker only helps when the long task is your own CPU-bound JavaScript. If the browser's Performance panel attributes the long task to React rendering, commit, or style recalculation, a worker moves nothing, because rendering must stay on the main thread.
Always construct workers with new Worker(new URL('./parse.worker.ts', import.meta.url)). Both webpack 5 and Turbopack detect that exact expression and emit the worker as its own hashed chunk; a plain string path resolves to a 404 in a production build.
postMessage serializes with the structured clone algorithm, which drops functions, class prototypes, DOM nodes, and getters. Sending any of those throws DataCloneError, and sending a class instance silently produces a plain object with no methods on the other side.
Comlink turns postMessage into awaited method calls using a JavaScript Proxy, so the worker exposes an object and the page calls await api.parse(file). It costs roughly 1 KB gzipped and removes all request-ID bookkeeping.
React StrictMode runs effects twice in development, so an uncleaned worker leaks a second thread. Return () => worker.terminate() from the effect; without it a hot-reloading page accumulates workers until the tab is slower than before.

What does a Web Worker actually fix, and what does it not?

A Web Worker fixes main-thread blocking caused by long-running synchronous JavaScript that does not touch the DOM. Parsing, compressing, diffing, hashing, tokenizing, building a search index, decoding a large payload, and running a WebAssembly module all move cleanly.

A Web Worker does not fix slow React rendering. React's reconciliation and commit phases must run on the main thread because they write to the DOM. If an Interaction to Next Paint (INP) regression comes from rendering a 5,000-row table, the fix is virtualization or fewer components, not a worker. I wasted an afternoon before I accepted that.

The distinction is visible in a Performance trace: expand the long task and read the flame chart. If the widest frames carry your own function names, a worker will help. If they are React internals or Recalculate Style, it will not.

Workers also have no access to window, document, or localStorage. They do get fetch, IndexedDB, WebAssembly, crypto.subtle, OffscreenCanvas, and timers. The rough rule I use now: if the code would run unchanged in Node.js, it will run in a worker.

How do I create a Web Worker in the Next.js App Router?

Create the worker inside a useEffect in a Client Component, using new URL(..., import.meta.url), and terminate it in the cleanup function. The Worker constructor does not exist in Node.js, so constructing one during server rendering or at module scope throws ReferenceError: Worker is not defined at build time.

'use client';

import { useEffect, useRef } from 'react';

export function CsvImporter() {
  const workerRef = useRef<Worker | null>(null);

  useEffect(() => {
    const worker = new Worker(
      new URL('../workers/parse.worker.ts', import.meta.url),
      { type: 'module' }
    );
    worker.onmessage = (e: MessageEvent<{ rows: number }>) => {
      console.log('parsed', e.data.rows);
    };
    workerRef.current = worker;
    return () => worker.terminate();
  }, []);

  // ...
}

Three details matter. The new URL('./x.worker.ts', import.meta.url) expression must appear literally inside the Worker constructor — hoisting it into a variable defeats the bundler's static analysis and the file is never emitted. The { type: 'module' } option is what lets the worker use import statements. And the worker file belongs outside app/ — I keep mine in src/workers/ — so the router never tries to interpret it as a route.

The worker file itself is an ordinary module that listens on its own global scope:

// src/workers/parse.worker.ts
self.onmessage = (e: MessageEvent<{ text: string }>) => {
  const rows = e.data.text.split('\n').length;
  self.postMessage({ rows });
};

export {};

The trailing export {} is not decorative. It makes the file a module so TypeScript scopes self to the worker context instead of colliding with the DOM lib's global declarations.

Why does my worker throw DataCloneError?

postMessage serializes its argument with the structured clone algorithm, which copies plain data but refuses functions, Symbols, DOM nodes, and anything holding a closure. Passing one of those throws DataCloneError: Failed to execute 'postMessage'.

The quieter failure is class instances. Structured clone copies own enumerable properties and discards the prototype, so a Decimal or a parser instance arrives as a plain object with no methods, and the first method call blows up far from the postMessage line that caused it. I now send only JSON-shaped data across the boundary and rehydrate on the receiving side.

Transferable objects are the escape hatch for large payloads. An ArrayBuffer, MessagePort, ImageBitmap, OffscreenCanvas, or ReadableStream can be transferred instead of copied, which hands ownership to the other thread in constant time and leaves the original detached:

const buffer = await file.arrayBuffer();
worker.postMessage({ buffer }, [buffer]);
// buffer.byteLength is now 0 on this thread — ownership moved

Forgetting that second argument is the difference between moving a pointer and copying every byte. For the image-resize worker this was the single change that made the interaction feel instant, because a multi-megabyte copy was happening on the main thread before the worker ever started.

When should I use Comlink instead of raw postMessage?

Comlink is a roughly 1 KB library from the Chrome team that wraps postMessage in a JavaScript Proxy so the worker looks like an awaitable object. Reach for it as soon as the worker has more than one operation, because hand-rolled routing means inventing request IDs, a pending-promise map, and a discriminated union of message types — then maintaining all three.

// src/workers/search.worker.ts
import * as Comlink from 'comlink';

const api = {
  async buildIndex(docs: Doc[]) { /* ... */ },
  async query(term: string) { return search(term); },
};

export type SearchApi = typeof api;
Comlink.expose(api);

import * as Comlink from 'comlink';
import type { SearchApi } from '../workers/search.worker';

const worker = new Worker(
  new URL('../workers/search.worker.ts', import.meta.url),
  { type: 'module' }
);
const api = Comlink.wrap<SearchApi>(worker);
const results = await api.query('next.js');

Two Comlink rules I learned by breaking them. Callbacks must be wrapped as Comlink.proxy(cb), because a bare function cannot be cloned. And transferables need Comlink.transfer(value, [buffer]) — Comlink will not infer a transfer list, so the zero-copy win silently disappears if you skip it.

Use import type for SearchApi so the worker module is never pulled into the main bundle, while the main thread still gets full autocomplete with every return type wrapped in a Promise.

Should I use a Web Worker or scheduler.yield()?

Use scheduler.yield() when the work must touch the DOM or is only moderately long; use a Web Worker when the work is pure computation measured in hundreds of milliseconds. scheduler.yield() is a Scheduling API method that returns a Promise and lets the browser service pending input before the same function continues — it splits one long task into several short ones on the same thread rather than moving the work.

for (const [i, item] of items.entries()) {
  render(item); // touches the DOM, must stay on the main thread
  if (i % 50 === 0) await scheduler.yield();
}

Aspect	Web Worker	scheduler.yield()
Thread	Separate thread; main thread stays free	Same thread; task split into chunks
DOM access	None	Full
Setup cost	Spawn a thread and parse a second bundle	One `await`
Data cost	Structured clone unless transferred	Zero — same memory
Best for	Parsing, hashing, indexing, WebAssembly	Long loops that build or mutate UI

The setup cost is real: spawning a worker means the browser creates a thread and parses a second bundle. For work measured in a couple of milliseconds, the round trip is pure overhead. I only move something into a worker once I can see it as a long task — over 50 ms — in a trace.

What broke for me the first time?

StrictMode spawned two workers. React StrictMode mounts, unmounts, and remounts every component in development. My effect created a worker and returned nothing, so each hot reload left an orphaned thread holding its index in memory. Returning () => worker.terminate() fixed it, and it is also the correct production behavior when a user navigates away mid-parse.

A hoisted URL produced a 404 in production. Development worked; the deployed build requested a worker path that did not exist and got an HTML error page back. The cause was refactoring new URL(...) into a shared constant, which defeats the bundler's static detection. Keep the expression inline inside the constructor.

Errors vanished. An exception thrown inside a raw worker does not reject anything on the main thread; it fires an error event on the worker object. I now always attach worker.onerror, and with Comlink I wrap calls in try/catch — remembering that only the message and stack survive the boundary, so a custom error class arrives as a generic object unless you register a Comlink.transferHandlers entry.

SharedArrayBuffer was not an option. Sharing memory between threads without copying requires cross-origin isolation: Cross-Origin-Opener-Policy: same-origin plus Cross-Origin-Embedder-Policy: require-corp. Those headers broke embedded third-party widgets on the same page, so I stayed with transferables. If your app embeds anything cross-origin, budget real time before assuming SharedArrayBuffer is available.

One worker was enough. I built a pool sized by navigator.hardwareConcurrency before measuring, then found a single worker already removed every long task from the trace. A pool is worth it when you have genuinely parallel independent chunks; it is not a default.

FAQ

Q: Do Web Workers work with Server Components in the Next.js App Router?
A: Not directly. Worker is a browser API, so the file that constructs it needs the 'use client' directive, and construction must happen inside useEffect or an event handler so it never runs during server rendering. A Server Component can freely render the Client Component that owns the worker.

Q: Does moving work to a Web Worker improve INP?
A: Only when the interaction is blocked by CPU-bound JavaScript you control. Interaction to Next Paint measures the delay from an interaction to the next frame, so moving a 400 ms parse off the main thread helps directly, while a slow React commit is unaffected because rendering cannot leave the main thread.

Q: Does Turbopack support new Worker(new URL(...))?
A: Yes. Turbopack, the default bundler for next dev and next build in Next.js 16, detects the new URL('./file', import.meta.url) pattern inside a Worker constructor and emits the worker as its own chunk, the same way webpack 5 does.

Q: What is the difference between a Web Worker and a Service Worker?
A: A Web Worker is a background compute thread owned by one page and terminated with it. A Service Worker is a network proxy between the page and the network that persists across page loads and powers offline caching and push notifications; it is not a place to run heavy computation for the current page.

Q: Can I share state between the main thread and a worker without copying?
A: Yes, with SharedArrayBuffer, but the page must be cross-origin isolated via COOP and COEP response headers. Without those headers, use transferable objects, which move ownership of an ArrayBuffer in constant time instead of sharing it.

Closing

The mental model that finally made workers easy: a worker is a tiny server that happens to run in the same tab. You send it a request, it answers with data, and everything crossing the gap must survive serialization. Once I stopped sending rich objects across the boundary and started sending buffers and plain JSON, the confusing failures went away.

The discipline is measurement first. Open a trace, find the long task, read the flame chart, and only then reach for a thread. Web Workers fix one specific problem very well, and they add real complexity to everything else.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.

Turborepo in a Real Monorepo: Field Notes on Cache Misses, NEXT_PUBLIC Poisoning, and the tasks Key That Replaced pipeline

Ahmed Mahmoud — Thu, 03 Sep 2026 06:00:08 +0000

Headline: Turborepo is a task runner that hashes each script's inputs, caches its outputs, and replays them instead of re-running the work. The cache is only as correct as the inputs, outputs, and env you declare in turbo.json — every wrong answer I got out of it was a declaration I never wrote.

I moved a two-app, six-package monorepo onto Turborepo 2 this year: a Next.js front end, a NestJS API, and shared UI, config, and type packages. The first week felt like a straight win, because CI stopped rebuilding packages nobody had touched. The second week I shipped a production build that was still pointing at the staging API, and the deploy log said cache hit, replaying logs. These are the notes I wish I had before that deploy.

Key takeaways

Turborepo is a memoization layer over package.json scripts. It does not install dependencies, link workspaces, or compile anything — pnpm and tsc still do that work.
Turborepo 2.0 renamed the top-level pipeline key in turbo.json to tasks. Run npx @turbo/codemod@latest migrate instead of editing the file by hand.
An undeclared environment variable is the most dangerous cache input. Next.js inlines NEXT_PUBLIC_* values into the client bundle at build time, so a cache hit can physically replay another environment's URLs.
Turborepo 2.0 defaults to strict environment mode, where a task only sees variables listed in env or globalEnv. That default converts a silent wrong-value bug into a loud undefined one.
The --affected flag is only as good as your git history. A shallow CI clone has no base commit to diff against, so the filter quietly degrades into building everything.

What does Turborepo actually do, and what does it not replace?

Turborepo is a task runner for JavaScript monorepos that builds a dependency graph of your scripts, hashes the inputs of each task, and restores cached outputs when the hash matches a previous run. That is the entire product. It does not install packages, does not resolve workspace links, and does not bundle a single byte.

The division of labour is worth stating plainly, because it decides where to debug:

pnpm, npm, or yarn workspaces install dependencies and symlink internal packages. Turborepo reads that workspace definition; it does not create it.
tsc, tsup, the Next.js compiler, and the Nest CLI do the actual compiling. Turborepo runs them as ordinary scripts.
Turborepo decides what runs, in what order, across how many cores — and whether it needs to run at all.

The useful mental model is memoization. turbo run build is a memoized call to pnpm build in every package, keyed on a hash of the source files, the dependency graph, the resolved lockfile entries, and the declared environment variables. Memoization is only correct when the function is deterministic with respect to its declared arguments. Every Turborepo bug I have hit was an argument I forgot to declare.

Why does turbo.json use tasks instead of pipeline now?

Turborepo 2.0 renamed the top-level pipeline key to tasks, because the old name implied a sequential pipeline when the value is really a set of task definitions whose order comes entirely from dependsOn. A configuration file still using pipeline fails on Turborepo 2 with a schema error, and npx @turbo/codemod@latest migrate renames it along with the other 2.x migrations.

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"],
      "env": ["NEXT_PUBLIC_*", "DATABASE_URL"]
    },
    "test": { "dependsOn": ["build"], "outputs": ["coverage/**"] },
    "dev": { "cache": false, "persistent": true }
  }
}

Two pieces of that syntax carry most of the meaning. "dependsOn": ["^build"] with the caret means "build every package this package depends on first", walking up the dependency graph. "dependsOn": ["build"] without the caret means "run the build task of this same package first". Mixing those two up produces a graph that reads correctly and schedules wrong.

persistent: true marks a task that never exits, such as a dev server. Turborepo 2 refuses to let any other task declare a dependency on a persistent task, which is the right error to raise: a task waiting on something that never finishes is a deadlock, not a build order.

Why is my build cache always missing?

A Turborepo task misses the cache when something inside its hash changed, and it caches nothing at all when its outputs array is empty. Those are two different failures with one symptom — a full rebuild every time — and turbo run build --dry=json tells them apart without running anything, because it prints each task's resolved inputs, environment variables, and final hash.

For a run that already happened, turbo run build --summarize writes a JSON file into .turbo/runs/ containing the hash breakdown per task. Diffing two of those files across a miss is the fastest way I know to find the single input that moved.

Two shapes are worth recognising on sight:

A hash that never repeats usually means a generated artifact is being counted as source. Turborepo's default inputs are the git-tracked files in the package, so a committed dist/ folder or a build-stamped file makes every run unique. Gitignore it.
A hash that never changes when it should means a real input is invisible. .env.local is the classic case: it is gitignored, so it is not in the default inputs, so editing it invalidates nothing.

The fix for the second case is the $TURBO_DEFAULT$ sentinel, which means "the default inputs, plus what I list next". Writing "inputs": [".env*"] on its own replaces the defaults entirely and silently stops tracking your source files, which is a far worse bug than the one you set out to fix.

Why did a cached build ship the wrong NEXT_PUBLIC value?

Next.js inlines every NEXT_PUBLIC_* variable into the client bundle at build time as a string literal, so the compiled .next output physically contains the values from whichever environment produced it. If those variables are not listed in the task's env array, Turborepo's hash cannot see them, the build looks identical to a previous one, and the cache restores a bundle pointing at the wrong API. Nothing throws. The build is green.

"build": {
  "dependsOn": ["^build"],
  "env": ["NEXT_PUBLIC_*", "NEXTAUTH_URL"],
  "passThroughEnv": ["AWS_SECRET_ACCESS_KEY"],
  "outputs": [".next/**", "!.next/cache/**"]
}

Turborepo 2.0 changed the default environment mode to strict, and that default is the real fix. In strict mode a task's process receives only the variables named in env and globalEnv, plus a small built-in allowlist. An undeclared variable is therefore undefined at build time rather than quietly present, which turns an invisible wrong-value bug into an obvious failure you catch locally.

Two distinctions I now apply mechanically. env is for variables that change the artifact, so they belong in the hash. passThroughEnv is for variables a task needs at runtime but that provably cannot change its output, such as an upload credential used after the bundle is written; those reach the process without joining the hash. globalEnv is for variables that affect every task in the repo, which in practice is a very short list.

Should internal packages export TypeScript source or compiled output?

Export raw TypeScript source from an internal package when every consumer is a bundler, and compile to JavaScript when any consumer is a Node process or an npm publish target. Turborepo's documentation calls these Just-in-Time Packages and Compiled Packages, and the choice changes how much there is to cache in the first place.

A Just-in-Time package has no build step at all:

{
  "name": "@repo/ui",
  "exports": { ".": "./src/index.ts" }
}

The consuming Next.js app then needs transpilePackages: ['@repo/ui'] in next.config.ts so its compiler handles the untranspiled source. The upside is that there is no build task, so there is no cache entry to invalidate and no stale dist/ to debug. The downside is that every consuming app compiles the shared code again, and a NestJS service started with node dist/main.js cannot import a .ts file at all.

A Compiled package pays a build step to remove those limits:

{
  "name": "@repo/core",
  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
  "scripts": { "build": "tsup src/index.ts --format esm --dts" }
}

My rule after living with both: UI components and type-only packages stay Just-in-Time, and anything imported by a Node runtime or published outside the repo gets compiled. Splitting on that line kept the build graph shallow, because most packages have no build task and ^build has almost nothing to wait for.

How do I build only what changed in CI?

turbo run build --affected restricts a run to the packages touched since the base branch, and it is the flag Turborepo 2.1 added to replace the older --filter=...[origin/main] syntax. It compares against main by default, and the TURBO_SCM_BASE and TURBO_SCM_HEAD variables override both ends of the comparison, which is what pull-request builds need.

The gotcha that cost me an afternoon is that --affected is a git operation. GitHub Actions' actions/checkout defaults to fetch-depth: 1, so the runner holds exactly one commit and has no base to diff against — and the run degrades into building everything with no error explaining why. Setting fetch-depth: 0 in the checkout step makes the flag behave.

Remote caching is what makes any of this matter on ephemeral runners. Without it, every CI job starts with an empty cache and the local hits you enjoy on your laptop help nobody else. turbo login followed by turbo link wires up Vercel's remote cache, and setting TURBO_API, TURBO_TOKEN, and TURBO_TEAM points the same client at a self-hosted one.

For Docker, turbo prune <app> --docker writes an out/json directory containing only the lockfile and the package.json files of that app's subgraph, plus an out/full directory with the source. Copying out/json and installing before copying out/full means the install layer only invalidates when a dependency actually changes, rather than on every source edit.

FAQ

Q: Does Turborepo replace pnpm workspaces?
A: No. Turborepo runs and caches tasks, while the package manager still installs dependencies and links internal packages. Turborepo reads the workspace definition from pnpm-workspace.yaml or the workspaces field in the root package.json.

Q: How is Turborepo different from Nx?
A: Both build a task graph and cache task outputs locally and remotely. Turborepo is configuration-only, wrapping the package.json scripts you already have in one turbo.json, while Nx adds plugins, generators, executors, and inferred targets. If your scripts already work, Turborepo is the smaller migration; if you want scaffolding and per-framework integrations, Nx does more.

Q: Can a Turborepo cache hit be wrong?
A: Yes. A cache hit is exactly as honest as the declared inputs and env. If a file or variable changes the output but is not part of the hash, Turborepo will confidently replay a stale artifact, so verify a suspicious hit with turbo run build --dry=json.

Q: Why does my dev task need persistent: true?
A: A dev server never exits, and persistent: true tells Turborepo not to wait for it. Turborepo 2 also rejects any task that declares dependsOn on a persistent task, because that dependency could never be satisfied.

Q: Is remote caching worth it for a solo developer?
A: For local work, no — the local cache under node_modules/.cache/turbo already covers it. For CI, yes, because CI containers are ephemeral and start with an empty cache on every run, which is exactly where a full rebuild costs the most.

Originally published on devya.dev. Also on eng-ahmed.com. Built by Devya Solutions.