{"id":1555,"date":"2026-08-19T11:46:54","date_gmt":"2026-08-19T11:46:54","guid":{"rendered":"https:\/\/www.projectimmerse.com\/blog\/?p=1555"},"modified":"2026-08-19T12:18:12","modified_gmt":"2026-08-19T12:18:12","slug":"next-js-confused-me-on-purpose-a-field-guide-to-framework-gotchas","status":"publish","type":"post","link":"https:\/\/www.projectimmerse.com\/blog\/next-js-confused-me-on-purpose-a-field-guide-to-framework-gotchas\/","title":{"rendered":"Next.js Confused Me on Purpose: A Field Guide to Framework Gotchas"},"content":{"rendered":"\n
\"Retro<\/a>
Next.js can feel confusing when framework conventions, prerendering behavior, database quirks, and TypeScript rules aren’t obvious at first.<\/figcaption><\/figure>\n\n\n\n

If you’ve ever built something with Next.js and Postgres, you’ve probably hit a moment where the app does something that looks broken but technically isn’t. Your database ID jumps from 2 to 35 out of nowhere. Next.js throws a scary-looking error about “blocking” your route. Your editor yells at you for naming a file wrong. None of these mean you broke something \u2014 they mean the framework is trying to tell you how it actually works under the hood.<\/p>\n\n\n\n

Here are three of the most common “wait, is this a bug?” moments, explained without the panic.<\/p>\n\n\n\n\n\n\n\n

Why Your Middleware Isn’t Running (Even Though the Code Is “Right”)<\/h2>\n\n\n\n

Here’s a fun one: you write a perfectly valid function that redirects requests, the logic is airtight, TypeScript isn’t complaining \u2014 and Next.js just… never runs it. No error. No warning. It just quietly does nothing.<\/p>\n\n\n

\nexport function proxy(request: NextRequest) {\n  if (request.nextUrl.pathname.startsWith("\/admin")) {\n    return NextResponse.redirect(new URL("\/", request.url));\n  }\n}\n<\/pre><\/div>\n\n\n
This looks like middleware. It smells like middleware. But Next.js won’t touch it, for two very specific, very unforgiving reasons: the file isn’t named middleware.ts<\/code>, and the function isn’t named middleware<\/code>.<\/p>\n\n\n\n
Next.js doesn’t scan your project for “a function that looks like it redirects things.” It looks for one exact convention: a file called middleware.ts<\/code> (or .js<\/code>) at your project root, or inside src\/<\/code>, exporting a function named middleware<\/code>. Call it proxy<\/code>, put it in the wrong folder, or misspell it, and you don’t get an error \u2014 you just get silence, which is arguably worse.<\/p>\n\n\n\n
The fix is boring on purpose:<\/p>\n\n\n
\n\/\/ middleware.ts (project root or src\/)\nimport { NextRequest, NextResponse } from "next\/server";\n\nexport function middleware(request: NextRequest) {\n  if (request.nextUrl.pathname.startsWith("\/admin")) {\n    return NextResponse.redirect(new URL("\/", request.url));\n  }\n}\n\nexport const config = {\n  matcher: "\/((?!api|_next\/static|_next\/image|.*\\\\.png$).*)",\n};\n<\/pre><\/div>\n\n\n
That config.matcher<\/code> is worth a second look too \u2014 it’s a regex telling Next.js which routes should even bother running your middleware. The pattern above says “run on everything except API routes, static assets, optimized images, and PNGs,” which keeps you from redirecting your own favicon by accident.<\/p>\n\n\n\n
The lesson: some frameworks infer intent from your code. Next.js middleware isn’t one of them \u2014 it wants the exact filename and the exact export name, full stop.<\/p>\n\n\n\n
“Blocking RouteServer” \u2014 Why Next.js Is Yelling About Prerendering<\/h2>\n\n\n\n
\"Next.js
Next.js framework gotchas make more sense once you understand the conventions behind middleware, prerendering, database IDs, and TypeScript file extensions.<\/figcaption><\/figure>\n\n\n\n
If you’ve fetched data straight from a database inside a page component, you may have run into this warning:<\/p>\n\n\n\n
\n
Next.js encountered uncached data during prerendering. This prevents the route from being prerendered, blocking navigation and leading to a slower user experience.<\/p>\n<\/blockquote>\n\n\n\n
Translated: Next.js tried to build this page ahead of time (prerendering), but your database call can only happen when a real request comes in. That makes the whole page “block” \u2014 nobody sees anything until the query finishes.<\/p>\n\n\n\n
Next.js gives you three honest options here, not just one “correct” answer:<\/p>\n\n\n\n
1. Stream it with Suspense.<\/strong> Pull the dynamic part into its own component, wrap it in Suspense, and let the rest of the page load instantly while that piece streams in behind a fallback.<\/p>\n\n\n
\nasync function PostsList() {\n  const posts = await prisma.post.findMany();\n  return <ul>{\/* render posts *\/}<\/ul>;\n}\n\nexport default function PostsPage() {\n  return (\n    <div>\n      <h1>Posts<\/h1>\n      <Suspense fallback={<p>Loading...<\/p>}>\n        <PostsList \/>\n      <\/Suspense>\n    <\/div>\n  );\n}\n<\/pre><\/div>\n\n\n
2. Cache it.<\/strong> If the data doesn’t need to be fetched fresh on every request, mark the function with “use cache” so Next.js can treat it like static content.<\/p>\n\n\n\n
3. Just allow the block.<\/strong> Sometimes a page genuinely needs fresh data every time and there’s no useful “shell” to show early. In that case you can tell Next.js you’re doing this on purpose:<\/p>\n\n\n
\nexport const instant = false;\n<\/pre><\/div>\n\n\n
Worth knowing: instant = false<\/code> doesn’t change how your page behaves at all. It doesn’t optimize anything or add caching. It just turns off the warning for that one route, essentially saying “yes, I know, I meant to do that.” It’s an escape hatch, not a fix \u2014 treat it as a temporary pass, not a permanent answer, unless you’re sure that route genuinely needs fresh data on every load.<\/p>\n\n\n\n
.ts vs .tsx: The Extension That Actually Means Something<\/h2>\n\n\n\n
This one trips up a lot of people moving into TypeScript + React, and the rule is simpler than it looks:<\/p>\n\n\n\n
Does the file contain JSX (like <div> or <Button \/>)? Use .tsx. Does it not? Use .ts.<\/strong><\/p>\n\n\n\n
That’s genuinely it. The extension isn’t about what a file “does” conceptually \u2014 it’s a signal to the compiler about how to parse <<\/code> characters. Without .tsx<\/code>, TypeScript can’t tell whether <Post><\/code> is a JSX tag or a generic type comparison, and it’ll throw a fit.<\/p>\n\n\n\n
A quick cheat sheet:<\/p>\n\n\n\n