DEV Community: Kunj Hirapara

Next.js 16, one year on: what broke when I upgraded a real site

Kunj Hirapara — Wed, 28 Oct 2026 10:18:32 +0000

Next.js 16 came out in October 2025. A year later it is the version most new projects start on, and the version a lot of working sites still have not moved to. This site moved this month. It is a real app, not a starter: the App Router, a Postgres database through TypeORM, a credentials-based admin panel, and a Docker image that runs on a small VPS.

The official upgrade guide is good and the codemod does most of the typing. What the guide cannot tell you is which of its changes will hit your particular stack. Two problems broke this site's production build in ways a dev server never showed. This is what broke, why, and what I would check before you upgrade yours.

Turbopack builds your app differently

The headline change is that next build uses Turbopack by default. Development already did; now production does too. For most code that is invisible. For code that relies on two routes sharing the same instance of a module, it is not.

After the upgrade, the production build served every public page fine, and admin sign-in failed with this:

No metadata for "Admin" was found

The cause is how the database connection and the bundles meet. The TypeORM DataSource is created once and shared through globalThis, so whichever route connects first registers its entity classes. Turbopack gives each route its own copy of those classes. In production the first request is usually a public page, so the connection held the public page's Admin class, and the auth route asked for a repository with its own, different Admin class. TypeORM compares classes by identity, so as far as it was concerned that entity had never been registered.

webpack, the builder Next.js 15 used for production, shared one module instance across routes, which is why the same code had worked for months.

The fix is one line per lookup: ask for the repository by name instead of by class.

// Breaks when the route that connected first holds a different copy of the class
const admins = ds.getRepository(Admin);

// Works from any route: TypeORM matches the entity by its name
const admins = ds.getRepository<Admin>('Admin');

The public loaders had already been switched to name lookups months earlier, after the same error showed up in development. The auth route was the one place still passing a class, and nothing exercised it until the production build did.

The lesson is broader than TypeORM. If anything in your app keeps state in a module-level singleton and compares classes or object identity across routes, test it on the production build. next dev will not show you this.

The Docker image lost its database driver

This one was not strictly Next.js. It came from upgrading TypeORM to 1.x in the same round, and it only surfaced because of how Next.js packages a standalone build. The two together are worth knowing about.

The site ships as output: 'standalone'. Next.js traces which files the server actually imports and copies only those into .next/standalone, which keeps the Docker image small. TypeORM 1.x loads its database driver with a dynamic require(name). Output tracing cannot follow a require whose argument is a variable, so the trace quietly left pg out. Every page that touched the database threw DriverPackageNotInstalledError.

The fix is to import the driver yourself and hand it over, which puts it back in the trace:

import pg from 'pg';

new DataSource({
  type: 'postgres',
  driver: pg,
  // ...
});

It never reached visitors, because CI builds the Docker image and runs a smoke test against it before anything deploys. It had already earned its place once, after an earlier standalone surprise: images uploaded at runtime into public/ were not served, and the test grew a check for that too. If your deploy is a standalone build and your CI does not boot it, I would add that before upgrading anything.

Middleware is now called proxy

middleware.ts is deprecated in favour of proxy.ts, and the exported function is renamed to match. The codemod does the rename. One difference matters if you relied on the Edge runtime: proxy always runs on Node.js, and the guide says to keep middleware for now if you need Edge. The behaviour this site relies on, guarding /admin before a request reaches the page, works the same.

The name is more honest about what the file does: it sits in front of your routes and decides what to do with a request.

I still check the session again inside every admin page and server action. A guard in front of the routes is a convenience, not the only lock on the door.

next lint is gone

next lint was removed. You run the ESLint CLI directly, with a flat config. The codemod writes one for you; this site's is core web vitals, TypeScript and Prettier in eslint.config.mjs, and npm run lint calls ESLint itself.

The practical difference is that ESLint now lints whatever its config says, not what Next.js decided to point it at. The first run after the switch walked into tool folders that had never been linted before, and they needed adding to the ignores.

The small breaking changes

Most of the remaining changes are mechanical, and the codemod handles them:

params, searchParams, cookies() and headers() are async. Await them.
revalidateTag takes a second argument, a cache profile such as 'max'. The single-argument form is deprecated and fails type checking.
The minimum Node.js is 20.9, and the supported browsers start at Safari 16.4 and Chrome 111.
If you have a custom webpack config, next build fails on purpose rather than silently ignoring it. You either migrate it or build with --webpack.

None of these are hard. They are just noisy, which is a good reason to land the upgrade on its own and not inside a feature branch.

The React Compiler is stable, and still a choice

Next.js 16 made built-in support for the React Compiler stable, after the compiler's own 1.0 release. It memoizes components for you, so most hand-written useMemo and useCallback calls become unnecessary.

It is off on this site for now. If you turn it on, two things are worth knowing first. The upgrade guide warns that builds and dev compiles get slower, because the compiler runs through Babel. And eslint-plugin-react-hooks 7 ships rules that only make sense with the compiler on; this site has those three switched off, to be switched back on the day the compiler is.

What I would check before you upgrade

If you are still on Next.js 15, this is the short list I would work through:

Test the production build, not dev. Run next build and next start, then click through the parts of the app that only some users reach: sign-in, admin, webhooks, anything behind auth.
Look for shared singletons. Database connections, caches and clients stored on globalThis are fine. Comparing classes across routes is not.
Boot the standalone output in CI. If you deploy .next/standalone, start it and hit a few routes before you deploy. Dynamic requires are where tracing loses files.
Upgrade one thing at a time. The driver problem came from TypeORM, not Next.js, and it was easy to pin down only because the dependency bumps were separate commits.
Run the codemod, then read its diff. It renames and rewrites correctly. It cannot know which of your routes depend on what it changed.

A year on, Next.js 16 is a better default than 15: faster builds, clearer names, and a cache API that says what it does. The upgrade itself is mostly typing. The work is in the few places where your app depended on how the old builder happened to behave, and the production build is the only place that will show you where those are.

This post first appeared on my site, kunjdeveloper.com, where I write about building and running full-stack web apps.

My portfolio was blank on every iPhone and BrowserStack said it was fine

Kunj Hirapara — Wed, 28 Oct 2026 10:17:15 +0000

I told my friends I'd finally pushed my portfolio live. One of them pulled it up on his phone right there on the bench.

The header loaded. The grid behind the hero loaded. Then nothing. A big empty screen where the rest of my site was supposed to be.

I got roasted. On a roadside bench, for a site I had announced moments earlier. It was funny. It was significantly funnier for them.

The phone was an iPhone 13 Pro Max on the latest iOS, and I'm putting that up front because it kills the excuse I would otherwise have reached for. This was not a five-year-old budget phone dying on 2G. It was a flagship, on mobile data, and my site did not render.

Blaming Safari, then running out of things to blame

First instinct: Safari. Blaming Safari is free and usually at least partly correct.

So he opened it in Chrome. Same shit.

That was the clue, and I completely missed it. Every browser on iOS is Safari wearing a different hat. Same WebKit engine underneath, whatever the icon says. "Try it in Chrome" isn't a second test on an iPhone, it's the first test again.

Then another friend opened it on his Samsung. Perfect. Smooth, exactly like my laptop.

Every iPhone broken. Every Android fine. My machine fine. Cool. Love that for me.

A week of not being able to reproduce it

This was the genuinely miserable part.

I threw it at BrowserStack. BrowserStack told me the site was fine. Every iOS version I tried, fine, fine, fine.

Then I borrowed my sister's phone. Broken. My cousins' phones. Broken. Every real iPhone I could physically get my hands on failed the same way, while the one service whose entire job is reproducing this stuff kept insisting I was imagining it.

I still don't have a clean explanation for that gap. My best guess is that a fresh remote device on a fast connection never sits in the broken state long enough for you to catch it. Whatever the reason, the lesson stuck: when every real phone you can find disagrees with your testing service, believe the phones.

So I did it the stupid way. Deploy, check on my sister's phone, change something, deploy again. For about a week.

The thing that actually cracked it

The next day I downloaded one of those apps that gives you a console on your phone. I genuinely don't remember which one, it was whatever came up first.

Then it took about ten seconds.

The content was there. All of it. Every paragraph sitting in the DOM at opacity: 0, waiting for JavaScript to turn up and give it permission to exist.

Nothing had failed to load. Nothing had crashed. My site had rendered perfectly and then hidden itself from everybody.

Two things I had done to myself

I wrote both of these on purpose, thinking I was being clever.

The first was the scroll reveal wrapped around every section:

<motion.div
  initial="hidden"
  whileInView="show"
  variants={{ hidden: { opacity: 0, y: 24 }, show: { opacity: 1, y: 0 } }}
>
  {children}
</motion.div>

initial="hidden" is the killer. It bakes opacity: 0 straight into the server-rendered markup. The element doesn't come back until the bundle has downloaded, parsed, hydrated and hooked up an IntersectionObserver, and every single link in that chain is something that can be slow.

The second one was dumber. My hero entrance was a GSAP timeline, and to stop everything flashing in its final position before GSAP grabbed it, I'd written the obvious guard:

.hero-reveal { opacity: 0; }

GSAP cleared that on load. So if GSAP didn't run, nothing cleared it, and the hero stayed invisible. Permanently. There's no route back from that state. I had written a line of CSS whose only job was to hide my own content, and then trusted a third-party library to undo it.

Which explains exactly what my friend saw on that bench. The header and the hero grid were plain HTML and plain CSS, so they painted. Everything else in the page was sitting behind a script that hadn't arrived yet.

I'd built a site where the decorative background was more reliable than the writing.

Why iOS specifically

Honestly, none of this is iOS-specific, and that's the part worth taking away. Any browser anywhere will show you a blank page if the content is gated behind a script that hasn't run. The only variable is how long the gap lasts.

On my laptop that gap was short enough that I never once saw it while building the entire site. On that iPhone it was long enough to look like a broken website, and occasionally long enough that people gave up and started roasting me instead.

The fix that wasn't

My first attempt was prefers-reduced-motion: reduce, wired up through JavaScript. Reasonable idea: if someone doesn't want motion, skip the animation and show everything.

It didn't help at all. The JavaScript still had to load before anything could decide anything, so you got the same blank wait, and then the entire page appeared at once in a single ugly slab.

I hadn't fixed the problem. I'd moved it. Same gate, different key.

Fixing the hero: no JavaScript at all

The hero entrance is a staggered fade and rise. There was never a reason for that to be JavaScript. CSS has done this natively for years, so I deleted the timeline, deleted the guard, and wrote it properly:

@keyframes hero-fade-up {
  from { opacity: 0; transform: translateY(18px); }
  to   { opacity: 1; transform: translateY(0); }
}

@media (prefers-reduced-motion: no-preference) {
  .hero-badge,
  .hero-sub,
  .hero-cta,
  .hero-terminal {
    animation: hero-fade-up 0.6s cubic-bezier(0.22, 1, 0.36, 1) both;
  }

  .hero-badge    { animation-delay: 50ms; }
  .hero-terminal { animation-delay: 400ms; }
  .hero-sub      { animation-delay: 500ms; }
}

Two things in there matter more than they look.

both as the fill mode. Without it you can't stagger with delays, because each element sits at its natural opacity until its delay runs out and then snaps into place. both tells the browser to apply the from state during the delay and hold the to state afterwards. The useful side effect is that the hidden state now lives inside the animation instead of in a rule of its own. Take the animation away and the element is just visible.

Then the no-preference wrapper, which is the direct fix for my failed attempt. Instead of animating by default and switching it off under reduce, the animation only exists inside no-preference. The plain stylesheet now describes a page that's already finished and static, and motion is the thing being added on top. Reduced motion stopped being something JavaScript had to decide and became the default I opt out of.

Visually it's the same entrance. Same easing, same delays. It just happens at first paint now, before the browser has even asked for the JavaScript.

Scroll reveals, which do need JavaScript

These actually depend on scroll position, so I couldn't just delete the JS. What I could change was which direction the logic ran. Instead of rendering hidden and letting JavaScript release it, render visible and let JavaScript arm it.

export function useInViewReveal(once = true) {
  const ref = useRef<HTMLDivElement>(null);
  const inView = useInView(ref, { once, margin: '-80px' });
  const [hydrated, setHydrated] = useState(false);

  useEffect(() => setHydrated(true), []);

  const animate: 'show' | 'hidden' = !hydrated || inView ? 'show' : 'hidden';
  return { ref, animate };
}

The hydrated flag is the whole trick. On the server it's false, so animate is 'show', so the markup that ships is visible. Pair it with initial={false} and Framer stops writing an initial state of its own:

<motion.div ref={ref} initial={false} animate={animate} variants={variants}>
  {children}
</motion.div>

There's now no moment where JavaScript hasn't run and the content is hidden, because "JavaScript hasn't run" and "visible" are the same state.

Once it hydrates, anything already on screen stays put, so nothing flashes and nothing re-animates a paragraph you're halfway through reading. Anything off screen drops to hidden and reveals on scroll like before. On a decent connection you cannot tell that any of this changed.

One thing I got wrong on the first pass: I'd made the staggering container a motion element too, with its own hidden variant. Doesn't matter how careful the children are if the parent can still hide them. RevealGroup is a plain div now that hands each child an incremental delay and has no opinion about visibility.

What else went, once I started looking

Lenis is lazy-loaded and skipped completely on touch devices. Native iOS scrolling beats anything I'd bolt on top, and not running a permanent requestAnimationFrame loop during hydration helps exactly the phones that need help.
The stacked project cards went back to position: sticky and became a server component. One less scroll library, and under reduced motion it collapses to a normal vertical stack for free.
The timeline progress rail is a small throttled scroll handler instead of a plugin.
The skills marquee waits for idle before mounting rather than shipping dozens of inline SVG paths in the initial HTML. Its height is reserved in CSS so nothing jumps when it arrives.
overflow-x: clip on body went back to hidden. clip is the better property and I'd rather use it, but Safari didn't ship it until 16, and an overflow value an older iPhone doesn't understand is not a bug you find quickly.

"Modern CSS" and "CSS that works on the phone your friend is holding" are not the same list.

How to catch this without the bench

None of it is hard to find once you know to look. It's just completely invisible from where I was standing.

The check that would have saved me a week: turn JavaScript off and reload. DevTools, command palette, Disable JavaScript. If the page still reads top to bottom you're fine. If it's blank, congratulations, you have my bug. Four seconds.

Then throttle properly, and watch the first two seconds rather than the finished state. The finished state always looks great. That's exactly why nobody catches this.

Read the SSR HTML instead of the DOM, too. The inspector shows you the page after hydration, which is precisely the version that's lying to you. curl the URL and grep it for opacity:0. Anything sitting on real content is a problem waiting for a worse connection.

And test on a real phone. Not a simulator, not a remote device farm that will cheerfully tell you everything is fine. A real one, in your hand, on cellular.

Where it actually stands

I'm not going to pretend this ended with a perfect Lighthouse score and a lesson learned. It's still not as fast as I want. The entrance is all hand-written CSS now with no motion library involved at all, and I'm still going back and forth on whether to do reduced motion through a proper hook instead of by hand.

But it renders. Immediately, on every phone I can get hold of, whether or not the JavaScript ever turns up. That's a low bar, and I had somehow built a site that couldn't clear it.

The thing had been live and broken for about a week before that bench. I have no idea who else opened it in that window. Probably nobody. I've decided to believe it was nobody.

This post first appeared on my site, kunjdeveloper.com, where I write about building and running full-stack web apps.