DEV Community: u11d

Next.js 16 Cache Components: Where Should You Place 'use cache'?

Paweł Sobolewski — Fri, 06 Nov 2026 16:20:40 +0000

Next.js 16 ships Cache Components as a first-class caching model: a single 'use cache' directive, paired with cacheLife, that you can drop on a route, a component, or a plain data-fetching function. The pitch is appealing: pick your own granularity, mix static and dynamic content on the same page, and let Partial Prerendering figure out the rest.

That pitch also raises a question the docs don't spend much time on: does it actually matter where you put 'use cache'? If you wrap an entire component versus just the fetch call inside it, what changes, for the reader and for the server doing the work?

To find out, I built a small dashboard with three crypto price cards (Bitcoin, Ethereum, Solana), all pulling the same kind of data from the same public API, each caching it a different way:

Bitcoin caches the fetch and the render together, at the component level.
Ethereum caches only the fetch; the chart underneath is recomputed on every request.
Solana caches nothing at all.

All three run under the exact same cacheLife profile. The only variable is what each card chooses to cache, not how long it's cached for. That constraint turned out to matter: it's what forced some genuinely non-obvious behavior into the open, the kind you won't hit until you've deployed something and watched it run for a few minutes under real traffic.

This is a walkthrough of what I found, with the actual numbers, not just the theory.

Quick Reference

All three cards share the exact same cacheLife("demo") profile (stale: 60, revalidate: 10, expire: 300). The only variable is what each one chooses to cache.

Card	What's cached	First-load time (warm cache)	Re-runs on every request?
Bitcoin	Fetch + chart computation + JSX, via `'use cache'` on the component	~40ms	No — only after the 10s `revalidate` window passes and a request triggers the refresh
Ethereum	Fetch only, via `'use cache'` on the data function	~445ms	Chart: yes, every request. Fetch: no
Solana	Nothing	~1084ms	Yes — fetch and chart, every request

cacheLife's prerendering rules force a cache scope into a dynamic hole (excluded from the static shell) once any of these thresholds is crossed:

`cacheLife` field	This demo's value	Forces dynamic below/at
`stale`	60s	< 30s
`revalidate`	10s	`0`
`expire`	300s (5m)	< 5m

The demo

The app itself is deliberately small: one route, three cards, no database. Each card fetches live price data for its coin from Binance's public REST API (no key required), renders a price, a 24h change, and a small chart. Under the hood, each card also prints two things most demos hide: an execution counter and a timestamp, both of which only update when the card's data-fetching function actually runs, not on every page load. That's the whole trick this article leans on: instead of guessing whether something was cached, you can watch the counter and just... check.

Stack-wise it's nothing exotic: Next.js 16.3.2, App Router, TypeScript, Tailwind. The full source is on GitHub if you want to run it yourself; every number quoted below came from that exact code, built and served with next build && next start. That last part matters more than it sounds: 'use cache' behaves differently under next dev, so next dev is not where you want to be verifying any of this.

Component-level: cache everything, render included

The 'use cache' directive can sit at the top of a function or a component. Put it on a component, and the entire thing (data fetching, computation, the JSX it returns) gets cached as one unit. That's the Bitcoin card:

import { cacheLife } from "next/cache";
import { computeExpensiveChart } from "@/lib/chart";
import { COINS, fetchBinancePrice, recordExecution } from "@/lib/prices";
import { CryptoCard } from "./crypto-card/CryptoCard";

export async function BitcoinCard() {
  "use cache";
  cacheLife("demo");

  const { price, change24h } = await fetchBinancePrice("bitcoin");
  const { executionCount, fetchedAt } = recordExecution("bitcoin");
  const { sparklinePath } = await computeExpensiveChart(price, change24h);

  return (
    <CryptoCard
      price={price}
      change24h={change24h}
      sparklinePath={sparklinePath}
      executionCount={executionCount}
      fetchedAt={fetchedAt}
      // ...tier, name, symbol
    />
  );
}

Three things happen inside that cached scope: fetching the price from Binance, recording that a real execution happened, and computing the chart's SVG path. computeExpensiveChart stands in for something you'd actually see in production: a heavier chart library, a technical-indicator calculation, a template render. So I gave it a real, measurable cost (a few hundred milliseconds) instead of pretending it's free.

The cacheLife call is what gives this cache entry a lifetime. "demo" is a custom profile defined in next.config.ts rather than one of the built-ins ("minutes", "hours", and so on); more on why, and on the exact numbers, in a couple of sections. For now, the point is simpler: on a cache hit, none of that work happens. Not the fetch, not the chart computation. The component just returns whatever was computed and stored the last time this cache entry was filled.

What actually gets stored isn't HTML, and it isn't a plain object of { price, change24h, ... } either. It's a serialized RSC payload: the same wire format React Server Components normally stream to the client, just persisted instead of sent once and discarded. That's also why 'use cache' is allowed to return JSX at all: return values follow client-serialization rules, which are more permissive than the rules for a cached function's arguments.

From that one stored payload, Next.js can produce whatever a given request needs: HTML for the prerendered static shell, the same payload replayed as-is for another server hit, or shipped straight to the browser so a client-side navigation can reuse it without a round trip.

Fetch-level: cache the data, not the render

'use cache' doesn't have to sit on a component. Put it on a plain async function instead, and only that function's return value gets cached; nothing about the component that calls it changes:

// lib/prices.ts
export async function getEthereumSnapshot(): Promise<PriceSnapshot> {
  "use cache";
  cacheLife("demo");

  const { price, change24h } = await fetchBinancePrice("ethereum");
  const { executionCount, fetchedAt } = recordExecution("ethereum");

  return { price, change24h, executionCount, fetchedAt };
}

// EthereumCard.tsx
export async function EthereumCard() {
  const { price, change24h, executionCount, fetchedAt } =
    await getEthereumSnapshot();
  const { sparklinePath } = await computeExpensiveChart(price, change24h);

  return (
    <CryptoCard
      price={price}
      change24h={change24h}
      sparklinePath={sparklinePath}
      executionCount={executionCount}
      fetchedAt={fetchedAt}
      // ...tier, name, symbol
    />
  );
}

EthereumCard itself has no 'use cache' at all. It calls a cached function to get pricing data, then unconditionally recomputes the chart from that data on every single request: same computeExpensiveChart, same artificial cost, as Bitcoin's card. Same cacheLife("demo"), too: the fetch is cached on the exact same schedule as Bitcoin's whole component. The only difference between these two cards is what's inside the cached scope versus what's outside it.

Here's the part that isn't obvious going in: that difference alone is not what makes Ethereum's chart recompute every time. If EthereumCard had no reason to be treated as dynamic, Next would happily bake the entire thing (cached fetch, chart computation and all) into the same kind of static shell Bitcoin gets, on the theory that nothing about it depends on the incoming request. Cache placement controls what gets cached; it doesn't, by itself, control how often a component gets re-evaluated. Those are two separate questions, and it's easy to assume the first answers the second.

What actually forces EthereumCard to run on every request is computeExpensiveChart itself: an await with no 'use cache' around it, sitting in a component that also has no 'use cache' around it. Next can't treat that as predictable output it's safe to freeze at build time, so the component becomes a genuine dynamic hole: resolved fresh, on the server, for every single request. The cached fetch inside it is just along for the ride: fast when it's warm, but that speed has no bearing on whether the component around it reruns.

Zero cache: the baseline

Solana's card doesn't try to be clever:

export async function SolanaCard() {
  const { price, change24h, executionCount, fetchedAt } =
    await getSolanaSnapshot();
  const { sparklinePath } = await computeExpensiveChart(price, change24h);

  return (
    <CryptoCard
      price={price}
      change24h={change24h}
      sparklinePath={sparklinePath}
      executionCount={executionCount}
      fetchedAt={fetchedAt}
      live
    />
  );
}

No 'use cache' anywhere in the chain: not on the component, not on getSolanaSnapshot. The fetch alone is enough to make this a dynamic hole, for the same reason as Ethereum's chart: an uncached async operation with nothing caching it. Every request pays for both the network round trip to Binance and the chart computation, in full, every time. That's the baseline the other two cards get compared against.

How to measure this for real

Explaining what should be cached is one thing. Watching it happen is more convincing, so each card carries two independent signals, and neither is a number the code invents.

The first is server-side: an execution counter plus a timestamp, both updated only inside the function that does the real work: the fetch for Ethereum and Solana, the whole component for Bitcoin. A cache hit means that code doesn't run, which means the counter doesn't move. No inference required, just read the number.

The second is client-side, and answers a different question: not "was this cached," but "how long did the reader actually wait for it." Each card mounts a small client component the instant its content reaches the browser:

"use client";

import { useEffect, useRef } from "react";

export function AppearedAtBadge() {
  const ref = useRef<HTMLSpanElement>(null);

  useEffect(() => {
    const node = ref.current;
    if (node) {
      node.textContent = `appeared after ${Math.round(performance.now())}ms`;
    }
  }, []);

  return <span ref={ref}>…</span>;
}

performance.now() inside a useEffect fires the moment this specific node mounts. For a card behind its own <Suspense> boundary, that's the moment its streamed chunk actually arrived, not when the initial HTML shell did. (It writes to the DOM directly instead of calling setState, on purpose: a setState here would just trigger an extra render for a value nothing else depends on.) Since Bitcoin, Ethereum, and Solana each stream independently, this produces three different numbers on the same page load. On a warm run, measured against this exact code:

Card	Appeared after
Bitcoin	~40ms
Ethereum	~445ms
Solana	~1084ms

That's the whole argument in one table. Bitcoin's number is just network latency: the cache hit means there's nothing else to wait for. Ethereum pays for the chart, once, and skips the fetch. Solana pays for both, every time.

Three things about `stale`, `revalidate`, and `expire` worth knowing before you hit them in production

Bitcoin and Ethereum share one cacheLife profile (see Quick Reference above), precisely so any difference between them comes from what's cached, not how long. Getting that shared profile right surfaced a few behaviors that aren't obvious from a first read of the docs.

A short lifetime can silently force a <Suspense> boundary you didn't ask for. cacheLife's prerendering rules exclude a cache scope from the static shell, turning it into a dynamic hole, under three conditions: revalidate: 0 or expire under 5 minutes, or stale under 30 seconds. Hit any of them on a component you expected to be static, like Bitcoin, and next build fails outright, pointing at that component with an error about uncached data outside a <Suspense> boundary.

revalidate never blocks a request, and it never fires without one. The background regeneration model is classic stale-while-revalidate: once a cache entry's age passes revalidate, the server keeps serving the existing value immediately while refreshing it in the background; nobody waits. If nothing asks, nothing refreshes, no matter how much wall-clock time passes.

A fresh build and a fresh process don't share state, even though they share a build. This one's specific to caching at the component level, and it's the kind of thing you only notice if you're watching closely. next build genuinely executes Bitcoin's cached component once, to produce the static shell, including our counter, which ticks up to 1 inside that short-lived build process. When next start boots, it's a new process with its own fresh copy of that counter, starting back at 0. So the first real execution inside the running server also lands on "1", the same number the build already showed, just with a new price behind it. Only the second live execution correctly shows "2". If you're using an in-memory counter as a "did this actually run" signal, this is the one moment it lies to you; a timestamp doesn't have the same problem, since it never resets.

None of these are bugs. They're the kind of detail that only shows up once you deploy something and watch it for a few minutes instead of trusting the mental model you built from the docs alone.

How this compares to classic ISR

If you've used Incremental Static Regeneration before (getStaticProps with a revalidate option, or export const revalidate = 60 in the App Router), the stale-while-revalidate mechanics in this article will feel familiar, because it's the same underlying model. What's different is the unit it applies to. Classic ISR revalidates a page: one lifetime, one cache entry, for everything that page renders. Getting Bitcoin-style and Ethereum-style behavior on the same route used to mean either splitting them into separate routes or reaching for something like unstable_cache to hand-roll a second cache boundary inside the page.

Cache Components collapses that gap by making the component or function the unit instead of the route. Bitcoin and Ethereum sit on the same page, share the same cacheLife, and still behave completely differently, because the boundary moved, not because the underlying revalidation logic changed. If you're already comfortable with ISR's mental model, most of what's new here is granularity, not a new set of rules to learn from scratch.

Picking a strategy

Three cards, three defensible choices, and the right one depends on what's actually expensive:

Cache the component (Bitcoin) when the render itself costs real time (a chart library, a heavy transform, anything downstream of the fetch) and that render doesn't need to be fresher than the data feeding it. Bundling both together means a cache hit skips all of it, not just the network call.
Cache just the fetch (Ethereum) when the data can tolerate being a little stale but what you build from it can't: per-request personalization, something reading a cookie, anything that has to reflect this request even though the numbers behind it don't change every second.
Cache nothing (Solana) when the data genuinely has to be live, and go in knowing you're paying for the fetch and everything downstream of it, every single time, deliberately.

The instinct worth keeping is to verify, not assume. 'use cache' placement determines what's frozen; it doesn't determine when your code runs. That's still governed by whether anything nearby gives Next a reason to treat the surrounding component as dynamic. As with most caching decisions, there's no universal answer here; it depends entirely on the use case in front of you. What does generalize is the method: a counter and a timestamp that only move on real work turn that decision into something you can check, not something you have to guess at.

Conclusion

Cache Components don't change the mental model of stale-while-revalidate caching — they change its unit, from the whole route down to a single component or function. That extra granularity is worth having, but it comes with a sharp edge: placement controls what's frozen, not how often the surrounding code reruns, and the two are easy to conflate until you've measured them separately, as the Bitcoin/Ethereum/Solana comparison above does. If you're building on Next.js and want this kind of caching behavior verified against real numbers before it ships, that's the same kind of work u11d's web development team does on React/Next.js projects.

Resources

Cache Components — Next.js docs
'use cache' directive reference
cacheLife function reference and prerendering rules
How revalidation works
Incremental Static Regeneration guide
Demo source code on GitHub
Implementing Postgres Row-Level Security in Next.js: The Drizzle Multi-Tenant Pattern — another Next.js production deep-dive on this blog
Building a Multi-Language Shop with Next.js App Router — another Next.js App Router deep-dive on this blog

FAQ

What does Next.js's 'use cache' directive actually cache?
'use cache' stores whatever the function or component it wraps returns, serialized as an RSC (React Server Components) payload — not raw HTML and not a plain JavaScript object. On a component, that means the data fetch, any computation inside it, and the JSX it returns are all cached together as one unit; on a plain function, only that function's return value is cached.

Does it matter whether I put 'use cache' on a component or on the fetch function?
Yes. Caching a whole component in Next.js caches the fetch, any computation, and the rendered output together, so a cache hit skips all of it. Caching only the data-fetching function leaves everything else in the component — like a chart calculation — to run on every request, even though the data behind it came from cache.

Why does my Next.js component still re-run on every request even though I cached the data fetch with 'use cache'?
Because an uncached await anywhere else in that component — a chart computation, a transform, another fetch — forces Next.js to treat the whole component as a dynamic hole that gets re-evaluated per request. Caching a function only freezes that function's own output; it doesn't stop Next.js from re-running everything around it.

Why did next build fail with an error about uncached data outside a <Suspense> boundary?
Next.js's cacheLife prerendering rules exclude a cache scope from the static shell — turning it into a required dynamic hole — whenever revalidate is 0, expire is under 5 minutes, or stale is under 30 seconds. Hitting one of these thresholds on a component you expected to prerender statically makes next build fail unless that component is wrapped in <Suspense>.

Does cacheLife's revalidate option refresh the cache automatically in the background?
No. revalidate only marks a Next.js cache entry as stale once its age passes that threshold — nothing refreshes it until the next real request arrives, at which point Next.js serves the existing stale value immediately and refreshes it in the background. If no request comes in, the cache never refreshes on its own, no matter how much time passes.

A Complete Guide to AWS CloudFront Origin Request Policies

Maciej Łopalewski — Wed, 04 Nov 2026 14:26:33 +0000

If your origin needs data the cache key shouldn't include, an origin request policy is the right tool. It controls what CloudFront forwards to your backend on a cache miss, separately from what makes a request "unique" for caching. Use a managed policy unless you have a specific reason not to — AWS ships eight of them, and most distributions can pick one off the shelf.

The short version, before the rest of the article:

Managed policy	Use when your origin is
`AllViewer`	A backend that needs every viewer header, cookie, and query string
`AllViewerAndCloudFrontHeaders-2022-06`	The same, plus geolocation, device-type, or TLS metadata
`AllViewerExceptHostHeader`	API Gateway or a Lambda function URL
`CORS-S3Origin`	An S3 bucket serving cross-origin assets
`CORS-CustomOrigin`	A non-S3 web server handling CORS
`HostHeaderOnly`	A backend that needs only the original `Host` header
`UserAgentRefererHeaders`	Doing analytics, hotlink protection, or basic device detection
`Elemental-MediaTailor-PersonalizedManifests`	An AWS Elemental MediaTailor endpoint

The rest of this article covers what these policies actually do, how they interact with the cache key (where most bugs live), and when to skip the managed list and write a custom one.

This is a follow-up to an earlier post that covered cache, origin request, and response policies as a trio — read that first if you want the broader context.

What an origin request policy actually does

CloudFront builds the request it sends to your origin from two sources. The first is everything in the cache key, controlled by your cache policy. The second is whatever your origin request policy adds on top. Without an origin request policy attached, the only headers your origin sees are the ones already in the cache key, plus a small set CloudFront automatically adds (Host, User-Agent, X-Amz-Cf-Id, and a few others).

That default is intentional. If a value isn't in the cache key, CloudFront treats requests with different versions of that value as the same cached object. Forwarding the value to the origin would make the response depend on something the cache doesn't see — and you'd get inconsistent results because the first response wins and gets served to everyone else. Origin request policies let you forward extra data to the origin while keeping the cache blind to it. That's only safe when the origin uses that data for things that don't change the response body: logging, analytics, downstream auth, or branching that returns the same content regardless.

I've seen teams reach for an origin request policy when what they actually needed was to add a value to the cache key. If your application reads User-Agent to decide between a mobile and a desktop response, forwarding it via an origin request policy isn't enough — the cached response is shared across both. The fix is to put User-Agent in the cache key, or to use a CloudFront-supplied header like CloudFront-Is-Mobile-Viewer, which is designed exactly for that case.

How it interacts with the cache policy

Anything in the cache key is automatically forwarded to the origin. The origin request policy can only add to that — it can't subtract. If your cache policy includes Authorization in the cache key, the origin will see it on a cache miss whether or not your origin request policy mentions it. This often surprises people debugging "why is this header reaching my origin when I didn't list it?"

There's also a hard requirement worth knowing up front: a cache behavior cannot have an origin request policy attached without also having a cache policy. AWS rejects the configuration. So in practice, every distribution that uses origin request policies pairs each one with a cache policy on the same behavior.

The working rule: put values in the cache key when the response actually varies on them. Put values in the origin request policy when the origin needs them but the response is the same regardless.

What's inside an origin request policy

Three knobs: headers, cookies, and query strings. Each one accepts a behavior, plus an optional list when the behavior calls for one.

For headers, the available behaviors are:

none — no viewer headers forwarded (cache-key headers still go through, plus the small CloudFront-added set)
whitelist — only the listed headers
allViewer — every viewer header
allViewerAndWhitelistCloudFront — every viewer header plus specific CloudFront headers (geolocation, device-type, TLS info)
allExcept — every viewer header except a listed set

Cookies and query strings have a similar shape but a smaller set: none, all, whitelist, or allExcept. There's no allViewerAndWhitelistCloudFront equivalent because CloudFront doesn't add its own cookies or query strings.

A subtlety worth knowing before you read the managed policies below: when a policy uses allExcept to remove the viewer's Host header, CloudFront automatically replaces it with a new Host header containing the origin's domain name. That's exactly what makes AllViewerExceptHostHeader work for API Gateway — the gateway sees its own domain in the Host header and routes correctly, instead of seeing the CloudFront distribution's domain and rejecting the request.

The eight managed policies

Each managed policy has a stable ID that you reference from CloudFormation, the AWS CLI, the SDKs, or your IaC tool of choice. The IDs don't change, so it's safe to hardcode them.

AllViewer

Forwards every header, cookie, and query string from the viewer request to the origin.

ID: 216adef6-5c7f-47e4-b989-5492eafa07d3

Use this when your backend genuinely needs the full request — typically for legacy applications, complex authenticated apps, or anything where you can't easily enumerate which headers and cookies matter. The trade-off is that it forwards the viewer's Host header too, which means it doesn't work with API Gateway or Lambda function URLs (use AllViewerExceptHostHeader for those). It also forwards anything sensitive that the client happens to send, so think about whether your origin should see, for instance, a long-lived authentication cookie that some unrelated part of your app sets.

AllViewerAndCloudFrontHeaders-2022-06

Same as AllViewer plus a fixed set of CloudFront-added headers: CloudFront-Forwarded-Proto, the device-type series (-Is-Android-Viewer, -Is-Mobile-Viewer, -Is-Tablet-Viewer, etc.), the geolocation series (-Viewer-Country, -Viewer-City, -Viewer-Latitude, -Viewer-Longitude, -Viewer-Time-Zone, -Viewer-Postal-Code, -Viewer-ASN, and a few more), CloudFront-Viewer-Http-Version, and CloudFront-Viewer-TLS.

ID: 33f36d7e-f396-46d9-90e0-52428a34d9dc

The -2022-06 suffix is significant. The set of headers this policy forwards is frozen as of June 2022 — any CloudFront viewer header added after that date isn't included. AWS does this so existing distributions don't change behavior when new headers ship. If you want a newer CloudFront header in your origin requests, write a custom policy.

Use this when your origin uses CloudFront's enriched headers for personalization, analytics, or routing. Geolocation-based content selection is the common case: your backend reads CloudFront-Viewer-Country and serves a localized response, without doing GeoIP lookups itself.

AllViewerExceptHostHeader

Forwards everything except the Host header. CloudFront then injects the origin's domain name as the new Host.

ID: b689b0a8-53d0-40ab-baf2-68738e2966ac

This is the policy you almost certainly want when your origin is API Gateway, a Lambda function URL, or any AWS-managed endpoint that does virtual hosting based on the Host header. These services check Host against their own domain. If CloudFront forwards the viewer's Host (which is your CloudFront distribution's domain or your custom domain), they don't recognize it and respond with a 403.

It also includes the same set of CloudFront viewer headers as AllViewerAndCloudFrontHeaders-2022-06, which means you get geolocation and device-type metadata for free. For most API Gateway-backed CloudFront distributions, this is a one-line answer to a problem that used to require fiddling with cache behaviors and Lambda@Edge.

CORS-CustomOrigin

Forwards only the Origin header. No cookies, no query strings.

ID: 59781a5b-3903-41f3-afcb-af62929ccde1

Use this when your origin is anything other than S3 — an ALB, an EC2 instance, a containerized service, or a third-party HTTP server — and it serves cross-origin requests. The Origin header is what the server inspects to decide whether to return CORS-allowing response headers. Anything more just bloats the origin request without any CORS benefit, and risks forwarding data the origin doesn't need to see.

This policy pairs naturally with the CORS-with-preflight-and-SecurityHeadersPolicy response headers policy when your backend doesn't reliably set CORS headers itself.

CORS-S3Origin

Forwards Origin, Access-Control-Request-Headers, and Access-Control-Request-Method. No cookies, no query strings.

ID: 88a5eaf4-2fd4-4709-b370-b4c650ea3fcf

S3 is fussier about CORS than a custom server. To return the right CORS response headers, S3 needs to see all three of these request headers — not just Origin. The standard CORS forwarding policy (CORS-CustomOrigin) doesn't work because it omits the other two. If you've ever spent time debugging "CORS works locally but not through CloudFront" with an S3 origin, this is almost certainly the missing piece.

Note that this policy is for S3-as-origin scenarios where you've also configured a CORS rule on the bucket itself. Without the bucket-side CORS configuration, S3 won't return the Access-Control-Allow-* headers regardless of what gets forwarded.

HostHeaderOnly

Forwards just the Host header. Nothing else.

ID: bf0718e1-ba1e-49d1-88b1-f726733018ae

A narrow policy with a specific use case: multi-tenant origins that route based on the original viewer Host. If your backend serves multiple custom domains and uses the Host header to figure out which tenant a request belongs to, you need that header to come through unchanged. Most other managed policies either rewrite Host or don't forward enough information to make it useful.

If you're using this with anything other than a multi-tenant routing scenario, double-check whether you actually want it. For API Gateway origins, HostHeaderOnly will not work — API Gateway needs the rewritten Host, which is what AllViewerExceptHostHeader gives you instead.

UserAgentRefererHeaders

Forwards only User-Agent and Referer.

ID: acba4595-bd28-49b8-b9fe-13317c0390fa

This is the policy for cases where the origin needs to know "what kind of client is this?" or "where did the request come from?" without seeing the rest of the headers, cookies, or query strings. Two common uses: hotlink protection (block requests where Referer doesn't match an allowed list) and analytics that bucket traffic by browser or operating system.

It pairs well with a tight cache policy — typically CachingOptimized — because neither header is in the cache key. The cache stays efficient and the origin still gets enough data to do its filtering or counting.

Elemental-MediaTailor-PersonalizedManifests

Forwards Origin, Access-Control-Request-Headers, Access-Control-Request-Method, User-Agent, X-Forwarded-For, and all query strings.

ID: 775133bc-15f2-49f9-abea-afb2e0bf67d2

A specialized policy for AWS Elemental MediaTailor, which serves personalized HLS/DASH manifests for ad insertion in video streaming. MediaTailor needs the CORS triplet for browser playback, User-Agent and X-Forwarded-For for ad-decisioning logic, and the full query string because session and personalization tokens are encoded there. If you're not using MediaTailor, you don't need this policy — but if you are, it's the difference between manifests that work and manifests that don't.

Comparison: what each managed policy forwards

Policy	Headers	Cookies	Query strings
`AllViewer`	All viewer	All	All
`AllViewerAndCloudFrontHeaders-2022-06`	All viewer + frozen CF set	All	All
`AllViewerExceptHostHeader`	All viewer except `Host` + CF set	All	All
`CORS-CustomOrigin`	`Origin`	None	None
`CORS-S3Origin`	`Origin`, `Access-Control-Request-Headers`, `Access-Control-Request-Method`	None	None
`HostHeaderOnly`	`Host`	None	None
`UserAgentRefererHeaders`	`User-Agent`, `Referer`	None	None
`Elemental-MediaTailor-PersonalizedManifests`	CORS triplet + `User-Agent` + `X-Forwarded-For`	None	All

When to write a custom origin request policy

The managed policies cover most cases. A custom policy is needed when:

Your origin needs a specific application header (like X-Tenant-ID or X-Request-Trace) that isn't in any managed policy
You want CloudFront viewer headers added after June 2022 — the managed AllViewerAndCloudFrontHeaders-2022-06 is frozen at that date
A specific cookie or query string needs to pass through while others stay blocked (no managed policy uses the whitelist behavior for cookies or query strings)
The requirements get oddly mixed — e.g., "everything except Authorization, plus a few CloudFront geolocation headers"

Here's a Terraform example for a custom policy that forwards a tenant header, geolocation, and a session cookie, while excluding everything else:

resource "aws_cloudfront_origin_request_policy" "tenant_api" {
  name    = "tenant-api-policy"
  comment = "Forwards tenant routing data and CF geolocation"

  headers_config {
    header_behavior = "whitelist"
    headers {
      items = [
        "X-Tenant-ID",
        "CloudFront-Viewer-Country",
        "CloudFront-Viewer-City",
      ]
    }
  }

  cookies_config {
    cookie_behavior = "whitelist"
    cookies {
      items = ["session_id"]
    }
  }

  query_strings_config {
    query_string_behavior = "none"
  }
}

A subtle gotcha worth knowing: under allViewerAndWhitelistCloudFront, the headers.items list isn't the only set of headers forwarded — every viewer header is forwarded too, and the list just adds CloudFront-specific headers on top. The behavior name is more literal than it looks. To restrict to a specific allowlist, use whitelist (as in the example above) and list both the viewer headers and any CloudFront headers you want.

To list all available origin request policies (managed and custom) from the AWS CLI:

# Returns the 8 managed policies with their IDs
aws cloudfront list-origin-request-policies --type managed

# Or list only your custom policies
aws cloudfront list-origin-request-policies --type custom

To attach a managed policy by ID, set OriginRequestPolicyId on the relevant cache behavior in your distribution config:

aws cloudfront update-distribution \
  --id E1A2B3C4D5E6F7 \
  --distribution-config file://config.json

Common pitfalls

A header isn't reaching the origin in the form you expect

Check whether the same header is configured under Origin Custom Headers on the distribution. AWS specifically warns against setting the same header in both places. Origin custom headers are applied before CloudFront forwards the request, and if the header is already present in the viewer request, CloudFront overwrites the value. The origin sees one deterministic value, but it may not be the one you set in the origin request policy. Pick one mechanism per header and you avoid the ambiguity.

API Gateway returns 403 even though `Host` isn't in the allowlist

If you wrote a custom policy and used whitelist for headers without including Host in the allowlist, the viewer's Host header isn't forwarded — but it also isn't replaced. CloudFront's automatic Host rewrite only kicks in with the allExcept behavior when Host is in the excluded list. For API Gateway, either use AllViewerExceptHostHeader (the easiest path), or use allExcept with Host in the exclusion list.

`Authorization` reaches the origin even though it's not in the policy

Your cache policy is including it. Cache-key headers are automatically forwarded; the origin request policy can only add to that. Open the cache policy attached to the same cache behavior and check whether Authorization is listed under headers there. If you actually want the header to stay out of the origin requests, you'll need to remove it from the cache key — and accept the implications for cache hit ratio, since responses will no longer be keyed on it.

A CloudFront-added header isn't arriving

Two different causes look the same from the origin side. First, the header may simply not be in your policy: a bare AllViewer doesn't include any CloudFront-added headers, and AllViewerAndCloudFrontHeaders-2022-06 is frozen at the set of headers AWS released through June 2022. Anything added later — CloudFront-Viewer-JA3-Fingerprint and CloudFront-Viewer-JA4-Fingerprint for TLS fingerprinting, CloudFront-Viewer-Header-Order and CloudFront-Viewer-Header-Count for bot detection, CloudFront-Error-Uri and CloudFront-Error-Args for error-handling flows — is not in the managed -2022-06 policy. To get those, write a custom origin request policy and list them explicitly.

Second, even when the header is included, AWS notes that CloudFront-Viewer-City, CloudFront-Viewer-Metro-Code, and CloudFront-Viewer-Postal-Code may not be available for every IP address — some addresses don't geolocate with enough precision. If those fields are blank for some traffic but populated for others, the policy is fine; the geolocation data just isn't there.

Cookies aren't reaching a Lambda function URL even with `AllViewerExceptHostHeader`

Three things to check, in order. First, confirm the browser actually sent the cookie to your CloudFront domain — Secure, HttpOnly, SameSite=Strict, and Domain mismatches all stop browsers from including the cookie in the first place, and no policy can rescue you if the cookie never crossed the wire. Second, confirm the policy you chose includes cookies: AllViewerExceptHostHeader does forward all cookies, but if you wrote a custom policy and set cookie_behavior = "none", you'll see no cookies at the origin regardless of what was in the request. Third, when you do receive the request at the function, remember that Lambda function URLs use the API Gateway v2.0 payload format — cookies arrive in the event's cookies array, not in headers["Cookie"]. Code that reads the Cookie header directly will appear to receive nothing even when the cookies are present in the event.

If the issue is specific to cross-origin browser requests, the function URL's CORS configuration matters too — specifically the AllowCredentials setting, which has to be true for credentialed requests to be allowed at all. But that's only one of three things that need to align: the cookie has to permit cross-origin sending (typically SameSite=None; Secure), the client-side fetch has to opt into credentials (credentials: 'include'), and the function URL has to allow credentials. Miss any one and the cookie won't reach the function — and none of that is something CloudFront can fix from the edge.

Picking the right policy

A short decision tree:

Is your origin API Gateway or a Lambda function URL? → AllViewerExceptHostHeader
Is your origin S3 and you need CORS? → CORS-S3Origin
Is your origin a custom server (ALB, EC2, ECS) with CORS? → CORS-CustomOrigin
Are you using AWS Elemental MediaTailor? → Elemental-MediaTailor-PersonalizedManifests
Do you only need to identify the client? → UserAgentRefererHeaders
Are you running multi-tenant routing on Host? → HostHeaderOnly
Does your origin need everything? → AllViewer, or AllViewerAndCloudFrontHeaders-2022-06 if you want geolocation too
None of the above? → Write a custom policy

If none of the managed policies match exactly but you're close, custom policies are cheap to create and easy to version. There's no API quota concern for normal use, and you can test changes by attaching the new policy to a non-production cache behavior first.

The next post in this series will go through CloudFront response headers policies in the same depth — what each managed policy adds, when the browser actually honors it, and where custom policies are worth the maintenance cost.

Boosting GPU Performance by Reordering Unstructured Mesh Cells

Aleksy Bohdziul — Wed, 04 Nov 2026 14:06:30 +0000

We're building a GPU flood solver for unstructured 2D meshes. On every step, each cell reads its neighbors' state and turns those values into fluxes across its edges. Before optimizing the solver, we wanted to answer one question: how much does the order of cells in memory affect the speed of those neighbor reads?

To find out, we swapped the solver for Game of Life on the same kind of mesh. The memory access pattern is the same (read your neighbors, write yourself), but there's almost no math, so the result mostly measures memory performance.

Storing cells along a space-filling curve instead of in random order made the benchmark 1.9-3x faster. We didn't change the kernel or the mesh. The simulation computes the same result, only the cell numbering changed.

Cell reordering assigns nearby mesh cells nearby positions in memory so GPU neighbor reads can reuse cache lines more effectively.

Why Cell Ordering Affects GPU Performance

A GPU memory system fetches data in cache-line-sized transactions. If a cell's neighbors live next to it in memory, one fetch can cover many of them. If they're scattered, neighbor reads can require separate trips to device memory.

Meshes don't always come with a useful order. Our Voronoi mesh numbers its cells in the order the random sites were generated, so random order is our baseline: it's what you get if you do nothing. The hex grids naturally come out row by row, which already has decent locality, so we shuffled them to create the same baseline.

A space-filling curve—Hilbert, Morton, or Peano—snakes through the 2D domain. Cells that are near each other in space then tend to be near each other in memory.

Each dot is colored by the cell's position in memory. With random order (left), you get noise. With Hilbert order (right), memory sweeps through the domain in compact blocks.

Benchmark Setup

Hardware: an M1 Pro running Taichi 1.7.4, a Python framework that compiles kernels to the GPU, on the Vulkan backend. On a Mac, MoltenVK translates Vulkan to Metal. Every timed run reported backend: vulkan, so nothing quietly fell back to the CPU.
Meshes: stored as CSR adjacency graphs. A 768x768 hex grid (589,824 cells, 3.53M directed edges), a 512x512 hex grid (262,144 cells), and a Voronoi mesh built from 200,000 random sites with scipy.
Orderings: each one is a permutation applied to the cells before the run. Random uses rng.permutation. For the curves, we snap cell centers to a grid, compute each cell's position along the curve, and sort with argsort. Neighbor indices get remapped to match. Geometry, initial state, and rules stay the same.
Kernel: two i32 buffers, one for the current state and one for the next. One kernel counts live neighbors along each CSR row and looks up birth/survive tables, then a second one copies the new state back. Standard B3/S23 rules.
Timing: an untimed warmup for each ordering, ti.sync() on both sides of the timed region, and no reads back to the host inside that region. Each number is the median of 5 runs.

GPU Performance Results

Hex 768x768, 1000 steps, 100 warmup steps:

ordering	steps/s	range over 5 runs	µs/step	G cell-updates/s	vs random
peano	4273	4252-4274	234	2.52	2.96x
hilbert	4033	4000-4058	248	2.38	2.80x
morton	4009	3950-4102	249	2.36	2.78x
random	1441	1437-1444	694	0.85	1.00x

Smaller meshes, 500 steps, 50 warmup steps:

mesh	best curve	worst curve	random	curve vs random
hex 512x512	peano 8840	hilbert 8358	3566	2.34-2.48x
Voronoi 200k	hilbert 9491	morton 8934	4693	1.90-2.02x

The choice of curve has little effect

Peano came out on top for both hex meshes in this run, while Hilbert won on Voronoi. In a repeat run, Morton took first place on the 512-cell hex mesh. The curves stayed within 9% of one another, and each beat random order by about 1.9-3x. All three were effective. Our solver uses Hilbert, but Morton is the simplest to implement, so the example below uses it.

Random ordering limits throughput

Under random order, every mesh runs at about 0.9 billion cell updates per second, whatever its size or shape. Random ordering causes poor cache reuse, so mesh layout has little effect. With a curve, the same meshes reach 1.8-2.5 billion updates per second because neighbors are stored closer together.

Memory is the bottleneck

If you count only the bytes each step has to move (edge list, row offsets, state reads, and writes), the curve orders move about 105-111 GB/s on the big hex mesh. That's more than half of the M1 Pro's 200 GB/s spec. Random order manages 37 GB/s of useful traffic and spends the rest of its time waiting on cache misses.

How to Reorder Cells in Your Own Mesh

You need two NumPy functions. morton_order takes cell centers and returns a permutation, and reorder_csr renumbers a CSR adjacency graph to match it. Here, order maps each new cell position to its old cell ID; new_id is the inverse mapping used to rewrite neighbor indices. Apply the same permutation to every other per-cell array you have (state, geometry, boundary flags).

import numpy as np

def morton_order(xy, bits=10):
    """Permutation that sorts cells along a Z-order (Morton) curve."""
    lo, hi = xy.min(0), xy.max(0)
    g = ((xy - lo) / np.where(hi > lo, hi - lo, 1) * (2**bits - 1)).astype(np.uint64)
    key = np.zeros(len(xy), np.uint64)
    for b in range(bits):
        key |= ((g[:, 0] >> b) & 1) << (2 * b)
        key |= ((g[:, 1] >> b) & 1) << (2 * b + 1)
    return np.argsort(key, kind="stable")

def reorder_csr(indptr, indices, order):
    """Renumber cells so that new cell k is old cell order[k]."""
    new_id = np.empty_like(order)
    new_id[order] = np.arange(len(order))
    deg = np.diff(indptr)[order]
    new_indptr = np.concatenate([[0], np.cumsum(deg)])
    src = np.repeat(indptr[order] - new_indptr[:-1], deg) + np.arange(new_indptr[-1])
    return new_indptr, new_id[indices[src]]

order = morton_order(positions)
indptr, indices = reorder_csr(indptr, indices, order)  # int64; cast with .astype(np.int32) for i32 GPU buffers
state = state[order]

With bits=10, the domain is split into a 1024x1024 grid. Cells that land in the same grid square keep their original relative order, so if your mesh is much finer than that, increase bits.

What it costs

Reordering is a one-time cost. On the 768 hex mesh, the code above runs in about 110 ms: 74 ms to compute the keys and sort, 33 ms to rebuild the CSR graph. Each step saves about 450 µs, so it pays for itself after roughly 240 steps. You only do it when you load the mesh.

Reading state back to the CPU is slow. If we copy the full state to the host after every step, the 768 hex mesh with Hilbert order drops from 4033 to 565 steps/s (median of 5 runs of 1000 steps, ranging from 510 to 826). Each readback costs about 1.5 ms, six times the step time. A flood run still needs periodic output, so how often you read back matters about as much as how you order the cells.

Caveats

All of these numbers come from a single M1 Pro going through MoltenVK. A discrete GPU with a different cache setup will give different ratios. Game of Life also does almost no math per neighbor, while a real flux kernel does plenty, so the gap should shrink. Treat 2-3x as the most you can expect from reordering on this hardware. Your own kernel will probably gain less.

Conclusion

If your GPU code gathers neighbor data on an unstructured mesh, check the order of your cells. If the mesher or loader hands them over in arbitrary order, you're probably leaving speed on the table. Sorting them along a Morton curve takes about 20 lines of NumPy and a tenth of a second when the mesh loads, and on this benchmark it made every step 2-3x faster.

For us, the real test is the flood solver itself. It already orders its cells along a Hilbert curve, and next we'll time its flux kernel the same way to see how much of that speedup survives once the kernel does real math.

Beyond Prompts: Enforcing Repository Rules With Git Hooks

Daniel Kraszewski — Fri, 30 Oct 2026 09:03:29 +0000

You have probably already tried the obvious thing. You wrote the rules down - in AGENTS.md, CLAUDE.md, .cursor/rules, or whatever file your agent reads first. Do not commit without tests. Do not leave a component without a story. Run the type checker before you say you are done. The agent agreed, enthusiastically, and then went ahead and did something else anyway.

This is not a prompt-quality problem, and it is not specific to any one model. Large language models optimize for the next plausible token, not for your repository's conventions. In a small codebase you can review every diff and catch the drift by hand. In a large one you cannot: the agent touches a dozen files across a monorepo, the formatting is off, a component is missing its story, a test that used to pass now does not, and the commit lands anyway because nobody is running the checks at the moment the change is written.

The fix is not a better prompt; it is a gate. A Git hook runs your checks on every change, at git commit and git push, whoever - or whatever - wrote it. The tool I use to manage them is Lefthook: a single, dependency-free Go binary, driven by one YAML file, able to run jobs in parallel and re-stage the files it fixes. It reaches past Git, too: an ai: block (currently beta) lets Claude Code, Cursor, Codex, and Copilot run Lefthook hooks on their own events, so your checks fire when the agent stops working - before anything is ever committed. What follows is a working setup: the Git hooks first, then the same checks wired into the agent.

Quick Reference

If you want the short answer before the walkthrough, this is the whole tool at a glance:

Category	Details
What it is	A hooks manager for Git and for coding agents; one binary, no runtime dependency
Config file	`lefthook.yml`, or a `.lefthook.yaml` / `.toml` / `.json` variant
Install the hooks	`lefthook install`
Run a hook by hand	`lefthook run pre-commit`
Validate the config	`lefthook validate`
Skip once	`LEFTHOOK=0 git commit`
Agent hooks (beta)	Run your Lefthook hooks on Claude Code, Cursor, Codex, or Copilot events
Current version	v2.1.17 (October 2026)

The config we build in the next sections wires up five checks on commit and two on push; later, the same checks are attached to your coding agent's events.

Why Instructions Are Not Enforcement

A written rule is advisory. The agent may follow it, may partially follow it, or may follow it for the first three files and forget by the fourth - and you will not know which until you read the diff. A hook is deterministic. It runs the same command on the same files every single time, it fails closed, and it does not care who authored the change. If the check fails, the commit does not happen.

That difference matters more, not less, as codebases grow. Instructions have to be read, remembered, and applied; enforcement is automatic. It also gives you a single place to put the rules that are specific to your project - the ones no linter ships with, like "every component must have a story" - instead of repeating them across agent instruction files and hoping.

Lefthook fits here because it is small. It is a Go binary with no runtime to install, and it reads lefthook.yml on every hook run, so you never reinstall after editing the config - for Git hooks or for the agent hooks we add later.

Install Lefthook

The most common route is the package manager you already use. For a Node project that is the lefthook npm package:

pnpm add -D lefthook     # or: npm install --save-dev lefthook / yarn add --dev lefthook

There are equivalents for almost every ecosystem, all documented in the installation guide: brew install lefthook on macOS and Linux, go install github.com/evilmartians/lefthook/v2@v2.1.17, pipx install lefthook, gem install lefthook, plus apt, rpm, apk, winget, scoop, snap, and mise. If you would rather not use a package manager at all, download the binary from the latest release and put it on your PATH; lefthook self-update keeps it current.

For CI the mechanics are slightly different, because Git hooks are a local, client-side feature. Nothing runs your pre-commit hook in a container that just cloned the repo - there is no .git/hooks/pre-commit doing work unless you install it. So the CI job installs Lefthook and then calls the hook explicitly:

pnpm add -D lefthook
pnpm exec lefthook run pre-commit --all-files

--all-files replaces {staged_files} with every tracked file, which is what you want when there is no index to speak of. There is no official Lefthook GitHub Action and no official Docker image, so in CI you install the binary yourself - brew, curl, npm, or your base image's package manager - and call the hook explicitly. One detail to know: when the npm package is installed with CI=true set, its postinstall script deliberately skips hook installation, so a CI run will not try to wire up .git/hooks that nothing will execute. Your CI step calling lefthook run is what does the work.

Step 1: Write the Config

The whole configuration is one file at the repository root. This is the shape I use on a TypeScript/React project, and it is the config the runs below use:

# lefthook.yml
min_version: 2.1.10
lefthook: pnpm exec lefthook
glob_matcher: doublestar

pre-commit:
  jobs:
    - name: format staged files
      glob: "**/*.{js,jsx,ts,tsx,json,md,yml,yaml,css}"
      run: pnpm format {staged_files}
      stage_fixed: true

    - name: lint staged files
      glob: "**/*.{js,jsx,ts,tsx}"
      run: pnpm lint {staged_files}
      stage_fixed: true

    - name: typecheck
      run: pnpm check:types

    - name: stories-present
      glob: "src/components/**/*.{ts,tsx}"
      exclude: "**/*.stories.{ts,tsx}"
      run: pnpm check:stories {staged_files}

    - name: unit tests
      run: pnpm test:unit

pre-push:
  parallel: true
  jobs:
    - name: full verification
      run: pnpm verify

    - name: storybook tests
      run: pnpm test:storybook

Seven jobs in total, split across the two hooks:

Job	Hook	What it enforces
`format staged files`	pre-commit	Prettier rewrites staged files, then Lefthook re-stages them
`lint staged files`	pre-commit	ESLint `--fix` rewrites staged files, then re-stages them
`typecheck`	pre-commit	`tsc --noEmit` over the whole project
`stories-present`	pre-commit	A custom rule: every component has a story file
`unit tests`	pre-commit	`node --test`
`full verification`	pre-push	Typecheck, tests, and the custom checks together
`storybook tests`	pre-push	Component-level tests

A few keys carry most of the weight. The format, lint, check:*, and test:* targets are your own package.json scripts, so the config stays tool-agnostic: replacing Prettier with Biome is a change to one script body, not to seven hook entries. jobs is the modern list form (the older commands: map still works, but jobs also support scripts and groups). glob filters the file list a job receives, and exclude removes files from that filtered list. run is the command, executed with sh. The {staged_files} template expands to the files staged for the current commit - for a pre-push job you would use {push_files}, and {all_files} gives you everything tracked.

stage_fixed: true is the one that changes how it feels to use. When a job rewrites its files - Prettier reformatting, ESLint applying an autofix - Lefthook runs git add on them afterward, so the fixes land in the same commit instead of leaving a dirty working tree behind. It only works on pre-commit, and because each of those jobs mutates the index, I keep the auto-fixing jobs sequential by leaving parallel at its default (false). If the git add fails, Lefthook fails the hook rather than let the commit go through with unfixed content. If you would rather fail than let a hook rewrite files, invert the two auto-fixing jobs: run prettier --check and eslint without --fix, drop stage_fixed, and the pre-commit hook becomes a pure, parallel-safe gate.

The typecheck, stories-present, and unit tests jobs do not use {staged_files}; they run against the whole project, because a change in one file can break a type or a test somewhere else. The stories-present job is the interesting one for the agent narrative: it is a rule that exists only in this repository. Its glob is the part that matters, and it is also the part that is easy to get wrong - see The Glob That Silently Disables Your Hook.

The pre-push hook is deliberately broader and parallel. It runs pnpm verify (types, unit tests, and the custom story check) alongside the component tests. This is the layer that catches what a distracted --no-verify commit slipped past, and it is the right place for the slower checks you do not want on every keystroke.

Step 2: Install and Run the Hooks

Install the hooks once per clone:

pnpm exec lefthook install

sync hooks: ✔️(pre-push, pre-commit)

That command writes small shell scripts into .git/hooks/ for each configured hook; each script simply calls lefthook run <hook>. Because the config is read fresh every time a hook runs, editing lefthook.yml never requires reinstalling. You can confirm the hooks are present and synchronized with:

pnpm exec lefthook validate     # config is well-formed
pnpm exec lefthook check-install # exit 0 if hooks are installed and in sync

To run a hook without committing, lefthook run is the entry point. lefthook run pre-commit runs the hook as-is, lefthook run pre-commit --all-files forces every tracked file through it, --file path/to/file forces a specific list, and --job or --tag narrows it to specific jobs. Any hook name is a valid target, so a custom block such as verify: becomes lefthook run verify.

Two escape hatches are worth knowing. LEFTHOOK=0 git commit disables hooks for a single command, and git commit --no-verify bypasses hooks at the Git level. I mention them because they are necessary - but they are also exactly why the push hook and CI matter: a rule enforced only at commit time is a rule that a tired developer or a confident agent can skip.

Finally, teams rarely want identical hooks on every machine. A lefthook-local.yml file (git-ignored) merges over lefthook.yml, so an individual can set skip: true on a slow job or re-tag a command without touching the shared config.

What It Looks Like When a Commit Is Blocked

Here is a real run, on a small demo repository, of an agent finishing a change and committing it. The change adds a greet helper written in double quotes with a let that is never reassigned, and a Modal component with no story file. The first attempt:

$ git commit -m "feat: add greeting helper and modal component"
╭───────────────────────────────────────╮
│ lefthook  v2.1.17   hook:  pre-commit │
╰───────────────────────────────────────╯
┃  format staged files ❯ 
$ prettier --write lefthook.yml src/components/Modal.ts src/greeting.ts
lefthook.yml 12ms
src/components/Modal.ts 18ms (unchanged)
src/greeting.ts 3ms

┃  lint staged files ❯ 
$ eslint --fix src/components/Modal.ts src/greeting.ts

┃  typecheck ❯ 
$ tsc --noEmit

┃  stories-present ❯ 
$ node scripts/check-stories.mjs src/components/Modal.ts
Missing story files for:
  src/components/Modal.ts
[ELIFECYCLE] Command failed with exit code 1.

exit status 1
...

  ────────────────────────────────────
summary: (done in 1.24 seconds)
✓ format staged files (0.26 seconds)
✓ lint staged files (0.44 seconds)
✓ typecheck (0.37 seconds)
✓ unit tests (0.11 seconds)
✗ stories-present (0.05 seconds)

The commit does not happen. Two different things occurred in that run, and they are the two halves of why this works. First, format and lint silently fixed the sloppy code: Prettier rewrote the quotes and style, ESLint turned the let into a const, and stage_fixed re-staged both. You can prove the fixed content is what is staged, not just present in the working tree:

$ git show :src/greeting.ts
export function greet(name: string) {
  const message = 'Hello, ' + name + '!'
  return message
}

Second, stories-present refused the change. The component exists, the story does not, and no amount of instruction-following on the agent's part makes the commit land. Add the missing story and the same commit passes, every job green:

$ git add src/components/Modal.stories.ts
$ git commit -m "feat: add greeting helper and modal component"
...

  ────────────────────────────────────
summary: (done in 1.17 seconds)
✓ format staged files (0.14 seconds)
✓ lint staged files (0.47 seconds)
✓ typecheck (0.38 seconds)
✓ stories-present (0.05 seconds)
✓ unit tests (0.12 seconds)
[main de227fe] feat: add greeting helper and modal component
 4 files changed, 17 insertions(+), 4 deletions(-)

git push runs the second gate. Both jobs run in parallel:

$ git push origin main
╭─────────────────────────────────────╮
│ lefthook  v2.1.17   hook:  pre-push │
╰─────────────────────────────────────╯
┃  storybook tests ❯ 
$ node scripts/check-stories.mjs
Story check passed for 2 component file(s).

┃  full verification ❯ 
$ pnpm check:types && pnpm test:unit && pnpm check:stories
$ tsc --noEmit
$ node --test "src/**/*.test.ts"
✔ adds two numbers (0.467667ms)
ℹ pass 1
ℹ fail 0
$ node scripts/check-stories.mjs
Story check passed for 2 component file(s).

  ────────────────────────────────────
summary: (done in 0.65 seconds)
✓ storybook tests (0.06 seconds)
✓ full verification (0.55 seconds)

The Glob That Silently Disables Your Hook

The config above includes glob_matcher: doublestar, and that one line is doing more than it looks. A pattern like src/components/**/*.{ts,tsx} reads as correct, but without doublestar it never matches a file sitting directly in src/components/. Here is what that looks like on a commit that adds src/components/Modal.ts with no story:

$ git commit -m "feat: add modal component"
...
│  stories-present (skip) no files for inspection
  ────────────────────────────────────
summary: (done in 1.10 seconds)
✓ format staged files (0.11 seconds)
✓ lint staged files (0.49 seconds)
✓ typecheck (0.38 seconds)
✓ unit tests (0.12 seconds)
[main 511f599] feat: add modal component
 1 file changed, 3 insertions(+)

The check did not fail. It did not run at all. In Lefthook's default matcher (gobwas), ** matches one or more directories, not zero or more, so src/components/**/*.ts requires at least one directory between src/components/ and the file - it matches src/components/Button/Button.ts but not src/components/Modal.ts. With no matching files, Lefthook prints (skip) no files for inspection and moves on, and the commit succeeds. A guard you believe is watching is worse than no guard, because you stop checking by hand.

There are two ways out. The recommended one is to switch to standard glob semantics for the whole config:

glob_matcher: doublestar

With doublestar, **/ matches zero or more directories, so src/components/**/*.{ts,tsx} matches Modal.ts as expected - this is the reason the setting appears at the top of the config above. The catch is that the same setting also makes * separator-aware: a bare *.ts now matches only files in the repository root, where the default matcher had let * cross /. That is why every file glob in the config above uses **/*.{...}: with doublestar, that is how you say "at any depth".

The second option is to keep the default matcher and write the pattern for its rules: because * crosses / there, src/components/*.{ts,tsx} already matches at any depth. That works, but it depends on a matcher behavior most people do not expect, so I prefer the explicit switch. Either way, the lesson generalizes: after you add a file-filtering rule, verify it actually fires. Lefthook's (skip) no files for inspection line in the output is the tell.

Make the Agent Run the Checks Too

The hooks above fire on git commit and git push. An agent that edits twenty files and stops - without committing - never triggers them. Lefthook has a beta feature for exactly this: an ai: block that declares which of your hooks an agent should call on which of its own events. During lefthook install, Lefthook generates the provider's settings file for you.

ai:
  claude:
    Stop: verify
  cursor:
    stop: verify

verify:
  jobs:
    - name: typecheck
      run: pnpm check:types
    - name: unit tests
      run: pnpm test:unit

Stop is Claude Code's event for "the agent finished responding", and stop is the Cursor equivalent; both map to the verify hook that Lefthook then runs. Supported providers are claude, codex, cursor, and copilot. Running lefthook install with the config above updates .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "pnpm exec lefthook run verify" }]
      }
    ]
  }
}

Note the command. Generated hook commands use the top-level lefthook: value when it is set - here pnpm exec lefthook - and otherwise fall back to the absolute path of the binary that ran install. Since that absolute path is machine-specific and would poison a committed settings file, setting lefthook: to a portable command is the difference between a file your teammates can share and a file that only works on your laptop. This feature is marked beta, so treat the generated output as version-sensitive and keep an eye on it when you upgrade.

Lefthook vs. pre-commit vs. Husky

	Lefthook	pre-commit	Husky
Runtime	Single Go binary, no runtime	Python framework	Node.js
Config	One YAML/TOML/JSON file	`.pre-commit-config.yaml`	Shell scripts in `.husky/`
Runs against	Staged/pushed/all files via templates	Staged files by default	Whatever the script does
Parallel jobs	Yes	Limited	No (manual)
Isolated tool envs	No (uses your project's tools)	Yes (per-hook language envs)	No
Language ecosystems	Any (it just runs commands)	Many, via hook repos	Any, in Node projects

There is no objective winner here; pick the one that fits how your repository already works. If you rely on pre-commit's managed, per-language hook environments, stay there - that isolation is real value. If your repo is Node-based, Husky is familiar and perfectly capable. I reach for Lefthook for three reasons: it is one binary so nothing new has to be installed at runtime, its jobs run in parallel so the hook stays fast, and {staged_files}, stage_fixed, and glob filtering are built into the config rather than pushed into scripts. As always with tools, the right answer is the one your team will actually keep running.

Troubleshooting & Gotchas

A glob that matches nothing silently skips the job. This is the failure from the section above, and it is the most dangerous one because the hook reports success. ** in the default gobwas matcher means one or more directories; (skip) no files for inspection in the output means your filter is excluding everything. Set glob_matcher: doublestar and use **/ where you mean any depth.

stage_fixed only works on pre-commit, and it needs the index. It calls git add after the job rewrites files, so it cannot fix anything on pre-push or a custom hook. Keep auto-fixing jobs on pre-commit and sequential: if several jobs run in parallel and rewrite the index at the same time, keep them out of that batch.

--no-verify and LEFTHOOK=0 bypass everything. Hooks are a convenience gate, not a security boundary. For rules that must hold, run the same checks in CI (lefthook run pre-commit --all-files) and make that job required. Do not rely on the client-side hook as your only enforcement.

pnpm gates the postinstall script. The lefthook npm package installs hooks from a postinstall script, but pnpm blocks dependency build scripts by default. In pnpm 11/12 the setting moved from pnpm.onlyBuiltDependencies in package.json to an allowBuilds map in pnpm-workspace.yaml; approve it and the postinstall runs. Failing that, lefthook install explicitly does the same thing.

Fresh releases can be held back by supply-chain policies. pnpm refused to install the just-published lefthook@2.1.17 because it was inside the default minimumReleaseAge window; minimumReleaseAge: 0 (or waiting out the window) is the adjustment. Useful to know when a version you just saw released will not install yet.

A long file list is split into several commands. Command-line length is capped on every OS, so Lefthook runs your command in batches when {staged_files} is large. A linter that prints per-run summaries will print one per batch.

Check that the hooks are actually installed. A fresh clone has no hooks until lefthook install runs - the npm postinstall usually handles it, but clones that skip install scripts will not, and CI=true makes the postinstall skip on purpose. lefthook check-install returns exit code 0 only when the hooks are present and in sync, which makes it a cheap guard in a setup script.

Conclusion

Agentic coding has not changed the need for quality gates; it has made them more valuable, because the volume of change goes up while the attention per change goes down. Writing the rules in an instruction file is still worth doing, but it is not enforcement. A Lefthook config is a few dozen lines of YAML that makes the same checks run on every commit and push, whoever - or whatever - wrote the code, and the beta ai: block extends the same jobs to the agent's own events. Start with one hook: format and lint the staged files, re-stage the fixes, and refuse the commit if the tests fail. In a large codebase, that one gate prevents more bad diffs than any prompt.

Resources

FAQ

My AI coding agent keeps committing code that fails lint and tests. How do I stop it?

Install Git hooks with Lefthook so the checks run before the commit is created. Add a lefthook.yml with a pre-commit hook whose jobs run your formatter, linter, type checker, and tests, then run lefthook install once per clone. If any Lefthook job exits non-zero, the commit is aborted, so code that fails your checks cannot be committed even if an agent ignored the same rules written in an instruction file.

How do I make Git hooks run automatically after every clone without asking each developer to install them?

Add Lefthook to your project's dependencies - for example pnpm add -D lefthook or npm install --save-dev lefthook. The package's postinstall script runs lefthook install, which writes the hooks into .git/hooks for each developer automatically. Note that pnpm blocks dependency build scripts by default, so you must approve Lefthook's build in pnpm-workspace.yaml, and a fresh clone can always run lefthook install manually.

Why did my Lefthook job not run and print "no files for inspection"?

Lefthook's default glob matcher treats ** as one or more directories, so a pattern like src/components/**/*.ts does not match src/components/Modal.ts - it matches nothing, and the job is skipped instead of failing. Set glob_matcher: doublestar in lefthook.yml so **/ matches zero or more directories, and remember that with doublestar a bare *.ts only matches the repository root, so use **/*.ts for files at any depth.

How do I make Lefthook commit the files that a formatter fixed?

Set stage_fixed: true on the Lefthook job. After the job's command rewrites the staged files, Lefthook runs git add on them, so the corrected content is included in the same commit. stage_fixed works only on the pre-commit hook, and jobs that use it should run sequentially rather than in parallel because they modify the Git index.

Can I skip Git hooks for a single commit?

Yes. Run LEFTHOOK=0 git commit to disable Lefthook for that one command, or git commit --no-verify to skip Git hooks entirely. Both are intentional escape hatches; because either can bypass a pre-commit hook, rules that must always hold should also be enforced in CI by running lefthook run pre-commit --all-files.

How do I run Lefthook hooks in CI when hooks are a local Git feature?

Install the Lefthook binary in your CI job, then invoke the hook explicitly instead of relying on .git/hooks: pnpm exec lefthook run pre-commit --all-files. The --all-files flag replaces {staged_files} with every tracked file, since there is no staging area to speak of. Setting CI=true makes the Lefthook npm package skip its postinstall hook installation, which is the desired behavior in CI.

Does Lefthook work with Claude Code, Cursor, Codex, and GitHub Copilot?

Yes, through the beta ai: block in lefthook.yml. You map a provider's event names - for example Claude Code's Stop or Cursor's stop - to a Lefthook hook, and lefthook install generates the provider's settings file so the agent calls lefthook run <hook> when that event fires. The feature supports claude, codex, cursor, and copilot, and because it is beta its generated files are worth re-checking after a Lefthook upgrade.

Is Lefthook faster than pre-commit or Husky?

Lefthook is distributed as a single Go binary with no runtime to load, and it can run a hook's jobs in parallel, so it does not pay the startup cost of a Python framework or a Node process. pre-commit's advantage is its isolated per-language hook environments, and Husky's is familiarity in Node projects, so the choice usually comes down to which model fits your repository rather than raw speed.

Achieving Instant Navigations in Next.js 16.3

uninterrupted — Wed, 07 Oct 2026 07:09:06 +0000

Server Components can reduce client-side JavaScript, keep sensitive logic on the server, and prevent data-fetching waterfalls. But they also introduced a frustrating user experience in many dynamic applications: after clicking a link, the user sometimes had to wait for the server before seeing the next screen.

Next.js 16.3 addresses this problem with Instant Navigations, an opt-in set of rendering, prefetching, development, and testing tools. The goal is not to make every data request finish immediately. It is to make sure the application always has meaningful UI ready when navigation begins.

This is particularly useful for e-commerce platforms, dashboards, and account areas. These applications cannot prerender every personalized state at build time, but they should still respond to clicks without a visible pause.

In this guide, I will explain how Instant Navigations work, how to choose between streaming and caching, and how to protect navigation performance with Playwright tests.

Why Dynamic Next.js Navigations Can Feel Slow

In a traditional server-driven navigation, the sequence often looks like this:

The user clicks a link.
The browser requests the target route from the server.
The server reads data and renders the route.
The browser finally displays the next UI.

The architecture can be efficient, but the delay between the first and fourth steps is visible. A client-driven SPA usually feels more responsive because it already has enough code in the browser to display the next screen or its loading state immediately.

Before Next.js 16.3, teams had two common ways to reduce this delay:

prerender the full page at build time, which does not work for every dynamic or personalized route
fully prefetch each destination with <Link prefetch={true}>, which can generate unnecessary requests and increase server load

A loading.tsx file could provide an immediate loading state, but it was easy to forget and applied at the route-segment level rather than around the exact data dependency.

Instant Navigations provide a more precise model. Instead of asking whether the whole route is static or dynamic, you decide which parts can be ready before the click and which parts should arrive later.

Enabling Instant Navigations in Next.js 16.3

Instant Navigations are opt-in in Next.js 16.3. Enable Cache Components and Partial Prefetching in next.config.ts:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
}

export default nextConfig

cacheComponents enables the explicit caching model built around 'use cache', cacheLife, and cacheTag. It also allows routes to combine prerendered UI with dynamic content behind Suspense boundaries.

partialPrefetching changes how Next.js prepares routes on the client. Instead of treating prefetching as an all-or-nothing decision, Next.js can prefetch only the reusable UI needed to start a navigation.

Enabling cacheComponents is a migration step, not just a performance flag. During production builds, Next.js attempts to prerender as much of a route as possible and can report an error when runtime or uncached data is accessed outside a Suspense boundary. Each case must be streamed behind Suspense, cached with 'use cache' when appropriate, or explicitly allowed to block with export const instant = false. Existing applications may also need to remove incompatible route segment configuration such as dynamic, revalidate, or fetchCache.

These behaviors are planned to become defaults in a future major version. In 16.3, enabling them explicitly gives teams time to review their asynchronous boundaries and migration requirements.

The Core Model: Stream, Cache, or Block

When a route depends on asynchronous data, Next.js 16.3 asks you to make the intended behavior explicit. There are three useful choices.

1. Stream dynamic content with Suspense

Use <Suspense> when the data must stay fresh or depends on the active request. The fallback becomes part of the route shell, so it can appear immediately while the server renders the final content.

This is a good fit for:

inventory and delivery estimates
cart state
account-specific data
live analytics
personalized recommendations

The navigation is instant because the user sees the fallback without waiting for the dynamic operation. The final data still arrives from the server later.

2. Cache reusable content with `'use cache'`

Use 'use cache' when the result can be safely reused. Cached UI can be included in the prefetched response and displayed immediately during navigation.

This works well for:

product descriptions
category content
CMS blocks
public pricing shared by a region
configuration that changes infrequently

The cache boundary should follow the business meaning of the data. Content that is safe to share globally should not be mixed with customer-specific prices or session state.

3. Allow the route to block

Not every route needs to navigate instantly. If displaying a loading state would be misleading and the route should wait for complete server output, mark that decision explicitly:

export const instant = false

This can be appropriate for a simple content page where the team prefers to show the complete article at once, or for a flow where a partial state would create confusion.

The important change is that blocking becomes an intentional route decision rather than an accidental result of one unresolved data dependency.

How Partial Prefetching Changes the Network Cost

The previous prefetching model could issue a request for every visible link. Consider an account sidebar with twenty links to /orders/[id]. Even though all links share the same route structure, the browser could prefetch each destination separately.

With Partial Prefetching, Next.js can generate one reusable shell for /orders/[id], store it in the browser, and use it for multiple links during the session. This is closer to route-level code splitting in a SPA: the browser receives enough UI to react immediately, but it does not need the complete data for every possible destination.

If a particular link deserves a deeper prefetch, you can still opt in:

<Link href={`/products/${product.slug}`} prefetch={true}>
  {product.title}
</Link>

Next.js then prerenders as much of that destination as it safely can. Synchronous values from the URL and content marked with 'use cache' can be included, while request-bound work remains behind its Suspense boundary.

This avoids a common tradeoff in dynamic applications: either prefetch nothing and make the user wait, or prefetch complete pages and make the server do work that may never be used.

A Practical E-Commerce Example

A product page usually combines data with very different freshness requirements:

product copy and media are broadly reusable
inventory changes often
customer pricing may depend on identity, region, or sales channel
the cart belongs to the current session

Making the whole page dynamic means one slow operation can block navigation. Caching the whole page is more dangerous because it can expose stale or private data.

A better boundary looks like this:

import { Suspense } from 'react'
import { cacheLife, cacheTag } from 'next/cache'

async function ProductSummary({ slug }: { slug: string }) {
  'use cache'

  cacheTag(`product:${slug}`)
  cacheLife('hours')

  const product = await getProduct(slug)

  return (
    <section>
      <h1>{product.title}</h1>
      <p>{product.description}</p>
    </section>
  )
}

async function Inventory({ slug }: { slug: string }) {
  const inventory = await getLiveInventory(slug)

  return <p>{inventory.available} items available</p>
}

export default async function ProductPage({
  params,
}: PageProps<'/products/[slug]'>) {
  const { slug } = await params

  return (
    <main>
      <ProductSummary slug={slug} />

      <Suspense fallback={<p>Checking availability...</p>}>
        <Inventory slug={slug} />
      </Suspense>
    </main>
  )
}

The product summary can be cached and reused. Live inventory remains dynamic, but it no longer prevents the route from showing useful content. During navigation, the browser can display the product UI or its prepared shell first and fill in availability when the server responds.

For a real storefront, customer-specific pricing should follow the same principle as inventory: isolate it in a private or request-time boundary instead of adding cookies or session access to the entire page.

Finding Slow Routes with Instant Insights

Performance problems are difficult to fix when they only appear as a vague feeling that the application is slow. Next.js 16.3 adds Instant Insights to the development tools to make the problem visible.

When you encounter a non-instant navigation during development, Instant Insights identifies the route and points to the asynchronous work that blocks its shell. In most cases, the fix is one of the following:

move request-specific work below a Suspense boundary
mark reusable work with 'use cache'
move a blocking dependency out of a shared layout
explicitly accept blocking with export const instant = false

The Navigation Inspector complements this by pausing navigation at the prefetched shell. This lets you inspect exactly what the user can see before dynamic content arrives. It is useful because production prefetching is normally disabled in development, where loading behavior can otherwise be difficult to reproduce accurately.

Testing Instant Navigations with Playwright

A route that feels instant today can become blocking after a small refactor. A new cookies() call in a shared component or a moved Suspense boundary may be enough to change the result.

Next.js 16.3 includes the instant() helper in @next/playwright. It temporarily holds back dynamic content, allowing the test to assert which UI is available without waiting for the network:

import { expect, test } from '@playwright/test'
import { instant } from '@next/playwright'

test('product navigation shows useful UI instantly', async ({ page }) => {
  await page.goto('/products/shoes')

  await instant(page, async () => {
    await page.click('a[href="/products/hats"]')
    await page.waitForURL((url) => url.pathname === '/products/hats')

    await expect(page.locator('h1')).toContainText('Baseball Cap')
    await expect(page.getByText('Checking availability...')).toBeVisible()
  })

  await expect(page.getByText(/items available/)).toBeVisible()
})

The test describes a user-facing contract:

the product title must be available immediately
the inventory fallback must be visible while live data is pending
the final inventory must appear after the dynamic work completes

This is more useful than testing an arbitrary duration such as 100 milliseconds. Network and CI timing can vary, but the boundary between prefetched UI and network-dependent UI is deterministic.

The v0 team used this property to improve real routes with a coding agent. The agent wrote a failing instant() test, moved or cached the blocking work, rebuilt the application, and repeated the process until the test passed. The resulting 16 tests were kept in CI to prevent future regressions.

Where Teams Usually Get It Wrong

Mistake 1: Treating “instant” as “fully loaded”

Instant Navigations do not make databases or APIs respond with zero latency. They guarantee that useful UI can respond to the click without waiting for those systems.

The distinction matters. A complete page may still stream in over time, but the application should never look unresponsive.

Mistake 2: Placing Suspense too high in the tree

Wrapping an entire page in one Suspense boundary may technically make navigation instant, but the user will see a generic full-page skeleton. Place boundaries close to the data that actually needs to wait so stable navigation, headings, and controls remain visible.

Mistake 3: Reading dynamic data in a shared layout

A session or request-dependent operation near the root can block many routes at once. Keep shared layouts focused on reusable UI and move dynamic reads into the components that need them.

Mistake 4: Enabling full prefetching on every link

prefetch={true} is still useful, but it should represent a deliberate choice to prepare more than the route shell. Applying it everywhere can recreate the server and network cost that Partial Prefetching is designed to avoid.

Mistake 5: Using meaningless loading states

An instant blank rectangle is not a good user experience. The shell should preserve the layout and provide enough context for the user to understand where the navigation is going.

For a product page, that may include the title, gallery frame, price area, and an inventory placeholder. For an account page, it may include the navigation, page heading, and form structure.

A Practical Adoption Strategy

For an existing Next.js application, avoid changing every route at once. Start with the journeys where a delay has the largest user or business impact.

Enable cacheComponents and partialPrefetching in a branch.
Use Instant Insights to identify blocking navigations.
Choose one important journey, such as category to product or cart to checkout.
Write a failing test with instant() that describes the minimum UI required after the click.
Stream request-bound data and cache only content that is safe to reuse.
Inspect the shell with Navigation Inspector.
Keep the test in CI after the route passes.

This process turns perceived performance into an architectural requirement that can be reviewed and tested. It also creates a clear stopping point: the work is complete when the intended shell is visible without network-dependent content.

Final Thoughts

The most important part of Instant Navigations is not another prefetch option. It is the clearer boundary between UI that must be ready for a click and data that is allowed to arrive later.

For dynamic applications, this removes the need to choose between a server-driven architecture and SPA-like responsiveness. Server Components can continue to handle rendering and sensitive data, while Suspense, Cache Components, and reusable route shells keep navigation responsive.

The best result comes from combining three decisions:

stream data that must remain dynamic
cache content that is genuinely reusable
block only when waiting is an intentional product choice

Once those decisions are protected by instant() tests, navigation performance stops being something that can disappear unnoticed during the next refactor.

WooCommerce, Shopify, or Medusa: Choosing an E-Commerce Platform for Bullion Dealers

Michał Miler — Wed, 30 Sep 2026 09:01:15 +0000

WooCommerce vs. Shopify vs. Medusa: Choosing an E-Commerce Platform for Bullion Dealers

A bullion dealer's product catalog doesn't have prices. It has formulas. A 1 oz gold coin isn't "$2,100" the way a t-shirt is "$25" — it's weight × today's spot price × your spread, plus whatever fixed minting or handling premium you charge on top. Spot prices for gold and silver move throughout the trading day, sometimes several times a minute, which means the "correct" price for every SKU in the catalog is technically wrong again a few seconds after you last calculated it.

Most e-commerce platforms were not built around that assumption. They were built around the idea that a product has a price, someone sets it, and it stays put until someone changes it again. That's a completely reasonable default for almost every category of goods sold online — until the goods themselves are priced off a market that never stops moving.

This creates a specific set of requirements that a general-purpose store doesn't have to think about:

Live pricing tied to a market feed, not a value someone typed into an admin panel.
A pricing formula per product or product line — spread, fixed premiums, percentage premiums — layered on top of that feed.
Frequent updates, ideally continuous during market hours, not a batch job that runs once an hour.
Checkout price locking — the price a customer sees when they start checkout has to hold for a defined window, or the order has to be rejected, otherwise either the dealer or the customer eats the difference.
Reliability when the feed itself fails — a stale or missing spot price can't silently turn into a wrong price or a broken checkout.
Integrations with ERP systems, inventory/vaulting software, and payment processors that are comfortable underwriting a high-value, high-risk category.
Room to customize the pricing logic as the business's spreads, premium structure, or product mix changes.

WooCommerce, Shopify, and Medusa can all run a bullion store. The difference is how much of the above you get by default, how much you build yourself, and how much friction you hit doing it. This article compares all three specifically against that list — not as a generic "which platform is better" question, but as the specific decision a bullion or precious-metals dealer is actually facing.

Quick Reference

	WooCommerce	Shopify	Medusa
Live spot price → product price	Via third-party plugins (e.g. real-time precious-metals pricing plugins); price is written to the product record	Not native — price is a stored variant field; apps push updates via the Admin API on a schedule, not per-request	Not native either, but the modular architecture is built for computing a price at read time instead of storing one
Formula-based premiums/spreads	Supported by dedicated bullion pricing plugins	Requires a custom app or third-party pricing app; no first-class concept of spot + spread + premium	Add a custom pricing module (or use an existing one, like Fluctum) that applies the formula
Real-time storefront price updates (no reload)	Not native; needs custom JS polling on top of a pricing plugin	Not native; storefront reflects whatever price was last written by the app	Not native to Medusa core; a pricing module can add it (Fluctum uses Server-Sent Events)
Checkout price locking / quote expiry	No built-in concept — cart totals recalculate from the current stored price on every load; locking is custom dev work	No built-in concept; Shopify Functions customize discounts, delivery, and validation, not a live commodity price	No built-in concept in core Medusa; a module can add a lock-and-validate step (Fluctum does this)
Behavior on feed outage	Depends entirely on the plugin	Depends entirely on the app	Depends entirely on the module — a well-built one falls back to the last known price
Tiered / wholesale pricing	Needs a wholesale/dynamic-pricing plugin (e.g. Wholesale Customers For WooCommerce)	Native volume pricing and quantity rules exist, but the more advanced B2B catalog features are Shopify Plus-only	Native in core — quantity tiers and customer-group price rules, no plugin or plan gate required
Extending with new integrations (tax, ERP, payments)	Full PHP access, thousands of hooks/filters, huge plugin ecosystem	Public apps run on any plan; custom apps with Shopify Functions require Shopify Plus	Modules → workflows → provider interfaces plugin; extend without forking, no plan gate
Hosting model	Self-hosted (or managed WordPress hosting); you own ops	Fully managed by Shopify	Self-hosted or Medusa Cloud (managed)
Transaction fees & monthly cost	Gateway fees (~2.9% + 30¢) + hosting & plugin costs. No platform fees on GMV.	Shopify Plus plan ($2,000+/mo) required for custom checkout logic, plus a 0.15% platform fee on third-party gateways.	Gateway fees only. No platform fees on GMV. Costs are hosting (self-hosted or Medusa Cloud) and development.
Best fit	Smaller catalog, WordPress-based stack already in place, moderate technical budget	Fast launch, managed infrastructure, simpler or less frequent pricing updates	Dealers who need real-time pricing plus specific ERP, payment, or wholesale requirements built once and owned outright

Why Bullion E-Commerce Doesn't Behave Like a Normal Store

Before comparing platforms, it's worth being precise about what's actually different, because it's easy to under-scope this as "just update the price more often."

The price is derived, not entered. A normal product's price is a fact you record. A bullion product's price is the output of a calculation: current spot price for that metal, times the product's weight, times a spread factor, plus any fixed or percentage premium (minting costs, rarity, packaging). Change the spot price and every affected SKU's correct price changes with it — instantly, in principle.

Update frequency is high and continuous. Gold and silver spot prices move throughout market hours. A store that only updates prices a few times a day is either giving away margin between updates (selling below the current market) or overcharging (selling above it) — and both outcomes cost the dealer customers over time, just in different ways.

Checkout needs a quote, not a live price. A customer needs the price to hold still for the few minutes it takes to fill in an address and pay. If the price is still tied to a live feed while payment is being processed, the amount charged can differ from the amount the customer agreed to. The standard fix is a "lock": freeze the computed price the moment checkout starts, attach an expiry to it, and refuse to complete the order if that lock has expired by the time payment is submitted.

A feed outage can't become a wrong price. If the spot-price provider goes down for ten minutes, the store has to keep functioning — showing the last known good price and continuing to accept orders — rather than either breaking checkout or, worse, silently pricing products at $0 or a stale multi-day-old value.

The integration surface is wider than checkout. Bullion dealers commonly need to sync with an ERP or inventory/vaulting system, and payment processing for precious metals is frequently treated as a reviewed or higher-risk category by processors — worth confirming with your payment provider early, regardless of which platform you choose.

None of this is exotic engineering. But it's also not something any of the three platforms below solves out of the box.

WooCommerce for Bullion Dealers

WooCommerce's strength here is exactly its strength everywhere else: it's open PHP, self-hosted, and has an enormous plugin ecosystem, so there's a real, mature market of niche plugins for this exact use case. Plugins like Precious Metals Product Prices for WooCommerce advertise real-time precious-metals pricing, product sync, and wholesale drop-ship order automation specifically for bullion and coin stores, and simpler options like Gold Price Based on Weight calculate a product's price from a global price-per-gram figure and the product's weight. These plugins genuinely solve the "pull a live price and multiply it out" problem.

Where WooCommerce runs into friction is checkout behavior. WooCommerce recalculates the cart and checkout totals from each product's currently stored price every time the cart is loaded — there's no built-in concept of "hold this exact quoted price for the next 10 minutes, then reject the order if it expires." A dealer who wants that has to build it as custom logic on top of one of the pricing plugins: snapshotting the computed price into cart or session data, and validating it again before the order is allowed to complete.

Real-time storefront updates (a price that visibly ticks upward or downward while a customer is looking at the cart, without a page reload) also aren't native. Even with WooCommerce's newer Cart and Checkout blocks, the built-in reactivity is around cart operations like changing a quantity — it won't push an externally changing spot price into an already-open page without custom JavaScript polling a price endpoint yourself.

WooCommerce is a good fit for a smaller dealer already running WordPress, with a catalog that doesn't need sub-minute pricing precision, and a technical budget that can stretch to some custom development for checkout locking.

Shopify for Bullion Dealers

Shopify's case is speed and operational simplicity: managed hosting, PCI compliance handled for you, a fast path to launch, and by far the largest app ecosystem of the three. For a dealer who wants to be selling quickly and isn't chasing sub-minute pricing precision, that's a legitimate, low-friction starting point.

The friction shows up in how Shopify models price and checkout. A product variant's price is a stored field, not a computed value — a pricing app updates it by calling the Admin API on a schedule or in response to a webhook, which is fundamentally a batch update loop, not a live per-request formula tied to a streaming feed. Checkout customization today runs through Shopify Functions: discount functions, cart/checkout validation functions, delivery and payment-method customization functions, and similar. Every documented Function category is scoped to adjusting discounts, validation, or checkout behavior around an existing price — none of them is designed to recompute a commodity-linked unit price from a live formula on the fly.

There's also a plan gate to be aware of: per Shopify's own documentation, stores on any plan can install a public app from the Shopify App Store that happens to contain Functions, but building and running a custom app with Shopify Function APIs requires a Shopify Plus plan. That matters for a dealer planning to build bespoke pricing logic in-house rather than relying entirely on a third-party app.

Shopify is a good fit for a dealer prioritizing managed infrastructure and fast launch, where pricing updates on the order of minutes-via-API (rather than a continuous live feed) and standard discount/checkout customization are acceptable trade-offs.

Medusa's Extensibility: Building Only the Part That's Actually Custom

Medusa doesn't ship dynamic commodity pricing, ERP connectors, or a high-risk-friendly payment processor out of the box — no platform in this comparison does. The difference is what it costs to add them. Medusa's core is organized as modules (self-contained data and logic for one domain — pricing, tax, payments, inventory), workflows (business logic composed of retryable, rollback-safe steps), and module links (which connect data across modules without collapsing everything into one table). That structure means a dealer-specific requirement gets built as an addition that plugs into Medusa's existing provider interfaces and event system, not as a fork of the platform or a rebuild of checkout, promotions, multi-region support, or order management.

This isn't a theoretical benefit. u11d's own @u11d/medusa-avalara plugin is a working example of the same pattern applied to tax instead of pricing. It installs into an existing Medusa store, registers itself through Medusa's tax-provider interface, and takes over the full transaction lifecycle: it creates a sales invoice in Avalara when an order is placed, commits it when the order completes, and voids it if the order is canceled — all without any change to Medusa's own cart, checkout, or order code. A dealer picks Avalara as their tax provider in the Medusa admin the same way they'd pick any other provider, and everything else in the store keeps working exactly as it did before.

The same pattern generalizes to the other systems a bullion dealer actually needs to connect:

ERP and vaulting/inventory sync. Medusa emits events for order placement, fulfillment, and inventory changes. A module can subscribe to those events, and a workflow can push the relevant data out to an ERP or a vaulting/inventory system — the integration lives in its own module, not scattered across checkout code.
Payment processors. Medusa's payment system is provider-based, with Stripe, PayPal, Klarna, and Adyen supported out of the box. Bullion dealers often need a processor comfortable underwriting a high-value, high-risk category rather than a default consumer gateway — adding one means implementing Medusa's payment provider interface, not replacing the checkout flow.
Tiered and wholesale pricing. This one doesn't even require an add-on: Medusa's core Pricing Module natively supports quantity-based tiers (a lower unit price once a customer buys 10+ or 50+ ounces) and rule-based pricing by customer group, region, or cart total — genuinely useful for a dealer serving both retail customers and wholesale/dealer accounts from the same catalog.
Market-driven pricing. The same module pattern is what lets a plugin compute a product's final price at read time from a live spot price plus a merchant-configured formula, without ever writing that value into Medusa's own price records — covered in detail below with Fluctum.

None of this requires forking Medusa or building a bullion-specific commerce platform from zero. It's the difference between building the tax logic, the ERP sync, the payment integration, and the pricing engine all from scratch, and building only the one piece that's actually specific to the business on top of a platform that already handles everything else.

The Checkout Price-Locking Problem

Across all three platforms, this is the piece that consistently doesn't come for free: freezing a computed price at the moment a customer starts checkout, and refusing to let the order complete if that lock has expired. It's not a hard problem conceptually, but getting it right requires the platform to support:

Recording the exact price, and the inputs that produced it (spot price, spread, premium), at the moment checkout begins.
An expiry window on that record.
A hard check, at order completion, that rejects the order if the lock is missing or expired — not just a soft warning.

WooCommerce and Shopify both leave this entirely to custom development or a third-party app's own implementation of it. Neither has a first-class "price lock" primitive in its core commerce model. This is precisely the gap Fluctum was built to close on Medusa.

Fluctum: Market-Driven Dynamic Pricing for Medusa

Fluctum is an open-source, MIT-licensed Medusa plugin built by u11d that implements the full pricing pipeline described above, so a Medusa store doesn't need a custom-built pricing engine to sell spot-priced goods.

It fetches live spot prices on a schedule, and computes each product's final price from the current spot price, the product's weight, and a merchant-configured formula — a spread factor, a fixed spread fee, a percentage premium, and a fixed premium (for minting or handling costs, for example) — without ever writing that computed value back into a Medusa product's own price fields. The storefront reflects price changes in real time via Server-Sent Events, so a customer watching the cart sees the price move without a page reload.

At checkout, Fluctum locks the computed price into an auditable record and gives it an expiry. If a customer completes payment before that lock expires, the order proceeds at the locked price. If the lock has expired — because checkout took too long, or the price moved and wasn't refreshed — order completion is rejected rather than silently charging a stale amount. If the spot-price feed itself goes down, the storefront and checkout keep working off the last known good price instead of breaking.

Because it's a Medusa plugin rather than a separate system, installing Fluctum on an existing Medusa store keeps everything else Medusa already provides — multi-region and multi-currency support, promotions, customer accounts, taxes, shipping, and payments — and adds market-driven pricing on top of it. It's free to use and, being open-source, can be extended by any developer to sync with an ERP, add payment providers, or add business logic specific to a given dealer.

We've written about Fluctum from two angles: a business-facing overview of the build-vs-buy decision for store owners deciding whether to build this themselves, and a developer guide covering the pricing formula, the price-lock lifecycle, and a full local setup walkthrough. A live demo is available at fluctum.medusajs.site.

Cost Comparison

A full cost-of-ownership model for a bullion dealer is more than just the monthly subscription fee. It's a mix of platform fees, transaction fees as a percentage of gross merchandise value (GMV), app/plugin costs, and hosting or infrastructure overhead.

WooCommerce: The core software is free, so there's no monthly platform fee. Costs are a combination of:
- Hosting: A reliable WordPress host capable of handling e-commerce can range from $25 to $100+ per month.
- Transaction Fees: These are charged by your payment gateway (e.g., WooCommerce Payments, Stripe, PayPal) and are typically around 2.9% + $0.30 per transaction for US cards. These are often negotiable for high-volume merchants.
- Plugin Costs: A robust "Pro" version of a precious metals pricing plugin is essential and can cost $100 - $300 per year.
- Operational Overhead: You are responsible for all maintenance, security, and updates.
Shopify: Pricing is based on a monthly subscription, but the need for custom checkout logic creates a significant cost hurdle.
- Monthly Subscription: To implement the required checkout customizations for live pricing, a dealer must use the Shopify Plus plan, which starts at $2,000/month.
- Transaction Fees: If you don't use Shopify Payments, Shopify adds its own fee on top of your payment gateway's charge. This fee is 0.15% on Shopify Plus—a direct tax on your GMV.
- App Costs: You'll need a third-party app for the pricing logic itself, which is an additional monthly cost.
- Development Costs: You'll need to hire developers to build a custom app using Shopify Functions to handle the live pricing at checkout.
Medusa: As an open-source framework, Medusa has no platform or transaction fees, offering the most control over your cost structure.
- Hosting: You can self-host on services like AWS or Vercel (typically $50 - $200+ per month depending on scale) or use Medusa Cloud (plans start from $29/month and scale up).
- Transaction Fees: You only pay the fees from your chosen payment processor (e.g., Stripe), with no additional platform tax on GMV.
- Development Costs: This is the primary investment. You need development resources to build and maintain the live pricing logic, integrations, and storefront. However, you only build the parts that are unique to your business, leveraging Medusa's core commerce features for the rest. Fluctum can significantly reduce this initial development cost.

Which Platform Should You Choose?

If your catalog is small and your pricing updates a handful of times a day is acceptable, WooCommerce or Shopify are both legitimate, lower-friction choices — pick based on whether you'd rather own a WordPress-based stack (WooCommerce) or hand hosting and PCI compliance to a managed platform (Shopify).

If you need pricing that genuinely tracks the live market, or you know you'll need to connect a specific ERP, tax provider, payment processor, or wholesale pricing model beyond what a plugin already covers, that combination pushes hard against how WooCommerce and Shopify are built, and it's the situation Medusa's modular architecture was built to accommodate. The same module/workflow/provider pattern that lets Fluctum add live pricing and u11d's own Avalara plugin handle tax automation is available for whatever a dealer needs to connect next — a dealer in that situation doesn't have to build each of those pieces from scratch.

Conclusion

For a bullion dealer, the choice between WooCommerce, Shopify, and Medusa is a decision about where you want to spend your money and how much control you need.

Shopify is the highest-cost option due to the non-negotiable requirement of the Shopify Plus plan ($2,000+/month) to achieve true dynamic pricing at checkout. You're paying a premium for managed infrastructure, but also a platform tax on every transaction.
WooCommerce offers a much lower entry cost, with no monthly platform fees. It's a viable option if your pricing logic is relatively simple and you have the technical resources to manage a WordPress/WooCommerce stack securely.
Medusa presents the lowest long-term platform cost, with zero platform fees on your GMV. The investment is in development, giving you complete ownership and control over the critical pricing and checkout logic that defines your business. For a serious dealer planning for scale, avoiding a platform tax on a high-GMV business is a significant financial advantage.

Medusa's modular architecture is what makes this control possible and cost-effective. The same pattern that lets Fluctum add live spot pricing is what lets u11d's own Avalara plugin automate tax, and it's the same pattern available for any other integration a dealer needs. u11d builds and maintains these open-source tools and works with bullion dealers on their Medusa storefronts precisely because of this flexibility. If live market pricing and long-term cost of ownership are your primary concerns, that's the problem Medusa, and by extension Fluctum, is built to solve.

MinIO Is Deprecated: Best Alternatives for S3-Compatible Storage

Bartek Gałęzowski — Mon, 28 Sep 2026 10:16:42 +0000

For years, MinIO was the obvious answer whenever an engineering team needed S3-compatible object storage outside AWS. You wanted an S3-compatible API on Kubernetes? You needed object storage for backups? You wanted something you could run locally with Docker Compose? The answer was the same - MinIO.

That recommendation has changed.

In 2026, the open-source MinIO project is no longer a maintained project in the way engineers historically expected it to be. The upstream GitHub repository was archived on April 25, 2026, and its README explicitly states that the repository is no longer maintained.

That raises an obvious question:

What should replace MinIO?

There isn't a single answer. Three projects are particularly worth looking at: Garage, RustFS, and SeaweedFS. All three provide S3-compatible storage, but they are built around quite different ideas. Garage focuses heavily on decentralized and geographically distributed object storage, RustFS is particularly interesting for engineers looking for something close to the MinIO model, while SeaweedFS takes a much broader approach and combines object storage with distributed file storage and other storage interfaces.

The important thing is therefore not simply to find "the next MinIO", but to understand what each project is actually designed to do.

What actually happened to MinIO?

The MinIO repository on GitHub is now archived and read-only. Its current README states:

"THIS REPOSITORY IS NO LONGER MAINTAINED."

For any production engineer, this should immediately raise a question: what are the alternatives? But let's be realistic. Thousands of projects are still running MinIO, and many of them are running perfectly fine on the latest version they deployed. A running MinIO cluster does not magically stop serving objects because the GitHub repository was archived. If your cluster is healthy and you already have the required binaries or container images, it can continue operating. The bigger problem is the future lifecycle of the installation.

In September 2026, the minio/minio repository on Docker Hub was archived, and users started reporting that both minio/minio and minio/mc could no longer be pulled from Docker Hub. This is exactly the kind of failure that makes infrastructure engineers nervous. Imagine that your application hasn't changed at all. Your Kubernetes manifests are still valid, your infrastructure code is still valid, and your production cluster is still running. Then a node fails. You need to recreate the workload, and Kubernetes tries to pull:

image: minio/minio:latest

But the image is no longer available.

If you haven't mirrored the image to your own registry, your deployment is blocked. You may end up relying on a colleague who still has the image locally, or trying to recover an old image from somewhere else.

Alternative #1: Garage

Garage is a distributed object storage system written in Rust that implements the S3 API.

Its philosophy is somewhat different from MinIO. Garage is particularly interesting if your goal isn't simply "I want a server that looks like MinIO", but rather "I want distributed object storage that can operate across multiple locations."

Garage uses a decentralized architecture where nodes participate in the distributed storage system. This makes it particularly interesting for deployments where you might have several relatively small nodes spread across different locations instead of one large storage cluster.

For example, you could have infrastructure distributed across several sites:

flowchart LR
    subgraph SiteA["Site A (Primary DC)"]
        A1["Node 1"] --- A2["Node 2"] --- A3["Node 3"]
    end

    subgraph SiteB["Site B (Secondary / Edge)"]
        B1["Node 4"] --- B2["Node 5"] --- B3["Node 6"]
    end

    SiteA <-->|Geo-distributed sync / WAN| SiteB

This is one of the areas where Garage differs significantly from the traditional MinIO mental model.

Alternative #2: RustFS

RustFS takes a different approach from Garage, although it shares some important characteristics. It is also written in Rust and provides an AWS S3-compatible API.

For MinIO users, the interesting part is its design philosophy. RustFS explicitly describes its architecture as being inspired by MinIO's design philosophy, which makes it particularly interesting when your starting point is: "I already know MinIO, and I want something that feels familiar."

RustFS uses a distributed model consisting of nodes and drives. Conceptually, it looks like:

flowchart LR
    Client["S3 Client Traffic"] --> N3 & N2 & N1

    subgraph Cluster["RustFS Cluster (Erasure Set)"]
        subgraph N3["Node 3"]
            D5["Drive 5"]
            D6["Drive 6"]
        end
        subgraph N2["Node 2"]
            D3["Drive 3"]
            D4["Drive 4"]
        end
        subgraph N1["Node 1"]
            D1["Drive 1"]
            D2["Drive 2"]
        end
    end

The cluster is divided into sets, with drives distributed across nodes. For engineers coming from MinIO, the mental model is relatively familiar. This is what makes RustFS one of the most obvious projects to investigate if the main objective is replacing an existing MinIO installation while keeping the application layer largely unchanged.

That doesn't mean that migration is completely transparent. S3 compatibility needs to be tested against the actual application workload, and the operational model of the new cluster still needs to be understood.

Alternative #3: SeaweedFS

SeaweedFS takes a broader approach than Garage and RustFS. While both are primarily distributed object-storage systems, SeaweedFS is designed as a distributed storage platform supporting S3, FUSE, HDFS, WebDAV, SFTP, and other interfaces.

For MinIO users, this makes SeaweedFS interesting when S3 is only part of the requirement. If you simply need an S3-compatible API, SeaweedFS may provide more infrastructure than necessary. But if you need multiple storage interfaces or have workloads involving very large numbers of small objects, its architecture becomes more compelling.

Conceptually, it looks like:

flowchart LR
    subgraph Interfaces["Storage Interfaces"]
        S3["S3 API"]
        FUSE["FUSE"]
        HDFS["HDFS"]
    end

    subgraph Cluster["SeaweedFS Cluster"]
        Storage["Storage Layer"]
    end

    Interfaces --> Cluster

SeaweedFS separates storage into master servers, volume servers, and the Filer. The master manages cluster metadata, volume servers store the data, and the Filer provides a filesystem-like namespace. The S3 gateway sits on top of this architecture and can be scaled independently.

Another notable feature is its support for both replication and erasure coding, together with a volume-based design that works well with large numbers of small objects. This makes SeaweedFS worth considering for datasets, thumbnails, generated files, and other high-object-count workloads.

The trade-off is complexity. SeaweedFS offers considerably more functionality than a simple S3-compatible object store, so the additional flexibility needs to be weighed against the operational overhead.

Garage vs RustFS vs SeaweedFS

At this point, it should be clear that these three projects aren't simply three interchangeable MinIO clones.

They all provide S3-compatible storage, but they target somewhat different requirements.

Garage is focused on decentralized object storage and is particularly interesting for geographically distributed or multi-site deployments.

RustFS is the most natural project to investigate when your primary requirement is replacing MinIO with another distributed S3-compatible object store while retaining a relatively familiar architecture.

SeaweedFS takes a broader approach and makes sense when object storage is only one part of the problem. Its ability to expose the same underlying storage through S3, filesystem, HDFS, and other interfaces can be valuable for larger or more diverse storage environments.

The important distinction is therefore not simply performance or feature count. It is the architecture you want to operate.

	Garage	RustFS	SeaweedFS
Primary language	Rust	Rust	Go
S3 compatibility	Yes	Yes	Yes
Architecture	Distributed, decentralized	Distributed, decentralized	Layered distributed storage
Primary focus	Distributed object storage	S3 object storage	Object + file storage platform
MinIO migration	Requires architectural changes	Conceptually closer	Requires architectural changes
Kubernetes	Yes	Yes	Yes
Geo-distribution	Strong focus	Supported	Supported
Filesystem access	No	No	Yes
FUSE	No	No	Yes
HDFS	No	No	Yes
Small-object workloads	Good fit	Good fit	Strong focus
Erasure coding	Supported	Supported	Supported
Operational complexity	Relatively focused	Relatively focused	Higher
Best suited for	Multi-site / decentralized storage	MinIO replacement	Multi-purpose distributed storage
Migration complexity	Medium	Low–medium	Medium–high

This table is not intended to declare a winner. The projects solve different problems, and the right choice depends on the workload and architecture you need to support.

If you have multiple locations and want decentralized storage that treats geographic distribution as a fundamental part of the architecture, Garage is worth investigating.

If your main requirement is replacing MinIO with a modern, Rust-based, distributed S3-compatible object store that follows a relatively familiar model, RustFS is an obvious candidate.

If you need more than S3 — for example, filesystem access, HDFS, huge numbers of small objects, or multiple storage interfaces — SeaweedFS deserves serious consideration.

The important thing is that you don't have to choose the project with the longest feature list. You have to choose the architecture that matches your workload.

Conclusion

MinIO may no longer be the default choice it once was, but that doesn't mean there is a single project waiting to take its place. Garage, RustFS, and SeaweedFS represent three different directions for self-hosted object storage. Garage focuses on decentralized, multi-site storage. RustFS is the closest fit for teams looking for a familiar distributed S3 model. SeaweedFS goes beyond object storage and provides a broader storage platform with multiple interfaces and a design particularly suited to large numbers of objects. The era of treating MinIO as the automatic default for self-hosted S3 is over. The right replacement depends on the operational model, workload, and architecture you want to maintain long after the migration is complete.

For an existing MinIO deployment, the decision should not start with "Which project is the best?". It should start with "What do we actually need from our storage layer?"

Once you answer that question, choosing between Garage, RustFS, and SeaweedFS becomes much less about finding the next MinIO and much more about choosing the storage architecture that actually fits your infrastructure.

TypeSafe AI Jev explained: examples, use cases, and LLM comparisons

Paweł Swiridow — Wed, 23 Sep 2026 19:00:00 +0000

TypeSafe AI Jev is a model for making bounded decisions inside software. You give it text or structured state plus questions whose valid answers you define. It returns typed choices, scores, probabilities, and confidence values instead of generating prose.

That makes Jev useful for classification, routing, scoring, and review gates. It does not replace GPT, Claude, or another generative model when you need writing, code, explanations, or open-ended reasoning. Think of it as a fuzzy decision function, not a chatbot wearing a smaller hat.

Quick answer

Use Jev when:

Every valid answer can be defined before the call.
The hard part is semantic judgment, not arithmetic or deterministic policy.
Software needs probabilities or confidence to decide whether to act, retry, or escalate.
The workload repeats often enough for latency and per-call cost to matter.

Use something else when:

The output must contain newly written text, code, or an explanation.
Correctness depends on exact math, dates, permissions, or database state.
The task requires long, multi-step reasoning.
The model would be the only security or authorization boundary.

What is TypeSafe AI Jev?

TypeSafe calls Jev its first System One model. That is the company's product category for models built to make fast, structured decisions that software can consume directly. It is not a new chat interface and it is not an industry-standard model category.

The contract is simple:

state + typed questions -> Jev -> typed answers + probabilities -> application code

The state can be a string, JSON object, or array containing text. Each question defines its answer space. Jev evaluates independent questions against the same state in parallel, then your code decides what happens next.

At the time of writing, jev-latest resolves to jev-1.13.0. TypeSafe's model documentation lists it at $0.042 per million input tokens with free output tokens. The documented context limit is 64,000 tokens per request, with a separate 32,000-token limit for the state plus the longest question. Input is text only, so images, audio, and video must be converted before they reach Jev.

Pin a version when tuning thresholds and rerun evaluation before upgrading. A moving alias is convenient until it changes a production route at 02:00.

TypeSafe's launch material describes Jev as unable to hallucinate because it cannot emit a value outside the schema. That claim needs a narrower reading. Jev cannot invent a fourth result when your Choice defines three, but it can choose the wrong one. Type safety protects the shape of an answer. It does not make the judgment correct. Independent analysis from Arize makes the same distinction.

How Choice, Score, and Noul work

Jev exposes three question types:

Primitive	Question it answers	Returned data	Good fit
Choice	Which predefined option fits best?	selected option, option probabilities, confidence	intent routing, taxonomy classification
Score	Where does this fall on an ordered rubric?	weighted score, level probabilities, legend, confidence	severity, quality, urgency
Noul	How likely is this yes/no proposition?	probability from 0 to 1	detection, verification, binary review signals

A Choice can contain up to 255 options. A Score accepts between two and ten ordered levels. Choice and Score return a confidence value derived from their probability distributions; Noul returns the probability of yes without a separate confidence field.

Questions in one request are independent. If question B depends on question A, use another call or express the dependency in code. Do not assume that two differently phrased questions will obey arithmetic identities either. TypeSafe documents cases where a Noul and an equivalent-looking Choice produce different numbers because they ask different statistical questions.

Keep questions atomic. Ask separately whether a refund was requested, score impact, classify intent, then let code apply policy. Models judge fuzzy meaning; code does not reinterpret accounting rules overnight.

Run a Jev decision in Python

Install the SDK

The Python SDK requires an API key in TYPESAFE_API_KEY:

python3 -m pip install typesafe-sdk
export TYPESAFE_API_KEY='replace-with-a-key-from-console.typesafe.ai'

Use your normal secret manager in CI and production. Committing the key beside the example would turn a quick start into an incident report.

Classify and route a support ticket

This example asks one Choice, one Score, and one Noul in a single call. It then applies routing thresholds in ordinary Python.

import os
import time

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

if "TYPESAFE_API_KEY" not in os.environ:
    raise SystemExit("Set TYPESAFE_API_KEY before running this example")

INPUT_USD_PER_MTOK = 0.042  # TypeSafe list price at the time of writing

ticket = {
    "subject": "Checkout fails after payment",
    "message": (
        "Our card was charged twice and checkout still shows an error. "
        "We need this fixed today because customers cannot place orders."
    ),
    "plan": "business",
}

started = time.perf_counter()

with TypeSafeClient(model="jev-1.13.0") as client:
    response = client.system_one(
        state=ticket,
        questions={
            "department": Choice(
                instructions="Which team should own this ticket first?",
                criteria={
                    "billing": "Charges, invoices, refunds, or subscriptions",
                    "technical": "Bugs, outages, failed integrations, or broken product behavior",
                    "account": "Login, identity, permissions, or account access",
                    "other": "The ticket does not fit the other categories",
                },
            ),
            "severity": Score(
                instructions="How severely does this issue block the customer's work?",
                criteria=[
                    "Minor inconvenience with a clear workaround",
                    "Important feature is degraded but work can continue",
                    "Critical workflow is blocked or customers are losing money",
                ],
            ),
            "requests_refund": Noul(
                instructions="Does the customer explicitly ask for a refund?",
                criteria={
                    "true": "The customer directly requests money back",
                    "false": "The customer reports a charge but does not request a refund",
                },
            ),
        },
    )

elapsed = time.perf_counter() - started

department = response.choices["department"]
severity = response.scores["severity"]
refund_probability = response.nouls["requests_refund"].noul

if department.confidence < 0.65 or severity.confidence < 0.55:
    destination = "human-review"
elif severity.score > 1.5:
    destination = "incident-response"
else:
    destination = department.choice

input_tokens = response.usage.input_tokens or 0
estimated_cost = input_tokens / 1_000_000 * INPUT_USD_PER_MTOK

print(f"model={response.model}")
print(f"destination={destination}")
print(f"department_confidence={department.confidence:.2f}")
print(f"severity={severity.score:.2f}")
print(f"refund_probability={refund_probability:.2f}")
print(f"input_tokens={input_tokens}")
print(f"output_tokens={response.usage.output_tokens}")
print(f"elapsed_seconds={elapsed:.2f}")
print(f"estimated_cost_usd={estimated_cost:.8f}")

The SDK exposes separate collections for Choice, Score, and Noul answers. The thresholds are examples, not TypeSafe defaults. Set them from errors and review costs measured on your own data.

Pinning jev-1.13.0 prevents alias drift. In production, log the criteria version, probability distributions, chosen route, and human outcome.

Sample output and cost

A real run of the example above against jev-1.13.0 printed this:

model=jev-1.13.0
destination=incident-response
department_confidence=0.95
severity=2.00
refund_probability=0.06
input_tokens=528
output_tokens=77
elapsed_seconds=0.64
estimated_cost_usd=0.00002218

The usage block in the response is what makes the cost measurable without opening a billing dashboard. That call moved 528 input tokens. TypeSafe bills $0.042 per million input tokens and does not bill output tokens, so the run cost 528 / 1,000,000 * 0.042, or roughly $0.000022 at current list prices. A thousand calls of this size cost about two cents, and one dollar buys roughly 45,000 of them.

elapsed_seconds covers client setup plus the round trip, not just server time. Values move with the input, criteria, and model version, so treat the transcript as a real example rather than a fixed contract.

Practical Jev use cases

Route support requests

Support routing is the natural first pilot. Put the ticket text and relevant account context in state. Use Choice for the owning queue, Score for impact, and Noul for independent conditions such as an explicit refund request:

{
  "state": {
    "channel": "email",
    "subject": "Wrong item delivered, replacement needed before Friday",
    "message": "Order 48213 arrived with two left boots. I need the replacement before the conference on Friday or I want to cancel.",
    "account_tier": "enterprise",
    "earlier_tickets": 2
  },
  "model": "jev-1.13.0",
  "questions": {
    "queue": {
      "type": "choice",
      "instructions": "Which queue should own this ticket first?",
      "criteria": {
        "returns": "Wrong, damaged, or missing items, replacements, and shipping problems",
        "billing": "Charges, invoices, refunds, and subscriptions",
        "technical": "Product failures, errors, and defects",
        "account": "Access, identity, and permissions",
        "other": "None of the other queues fit"
      }
    },
    "impact": {
      "type": "score",
      "instructions": "How much does the problem block the customer?",
      "criteria": [
        "Minor inconvenience with a workaround",
        "The item or order cannot be used as delivered",
        "Time-critical situation or total loss of the purchase"
      ]
    },
    "wants_cancel": {
      "type": "noul",
      "instructions": "Is the customer asking to cancel an order or close the account?"
    }
  }
}

Code can accept a confident route, send uncertain tickets to a person, and apply exact entitlement rules from the account database.

Review agent actions

An agent can propose a tool call while Jev supplies a bounded semantic risk signal:

{
  "state": {
    "user_goal": "Remove generated build artifacts",
    "tool": "shell",
    "command": "rm -rf dist"
  },
  "model": "jev-1.13.0",
  "questions": {
    "risk": {
      "type": "choice",
      "instructions": "Classify the operational risk of the proposed action",
      "criteria": {
        "read_only": "Does not modify state",
        "reversible_write": "Changes state but has a reliable rollback",
        "irreversible_write": "Deletes or overwrites state without a reliable rollback",
        "unclear": "The available state is insufficient"
      }
    },
    "matches_goal": {
      "type": "noul",
      "instructions": "Does the proposed action directly match the user's stated goal?"
    }
  }
}

This is a review signal, not permission to execute. Allowlist enforcement, path validation, sandboxing, and user confirmation still belong in code. Jev's own documentation warns that adversarial text in state can move an answer, so it must not become the sole security boundary.

Check RAG evidence before generation

Jev can classify whether a retrieved passage supports a claim before a generative model writes the answer:

{
  "state": {
    "question": "Does the service retain customer prompts for training?",
    "claim": "Customer requests are not used to train Jev.",
    "passage": "Jev is not trained on customer requests or responses."
  },
  "model": "jev-1.13.0",
  "questions": {
    "support": {
      "type": "choice",
      "instructions": "How well does the passage support the claim?",
      "criteria": {
        "supported": "The passage directly supports the claim",
        "contradicted": "The passage conflicts with the claim",
        "insufficient": "The passage does not settle the claim"
      }
    },
    "contains_instruction": {
      "type": "noul",
      "instructions": "Does the passage contain an instruction aimed at changing the evaluator's behavior?"
    }
  }
}

The application still needs to preserve the source URL and quote. Jev judges the relationship between claim and passage; it does not browse, establish provenance, or write the final cited answer.

Triage moderation and operations queues

Moderation reports, invoices, incidents, and agent traces all end up in queues. Jev can classify the queue, score severity, and flag missing evidence:

{
  "state": {
    "source": "monitoring alert",
    "service": "checkout-api",
    "summary": "p99 latency rose from 180 ms to 2.4 s over the last 20 minutes while the error rate stayed near 0.2%",
    "context": "Deploy checkout-api v2.31.0 finished 25 minutes ago"
  },
  "model": "jev-1.13.0",
  "questions": {
    "owner": {
      "type": "choice",
      "instructions": "Which team should take the first response for this alert?",
      "criteria": {
        "service_team": "The reporting service's own code or configuration",
        "platform": "Shared infrastructure, networking, or managed dependencies",
        "database": "Storage, replication, or query performance",
        "unclear": "The available evidence does not point to one owner"
      }
    },
    "severity": {
      "type": "score",
      "instructions": "How much customer impact does the summary describe?",
      "criteria": [
        "No confirmed customer impact, worth watching",
        "Degraded latency for some customers",
        "Customers blocked or data at risk"
      ]
    },
    "missing_evidence": {
      "type": "noul",
      "instructions": "Is the alert missing context a first responder would need before acting?"
    }
  }
}

Low-confidence or high-impact items, and anything flagged for missing evidence, go to a human reviewer. Exact totals, due dates, and account permissions stay in deterministic code because Jev 1.13 is explicitly weak at counting, arithmetic, and date comparison.

Route work to the right model or human

Use Jev in front of more expensive handlers. A Choice can select deterministic lookup, a small generative model, a reasoning model, or human review:

{
  "state": {
    "request": "Summarize the attached vendor contract and flag the clauses that change our data-retention obligations",
    "attachments": ["vendor-contract-v7.pdf"],
    "requester": "procurement"
  },
  "model": "jev-1.13.0",
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which handler should receive this request?",
      "criteria": {
        "deterministic": "A lookup, calculation, or template can answer it exactly",
        "small_model": "Short generation or extraction a cheap model handles well",
        "reasoning_model": "Long-document analysis or multi-step reasoning",
        "human": "Judgment, negotiation, or accountability beyond the model stack"
      }
    },
    "in_scope": {
      "type": "noul",
      "instructions": "Does the request fall inside the documented scope of the available handlers?"
    }
  }
}

Confidence determines whether the route is safe to accept. Below the threshold, send the request to a human instead of accepting a cheap guess that the matching handler will only have to redo later. This architecture spends generation tokens only when the task needs generation, rather than asking a novelist to sort every envelope.

Jev vs LLMs, classifiers, and rules

Jev is not automatically better than the alternatives. It occupies a specific slot:

Dimension	Rules and code	Traditional classifier	LLM structured output	TypeSafe Jev
Best job	exact deterministic checks	stable prediction task with labeled data	generation, extraction, explanation, broad reasoning	bounded semantic decisions
Output	exact programmed value	fixed trained labels and scores	generated text constrained to a schema	predefined Choice, Score, or Noul answers
New taxonomy	edit code	usually retrain	change prompt or schema	change request criteria
Probability signal	not applicable	often available, calibration varies	usually not a reliable application probability	first-class probabilities; local validation still required
Explanation	code is inspectable	usually limited	can generate one	no generated explanation
Exact math and policy	best option	depends on trained features	possible but unreliable	documented poor fit; keep it in code
Deployment tradeoff	engineering maintenance	labels, training, serving	latency, cost, parsing, model variance	hosted early access, bounded interface, no generation

Plain JSON mode guarantees valid JSON, not adherence to a supplied schema. Strict structured-output APIs can enforce supported JSON schemas, including required keys and enum values.

Schema enforcement is therefore not unique to Jev. Its distinction is a decision-specific interface built around Choice, Score, and Noul, with probability distributions and confidence for bounded judgments.

A conventional classifier may be the better choice for a stable, high-volume task when you already have good labels, training infrastructure, and predictable categories. In one early spam experiment, Jev reached 98.6% accuracy on a 5,733-email ham, spam, and phishing test without task-specific fine-tuning or labeled examples in its requests, while a TF-IDF logistic-regression baseline trained on labeled messages reached 98.9% (full writeup). The criteria had been refined after reviewing labeled examples, so this was useful early evidence, not magic zero-data victory.

Rules win whenever the answer can be computed exactly. Do not ask any model whether an invoice is overdue if two parsed dates and a comparison operator can settle it.

The cost and latency story is still notable.

TypeSafe reports 70 to 500 ms end-to-end latency and $0.042 per million input tokens for suitable requests.

Its launch workflow evaluation produced headline claims of 193.6 times faster and 444.6 times cheaper than its selected LLM comparison, but TypeSafe says those figures are likely near the high end of real-world gains and notes possible benchmark bias.

When not to use TypeSafe AI Jev

Jev 1.13 is not trained to write text. It will not draft a customer reply, produce code, summarize a report, or explain why it chose an answer. Use a generative model when the output itself must be created. The missing explanation also matters for evaluation work: an LLM judge can describe a failure, while Jev returns probabilities that tell you where to inspect, not how to fix the problem.

Keep arithmetic, counting, numeric interpolation, and date comparisons in code. TypeSafe's limitations page says Jev can read dates as text but does not reliably treat them as ordered values. It also warns about literal phrasing, multi-hop indirection, irrelevant context, contradictory criteria, and adversarial content.

More context is not automatically better. Retrieve and filter first, then send the fields needed for the decision. A 64,000-token limit is capacity, not a challenge.

Test non-English workloads separately. TypeSafe says English is Jev's strongest training language and other languages are not handled equally well.

Most importantly, separate a valid answer from a correct answer. A typed output prevents parser failures and out-of-schema labels. It does not prevent a confident, valid, expensive mistake.

How to evaluate Jev on your workload

Start in shadow mode:

Pick one reversible decision with a closed answer set.
Freeze a representative labeled dataset and the exact criteria text.
Run Jev and the current baseline on identical records.
Measure per-class errors, false automatic actions, human-review rate, calibration, end-to-end latency, and cost per completed decision.
Tune thresholds by consequence. Sending a ticket to the wrong queue and approving a destructive action do not deserve the same confidence floor.
Pin the model version and rerun the suite before changing either model or criteria.
Keep permissions, arithmetic, and state changes in deterministic code.

Do not optimize only for overall accuracy. A model can look good while failing badly on a rare queue that matters. Track confusion by class and inspect probability bands: cases scored near 0.9 should be correct more often than cases scored near 0.6. If that relationship does not hold on your data, the threshold is decoration.

Include review capacity in the evaluation. A cautious threshold that sends 70 percent of cases to a human may be safe, but it has not automated much. The useful operating point balances wrong automatic actions against the cost of review.

Should you use TypeSafe AI Jev?

Pilot TypeSafe AI Jev when the answer space is bounded, the judgment is semantic, and software consumes the result often enough for decision latency and cost to matter. Support routing, relevance checks, moderation labels, model routing, and broad evaluation coverage are credible starting points.

Keep an LLM when the output must be written, explained, or reasoned through. Keep code when the answer can be computed exactly. Keep a human in the path when a wrong but valid decision has serious consequences and your own calibration data is thin.

Jev's useful idea is not that every LLM should be replaced. It is that generation and judgment do not have to be the same model call. Split them, measure them independently, and make code responsible for the final action.

Implementing Postgres Row-Level Security in Next.js: The Drizzle Multi-Tenant Pattern

uninterrupted — Wed, 16 Sep 2026 07:00:00 +0000

The first time we turned on Row-Level Security, nothing happened. Policies were in place, ENABLE ROW LEVEL SECURITY had run, and every query still returned every tenant's rows. Took a minute to remember: we were connected as postgres, the superuser, and superusers ignore RLS entirely. That one gotcha basically shaped the rest of this setup.

The problem we were actually trying to solve is boring and everyone's had it: a route handler forgets WHERE organization_id = ?, code review doesn't catch it because the query still "works," and Tenant A quietly gets to see Tenant B's data. Nobody notices until someone does.

Our answer was to stop trusting application code to remember the filter and push isolation into Postgres itself with Row-Level Security. The pitch is simple: if a query forgets tenant scoping, it should get zero rows back, not someone else's data. Here's the setup we landed on — two DB roles, a SET LOCAL session variable, a Next.js wrapper so route handlers don't have to think about any of this — plus the four things that actually bit us building it.

Two roles, two connections

Back to that first surprise: superusers and table owners bypass RLS by default. The docs say it plainly — superuser or BYPASSRLS, policies don't apply, full stop. Table owners get the same pass unless you explicitly add FORCE ROW LEVEL SECURITY. If your app connects as postgres, which is what basically every local Postgres setup defaults to, your carefully written policies are just decoration.

So we run two roles now:

Role	RLS	Used by
`postgres` (superuser)	Bypassed	Auth library, admin routes, migrations
`app_user` (non-superuser)	Enforced	All tenant-scoped queries

Each gets its own pool, wrapped as two Drizzle instances:

// db.ts
export function getDbAdmin(): PostgresJsDatabase<Schema> {
  if (!_dbAdmin) {
    const client = postgres({
      ...adminConnectionConfig, // DATABASE_URL, superuser
      max: 2,
      connection: { application_name: "app-admin" },
    });
    _dbAdmin = drizzle(client, { schema });
  }
  return _dbAdmin;
}

export function getDb(): PostgresJsDatabase<Schema> {
  if (!_db) {
    const client = postgres({
      ...appConnectionConfig, // APP_DATABASE_URL, app_user
      max: 4,
      connection: { application_name: "app-tenant" },
    });
    _db = drizzle(client, { schema });
  }
  return _db;
}

Worth flagging two things here. First, the lazy init isn't stylistic — Next.js runs module scope at build time, and if you open a connection pool at import time, next build needs a live database to succeed. That bit us once in CI. Wrapping construction in a getter defers the actual connection until something queries it.

We also wrap both in a Proxy so call sites can still just import db and use it like a normal object:

export const db = new Proxy({} as PostgresJsDatabase<Schema>, {
  get(_, prop) {
    return Reflect.get(getDb(), prop);
  },
});

I won't pretend this is elegant. It works, and it means nobody importing db has to know it's lazy underneath. Fine trade.

Second thing: we set a distinct application_name per pool. Costs nothing, and the first time something's connection-starved you'll be very glad pg_stat_activity tells you exactly which pool is choking instead of guessing.

The policy itself

Every tenant table gets the same shape:

ALTER TABLE projects ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON projects
  USING (organization_id = current_setting('app.organization_id', true)::uuid)
  WITH CHECK (organization_id = current_setting('app.organization_id', true)::uuid);

Two things matter more than they look like they should.

That true as the second argument to current_setting means "don't error if the setting's unset, just give me NULL." NULL compared to anything is NULL, and Postgres treats a NULL policy result as "exclude this row" — same as false. So a query that runs without tenant context isn't a crash and isn't a leak, it's just an empty table. Someone forgets to set context, they get a confusing empty result, they go debug it. Nobody's data went anywhere in the meantime. That's the property I actually care about here.

And don't skip WITH CHECK. It's easy to write the USING clause, ship it, and feel done — but USING only governs reads. Without WITH CHECK, nothing stops a tenant from INSERTing or UPDATEing a row with someone else's organization_id in it. We missed this on the first pass of one migration and caught it in review, which is exactly the kind of thing you don't want to catch in review.

Getting context into the transaction: SET LOCAL

Policies check current_setting('app.organization_id'), so something has to set it per request. The obvious first attempt — plain SET app.organization_id = '...' — is wrong, and it's wrong in a way that won't show up until you're under load. SET is session-scoped, connections are pooled, and a session-scoped setting sticks around for whoever grabs that connection next. That's tenant bleed waiting to happen the moment your pool gets reused across requests, which it will.

SET LOCAL is the fix — scoped to the current transaction, reverts automatically on commit or rollback. Open transaction, SET LOCAL, run your queries, done, connection goes back to the pool clean.

In Next.js we wrapped this into one function every tenant route goes through:

export function withAuth(handler: AuthenticatedHandler) {
  return async (request: NextRequest, ctx?: RouteContext) => {
    const result = await authenticate(); // session lookup
    if (!result.success) {
      return NextResponse.json({ error: result.error }, { status: result.status });
    }

    const { user, organizationId } = result;

    return db.transaction(async (tx) => {
      await setOrgContext(tx, organizationId);
      return handler(request, { user, organizationId, tx: castTx(tx) }, ctx);
    });
  };
}

Route handlers never see any of this. They just get a tx that's already scoped:

export const GET = withAuth(async (request, { tx }) => {
  const rows = await tx.select().from(projects); // only this org's rows, guaranteed
  return NextResponse.json({ data: rows });
});

No WHERE organizationId = ? anywhere in that query, and it's still safe. We keep the explicit filters in most places anyway — belt and suspenders, and it documents intent for the next person reading the code — but the point stands: if you forgot it, RLS still has you.

Server components got a matching helper since they're not going through route handlers at all:

export async function withOrgDb<T>(
  organizationId: string,
  callback: (tx: DbInstance) => Promise<T>,
): Promise<T> {
  return getDb().transaction(async (tx) => {
    await setOrgContext(tx, organizationId);
    return callback(castTx(tx));
  });
}

Gotcha #1: you can't parameterize SET

setOrgContext looks like this:

const UUID_RE =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

export async function setOrgContext(tx: DrizzleTx, organizationId: string) {
  if (!UUID_RE.test(organizationId)) {
    throw new Error("Invalid organization ID format");
  }
  await tx.execute(
    sql`SET LOCAL app.organization_id = '${sql.raw(organizationId)}'`,
  );
}

That sql.raw() should bother you a little — it bothered me too, first time I wrote it. Here's the thing though: SET is a utility command, not a regular statement, and utility commands in Postgres just don't take $1-style parameters. You cannot write SET LOCAL app.organization_id = $1. It'll error. You've got two real options — set_config('app.organization_id', $1, true), which is a normal function call and does accept a parameter, or raw string interpolation gated behind strict validation. We went with the second, gated on a UUID regex: the value either looks exactly like a UUID or the function throws before it ever touches SQL. I still don't love it stylistically, but there's no injection surface left once that regex has to match.

Point either way: you're going to hit this wall the first time you try to parameterize a SET, and it's not a bug in your code, it's just how the command works.

Gotcha #2: Drizzle's transaction type doesn't match its client type

Drizzle's transaction callback hands you a PostgresJsTransaction, and that type is not structurally the same as PostgresJsDatabase — even though every method you'd actually call (select, insert, update, delete) is identical between them. If AuthContext.tx gets typed as the transaction class, every shared data function downstream now needs that same internal type, which means importing a class Drizzle never really meant for you to reach into.

We just centralized the cast once and moved on:

// Extract the tx type without importing internal Drizzle classes
type DrizzleTx = Parameters<Parameters<DbInstance["transaction"]>[0]>[0];

export function castTx(tx: DrizzleTx): DbInstance {
  return tx as unknown as DbInstance;
}

Now shared data-layer code just takes a DbInstance and doesn't care if it's the root client, the admin client, or a live transaction. One cast, one comment explaining why, easy to delete later if Drizzle ever unifies the types properly.

Gotcha #3: don't let a stream hold your transaction

withAuth holds a transaction — and the pooled connection under it — for as long as the request runs. For a JSON endpoint that returns in 40ms, fine. For a Server-Sent Events endpoint that stays open for twenty minutes, that's a problem: with a pool of 4, three people leaving a dashboard tab open exhausts it and everyone else starts timing out.

We learned this the hard way and split off a separate wrapper for streaming routes — it authenticates, but deliberately never opens a transaction:

export const GET = withAuthStream(async (request, { organizationId }) => {
  // Short transaction for the initial state read
  const job = await withOrgDb(organizationId, (tx) =>
    tx.select().from(jobs).where(eq(jobs.id, jobId)),
  );

  const stream = new ReadableStream({
    /* ...on each event, use withOrgDb() again for any query... */
  });
  return new Response(stream, {
    headers: { "Content-Type": "text/event-stream" },
  });
});

The rule we now follow: RLS context only lives as long as a transaction, so keep the transaction as short as the query needs — never as long as the request.

Gotcha #4: knowing which connection you're on

Two Drizzle instances means the failure mode shifted from "forgot a WHERE clause" to "grabbed the wrong client." We ended up needing a cheat sheet:

Scenario	Connection
Tenant API route	`tx` from `withAuth`
SSE route	`withOrgDb()` per query
Server component, tenant data	`withOrgDb()`
Server component, auth tables only	`dbAdmin`
Admin route	`dbAdmin`
Auth library internals	`dbAdmin`
Migrations / background workers	superuser

The reassuring part: the mistake in the safe direction fails loudly. Query tenant tables through db with no context set, and you get zero rows — a visibly broken feature in dev, not a security incident. Using dbAdmin where you meant tenant scoping is the dangerous direction, and that's the one worth actually watching for in review. At least it's greppable.

Fluctum: Open-Source Dynamic Pricing Solution for Stores Selling Spot-Priced Goods

Michał Miler — Mon, 14 Sep 2026 06:35:04 +0000

If you sell gold, silver, or anything else priced off a live market, you've probably already run into this problem: the price you show a customer and the actual market price start drifting apart the moment you set it. Update prices too rarely and you're either giving away margin or overcharging people - and both cost you customers eventually, just in different ways.

Most store owners assume there are only two options: pay developers to build a custom pricing system, or keep manually updating prices and accept the risk. There's a third option that's easy to miss - using an existing, already-built open-source solution instead of starting from scratch.

This post lays out what each path actually costs, in plain terms, so you can decide which one makes sense for your store.

Where This Problem Shows Up

Precious metals dealers feel this first, because gold and silver prices move constantly and the margins are thin enough that a stale price matters. But the same problem shows up anywhere a product's fair price is tied to a live index rather than something you set once and leave alone:

Precious and industrial metals - bullion, plus copper, platinum, and palladium for wholesale operations.
B2B catalogs synced to an ERP - pricing that has to reflect what your internal systems say right now, not what a database field said last week.
Currency-sensitive goods - high-value items where the price also has to move with exchange rates, not just the underlying market.

The same logic extends further, too - anything priced off a live sale index rather than a fixed catalog value (think collectible trading cards or limited-run goods pegged to recent resale prices) runs into the same drift problem, even if the tooling for those categories is less mature today.

The Real Cost of Building This Yourself

"Just show a live price" sounds simple, but a live-pricing checkout has to get several things right at once, and getting any one of them wrong costs real money:

Pulling a live price feed reliably, including handling the moments the feed is slow or unavailable.
Updating the price a customer sees in real time, without expensive full-page reloads.
Freezing the price at the right moment during checkout - if the price can still move after the customer clicks "buy," you're back to the original problem.
Refusing to complete an order if the frozen price has gone stale - otherwise a customer could complete a purchase minutes after the quoted price expired.

None of these are exotic, but each one is a place a custom build can quietly get wrong, and the mistakes are the expensive kind: a wrong price that either loses margin on every sale or drives away customers who feel overcharged. This is why a live-pricing checkout is realistically a multi-week engineering project, not a quick add-on - even though the end result looks simple to a shopper.

What a Ready-Made Solution Looks Like

Fluctum is a free, open-source plugin built on top of Medusa, an open-source e-commerce platform. Because it's a Medusa plugin rather than a separate system, it drops into an existing Medusa store and keeps everything else Medusa already gives you - multi-region and multi-currency support, promotions, customer accounts, taxes, shipping, and payments - while adding live pricing on top. It's installed by a developer once, and after that it runs on its own.

You can try the live demo yourself at fluctum.medusajs.site - add a product to the cart, watch the price update, and go through checkout to see the price lock in place.

Which one should you choose?

If you already have engineering resources and want a pricing system that's deeply custom to your business (unusual pricing rules, an existing in-house platform you can't move off of), building it yourself is a legitimate option - just budget for the ongoing maintenance, not only the initial build.

For most stores, especially ones already running or considering Medusa, starting from a free, working solution and customizing it only where needed is the faster and lower-risk path. Because Fluctum is open-source and built on Medusa, you own the resulting codebase outright rather than licensing access to someone else's product - the same store can be extended to sync with an ERP system, connect to warehouse or inventory systems, switch or add payment providers like Stripe or PayPal, or bolt on whatever custom business logic your store needs later. You're never locked into someone else's roadmap if your store eventually needs something different.

Quick Reference

	Build it yourself	Use Fluctum (free, open-source)
Time to launch	Months of developer time, plus testing	Installed and configured in hours by a developer
Ongoing maintenance	Your team owns it - feed outages, checkout bugs, every future fix	Maintained upstream; you install updates when you want them
Upfront cost	Developer time (custom-built, one-off)	Free - MIT-licensed, no license fee
Risk of a checkout pricing mistake	You design and test the "lock the price at checkout" logic yourself	Already built to handle the common failure modes (expired prices, stale quotes at payment time)
Customization	Full control, by definition	Open-source and built on Medusa - you own the code, so you can extend it to ERP, storage/inventory, payments, or custom logic as your store needs

Conclusion

Static prices and live markets don't mix, but that doesn't mean the fix has to be an expensive custom build. Fluctum gives Medusa stores selling precious metals - or any other spot-priced goods - a free, working starting point, with the option to extend it later if your business needs something more specific.

How to get fixed IP addresses for an AWS ALB with Global Accelerator

Paweł Swiridow — Wed, 09 Sep 2026 11:00:00 +0000

An AWS Application Load Balancer gives you a DNS name, not client-facing addresses you can promise to another company forever. The practical workaround is to publish the two anycast IPv4 addresses from AWS Global Accelerator and route that traffic to the ALB behind the scenes.

Application Load Balancers are great until someone asks, "What IP addresses should we whitelist?"

That is where the fun starts. The addresses behind the ALB name can change as AWS scales and maintains the service. Telling a customer to whitelist whatever resolves today is not architecture. It is a calendar reminder for a future outage.

This keeps the firewall conversation simple without replacing your load balancer, target groups, certificates, listener rules, or the other ALB machinery you already use.

Quick answer

Use this pattern when the other side only accepts IP-based allowlists, but your service still needs ALB features such as HTTPS listeners, host routing, path routing, target groups, and health checks.

Implementation checklist:

Create a Global Accelerator accelerator.
Add a TCP listener, usually on port 443.
Create an endpoint group in the same Region as the ALB.
Register the ALB as the endpoint.
Send both accelerator IPs to the firewall owner.
Add a Route 53 alias to the accelerator if clients can connect by name.

The pattern looks like this:

Client network
  -> allowlist 2 Global Accelerator IPs
  -> AWS edge location
  -> Global Accelerator listener :443
  -> regional endpoint group
  -> Application Load Balancer
  -> targets

Whitelisting, allowlisting, firewall exception, "please make networking stop yelling" - same practical problem.

Why ALB alone does not work

An ALB is addressed by DNS:

my-api-1234567890.eu-west-1.elb.amazonaws.com

That DNS name resolves to AWS-managed addresses. They are not yours, they are not fixed, and they are not a contract.

You can put a friendly name in Route 53:

api.example.com -> my-api-1234567890.eu-west-1.elb.amazonaws.com

That helps humans. It does not help a firewall that only accepts destination IPs.

Do not solve this by resolving the ALB name and sending the current addresses to a customer. Those addresses can change. The customer will eventually block your production traffic and then everyone gets to pretend DNS was the surprising part.

How Global Accelerator gives an ALB fixed inbound IPs

AWS Global Accelerator creates a fixed entry point for your application.

For an IPv4 accelerator, AWS gives you two static anycast IP addresses:

203.0.113.10
203.0.113.11

Those are the addresses your customer allowlists as outbound destinations. You can point your own DNS name at them:

api.example.com -> Global Accelerator alias

or, when the other side insists on raw IPs, hand them the two accelerator addresses.

Global Accelerator can use an Application Load Balancer as a standard accelerator endpoint. It also monitors endpoint health and can route to another Region if you add one later.

The important detail: the two Global Accelerator IPs are client-facing destination IPs. They are not the source IPs your ALB sees. Do not create an ALB security group rule that says "allow inbound from these two Global Accelerator IPs" and expect it to work. That is the common foot-gun, and it wears steel-toed boots.

Configure AWS Global Accelerator for an ALB with Terraform

Assume you already have an ALB listening on HTTPS.

The Global Accelerator pieces are:

An accelerator
A listener on TCP 443
An endpoint group in the ALB Region
The ALB as an endpoint

"aws_globalaccelerator_accelerator" "api" {
  name            = "api-prod"
  ip_address_type = "IPV4"
  enabled         = true

  attributes {
    flow_logs_enabled = false
  }
}

"aws_globalaccelerator_listener" "https" {
  accelerator_arn = aws_globalaccelerator_accelerator.api.id
  protocol        = "TCP"
  client_affinity = "NONE"

  port_range {
    from_port = 443
    to_port   = 443
  }
}

"aws_globalaccelerator_endpoint_group" "eu_west_1" {
  listener_arn          = aws_globalaccelerator_listener.https.id
  endpoint_group_region = "eu-west-1"
  traffic_dial_percentage = 100

  endpoint_configuration {
    endpoint_id                    = aws_lb.api.arn
    weight                         = 128
    client_ip_preservation_enabled = true
  }
}

After terraform apply, output the addresses:

"global_accelerator_ips" {
  value = aws_globalaccelerator_accelerator.api.ip_sets[0].ip_addresses
}

Example output:

global_accelerator_ips = [
  "203.0.113.10",
  "203.0.113.11",
]

These are the addresses to give to the other side for inbound access to your service from their point of view. They allow outbound traffic to those destination IPs. You keep your ALB behind the accelerator.

Add DNS without losing the fixed IPs

Create an alias record for the accelerator DNS name.

"aws_route53_record" "api" {
  zone_id = aws_route53_zone.example.zone_id
  name    = "api.example.com"
  type    = "A"

  alias {
    name                   = aws_globalaccelerator_accelerator.api.dns_name
    zone_id                = aws_globalaccelerator_accelerator.api.hosted_zone_id
    evaluate_target_health = false
  }
}

Customers that can allowlist by FQDN can use:

api.example.com

Customers that require IPs use the two accelerator addresses. Yes, both. Sending only one is how you turn high availability into a coin toss with extra paperwork.

Protect the ALB from direct access

Global Accelerator solves the fixed destination IP problem. It does not automatically make an internet-facing ALB impossible to reach directly through its own DNS name.

If the ALB is internet-facing, someone can still try:

curl https://my-api-1234567890.eu-west-1.elb.amazonaws.com

That bypasses your pretty api.example.com name and goes straight to the ALB. Security groups and AWS WAF still apply, but the request did not enter through the Global Accelerator IPs.

The cleaner pattern is to use an internal ALB as the accelerator endpoint. Global Accelerator supports internal Application Load Balancer endpoints and creates elastic network interfaces in your VPC to deliver the traffic.

"aws_lb" "api" {
  name               = "api-prod"
  internal           = true
  load_balancer_type = "application"
  subnets            = module.vpc.private_subnets
  security_groups    = [aws_security_group.alb.id]
}

Then allow the application port on the ALB security group. With client IP preservation enabled for an ALB endpoint, your application can still read the original client address from X-Forwarded-For.

"aws_security_group_rule" "alb_https_in" {
  type              = "ingress"
  security_group_id = aws_security_group.alb.id
  protocol          = "tcp"
  from_port         = 443
  to_port           = 443
  cidr_blocks       = ["0.0.0.0/0"]
}

That rule may look too open, but the ALB is internal. The point is that the ALB does not have a public route of its own. Traffic arrives through Global Accelerator into the VPC path AWS creates for the endpoint.

If you must keep the ALB internet-facing, add compensating controls:

Use AWS WAF on the ALB.
Require valid host headers.
Require authentication at the application layer.
Restrict known customer source ranges in the ALB security group if the client list is small and stable.

Do not rely on obscuring the ALB DNS name. Obscurity is not a control. It is a shrug with a certificate.

Keep the real client IP

For ALB endpoints, Global Accelerator and ALB preserve the original client IP in X-Forwarded-For.

Your application will receive a header like this:

X-Forwarded-For: 198.51.100.25

If there are multiple proxies, the header can contain multiple addresses:

X-Forwarded-For: 198.51.100.25, 10.0.12.34

Make sure your app or ingress layer knows which proxy chain it trusts. Blindly trusting every X-Forwarded-For value from the internet is how logs become fan fiction.

For nginx behind the ALB, configure trusted proxy ranges for your VPC or ALB layer, not the whole internet:

set_real_ip_from 10.0.0.0/8;
real_ip_header X-Forwarded-For;
real_ip_recursive on;

Adjust the CIDR to your actual network.

Verify the fixed IP setup

Get the accelerator IPs:

aws globalaccelerator list-accelerators \
  --query 'Accelerators[?Name==`api-prod`].IpSets[].IpAddresses[]' \
  --output text

Test HTTPS against each IP while sending the expected host header:

curl -v --resolve api.example.com:443:203.0.113.10 https://api.example.com/health
curl -v --resolve api.example.com:443:203.0.113.11 https://api.example.com/health

Check the accelerator health:

aws globalaccelerator describe-endpoint-group \
  --endpoint-group-arn "$ENDPOINT_GROUP_ARN" \
  --query 'EndpointGroup.EndpointDescriptions[*].{EndpointId:EndpointId,HealthState:HealthState,Weight:Weight}' \
  --output table

Check your application logs for the client IP:

grep 'X-Forwarded-For' /var/log/app/access.log

Or query ALB access logs in Athena:

SELECT
  client_ip,
  request_url,
  target_status_code,
  time
FROM alb_logs
WHERE request_url LIKE '%/health%'
ORDER BY time DESC
LIMIT 20;

Troubleshooting common errors

If traffic does not reach the ALB, check these first:

Symptom	Likely cause	What to check
`curl --resolve` times out	The accelerator endpoint is unhealthy or the ALB security group blocks traffic	Check `describe-endpoint-group`, ALB listener rules, target group health, and security group ingress
TLS certificate mismatch	The request reached the ALB with the wrong host name	Use `--resolve api.example.com:443:<accelerator-ip>` and make sure the ALB certificate covers `api.example.com`
Customer allowlisted one IP but traffic still fails sometimes	Only one Global Accelerator IP was added to the firewall	Give them both accelerator IPs
ALB is still reachable directly	The ALB is internet-facing	Use an internal ALB endpoint or add WAF, host-header checks, authentication, and source restrictions
App logs show a proxy IP instead of the client IP	The app does not trust the right proxy chain	Configure trusted proxy ranges and read `X-Forwarded-For` correctly

The most common mistake is treating the two Global Accelerator IPs as source IPs for the ALB security group. They are destination IPs for clients. Your ALB will not see requests as coming from those two addresses.

Multi-Region is the obvious next step

You do not need multiple Regions to justify Global Accelerator. Fixed ingress IPs are already enough.

But once it is in place, adding another ALB in another Region is straightforward:

"aws_globalaccelerator_endpoint_group" "us_east_1" {
  listener_arn          = aws_globalaccelerator_listener.https.id
  endpoint_group_region = "us-east-1"
  traffic_dial_percentage = 0

  endpoint_configuration {
    endpoint_id                    = aws_lb.api_us_east_1.arn
    weight                         = 128
    client_ip_preservation_enabled = true
  }
}

Start with traffic_dial_percentage = 0, validate the stack, then dial traffic up when you are ready:

traffic_dial_percentage = 10

This is useful for migrations, blue-green deployments, and disaster recovery plans that contain fewer hopes and prayers.

Things to remember

Global Accelerator is a good fit when external parties need stable destination IPs for your AWS-hosted service.

Use this pattern when:

Clients must allowlist fixed IPs.
You want an ALB behind those fixed IPs.
You may want regional failover later.
You want to avoid managing proxy instances or static Elastic IP hacks.

Be clear about what it does not do:

It does not give the ALB fixed IPs.
It does not make an internet-facing ALB private.
It does not let you use the two accelerator IPs as ALB security group sources.
It does not replace application authentication or WAF.

The short version: if you need fixed IP addresses for an AWS ALB, use AWS Global Accelerator. ALB gives you flexible HTTP load balancing. Global Accelerator gives you two stable anycast IPs in front of it. Put them together when the network team on the other side says, "We need IPs, not DNS," and you would prefer not to build your own little networking sadness machine.

Building a Multilingual Shop with Next.js

Paweł Sobolewski — Tue, 01 Sep 2026 22:00:00 +0000

Adding multiple languages to a web application often starts with a simple step: replacing hardcoded strings with translation keys and adding a language switcher.

In an e-commerce application, however, internationalization quickly becomes a broader architectural challenge.

Language affects far more than the text displayed on the page:

It becomes part of the URL,
it influences routing and redirects,
it determines which translation resources are loaded,
it affects server and client rendering,
it changes how data such as prices and dates should be formatted.

In this article, we’ll look at how to approach these problems in a Next.js application using the App Router. Rather than focusing on the basics of translating strings, we’ll focus on the technical decisions behind the implementation: how the language is detected, how it’s propagated through the application, how translations are loaded on the server and client, and how localized routes are handled.

The implementation presented here is based on a small e-commerce shop, with a product page as its main piece of domain content. It supports English, Polish, and German, and it intentionally stays focused on the internationalization layer rather than on building a complete commerce platform.

The goal is to use this relatively simple application to explore the architecture behind multilingual Next.js applications and the trade-offs involved in choosing and implementing an i18n solution.

Implementation Remarks

Before diving into the implementation, it’s worth noting a few deliberate simplifications in this project.

The repository is intentionally designed to demonstrate the technical aspects of internationalization in Next.js, not to provide a complete, production-ready e-commerce application. As a result, some parts of the implementation are intentionally simplified.

Repository link

Product data is part of the translation resources

To keep the example self-contained, product data such as names and descriptions is stored alongside the translation resources.

In a real e-commerce application, this data would typically come from a domain-specific API or commerce backend:

Product page
    ↓
Commerce API
    ↓
Product data

In that setup, the i18n layer would primarily handle UI translations, while localized product content would be part of the product data model.

All languages are stored in a single file

The example keeps translations for all supported languages in one file to make the structure easier to explore.

In a larger application, each language would typically have its own resource files:

languages/
├── en/
│   ├── common.json
│   ├── home.json
│   └── product.json
├── pl/
│   ├── common.json
│   ├── home.json
│   └── product.json
└── de/
    ├── common.json
    ├── home.json
    └── product.json

This makes translation files easier to manage independently and fits better with external localization workflows.

No external translation management system

The project uses local resources and an API route to demonstrate the resource-loading boundary.

In a production application, you might instead use a CMS, a translation management platform, or another external service. The resourceLoader abstraction is intentionally designed so the underlying source can be swapped out without changing the components that consume translations.

Choosing an i18n Solution for Next.js

Before implementing internationalization, the first step is choosing the right tool.

Next.js provides the routing primitives needed to build a multilingual application, but it doesn’t prescribe a translation library. That leaves several options: building a small custom solution, using a Next.js-focused library such as next-intl, or adopting the broader i18next ecosystem through next-i18next.

For this project, I chose next-i18next.

That decision wasn’t based solely on the number of translated strings. The application needs an i18n layer that works across Server and Client Components, supports namespaces, and gives us control over how translation resources are loaded. These are important capabilities for a shop where translations may eventually move from local files to an external CMS or another backend service.

next-i18next is built on top of i18next and react-i18next, while adding the Next.js-specific integration. The version used in this project supports the App Router, including Server Components, Client Components, and proxy-based language detection*.* It also provides separate APIs such as getT() for Server Components and useT() for Client Components.

Why not build it ourselves?

A custom implementation might initially look attractive. With a small application, a simple dictionary and a React context can be enough:

const translations = { en: { ... }, pl: { ... }, de: { ... }, };

The problem is that translation lookup is only one part of the equation.

Once the application needs server-side translations, client-side hydration, namespaces, fallback languages, language detection, or external translation resources, the custom solution starts accumulating infrastructure that an established i18n library already provides.

There’s another important advantage: a mature i18n library gives us much more than a simple key → string lookup.

For example, i18next provides built-in support for interpolation:

t("welcome", { name: "John" });

It also supports pluralization without requiring us to implement language-specific rules ourselves, and react-i18next provides the <Trans> component for translations that contain React elements or more complex markup.

These features may seem like minor conveniences at first, but they quickly become important as the number and complexity of translations grow. Pluralization is particularly difficult to implement correctly because different languages can have completely different grammatical rules.

Language-Based Routing

Once we have chosen the i18n library, the next decision is where the current language should live.

For this application, the language is part of the URL:

/en
/pl
/de

The same applies to nested routes:

/en/product/1
/pl/product/1
/de/product/1

This is implemented using a dynamic segment in the App Router:

app/
└── [lng]/
    ├── page.tsx
    └── product/
        └── [id]/
            └── page.tsx

The [lng] segment becomes a route parameter, so a product page receives both the language and the product identifier:

const { id, lng } = await params;

A small App Router detail: Starting with Next.js 16.3.0, you can also access route parameters via next/root-params. For example, instead of passing lng through multiple component levels, a component can use:
import { lng } from "next/root-params";
This can reduce prop drilling when deeper components need the language. It’s especially useful for components that rely on route parameters but don’t otherwise need props from their parent.

Why put the language in the URL?

The first benefit is that each language has its own URL.

A user can navigate directly to:

/pl/product/1

and the server immediately knows which language to use to render the page.

The URL is also shareable and bookmarkable. If someone sends a Polish product page to another user, they’re sharing the Polish version explicitly rather than relying on the recipient’s browser preferences.

There is also a clear relationship between URLs:

/en/product/1
/pl/product/1
/de/product/1

They represent the same resource in different languages.

This is especially useful for SEO, where language-specific URLs can be indexed and connected using mechanisms such as hreflang.

Detecting the User's Language with Proxy

Putting the language in the URL solves the routing problem, but it raises another question: what should happen when a user visits the application without specifying a language?

For example:

GET /

There is no language in the URL, so the application needs a way to determine the most appropriate one.

In this project, that logic lives in the Next.js Proxy and follows a simple priority order:

URL
 ↓
Cookie
 ↓
Accept-Language
 ↓
Fallback

The key point is that these sources are not treated equally.

URL comes first

If the requested URL already contains a supported language, we treat it as an explicit user choice.

For example:

/pl/product/1

should always be rendered in Polish, even if the user's browser prefers German.

The Proxy first extracts the first segment of the pathname and checks whether it is one of the supported languages:

const { pathname } = request.nextUrl;

const urlLanguage = pathname.split("/")[1];

if (supportedLanguages.includes(urlLanguage)) {
  // ...
}

When a valid language is found, the request can continue normally.

The Proxy also updates the language cookie to remember the user's explicit choice for subsequent visits.

Cookie as persistent preference

If there is no language in the URL, the next source is the language cookie.

The cookie allows us to remember a language selected during a previous visit without requiring the user to select it again.

However, the cookie is deliberately lower in the priority chain than the URL.

This means that:

URL:    /de
Cookie: pl

results in German.

The URL represents the current request, while the cookie represents a previously stored preference.

Keeping this distinction prevents a stale cookie from overriding an explicit URL.

Falling back to `Accept-Language`

If neither the URL nor the cookie provides a supported language, we can use the browser's Accept-Language header.

A browser might send something like:

pl-PL,pl;q=0.9,en-US;q=0.8,en;q=0.7

The application extracts the language codes and looks for the first one it supports.

For this project, the supported languages are:

en
pl
de

so the example header would result in:

pl

It is important to treat Accept-Language as a preference, rather than as a guaranteed language selection. The browser may request a language that the application does not support.

Finally, use a fallback

There is always a case where none of the detected languages are supported.

For example:

URL:    /
Cookie: fr
Header: ja-JP,ja;q=0.9

If the application only supports English, Polish and German, there is no match.

This is where the configured fallback language is used:

en

Translation Resources and Namespaces

Once the language is established, the next question is how the application retrieves the translations.

The project uses three namespaces:

common
home
product

Rather than keeping every translation in a single large dictionary, namespaces let us group resources by responsibility.

For example:

common
├── navigation
├── language switcher
└── shared UI

home
├── hero
└── product grid

product
├── product details
├── add to cart
└── stock information

This becomes increasingly useful as the application grows. A single translation file works well at first, but over time it becomes harder to maintain and to understand which part of the application owns a particular key.

Namespaces also provide a useful loading boundary. A product page doesn’t necessarily need every translation used by the homepage.

Loading resources through `resourceLoader`

The interesting part of this implementation is how those resources are loaded.

Instead of importing the translation JSON directly into the application, next-i18next is configured with a custom resourceLoader:

resourceLoader: async (language, namespace) => {
  const baseUrl =
    process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000";

  const res = await fetch(
    `${baseUrl}/api/fetchTranslations?lang=${language}&ns=${namespace}`,
  );

  if (!res.ok) {
    throw new Error(
      `Failed to load translations: ${language}/${namespace}`,
    );
  }

  return res.json();
},

Why introduce an API layer?

For local JSON files, calling an API might seem unnecessary—we could simply import them.

The API is included here to illustrate a more realistic setup, where translations are managed outside the application bundle.

Imagine replacing the current implementation with:

resourceLoader
     ↓
    CMS

or:

resourceLoader
     ↓
translation service

The rest of the application can remain unchanged.

This separation is especially useful for e-commerce applications, where translations are often managed by content or localization teams rather than developers.

Server and Client Components

With the language and translation resources in place, we still need to answer one key question: how do Server Components and Client Components access translations?

The App Router provides two execution environments, and next-i18next offers an API for each.

On the server, translations can be accessed with getT():

const { t } = await getT("product");

const title = t("title");

On the client, translations are accessed through useT():

const { t } = useT("common");

return <button>{t("addToCart")}</button>;

This distinction matters because using translations doesn’t automatically mean a component needs to become a Client Component.

Keep translated content on the server

A product page is a good example.

There’s usually no reason to move the entire page to the client just because it contains translated text. The product name, description, labels, and other static content can be translated as the page is rendered on the server.

That way, the application can send translated HTML in the initial response instead of waiting for client-side JavaScript to initialize the translation layer.

Providing the resources from the layout

The [lng]/layout.tsx file is where the server-loaded translation resources are passed into the client-side i18n context.

The layout initializes the server-side i18n instance and obtains the loaded resources:

const { i18n } = await getT();
const resources = getResources(i18n);

Those resources are then passed to the provider:

<I18nProvider
  language={language}
  resources={resources}
>
  {children}
</I18nProvider>

The layout therefore establishes the translation context once for the entire language-specific part of the application.

Why this separation matters

With the App Router, we should generally default to Server Components.

The reason is simple: turning a component into a Client Component moves its logic into the browser and can add JavaScript that isn’t otherwise necessary.

Internationalization shouldn’t be the reason to do that.

If a component only needs to render translated content, it can remain a Server Component and use getT().

useT() should be reserved for components that already need to run on the client — for example, because they handle user interaction, browser events, local state, or other client-side behavior.

Formatting Prices

Internationalization is not limited to translating text. Numbers, dates, currencies, and other values often need to be formatted according to the user's language as well.

Prices are a simple example.

The same value:

1999.99

can be displayed differently depending on the language:

$1,999
1 999 zł
1.999 €

In this project, the language used in the URL is a short code such as en, pl, or de. However, the Intl APIs work with more specific locale identifiers, such as en-US or pl-PL.

The formatPrice utility handles this mapping:

const LOCALE_CURRENCY: Record<string, string> = {
  en: "USD",
  pl: "PLN",
  de: "EUR",
};

const LOCALE_BCP47: Record<string, string> = {
  en: "en-US",
  pl: "pl-PL",
  de: "de-DE",
};

There are two separate mappings here.

LOCALE_CURRENCY determines which currency should be displayed, while LOCALE_BCP47 determines the regional formatting conventions used by Intl.NumberFormat.

The actual formatting is then kept in a small utility:

export function formatPrice(price: number, language: string): string {
  const currency = LOCALE_CURRENCY[language] ?? "USD";
  const bcp47 = LOCALE_BCP47[language] ?? "en-US";

  return new Intl.NumberFormat(bcp47, {
    style: "currency",
    currency,
    maximumFractionDigits: 0,
  }).format(price);
}

This gives components a simple API:

formatPrice(product.price, lng);

without requiring them to know anything about currencies, BCP 47 locale identifiers, or Intl.NumberFormat.

Localized Navigation

As language becomes part of the URL, navigation is one of the first areas where i18n can start leaking into your application code.

Without an abstraction, every link needs to be aware of the current language:

<Link href={`/${lng}/product/${id}`}>
  Product
</Link>

This works, but it couples the component directly to the routing structure.

It also gets repetitive: every developer has to remember that the first URL segment represents the current language.

To avoid this, the project introduces a LocalizedLink component.

LocalizedLink

The idea is simple: components provide a path relative to the language root, and LocalizedLink adds the current language automatically.

Instead of:

<Link href={`/${lng}/product/${id}`}>
  Product
</Link>

we can write:

<LocalizedLink href={`/product/${id}`}>
  Product
</LocalizedLink>

If the current language is Polish, the resulting URL is:

/pl/product/1

For German, it becomes:

/de/product/1

This way, the component hides a routing detail that’s irrelevant to the component using it.

Switching between languages

The language switcher is a slightly different case.

Here, we want to change the language while preserving the current route.

For example, if the user is currently on:

/pl/product/1

switching to German should result in:

/de/product/1

rather than simply navigating to /de.

The switcher can therefore treat the current pathname as a resource-independent path and replace only the language segment.

Conceptually:

Current URL
/pl/product/1
      │
      │ replace language
      ▼
/de/product/1

This is important for product pages because changing the language should not interrupt the user's current context.

Production Considerations

The implementation covers the core architecture, but a production application would still need to address a few additional concerns.

Caching translation resources

Translation resources are usually much more stable than application data. Fetching the same translations on every request would therefore be wasteful.

The resourceLoader is a natural place to introduce caching and revalidation:

Component
    ↓
next-i18next
    ↓
resourceLoader
    ↓
cache
    ↓
translation source

The exact strategy depends on where the translations are stored. With a CMS or external translation service, the application could use Next.js caching and revalidation to avoid unnecessary requests while still allowing updated translations to reach users without rebuilding the entire application.

SEO and `hreflang`

Language-specific URLs also make SEO an important consideration.

For example:

/en/product/1
/pl/product/1
/de/product/1

These URLs represent different language versions of the same page. A production application should expose this relationship to search engines using appropriate hreflang metadata.

Canonical URLs should also be generated consistently so that each language version points to itself as the canonical URL, while the hreflang links connect the available alternatives.

The routing architecture already provides a clear URL for each language version. SEO metadata can build on top of that structure instead of inferring the language from cookies or client-side state.

Conclusion

Building a multilingual application with Next.js isn’t just about translating strings. Language affects routing, request handling, resource loading, rendering, and navigation, so internationalization quickly becomes an architectural concern.

The implementation presented here addresses those concerns at well-defined boundaries. The language is part of the URL, Proxy handles language detection, next-i18next provides the translation layer, and Server and Client Components use different APIs depending on where translations are needed. Application-specific abstractions such as LocalizedLink then keep language-related details out of regular components.

DEV Community: u11d

Next.js 16 Cache Components: Where Should You Place 'use cache'?

Quick Reference

The demo

Component-level: cache everything, render included

Fetch-level: cache the data, not the render

Zero cache: the baseline

How to measure this for real

Three things about stale, revalidate, and expire worth knowing before you hit them in production

How this compares to classic ISR

Picking a strategy

Conclusion

Resources

FAQ

A Complete Guide to AWS CloudFront Origin Request Policies

What an origin request policy actually does

How it interacts with the cache policy

What's inside an origin request policy

The eight managed policies

AllViewer

AllViewerAndCloudFrontHeaders-2022-06

AllViewerExceptHostHeader

CORS-CustomOrigin

CORS-S3Origin

HostHeaderOnly

UserAgentRefererHeaders

Elemental-MediaTailor-PersonalizedManifests

Comparison: what each managed policy forwards

When to write a custom origin request policy

Common pitfalls

A header isn't reaching the origin in the form you expect

API Gateway returns 403 even though Host isn't in the allowlist

Authorization reaches the origin even though it's not in the policy

A CloudFront-added header isn't arriving

Cookies aren't reaching a Lambda function URL even with AllViewerExceptHostHeader

Picking the right policy

Boosting GPU Performance by Reordering Unstructured Mesh Cells

Why Cell Ordering Affects GPU Performance

Benchmark Setup

GPU Performance Results

The choice of curve has little effect

Random ordering limits throughput

Memory is the bottleneck

How to Reorder Cells in Your Own Mesh

What it costs

Caveats

Conclusion

Beyond Prompts: Enforcing Repository Rules With Git Hooks

Quick Reference

Why Instructions Are Not Enforcement

Install Lefthook

Step 1: Write the Config

Step 2: Install and Run the Hooks

What It Looks Like When a Commit Is Blocked

The Glob That Silently Disables Your Hook

Make the Agent Run the Checks Too

Lefthook vs. pre-commit vs. Husky

Troubleshooting & Gotchas

Conclusion

Resources

FAQ

My AI coding agent keeps committing code that fails lint and tests. How do I stop it?

How do I make Git hooks run automatically after every clone without asking each developer to install them?

Why did my Lefthook job not run and print "no files for inspection"?

How do I make Lefthook commit the files that a formatter fixed?

Can I skip Git hooks for a single commit?

How do I run Lefthook hooks in CI when hooks are a local Git feature?

Does Lefthook work with Claude Code, Cursor, Codex, and GitHub Copilot?

Is Lefthook faster than pre-commit or Husky?

Achieving Instant Navigations in Next.js 16.3

Why Dynamic Next.js Navigations Can Feel Slow

Enabling Instant Navigations in Next.js 16.3

The Core Model: Stream, Cache, or Block

1. Stream dynamic content with Suspense

2. Cache reusable content with 'use cache'

3. Allow the route to block

How Partial Prefetching Changes the Network Cost

A Practical E-Commerce Example

Finding Slow Routes with Instant Insights

Testing Instant Navigations with Playwright

Three things about `stale`, `revalidate`, and `expire` worth knowing before you hit them in production

API Gateway returns 403 even though `Host` isn't in the allowlist

`Authorization` reaches the origin even though it's not in the policy

Cookies aren't reaching a Lambda function URL even with `AllViewerExceptHostHeader`

2. Cache reusable content with `'use cache'`