u/shubhradev

One of the most confusing bugs I hit in Next.js 16 had nothing to do with fetching or caching logic. It was just the order of two functions.

I had a Server Action updating a product price. The mutation worked, revalidation was happening, everything looked correct.

But the user who clicked save kept seeing the old price.

Everyone else saw the update. Just not them.

The fix ended up being:

updateTag before revalidateTag.

That was it.

Nothing in the errors, nothing in the docs, nothing in the runtime makes this obvious. It just quietly behaves wrong.

I’ve run into a few of these now where everything compiles, deploys fine, and then breaks in subtle ways in production.

I wrote down 7 of the most common ones I’ve hit along with fixes:
(link in comments)

Curious what’s been the most confusing or unexpected part of the new caching model for others?

I had a component that was supposed to be cached with 'use cache'. It was still re-fetching on every single request. No error. No warning. Nothing in the terminal. Just mysteriously slow performance. The problem was placement. 'use cache' was on the wrapper function, not inside the actual data function. One wrong placement and caching silently does nothing. Next.js does not tell you. So I built a small dev-only debugger that makes caching visible in the terminal. What it catches:

• FIRST RUN vs re-execution with the same args (catches the wrong placement problem above)

• Dynamic holes: cacheLife('seconds') silently excludes a function from the PPR static shell

• Missing cacheTag: no tag means no on-demand invalidation, only time-based expiry

• Deprecated revalidateTag: calling it without a second arg is a TypeScript error in Next.js 16

• updateTag outside a Server Action: runtime throw, caught before it happens

• Repeated fetches: same URL hit multiple times in one render What it looks like in the terminal:

  [cache-debug] ▶ FIRST RUN fn: getProductById args: ["prod-123"]

  [cache-debug] ⚠ POSSIBLE CACHE MISS - RE-EXECUTION WITH SAME ARGS fn: getProductById args: ["prod-123"] This function ran 2 times with identical args.

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

One wrapper, zero API change:

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

The exported function works exactly the same everywhere you already call it. Free, zero dependencies, zero production overhead. One .tsx file. Would love to hear from anyone already working with 'use cache' and cacheTag in Next.js 16. What has been the most confusing part of the new caching model for you?

Not the obvious stuff. The things that cost me actual time.

revalidateTag now requires a second argument. revalidateTag('products') is a TypeScript error in 16. It compiles in loose setups and silently falls back to legacy behaviour. You won't notice until pages stop updating after mutations.

updateTag only works in Server Actions. Calling it in a Route Handler throws at runtime. Compiles fine. Deploys fine. Breaks on the first real webhook.

cacheLife('seconds') removes your component from the PPR static shell entirely. Nothing in the terminal tells you. Your page quietly becomes fully dynamic at request time.

middleware.ts is now proxy.ts. The codemod handles the rename but if you have custom header logic and headers stop applying after the upgrade, this is why.

What did I miss? Drop yours below.

Just finished a full rebuild of my personal site using Tailwind v4 and Next.js 16. Been using Tailwind almost every day for over two years so I went pretty deep this time.

What actually surprised me:

The new engine is genuinely faster. Full builds up to 5x, incremental builds feel instant. You actually feel it during development.

Container queries are now built into core with no plugin needed. In v3 you had to add the official plugin. Small thing but it is cleaner.

The class string problem is still very real. Complex components still end up with strings that are painful to read and maintain. I do not think this ever fully goes away.

One thing I am still figuring out: I use `u/apply` heavily for repeated patterns but the Tailwind team now recommends moving away from it toward CSS variables in v4. Have not fully made that switch yet.

I landed on shadcn plus my own component layer. Best balance I have found so far.

Curious how others are handling this in bigger projects. Full inline classes, CSS layers, utility libraries? What actually works at scale.

I just finished rebuilding my entire personal site with Next.js 16.1.1 (App Router + React 19).

Some things that hit differently compared to 15:

- Caching behavior feels even more strict now

- The improvements in partial prerendering and server components are noticeable

- Had to rethink my ISR + on-demand revalidation strategy again

- Debugging Server Actions still takes some patience

Overall I'm really enjoying the direction, but there was definitely a learning curve moving from 15 → 16.

Would love to hear from others who have already upgraded:

- What’s been your biggest win with Next.js 16 so far?

- Any gotchas or best practices you wish you knew earlier?

I wrote a few detailed posts about the migration and architecture decisions if anyone is interested.

I’ve been building with Next.js for a while now, and honestly, the logic side got comfortable pretty fast.

Server components, data fetching, auth flows, all of that started to click after some projects.

But what kept slowing me down was something else.

UI.

Not because I don’t like design, I actually enjoy it a lot.
But trying to turn working features into a clean, consistent layout took way more time than expected.

Spacing, structure, responsive behavior, small inconsistencies, I would end up tweaking things way too much.

Sometimes I’d spend more time adjusting layout than building actual features.

So recently I started doing something different.
Instead of starting UI from scratch every time, I began creating small reusable page structures alongside real features.

Nothing fancy, just patterns that:

• work well with server components and real data
• stay consistent across pages
• don’t break on different screen sizes

It made things feel much faster and less mentally draining.

Curious how others approach this.

Do you:

• build UI systems first
• or just ship features and refine UI later

I don’t know if this is just me, but Tailwind made me both faster and slower at the same time.

Faster because I don’t have to switch files or think about class names.
Slower because I keep obsessing over small things.

Like:

• is this padding 16 or 18
• should this be gap 4 or gap 5
• why does this section feel slightly off
• one breakpoint looks perfect, another feels weird

I actually enjoy designing UI, but I get stuck trying to make everything feel “just right”.

Sometimes even 1px differences start bothering me.

Recently I started trying a different approach.
Instead of tweaking everything per component, I’m building small reusable layout patterns and sticking to them.

It’s less “perfect” in the moment, but way more consistent overall.

Still figuring it out.

Curious how you handle this.

Do you:

• follow a strict spacing system
• or adjust things visually until it feels right

For a long time, I had this pattern.

I could build features like auth, infinite scroll, and data flows without much trouble, but when it came to putting everything together into a clean UI, I would slow down a lot.

Layout, spacing, structure… it always felt harder than it should be.

The weird part is, I actually enjoy design. I just get stuck trying to make everything feel perfect, even small things like 1px margin or padding differences.

So instead of jumping between random UI libraries, I started building my own reusable landing page structures alongside real features.

Nothing fancy, just simple sections that look clean, fit real apps, and don’t break responsiveness.

Over time I realized I care less about “perfect UI” and more about something that works well with real logic like auth, data, and user flows, and something devs can ship fast without overthinking every detail.

Still figuring this out.

Curious how others handle this.

Do you focus more on features first, or design system first?