DEV Community: Shubhra Pokhariya

I Got the proxy.ts Matcher Wrong for Three Projects Before I Understood Why

Shubhra Pokhariya — Wed, 17 Jun 2026 07:56:06 +0000

A few days ago I published a post about the three-layer auth model and the invoice incident that made me rebuild how I think about Next.js 16 auth. More people had hit the same thing than I expected.

One comment stopped me. Someone pointed out a real gap in how the forwarded headers work when the matcher misses a route. They were right, and I want to cover it properly here. But before that, I want to go through proxy.ts end to end, because in my experience the matcher is where most auth setups quietly break first, and it breaks in the worst way, no error, no warning, nothing in the logs.

Why the Name Changed

If you've been building with Next.js for a while, the rename felt arbitrary at first. middleware.ts to proxy.ts. Same location in your project, different filename, different export.

The Next.js team has been direct about why. The word "middleware" created real confusion. Developers coming from Express thought of it as a pipeline, stack things up, run them in order, app.use everything. That's not what this is and it led to people using it for things it was never meant to do: database calls, heavy business logic, session management.

What it actually does is sit at the network boundary in front of your app and intercept requests before they reach your routes. That's a proxy. The rename is the team saying: this has a specific job. Stop treating it like a general-purpose request pipeline.

The official docs are pretty clear:

Proxy is meant to be invoked separately of your render code. You should not attempt relying on shared modules or globals.

No database calls. No heavy logic. That belongs in the layers behind it, which is exactly what the previous post was about.

The Runtime Change That Actually Matters for Auth

middleware.ts defaulted to the Edge runtime. The Edge runtime had limited crypto support. Verifying JWTs with certain algorithms meant lighter libraries, specific workarounds, and sometimes things that just didn't work depending on which signing algorithm your tokens used.

proxy.ts runs on the Node.js runtime by default in Next.js 16. Full crypto support. jose works completely. Any standard JWT library works. No workarounds.

From the official version history:

v16.0.0: Middleware is deprecated and renamed to Proxy. Proxy defaults to the Node.js runtime

The Node.js runtime in proxy.ts is not configurable. The docs are explicit: the edge runtime is not supported in proxy, the runtime is nodejs, and it cannot be configured. Don't try to change it.

Edge runtime is still available through middleware.ts, which still exists in Next.js 16 for edge-specific cases like geographic redirects or A/B testing at the CDN level. But middleware.ts is deprecated. For auth, you want proxy.ts.

Migrating From middleware.ts

If you haven't done this yet, two options.

Full upgrade codemod for all Next.js 16 breaking changes:

npx @next/codemod@canary upgrade latest

Only the middleware migration if that's all you need:

npx @next/codemod@canary middleware-to-proxy .

After running either one, check these three things manually. Don't trust the codemod alone:

proxy.ts exists at your project root, same level as the app folder
The exported function is named proxy, not middleware
middleware.ts is gone

That third one is more important than it sounds. If you manually bumped the package version without the codemod, your old middleware.ts sits there, compiles clean, passes TypeScript checks, and does nothing at runtime. Routes that should be intercepted aren't. Redirects don't fire. No error anywhere. The file is just silently bypassed.

I covered this in the 4 places Next.js 16 broke my app post. This is the one that hurt the most because everything looks fine until a real redirect fails to fire in staging.

Also check next.config.js if you had skipMiddlewareUrlNormalize — configuration flags containing the middleware name are renamed in Next.js 16, so this is now skipProxyUrlNormalize. The codemod handles it, but worth verifying manually.

Building the proxy.ts Auth Gate

Three decisions in this code that look obvious but aren't. I'll walk through each one after.

// proxy.ts
import { NextResponse } from "next/server"
import type { NextRequest } from "next/server"
import { jwtVerify } from "jose"

// npm install jose
const JWT_SECRET = new TextEncoder().encode(process.env.JWT_SECRET!)

const PUBLIC_ROUTES = [
  "/login",
  "/register",
  "/forgot-password",
  "/reset-password",
  "/api/auth/login",
  "/api/auth/refresh",
  "/api/auth/logout",
  "/",
  "/about",
  "/pricing",
  "/blog",
]

const ROLE_ROUTES: Record<string, string[]> = {
  "/admin": ["admin"],
  "/dashboard": ["admin", "user", "moderator"],
  "/moderator": ["admin", "moderator"],
  "/api/admin": ["admin"],
  "/api/user": ["admin", "user", "moderator"],
}

export async function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl

  if (PUBLIC_ROUTES.some((route) => pathname.startsWith(route))) {
    return NextResponse.next()
  }

  const tokenCookie = request.cookies.get("auth_tokens")?.value

  if (!tokenCookie) {
    const loginUrl = new URL("/login", request.url)
    loginUrl.searchParams.set("redirect", pathname)
    return NextResponse.redirect(loginUrl)
  }

  try {
    const tokens = JSON.parse(tokenCookie)
    const { payload } = await jwtVerify(tokens.accessToken, JWT_SECRET)
    const role = payload.role as string

    for (const [route, allowedRoles] of Object.entries(ROLE_ROUTES)) {
      if (
        (pathname === route || pathname.startsWith(route + "/")) &&
        !allowedRoles.includes(role)
      ) {
        return NextResponse.redirect(new URL("/unauthorized", request.url))
      }
    }

    // Headers go on the request, not the response
    // Server Components read incoming request headers via headers()
    // Setting them on the response sends them to the browser instead
    const requestHeaders = new Headers(request.headers)
    requestHeaders.set("x-user-id", payload.sub as string)
    requestHeaders.set("x-user-role", role)
    requestHeaders.set("x-user-email", (payload.email as string) ?? "")

    return NextResponse.next({
      request: { headers: requestHeaders },
    })
  } catch {
    // Expired token, malformed JWT, bad JSON — all redirect to login
    // Same response for all three, no information leak about which failed
    const loginUrl = new URL("/login", request.url)
    loginUrl.searchParams.set("redirect", pathname)
    return NextResponse.redirect(loginUrl)
  }
}

export const config = {
  matcher: [
    "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt|.*\\.png$|.*\\.jpg$|.*\\.webp$|.*\\.svg$|.*\\.ico$).*)",
  ],
}

Decision 1: The Matcher

This is where most auth setups break. And the way it breaks is the worst possible kind.

Without a matcher, the proxy runs on every request. Every CSS file. Every JS bundle. Every image. That's a JWT verification attempt on each one. When an unauthenticated user hits a CSS request, they get redirected to login, which has no token, which redirects to login again. Infinite redirect loop on static assets. Your app loads for authenticated users but something always feels slow and wrong, and the logs don't explain it.

The negative lookahead in the matcher above excludes static files and keeps the proxy on actual routes:

_next/static : compiled JS and CSS bundles
_next/image : image optimization endpoint
favicon.ico, sitemap.xml, robots.txt : metadata files
.*\\.png$ and the other image extensions : public folder assets

One behavior worth knowing: even if you exclude _next/data in your matcher, the proxy still runs for _next/data routes. This is intentional by design. If you protect a page, the proxy deliberately still covers the corresponding data route so you can't accidentally leave it exposed.

Matcher values must be constants. Statically analyzed at build time. Dynamic values, variables, anything computed gets silently ignored. Another way auth gaps get introduced with zero error output.

Decision 2: The Header Direction

I got this backwards the first time I wrote it.

// This is correct. Headers reach your Server Components
return NextResponse.next({
  request: { headers: requestHeaders },
})

// This is wrong. Headers go to the browser instead
// No error produced
return NextResponse.next({
  headers: requestHeaders,
})

headers() in a Server Component returns incoming request headers. If you set the x-user-id header on the response instead of on the forwarded request, every headers().get("x-user-id") call in your pages returns null. Every authenticated user gets redirected to login. Nothing in the logs to explain it. Took me way longer to debug than it should have.

Decision 3: The try/catch

The catch block handles three failure modes with one redirect: the cookie is valid JSON but the tokens object is malformed, the JWT is structurally broken, or the JWT is expired. All three end at login with no indication of which failed.

Different error responses for different failure modes tell an attacker something about the state of your system. One generic redirect tells them nothing.

The Header Trust Boundary

The proxy sets x-user-id on the request headers before forwarding. Server Components read it with headers().get("x-user-id"). Works fine when the proxy runs.

When does the proxy not run? When the matcher has a gap.

Add a new route, forget to check it falls inside the matcher pattern, the proxy never runs for that route. Nobody set x-user-id. Now a client sends their own x-user-id: someone_elses_id header on that unmatched route. The Server Component reads it. From inside the Server Component, a proxy-set header and a client-sent header look identical — there's no way to tell the difference.

What breaks: if you use that userId to query data, the data layer's AND user_id = $2 still scopes the query correctly. Actual records don't leak. But getUserPermissions(userId) now runs against the wrong user entirely. The attacker gets a different user's permissions back. No records exposed, but a real authorization failure on a specific route.

The fix is verifying the JWT directly from the cookie in the Server Component instead of trusting the forwarded header.

// lib/auth-server.ts
import { cookies } from "next/headers"
import { jwtVerify } from "jose"

const JWT_SECRET = new TextEncoder().encode(process.env.JWT_SECRET!)

type AuthUser = {
  userId: string
  role: string
  email: string
}

export async function getVerifiedUser(): Promise<AuthUser | null> {
  const cookieStore = await cookies()
  const tokenCookie = cookieStore.get("auth_tokens")?.value

  if (!tokenCookie) return null

  try {
    const tokens = JSON.parse(tokenCookie)
    const { payload } = await jwtVerify(tokens.accessToken, JWT_SECRET)

    return {
      userId: payload.sub as string,
      role: payload.role as string,
      email: (payload.email as string) ?? "",
    }
  } catch {
    return null
  }
}

Using it in a Server Component:

// app/dashboard/billing/page.tsx
import { redirect } from "next/navigation"
import { getVerifiedUser } from "@/lib/auth-server"
import { getUserPermissions, getUserInvoices } from "@/lib/data"

export default async function BillingPage() {
  const user = await getVerifiedUser()

  if (!user) {
    redirect("/login")
  }

  const permissions = await getUserPermissions(user.userId)

  if (!permissions.includes("billing:read")) {
    redirect("/unauthorized")
  }

  const invoices = await getUserInvoices(user.userId)
  return <BillingView invoices={invoices} />
}

Yes, this verifies the JWT twice on requests that go through the proxy. The proxy verifies at the network boundary, the Server Component verifies again at render time. That feels redundant. It isn't.

The proxy verification is the fast gate. The Server Component verification removes the trust dependency on the proxy having run at all. On a route where the proxy ran normally, the second verification takes a few milliseconds. On a route where the matcher had a gap, it's what closes the hole. Trusting a header any client can send on any unmatched route is not worth the few milliseconds saved.

Server Functions and the Proxy

Something in the official docs tucked into the execution order section that gets missed:

Server Functions are not separate routes in this chain. They are handled as POST requests to the route where they are used, so a Proxy matcher that excludes a path will also skip Server Function calls on that path.

If your matcher excludes a path, Server Actions on that path run without proxy coverage too. The docs explicitly say to verify authentication and authorization inside each Server Function, not rely on proxy coverage alone.

Same principle as the three-layer model. The proxy is the fast gate, not the complete answer.

Where proxy.ts Sits in the Request Flow

From the official docs, the actual execution order:

headers from next.config.js
redirects from next.config.js
proxy.ts
beforeFiles rewrites from next.config.js
Filesystem routes (public/, _next/static/, pages/, app/)
afterFiles rewrites from next.config.js
Dynamic routes
fallback rewrites from next.config.js

Third. After next.config.js headers and redirects, before anything in the filesystem renders. That's why it's cheap, it intercepts before any React component work starts.

Three Things to Check Before You Ship

JWT_SECRET in every environment. Always in .env.local. Easy to forget in staging or production. The jwtVerify call throws an opaque error when it's missing and authenticated users get sent to login with nothing in the logs that explains why.

Actually verify the migration ran. Check that proxy.ts exists at project root, the export is named proxy, and middleware.ts is deleted. Running the codemod and assuming it worked is not the same as checking. Manual upgrade with no codemod means the old file sits there silently doing nothing with zero warning.

Check the matcher every time you add a protected route. New route, check it falls inside the matcher pattern, check it appears in ROLE_ROUTES. Most auth gaps I've seen get introduced weeks after the initial proxy setup when someone adds a route and nobody goes back to verify coverage.

The proxy is the fast gate. It's essential and does its job well at the network boundary.

It can't answer ownership questions. It can't stop one user from seeing another user's data. And the forwarded header pattern has a real trust boundary issue on any route where the matcher has a gap.

Next post covers the Server Component authorization layer, roles versus permissions, why permissions need a database call that roles don't, and how the independent check at render time catches what the proxy structurally cannot.

Full implementation with all three layers: shubhra.dev/tutorials/nextjs-16-authentication-3-layer-security. The proxy setup in this post maps to Step 2 there. The getVerifiedUser utility above updates the Server Component pattern in Step 3 to close the header trust boundary gap.

Note: I use AI for editing and structure, but the technical substance is from my own work.

I Thought My Next.js 16 Auth Was Solid. One Afternoon Proved Otherwise.

Shubhra Pokhariya — Wed, 10 Jun 2026 07:04:58 +0000

A few months ago I was doing a final pre-release review on a client project before handing it over.

Protected routes were protected. Unauthenticated users got redirected. Tokens expired correctly. I had tested it three different ways and everything held up. I was confident enough to stop thinking about it.

Then I found something.

A user with a valid session, the right role, and a correct JWT could still request another user's invoice if they knew the ID. No error in the logs. No failed requests. The auth was technically correct at every layer I had actually built.

The problem was I had only built one layer and called it done.

That afternoon changed how I think about Next.js 16 authentication entirely. And I have been building it differently ever since.

One Thing to Check Before Writing a Line of Auth Code

If you are coming from Next.js 15, middleware.ts is deprecated in Next.js 16 and replaced by proxy.ts. Same location in your project, different filename, different exported function name. middleware.ts still works for Edge runtime use cases but will be removed in a future version.

// Before: middleware.ts
export function middleware(request: NextRequest) { ... }

// After: proxy.ts
export function proxy(request: NextRequest) { ... }

The auth-relevant change is the runtime. middleware.ts defaulted to Edge runtime, which had limited crypto support. Verifying JWTs in Edge required lighter libraries and sometimes workarounds depending on which algorithms your tokens used.

proxy.ts runs on Node.js runtime in Next.js 16. jose works completely. Any standard JWT library works. It removes the Node-crypto limitations that existed in the Edge runtime, which is a massive improvement for auth specifically.

# Handles the rename and all other Next.js 16 breaking changes
npx @next/codemod@canary upgrade latest

# Only the middleware migration if that is all you need
npx @next/codemod@canary middleware-to-proxy .

After running it: verify proxy.ts exists in your project root and the exported function is named proxy. Remove middleware.ts to avoid ambiguity. While it is still supported for Edge runtime, it is deprecated in Next.js 16 and the framework expects proxy.ts going forward.
Keeping both files can lead to confusion about which one is actually handling requests.

One important constraint: proxy.ts is designed for redirects, rewrites, header modifications, and direct responses. It is not intended for slow data fetching or full session management, and should not be used as your primary authorization layer. This is by design to keep the proxy focused on fast network boundary concerns.

Why proxy.ts Is Not Your Security Layer (Even Though It Looks Like One)

This is the thing almost every Next.js auth tutorial gets wrong. Not in an obvious way. In the way that passes all your tests and breaks in production.

proxy.ts runs at the network boundary before anything renders. It reads your session cookie, verifies the JWT, checks the role, and redirects or continues. Fast, essential, genuinely useful. Every auth setup needs it.

But it only sees URL patterns.

When it decided my user could access /dashboard/invoices, its job was done. It had no idea which specific invoice ID was in the URL, who owned that invoice, or whether the person requesting it had any right to see it. From the proxy's point of view, the URL matched, the role matched, the token was valid. Green light.

That gap is the invoice incident. The proxy was correct. It was just correct about the wrong thing.

// proxy.ts: role-based route protection, correct and valuable
const ROLE_ROUTES: Record<string, string[]> = {
  "/admin": ["admin"],
  "/dashboard": ["admin", "user", "moderator"],
}

// The proxy sees /dashboard/invoices/abc123 and approves it
// It has no way to know if abc123 belongs to this user
// Not a proxy bug. A category mismatch.

The proxy cannot answer ownership questions. Nobody can answer ownership questions from a URL pattern alone. You need the database for that. And the database is not where the proxy runs.

Treating proxy.ts as the complete security layer is not a configuration mistake. It is a mental model mistake. And it is the one almost every auth tutorial makes by stopping there.

The Check That Runs Even When Your Proxy Has a Gap

Server Components render when the page renders. That sounds obvious, but the implication is worth sitting with: Server Components run after the proxy and act as a second layer of enforcement. Even if a route slips past a misconfigured proxy matcher gap, this check still runs.

This is also where you catch the thing the proxy structurally cannot catch: permission-level decisions that depend on your database.

// app/dashboard/billing/page.tsx
import { headers } from "next/headers"
import { redirect } from "next/navigation"
import { getUserPermissions, getUserInvoices } from "@/lib/data"

export default async function BillingPage() {
  const headerStore = await headers()
  const userId = headerStore.get("x-user-id")

  // This check runs even if the proxy had a gap on this route
  if (!userId) {
    redirect("/login")
    return
  }

  // Role came from the JWT, fast, no DB call needed
  // Permissions need a DB call because they change more often than roles
  const permissions = await getUserPermissions(userId)

  if (!permissions.includes("billing:read")) {
    redirect("/unauthorized")
  }

  const invoices = await getUserInvoices(userId)
  return <BillingView invoices={invoices} />
}

The split between roles and permissions is intentional. Roles are stable enough to embed in a JWT. The proxy reads them without touching the database. Permissions change when you update access settings and you do not want to wait for a JWT to expire before that change takes effect. Roles in the proxy, permissions in the Server Component. That boundary matters.

The x-user-id header gets there because the proxy sets it before forwarding the request:

// Inside proxy.ts after JWT verification
const requestHeaders = new Headers(request.headers)
requestHeaders.set("x-user-id", payload.sub as string)
requestHeaders.set("x-user-role", role)

return NextResponse.next({
  request: { headers: requestHeaders },
})
// Headers go on the request, not the response
// Server Components read incoming request headers via headers()
// Setting them on the response sends them to the browser instead
// Your pages never see them if you get this backwards

I got this backwards the first time I wrote it. No error anywhere. The headers() call in the Server Component just returned null for both fields and the page redirected everyone to /login including fully authenticated admins. Spent an embarrassing amount of time on that one.

The Backstop That Would Have Caught the Invoice Bug No Matter What

Even if the proxy had a gap and the Server Component had a gap on the same day, this layer still holds.

Every data function that returns user-specific data takes a userId and uses it inside the query. Not as a convenience. As the actual access control.

// lib/data.ts

// This is what my data layer looked like before the incident
export async function getInvoice(invoiceId: string) {
  return db.query(
    "SELECT * FROM invoices WHERE id = $1",
    [invoiceId]
  )
}
// Anyone with any valid session could call this with any ID
// No error. No log entry. Just data returned to whoever asked.

// This is what it looks like now
export async function getInvoice(invoiceId: string, userId: string) {
  const invoice = await db.query(
    "SELECT * FROM invoices WHERE id = $1 AND user_id = $2",
    [invoiceId, userId]
  )

  if (!invoice) {
    throw new Error("Not found")
  }

  return invoice
}

The same error for "not found" and "not authorized" is intentional. Different errors let an attacker enumerate which IDs exist in your system. One generic error closes that information leak.

The ownership check lives inside the SQL. It cannot be misconfigured away. It cannot be missing from a route someone added last week. It cannot have a matcher gap. The authorization is in the query itself and the query runs every single time.

This is the layer that was missing from my app. The other two were correct. This one did not exist.

What All Three Layers Look Like on One Request

When an authenticated user hits /dashboard/invoices/abc123:

Request arrives

proxy.ts
  Reads auth_tokens cookie (written by your auth API on login)
  Verifies JWT (full Node.js runtime in Next.js 16, jose works completely)
  Checks role against ROLE_ROUTES
  Wrong role? Redirect to /unauthorized
  Correct role? Set x-user-id, x-user-role on request headers, continue

app/dashboard/invoices/[id]/page.tsx
  Reads x-user-id from forwarded headers, no re-verification needed
  Checks billing:read permission against DB
  Missing permission? redirect('/unauthorized')
  Has permission? Call getInvoice(id, userId)

lib/data.ts: getInvoice(invoiceId, userId)
  SELECT * FROM invoices WHERE id = $1 AND user_id = $2
  No row? throw new Error('Not found')
  Row exists? User owns it. Return data.

Component renders.

Three independent checks. A bug at any one of them does not open a door because the other two are still running.

One setup requirement worth knowing before you build this: the proxy reads the session from a cookie. If your auth client stores tokens in localStorage by default, the proxy cannot see them at all and will redirect every authenticated request straight to login. Make sure your auth setup writes tokens to a cookie. The proxy template in the full implementation reads a cookie named auth_tokens set on login.

The invoice incident had no bug in the proxy. No bug in the Server Component. One missing AND user_id = $2 in a data function. That was the whole thing.

The Mental Model in One Sentence

The proxy decides who can reach a route. The Server Component decides who can render a page. The data layer decides who can see a record.

All three are required. Any one of them alone will eventually have a gap. Two of them will eventually have a gap on the same day and you will be glad the third one exists.

The invoice incident was not a proxy failure. Not a Server Component failure. It was a missing data layer. The first two layers were correct. The third one did not exist.

That is the auth system most Next.js tutorials hand you. One layer. The other two are never mentioned.

This post is part of the Next.js 16 Auth: From Broken to Production-Safe series. The next post covers building the complete proxy.ts gate with working code: JWT verification with jose, the role routing config, the matcher pattern that most setups get wrong, and why the header forwarding direction breaks silently when you get it backwards.

The full implementation with all three layers, token refresh, Route Handler protection, and the complete Auth Guard client-side setup is at shubhra.dev/tutorials/nextjs-16-authentication-3-layer-security.

Has anyone else hit a data layer gap like this? I kept assuming the proxy covered everything until it very clearly did not. Curious how common this actually is across different projects.

After 7 Next.js 16 Caching Bugs, I Stopped Guessing and Built a System

Shubhra Pokhariya — Wed, 03 Jun 2026 05:09:01 +0000

There's a specific feeling you get after your third production caching incident.

It's not panic. It's worse than panic. It's that quiet realisation that you fixed the last bug correctly, and you still have no idea where the next one is hiding.

After the 7 silent caching bugs post, a pattern kept coming up in the comments. Everyone understood what was breaking, but not what the correct setup should look like. This is that answer.

Not theory. The actual system I use now, after getting burned enough times to understand why each piece exists.

The first problem: tag strings written from memory in different files

Most silent cache bugs in Next.js 16 start here. Not because anyone is being careless. Because there is nothing stopping two people from writing two different strings that should be the same.

Developer A writes the data function on Monday:

async function getProducts() {
  'use cache'
  cacheTag('product-list')
  return db.query('SELECT * FROM products')
}

Developer B writes the mutation two weeks later in a different file:

export async function createProduct(data: ProductData) {
  await db.query('INSERT INTO products ...', [...])
  revalidateTag('products', 'max')
}

product-list and products. Two different strings. Zero errors from TypeScript, zero warnings from Next.js. The product list never refreshes after a new product is created and nobody knows why until someone reads both files at the same time.

This is Bug 3 from the previous post. I kept hitting variations of it across different parts of the codebase even after I knew about it, because knowing about a problem and having something that prevents it are not the same thing.

The fix is one file that owns all your tag strings:

// lib/tags.ts
export const tags = {
  product: (id: string | number) => `product-${id}`,
  user: (id: string | number) => `user-${id}`,
  productList: 'products',
  userList: 'users',
  navigation: 'navigation',
} as const

Now both files import from tags. A typo is a TypeScript compile error. The string mismatch bug cannot happen. Everyone on the team gets autocomplete instead of muscle memory.

// data function
cacheTag(tags.productList)

// mutation — same import, same string, guaranteed
revalidateTag(tags.productList, 'max')

This is the single change that removed the most bugs from my codebase, by far. Set it up before you write a single cached function on a new project.

The second problem: three different places to invalidate cache, three different correct APIs

This is where I see the most confusion, including in my own early code. The API you reach for depends entirely on where you're calling from and what the user needs to see. Get it wrong and you either throw at runtime or silently give someone stale data.

Here is how I think about it now:

Inside a Server Action where the user who just made a change needs to see it immediately:

'use server'
import { updateTag, revalidateTag } from 'next/cache'

export async function updateProductPrice(id: string, newPrice: number) {
  await db.query('UPDATE products SET price = $1 WHERE id = $2', [newPrice, id])

  updateTag(tags.product(id))               // acting user sees fresh data right away
  revalidateTag(tags.product(id), 'max')    // everyone else gets SWR update
  revalidateTag(tags.productList, 'max')    // product list refreshes too
}

The order matters here. updateTag runs first. This is what prevents the admin from clicking save, navigating back to the product page, and seeing the old price. That looks like the save failed. It causes people to click save again. updateTag fixes it.

updateTag is Server Actions only. Calling it anywhere else throws at runtime.

Inside a Route Handler (webhooks, external services):

// app/api/webhooks/stripe/route.ts
import { revalidateTag } from 'next/cache'

export async function POST(req: Request) {
  const event = await parseStripeWebhook(req)
  if (event.type === 'price.updated') {
    revalidateTag(tags.productList, { expire: 0 })
  }
  return new Response('ok', { status: 200 })
}

updateTag is not available in Route Handlers. { expire: 0 } is the equivalent for immediate expiry here. This is what you want for webhooks where a third-party system just told you something changed.

Background updates where a brief stale window is fine:

revalidateTag(tags.productList, 'max')

Stale-while-revalidate. Users get a fast cached response while fresh data loads behind the scenes. For most content this is exactly right. An admin publishes a new post, readers might see the old list for a moment, that is usually acceptable.

Here is the whole thing as a decision table:

Situation	Use
User edits their own data and needs to see it immediately	`updateTag` then `revalidateTag`
Webhook fires, third-party service needs immediate consistency	`revalidateTag(tag, { expire: 0 })`
Background refresh, brief stale window is acceptable	`revalidateTag(tag, 'max')`

Write this down somewhere your team can see it. Saves a lot of "why is the user seeing old data after saving" conversations.

The third problem: the PPR split is invisible by default

With cacheComponents: true, Next.js uses Partial Prerendering. Your page has a static shell that renders instantly from cache and dynamic holes that stream in after. The performance win is real. The problem is that what ends up in the shell versus what ends up as a dynamic hole is not obvious until something behaves wrong.

One component with cacheLife('seconds') gets quietly excluded from the static shell. A cookies() call inside a cached scope throws at build time with "Uncached data was accessed outside of Suspense" and gives you no component name, no file path, nothing useful. A dynamic component added without a Suspense boundary pushes part of the page out of the shell.

The way I stopped guessing about this is to document intent at the component level:

// components/UserCart.tsx
export const boundary = {
  name: 'UserCart',
  isDynamic: true,
  reason: 'Reads user session cookie — different per user',
}

Then in the page that uses it, I reference that intent explicitly:

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params

  // UserCart is dynamic — must be in Suspense or it breaks the static shell
  return (
    <div>
      <ProductDetails id={id} />       {/* cached, part of static shell */}
      <RelatedProducts id={id} />      {/* cached, part of static shell */}
      <Suspense fallback={<CartSkeleton />}>
        <UserCart productId={id} />    {/* dynamic, streams in after */}
      </Suspense>
    </div>
  )
}

The cached components look like this:

async function ProductDetails({ id }: { id: string }) {
  'use cache'
  cacheLife('hours')
  cacheTag(tags.product(id))

  const product = await db.query(
    'SELECT * FROM products WHERE id = $1', [id]
  )
  return <article>...</article>
}

The dynamic component has no 'use cache' at all:

async function UserCart({ productId }: { productId: string }) {
  const cookieStore = await cookies()
  const userId = cookieStore.get('user-id')?.value
  const cartItem = await db.query(
    'SELECT * FROM cart WHERE user_id = $1 AND product_id = $2',
    [userId, productId]
  )
  return cartItem ? <InCartButton /> : <AddToCartButton />
}

Static shell hits the user instantly. Cart streams in after. The split is intentional and documented, not whatever survived the algorithm.

One more thing on this: never call cookies(), headers(), or draftMode() inside a 'use cache' scope. Read them outside, pass the values as props. Those values become part of the cache key automatically — different users produce separate cache entries without you doing anything extra.

The fourth problem: cold starts hurt the first visitor after every deploy

This one is separate from the bugs but connects to the same goal. Your caching is set up correctly. You deploy. The first visitor hits the page and every cached function runs from scratch sequentially because the cache is empty.

PPR is fast once the cache is warm. That first request after a deploy is not.

The fix is React's cache() for request-level deduplication. Fire all your data fetches in parallel at the top of the page before any component needs them:

import { cache } from 'react'
import { getProductById, getRelatedProducts } from '@/lib/data'

const prefetch = {
  product: cache(getProductById),
  related: cache(getRelatedProducts),
}

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params

  void prefetch.product(id)
  void prefetch.related(id)

  return (
    <div>
      <ProductDetails id={id} />
      <RelatedProducts id={id} />
      <Suspense fallback={<CartSkeleton />}>
        <UserCart productId={id} />
      </Suspense>
    </div>
  )
}

Both fetches fire immediately in parallel. Child components that call the same functions get deduplicated results from React's cache(). If a prefetch fails it fails silently. It is an optimisation, not a requirement. The actual fetching in child components still works.

The distinction worth knowing: React's cache() deduplicates within a single request. 'use cache' persists across requests. You need both, they solve different problems.

What the full system looks like

One tags file. Everyone imports from it. A typo is a compile error, not a production incident.

A clear decision for invalidation context: Server Action with a user waiting for their change uses updateTag first, then revalidateTag. Route Handler uses revalidateTag with { expire: 0 }. Background broadcast uses revalidateTag with 'max'.

Dynamic components documented and always wrapped in Suspense. The static shell is explicit, not accidental.

Prefetch fired in parallel at the top of heavy pages so the first visitor after a deploy is not the one paying the cold start cost.

None of this is complicated once you have it written down. The hard part was figuring out that I needed all of it, which took enough production bugs to see the pattern.

The earlier posts in this series cover how I got here. Building the debugger when development was a black box. The seven bugs that compile and break silently. The upgrade breaks that the build never warns you about.

If you want the full migration reference, I wrote that at shubhra.dev/tutorials/nextjs-16-cache-components.

I kept hitting these edge cases often enough that I eventually pulled the whole system into a single utility. The Cache Pro Kit is the production version of everything in this post. Type-safe tag registry, safeRevalidate that blocks the single-arg call at compile time, serverActionInvalidate that enforces the correct order, routeHandlerInvalidate so updateTag in a Route Handler is impossible. One file, drop into lib/.

What does your caching setup look like right now? Have you hit any of these in your own projects?

Next.js 16 Broke My App in 4 Places and None of Them Threw an Error

Shubhra Pokhariya — Wed, 27 May 2026 08:32:54 +0000

The CI was green.

Build passed. No TypeScript errors. No warnings. Everything looked clean. I clicked deploy and went to make tea.

Came back, opened staging, and things were broken in ways that made no sense. A redirect wasn't working. Lint had silently disappeared from the build pipeline. One API route was throwing on the very first real request. And a revalidation call I'd written two weeks earlier was running but doing nothing.

Not one of these showed up during the build. Everything looked completely fine until it wasn't.

This is what actually happened during my Next.js 16 upgrade, and what to check before you ship yours.

1. `middleware.ts` stopped running and told me nothing

My middleware file was fine. It compiled. The export was valid. TypeScript was happy.

After upgrading to Next.js 16, it just stopped running on requests. No error. No deprecation warning. No sign of anything wrong in the terminal. The file was simply ignored.

What happened: Next.js 16 replaced middleware.ts with proxy.ts. Same location in your project. Different filename. Different exported function name.

// Before: middleware.ts
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

// After: proxy.ts
export function proxy(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

That's the whole change. File rename, function rename. But because the old file didn't throw anything, I assumed it was still running. I only caught it because a redirect I expected wasn't happening and I spent way too long looking at the wrong thing.

One thing to know: if you need edge runtime behavior specifically, middleware.ts still exists for that use case. In my case, the logic I had there stopped running after the upgrade. Renaming the file and export fixed it immediately. The codemod handles this automatically. But if you manually upgraded the package without running it, or if it missed a file, this one is completely invisible.

Before you ship: rename the file, rename the export, test a route that depends on it.

2. `revalidateTag('products')` compiled, deployed, and silently did the wrong thing

During the migration I wrote this:

revalidateTag('products')

One argument. Totally normal in Next.js 15. I'd written it a couple of weeks earlier and hadn't thought about it since.

In Next.js 16, the single-argument form is deprecated and produces a TypeScript error. But only if your tsconfig is in strict mode. Mine wasn't. It had been set up on an older project years ago and never touched.

So it compiled. It deployed. It ran. And it fell back to legacy invalidation behavior instead of the new SWR-based system. Pages weren't reflecting mutations. No error anywhere, just stale data that I attributed to other things for longer than I should have.

The fix is just adding the second argument:

revalidateTag('products', 'max')          // SWR, the recommended default
revalidateTag('products', { expire: 0 })  // Immediate expiry, for webhooks

The codemod (npx @next/codemod@canary upgrade latest) handles this. But if you wrote any revalidation calls after upgrading, or if the codemod missed a file, check manually.

The real fix is turning on strict mode in your tsconfig. That one change makes this a compile error instead of a silent runtime problem:

{
  "compilerOptions": {
    "strict": true
  }
}

Do it before anything else.

3. `next lint` disappeared and my CI kept saying it passed

This one sounds minor. It wasn't.

next lint is completely removed in Next.js 16. Not deprecated. Not changed. Gone. The eslint option in next.config.ts is also gone. next build no longer runs linting automatically.

My CI was configured to run next lint as a step. After the upgrade, that command no longer existed. Depending on how your CI handles missing commands, it might fail loudly or it might just succeed silently and move on. Mine moved on.

So I was shipping code with no linting running, and the CI was reporting green. I only noticed when an obvious issue slipped through that I expected lint to catch.

The migration is to run ESLint directly:

"scripts": {
  "lint": "eslint .",
  "lint:fix": "eslint . --fix"
}

The codemod creates eslint.config.mjs and updates your package.json scripts. But your CI config is a separate file the codemod does not touch. Check both places.

4. One component was still reading `params` synchronously

The codemod updated most of my pages correctly. But I had a layout file it missed. The component was accessing params directly without awaiting it, which is fine in Next.js 15 but wrong in 16 where params is now a Promise.

// Before — Next.js 15
export default function Layout({ params }: { params: { id: string } }) {
  const id = params.id
}

// After — Next.js 16
export default async function Layout({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
}

This one did throw, but only on the first real request to that route in staging, not during the build. The build passed completely clean.

If you have layouts, pages, or route handlers, search the whole codebase for direct params. access and check that every one has been updated. Same goes for searchParams, cookies(), headers(), and draftMode(). All async now, all need awaiting.

The pattern that connects all four

None of these are caching bugs. They're upgrade bugs. The kind where the build passes, the code is technically valid, and the wrong behavior only shows up under a specific condition: a real redirect being triggered, a mutation needing to reflect, a lint issue reaching review, a specific route being hit.

The codemod gets most of this. Run npx @next/codemod@canary upgrade latest before you change anything else. Then check three things manually: grep for any revalidateTag( with a single argument, check your CI config for next lint, and turn on strict TypeScript. Those three cover most of what the codemod can miss.

If you're already past the upgrade and dealing with caching behavior specifically, the previous posts in this series cover that. The debugger I built to make cache behavior visible during development and the seven bugs that compile clean and break silently in production.

I also have a full step-by-step migration guide with before/after comparisons at shubhra.dev/tutorials/nextjs-16-cache-components if you want the complete reference.

Which of these hit you? Or something I didn't mention here?

7 Next.js 16 Caching Bugs That Compile Fine and Break Silently in Production

Shubhra Pokhariya — Thu, 21 May 2026 12:06:06 +0000

I lost hours debugging a Next.js 16 caching issue that had no error, no warning, and only showed up in production.

The Next.js 16 caching model is genuinely good. But it introduces a class of bugs that are harder to detect than anything in previous versions: bugs that look correct, compile without errors, deploy successfully, and then silently misbehave in production.

These are the most common ones I've seen across real projects. Every one comes from real production incidents.

(Assumes you have cacheComponents: true enabled in next.config.ts.)

This is a follow-up to my previous post where I built a dev-only debugger to surface these issues during development. That tool helps you detect them. This post breaks down the exact failure cases behind those warnings.

Bug 1: `'use cache'` on the Wrapper Instead of Inside the Function

// This looks cached. It is not.
export const getProducts = someWrapper(async function() {
  'use cache'
  cacheLife('hours')
  return db.query('SELECT * FROM products')
})

The 'use cache' directive tells the Next.js compiler to treat that function as a cache boundary. When you wrap it, the compiler sees the wrapper as the entry point. The inner function may be cached, but the wrapper becomes the execution boundary, so you still end up running it on every request.

No error. No warning. Just a function running on every request when it should be cached.

Fix:

async function _getProducts() {
  'use cache'
  cacheLife('hours')
  cacheTag('products')
  return db.query('SELECT * FROM products')
}

// Wrapper receives the already-cached function
export const getProducts = someWrapper(_getProducts)

The rule is simple: 'use cache' lives inside the data function, never on anything that wraps it.

Bug 2: Deprecated `revalidateTag` That Compiles and Uses Legacy Behavior

// Next.js 15: correct
// Next.js 16: TypeScript error, silently uses legacy behavior in loose tsconfig
revalidateTag('products')

In Next.js 16, revalidateTag without a second argument is deprecated and produces a TypeScript error. But if your tsconfig is not in strict mode (common in older projects), it compiles cleanly and falls back to legacy invalidation behavior instead of the new SWR-based system.

Pages stop reflecting mutations. No error anywhere.

Fix:

revalidateTag('products', 'max')         // SWR, recommended for most content
revalidateTag('products', { expire: 0 }) // Immediate expiry for webhooks/payments

Run npx @next/codemod@canary upgrade latest during your migration, it handles this automatically. But check your tsconfig strictness regardless.

Bug 3: Tag String Mismatch Across Files

// lib/data.ts -- written by developer A
async function getProducts() {
  'use cache'
  cacheTag('product-list')  // Tag is 'product-list'
  return db.query('...')
}

// app/actions/products.ts -- written by developer B
export async function createProduct(data: ProductData) {
  await db.query('INSERT INTO products ...', [...])
  revalidateTag('products', 'max')  // Different string, invalidates nothing
}

Two different strings. Zero errors. The product list never refreshes after a new product is created. Users see stale data until cacheLife expires on its own.

Fix:

// lib/tags.ts -- one source of truth
export const tags = {
  products: 'product-list',
  product: (id: string) => `product-${id}`,
  user: (id: string) => `user-${id}`,
} as const

// Both files import from tags
cacheTag(tags.products)
revalidateTag(tags.products, 'max')

Tag typos become TypeScript errors. The string mismatch bug becomes structurally impossible.

Bug 4: Server Action Mutation Where the Acting User Sees Stale Data

'use server'
export async function updateProductPrice(id: string, newPrice: number) {
  await db.query('UPDATE products SET price = $1 WHERE id = $2', [newPrice, id])
  revalidateTag(`product-${id}`, 'max')
}

revalidateTag with any named profile uses stale-while-revalidate. It marks the cache as stale. The next request still gets the cached version while fresh data loads in the background.

For the admin who just clicked save, that means they navigate to the product page and see the old price. Looks like the save failed. Causes confusion and duplicate mutations.

Fix:

'use server'
import { revalidateTag, updateTag } from 'next/cache'

export async function updateProductPrice(id: string, newPrice: number) {
  await db.query('UPDATE products SET price = $1 WHERE id = $2', [newPrice, id])
  updateTag(`product-${id}`)            // Acting user sees change immediately
  revalidateTag(`product-${id}`, 'max') // Everyone else gets SWR
  revalidateTag('products', 'max')      // Product list also refreshes
}

updateTag expires the cache entry immediately. The next request waits for fresh data. The admin sees their change. Everyone else gets the fast SWR treatment.

Constraint: updateTag only works inside Server Actions. In Route Handlers, use revalidateTag(tag, { expire: 0 }) instead.

Bug 5: `updateTag` in a Route Handler

// app/api/webhooks/stripe/route.ts
import { updateTag } from 'next/cache'

export async function POST(req: Request) {
  const event = await parseStripeWebhook(req)
  if (event.type === 'price.updated') {
    updateTag('products')  // Throws at runtime
  }
  return new Response('ok', { status: 200 })
}

This compiles. It deploys. On the first real webhook call from Stripe, it throws at runtime. updateTag only works inside Server Actions. Calling it anywhere else throws.

Fix:

import { revalidateTag } from 'next/cache'

export async function POST(req: Request) {
  const event = await parseStripeWebhook(req)
  if (event.type === 'price.updated') {
    revalidateTag('products', { expire: 0 })  // Immediate expiry in Route Handlers
  }
  return new Response('ok', { status: 200 })
}

Bug 6: Short `cacheLife` That Silently Affects PPR

async function LiveStockStatus({ productId }: { productId: string }) {
  'use cache'
  cacheLife('seconds')  // Seems right for live stock data
  cacheTag(`stock-${productId}`)
  return fetchStockLevel(productId)
}

cacheLife('seconds'), revalidate: 0, and expire under 5 minutes are automatically excluded from the PPR static shell. They become dynamic holes that run at request time.

One component with cacheLife('seconds') can push parts of the page out of the static shell and turn them into request-time work. No warning. The page still works. It just becomes fully dynamic without any obvious signal.

Fix, if the data can tolerate a short delay:

cacheLife('minutes')  // Now included in the static shell

Fix, if it genuinely needs to be live:

// Parent page
<Suspense fallback={<StockSkeleton />}>
  <LiveStockStatus productId={id} />  {/* Streams in after static shell */}
</Suspense>

The second approach is the correct PPR pattern for truly dynamic data. The static shell renders instantly and the live data streams in after.

Bug 7: Runtime API Inside a Cached Scope

async function UserHeader() {
  'use cache'
  const cookieStore = await cookies()  // Throws at build time
  const user = await getUser(cookieStore.get('user-id')?.value)
  return <div>{user.name}</div>
}

cookies(), headers(), and draftMode() are runtime APIs. They read request-specific data. They cannot live inside a 'use cache' scope because cached output is stored and replayed across requests.

This one at least throws at build time with "Uncached data was accessed outside of Suspense". But the error gives you no component name, no file path, and no useful stack trace. You get to play binary search across your codebase to find it.

Fix:

// Read runtime values OUTSIDE the cached scope
async function UserHeader() {
  const cookieStore = await cookies()
  const userId = cookieStore.get('user-id')?.value
  return <CachedUserProfile userId={userId} />
}

// Pass the VALUE as a serializable prop to the cached component
async function CachedUserProfile({ userId }: { userId?: string }) {
  'use cache'
  cacheLife('hours')
  cacheTag(`user-${userId}`)
  if (!userId) return <GuestGreeting />
  const user = await getUser(userId)
  return <div>{user.name}</div>
}

userId is a string so it becomes part of the cache key automatically. Different users produce different cache entries without any manual key construction.

The Common Thread

None of these have good error messages. Five of the seven compile and deploy without complaint. The other two throw, but either without enough information to find the cause quickly or only after the first real production request.

The pattern across all of them is the same: the new caching model requires explicit correctness. When you get something wrong, it does not always tell you.

If you are in the middle of a Next.js 16 migration and want to catch these during development rather than in production, I ended up building a free dev-only debugger that logs cache misses, dynamic holes, missing tags, and deprecated invalidation calls directly in your terminal. Zero production cost, one .tsx file: Next.js cache debugger.

And if you want these patterns enforced at the type level so the wrong call is a compile error rather than a runtime surprise, the production enforcement layer is Cache Pro Kit.

Have you run into any of these? Or something even stranger? I'm curious what the distribution looks like across different kinds of projects.

I built a free debugger because Next.js 16 'use cache' was completely invisible during development

Shubhra Pokhariya — Tue, 19 May 2026 10:29:28 +0000

I spent an afternoon debugging a component that kept re-fetching on every single request.

It had 'use cache' right there in the code. I was confident it was working. It wasn't.

The problem was placement. 'use cache' was on the wrapper function, not inside the actual data function. That one mistake makes Next.js ignore the directive entirely. No error, no warning, nothing in the terminal. Just a function running on every request when it should have been cached.

Another time I wrote this in a Server Action during a Next.js 16 migration:

revalidateTag('products')

It compiled. It deployed. Pages stopped reflecting mutations. Calling revalidateTag without a second argument is a TypeScript error in Next.js 16, but the runtime fell back to legacy behaviour silently. I only caught it when users started reporting stale data.

Next.js 16's new caching model is genuinely great. But during development it is a complete black box. You add the directive, you assume it works, and you only find out otherwise when something breaks in production.

So I built a small dev-only toolkit to make it visible.

What it catches

1. Silent cache misses

If a function runs more than once with identical arguments, you see this immediately:

[cache-debug] ⚠  POSSIBLE CACHE MISS - RE-EXECUTION WITH SAME ARGS
  fn:   getProductById
  args: ["prod-123"]
  This function ran 2 times with identical args.
  If you expect caching: check 'use cache' is inside this function, not the wrapper.

That warning would have saved me that entire afternoon.

2. Dynamic holes from short cacheLife

cacheLife('seconds') silently excludes a component from the PPR static shell. It becomes fully dynamic. No warning anywhere, just a slower page that you cannot explain.

[cache-debug] ⚡ DYNAMIC HOLE WARNING
  fn:       getLivePrice
  cacheLife 'seconds' is short-lived (< 5 minutes or revalidate: 0).
  Next.js 16 automatically EXCLUDES this from the PPR static shell.
  This function will run at request time, it is NOT prerendered.
  Fix: Use 'minutes' or longer if you want it in the static shell.

3. Missing cacheTag

A cached function with no cacheTag() can only expire by time. You cannot revalidate it on demand. Easy to miss when moving fast, painful to discover later.

[cache-debug] 🏷  MISSING cacheTag WARNING
  fn:   getProductById
  No cacheTag() found. This function cannot be invalidated on demand.
  It will only expire when cacheLife runs out.
  Fix: Add cacheTag('your-tag') inside the function.

4. Deprecated revalidateTag

In Next.js 16, revalidateTag('tag') without a second argument is a TypeScript error. The logInvalidation helper catches it before your CI does:

[cache-debug] ✗  DEPRECATED revalidateTag - MISSING SECOND ARG
  tag:     products
  revalidateTag('products') without a profile is deprecated in Next.js 16.
  Fix: revalidateTag('products', 'max')

5. updateTag outside a Server Action

Calling updateTag outside a Server Action throws at runtime. The toolkit catches it at dev time before it reaches production.

6. Repeated fetches

detectRepeatedFetch surfaces the same URL being hit multiple times in one render. Usually means a cache layer is missing entirely.

How to use it

Step 1: Enable in .env.local

CACHE_DEBUG=true

Do not add this to .env.production. The NODE_ENV guard already ensures it is off in production, but keeping env files clean is good practice.

Step 2: Wrap your cached functions

The 'use cache' directive must stay inside the original function. withCacheDebug is a regular wrapper and cannot be a cache boundary. If you put 'use cache' on the wrapper, the instrumentation gets cached instead of the data function, which is exactly the mistake the POSSIBLE CACHE MISS warning is designed to catch.

import { cacheLife, cacheTag } from "next/cache";
import { withCacheDebug } from "@/lib/cache-debug";

async function _getProductById(id: string) {
  "use cache";
  cacheLife("hours");
  cacheTag(`product-${id}`, "products");
  return db.query("SELECT * FROM products WHERE id = $1", [id]);
}

export const getProductById = withCacheDebug(_getProductById, {
  name: "getProductById",
  cacheLife: "hours",
  tags: ["product-{id}", "products"],
});

const product = await getProductById("prod-123");

Zero API change. The exported function works exactly the same everywhere you already call it.

Step 3: Log invalidation calls in Server Actions

"use server";
import { revalidateTag, updateTag } from "next/cache";
import { logInvalidation } from "@/lib/cache-debug";

export async function updateProductPrice(id: string, newPrice: number) {
  await db.query("UPDATE products SET price = $1 WHERE id = $2", [newPrice, id]);

  logInvalidation("updateTag", `product-${id}`, {
    isServerAction: true,
    context: "admin price update",
  });
  updateTag(`product-${id}`);

  logInvalidation("revalidateTag", "products", {
    profile: "max",
    isServerAction: true,
    context: "admin price update",
  });
  revalidateTag("products", "max");
}

Honest limitations

Process-scoped. Execution maps reset on cold start. In serverless environments each invocation may be a fresh process, so you will only see re-execution data within the same warm instance. For local dev with a long-running server it works exactly as intended.
Best-effort concurrency. Under concurrent rendering with identical args, both calls may log FIRST RUN rather than a miss. Detection does not affect correctness.
Cannot inspect Next.js internals. The debugger counts executions to detect likely misses. It cannot read Next.js's internal cache store directly.

None of these affect production because the tool is not present there.

At a glance

What it detects	Without this tool
FIRST RUN / CACHE MISS / NEW KEY	Not visible
Dynamic hole from short cacheLife	Not visible
Missing cacheTag	Not visible
Deprecated revalidateTag	TypeScript error, easy to miss
updateTag outside Server Action	Runtime throw
Repeated fetches in one render	Not visible

Zero external dependencies. TypeScript 5.0+ with strict mode. Next.js 16 only -- updateTag does not exist in Next.js 15. Double-gated on NODE_ENV === 'development' AND CACHE_DEBUG=true so nothing ships to production. No overhead, no bundle impact.

Get it

Free forever, one .tsx file: shubhra.dev/snippets/nextjs-use-cache-debugger

If you want the production enforcement layer that pairs with this -- type-safe tag registry, safeRevalidate that blocks the deprecated single-arg call at compile time, serverActionInvalidate that enforces the correct invalidation order -- that is the Cache Pro Kit.

If you are new to the Next.js 16 caching model and want to understand what 'use cache', cacheLife, and cacheTag are actually doing before using this toolkit, the practical migration guide covers the full picture. There is also a 15-question quiz if you want to test your understanding.

If you are in the middle of a Next.js 16 caching migration and something is behaving unexpectedly, this will make it visible. What has been the most frustrating or confusing part of the new caching model for you?

Lighthouse Said It Was Fast. My Users Kept Clicking the Same Button.

Shubhra Pokhariya — Wed, 06 May 2026 09:46:33 +0000

The bug wasn’t performance. It was silence.

I ran into this while building a Next.js dashboard.

There was a button that triggered a report generation flow. Some client-side processing, then an API call.

Lighthouse looked great. API response was around 80ms.

But session recordings told a different story.

Users were clicking the button 3 to 5 times in a row.

No errors in logs. No failed requests. Everything technically worked.

So I watched one of the recordings more carefully.

The moment the user clicked, nothing changed on screen.

No loading state.
No disabled button.
No visual feedback at all.

The UI looked exactly the same before and after the click.

That was the issue.

80ms response, zero perceived response

The backend was fast.

The interface just didn’t acknowledge the interaction.

From the user’s point of view, the click didn’t go through.

So they clicked again.

And again.

Not because they were impatient. Because the UI stayed silent.

Where most of us focus (and where it falls short)

We spend a lot of time optimizing load performance.

FCP, LCP, bundle size, Lighthouse scores. All worth caring about.

But most of the time a user spends on your app happens after the page has loaded.

That’s where trust is decided. In the interactions.

The 200ms line

There’s a threshold that shows up consistently in real usage.

If the UI responds within roughly 100 to 200ms, it feels instant.

Between 200 and 500ms, the delay becomes noticeable.

Beyond that, people start questioning whether their action worked.

A slow app is frustrating. An app that feels unresponsive gets abandoned.

What INP actually measures

INP (Interaction to Next Paint) focuses on one thing:

How long it takes for the user to see a response after they interact.

Not when your API returns.
Not when your function finishes.

When something visibly changes on the screen.

That’s what closes the loop.

The fix was not “make it faster”

The fix was: acknowledge the interaction immediately.

Instead of doing all the work first:

button.addEventListener("click", async () => {
  await processData();
  await syncWithServer();
  setLoading(false);
});

Flip it:

button.addEventListener("click", async () => {
  setLoading(true); // immediate visual feedback

  await scheduler.yield(); // let the browser paint

  await processData();
  await scheduler.yield();

  await syncWithServer();

  setLoading(false);
});

If scheduler.yield() is not available yet in your environment, a simple fallback works:

const yieldToMain = () => new Promise((r) => setTimeout(r, 0));

Same total work. Same total time.

Completely different experience.

Users stopped clicking multiple times.

The pattern you already use

You’ve seen this in every modern app.

You tap like. It updates instantly. The server confirms later.

That’s optimistic UI.

Here is the same idea in a simple form:

async function handleLike(postId) {
  setLiked(true);
  setCount((c) => c + 1);

  try {
    await api.like(postId);
  } catch {
    setLiked(false);
    setCount((c) => c - 1);
  }
}

In React and Next.js setups, this maps cleanly to useOptimistic and Server Actions.

The idea stays the same:

Show the result immediately. Reconcile in the background.

Why this matters more than Lighthouse 100

Lighthouse runs in controlled conditions.

Your users don’t.

They’re on slower devices, switching tabs, running background apps, dealing with network jitter.

You can ship a perfect score and still have interactions that feel off.

INP exposes that gap.

If you want to go deeper

This bug was the entry point for me.

I ended up breaking this down properly across INP, optimistic UI, task yielding, and how this fits into modern Next.js setups like Server Actions and streaming.

I wrote it up in detail here:
https://shubhra.dev/tutorials/performance-first-ui-mastery-guide-2026

That one goes deeper into how to actually implement this in real apps. This post is just the moment where the problem becomes obvious.

A quick way to test this

While working through this, I built a small quiz to check if I actually understood the idea or was just agreeing with it.

Here’s one of the questions:

A user clicks a button.
The server responds in 80ms.
They click four more times.

What actually failed?

Most people still go to backend performance first.

If that was your instinct too, you’ll probably find the rest useful:

https://shubhra.dev/quiz/performance-first-ui

It’s short. Focused on real interaction problems. No trick questions.

One practical takeaway

Next time you write a click handler, check the order:

Does something change on screen immediately?
Or does all the work happen before the user sees anything?

That one decision is often the difference between a UI that feels fast and one that feels broken.

If you’ve run into this in your own apps, I’m curious what caused it and how you approached it.

Why Most React Infinite Scroll Hooks Fail in Production (and the One That Fixed It for Me)

Shubhra Pokhariya — Thu, 30 Apr 2026 11:28:52 +0000

I used to believe infinite scroll was one of the simplest features to implement.

Fetch data → append to a list → load more on scroll.

Easy, right?

That’s exactly how most tutorials show it.

And honestly… it works.

Until it doesn’t.

The Bug That Changed Everything

One bug completely changed how I think about infinite scroll.

A user changed a filter → the list reset → new data loaded.

Everything looked correct.

Then a couple of seconds later…

the old results came back and overwrote the new ones.

No errors. No warnings.

Just silently broken UI.

What actually happened?

A slow request from the previous state finished late and updated the UI with stale data.

That was the moment I realized:

Infinite scroll doesn’t break in demos.It breaks with real users, real timing, and real networks.

Where Things Start Falling Apart

After that, I started noticing the same issues again and again:

Stale requests overwriting fresh data after reset
Retry logic fetching the wrong page
IntersectionObserver continuing to fire after errors
Duplicate requests in React Strict Mode
Loading states that never resolve

These problems rarely show up locally.

But in production, they show up fast.

What I Actually Needed

Not another demo.

Something I could trust in a real app.

So I built a hook around one idea:

Control the async flow. Don’t just “load more data”

What This Hook Handles

✔ Cancels stale requests (no overwrite bugs)
✔ Smart retry logic (correct page every time)
✔ Proper observer cleanup (no leaks)
✔ React 18+ Strict Mode safe
✔ Clear initial vs pagination loading states
✔ Manual loadMore, reset, and retry
✔ Zero dependencies

Basic Usage

const {
  items,
  isInitialLoading,
  hasMore,
  error,
  loadMoreRef,
  retry,
  reset
} = useInfiniteScroll({
  fetchFn: async (page, signal) => {
    const res = await fetch(`/api/posts?page=${page}`, { signal });
    return res.json();
  },
  pageSize: 20,
});
return (
  <div>
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.title}</li>
      ))}
    </ul>

    {/* Sentinel element */}
    <div ref={loadMoreRef} />

    {error && <button onClick={retry}>Retry</button>}
  </div>
);

Real Use Case: Reset on Filter Change

This is where most bugs happen.

useEffect(() => {
  reset(); // cancels old request + reloads safely
}, [filter]);

Without proper handling, this is exactly where stale data bugs appear.

Why AbortController Matters So Much

Before using it:

old requests still resolved
stale data overwrote the UI

After using it:

old requests get cancelled immediately
they never reach your state

That single change removes an entire class of bugs.

One Honest Note

This hook handles most real-world issues.

But for very large lists, you should still use virtualization
(like react-window or tanstack/virtual).

Infinite scroll solves loading.

Virtualization solves rendering.

Try It Yourself

You can grab the full hook here:

👉 https://shubhra.dev/snippets/use-infinite-scroll

MIT licensed
free to copy and modify
built for real production cases

Final Thought

I didn’t build this because infinite scroll is hard.

I built it because the small edge cases are what break real products.

Slow APIs. Fast users. Overlapping requests.

That’s where things actually fall apart.

Curious - what broke for you?

Have you ever hit a weird infinite scroll bug in production?

Something like:

duplicate data
stale UI
loading that never stops

Would genuinely love to hear what you ran into.

I Turned My Blog Into a Full Developer Platform (Tutorials + Snippets + Quizzes + Tools)

Shubhra Pokhariya — Tue, 28 Apr 2026 12:25:37 +0000

I’ve been working on building a developer platform with tutorials, reusable code snippets, interactive quizzes, and practical tools. This post shares what changed and what I’m building now.

For the past few months, I’ve been a little quiet here.

If you’ve been active on Dev.to regularly, you probably noticed I wasn’t reading as many posts, commenting, or sharing like I used to. And honestly, I missed that.

This community has always been one of my favorite places to learn and grow. Reading how others think, build, and solve problems has helped me a lot in my own journey.

So stepping away from that wasn’t easy.

Why I Went Quiet

I reached a point where I felt like just writing blog posts wasn’t enough for me anymore.

Don’t get me wrong, I still love writing. But I kept thinking:

What if I could make something more useful than just articles?

Something that helps people not only read, but also:

try things quickly
test their understanding
and actually use code in real projects

That idea stayed in my mind for a while.

And instead of talking about it, I decided to just build it.

What I’ve Been Working On

I took my simple blog and slowly turned it into something more complete.

Now it’s not just posts. It includes:

Tutorials that go step by step

Here’s how one of the tutorials looks:

Small, practical code snippets you can directly use

A quick example of a reusable snippet in action:

Quizzes to test concepts in a quick way

Here’s a quick look at how the quiz works:

Here’s a small taste of what the quizzes look like:

1. What does the === operator do?

Checks for value equality only
Checks for reference equality only
Checks for both value and type equality without coercion
Assigns a value

→ Correct answer: Checks for both value and type equality without coercion

2. What is a closure in JavaScript?

A way to immediately end a function
A function that retains access to its outer scope
A syntax error
A loop

→ Correct answer: A function that retains access to its outer scope

3. What will typeof null return?

'null'
'undefined'
'object'
'number'

→ Correct answer: 'object'

A couple of products built from things I personally needed

It’s still growing, still improving, and definitely not perfect.

But it feels closer to what I actually wanted to create.

What Changed for Me

Earlier, I was mostly focused on sharing information.

Now I’m trying to focus more on usefulness.

Instead of just explaining things, I want to:

make it easier to apply them
keep things simple and practical
and help someone save time when they’re stuck

Even the smallest snippet can be helpful if it solves a real problem.

I Missed This Community

One thing I realized during this time is how much I value this space.

Reading posts here, seeing different approaches, and learning from others is something I genuinely enjoy.

I missed that part.

So I’m coming back, not just to share, but also to read, learn, and engage again.

What You’ll See From Me Now

I’ll start sharing more regularly again, but with a slightly different approach.

You’ll see things like:

small useful snippets
short explanations
occasional deep tutorials
and some interesting questions or quizzes

Nothing too heavy. Just practical and helpful.

If You Want to Check What I Built

Here’s how everything comes together:

If you’re curious, you can take a look here:

https://shubhra.dev/

No pressure at all. Just sharing what I’ve been working on.

One Small Thought

Sometimes we feel like we need to keep posting consistently no matter what.

But taking a step back to build something meaningful can be just as important.

For me, this phase helped me rethink what I actually want to create and share.

And I’m glad I took that time.

I’m looking forward to reading your posts again and being more active here.

If you’ve been working on something quietly too, I’d love to hear about it.

Performance First UI Taught Me More Than Any Framework Ever Did

Shubhra Pokhariya — Mon, 12 Jan 2026 10:40:43 +0000

The slowest app I ever worked on had a perfect performance score.

That sentence used to confuse me.

Everything was optimized. Bundles were trimmed. Images were compressed. Lighthouse smiled back at me like a proud teacher.

And yet, users kept behaving strangely.

They clicked twice.

They hesitated.

They abandoned flows halfway through.

At first, I blamed users. Then devices. Then networks.

Eventually, I blamed myself.

That was the moment I started understanding performance first UI.

Speed is not what developers think it is

As developers, we grow up believing speed is a number.

Milliseconds.

Scores.

Graphs.

But users never see numbers. They feel moments.

The moment after a click.

The moment after a tap.

The moment when they expect acknowledgment.

If nothing happens in that moment, something breaks not technically, but emotionally.

The day I stopped trusting Lighthouse alone

Lighthouse is useful. It taught an entire generation to care about performance.

But in 2026, relying on Lighthouse alone is like judging a car by how fast it accelerates on an empty track.

Real users drive in traffic.

They scroll while data loads.

They click while JavaScript executes.

They type while hydration finishes.

That’s where performance first UI lives, not at load time, but during interaction.

Interaction is the real contract with the user

A page load is an introduction.

An interaction is a promise.

When a user clicks a button, they are not asking for data. They are asking for reassurance.

Did you hear me?

Are you working?

Can I trust you?

If your interface stays visually silent, the promise is broken.

Why Interaction to Next Paint quietly changed everything

Interaction to Next Paint does something rare in web metrics.

It measures reality.

Not when logic finishes.

Not when promises resolve.

But when pixels change.

This sounds obvious, but it reframes how you write UI code.

Because suddenly, doing work before paint feels dangerous.

If this shift in thinking around Interaction to Next Paint resonated with you, I’ve explored it in much more depth in my long-form guide Performance First UI Mastery: A Critical Guide for 2026 Developers, where I break down real-world examples, beginner-to-advanced concepts, and how this mindset plays out in modern Next.js apps.

The hidden enemy of modern interfaces

Most INP problems are not caused by slow servers.

They are caused by good intentions.

Too much logic inside event handlers
Too many state updates
Too many components reacting at once

Everything works. Everything is correct. Everything is just slightly late.

And that slight lateness compounds.

The small habit that fixed most of my issues

The biggest improvement I ever made to interaction performance was embarrassingly simple.

I stopped doing real work before showing feedback.

Instead of:

Click → compute → update UI

I switched to:

Click → update UI → compute

Nothing fancy. No new libraries.

Just respect for the paint cycle.

Why modern Next.js makes this mindset possible

Next.js quietly evolved alongside performance first UI thinking.

Partial Prerendering lets interfaces appear ready before they are complete.
Streaming lets content arrive without blocking interaction.
Server Actions let the UI move first and confirm later.
Edge Middleware removes entire decision trees from the client.

Used correctly, these tools keep the browser free to respond.

Performance is not about doing less, it’s about doing things later

This was a hard lesson for me.

I used to chase minimalism. Fewer features. Smaller bundles.

But performance first UI taught me something better.

You can do a lot, just not all at once.

Defer what the user cannot see.

Delay what the user does not care about yet.

Focus on what the user just did.

The business side developers rarely talk about

Here’s an uncomfortable truth.

A sluggish interaction costs more than a slow page load.

Because interaction delay happens when the user is already invested.

They clicked.

They intended.

They were ready.

Losing them here hurts conversion far more than a slow landing page.

Performance is becoming a human skill again

In 2026, AI can generate components.

AI can refactor code.

AI can optimize assets.

But AI cannot feel hesitation.

It cannot sense when a transition feels awkward.

It cannot sense when feedback arrives too late.

That sensitivity is now the developer’s real value.

What performance first UI actually demands from us

It demands patience.

It demands that we observe our own interfaces instead of trusting dashboards.

It demands that we click our own buttons slowly and ask:

Does this feel respectful?

Not impressive.

Not clever.

Respectful.

Final thought

Performance first UI is not a trend. It is a correction.

A return to building software that listens.

If your UI responds instantly, users forgive imperfections.

If it hesitates, they remember.

In the end, performance is not about speed.

It is about trust.

How CSS Animation Helped Me Build Interfaces That Feel Alive

Shubhra Pokhariya — Mon, 22 Dec 2025 06:24:42 +0000

I always believed great UI was about color, spacing, structure, and typography. I spent years improving those things. I obsessed over grids. I experimented with type scales. I rewrote layout systems again and again.

Yet something still felt missing.

Every interface I created worked perfectly, but emotionally it felt silent. It behaved like a machine. Nothing moved unless a page refreshed. Nothing acknowledged the user. I did not realize how empty that silence was until I compared my projects with modern interfaces around the web.

Some apps felt warm and alive, even though their layouts were simple. Their buttons breathed. Their cards shifted gently when hovered. Even status messages faded in and out like they had personality.

I kept asking myself

How are they doing that?

That question pushed me toward CSS Animation.

Not as a design trend
but as a missing piece of expression.

My First Real Encounter With Motion

My turning point arrived inside a dashboard project. Everything looked clean and minimal. The data tables worked. The navigation was solid. The code was tidy.

But the experience lacked a pulse.

One evening while polishing the UI, I decided to animate only a single button. Not to impress anyone, but to understand how it would feel. I added a soft hover lift and a clearer color transition. Nothing dramatic.

The moment I refreshed the browser
the UI reacted like it suddenly woke up.

The button rose slightly.

The shadow deepened.

It felt like the interface acknowledged me.

It was such a small change that the code barely filled a few lines, and yet the product felt more professional instantly.

That tiny success completely changed how I saw CSS Animation.

Why Motion Matters To Users

Modern users expect movement even if they cannot explain why.

Motion tells the brain something is happening.

It guides attention with subtle cues.

It communicates structure faster than text.

When a button lifts
you know it is clickable.

When content fades gently
you understand that something changed without reading anything.

Motion replaces confusion with instinct.

Once I understood that, I saw animation everywhere:

apps, websites, mobile UI, operating systems, ecommerce stores.

Motion has become the language of modern interaction.

CSS Animation Is Not Just Decoration

Before learning it deeply, I believed animation was fancy.

I assumed it slowed pages down.

I thought it was extra work for no real benefit.

All of that was wrong.

CSS Animation can improve usability in extremely practical ways:

Guiding users to the next step
Confirming they clicked something
Building visual rhythm
Reducing visual shock
Improving brand identity
Creating focus without clutter

Motion is not frosting on top of UI. It is part of UI itself.

The Mindset Shift That Helped Me Learn Faster

The biggest challenge was learning how to think about motion.

I stopped asking How do I make this look cool?

and started asking What should the user feel here?

When they open a page, maybe they should feel welcomed.

When they press save, maybe they should feel confirmed.

When they hover over content, maybe they should feel engaged.

That mindset turned animation into storytelling.

Why CSS Animation Works So Well With Modern UI

CSS Animation is not heavy, nor complicated, nor dependent on JavaScript.

It is built to run smoothly if you animate the right properties.

Transforms and opacity create GPU-powered motion that feels fluid even on average devices.

The more I practiced, the more confident I became because I saw that animation can stay clean and fast when done with purpose.

The Most Surprising Part

Clients noticed the improvements immediately.

They could not describe what changed in technical language,

but they kept saying the same thing -
"This feels better.",

Not This looks better, but This feels better.
That sentence taught me something powerful:

Users care about feeling, not code.

A New Way Of Seeing My Projects

Today I build interfaces very differently.

I do not start by applying motion everywhere.

I begin by searching for moments where the UI speaks to users.
Moments that deserve attention, and moments that need softness.

Sometimes it is a card hover.

Sometimes it is a hero title reveal.

Sometimes it is a form success message.

Motion is now part of my design decisions, not an afterthought.

Want To Learn How I Apply CSS Animation To Real UI

I recently wrote a deep story and breakdown on my blog showing how CSS Animation reshaped my understanding of UI feeling and movement.

You can read it here:

👉 https://blog.shubhra.dev/css-animation-level-up-ui

If you are a developer who wants your UI to feel more human, this will help you see animation differently.

Final Thought

The moment you experience your first animated interaction that feels natural, not flashy, you understand why motion matters.

CSS Animation is not only a visual tool, it is emotional design.

And once you learn it, you never see UI the same way again.

The CSS Positioning Chaos: Why Your Elements Run Away (And How I Finally Mastered the 5 Keys)

Shubhra Pokhariya — Fri, 28 Nov 2025 07:54:55 +0000

There is a special kind of chaos that only frontend developers understand.

The kind where your layout looks perfect one second and then suddenly one button escapes to the top corner of the screen like it has its own dreams and ambitions.

That chaos usually has a name: CSS Positioning.

Every developer goes through this phase.

Every beginner gets confused.

And honestly, even after years of working with CSS, I still smile whenever someone asks me:

“Why does my element move when I scroll?”

Because that question reminds me of my own journey, a journey full of tiny mistakes, confused evenings, and small victories that made CSS feel less like a puzzle and more like a friend.

Recently, I wrote a full blog post on my main site where I broke down CSS Positioning in the simplest, most practical way I could.

Today I wanted to share a little behind the scenes of that post and also explain why CSS Positioning deserves more love than it gets.

The Phase Where CSS Positioning Made Me Doubt My Career Choices

Let me tell you something honestly.

In my early days of coding, nothing confused me more than absolute and relative.

I remember placing a badge inside a hero section and the moment I refreshed the page, it flew somewhere completely unrelated.

I thought I broke the browser. I even restarted my laptop once thinking something was wrong with VS Code.

Little did I know it was just CSS Positioning doing its usual drama.

static was too simple
relative felt too subtle
absolute felt too free
fixed felt too stubborn
sticky felt like magic

And because I did not understand their personalities, I kept fighting them instead of letting them help me.

It took me weeks to finally understand that CSS Positioning is not just about moving elements around.

It is about understanding how the browser thinks.

How it calculates boundaries.

How it decides the containing block.

How each element follows a very logical set of rules.

Once I understood this, the fear disappeared.

And CSS started feeling like a superpower.

The Beauty Behind Understanding CSS Positioning

When you truly understand CSS Positioning, you begin to see your layout differently.

Static becomes your calm baseline.
Relative becomes your gentle adjustment tool.
Absolute becomes the creative freedom you use when you want elements to float exactly where you want.
Fixed becomes your loyal companion for floating buttons and sticky helpers.
Sticky becomes the modern magic that makes long pages feel smoother.

The moment you master these five:

your designs stop breaking
your elements stop running away
and your confidence grows instantly

This is why CSS Positioning is not just a “topic” — it is a core foundation that every modern frontend layout quietly depends on.

The Best Way To Learn CSS Positioning Is Not Memorizing It

One of the main things I shared in my WordPress post is something simple but important:

CSS Positioning is not learned through memorization.

It is learned through experience.

You learn it by:

building small boxes
adding a badge
scrolling a page
trying absolute without relative
trying sticky inside a tiny container
placing a button with fixed
and observing every single behavior

This hands‑on curiosity is what transforms CSS Positioning from confusing to intuitive.

And once it clicks, you will wonder how you ever struggled with it.

Why This Topic Deserves More Attention

We often jump directly into Flexbox, Grid, animations, Tailwind, frameworks, and component libraries.

But behind all of them, positioning still plays a silent role.

The moment something goes wrong,

the moment a layout shifts,

the moment an element overlaps,

the moment a menu disappears,

we all return to the same root question:

“Where is this element positioned, and relative to what?”

Understanding CSS Positioning early saves so much frustration later.

Final Thoughts

CSS Positioning is not scary.

It is simply misunderstood.

And once you understand how these five values behave, you will start designing with more confidence, clarity, and creativity.

Whether you are:

a beginner trying to place a small badge
a student building a landing page
or someone revisiting fundamentals after years

CSS Positioning is one of those topics that rewards you every time you give it attention.

If you want the full detailed breakdown, the real examples, and the step‑by‑step mental model, check out my complete WordPress guide:

👉 CSS Positioning: The 5 Keys to Master Static, Relative, Absolute, Fixed, Sticky

DEV Community: Shubhra Pokhariya

I Got the proxy.ts Matcher Wrong for Three Projects Before I Understood Why

Why the Name Changed

The Runtime Change That Actually Matters for Auth

Migrating From middleware.ts

Building the proxy.ts Auth Gate

Decision 1: The Matcher

Decision 2: The Header Direction

Decision 3: The try/catch

The Header Trust Boundary

Server Functions and the Proxy

Where proxy.ts Sits in the Request Flow

Three Things to Check Before You Ship

I Thought My Next.js 16 Auth Was Solid. One Afternoon Proved Otherwise.

One Thing to Check Before Writing a Line of Auth Code

Why proxy.ts Is Not Your Security Layer (Even Though It Looks Like One)

The Check That Runs Even When Your Proxy Has a Gap

The Backstop That Would Have Caught the Invoice Bug No Matter What

What All Three Layers Look Like on One Request

The Mental Model in One Sentence

After 7 Next.js 16 Caching Bugs, I Stopped Guessing and Built a System

The first problem: tag strings written from memory in different files

The second problem: three different places to invalidate cache, three different correct APIs

The third problem: the PPR split is invisible by default

The fourth problem: cold starts hurt the first visitor after every deploy

What the full system looks like

Next.js 16 Broke My App in 4 Places and None of Them Threw an Error

1. middleware.ts stopped running and told me nothing

2. revalidateTag('products') compiled, deployed, and silently did the wrong thing

3. next lint disappeared and my CI kept saying it passed

4. One component was still reading params synchronously

The pattern that connects all four

7 Next.js 16 Caching Bugs That Compile Fine and Break Silently in Production

Bug 1: 'use cache' on the Wrapper Instead of Inside the Function

Bug 2: Deprecated revalidateTag That Compiles and Uses Legacy Behavior

Bug 3: Tag String Mismatch Across Files

Bug 4: Server Action Mutation Where the Acting User Sees Stale Data

Bug 5: updateTag in a Route Handler

Bug 6: Short cacheLife That Silently Affects PPR

Bug 7: Runtime API Inside a Cached Scope

The Common Thread

I built a free debugger because Next.js 16 'use cache' was completely invisible during development

What it catches

How to use it

Honest limitations

At a glance

Get it

Lighthouse Said It Was Fast. My Users Kept Clicking the Same Button.

The bug wasn’t performance. It was silence.

80ms response, zero perceived response

Where most of us focus (and where it falls short)

The 200ms line

What INP actually measures

The fix was not “make it faster”

The pattern you already use

Why this matters more than Lighthouse 100

If you want to go deeper

A quick way to test this

One practical takeaway

Why Most React Infinite Scroll Hooks Fail in Production (and the One That Fixed It for Me)

The Bug That Changed Everything

Where Things Start Falling Apart

What I Actually Needed

What This Hook Handles

Basic Usage

Real Use Case: Reset on Filter Change

Why AbortController Matters So Much

One Honest Note

Try It Yourself

Final Thought

I Turned My Blog Into a Full Developer Platform (Tutorials + Snippets + Quizzes + Tools)

Why I Went Quiet

What I’ve Been Working On

What Changed for Me

I Missed This Community

What You’ll See From Me Now

If You Want to Check What I Built

One Small Thought

Performance First UI Taught Me More Than Any Framework Ever Did

Speed is not what developers think it is

1. `middleware.ts` stopped running and told me nothing

2. `revalidateTag('products')` compiled, deployed, and silently did the wrong thing

3. `next lint` disappeared and my CI kept saying it passed

4. One component was still reading `params` synchronously

Bug 1: `'use cache'` on the Wrapper Instead of Inside the Function

Bug 2: Deprecated `revalidateTag` That Compiles and Uses Legacy Behavior

Bug 5: `updateTag` in a Route Handler

Bug 6: Short `cacheLife` That Silently Affects PPR