Coder Legion - Recent posts tagged nextjs

Your Next.js redirect() Silently Does Nothing Because It's Inside a try/catch

Fri, 30 Oct 2026 10:08:42 +0000

A user fills in your form and clicks "Create post". The post is saved in the database. And the page shows "Could not create post".

They try again. Now there are two posts.

Nothing is wrong with your database. Your error handling caught something it was never supposed to catch.

The Code That Causes It

// app/actions.ts
'use server';

import { redirect } from 'next/navigation';

export async function createPost(formData: FormData) {
  try {
    const post = await db.post.create({
      data: { title: String(formData.get('title')) },
    });

    redirect(`/posts/${post.id}`);
  } catch (err) {
    return { error: 'Could not create post' };
  }
}

It reads perfectly. Save the post, go to its page, and if anything fails, return an error. A tidy, defensive pattern that you have probably written a hundred times in other frameworks.

Why It Breaks

In Next.js, redirect() does not return. It throws a special error, and the framework catches that error higher up and turns it into a redirect response.

That means your catch block receives it first. Your code swallows the redirect, returns { error: ... }, and the framework never sees it.

The same is true for notFound(), which also works by throwing. Both are written to stop execution immediately, which is why TypeScript treats them as functions that never return.

Why It Is Hard to Catch

The data is saved. The only visible symptom is a wrong error message, so it looks like a UI bug, not a logic bug.
It is inconsistent in your head. The same redirect() works fine outside a try, so you assume it is fine everywhere.
Your logs are confusing. If you log the caught error, you will see a strange error with a NEXT_REDIRECT digest and think something crashed.
It tempts you to retry. Users see an error, submit again and create duplicates.

Fix 1: Keep redirect() Outside the try Block

Only wrap the code that can genuinely fail, and redirect afterwards:

export async function createPost(formData: FormData) {
  let postId: string;

  try {
    const post = await db.post.create({
      data: { title: String(formData.get('title')) },
    });
    postId = post.id;
  } catch (err) {
    return { error: 'Could not create post' };
  }

  redirect(`/posts/${postId}`);
}

The try now covers only the database call. If it fails, you return the error. If it succeeds, execution continues to redirect(), which is outside any catch, so it can do its job.

This is the cleanest option, and it is the one I use by default.

Fix 2: Rethrow If You Must Catch Everything

Sometimes the redirect() sits deep inside a helper, and restructuring is awkward. Then let the framework's own errors pass through your catch. Newer Next.js versions provide a helper for exactly this:

import { redirect, unstable_rethrow } from 'next/navigation';

try {
  // ...work that may call redirect() or notFound() somewhere inside
} catch (err) {
  unstable_rethrow(err); // lets redirect/notFound errors continue upward
  return { error: 'Something went wrong' };
}

The name says it is not final, so check the documentation for the version you use. If it is not available in yours, structure your code as in Fix 1.

Fix 3: Do Not Use Catch-All to Control Flow

A broader habit helps here. A catch (err) with no check is a very wide net. Catch what you expect:

catch (err) {
  if (err instanceof DuplicateTitleError) {
    return { error: 'You already have a post with that title' };
  }
  throw err; // anything else is not yours to handle here
}

Rethrowing what you do not recognize means the framework's own signals, real crashes and bugs all reach the place that is meant to handle them.

Where Else This Bites

notFound() inside try. A missing record becomes your generic error instead of a 404 page.
Route handlers and Server Components. The same rule applies: any try/catch around a call that can redirect or 404 will swallow it.
.catch() on a promise. somePromise.catch(() => null) has the same effect if the promise's code calls redirect().
Wrapper functions. A helper like withErrorHandling(fn) that catches everything will break redirects in every function it wraps.

Quick Checklist

Situation	What to do
`redirect()` after a database write	Put the write in `try`, `redirect()` after it
`notFound()` when a record is missing	Call it outside the `try`, or rethrow
A shared error-handling wrapper	Make it rethrow framework errors
Unsure	Catch specific error types, rethrow the rest

The Rule

redirect() and notFound() signal by throwing, so a catch around them will eat the signal. Keep them outside try blocks, or rethrow what you do not recognize.

Quick audit: search your project for redirect( and notFound(. For each hit, look upward. If it sits inside a try, you have either a bug now or one waiting for the day the code path is used.

If you want a Next.js starting point where forms and actions are set up sensibly from day one, you can browse my templates on pixelanas.com.

Get the templates: https://pixelanas.gumroad.com

Have you ever shipped a form that showed an error after it had succeeded? Tell me in the comments how long it took you to find it.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

You Deleted the .env File From Git. Your Secrets Are Still Public.

Wed, 28 Oct 2026 08:06:21 +0000

You notice it during a code review: .env is in the repository. Your stomach drops. You run git rm .env, commit with the message "remove env file", push, and feel the relief of a problem solved.

It is not solved. The file is gone from your latest commit. It is sitting, in full, in every commit before that one, and anyone who can read the repository can read it.

Why Deleting Doesn't Delete

Git is a history book. A new commit adds a page saying "the file no longer exists". It does not tear out the old pages.

git log --all --full-history -- .env

If that prints any commits, your file is in history. And anyone can go back to it:

git show <old-commit>:.env

That works for a public repository on GitHub, for a coworker's clone, for a fork, and for any tool that scans old commits. Automated bots scan public repositories for exactly this, so a leaked key can be found quickly.

Step 1: Rotate Everything First

This is the part people skip, and it is the only part that actually matters.

Treat every secret that was ever in that file as compromised, and replace it:

Database passwords and connection strings
API keys (payment, email, storage, maps, AI)
Auth secrets such as NEXTAUTH_SECRET or JWT signing keys
OAuth client secrets
Webhook signing secrets

Create the new value, update your hosting environment, deploy, and then revoke the old one. Cleaning the history comes after, because cleaning cannot take back what someone already copied.

Rotating a signing secret logs users out, which is the right outcome. It means the old secret can no longer be used to forge sessions.

Step 2: Find Out What Else Was Committed

.env is not the only way secrets end up in Git. Search the whole history for the values themselves:

git log -p --all -S'sk_live' | head -100

-S finds commits where a string was added or removed. Try the prefixes of keys you use. A dedicated scanner is faster and more thorough:

gitleaks detect --source . --log-opts="--all"

It checks every commit for patterns that look like keys and tokens, and prints where it found them.

Step 3: Remove It From History

Once the secrets are rotated, you can clean the history so the old file stops being a trap. The current recommended tool is git filter-repo:

git filter-repo --path .env --invert-paths

This rewrites every commit as if .env had never been added. Because it changes commit IDs, you then force push:

git push --force --all

Be honest about the limits:

Everyone else must re-clone or reset, or they will push the old history back.
Forks and existing clones keep the old data. You cannot reach into them.
Hosting platforms may keep cached copies of old commits for a while. Check their guidance on removing sensitive data.

This is why step 1 comes first. History rewriting is cleanup, and rotation is the fix.

The Leak That Has Nothing to Do With Git

Next.js developers have a second way to leak a secret, and no commit is involved:

# .env.local
NEXT_PUBLIC_STRIPE_SECRET_KEY=sk_live_...

Any variable that starts with NEXT_PUBLIC_ is inlined into the JavaScript sent to the browser at build time. Anyone can open DevTools, read your bundle and find the value. The prefix means "this is safe to publish", and it does exactly that.

Rules that keep you safe:

Only values that are meant to be public get the NEXT_PUBLIC_ prefix, such as a public analytics ID or a publishable key.
Secret keys have no prefix and are read only in Server Components, Route Handlers and Server Actions.
If a secret ever got that prefix, assume it is exposed and rotate it.

Make It Hard to Repeat

Ignore the file before the first commit.

.env
.env.*
!.env.example

Commit a .env.example with the variable names and fake values, so teammates know what to set, and nothing real is ever in the repository.

Scan before commits leave your machine. A pre-commit hook with a scanner like gitleaks blocks a commit that contains something key-shaped. Hosting your code on GitHub also gives you secret scanning and push protection for many known key formats. Turn both on.

Fail loudly when a variable is missing. Check required variables at startup, so a missing secret becomes an error message, not a silent fallback to a hardcoded value that someone then commits.

The Rule

Once a secret has been in a commit, it is public forever. The fix is rotation, not deletion. Rotate first, clean the history second, and add a scanner so the next mistake is caught before it leaves your laptop.

Quick audit, right now, in your own project:

git log --all --full-history -- .env .env.local .env.production

If that prints anything, you have found a rotation task.

If you are starting a new Next.js project and want the structure set up sensibly from day one, you can browse my templates on pixelanas.com.

Get the templates: https://pixelanas.gumroad.com

Have you ever committed a secret by accident, and how fast did you notice? Tell me in the comments, and no judgment, this happens to nearly everyone once.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

You Upgraded to Next.js 15 and Your Site Got Slower. The Caching Defaults Flipped

Tue, 27 Oct 2026 16:13:23 +0000

You upgrade from Next.js 14 to 15. The app compiles, the tests pass, nothing visibly breaks. A week later your database bill is higher, your pages feel slower, and your Time to First Byte graph has a step in it that lines up exactly with the deploy.

Nothing is broken. Something that used to happen for free stopped happening.

What Changed

In Next.js 14, data fetching was cached by default. A fetch in a Server Component ran once, the result was stored, and later requests reused it. You had to opt out of caching.

In Next.js 15, the default flipped. Per the upgrade notes:

fetch requests are no longer cached by default.
GET route handlers are no longer cached by default.
The client-side router cache no longer holds page segments between navigations by default.

So code you wrote once and never touched now behaves differently:

// app/products/page.tsx
export default async function ProductsPage() {
  const res = await fetch('https://api.example.com/products');
  const products = await res.json();
  return <ProductList products={products} />;
}

On 14, this fetched the data once and served the page from cache. On 15, every visitor triggers the API call, and because the page now depends on data fetched at request time, the route is rendered dynamically.

Why It Is Easy to Miss

Nothing errors. The code is valid. It just does more work.
Dev mode hides it. In next dev, nearly everything is rendered per request anyway.
The slowdown is gradual. With low traffic, an extra API call per request is invisible. It shows up when the traffic does.
Third-party limits bite later. If the API you call has rate limits or per-request billing, you find out from the invoice.

How to See It in 30 Seconds

Run a production build and read the route table at the end:

next build

Route (app)
┌ ○ /                 (Static)
├ ƒ /products         (Dynamic)
└ ƒ /blog/[slug]      (Dynamic)

○ means the page is pre-rendered once at build time. ƒ means it runs on the server for every request. A page that used to be static and is now ƒ is exactly what this upgrade can cause. Compare the table before and after the upgrade.

Fix 1: Cache One Request on Purpose

const res = await fetch('https://api.example.com/products', {
  cache: 'force-cache',
});

This restores the old behavior for that single request. Use it for data that does not change per user and rarely changes at all.

Fix 2: Cache With an Expiry

Most data is not permanent, just slow-changing. Revalidate it on a timer:

const res = await fetch('https://api.example.com/products', {
  next: { revalidate: 3600 }, // seconds
});

Visitors get the cached copy, and after an hour the next request refreshes it in the background. This is the right default for product lists, blog posts and prices.

Fix 3: Set It Once for the Whole Page

If several fetches on a page should share the same freshness, declare it at the route level:

// app/products/page.tsx
export const revalidate = 3600;

Everything that page renders is treated as cacheable for an hour, without repeating options on each call.

Fix 4: Route Handlers Need Their Own Opt-In

A GET route handler that returns the same data for everyone used to be cached automatically. Now you must say so:

// app/api/products/route.ts
export const dynamic = 'force-static';

export async function GET() {
  const products = await getProducts();
  return Response.json(products);
}

Without that line, the handler runs on every request.

The Part People Forget: Your Database Was Never Covered

Here is the subtle thing. The fetch cache only ever applied to fetch. If you read from MongoDB or Postgres directly with an ORM, this change did not touch those calls. Depending on whether the page used request data such as cookies, it was either rendered once at build time with the data frozen in, or rendered on every request. Neither is controlled by the fetch cache, so check your build table for those pages too.

To cache a database call at runtime, wrap it:

import { unstable_cache } from 'next/cache';

const getProducts = unstable_cache(
  async () => Product.find().lean(),
  ['products'],
  { revalidate: 3600, tags: ['products'] }
);

The tags option lets you clear that cache on demand with revalidateTag('products') after an edit. I wrote about why revalidateTag appears to do nothing when the data is not tagged in the first place. Newer Next.js versions keep moving toward explicit opt-in caching, so check the docs for the version you are on before copying any of this.

Should You Cache Everything Again?

No. The new default exists because stale data surprised people. Show a user their own cart, balance or notifications from a shared cache and you have a bug, or a data leak.

Data	Choice
Public, rarely changes (marketing pages, docs)	Cache it, long expiry
Public, changes often (product list, prices)	Cache with a short `revalidate`
Per-user (dashboard, cart, account)	Do not cache
Admin views	Do not cache

The Rule

When a framework changes a default, your old code changes behavior without a single line changing. After any major upgrade, run next build before and after and compare which routes are static (○) and which are dynamic (ƒ). Then opt back in on purpose, for the data that deserves it.

Slow server responses hurt the metrics Google measures. I break those down in plain language in my guide to Core Web Vitals, and if you want a Next.js starting point, you can browse my templates on pixelanas.com.

Get the templates: https://pixelanas.gumroad.com

Did a framework upgrade ever quietly change your app's behavior? Tell me what it was in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

"'use client' Doesn't Turn Your Whole App Into a Client Component (The Children Trick Nobody Explain

Sat, 24 Oct 2026 11:28:48 +0000

You need a theme provider, so you create a file, add 'use client' at the top, and wrap your app in it.

Then a nagging thought arrives: "I just wrapped my entire layout in a client component. Did I turn the whole app into client-side React?"

Most developers either panic and avoid providers, or give up and put 'use client' at the top of every file "just to be safe". Both are the wrong response, and the actual rule is simpler than you expect.

The Setup

// components/ThemeProvider.tsx
'use client';

import { createContext, useState } from 'react';

export const ThemeContext = createContext('light');

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme] = useState('light');
  return <ThemeContext value={theme}>{children}</ThemeContext>;
}

// app/layout.tsx  (a Server Component)
import { ThemeProvider } from '@/components/ThemeProvider';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

ThemeProvider is a Client Component. It wraps every page. So are all the pages client components now?

No.

What 'use client' Actually Does

'use client' marks a boundary. It says: "this file, and everything this file imports, is part of the JavaScript sent to the browser."

The key word is imports. The boundary follows the import graph, not the position in the rendered tree.

In the layout above, children is not imported by ThemeProvider. It is passed in as a prop by the layout, which is a Server Component. The server renders the page first, and hands the finished result to the client component as a slot to fill.

So your pages stay Server Components. They can still fetch data on the server, use secrets, and ship no JavaScript for their static parts.

The Mistake That Does Change Things

Now look at this version:

// components/ThemeProvider.tsx
'use client';

import { Dashboard } from './Dashboard'; // imported, not passed in

export function ThemeProvider() {
  // ...
  return <Dashboard />;
}

Here the client file imports Dashboard, so Dashboard joins the client bundle, along with everything it imports. If it was a Server Component that queried your database, it is no longer one. It will either break the build or quietly ship heavy code to every visitor.

The difference between the two examples is a single word: import versus prop.

The Pattern: Pass Server Components Through as Children

Any time a client component needs to wrap server content, use a slot:

// components/Modal.tsx
'use client';

import { useState } from 'react';

export function Modal({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = useState(false);
  return (
    <>
      <button onClick={() => setOpen(true)}>Show stats</button>
      {open && <div role="dialog">{children}</div>}
    </>
  );
}

// app/page.tsx  (Server Component)
import { Modal } from '@/components/Modal';
import { Stats } from '@/components/Stats'; // reads the database

export default function Page() {
  return (
    <Modal>
      <Stats />
    </Modal>
  );
}

Stats runs on the server, even though it is rendered inside a client component's JSX. The button and the toggle are interactive in the browser. The data never leaves the server except as finished markup.

This works for any prop that holds JSX, not only children. A sidebar prop or a header prop behaves the same way.

Rule of Thumb: Push the Boundary Down

Put 'use client' on the smallest piece that needs interactivity, not on the page:

// Bad: the whole page becomes client code
'use client';
export default function ProductPage() { /* ...200 lines... */ }

// Better: only the button is client code
export default function ProductPage() {
  return (
    <main>
      <ProductDetails />   {/* server */}
      <AddToCartButton />  {/* 'use client' lives here */}
    </main>
  );
}

A page that is mostly text and images, with one button, should send JavaScript for the button, not for the page. Less JavaScript sent means a faster load, which is what I walk through in this plain-language guide to Core Web Vitals.

Two Things That Still Bite

1. Props crossing the boundary must be serializable. Data goes from server to client as text, so you can pass strings, numbers, plain objects, arrays and dates. You cannot pass a regular function. (Server Actions are the exception, because they are designed to cross.)

// Error: functions cannot be passed to Client Components
<ClientButton onClick={() => console.log('hi')} />

Define the handler inside the client component instead.

2. A server-only module can leak into the client by import. If a client file imports a helper that touches your database or secrets, the build either fails or bundles code you never meant to ship. The server-only package turns that into a loud build error:

// lib/db.ts
import 'server-only';

Import this file from a client component and the build fails, instead of shipping the connection code.

The Rule

'use client' marks an import boundary, not a rendering zone. Whatever a client file imports goes to the browser. Whatever you pass to it as props or children can stay on the server. Keep the directive on small interactive leaves, and use the children slot for everything else.

Quick audit: search your project for 'use client' and look at each file. If it is a page or a layout, ask whether it really needs state or browser APIs. If it is a wrapper, check that it receives its content as children and does not import it.

If you want a Next.js starting point built around the App Router, you can browse my templates on pixelanas.com.

Get the templates: https://pixelanas.gumroad.com

Where in your project is 'use client' doing more than it needs to? Drop it in the comments, and tell me if the children trick surprised you.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

How to Protect a Next.js App with a WAF Before You Change DNS

Fri, 23 Oct 2026 04:02:28 +0000

A Next.js app is still a web application that speaks HTTP. That is the only placement fact you need before you look for a framework plugin. The SafeLine documents used here do not describe a Next.js SDK, App Router hook, or hosting-platform add-on. Treat protection as a reverse-proxy decision, then walk a checklist before you move DNS.

SafeLine is a self-hosted web application firewall. Its documentation says it filters and monitors HTTP traffic between a web application and the Internet, and that it works as a reverse proxy so clients reach the WAF before they reach the origin server (https://docs.waf.chaitin.com/en/home). The application guide says SafeLine is developed based on nginx, receives traffic for the original website, cleans malicious attack traffic, and forwards safe traffic to the upstream application (https://docs.waf.chaitin.com/en/GetStarted/AddApplication). For a Next.js deployment, the upstream is the address that actually serves the app, such as a Node process, a container, or another proxy you already operate. Do not add an undocumented Next.js middleware path and treat that path as the firewall.

Placement checklist

Start with exposure. If users already reach the app by a domain over HTTP or HTTPS, you can put SafeLine on that path. In the Web Admin Console, open Applications, choose Add Application, and enter Domain, Port, and Upstream. Domain can be a domain name, hostname, or IP address. Port is the port SafeLine listens on, such as 80 or 443, and HTTPS apps should use the SSL option. Upstream is the real address SafeLine will forward to (https://docs.waf.chaitin.com/en/GetStarted/AddApplication). After those fields are saved, resolve the domain to the IP address of the server where SafeLine runs. Until that DNS change is correct, and until you have written down the previous origin address for rollback, the checklist is unfinished.

Confirm the host can run the proxy. The install guide requires Linux, x86_64 or arm64, Docker 20.10.14 or above, Docker Compose 2.0.0 or above, and at least 1 CPU core, 1 GB memory, and 5 GB disk. The CPU must support ssse3 (https://docs.waf.chaitin.com/en/GetStarted/Deploy). On ARM, the same guide says SafeLine requires a Pro license to work properly and that the Personal Edition is not supported. If the machine in front of Next.js is ARM and you expected the Personal Edition to run there, stop and choose another architecture or a licensed Pro install. The guide also says the LTS line will no longer be maintained starting from 9.1.0-LTS (14 August 2025), and it recommends the latest version if you have concerns about staying on that line.

Choose controls from the documented list only. The product page lists defenses for web attacks, proactive bot abused defense, HTML and JS code encryption, IP-based rate limiting, and a web access control list (https://docs.waf.chaitin.com/en/home). Named coverage includes SQL injection, XSS, code injection, os command injection, CRLF injection, ldap injection, xpath injection, RCE, XXE, SSRF, path traversal, backdoor, bruteforce, http-flood, and bot abused. Rate limiting throttles traffic that exceeds defined limits, including DoS attacks, bruteforce attempts, traffic surges, and other abuse. A CAPTCHA challenge is described as allowing human users through while blocking crawlers and bots. An authentication challenge, when turned on, requires visitors to enter the password or be blocked. Dynamic protection, when turned on, dynamically encrypts HTML and JS code on each visit.

Those controls are relevant because a Next.js app still emits HTML and JavaScript and still accepts HTTP requests on pages, route handlers, and other endpoints. They do not replace validation, authorization, or secret handling in application code. Nothing in these sources says dynamic encryption understands a particular Next.js rendering mode, or that it replaces a policy you set in the app. There is also no documented promise that a strict policy will ignore harmless JSON, file uploads, or query strings that your routes legitimately use. That is why the checklist includes a real-user retest, not only attack samples.

As of September 30, 2026, SafeLine surpassed 700,000 installations worldwide. SafeLine Pro annual promotional pricing is $650-$880 versus the $1,000 regular price. The documentation also calls the product production-ready, protecting over 1,000,000 websites and handling over 30,000,000,000 HTTP requests daily (https://docs.waf.chaitin.com/en/home). Read those scale statements as product context, not as a forecast for your own site. The same page reports an effect evaluation on 33669 samples: SafeLine, Balance showed 71.65% detection, 0.07% false positives, and 99.45% accuracy, while SafeLine, Strict showed 76.17% detection, 0.22% false positives, and 99.38% accuracy. Match the stricter profile to a site that can tolerate more false positives, and retest real Next.js routes before you leave it on.

Verification checklist

After the application is proxied, use the test cases in the application guide and replace the sample domain with yours. The guide lists SQL injection, XSS, path traversal, code injection, and XXE-style query examples (https://docs.waf.chaitin.com/en/GetStarted/AddApplication). A blocking page means SafeLine stopped that request. Then open the console attack list and use the detail view. Also request a normal page, a client-side navigation, and one legitimate POST that your users need. A proxy that stops the samples but breaks a real form is not done.

Keep the management console off the public app hostname unless you intend to expose it. The install guide opens the console at https://<safeline-ip>:9443/ and creates the first administrator with docker exec safeline-mgt resetadmin (https://docs.waf.chaitin.com/en/GetStarted/Deploy). Store that initial password outside the Next.js repository. Record the upstream URL, the listen port, whether SSL is enabled, and the DNS rollback value in the same change note.

Does SafeLine ship a Next.js integration?

No. The install guide, the application guide, and the product overview used here describe a reverse proxy and an application record. They do not describe a Next.js plugin, middleware package, or platform add-on. The working record is domain, listen port, SSL when needed, and upstream.

Can the Next.js process keep its current port?

Yes, if that port is the upstream SafeLine forwards to. SafeLine listens on the port you configure, commonly 80 or 443, while the origin can remain on an internal port. The public domain must resolve to the SafeLine server, which is the change you should not make until the checklist above is filled in.

Which Next.js defects does this checklist remove?

It does not patch framework defects. It can filter HTTP attack classes named in the product documentation, throttle traffic over defined limits, challenge bots, require a password gate, and encrypt HTML and JS when dynamic protection is enabled. Authorization inside route handlers remains an application problem.

Should every challenge be enabled on the first day?

No. CAPTCHA, the authentication challenge, rate limiting, and dynamic HTML and JS encryption are separate features. Turn on the ones that match abuse you can name, then repeat the legitimate page and POST checks. A public marketing route and a signed-in app route do not need the same gate.

Which host choice blocks the Personal Edition?

ARM does. The deploy guide says a Pro license is required on ARM and that the Personal Edition is not supported there. Before you call the checklist complete, also confirm Docker, Docker Compose, disk, memory, and the ssse3 instruction on the SafeLine host, and prefer a maintained release over the unmaintained LTS line.

SafeLine has surpassed 700,000 installations worldwide as of September 30, 2026. SafeLine Pro annual promotional pricing is $650-$880, compared with the regular $1,000 per year.

SafeLine website: https://ly.cyberserval.tech/MqhYdmI
Demo: https://demo.waf.chaitin.com:9443/statistics
Official docs: https://docs.waf.chaitin.com/en/home
GitHub: https://github.com/chaitin/SafeLine
Pro offer: https://cyberserval.tech/landing/lto

How to Protect a Next.js App When No Framework Plugin Exists

Fri, 23 Oct 2026 04:01:56 +0000

If you are asking how to protect a Next.js app with a WAF, start by rejecting the idea of a hidden framework connector. The SafeLine documents supplied here never mention Next.js, React Server Components, a middleware file, or a platform add-on. They describe a self-hosted web application firewall that sits in front of a web application and filters HTTP traffic. The honest guide is a decision checklist: either your Next.js origin can sit behind that reverse proxy, or this product path does not fit. Do not fill the gap with an integration the sources do not describe.

SafeLine protects web apps by filtering and monitoring HTTP traffic between the application and the Internet. Deployed in front of the app, it is a reverse proxy: clients pass through it before they reach the server, and it blocks malicious HTTP and HTTPS traffic according to policy (https://docs.waf.chaitin.com/en/home). The application guide adds that SafeLine is developed based on nginx, receives traffic for the original site, cleans malicious attack traffic, and forwards safe traffic to the upstream application (https://docs.waf.chaitin.com/en/GetStarted/AddApplication). A Next.js server is in scope only as that upstream. Page routes, API routes, and form posts are protected to the extent they arrive as HTTP requests the proxy can see.

Run the fit checklist before DNS cutover

Work through these gates in order. A later control cannot repair a failed gate.

First, confirm you own an upstream address. In the console you add an application with a Domain, a listen Port, and an Upstream. Domain may be a domain name, a hostname, or an IP address. Port is what SafeLine listens on, such as 80 or 443, and HTTPS applications should use the SSL option. Upstream is the real address of the original app (https://docs.waf.chaitin.com/en/GetStarted/AddApplication). For Next.js, that upstream is the host and port of the Node process or container you actually run. If the app is hosted where you cannot place your own reverse proxy in front of it, stop. These pages do not document another mode.

Second, plan the client path. After the application record exists, you resolve the domain to the IP of the SafeLine server and reach the protected app through that domain. If visitors can still open the Next.js port directly, the WAF is optional and the exposure remains. Write the public port and the upstream port on two lines so Upstream never points back at SafeLine itself.

Third, check the WAF host against the deploy guide before you promise a launch date. SafeLine expects Linux on x86_64 or arm64, Docker 20.10.14 or above, Docker Compose 2.0.0 or above, and at least 1 CPU core, 1 GB of memory, and 5 GB of disk. The CPU also needs the ssse3 instruction (https://docs.waf.chaitin.com/en/GetStarted/Deploy). An ARM install requires a Pro license to work properly. The Personal Edition is not supported on ARM. The LTS release is no longer maintained starting from 9.1.0-LTS on 14 August 2025, and the guide strongly recommends moving to the latest version, or waiting about a month after a new release if you want a calmer upgrade.

Fourth, separate the management plane from the app plane. The web console is served at https://<safeline-ip>:9443/. The initial administrator account is created with docker exec safeline-mgt resetadmin, which prints the initial username and password. Store that password. Do not assume the console is protected just because the Next.js site is.

Fifth, decide which documented controls match this app, and leave the rest off until you have evidence. The core list is defenses for web attacks, proactive bot abused defense, HTML and JS code encryption, IP-based rate limiting, and a web access control list (https://docs.waf.chaitin.com/en/home). Rate limiting is documented against DoS attacks, brute-force attempts, traffic surges, and other abuse. A CAPTCHA challenge is documented to allow human users and block crawlers and bots. An authentication challenge requires a password before the visitor continues. Dynamic protection, when turned on, dynamically encrypts HTML and JS from the web server on each visit.

Map those controls onto Next.js without inventing a parser

Next.js does not get a special inspection profile in these documents. What you can say is narrower and still useful. A production Next.js app usually publishes HTML, JavaScript, and JSON over HTTP. Those are the surfaces the documented feature list talks about. The attack categories named on the product home page include SQL injection, XSS, code injection, OS command injection, CRLF injection, LDAP injection, XPath injection, RCE, XXE, SSRF, path traversal, backdoor, brute force, HTTP flood, and bot abuse, among others. The application guide uses query-string trial cases for SQL injection, XSS, path traversal, code injection, and XXE, then expects a blocking page and an entry in the attack list with a detail view.

Use that as a verification method, not as a claim that every Next.js bug class is covered. Replay the guide sample cases against your domain after DNS points at SafeLine. Confirm the block page. Open the attack detail. Then exercise a normal page load, a normal API call, and a normal form post so you can see whether a strict policy collides with legitimate traffic. The home page publishes an evaluation table, but this checklist does not treat that table as a sizing tool for your app.

Rate limiting belongs in the first tuning pass if the Next.js app has a login, a search box, or any route that triggers expensive server work. Bot and CAPTCHA controls belong next if anonymous clients scrape or hammer the site. The authentication challenge is a site gate, not your session implementation. Dynamic HTML and JS encryption is a documented option for pages that serve HTML and JS, which Next.js does, but the docs do not say it is required, and they do not say it is aware of client rendering. Turn it on only after a page-level test.

Keep the claims inside the sources

SafeLine states that it is production-ready, that it protects over 1,000,000 websites, and that it handles over 30,000,000,000 HTTP requests daily (https://docs.waf.chaitin.com/en/home). As of September 30, 2026, SafeLine surpassed 700,000 installations worldwide. SafeLine Pro annual promotional pricing is $650-$880 versus the $1,000 regular price. Those figures help a budget conversation. They do not change the install floor, and they do not prove that a minimal 1 core and 1 GB host will carry your traffic. The deploy guide gives a minimum, not a capacity plan.

I would also refuse three common overclaims. There is no documented command that installs SafeLine inside a Next.js repository. There is no documented connector for a hosted frontend platform that will not let you set an upstream. There is no documented promise that proxy filtering replaces authorization, output encoding, or dependency patching inside the app. The WAF can filter, monitor, and block malicious HTTP traffic, and the home page also says it prevents unauthorized data from leaving the app by applying policy. That is a proxy control. It is not a code review.

If the checklist fails at upstream ownership or DNS placement, do not publish a protected label. A request that never passes through SafeLine is outside every feature named above.

Does SafeLine document a Next.js integration?

No. The install and application guides describe a reverse proxy and an application record. They do not document a Next.js package, config plugin, middleware hook, or server-action mode. If you cannot proxy the origin, this setup is the wrong fit.

Which fields matter when the upstream is a Next.js server?

Domain, Port, and Upstream. Domain is the name clients use. Port is the SafeLine listen port, with SSL checked for HTTPS. Upstream is the real Next.js address. After saving, resolve that domain to the SafeLine server (https://docs.waf.chaitin.com/en/GetStarted/AddApplication).

What should I test on the first day?

Use the application guide sample cases for SQL injection, XSS, path traversal, code injection, and XXE, with your domain in place of the sample host. Expect the blocking page, then check the attack list and the detail view. Also send ordinary page, API, and form traffic so a policy problem is visible before users are.

When is dynamic protection a reasonable option?

When you want the documented behavior: HTML and JS encrypted dynamically on each visit. It is listed with the other main features, not as a Next.js switch (https://docs.waf.chaitin.com/en/home). Test real pages first. Do not treat it as a substitute for safe rendering in the app.

What host and license facts should a buyer check?

Linux, x86_64 or arm64, current Docker and Compose versions from the deploy guide, ssse3, and at least 1 core, 1 GB of memory, and 5 GB of disk. ARM needs a Pro license; the Personal Edition is not supported on ARM (https://docs.waf.chaitin.com/en/GetStarted/Deploy). As of September 30, 2026, SafeLine surpassed 700,000 installations worldwide, and SafeLine Pro annual promotional pricing is $650-$880 versus the $1,000 regular price.

SafeLine has surpassed 700,000 installations worldwide as of September 30, 2026. SafeLine Pro annual promotional pricing is $650-$880, compared with the regular $1,000 per year.

SafeLine website: https://ly.cyberserval.tech/MqhYdmI
Demo: https://demo.waf.chaitin.com:9443/statistics
Official docs: https://docs.waf.chaitin.com/en/home
GitHub: https://github.com/chaitin/SafeLine
Pro offer: https://cyberserval.tech/landing/lto

Your Next.js Dates Are Wrong for Half Your Users (and the Hydration Warning Is Only the Start)

Wed, 21 Oct 2026 11:48:27 +0000

You format a date in a component. It looks right on your laptop. Then a user in another country opens the page and either sees a console full of hydration errors, or worse, sees nothing wrong at all and reads the wrong time.

I live in a timezone that is five hours away from where most servers run, so this one finds me every time.

The Code That Looks Fine

// components/OrderDate.tsx
export function OrderDate({ date }: { date: string }) {
  return <p>Ordered on {new Date(date).toLocaleString()}</p>;
}

No hooks, no browser APIs, nothing that looks risky. It even works in next dev, because on your machine the server and the browser are the same computer.

Why It Breaks

In Next.js, this component runs twice: once on the server to produce the HTML, and again in the browser to hydrate it. toLocaleString() with no arguments uses the timezone and language of whatever machine runs it.

The server is often in UTC, with a default locale such as en-US.
Your user's browser might be in Karachi, with en-GB.

Server HTML:   Ordered on 10/20/2026, 10:15:00 AM
Browser render: Ordered on 20/10/2026, 15:15:00

React compares the two, finds that they differ, and logs a hydration error. In development, you see it. In production, React quietly tries to recover by re-rendering on the client, which costs time and can cause a visible flash.

Why It Is Hard to Catch

It never fails where you test. Same machine, same timezone, same locale: the two outputs are identical.
Many users never see an error. The page just shows one format for a split second and then another.
It often hides inside other pieces of data. Date.now(), Math.random(), new Date().getFullYear() and anything that reads window or localStorage can all produce a different value on the server and in the browser.

The Fix That Is Tempting, and Wrong

You will find this advice everywhere:

<p suppressHydrationWarning>
  Ordered on {new Date(date).toLocaleString()}
</p>

It does silence the warning. But per React's documentation, it only suppresses the warning on that one element and does not patch up mismatched text. The user can end up looking at the server's version of the time, which is in the wrong timezone.

You did not fix the bug, you removed the alarm for it.

Fix 1: Make the Output the Same on Both Sides

Pass an explicit locale and timezone, so the server and the browser calculate the same string:

export function OrderDate({ date }: { date: string }) {
  const text = new Date(date).toLocaleString('en-US', {
    timeZone: 'UTC',
    dateStyle: 'medium',
    timeStyle: 'short',
  });

  return <time dateTime={date}>{text} UTC</time>;
}

This is deterministic, so there is nothing to mismatch. It is the right choice for logs, admin tables and anything where showing UTC is acceptable. Label it as UTC so nobody reads it as local time.

Fix 2: Show the Local Time After the Page Loads

If users should see their own timezone, only compute it in the browser:

'use client';

import { useEffect, useState } from 'react';

export function LocalDate({ date }: { date: string }) {
  const [local, setLocal] = useState<string | null>(null);

  useEffect(() => {
    setLocal(
      new Date(date).toLocaleString(undefined, {
        dateStyle: 'medium',
        timeStyle: 'short',
      })
    );
  }, [date]);

  return (
    <time dateTime={date}>
      {local ?? new Date(date).toISOString().slice(0, 10)}
    </time>
  );
}

The first render, on the server and in the browser, shows a stable fallback (the ISO date). Right after hydration, useEffect runs only in the browser and swaps in the local time. Nothing mismatches, and the user ends up with the right value.

The cost is a brief change from the fallback to the local string. Keep the fallback short so the layout does not jump.

Fix 3: Store and Send Dates as ISO Strings

Whichever display option you pick, pass dates around as ISO strings (2026-10-20T10:15:00.000Z) and format them only at the edge, in one place. An ISO string is plain text, so it means the same thing on the server, in the browser and in your database.

Which One When

Situation	Fix
Admin tables, logs, reports	Fixed locale and `timeZone: 'UTC'`
Customer-facing times (orders, bookings, messages)	Format in the browser after mount
A date that never changes (blog post date)	Fixed locale and timezone, since the author's date is what matters

The Rule

Any value that depends on where the code runs, such as timezone, locale, the current time or a random number, will differ between the server and the browser. Either make it identical on both sides, or compute it only in the browser after hydration. Do not suppress the warning and hope.

Quick audit: search your project for toLocaleString(, toLocaleDateString(, Date.now() and Math.random() inside components that render on the server. Each one is either deterministic on purpose, or a mismatch that has not met a user in another timezone yet.

Hydration mistakes also slow pages down, because React has to redo work in the browser. I explain what that does to real-world speed scores in this plain-language guide to Core Web Vitals, and I keep every date in my Next.js templates formatted through one small helper so the server and the browser always agree.

Get the templates: https://pixelanas.gumroad.com

Which timezone bug has bitten you hardest? Drop it in the comments, especially if it only showed up in production.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Fix: useSearchParams() Should Be Wrapped in a Suspense Boundary (and Why It Only Breaks at Build

Sun, 18 Oct 2026 12:23:34 +0000

You add a small search box to your navbar. It reads the query string, so you reach for useSearchParams(). Everything works in next dev. You push, the deploy fails, and the build log says:

useSearchParams() should be wrapped in a suspense boundary at page "/about".
Read more: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout

Notice the page name. You did not touch /about. That detail is the whole story.

The Code That Triggers It

// components/SearchBox.tsx
'use client';

import { useSearchParams } from 'next/navigation';

export function SearchBox() {
  const searchParams = useSearchParams();
  const query = searchParams.get('q') ?? '';

  return <input defaultValue={query} placeholder="Search..." />;
}

// app/layout.tsx
import { SearchBox } from '@/components/SearchBox';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <nav>
          <SearchBox />
        </nav>
        {children}
      </body>
    </html>
  );
}

Nothing here looks wrong, and next dev agrees with you.

Why Only the Build Complains

At build time, Next.js tries to pre-render every page that does not obviously need request data into static HTML. That is the fast path, and it is the default.

But a static page is built once, before any visitor exists, so it has no query string. useSearchParams() needs one. Next.js handles this by bailing out of static rendering for that part of the tree: the component is skipped on the server and rendered in the browser instead.

The catch is how far the bail-out spreads. Without a Suspense boundary around the component, the nearest boundary is the page itself, which would turn the whole page into client-side rendering and quietly throw away the static HTML you were about to ship. Instead of letting that happen silently, the build fails and asks you to say where the boundary should be.

Dev mode renders every page on demand, so it never has to make that decision, which is why the error only shows up when you build.

Why It Hits Every Page at Once

I put the component in layout.tsx on purpose. A shared layout wraps every page, so one unguarded useSearchParams() in a navbar breaks the build for /, /about, /pricing and every other static route at the same time.

That is also why the error names a page you never edited. The problem lives in a shared component.

Fix 1: Wrap the Component in Suspense

// app/layout.tsx
import { Suspense } from 'react';
import { SearchBox } from '@/components/SearchBox';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <nav>
          <Suspense fallback={<input disabled placeholder="Search..." />}>
            <SearchBox />
          </Suspense>
        </nav>
        {children}
      </body>
    </html>
  );
}

Now only the search box is rendered in the browser. Everything else stays static HTML. The fallback is what visitors see until the client takes over, so make it the same size as the real component to avoid the layout jumping when it swaps in.

This is the fix to reach for first. It keeps your pages static and limits the client-side part to the one component that needs it.

Fix 2: Read the Params on the Server and Pass Them Down

If the value is only needed on one page, skip the hook entirely. Pages receive searchParams as a prop:

// app/search/page.tsx
export default async function SearchPage({
  searchParams,
}: {
  searchParams: Promise<{ q?: string }>;
}) {
  const { q } = await searchParams;
  return <SearchResults query={q ?? ''} />;
}

In Next.js 15, searchParams is a Promise, so it has to be awaited. Reading it marks that page as dynamic, so it renders per request instead of at build time. For a real search results page that is exactly what you want.

Fix 3: Force the Route to Be Dynamic

export const dynamic = 'force-dynamic';

This also makes the error disappear, but it does so by giving up static rendering for the route. Use it when the page genuinely depends on the request, not as a way to silence the build. On a marketing page it trades speed for nothing.

Which Fix When

Situation	Fix
Small interactive component reads the URL (navbar search, filters, tabs)	Suspense around that component
An entire page depends on the query string	Read `searchParams` in the page
The page really is per-request	`force-dynamic`

A Detail Worth Knowing About the Fallback

Whatever sits inside the Suspense boundary is client-rendered, so it will not be in the initial HTML. For a search input that does not matter. For content you want indexed, keep it outside the boundary. A fallback that does not match the final size also adds layout shift, which counts against your Core Web Vitals. I cover what those metrics measure in this plain-language guide.

The Rule

A client component that reads request-time data needs a Suspense boundary, so Next.js knows how much of the page to make dynamic. Put the boundary as close to the component as you can, and the rest of the page stays static.

I wrap every URL-driven component this way across my Next.js templates, so the production build never depends on where a navbar or filter bar ends up in the layout.

Get the templates: https://pixelanas.gumroad.com

Search your project for useSearchParams and check that every use sits inside a Suspense boundary, especially anything imported by layout.tsx. If you have hit a different build-only error, drop it in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Your Server Action Error Messages Vanish in Production, and Throwing Is the Wrong Tool

Sat, 17 Oct 2026 09:48:36 +0000

Here is a bug report you will eventually get: "The signup form told me what was wrong on your machine, but on the live site it just says something went wrong."

Nothing is broken. Next.js is doing this on purpose. But the code that triggers it looks completely normal, and it is in a lot of Server Actions tutorials, including a version in my own earlier post on replacing API routes.

The Code That Works Locally

// actions/signup.ts
'use server';

export async function signup(formData: FormData) {
  const email = formData.get('email') as string;

  const existing = await User.findOne({ email });
  if (existing) {
    throw new Error('That email is already registered');
  }

  await User.create({ email });
}

// components/SignupForm.tsx
'use client';

export function SignupForm() {
  const [error, setError] = useState('');

  async function handleSubmit(formData: FormData) {
    try {
      await signup(formData);
    } catch (e) {
      setError((e as Error).message);
    }
  }

  return (
    <form action={handleSubmit}>
      <input name="email" type="email" />
      <button type="submit">Sign up</button>
      {error && <p>{error}</p>}
    </form>
  );
}

In development, a duplicate email shows "That email is already registered". After next build and next start, or on Vercel, the same submission shows a generic message about an error occurring on the server, with a short digest string instead of your text.

Why Next.js Hides It

An error thrown on the server can carry anything: a database connection string inside a driver message, a file path, a query, a stack trace. If Next.js forwarded every thrown message to the browser, a single unexpected failure could leak internal details to anyone watching the network tab.

So in production builds, Next.js replaces the message of a thrown error with a generic one and attaches a digest, a short hash you can search for in your server logs. In development it shows you the real message because you are the only one looking.

That is the correct default. The mistake is using throw for something that is not an unexpected failure.

Two Kinds of Errors, Two Different Tools

Expected errors are things that will happen during normal use: a duplicate email, a wrong password, a failed validation, a card that was declined. The user should see a specific message and fix it.

Unexpected errors are things that should not happen: the database is down, a bug, a null that should not be null. The user should see a safe generic message and you should see the details in your logs.

throw is the right tool for the second kind. It is the wrong tool for the first, because the framework treats every thrown error as potentially sensitive and strips it.

The Fix: Return Expected Errors as Data

// actions/signup.ts
'use server';

import { z } from 'zod';

const SignupSchema = z.object({
  email: z.string().email('Enter a valid email'),
});

export type SignupState = {
  success: boolean;
  message?: string;
  fieldErrors?: Record<string, string[]>;
};

export async function signup(
  prevState: SignupState | null,
  formData: FormData
): Promise<SignupState> {
  const parsed = SignupSchema.safeParse({
    email: formData.get('email'),
  });

  if (!parsed.success) {
    return {
      success: false,
      fieldErrors: parsed.error.flatten().fieldErrors,
    };
  }

  const existing = await User.findOne({ email: parsed.data.email });
  if (existing) {
    return { success: false, message: 'That email is already registered' };
  }

  await User.create({ email: parsed.data.email });
  return { success: true, message: 'Account created' };
}

// components/SignupForm.tsx
'use client';

import { useActionState } from 'react';
import { signup } from '@/actions/signup';

export function SignupForm() {
  const [state, action, isPending] = useActionState(signup, null);

  return (
    <form action={action}>
      <input name="email" type="email" />
      {state?.fieldErrors?.email && <p>{state.fieldErrors.email[0]}</p>}
      <button type="submit" disabled={isPending}>
        {isPending ? 'Creating account...' : 'Sign up'}
      </button>
      {state?.message && <p>{state.message}</p>}
    </form>
  );
}

A returned value is just data. Next.js does not treat it as sensitive, so the exact same message reaches the user in development and in production. You also get useActionState handling pending state and the previous result for free, with no try/catch in the component.

Keep `throw` for the Real Failures

export async function signup(prevState, formData) {
  // ...expected errors returned as data above...

  try {
    await User.create({ email: parsed.data.email });
  } catch (error) {
    console.error('signup failed', error); // full details stay in your logs
    throw error; // user gets the safe generic message
  }

  return { success: true, message: 'Account created' };
}

When this throws in production, the user sees the generic message and an error boundary can take over. You search your logs for the digest and find the real error. Nothing sensitive reaches the browser.

Why This Survives Testing

Every manual test happens in next dev, where thrown messages are shown in full. The code looks perfect right up until the first production build, which is usually when real users start signing up.

The Rule

Return expected errors as data, throw only for unexpected failures. If a message is meant for the user to read, it should travel as a returned value. If it is meant for you to debug, it should go to your logs and surface to the user as something generic.

I use this return-a-state pattern in the forms and dashboard actions across my Next.js templates, so validation messages behave identically in development and on the live site.

Get the templates: https://pixelanas.gumroad.com

Search your own codebase for throw new Error inside files marked 'use server'. For each one, ask whether a user is supposed to read that message. If yes, it is probably already invisible in production. Drop what you find in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Why Your Tailwind Classes Work in Development and Silently Vanish in Production

Thu, 15 Oct 2026 12:05:37 +0000

Almost every Tailwind developer hits this exact bug once, usually right after a deploy, and the confusing part is that nothing about it looks wrong in the code, nothing throws an error, and it worked completely fine five minutes earlier on the same machine.

The Code That Looks Completely Reasonable

function StatusBadge({ status }: { status: 'success' | 'warning' | 'error' }) {
  const color = status === 'success' ? 'green' : status === 'warning' ? 'yellow' : 'red';

  return (
    <span className={`bg-${color}-100 text-${color}-800 px-2 py-1 rounded`}>
      {status}
    </span>
  );
}

In development, this renders exactly as expected, colored badges for each status, built dynamically from a single reusable component instead of three separate hardcoded ones. Then you deploy, and every badge renders as a plain, unstyled span. No color, no padding in some setups, nothing, depending on exactly what else got purged alongside it.

Why This Happens: Tailwind Doesn't Actually Execute Your Code

Tailwind doesn't run your JavaScript to figure out which classes you're using. It scans your source files as plain text, looking for strings that match known utility class patterns, and only generates CSS for the classes it actually finds written out, literally, somewhere in that scanned text.

className={`bg-${color}-100 text-${color}-800`}

Tailwind's scanner sees the literal text bg-${color}-100, not bg-green-100, bg-yellow-100, or bg-red-100. Template literal interpolation happens at runtime, in the browser or on your server, long after Tailwind's build step has already finished scanning your source files and generating the final CSS. Since none of the three actual color classes your component needs ever appears as literal, complete text anywhere in your codebase, Tailwind never generates CSS for any of them, and the class names that do get applied to the DOM at runtime simply don't exist in your stylesheet at all.

Why This Specifically Survives Local Development

This is the part that makes the bug genuinely sneaky rather than just a misunderstanding: in development mode, especially with certain dev server configurations or cached builds from before the dynamic class was introduced, you can sometimes see the correct styling anyway, either because an earlier full build still has the class generated from some other literal usage elsewhere in the project, or because of how some dev tooling handles incremental rebuilds. The failure shows up specifically in a clean production build, which scans and purges from scratch, with nothing left over from earlier development sessions to accidentally mask the problem.

The Fix: Always Write Complete Class Names, Literally

function StatusBadge({ status }: { status: 'success' | 'warning' | 'error' }) {
  const styles = {
    success: 'bg-green-100 text-green-800',
    warning: 'bg-yellow-100 text-yellow-800',
    error: 'bg-red-100 text-red-800',
  };

  return (
    <span className={`${styles[status]} px-2 py-1 rounded`}>
      {status}
    </span>
  );
}

Every complete, literal class name Tailwind needs now appears as actual text somewhere in the source file, bg-green-100, bg-yellow-100, bg-red-100, text-green-800, and so on, even though the specific one that gets applied is still chosen dynamically at runtime based on status. Tailwind's scanner finds all three as literal strings during the build, generates CSS for all three, and the correct one gets applied correctly regardless of which branch of the mapping object actually executes.

The Rule That Generalizes Beyond This One Example

Tailwind only generates CSS for class names that exist as complete, literal text somewhere in your scanned source files, string concatenation and template literal interpolation don't count, no matter how confident the resulting string looks at runtime. This applies to any dynamic styling pattern, not just color variants, conditionally built spacing classes, responsive variants built from a variable, state-based classes constructed from a prop, all of them need the complete literal class name written out somewhere Tailwind's scanner can see it, usually in a lookup object exactly like the one above, rather than assembled through string interpolation.

I keep every dynamic variant mapped out explicitly like this across the component libraries in my Next.js and Tailwind templates, specifically because this exact bug is so easy to reintroduce months later when someone, often future-you, refactors a component back toward the more compact-looking interpolated version without remembering why it was written the longer way.

Get the templates: https://pixelanas.gumroad.com

Go check your own codebase for className={...${variable}...} patterns building Tailwind classes dynamically. If you find one, do a clean production build and actually look at it, don't trust how it renders in dev. Drop what you find in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Vercel Was Too Expensive, So I Migrated My Next.js App to Cloudflare Workers

Thu, 15 Oct 2026 00:06:44 +0000

I recently moved production traffic for Galaxy Movies, my Next.js movie/TV discovery site, off Vercel and onto Cloudflare Workers. Nothing against Vercel. Vercel is a great platform, and the app ran happily there for a long time. But I was paying for a Pro plan for what is ultimately a side project, my DNS was already on Cloudflare, and the entire backend surface is fetch-based (Upstash REST, OpenAI, Resend, TMDB); no databases, no TCP. That's about as close to a best-case scenario for running Next.js on workers as you can get.

The site is Next.js 16 Pages Router, React 19, Chakra UI, with ISR catalog pages, a pile of API routes, four Vercel cron jobs, and dynamic OG images via next/og. Here's what the migration actually looked like, including the parts that fought back.

The adapter: @opennextjs/cloudflare
The OpenNext Cloudflare adapter takes a standard next build output and rebundles it into a worker. Setup is two files. First, open-next.config.ts. The interesting bit is the incremental cache override, which points ISR's cache at an R2 bucket:

import { defineCloudflareConfig } from '@opennextjs/cloudflare'

import r2IncrementalCache from '@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache'

export default defineCloudflareConfig({

  default: { experimentalBundledNextServer: true },

  incrementalCache: r2IncrementalCache

})
Then wrangler.jsonc:

{

  "main": ".open-next/entry.js",

  "name": "galaxy-movies",

  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],

  "assets": { "directory": ".open-next/assets", "binding": "ASSETS" },

  "services": [{ "binding": "WORKER_SELF_REFERENCE", "service": "galaxy-movies" }],

  "r2_buckets": [

    { "binding": "NEXT_INC_CACHE_R2_BUCKET", "bucket_name": "galaxy-movies-inc-cache" }

  ],

  "triggers": { "crons": ["0 6 * * *", "30 6 * * *", "0 7 * * *", "0 16 * * 5"] },

  "find_additional_modules": true,

  "rules": [

    { "type": "Data", "globs": ["public/fonts/**", "public/backdrop_fallback.jpg"], "fallthrough": true }

  ]

}

Deploy is two commands: opennextjs-cloudflare build then wrangler deploy. Everything below is the gap between "two commands" and "actually works in production."

Gotcha 1: Next's dev-only require()s break the bundle
The adapter bundles the Next server with esbuild, and esbuild wants every require() to resolve, including dev-only code paths inside Next's own dist files (next-dev-server, setup-dev-bundler, an upgrade nudge) and an RSC-only path (react-server-dom-webpack) that a Pages Router app never executes. They're dead code in production, but dead code still has to resolve.

I fixed it with patch-package to mark them external in the adapter's bundle step, plus a postbuild script that drops tiny stub modules where the runtime resolution lands:

// scripts/opennext-postbuild.js: runs after opennextjs-cloudflare build

fs.writeFileSync('.../dev/next-dev-server.js', 'module.exports = {}\n')

fs.writeFileSync('.../router-utils/setup-dev-bundler.js', 'module.exports = {}\n')

// ...etc

The patch also adds preview-props.json to the manifest glob the adapter uses, which the Pages Router build emits, and the adapter wasn't collecting. Not elegant, but it's contained in patches/ and reapplied on every npm install by patch-package. If the upstream adapter fixes these, the patch just stops applying cleanly, and I delete it.

Gotcha 2: next/og picks the wrong runtime
This one took the longest. I generate OG images with next/og, which wraps @vercel/og. The library has two entries: a Node build that does readFileSync on a bundled font and calls WebAssembly.instantiate at runtime (both disallowed on workerd), and an edge build that doesn't.

The problem: OpenNext forces NEXT_RUNTIME="nodejs" at bundle time, so next/og always resolves the Node entry, even inside a worker. The workaround is sniffing the runtime myself and importing the edge build directly:

const { ImageResponse } = (await (globalThis.navigator?.userAgent === 'Cloudflare-Workers'

  ? import(/* webpackIgnore: true */ 'next/dist/compiled/@vercel/og/index.edge.js')

  : import('next/og'))) as { ImageResponse: typeof ImageResponseType }

Navigator.userAgent === 'Cloudflare-Workers' is genuinely how you detect workerd. The webpackIgnore comment keeps webpack from trying to bundle the path at build time, and I pin the whole @vercel/og compiled directory into the output via outputFileTracingIncludes in next.config.ts so the edge build and its resvg wasm actually ship.

Gotcha 3: fs reads land in the wrong directory
My OG route also reads custom fonts and a fallback backdrop off disk with readFile(path.join(process.cwd(), 'public', ...)). On Vercel, process.cwd() is the project root. On workerd, the vfs cwd is /bundle (the .open-next output root), so public/fonts doesn't exist where the code looks for it.

The fix is a three-part move: the postbuild script copies public/fonts and backdrop_fallback.jpg into .open-next/public/, and wrangler's find_additional_modules + the Data rules in wrangler.jsonc ship those files in the worker's virtual filesystem. Same code path; files just exist where the worker looks.

Gotcha 4: packages hiding behind the workerd export condition
Some packages, in my case @emotion/* (Chakra's styling engine) and uncrypto, publish their ESM builds behind a workerd export condition. Next's file tracer only follows the CJS variants, so the worker bundle ends up with nothing it can resolve for those imports.

The fix is listing them in serverExternalPackages in next.config.ts, which tells the adapter to copy the packages whole instead of relying on tracing:

serverExternalPackages: [

  '@emotion/react', '@emotion/cache', '@emotion/serialize',

  '@emotion/sheet', '@emotion/weak-memoize', '@emotion/hash',

  '@emotion/memoize', '@emotion/unitless', '@emotion/utils',

  '@emotion/use-insertion-effect-with-fallbacks',

  'hoist-non-react-statics', 'uncrypto'

]

If you hit "cannot resolve module" errors on workerd that don't reproduce locally, this is the first thing to check.

Gotcha 5: Vercel crons don't exist on Workers
vercel.json crons are a Vercel platform feature; nothing in a Next.js build output describes them. On Workers, the equivalent is triggers.crons + a scheduled() handler. But the adapter generates worker.js, so I wrap it in a custom entry that adds the handler and maps each cron expression back to the same endpoint Vercel used to hit:

// .open-next/entry.js, written by the postbuild script

import worker from './worker.js'

const CRON_ROUTES = {

  '0 6 * * *': '/api/cron/generate-content',

  '30 6 * * *': '/api/cron/streaming-changes',

  '0 7 * * *': '/api/cron/watchlist-alerts',

  '0 16 * * 5': '/api/cron/weekly-digest'

}

export default {

  ...worker,

  async scheduled(event, env, ctx) {

    const route = CRON_ROUTES[event.cron]

    if (!route) return

    ctx.waitUntil(

      env.WORKER_SELF_REFERENCE.fetch(

        new Request('https://worker.internal' + route, {

          headers: { authorization: 'Bearer ' + env.CRON_SECRET }

        })

      )

    )

  }

}

Two things make this nice. The WORKER_SELF_REFERENCE service binding lets the worker call itself as an internal fetch, no public round trip. And the endpoints needed zero changes: they already checked Authorization: Bearer $CRON_SECRET because that's how Vercel's cron caller authenticates too. Testing is wrangler dev --test-scheduled, then hit /__scheduled?cron=0 6 *.

Secrets
wrangler secret bulk takes a JSON file, so a 20-line script converts .env.local into .secrets.json, skipping NEXTPUBLIC* vars (those get inlined at build time anyway) and my local Cloudflare API token. npm run cf:secrets and done: no dashboard clicking through a dozen vars.

Cutover and rollback
The safest part of the whole migration was the cutover itself, because I deliberately ran both platforms in parallel:

npm run cf:deploy, then verify everything on the *.workers.dev URL (all routes, OG images, cron triggers registered).
Attach the galaxymovies.app + www custom domains to the worker. Since DNS was already on Cloudflare, this was instant, no propagation wait.
Keep Vercel as cold standby: git.deploymentEnabled.main: false in vercel.json stops main pushes from auto-deploying, and I disabled the Vercel crons in the dashboard so the two platforms don't double-fire jobs.

Rollback is re-adding two DNS records (A to Vercel's anycast IP, CNAME www to the Vercel DNS name). Traffic flips back immediately because the worker custom domains only take precedence while they're the only records on those names. That escape hatch made the whole thing low-stress: worst case is a DNS edit, not a redeploy.

What's actually running
Same codebase, same next build, no platform fork in the source. SSR, ISR (backed by R2), all API routes, the OG image route, and all four crons work identically to how they did on Vercel. The only code that knows which platform it's on is that one navigator.userAgent check in the OG route.

The honest summary: the adapter gets you ~80% there out of the box, and the remaining 20% is the kind of platform-shim work above. It's tractable, but expect an afternoon of debugging, not a lunch break. If your app leans on Node APIs that aren't fetch-shaped, the logic is different. But if you're already edge-friendly and your DNS is on Cloudflare anyway, the economics are hard to argue with, and Vercel sitting dormant as a free rollback target is a pretty nice safety net.

Repo notes worth taking if you're doing this: patch-package for the adapter externals, a postbuild script for stubs + vfs assets + the cron entry, serverExternalPackages for workerd-conditioned packages, and wrangler dev --test-scheduled for cron testing.

Happy to answer questions in the comments!

Your Next.js Page Might Be Caching One User's Data and Serving It to Everyone Else

Wed, 14 Oct 2026 07:51:52 +0000

This is the kind of bug that goes from "works perfectly in every test" to "actively leaking one customer's data to another customer" without a single code change in between, purely because of how caching and personalization interact in a way that isn't obvious from reading the component code.

The Setup

// app/dashboard/page.tsx
export default async function DashboardPage() {
  const session = await getServerSession();
  const user = await User.findById(session.userId);

  return (
    <div>
      <h1>Welcome back, {user.name}</h1>
      <p>Account balance: {user.balance}</p>
    </div>
  );
}

This looks obviously personalized, it reads the session, looks up the specific user, renders their specific data. There's nothing here that looks like it needs special caching considerations. That assumption is exactly where this goes wrong.

Why Next.js Can Get This Wrong

Next.js's App Router tries to statically render as much as possible by default, for good performance reasons. A page gets treated as static (cacheable, shared across all visitors) unless something in it signals that it needs to be dynamic (rendered fresh per-request). Specific APIs, reading cookies(), headers(), or searchParams directly, are what tell Next.js a page actually depends on request-specific data and needs dynamic rendering.

The problem is that getServerSession() in the example above may, depending on exactly how it's implemented and which auth library version you're on, read the session cookie in a way that doesn't always propagate that dynamic signal up to the page itself, especially if the cookie read happens inside a library function several layers removed from the page component, rather than a direct cookies() call visible in the page's own code. When that signal doesn't propagate correctly, Next.js can determine the page is eligible for static optimization, render it once during the build or on first request, and then serve that exact same rendered HTML, including the first user's name and balance, to every subsequent visitor who hits that route, until the cache naturally expires or gets invalidated.

Why This Is Specifically Dangerous, Not Just Buggy

A caching bug that shows stale content is annoying. A caching bug that shows a different user's personal data is a real data exposure incident, and the specific danger here is that it doesn't look like a caching bug from the outside, it looks like the application is broken for that specific user, showing someone else's name and balance, which can easily get reported and triaged as "a display bug" rather than correctly identified as a serious caching and session isolation issue.

Why This Survives Normal Testing

Testing a dashboard page almost always means logging in as a specific test user and confirming their own correct data renders. That test passes regardless of whether the response got cached and shared or genuinely rendered fresh for that specific request, because from a single test account's perspective, the result looks identical either way. The bug only becomes visible with two separate user sessions hitting the same route in a way that reveals the cached response is actually shared, which isn't a scenario most manual or automated testing naturally covers.

The Fix: Force Dynamic Rendering Explicitly for Anything Personalized

Don't rely on an auth helper's internal implementation to correctly signal dynamic rendering. State it explicitly for any route serving per-user data:

// app/dashboard/page.tsx
export const dynamic = 'force-dynamic';

export default async function DashboardPage() {
  const session = await getServerSession();
  const user = await User.findById(session.userId);

  return (
    <div>
      <h1>Welcome back, {user.name}</h1>
      <p>Account balance: {user.balance}</p>
    </div>
  );
}

The export const dynamic = 'force-dynamic' line removes any ambiguity about whether the page qualifies for static optimization. It costs the performance benefit of static rendering for that specific route, which is the correct tradeoff for anything genuinely personalized, that cost is real but small compared to the alternative.

An equally valid alternative is calling cookies() or headers() directly inside the page itself, rather than only inside a wrapped auth helper function, since a direct call from the page component is what reliably signals dynamic rendering without depending on how a library internally implements its own session check.

import { cookies } from 'next/headers';

export default async function DashboardPage() {
  cookies(); // explicit, direct call signals dynamic rendering regardless of what getServerSession does internally
  const session = await getServerSession();
  // ...
}

The Rule

Any page serving per-user or per-request data needs to explicitly and verifiably opt out of static rendering, not just assume an auth library's internals do that correctly on its behalf. This matters more, not less, as auth libraries and caching layers evolve between versions, since a signal that correctly propagated in one version can silently stop doing so after an update you didn't closely audit.

I treat every authenticated dashboard route as explicitly force-dynamic by default in the Next.js dashboard templates I build, specifically because the cost of guessing wrong here is a real user data leak, not just a stale page.

Get the templates: https://pixelanas.gumroad.com

Go check your own authenticated pages for an explicit dynamic export or a direct cookies()/headers() call, rather than relying on an auth helper to signal it correctly on your behalf. If you're not sure, this is worth verifying with two separate logged-in sessions today, not assuming. Drop what you find in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Your Mongoose pre('save') Hook Is Being Silently Skipped by Half Your Update Calls

Tue, 13 Oct 2026 09:40:18 +0000

This is one of the more consequential Mongoose gotchas because of exactly what tends to live inside a pre('save') hook, password hashing, slug generation, validation logic, and exactly which methods silently bypass it without ever telling you.

The Setup

// models/User.ts
const userSchema = new Schema({
  email: String,
  password: String,
});

userSchema.pre('save', async function (next) {
  if (this.isModified('password')) {
    this.password = await bcrypt.hash(this.password, 12);
  }
  next();
});

export const User = model('User', userSchema);

Create a new user with User.create() or new User(data).save(), and this works exactly as intended. The password arrives hashed, every time, without the rest of your codebase needing to remember to call bcrypt.hash manually anywhere. It feels like a solved problem.

Where It Actually Breaks

// A password reset flow
export async function resetPassword(userId: string, newPassword: string) {
  await User.findByIdAndUpdate(userId, { password: newPassword });
}

This runs without error. It updates the user's password field in the database. It also never calls pre('save'), which means the password gets stored in plain text, directly in your database, with no error, no warning, and a function name, findByIdAndUpdate, that reads as a completely reasonable, idiomatic way to update a user record.

findByIdAndUpdate, findOneAndUpdate, updateOne, and updateMany all operate directly against MongoDB's update commands. They don't instantiate a full Mongoose document and call .save() on it internally, they issue an update operation straight to the database. Mongoose's document middleware, including pre('save'), only runs on document instances that actually go through .save(). These query-based update methods structurally never touch that code path at all.

Why This Specifically Gets Missed

Both approaches, .save() and findByIdAndUpdate, look like equally valid, equally idiomatic ways to update a Mongoose document, and most Mongoose tutorials use both interchangeably without flagging that they behave completely differently with respect to middleware. A codebase that uses .save() for creating users and findByIdAndUpdate for updating them, which is an extremely common and reasonable-looking pattern, ends up with password hashing that works perfectly at signup and silently doesn't exist at all for a password reset, profile update, or admin-initiated password change, unless someone happens to specifically test that exact path with a tool that shows raw database contents.

The Fix: Use Query Middleware, Not Just Document Middleware

Mongoose provides a separate middleware hook specifically for query-based update methods:

userSchema.pre('findOneAndUpdate', async function (next) {
  const update = this.getUpdate() as any;

  if (update.password) {
    update.password = await bcrypt.hash(update.password, 12);
  }

  next();
});

This specifically targets findOneAndUpdate and findByIdAndUpdate (which is implemented as a wrapper around findOneAndUpdate internally). updateOne and updateMany need their own separate middleware registration, since Mongoose treats each query method as its own distinct middleware hook rather than one unified "any kind of update" event:

userSchema.pre('updateOne', async function (next) {
  const update = this.getUpdate() as any;
  if (update.password) {
    update.password = await bcrypt.hash(update.password, 12);
  }
  next();
});

A More Defensive Alternative: Standardize on One Update Path

Registering middleware separately for every query method Mongoose offers is viable but easy to let drift out of sync as new update call sites get added later by someone who doesn't know this distinction exists. A more durable fix for anything genuinely sensitive, like password handling, is routing all updates through a single service function that always uses .save() internally, rather than letting findByIdAndUpdate calls for that model spread throughout the codebase:

// services/userService.ts
export async function updateUser(userId: string, data: Partial<UserInput>) {
  const user = await User.findById(userId);
  if (!user) throw new Error('User not found');

  Object.assign(user, data);
  await user.save(); // always goes through pre('save') middleware
  return user;
}

This trades a small amount of performance, an extra read before the write, for a guarantee that every update for this model goes through the exact same validation and transformation logic, with no separate middleware registration required for each query method and no risk of a future findByIdAndUpdate call quietly skipping it.

The Rule

Anything inside a pre('save') hook only runs for updates that go through .save(), never for findOneAndUpdate, findByIdAndUpdate, updateOne, or updateMany. For any logic where skipping it has real consequences, password hashing being the clearest example, either register the equivalent query middleware for every update method your codebase actually uses, or standardize on a single service function that always goes through .save().

I route every sensitive field update through a dedicated service layer exactly like this in the auth code behind my Next.js and MongoDB templates, specifically because this gap is easy to introduce the moment a second developer, or a future version of yourself, reaches for the more convenient-looking findByIdAndUpdate call.

Get the templates: https://pixelanas.gumroad.com

Go check your own password reset, profile update, and admin edit flows for a findByIdAndUpdate or updateOne call on a model with password hashing in pre('save'). If you find one, check what's actually sitting in that field in your database right now. Drop what you find in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Your NextAuth callbackUrl Might Be an Open Redirect Waiting to Happen

Mon, 12 Oct 2026 10:39:32 +0000

Redirecting a user back to the page they were trying to reach after they log in is good, expected UX. Nobody wants to log in and land back on the homepage when they were actually trying to read a specific article or check out a specific product. The common way this gets implemented is also a common way to accidentally build an open redirect vulnerability directly into your auth flow.

The Pattern That Looks Completely Reasonable

// app/login/page.tsx
export default function LoginPage({ searchParams }: { searchParams: { callbackUrl?: string } }) {
  return (
    <form action={async (formData: FormData) => {
      'use server';
      const result = await signIn('credentials', {
        email: formData.get('email'),
        password: formData.get('password'),
        redirect: false,
      });

      if (result?.ok) {
        redirect(searchParams.callbackUrl || '/dashboard');
      }
    }}>
      {/* form fields */}
    </form>
  );
}

This is a genuinely common pattern, a protected page redirects an unauthenticated visitor to /login?callbackUrl=/dashboard/reports, and after a successful login, the app sends them back to wherever that parameter points. It works correctly, and it feels like a small, harmless convenience feature, right up until someone realizes that callbackUrl value came straight from a query string the visitor controls entirely.

What an Attacker Actually Does With This

https://yourapp.com/login?callbackUrl=https://evi1-yourapp-login.com/phish

If your redirect logic trusts the callbackUrl value without validating that it actually points somewhere inside your own app, a victim who clicks a link like this, maybe from a phishing email that looks legitimate because the domain in the visible link is genuinely yourapp.com, logs in successfully on your real site, with their real credentials, and then gets silently redirected to an attacker-controlled page immediately afterward. That page can look like anything, a fake "session expired, please log in again" prompt designed to harvest the same credentials a second time, now with the victim's guard completely down because they just successfully authenticated on the real site seconds earlier.

This is specifically dangerous because every part of the actual login happened on your real, legitimate domain. Nothing about the login page itself looked suspicious, because it wasn't, the vulnerability is entirely in what happens after a genuine, successful login.

Why This Is Easy to Miss

Redirect-after-login code gets tested by developers clicking through their own app, which only ever produces callbackUrl values that point to real internal pages, because that's the only way anyone naturally encounters this flow during development. The idea of someone deliberately crafting a malicious external value for this parameter doesn't come up unless security testing specifically targets it, since from a pure functionality standpoint, the feature works perfectly for every normal case anyone would think to try.

The Fix: Validate the Redirect Target Is Actually Internal

// lib/safe-redirect.ts
export function getSafeRedirectUrl(callbackUrl: string | undefined, fallback = '/dashboard'): string {
  if (!callbackUrl) return fallback;

  // Reject anything that isn't a relative path starting with exactly one slash.
  // "//evil.com" and "https://evil.com" both get rejected here,
  // protocol-relative URLs are a classic bypass for a naive check.
  if (!callbackUrl.startsWith('/') || callbackUrl.startsWith('//')) {
    return fallback;
  }

  return callbackUrl;
}

if (result?.ok) {
  redirect(getSafeRedirectUrl(searchParams.callbackUrl));
}

The specific check for a leading // matters more than it looks like it should. A browser interprets //evil.com as a protocol-relative URL, meaning it resolves to https://evil.com using whatever protocol the current page is on, and a naive check that only verifies "does this start with a single slash" can be bypassed entirely by that exact pattern. Rejecting anything that doesn't match a genuine single-slash-prefixed relative path closes this specific gap.

If you're using NextAuth's built-in redirect callback, the same principle applies there directly, NextAuth exposes a redirect callback specifically so you can validate target URLs centrally:

// auth.ts
export const authOptions: NextAuthOptions = {
  callbacks: {
    async redirect({ url, baseUrl }) {
      // Only allow redirects to the same origin as the app itself
      if (url.startsWith(baseUrl)) return url;
      if (url.startsWith('/')) return `${baseUrl}${url}`;
      return baseUrl;
    },
  },
};

The Rule

Any redirect target sourced from user-controllable input, a query parameter, a form field, a referrer header, needs to be validated as pointing somewhere inside your own app before you redirect to it. "It's just a convenience redirect" is exactly the framing that makes this vulnerability easy to introduce without noticing, since the feature's happy path looks completely benign and only the deliberately crafted input reveals the gap.

I validate every redirect target this way in the auth flows across my Next.js dashboard templates, since login and post-auth redirects show up in basically every project and this is a genuinely easy detail to skip under normal development pressure. More on the broader auth patterns I build around at pixelanas.com.

Get the templates: https://pixelanas.gumroad.com

Go check your own login flow for a callbackUrl, returnTo, or next parameter that gets redirected to without validation. If you find one, try crafting a //evil.com style value against it. Drop what you find in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Your Next.js Middleware Matcher Config Is Probably Skipping Routes You Think It Protects

Sun, 11 Oct 2026 14:25:54 +0000

Middleware feels like the cleanest way to gate an entire section of a Next.js app behind auth, one file, one config, covering everything under a path. That confidence is exactly the problem, because the matcher config that's supposed to define "everything under this path" has a few specific gaps that don't show up until someone hits a nested route that quietly skipped the check entirely.

The Setup That Looks Complete

// middleware.ts
import { NextResponse } from 'next/server';
import { getToken } from 'next-auth/jwt';

export async function middleware(request: NextRequest) {
  const token = await getToken({ req: request });

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: '/dashboard/:path*',
};

This reads as "protect everything under /dashboard," and for the routes most people test during development, /dashboard, /dashboard/settings, /dashboard/analytics, it works exactly as expected. The gap shows up specifically with route groups and parallel/intercepting route conventions, which don't map onto the URL path the way the folder structure visually suggests they do.

Where It Actually Breaks

app/
├── (dashboard)/
│   ├── dashboard/
│   │   └── page.tsx          → /dashboard
│   └── settings/
│       └── page.tsx          → /settings  (NOT /dashboard/settings!)

Route groups, the parenthesized folders, don't appear in the URL at all. A page at app/(dashboard)/settings/page.tsx is served at /settings, not /dashboard/settings, even though it visually sits inside what looks like your dashboard's folder in the codebase. A matcher: '/dashboard/:path*' pattern never matches /settings, because as far as the URL is concerned, it was never under /dashboard to begin with.

This is exactly the kind of structural confusion that's easy to carry forward from a folder structure that leans on route groups for layout purposes, the same route groups I use throughout the Next.js templates on pixelanas.com, without re-checking that every protected page's actual URL still falls inside the matcher pattern protecting it, because the folder nesting and the URL nesting have quietly diverged.

A Second, Subtler Gap: Matcher Patterns and Encoded Characters

Next.js's own documentation for the matcher config notes that values must be literal strings or simple patterns, matcher patterns don't support arbitrary regex features, and certain edge cases around encoded path segments or unusual characters in dynamic segments can fail to match in ways that aren't obvious from reading the pattern itself. A route like /dashboard/reports/q1%2F2026 (an encoded slash inside a dynamic segment) can behave unpredictably against a pattern that looks like it should obviously cover it.

Why This Doesn't Get Caught

Testing auth-gated routes usually means manually clicking through the main pages of a protected section, the ones directly nested under the obvious path, and confirming the redirect works. Pages that technically live in the same conceptual section of your app but sit outside the matched URL pattern because of a route group, or a page that was added later and happens to resolve to a URL slightly outside what the matcher covers, simply never get manually tested against the auth gate, because nobody thinks to check a URL that doesn't look like it needs checking.

The Fix: Verify Matcher Coverage Against Actual Resolved URLs, Not Folder Structure

Don't trust the matcher pattern based on how your app/ folder looks. Check it against the actual resolved URL of every page you intend to protect:

export const config = {
  matcher: [
    '/dashboard/:path*',
    '/settings/:path*',       // explicitly added once the real URL was checked
    '/billing/:path*',
  ],
};

A more defensive pattern for anything genuinely sensitive is inverting the logic entirely, protect everything by default, and explicitly exclude the few public routes, rather than trying to enumerate every protected path and hoping the list stays complete as the app grows:

export const config = {
  matcher: [
    '/((?!login|signup|api/public|_next/static|_next/image|favicon.ico).*)',
  ],
};

This pattern protects everything except the explicitly named public routes, which means a newly added page under a route group, or anywhere else, is protected by default rather than silently falling outside coverage until someone notices.

The Rule

A middleware matcher pattern should be verified against the app's actual resolved URLs, not assumed from how the app/ folder is visually organized. Route groups, parallel routes, and intercepting route conventions all affect the URL in ways that don't match the folder nesting, which is exactly where a matcher pattern that looks complete quietly isn't.

Get the templates: https://pixelanas.gumroad.com

Go check your own middleware matcher against the real URLs of every page it's supposed to protect, not the folder structure. If any of them use route groups, this is worth double-checking today. Drop what you find in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

You Changed a User's Role in the Database, But Their JWT Doesn't Know That Yet

Sat, 10 Oct 2026 13:33:53 +0000

You find out a user's permissions need to change right now, maybe they're being demoted from admin, maybe their account access is being revoked entirely after an incident. You update the database. The change looks instant in your admin panel. Meanwhile, that user keeps acting with their old permissions for as long as their existing session token stays valid, sometimes for hours, sometimes for days, and nothing about your database update touched that.

Why This Happens: JWTs Don't Check Back In

A JWT-based session, the kind most Next.js apps use with something like NextAuth, is a self-contained token. Once it's issued, your server verifies it by checking its signature and expiration, not by looking anything up in your database. That's the entire point of a stateless token, it avoids a database round trip on every single request.

// middleware.ts
export async function middleware(request: NextRequest) {
  const token = await getToken({ req: request });

  // This only checks: is the signature valid, has it expired?
  // It does NOT check: does this role still match what's in the database right now?
  if (token?.role !== 'admin') {
    return NextResponse.redirect(new URL('/unauthorized', request.url));
  }

  return NextResponse.next();
}

The role embedded in that token was correct the moment it was issued. It is not re-verified against the database on every request, because doing so would defeat the entire performance benefit of using a stateless token in the first place. If you update the user's role in the database five minutes after their token was issued, the token itself still says the old role, and will keep saying that until it expires and they're forced to log in again.

Where This Actually Causes Real Problems

For a routine role change, like a title update that doesn't affect sensitive access, a short delay before it takes effect is a minor inconvenience, at worst, mildly confusing. For a security-sensitive revocation, suspending an account after detecting suspicious activity, revoking admin access after an employee departure, removing a compromised API key's associated session, that same delay is a real exposure window. The access you believed you'd just shut off is still fully functional from the attacker's or departed employee's side, for however long their existing token remains valid.

Why This Is Easy to Miss Building the App

Session and role logic almost always gets tested by logging in fresh after making a change, which issues a brand new token with the updated role baked in, making the fix look like it worked perfectly. The actual bug only shows up for a user who's already logged in with an existing token at the moment the change happens, a scenario that's genuinely easy to never think to test, since it requires two separate sessions and specific timing to notice.

The Fix: Force Re-Verification for Anything Sensitive

The cleanest general fix is shortening token lifetime for sensitive roles and pairing it with refresh logic that re-checks the database:

// auth.ts (NextAuth config)
export const authOptions: NextAuthOptions = {
  session: {
    strategy: 'jwt',
    maxAge: 15 * 60, // 15 minutes instead of days, forces more frequent re-issuance
  },
  callbacks: {
    async jwt({ token, user, trigger }) {
      if (trigger === 'update' || !token.lastChecked || Date.now() - (token.lastChecked as number) > 60_000) {
        // Re-fetch the current role from the database periodically,
        // not just at initial login
        const dbUser = await User.findById(token.sub).select('role status');
        if (!dbUser || dbUser.status === 'suspended') {
          return { ...token, role: null, revoked: true };
        }
        token.role = dbUser.role;
        token.lastChecked = Date.now();
      }
      return token;
    },
  },
};

For genuinely urgent revocations, like an active security incident, token expiration alone isn't fast enough, and this is where some form of server-side revocation check becomes necessary, a denylist of revoked token IDs checked against a fast store like Redis, even if you're otherwise fully stateless everywhere else. It adds back a small lookup cost, but only for the specific case where "wait until the token expires naturally" genuinely isn't an acceptable answer.

// A minimal revocation check added to middleware
const isRevoked = await redis.sismember('revoked_sessions', token.jti);
if (isRevoked) {
  return NextResponse.redirect(new URL('/login', request.url));
}

The Rule

A JWT's claims are a snapshot from the moment it was issued, not a live view of your database. Any role or permission check based purely on token contents can be stale for as long as that token remains valid. For routine data, that staleness is usually an acceptable tradeoff for performance. For anything where immediate revocation actually matters, you need either short-lived tokens with periodic re-verification, or an explicit revocation check, because the token itself has no way of knowing anything changed.

I treat this distinction explicitly in the auth setup behind my Next.js dashboard templates, where role-based access control needs to actually mean something the moment it changes, not sometime later.

Get the templates: https://pixelanas.gumroad.com

Check your own app, specifically how fast a role change or account suspension actually takes effect for a user with an existing session. If the honest answer is "whenever their token expires," that's worth deciding on purpose rather than by default. Drop what you find in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

How we check every AI-generated room render before a user sees it

Fri, 09 Oct 2026 18:55:25 +0000

Image models are very good at restyling a room and quietly bad at leaving the room alone. Ask for a Japandi living room and you get beautiful furniture, and sometimes also:

a window that moved, shrank, or appeared over a kitchen sink where the photo shows a solid wall;
a closet door that came back as a curtain, a sliding screen, or plain wall;
a sofa parked across the only archway;
a new doorway at the frame edge, or a niche carved into a flat wall;
a camera that slid sideways;
or the opposite: a picture that is almost exactly the photo you uploaded.

Our users put these images in property listings, where a staged photo may change the furniture but not the windows, walls or doors (why that line exists). So every render is checked automatically before anyone sees it. Here is how, and what building it taught us.

The pipeline at a glance

For an indoor room, each render goes through three gates in parallel:

A vision-model judge compares the original photo with the render and answers a fixed list of yes/no questions.
A mechanical camera check measures whether the viewpoint moved, with no language model involved.
A crop-level presence check looks at each door, window and staircase found in the original, at full resolution.

If all three pass, the render is served. If not, we retry. If nothing passes, the user gets the best attempt, clearly marked as a draft.

Gate 1: a judge that only answers booleans

The judge gets the original and the render, both downscaled, and must return a fixed JSON object. We use structured output with a schema, so it cannot reply in prose. An earlier version asked for "only JSON" and scraped it out with a regex; when the output got long or cut off, the parse failed and the gate silently did nothing.

Indoors there are 16 checks, outdoors 9. Indoors they cover:

Openings: every door is still a door you could open; every passage has clear floor to walk through.
Windows: same count, position, size and shape; none invented; not hidden behind a tall wardrobe; the same view outside.
The room shell: ceiling, fireplace, no carved niches, features on the same walls, solid frame edges, no new rooms or corridors.
Finish consistency: no half-repainted rooms.
Content rules: no people, and no photo or realistic portrait of a person in the wall art.
Camera: same viewpoint, same room depth.

Outdoors: buildings, fence line and gates, terrain (no new pool), mature trees, background, and a usable driveway.

A simplified, illustrative verdict:

{
  "doors_preserved": true,
  "openings_clear": false,
  "windows_ok": true,
  "window_unblocked": true,
  "walls_uniform": true,
  "frame_edges_solid": true,
  "no_faces_in_art": true,
  "fail_reasons": ["sofa end stands on the archway floor"]
}

A render passes only if every counted boolean is true; the reasons feed logs and the retry prompt. Most of the work went into the wording:

Say what must pass. Restyling is the product, so the instructions list what is expected (new floors, paint, wallpaper, fixtures) and say "unsure means pass". The exception is a short list where unsure means fail, led by a window that may not have been in the original. An invented window is the worst defect a listing photo can have.

One question per field. While the frame-edge rule was a sub-clause of a broader "no phantom architecture" check, new doorways at the frame edge got through. Its own boolean made the model actually look.

Naming things primes the judge. An early niche check listed which shelves were allowed, and the judge started flagging every shelf. The current wording is purely geometric: is this flat wall still one plane?

Allow "nothing to compare". The "same view through the window" check kept firing on originals with blinds drawn or glass blown out to white. That case is now an explicit pass.

Wording is measurable. The old wall-art wording wrongly failed 10 of 16 good frames (stylised line drawings counted as faces). The rewrite failed 0 of 16 and still caught all 5 real portraits.

Gate 2: measuring the camera instead of asking about it

Early on, the vision model was close to blind to viewpoint changes: renders shot from a visibly different spot passed every neural check. Later, a stronger judge had the opposite problem: on 43 renders where the camera had not moved, it said it had 13 times. So indoors the judge's camera answers no longer decide pass or fail. A measurement does, with two channels:

Ceiling line. We trace the wall/ceiling boundary as a curve (dynamic programming over the vertical brightness gradient) and compare the original's curve with the render's.
Depth profile. A monocular depth model estimates both images. Per column we take how far the far wall reads, then compare the profiles with a robust fit, a rank correlation and a search for a sideways shift.

Each channel is fooled by something different. Paint fools the ceiling line (dark beams, art on a mantel). Glass fools depth (windows and mirrors are estimated differently each time). Paint is flat in depth, and glass does not move the ceiling line, so we flag a shift only when both agree: the minimum of the two normalised scores.

On 24 hand-labelled pairs from two rooms, this caught 5 of 5 real shifts with 0 false flags. The margin was thin, so a grey zone around the threshold is logged, not failed. Outdoors there is no ceiling to trace, so the mechanical check is off and the judge's camera question stays in charge.

Gate 3: crops, because a door is 80 pixels wide

At the judge's resolution a front door is a thin strip. So doors, windows and stairs are detected at upload, and after each render a model is asked about each crop at full resolution: is it still there? A mechanical channel also measures whether a window drifted or widened. On 87 labelled pairs, the crop judge caught 7 of 10 broken renders with no false alarms on the 75 clean ones; the mechanical channel caught the other 3.

When a render fails

Retries depend on the kind of defect.

Placement defects (a blocked passage, a face in the art, half-painted walls) are retried on the same image model with the judge's reasons added to the prompt.
Geometry defects go to a second, pricier image model. We measured a same-model retry fixing broken geometry about one time in five. In an earlier bake-off the two models were clean on 18 and 17 of 20 renders, and 19 of 20 together: their failures barely overlap.

The geometry retry gets a fixed, count-based instruction ("same set of openings, not one more, not one less"), never the judge's description of the defect. When a retry prompt named an arched opening at the left edge, the retry model painted exactly that.

If nothing passes, the user still gets the best attempt, under a "rough draft" banner. On paid plans the first four rejected drafts in a rolling week don't use a render; the free plan gets one. The cap is deliberate: a draft is a real, downloadable image, so unlimited forgiveness would be a free image farm.

The checks fail open. If the judge itself errors or times out, the user is not blocked: the image is served flagged, and an unverified render is not charged as a draft.

The near-copy trap

At first, "best attempt" meant the one with the fewest failed checks. The attempt that breaks the least is often the one where the model barely did anything. In one real case the first attempt was a convincing industrial restyle that failed on geometry, and the user was served the second: their old room, old wallpaper and all, plus a pair of lamps. The ranking was paying the model for doing nothing.

The fix is a change meter: shrink both images to a tiny thumbnail and count how much of the frame visibly changed. No model call, and we calibrated it on 110 real renders and 10 synthetic near-copies (recompressed, blurred, brightened, shifted, a couple of lamp-sized patches). The ranking now:

// simplified
function draftRank(a: Attempt): number {
  if (a.checkerErrored) return LAST;
  let rank = a.failedChecks.length;
  if (a.hasPeopleOrRealFacesInArt) rank += HARD_BAN;
  if (a.isNearCopy && a.intensity !== "light") rank += NEAR_COPY;
  return rank; // lowest is served
}

A light restage is exempt, because there the user asked us to keep the room.

Picking the judge model with a calibration set

The judge runs on every attempt, so a cheaper model is tempting. We keep a calibration set of 31 hand-labelled frames and run every candidate on it twice. A cheaper model at under half the price per call missed 6 defects per run against our current judge's 3. On 46 live renders with 8 defects marked by eye, it caught 0 and 1 across two runs; the current judge caught 6. A newer model wasn't clearly better either: fewer misses (2 vs 3), twice the false alarms (4 vs 2). We kept the current judge.

Takeaways

Ask the judge narrow yes/no questions, not one "is this good?".
Where geometry can be measured, measure it, with channels whose failure modes don't overlap.
Calibrate every wording change and model swap on a labelled set, twice.
Design the failure path as carefully as the check: ranking, draft label, who pays.
"Least broken" can mean "least changed". Measure change directly.

We build this at AI Flip Room.

I built email alerts for my app with no login system

Thu, 08 Oct 2026 23:42:57 +0000

My movie discovery site (galaxymovies.app) needed a feature that sounds simple: "email me when something on my watchlist lands on Netflix." Users save titles to a local watchlist, pick their streaming services, and want a nudge the day a title actually arrives.

That feature wants an account system. Passwords, sessions, email verification, password resets, the works. I really did not want to build that. Every line of auth code is a liability I have to maintain forever, and the payoff for users is typing a password into a movie site.

So I asked a different question: what's the minimum credential that makes this work? The answer turned out to be one email address and two tokens. Here's the whole design.

The insight: the confirmation link is already proof

When someone submits the waitlist form, they get a confirmation email with a token link. Clicking it proves they control that inbox. That's it. That's the entire identity system.

But the confirm token can't be the API credential. It's a link secret, meant to be clicked once and done. Syncing a watchlist needs a durable bearer credential the client sends on every edit. So confirm mints a second, separate token: a UUID sync key stored in a Redis hash keyed by email.

export const PENDING_KEY = 'gm:waitlist:pending'       // email => confirm token
export const CONFIRMED_KEY = 'gm:waitlist:confirmed'   // email => unsub token
export const SYNCKEY_KEY = 'gm:alerts:synckey'         // email => sync UUID
export const ALERTS_PREFS_KEY = 'gm:alerts:prefs'      // email => {watchlist, services, region}
export const ALERTS_NOTIFIED_KEY = 'gm:alerts:notified' // email => sent alert keys

Two credentials, two jobs. Leaking or rotating the sync key never touches the unsubscribe token, and vice versa.

Handing out the key through a URL fragment

The interesting part is delivery. The sync key has to get from the confirmation click to the user's browser without ever appearing in my server logs. Query strings get logged; fragments don't.

So the confirm endpoint 302-redirects to a status page with the credentials in the hash:

// Fragment never reaches the server on redirect follow, so the sync
// credential stays out of access logs from this point on.
const syncKey = await getOrCreateSyncKey(kv, email)
return redirect('confirmed', `email=${encodeURIComponent(email)}&key=${syncKey}`)

Which produces /email-status?status=confirmed#email=you%40x.com&key=abc-123. The status query param is logged; the fragment is not, because browsers don't send it. The page reads window.location.hash, writes {email, key} to localStorage, and the credential now exists in exactly two places: the user's browser and one Redis hash field.

Syncing without sessions

The client posts a snapshot of the watchlist and chosen providers whenever they change. Two details keep this cheap:

export async function syncAlertsNow(data, creds = getAlertsCredentials()) {
  if (!creds) return
  const payload = JSON.stringify(buildSnapshot(data))
  if (localStorage.getItem(LAST_SYNCED_KEY) === payload) return
  const ok = await postPrefs(creds, snapshot)
  if (ok) localStorage.setItem(LAST_SYNCED_KEY, payload)
}

A 4 second debounce collapses edit bursts, and the LAST_SYNCED_KEY check skips the request entirely if nothing changed since the last successful sync. Any watchlist edit re-renders the app, so without the diff check every idle re-render would fire a POST.

On the server side, POST /api/alerts-prefs validates the email and key formats, rate limits per IP and per email (30/hour each, keyed by a sha256 of the address rather than the raw email), then safeEquals the key against the hash:

const stored = await kv.hget<string>(SYNCKEY_KEY, email)
if (!stored || !safeEqual(stored, key)) {
  return res.status(403).json({ error: 'Invalid sync credentials' })
}
await kv.hset(ALERTS_PREFS_KEY, { [email]: { watchlist, services, region, updatedAt: Date.now() } })

Notice what's missing: no session, no cookie, no JWT. The sync key is just a bearer token with a 36 character format check.

The cron does the matching

A daily job diffs each tracked provider's catalog (added and coming soon lists are already computed by an earlier cron and cached). Then it loads all three hashes in three HGETALLs and walks subscribers:

for (const item of change[kind]) {
  if (!item.tmdbId || !watchlistKeys.has(`${item.tmdbType}:${item.tmdbId}`)) continue
  const notifiedKey = `${kind}:${item.tmdbType}:${item.tmdbId}@${providerKey}`
  if (notified.has(notifiedKey)) continue
  out.push({ kind, notifiedKey, tmdbId: item.tmdbId, ... })
}

Each subscriber's watchlist becomes a mediaType:id set matched against their chosen providers' diffs. The notifiedKey dedupe (added:movie:550@netflix) means nobody gets the same alert twice, and each user gets at most one email per day with up to 20 matches. The email carries a List-Unsubscribe header and a one-click link.

One subtlety: the cron reads provider diffs with fresh: true to skip the per-instance memo I added to keep pageviews cheap. A memoized diff is exactly wrong here, the whole point is "what changed today."

A second device is just a form resubmit

Syncing another device needs no new UI. If an already confirmed email resubmits the waitlist form, the server mails them an "alerts-link" URL that reissues the fragment flow on whatever device opened the email:

if (await kv.hget(CONFIRMED_KEY, email)) {
  const key = await getOrCreateSyncKey(kv, email)
  await sendLinkDeviceEmail(email, key)
  return res.status(200).json({ ok: true, pending: true })
}

Same pending: true response as a fresh signup, deliberately. Returning "you're already subscribed" would make the form an oracle for checking who's on the list.

Unsubscribing deletes everything

The unsubscribe link uses the original confirm token and wipes all five hash fields: confirmed status, pending, sync key, stored prefs, and the notified set:

await kv.hdel(CONFIRMED_KEY, email)
await kv.hdel(PENDING_KEY, email)
await kv.hdel(SYNCKEY_KEY, email)
await kv.hdel(ALERTS_PREFS_KEY, email)
await kv.hdel(ALERTS_NOTIFIED_KEY, email)

Any client still holding the sync key starts getting 403s immediately, and there's no residual data to leak.

What I gave up, honestly

This is not authentication, and I want to be straight about the limits:

Anyone with the sync key can overwrite that email's watchlist prefs. It's a write only vandalism risk bounded to preference data, not an impersonation risk. There's nothing sensitive to read back, the prefs endpoint never returns stored data.
The confirm and link endpoints skip rate limiting on purpose, because mail scanners prefetch links. The token is the auth. That trade means those endpoints are cheap GETs that do one hash lookup.
If someone loses their browser profile, the fix is resubmitting the form and getting a fresh link. Annoying, but not a support ticket.

The actual lesson

"Needs alerts" does not mean "needs accounts." If the identity proof you're already doing (email confirmation) is strong enough, a second bearer credential for the chatty sync traffic gets you the whole feature. Fragment delivery keeps it out of logs, format checks plus rate limits keep it boring, and the unsubscribe path deleting every trace keeps it honest.

Total auth surface: zero passwords, zero sessions, zero cookies. One email field and a UUID.

The site is galaxymovies.app if you want to see the flow. Sign up, confirm, and watch your browser's localStorage for gm.alerts.v1, that's the whole credential.

My side project's free tiers were dying, so I counted what each service actually bills

Thu, 08 Oct 2026 22:42:45 +0000

Galaxy Movies is a movie discovery side project ~ Next.js Pages Router on Vercel, TMDB for data, Upstash Redis for caching & rate limiting, and OpenAI for a chat assistant & generated synopses. Everything runs on free tiers, which is the whole point of a side project.

A few weeks ago all three of those free tiers started groaning at once. Vercel function usage was climbing, Upstash was burning through its daily command quota well before midnight, and OpenAI spend had a suspicious correlation with traffic spikes that produced no actual readers.

The fixes all came down to the same realization: every "free" tier bills a different unit, and I was counting the wrong things. Here's what was actually billing me, and what I changed.

Act 1: The bots were running up my function bill

Vercel bills function duration, and my movie and TV detail pages were expensive: five parallel TMDB fetches (title, watch providers, credits, ratings, recommendations), plus Redis reads for the AI content slots, all in getServerSideProps.

The expensive traffic wasn't humans. SEO crawlers and AI scrapers sweep the entire TMDB ID space in bulk, and every one of those detail pages ran the full fetch chain. They don't index anything and send zero readers. Pure cost.

The fix was a thin render path just for them:

// Bots that don't index get a minimal render. They sweep the TMDB id
// space in bulk and don't need providers, credits, videos, or AI slots.
if (isBot(ua) && !isSearchEngine(ua)) {
  const titleRes = await fetch(`https://api.themoviedb.org/3/${media}/${id}?api_key=${apiKey}`)
  // on failure return notFound or errorProps; otherwise:
  context.res.setHeader('Cache-Control', 'private, no-store')
  return { props: { ...thinProps, media, title, topCast: [] } }
}

Two details matter here:

The isSearchEngine split. isBot matches a broad allowlist, but Googlebot, Bingbot, and DuckDuckGo still get the full render since they index. Social preview bots get the thin version. Whether a bot indexes is the only question that matters.
private, no-store is critical. If the stripped page entered the shared CDN cache, a cache collision could serve the bot version to a human, or worse, to Googlebot. Cheap responses must never contaminate the real cache.

I also found robots.txt was being rendered by a Next.js page, which meant every crawler's very first request was a function invocation. It moved to a static public/robots.txt, which doubles as an enforcement layer:

User-agent: AhrefsBot
User-agent: SemrushBot
User-agent: MJ12bot
User-agent: Bytespider
User-agent: GPTBot
User-agent: ClaudeBot
User-agent: CCBot
# ...several more
Disallow: /

Yes, Disallow is an honor system, but the big commercial crawlers honor it, and they were most of the volume.

Finally, I lengthened the SSR CDN cache windows: s-maxage from 1 hour to 1 day, stale-while-revalidate from 1 day to 1 week. Repeat crawler hits on popular titles now terminate at the edge instead of running SSR again.

Act 2: Upstash bills every single Redis command

This one caught me off guard. Upstash's free tier bills per command, and a pipeline doesn't save you, because each member of a pipeline is its own billed command. My request paths fanned out into Redis calls that felt free because "Redis is fast."

The audit turned up some embarrassing finds. Cache reads on detail pages were ~97% misses, so I was paying a billed command for a null almost every time. Rate limiting cost up to three commands per check. A dataset updated once a day was being fetched again on every pageview.

The fixes, roughly in order of satisfaction:

Rate limiting became one Lua script. INCRBY plus a conditional EXPIRE plus a TTL recovery check run inside a single EVAL, billed once no matter how many redis.call()s it makes:

local count = redis.call("INCRBY", KEYS[1], ARGV[1])
if count <= tonumber(ARGV[1]) then
  redis.call("EXPIRE", KEYS[1], ARGV[2])
elseif count > tonumber(ARGV[3]) and redis.call("TTL", KEYS[1]) < 0 then
  redis.call("EXPIRE", KEYS[1], ARGV[2])
end
return count

The TTL check handles a real edge case: if a key somehow loses its expiry, a blocked client fixes it on the next attempt instead of being rate limited forever.

Check caches before paying the rate limit write. /api/prices was rate limiting requests that would have been cache hits, paying a write before doing a read. Reorder, and every cache hit is one command instead of two.

Memoize what changes daily. The streaming-changes diffs are rewritten once a day by cron but were being fetched per key on every pageview. A per instance LRU holding results for ten minutes turns repeat page loads into zero Redis commands:

const changesMemo = new LRUCache<string, Record<string, ProviderChanges>>({ max: 64, ttl: 10 * 60 * 1000 })

export async function getProviderChanges(providerKeys = [], { fresh = false } = {}) {
  const memoKey = [...providerKeys].sort().join(',')
  if (!fresh) {
    const memoized = changesMemo.get(memoKey)
    if (memoized) return memoized
  }
  // ...Redis reads, then changesMemo.set(memoKey, changes)
}

The fresh flag exists because the cron itself must never match subscribers against a diff it just replaced. Memoization that's correct most of the time is a bug with extra steps.

Batch the counters. Every HINCRBY is billed, so AI usage and analytics deltas accumulate in a Map and flush every 30 seconds (or 50 fields). Stats lag by up to half a minute and a dying instance loses its unflushed tail, a fine trade for telemetry.

Restructure data to match access patterns. Detail pages fetch both AI content slots in one MGET instead of two GETs. Generated lists moved from one key per slug into a single hash, where HGETALL is one command replacing an unbounded key fanout.

Net result: roughly half the daily command volume, with quota headroom for the first time in weeks.

Act 3: OpenAI spend, or "why is a scraper generating my content?"

The AI features on detail pages (generated synopses, similar title blurbs) trigger an OpenAI call on a cache miss. Guess who was causing cache misses at scale: the same scrapers from Act 1. Bots were literally generating my content.

So bots got read only access: they can consume AI content that's already cached but can never trigger generation (generate: false on the cache lookup). Human traffic is unaffected; scraper sweeps now cost zero tokens.

The other fixes were less dramatic but added up:

Failed cron seeds stopped retrying forever. A broken seed now records failed with an attempt counter and gives up after 3 tries, instead of burning a discover call on every daily run until the heat death of the universe.
Longer cache TTLs. Reviews and similar titles are static per title, so 365 day TTLs mean one generation per title, ever.
Prompt dieting. Similar title prompts dropped to 6 candidates with 200 character overviews; editorial prompts got explicit word budgets; structured JSON output removed the "please don't ramble" tax.
Shared chat cache. Identical chat requests (quick actions, common first questions; the bulk of traffic) now hit a Redis cache shared across instances, plus tighter limits: 10/hr per IP, 1000/day global.
Per task model control. All OpenAI calls route through one module with per task reasoning_effort: none for latency sensitive tasks, low only for the discover generator. Real token usage gets logged so I can see where spend actually goes.

The kill switch

The scariest scenario isn't gradual spend. It's a quota or billing problem silently converting every request into an error, or worse, into retry storms. Billing and auth failures (401/402, insufficient_quota) now trip a shared kill switch with a one hour cooldown:

export function isQuotaError(err: unknown): boolean {
  if (!(err instanceof OpenAI.APIError)) return false
  if (err.status === 401 || err.status === 402) return true
  const code = err.code || err.error?.code
  return code === 'insufficient_quota'
      || code === 'billing_hard_limit_reached'
      || code === 'billing_not_active'
}

While it's tripped: /api/chat returns 503 { code: 'ai_unavailable' } before spending budget, the chat widget checks /api/aiStatus on mount and hides itself entirely instead of showing an error bubble, the generators skip their calls, and the content cron skips the run without burning seed attempts, since an outage isn't a seed's fault. Crucially, ordinary 429 rate_limit_exceeded errors don't trip it; those are transient.

One deliberate choice throughout: degrade in the direction that saves money. When Redis errors on a check that protects spend, the code falls back to a per instance limiter and never fails open. An in memory limiter might be less accurate, but a Redis outage can't be used to run up my OpenAI bill.

The part where I broke things

Honest bookkeeping: the cost cuts shipped two bugs worth their own paragraph.

After moving the chat cache to Redis, identical requests started hitting on every quick action prompt, and the cache hit path returned plain JSON that the SSE client never parsed. Cache hits went from "the fast path" to "the broken path" overnight. Fix: return cache hits through the SSE stream like everything else.

And when bots stopped triggering AI generation, Lighthouse CI got caught in the crossfire. It audits the real detail pages, and its UA matched the bot list, so it was suddenly measuring the thin render. Chrome-Lighthouse went on the search engine side of the check.

Both bugs were the same shape: a filter added at the edge changed behavior for a consumer I forgot about. If your bot detection doesn't have a list of legitimate automated consumers, it will find one for you. In production. On a Sunday.

What I'd tell past me

Count the billed unit, not the abstraction. "Redis call," "function invocation," and "API request" are all wrong. It's commands, gigabyte seconds, and tokens, and the gap between what I thought I was spending and what I was billed lived entirely inside that distinction.
Segment bots by whether they index, not whether they're bots. That one boolean decided which requests deserved the expensive render, the Redis reads, and the cacheable output.
Cache at the cheapest layer that works. CDN edge > shared Redis > per instance LRU > regenerate. I had requests traversing the whole hierarchy when a static file would do (looking at you, robots.txt).
Free tier quotas are architecture constraints, not billing details. "A few Redis commands per request is fine" is a statement that only survives until you do the multiplication.
Instrument spend itself. The usage counters I added to survive the Upstash quota are now how I watch OpenAI costs. The fix for a quota crisis becomes your observability for the next one.

The site is galaxymovies.app if you want to see the thin renders in the wild. View source as a human, please; the bots are expensive enough. Happy to compare notes in the comments if you've fought the same free tier math!

Your useEffect Search Bar Has a Race Condition, and It Only Shows Up When Users Type Fast

Thu, 08 Oct 2026 12:08:17 +0000

This is one of those bugs where the code looks completely reasonable, passes every manual test you'd naturally think to run, and still ships with a real defect that only shows up under a specific, very common usage pattern: someone typing faster than your network requests resolve.

The Setup

// components/SearchBox.tsx
'use client';

export function SearchBox() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState<Result[]>([]);

  useEffect(() => {
    if (!query) {
      setResults([]);
      return;
    }

    async function fetchResults() {
      const res = await fetch(`/api/search?q=${query}`);
      const data = await res.json();
      setResults(data.results);
    }

    fetchResults();
  }, [query]);

  return (
    <div>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      <ul>
        {results.map((r) => (
          <li key={r.id}>{r.title}</li>
        ))}
      </ul>
    </div>
  );
}

Type slowly, pause between letters, and this works exactly as expected. It's also wrong in a way that's specifically invisible to that kind of careful, deliberate testing.

What Actually Breaks

Say a user types "react" quickly, letter by letter: r, re, rea, reac, react. Each keystroke triggers the effect, which fires a new fetch request for that exact partial query. These five requests are now all in flight simultaneously, and nothing about this code guarantees they resolve in the order they were sent.

Network conditions are not guaranteed to preserve request order. It's entirely possible, and in practice fairly common under real-world network jitter, for the request for "r" to resolve after the request for "react" does. When that happens, setResults(data.results) runs last for the "r" response, overwriting the correct, complete results for "react" with a handful of broad, barely-relevant matches for a single letter the user stopped looking at four keystrokes ago.

The user sees a results list that doesn't match what's sitting in the input field, with no error, no warning, nothing to indicate anything went wrong. It just looks like the search is broken or laggy, which is a uniquely frustrating kind of bug to report because it's intermittent and timing-dependent, not consistently reproducible by just repeating the same steps slowly.

Why This Specifically Survives Testing

Manual testing during development almost always involves typing at a normal, deliberate pace, often pausing to look at the screen between each change. That pace gives each request time to resolve well before the next one fires, which means the race condition's actual precondition, overlapping in-flight requests for different queries, simply never occurs during the kind of testing most developers naturally do. The bug needs genuinely fast typing, a slow or inconsistent network, or both, to reliably surface, and automated tests using scripted input often type unrealistically fast without that being the specific thing anyone's checking for.

The Fix: Ignore Stale Responses

useEffect(() => {
  if (!query) {
    setResults([]);
    return;
  }

  let ignore = false;

  async function fetchResults() {
    const res = await fetch(`/api/search?q=${query}`);
    const data = await res.json();

    if (!ignore) {
      setResults(data.results);
    }
  }

  fetchResults();

  return () => {
    ignore = true;
  };
}, [query]);

The ignore flag is set in the effect's cleanup function, which React runs right before the effect re-runs for a new query value, or when the component unmounts. Every in-flight request from a now-outdated query gets its ignore flag flipped to true the moment a newer request starts, so even if the old request resolves later, its result is silently discarded instead of overwriting the current, correct state.

A Cleaner Version With AbortController

The ignore-flag pattern works, but it still lets the outdated network request complete in the background, wasting bandwidth and a server round trip for a result nobody will ever see. AbortController actually cancels the request itself:

useEffect(() => {
  if (!query) {
    setResults([]);
    return;
  }

  const controller = new AbortController();

  async function fetchResults() {
    try {
      const res = await fetch(`/api/search?q=${query}`, {
        signal: controller.signal,
      });
      const data = await res.json();
      setResults(data.results);
    } catch (err) {
      if ((err as Error).name !== 'AbortError') {
        console.error('Search failed:', err);
      }
    }
  }

  fetchResults();

  return () => {
    controller.abort();
  };
}, [query]);

Now a stale request is actually cancelled, not just ignored, which both fixes the race condition and avoids burning server resources on searches the user has already moved past.

Where Else This Exact Pattern Bites

Any useEffect that fetches data based on a value that can change again before the fetch resolves has this same underlying issue, not just search boxes. A filter dropdown firing a new query on every change, a tab switcher loading different data per tab, pagination where a user clicks "next" rapidly, all of these share the identical race condition shape. It's the same category of timing bug I build defensively around in the dashboard and data-table components across my Next.js templates, same root cause, different trigger.

The Rule

Any effect that fetches data based on a value that can change again before the request resolves needs a way to discard or cancel the outdated response. Either an ignore flag or an AbortController, but not neither. The bug is invisible in slow, deliberate testing and reliably present the moment a real user interacts with your app faster than your network responds.

Get the templates: https://pixelanas.gumroad.com

Go check your own search boxes, filters, and tab switchers for a useEffect fetch with no cleanup-based cancellation. If you find one, try typing into it as fast as you actually can. Drop what you find in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Server Actions Don't Need CSRF Protection, API Routes Still Do, and Mixing That Up Is a Real Hole

Wed, 07 Oct 2026 12:14:06 +0000

Somewhere along the way, a lot of Next.js developers picked up the idea that "Server Actions are secure by default" and quietly generalized that into "mutations in this app are secure by default." Those are not the same statement, and the gap between them is exactly where this bug lives.

Why Server Actions Actually Are Safe From CSRF

Next.js Server Actions include built-in CSRF protection out of the box. When a Server Action is called, Next.js checks the request's Origin header against the deployment's own host, and rejects the call if it doesn't match.

// actions/update-email.ts
'use server';

export async function updateEmail(formData: FormData) {
  const newEmail = formData.get('email') as string;
  const userId = await getCurrentUserId();
  await User.findByIdAndUpdate(userId, { email: newEmail });
}

You didn't write any CSRF-handling code here, and you don't need to. Next.js's framework-level origin check means a malicious site trying to trigger this action from a hidden form or script on a different domain gets rejected before your function body ever runs. This protection is real, and it's one of the genuinely nice defaults Server Actions give you for free.

Where the Same Confidence Quietly Stops Applying

The problem shows up the moment the same app also has API routes doing equivalent mutations, which is extremely common, Server Actions for your own forms, API routes for anything that needs to be called from outside, a mobile app, a webhook, a public integration.

// app/api/users/update-email/route.ts
export async function POST(request: Request) {
  const { email, userId } = await request.json();

  // No origin check here. Nothing here is Next.js's built-in CSRF protection,
  // because that protection is specific to Server Actions, not API routes.
  await User.findByIdAndUpdate(userId, { email });

  return Response.json({ success: true });
}

This route has no framework-provided CSRF protection at all. If it relies on a cookie-based session to identify the user rather than a token the calling code must explicitly attach, a malicious page on a completely different domain can trigger a request to this endpoint using the victim's own browser, which will happily attach their existing session cookie, and the server has no way to tell this request apart from a legitimate one made from your own app.

<!-- On attacker-controlled-site.com -->
<form action="https://yourapp.com/api/users/update-email" method="POST">
  <input type="hidden" name="email" value="*Emails are not allowed*" />
</form>
<script>document.forms[0].submit();</script>

If a logged-in victim visits that page, their browser submits this form to your real API route, cookies and all, and your route processes it as if it came from your own frontend, because nothing in that route checks otherwise.

Why This Specifically Gets Missed

The mental model "Next.js handles CSRF" is correct for exactly one surface, Server Actions, and developers reasonably extend it to the whole app because the framework genuinely did remove the need to think about this for the most common mutation path. API routes feel like the same kind of thing, same app, same auth system, same database calls, so the assumption carries over even though the actual protection mechanism does not.

This also tends to get reinforced by testing, since every normal test of the API route happens from your own frontend, on your own origin, which is exactly the traffic pattern that looks identical whether or not CSRF protection exists.

The Fix: Treat API Routes as Needing Their Own Explicit Protection

If an API route is meant to only ever be called from your own frontend, verify the origin explicitly, the same check Server Actions do for you automatically:

// app/api/users/update-email/route.ts
function isSameOrigin(request: Request): boolean {
  const origin = request.headers.get('origin');
  const host = request.headers.get('host');
  if (!origin) return false;
  return new URL(origin).host === host;
}

export async function POST(request: Request) {
  if (!isSameOrigin(request)) {
    return Response.json({ error: 'Invalid origin' }, { status: 403 });
  }

  const { email, userId } = await request.json();
  await User.findByIdAndUpdate(userId, { email });
  return Response.json({ success: true });
}

If the route genuinely needs to be called from outside your own frontend, don't rely on cookie-based session auth for it at all. Use an explicit bearer token or API key that an attacker's page has no way to attach automatically, which is the actual reason CSRF doesn't apply to most token-based API authentication in the first place, the browser doesn't auto-include a header a malicious page doesn't know the value of.

The Rule

"Next.js handles CSRF" is true for Server Actions specifically, not for every mutation path in your app. Any API route that mutates data and relies on cookie-based auth needs its own explicit protection, either an origin check or a move away from cookies toward an explicit token for that specific route.

I keep this distinction explicit in the auth layer of my Next.js dashboard templates, where Server Actions and API routes sit side by side and get treated very differently for exactly this reason. You can see the broader portfolio of templates and projects this pattern comes from at pixelanas.com.

Get the templates: https://pixelanas.gumroad.com

Go check your own API routes for anything that mutates data using cookie session auth with no origin check. If you find one, this is worth closing today. Drop what you find in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

AudioFlow- STT and TTS tool

Wed, 07 Oct 2026 06:52:22 +0000

Welcome to AudioFlow in this app i created 2 simple ai tools that u can use in daily life

Voise to Text (STT)
Text to Voise (TTS)

This project is completely open-source so u can re-use this tools for your any kind of chatbot project

features of this app

Real-time audio streaming using web-socket
Reactive waveform which improve UX
Keeps Audio and Transaction history in local-storage

How to use this app ?
both tools are use Gemini models so u need to provide an api key it free generous tier for you personal use and it safely stored in local storage.

Live Demo: website-link
GitHub Repository: repo-link
Video Demo: video-link

Why Your Pages Get Indexed But Never Rank

Tue, 06 Oct 2026 13:47:23 +0000

Why Your Pages Get Indexed But Never Rank

You check Google Search Console. Your page is indexed. Google crawled it, read it, and added it to the index without any errors. You search your exact keyword anyway, and your page is nowhere to be found, not on page one, not on page five, sometimes not anywhere in the first several pages of results.

This confuses a lot of site owners, because it feels like being indexed should mean you are now in the running. It does not. Indexing and ranking are two separate stages, and most of the disappointment around "my SEO isn't working" actually comes from mixing the two up.

Indexing Just Means Google Knows Your Page Exists

Being indexed means Google has crawled your page, processed its content, and stored it in the enormous database it uses to serve search results. That's it. It is a prerequisite for ranking, not a form of ranking itself.

Think of indexing as being added to a library's card catalog. Being in the catalog means a librarian could theoretically hand your book to someone. It says nothing about whether your book ends up on the recommended shelf at the front of the store or buried in the back where nobody browses.

Ranking Is a Completely Different Competition

Once a page is indexed, it enters a separate process every time someone searches a related query. Google compares your page against every other indexed page that might answer that same query, and ranks them by its own assessment of relevance, authority, and user experience.

This is where the real competition happens, and it is a competition against pages that may have been building relevance and authority for years. A new page being indexed just means it is now eligible to enter that competition. It says nothing about where it finishes.

The Most Common Reasons Indexed Pages Don't Rank

Weak or thin content for the query. If your page technically covers a topic in 300 words while top-ranking competitors cover it in 1,500 with examples, data, and clear structure, Google has little reason to consider your page the best answer, even though it is a valid one.

No backlinks or topical authority. Google weighs how many other credible sites link to a page, and how authoritative your site is on that general subject, as part of ranking relevance. A brand new site with no external signals pointing to it is starting the competition from zero, regardless of content quality.

Keyword mismatch with actual search intent. A page optimized around a keyword's literal wording, but written for a different intent than what people actually want when they type that phrase, loses to pages that better match what searchers are really looking for. If you're unsure how your pages actually line up with real search terms, that's exactly what Google Search Console's Performance report is for.

Internal linking gaps. A page that nothing else on your site links to sends a weak signal about its importance relative to your other content. If you want to understand how this fits into a broader technical setup, we covered it in our technical SEO guide for non-developers.

Direct competition from stronger, older pages. Sometimes the honest answer is simply that the top results for a query are well-established, well-linked, and well-written, and a new page needs time and continued improvement to realistically compete, not a quick fix.

What Actually Moves a Page From Indexed to Ranking

There is no single switch to flip here, which is exactly why some SEO advice overpromises results it cannot actually guarantee. What consistently helps is making the page a genuinely better answer to the query than what currently ranks: covering the topic more thoroughly, answering the follow-up questions a reader would naturally have, structuring content with clear headings that match how people scan a page, and linking it naturally from other relevant pages on your own site.

Patience is also a real factor. Even a page that deserves to rank well can take weeks or months to climb, as Google continues to evaluate it against real user behavior and against changes other competing pages are making in the same window of time.

Frequently Asked Questions

How long does it take an indexed page to start ranking?

There's no fixed timeline. Some pages see movement within weeks, others take several months, depending on competition, content quality, and how established your site already is.

Does more content automatically rank higher?

No. Length alone isn't a ranking factor. What matters is whether the page thoroughly and clearly answers what the searcher actually wants, which sometimes takes more words and sometimes doesn't.

Can a page be indexed and then dropped from the index later?

Yes. Pages can be removed from the index if they're deleted, blocked via robots.txt, marked noindex, or if Google reassesses them as low value over time.

Is it possible to guarantee a page will rank for a specific keyword?

No legitimate SEO practice can guarantee a specific ranking position. Anyone promising that is selling something they can't actually control, since Google's ranking decisions are made algorithmically and are never contractually guaranteed to anyone.

Conclusion

Getting indexed is the easy part. Ranking well is an ongoing process of making your page a genuinely stronger answer than the competition, backed by real structure, real depth, and real signals pointing to it from elsewhere. There's no guaranteed shortcut to the top of the results, but understanding the difference between these two stages at least means you're troubleshooting the right problem instead of wondering why "indexed" didn't already mean "ranked."

Want a second opinion on why a specific page isn't ranking the way you expected? Get in touch.

Anas, full-stack Next.js developer building SaaS products and premium templates.

placeholder="blur" on a Next.js Image Silently Does Nothing If You Forget One Thing

Sun, 04 Oct 2026 13:33:12 +0000

placeholder="blur" is one of those props that works perfectly the first time you try it, in a quick example with a locally imported image, and then quietly stops doing anything the moment you swap that example for a real image coming from a CMS, S3, or any other remote source.

The Example That Works, and Why It Works

import heroImage from '@/public/hero.jpg'; // a static, local import

<Image src={heroImage} alt="Hero" placeholder="blur" />

This works because a statically imported image is processed at build time, and Next.js automatically generates a tiny, blurred base64 placeholder from the actual image's real content during that build step. You get a genuine, accurate blur preview with zero extra configuration, because the framework has direct, build-time access to the actual image file.

Where It Silently Stops Working

// A product image coming from your CMS or a database field
<Image src={product.imageUrl} alt={product.name} placeholder="blur" />

product.imageUrl is a remote URL, a string, not a statically imported file. Next.js has no way to generate a blur placeholder from a URL at build time, since the actual image content isn't available until runtime, when the page is actually being requested, not when the project is built. Without a manually provided blurDataURL prop, placeholder="blur" on a remote image source simply has nothing to use, and the image renders without a placeholder at all, exactly as if the prop had never been added.

Why This Doesn't Throw an Error

This is genuinely a silent no-op, not a crash, which is exactly what makes it easy to miss. The prop exists, the code runs, the page renders, the image loads, just without the blur transition anyone added placeholder="blur" specifically to get. Nothing in the console points at the actual gap, since from Next.js's perspective, nothing is actually wrong, you simply didn't provide the one piece of data the feature needs for a remote source.

The Fix: Provide blurDataURL Explicitly for Remote Images

<Image
  src={product.imageUrl}
  alt={product.name}
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRg..." // a real, small base64 placeholder
/>

For this to genuinely work, you need an actual base64-encoded placeholder, generated from the real image, not a generic, unrelated blur applied to every image regardless of its actual content. A common approach is generating and storing this placeholder at the time an image is uploaded, saving it alongside the image URL itself in your database, so it's already available whenever the image needs to render, without a separate runtime computation on every single page load.

// A simplified example of generating a blur placeholder at upload time
import { getPlaiceholder } from 'plaiceholder';

async function generateBlurPlaceholder(imageUrl: string) {
  const buffer = await fetch(imageUrl).then((res) => res.arrayBuffer());
  const { base64 } = await getPlaiceholder(Buffer.from(buffer));
  return base64; // store this alongside the image URL in your database
}

Libraries like plaiceholder exist specifically for this, generating a real, accurate blur placeholder from any image buffer, which you can then store once and reuse on every subsequent render, rather than regenerating it on the fly.

A Cheaper Fallback When a Real Placeholder Isn't Worth the Effort

For cases where generating and storing a genuine per-image placeholder is more infrastructure than the project needs, a generic, static color placeholder is still better than silently getting nothing:

<Image
  src={product.imageUrl}
  alt={product.name}
  placeholder="blur"
  blurDataURL="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxIiBoZWlnaHQ9IjEiPjxyZWN0IHdpZHRoPSIxIiBoZWlnaHQ9IjEiIGZpbGw9IiNlNWU3ZWIiLz48L3N2Zz4="
/>

This is a tiny, solid-color SVG, decoded, just a single gray rectangle, which still gives a smoother loading transition than nothing, even though it isn't a real, content-matched blur of the actual image. Not as polished as a genuine per-image placeholder, genuinely better than the silent no-op most remote images end up with by default.

How to Check if This Is Happening on Your Own Site

Search for placeholder="blur" across your codebase and check, for each match, whether the src is a static import or a remote URL. Any remote src without an accompanying blurDataURL prop is this exact gap, the prop is present, and doing nothing.

grep -B2 -A2 'placeholder="blur"' --include="*.tsx" -r .

The Actual Rule

placeholder="blur" only works automatically for statically imported images. Any remote image source needs an explicit blurDataURL, generated from the real image content, or the prop silently does nothing rather than failing loudly. Generating and storing that placeholder once, at upload time, is the more complete fix. A generic, static color placeholder is a reasonable, low-effort fallback when a real one isn't worth the infrastructure for a given project.

I handle this exact pattern, generating and storing real blur placeholders at upload time, across the dashboards and templates I build at pixelanas.com, and I've covered related image and performance patterns on the blog too.

If you're using placeholder="blur" anywhere with a remote image source, check whether blurDataURL is actually present. If it's not, the prop has been doing nothing this whole time. Drop what you find in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Your Zod Schema's .optional() Might Be Silently Rejecting Valid Data From MongoDB

Sat, 03 Oct 2026 21:14:32 +0000

This one trips people up specifically because the two words feel interchangeable in everyday English, "optional" and "nullable" both sound like "this might not be there," and Zod treats them as two genuinely distinct, non-overlapping conditions.

What Each One Actually Validates

import { z } from 'zod';

const Schema = z.object({
  bio: z.string().optional(), // allows the key to be MISSING, or a string. Does NOT allow null.
  avatar: z.string().nullable(), // requires the key to be PRESENT, as a string OR null. Rejects missing.
});

.optional() accepts undefined, meaning the field can be genuinely absent from the object entirely, but if it's present, it must match the base type, never null. .nullable() accepts null specifically, but the key itself still needs to actually be present in the object, just potentially holding the value null rather than a real value. These aren't two flavors of the same leniency, they're validating two different, non-overlapping conditions, and passing the wrong kind of absence to either one fails validation.

Where This Actually Breaks With MongoDB Specifically

MongoDB documents very commonly store an explicit null for a field that has no value, rather than omitting the key entirely, especially for fields that were part of the original schema design but just haven't been set for a given document yet.

// A real document from MongoDB
{
  _id: '...',
  name: 'Alex',
  bio: null, // explicitly null, not missing
}

// ❌ This schema expects the key to be absent, not present-and-null
const UserSchema = z.object({
  name: z.string(),
  bio: z.string().optional(),
});

UserSchema.safeParse(userFromDb); // fails: bio received null, optional() doesn't accept null

bio: null is a completely valid, common shape coming straight out of MongoDB, and .optional() rejects it anyway, since .optional() only ever expected undefined, never null. The validation failure here isn't catching a real data problem, it's a mismatch between what Zod's .optional() actually means and what the developer assumed it meant when writing the schema against real database output.

The Fix: Match the Schema to What the Data Actually Does

const UserSchema = z.object({
  name: z.string(),
  bio: z.string().nullable(), // correctly matches MongoDB's explicit null
});

For a field that MongoDB stores as explicit null when empty, .nullable() is the correct validator, not .optional(). If a field could genuinely be either missing entirely or explicitly null, both conditions need to be allowed together:

bio: z.string().nullable().optional(), // accepts a string, null, OR a missing key

Chaining both is completely valid and often the most accurate reflection of real-world data that's passed through several code paths, some of which omit the key, others of which explicitly set it to null.

Why This Doesn't Show Up Until Real Data Hits It

A schema tested only against hand-written test objects during development, where the developer naturally omits fields they don't care about rather than explicitly setting them to null, never actually exercises this gap. The validation failure only shows up once real documents, containing MongoDB's genuine, common pattern of explicit null values, flow through the same schema, often well after the schema was written and seemingly working correctly.

A Quick Way to Check Which One You Actually Need

Query a real, representative document from your actual collection and look at the field in question directly. If it shows up as null in the raw document, you need .nullable(). If the key is genuinely absent from documents where it has no value, you need .optional(). Guessing based on the field's name or what "feels right" is exactly how this mismatch gets introduced in the first place, checking the real data removes the ambiguity entirely.

const doc = await User.findOne({}).lean();
console.log(Object.keys(doc).includes('bio'), doc.bio);
// If bio is a key with value null → nullable()
// If bio is simply absent as a key → optional()

The Actual Rule

.optional() and .nullable() are not interchangeable leniency settings, they validate two distinct, specific shapes of absence, and MongoDB's own default behavior of storing explicit null means .nullable() is very often the one you actually need for fields coming straight out of a database, not .optional(), even though "optional" is the word that intuitively comes to mind first. When a schema seems to be rejecting data that looks completely fine in your database, this mismatch is one of the first things worth checking.

I ran into exactly this building the MongoDB-backed dashboards covered in the MongoDB patterns I use in every Next.js project, and it's one of those small schema details worth getting right once rather than re-discovering on every new project.

If a Zod schema is rejecting data that looks completely valid sitting in your actual database, check whether it's this exact .optional() versus .nullable() mismatch before assuming the data itself is somehow wrong. Drop what you find in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Your Server Component Might Be Fetching Data Three Times Slower Than It Needs To

Fri, 02 Oct 2026 18:05:04 +0000

This is one of the easiest performance mistakes to write without noticing, since the code reads completely naturally, top to bottom, each line waiting for the one before it to finish, exactly the way most people learn to write async code in the first place.

The Setup That Reads Perfectly Naturally

// app/dashboard/page.tsx
export default async function DashboardPage() {
  const user = await getUser();
  const posts = await getPosts();
  const comments = await getComments();
  const analytics = await getAnalytics();

  return (
    <Dashboard
      user={user}
      posts={posts}
      comments={comments}
      analytics={analytics}
    />
  );
}

Four await calls, one after another. Clean, readable, and exactly how sequential code naturally gets written when each line is just "get the next thing I need." The problem is that none of these four calls actually depend on the results of the others, getPosts doesn't need anything from getUser, getComments doesn't need anything from getPosts, and so on. They're all independently fetchable at the same time, and writing them sequentially means the total page load time is the sum of all four, not the time of the single slowest one.

Why This Costs More Than It Looks Like It Should

If each of these four calls takes roughly 150 milliseconds, a genuinely reasonable time for a real database query, the sequential version takes roughly 600 milliseconds total, each one waiting for the previous one to fully complete before even starting. Run the same four calls concurrently instead, and the total time is roughly 150 milliseconds, the time of the single slowest call, since they're all genuinely happening at once rather than queued up one behind another for no actual reason.

This is a real, measurable difference on a page real users are waiting for, and it's entirely avoidable, since nothing about these four pieces of data actually requires this sequential order, the code just happens to be written in a shape that imposes one anyway.

The Actual Fix: Promise.all for Independent Fetches

export default async function DashboardPage() {
  const [user, posts, comments, analytics] = await Promise.all([
    getUser(),
    getPosts(),
    getComments(),
    getAnalytics(),
  ]);

  return (
    <Dashboard
      user={user}
      posts={posts}
      comments={comments}
      analytics={analytics}
    />
  );
}

Promise.all starts all four requests essentially simultaneously and waits for all of them to complete together, rather than starting each one only after the last one finished. Same data, same final render, a fraction of the total wait, purely by removing an ordering constraint that was never actually necessary in the first place.

Where This Gets Genuinely Trickier: Partial Dependencies

Not every case is this clean. Sometimes one piece of data genuinely depends on another, and mixing dependent and independent fetches needs a bit more care than a single flat Promise.all.

// ❌ Everything sequential, even though posts and analytics don't need each other
export default async function DashboardPage() {
  const user = await getUser();
  const posts = await getPostsForUser(user.id); // genuinely depends on user
  const analytics = await getAnalytics(); // does NOT depend on user at all
  return <Dashboard user={user} posts={posts} analytics={analytics} />;
}

// ✅ Only the genuine dependency stays sequential, everything else runs alongside it
export default async function DashboardPage() {
  const analyticsPromise = getAnalytics(); // starts immediately, not awaited yet

  const user = await getUser();
  const posts = await getPostsForUser(user.id); // genuinely needs user.id first

  const analytics = await analyticsPromise; // was already running this whole time

  return <Dashboard user={user} posts={posts} analytics={analytics} />;
}

Starting getAnalytics() without immediately awaiting it lets that request begin running in the background while getUser and getPostsForUser proceed through their genuine, necessary sequence. By the time the code actually needs the analytics result, it's very likely already finished, or at least has been running the whole time instead of only starting after everything else completed.

How to Actually Spot This in Your Own Code

Look for multiple await statements in a row where each one calls a genuinely independent function, nothing on the left side of an earlier line appears as an argument to a later one. That absence of a real data dependency is the signal, these calls have no actual reason to be sequential, and wrapping them in Promise.all is very likely a free, meaningful performance improvement with zero behavior change.

grep -B2 -A2 "await get" app/**/page.tsx

Scanning for clusters of consecutive await calls to different functions, then checking whether any of them genuinely reference the previous line's result, is a quick, practical way to find real waterfall candidates across an existing codebase.

Why This Matters More on Pages With Several Independent Data Sources

A dashboard, a page with several distinct widgets or sections each backed by their own query, is exactly where this pattern accumulates the most cost, since it's common to have four, five, or more genuinely independent pieces of data feeding one page, each one innocently written as its own await line, each one adding its full latency on top of all the others instead of overlapping.

The Actual Rule

Before awaiting multiple async calls sequentially, check whether any of them genuinely need a previous call's result. If none do, Promise.all turns their combined wait time from a sum into a maximum, for free, with no behavior change. For a genuine mix of dependent and independent calls, start the independent ones early without immediately awaiting them, so they run in the background while the real, necessary sequence proceeds.

I check every Server Component I write for exactly this pattern now, across client work and the dashboards and templates I build at pixelanas.com, since it's one of the highest-value, lowest-effort performance fixes available, and I've written about related data-fetching patterns on the blog too.

Go check your own dashboard or any data-heavy page for consecutive await calls with no genuine dependency between them. If you find some, wrapping them in Promise.all is very likely a free win sitting right there. Drop what you find in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Next.js PostgreSQL: Build a Complete Full Stack Application

Fri, 02 Oct 2026 15:53:08 +0000

Building a modern full stack application is about much more than creating attractive user interfaces. A successful application needs a reliable frontend, a powerful backend, secure authentication, efficient database management, and a smooth user experience.

Among the many technologies available today, Next.js and PostgreSQL provide a powerful combination for building scalable, maintainable, and production-ready web applications.

Next.js offers a modern React-based framework with server-side rendering, routing, server components, and backend capabilities. PostgreSQL provides a reliable relational database for storing, managing, and retrieving structured information.

When these technologies work together, developers can create applications such as task management platforms, project management dashboards, ecommerce systems, customer relationship management tools, and SaaS products.

In this article, we will explore how to build a complete full stack application using Next.js and PostgreSQL, covering architecture, database design, authentication, CRUD operations, API development, security, testing, and deployment.

The goal is not simply to make an application work. It is to understand how different parts of a real-world software system communicate with one another.

1. Understanding the Technology Stack

Before starting development, it is important to understand the responsibilities of each technology.

What Is Next.js?

Next.js is a React framework designed for building modern web applications. It provides several features that simplify frontend and backend development.

Important features include:

File-based routing
Server Components
Client Components
Server-side rendering
Static site generation
API route handlers
Server Actions
Image optimization
Built-in performance improvements

One of the biggest advantages of Next.js is that developers can build frontend interfaces and server-side functionality within a single project.

Instead of maintaining completely separate frontend and backend repositories for every application, developers can organize much of the application logic in one codebase.

What Is PostgreSQL

PostgreSQL is an open-source relational database management system known for reliability, data integrity, and advanced querying capabilities.

It supports:

Relational tables
Primary and foreign keys
Transactions
Indexing
Complex SQL queries
JSON and JSONB data
Constraints
Database relationships

For applications involving users, products, orders, tasks, payments, or business records, PostgreSQL offers a structured way to manage information.

Why Combine Next.js and PostgreSQL

The combination provides a clear separation of responsibilities.

Next.js handles the user interface, application routing, and server-side logic, while PostgreSQL manages persistent application data.

A typical architecture looks like this:

User → Next.js Frontend → Server Logic → PostgreSQL Database

When a user creates a task, for example, the frontend sends the information to the server. The server validates the request, checks authorization, and executes a database operation. PostgreSQL stores the task, and the application returns the updated information to the user.

This architecture is suitable for applications that need reliable data handling and room for future growth.

2. Planning the Application Before Coding

Let's build a practical project: a Task Management Application.

Users will be able to register, log in, create tasks, update task details, mark tasks as completed, and delete records.

Core Features

Our application will include:

User registration and login
Secure authentication
Personal task dashboard
Create, read, update, and delete operations
Task status management
PostgreSQL database integration
Form validation
Responsive design
Error handling
Production deployment

Planning these features before writing code helps prevent unnecessary complexity.

It also allows us to identify the database tables, relationships, routes, and security requirements early.

3. Setting Up the Next.js Project

First, ensure that Node.js and npm are installed.

Create a new Next.js application using:

npx create-next-app@latest next-postgres-app

During setup, choose TypeScript, ESLint, Tailwind CSS, and the App Router.

Move into the project directory:

cd next-postgres-app

Start the development server:

npm run dev

Open the application in your browser:

http://localhost:3000

You should now see the default Next.js application.

Recommended Project Structure

A clean folder structure makes a full stack project easier to maintain.

next-postgres-app/
│
├── app/
│   ├── dashboard/
│   │   └── page.tsx
│   ├── login/
│   │   └── page.tsx
│   ├── register/
│   │   └── page.tsx
│   ├── api/
│   │   └── tasks/
│   │       └── route.ts
│   ├── layout.tsx
│   └── page.tsx
│
├── components/
│   ├── Navbar.tsx
│   ├── TaskForm.tsx
│   └── TaskList.tsx
│
├── lib/
│   ├── db.ts
│   └── auth.ts
│
├── prisma/
│   └── schema.prisma
│
├── public/
├── .env
└── package.json

This structure separates pages, reusable components, database utilities, and application logic.

4. Connecting PostgreSQL to Next.js

There are several ways to connect PostgreSQL to a Next.js application.

Developers can use:

Prisma ORM
Drizzle ORM
node-postgres (pg)
Raw SQL queries

For this tutorial, we will use Prisma because it provides schema management, type-safe database queries, and migration support.

Install Prisma:

npm install prisma @prisma/client

Initialize Prisma:

npx prisma init

This creates a Prisma configuration and schema file.

Configure the Database Connection

Inside the .env file, define your PostgreSQL connection string:

DATABASE_URL="postgresql://postgres:password@localhost:5432/taskdb"

Replace the username, password, host, and database name with your actual PostgreSQL configuration.

Never commit real database credentials to a public GitHub repository.

For production, use environment variables supplied by your hosting provider.

5. Designing the PostgreSQL Database

Database design is one of the most important parts of full stack development.

A poorly structured database can create duplicate records, inconsistent information, and difficult queries.

For our application, we need two primary entities:

User
Task

Each user can have multiple tasks, but each task belongs to one user.

This is a one-to-many relationship.

Prisma Database Schema

Open prisma/schema.prisma and define the models:

model User {
  id        Int      @id @default(autoincrement())
  name      String
  email     String   @unique
  password  String
  tasks     Task[]
  createdAt DateTime @default(now())
}

model Task {
  id          Int      @id @default(autoincrement())
  title       String
  description String?
  completed   Boolean  @default(false)
  userId      Int
  user        User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  createdAt   DateTime @default(now())
}

The User model stores account information, while the Task model stores task details.

The userId field connects each task to its owner.

The unique constraint on email prevents multiple accounts from using the same email address.

The cascade delete behavior ensures that associated tasks are removed when their user record is deleted. In an actual production system, account deletion policies should be designed carefully.

Run the Database Migration

Execute:

npx prisma migrate dev --name init

Generate the Prisma Client:

npx prisma generate

Your database tables are now ready.

6. Creating a Reusable Database Client

Instead of creating a new database connection in every file, we can create a reusable Prisma client.

Inside lib/db.ts:

import { PrismaClient } from "@prisma/client";

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const prisma =
  globalForPrisma.prisma ?? new PrismaClient();

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = prisma;
}

This pattern helps prevent unnecessary Prisma client instances during development hot reloads.

It is especially useful when building applications with multiple server-side modules.

7. Building the First User Interface

Now let's create a simple homepage.

Inside app/page.tsx:

export default function Home() {
  return (
    <main className="min-h-screen flex flex-col items-center justify-center">
      <h1 className="text-4xl font-bold">
        Task Management App
      </h1>

      <p className="mt-4 text-gray-600">
        Organize your work and manage your daily tasks.
      </p>

      <a
        href="/dashboard"
        className="mt-6 rounded bg-blue-600 px-6 py-3 text-white"
      >
        Open Dashboard
      </a>
    </main>
  );
}

This creates a basic landing page.

In a production application, we could expand it with navigation, authentication links, feature descriptions, and responsive layouts.

A useful principle is to keep reusable UI elements inside the components directory instead of repeating the same code across multiple pages.

8. Implementing CRUD Operations

CRUD stands for:

Create
Read
Update
Delete

These operations form the foundation of many database-driven applications.

Let's implement them using Next.js Route Handlers and Prisma.

Create a Task API

Create app/api/tasks/route.ts.

import { NextResponse } from "next/server";
import { prisma } from "@/lib/db";

export async function GET() {
  try {
    const tasks = await prisma.task.findMany({
      orderBy: {
        createdAt: "desc",
      },
    });

    return NextResponse.json(tasks);
  } catch {
    return NextResponse.json(
      { error: "Failed to fetch tasks" },
      { status: 500 }
    );
  }
}

export async function POST(request: Request) {
  try {
    const body = await request.json();

    if (
      typeof body.title !== "string" ||
      !body.title.trim()
    ) {
      return NextResponse.json(
        { error: "A valid title is required" },
        { status: 400 }
      );
    }

    const task = await prisma.task.create({
      data: {
        title: body.title.trim(),
        description: body.description ?? null,
        userId: 1,
      },
    });

    return NextResponse.json(task, { status: 201 });
  } catch {
    return NextResponse.json(
      { error: "Failed to create task" },
      { status: 500 }
    );
  }
}

This demonstrates how the frontend communicates with the database through a server-side endpoint.

The userId: 1 value is only a temporary development placeholder. A real application must obtain the authenticated user's ID from a verified server-side session and authorize every operation.

Reading Tasks

The GET handler retrieves tasks from PostgreSQL.

The orderBy option sorts tasks by creation date, placing the newest records first.

For a real multi-user application, the query should filter by the authenticated user's ID.

Updating a Task

A PATCH endpoint can update an existing task.

const updatedTask = await prisma.task.update({
  where: {
    id: taskId,
  },
  data: {
    completed: true,
  },
});

The application should validate the task ID and verify that the authenticated user owns the task before updating it.

Deleting a Task

Prisma provides a simple deletion method:

await prisma.task.delete({
  where: {
    id: taskId,
  },
});

In a production system, authorization checks are essential to prevent users from deleting other users' data.

9. Building the Frontend Dashboard

A dashboard is where users interact with application data.

A useful task dashboard should provide:

A task creation form
A list of existing tasks
Completion indicators
Edit and delete buttons
Loading states
Error messages
Empty-state guidance

The interface should remain understandable even when the database is empty or a request fails.

For example, instead of showing a blank screen, display:

"No tasks yet. Create your first task to get started."

This small detail improves usability.

Example React Component

"use client";

import { useState } from "react";

export default function TaskForm() {
  const [title, setTitle] = useState("");
  const [loading, setLoading] = useState(false);

  async function handleSubmit(
    event: React.FormEvent<HTMLFormElement>
  ) {
    event.preventDefault();

    if (!title.trim()) return;

    setLoading(true);

    try {
      const response = await fetch("/api/tasks", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ title }),
      });

      if (!response.ok) {
        throw new Error("Unable to create task");
      }

      setTitle("");
    } catch (error) {
      console.error(error);
    } finally {
      setLoading(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={title}
        onChange={(event) => setTitle(event.target.value)}
        placeholder="Enter task title"
      />

      <button disabled={loading}>
        {loading ? "Saving..." : "Add Task"}
      </button>
    </form>
  );
}

This component demonstrates controlled form input, asynchronous requests, and loading-state management.

A complete dashboard would also refresh its task list after a successful submission.

10. Implementing Authentication

Authentication is a critical part of applications that store personal information.

Users should only be able to access their own records.

A typical authentication workflow includes:

User registration
Password validation
Secure password hashing
Login verification
Session creation
Protected routes
Logout functionality

Passwords must never be stored as plain text.

Use a password hashing algorithm such as Argon2id or bcrypt.

For a production application, a maintained authentication solution such as Auth.js can help manage sessions and authentication flows.

Protecting User Data

Authentication alone is not enough.

Every database operation should check authorization.

For example:

const tasks = await prisma.task.findMany({
  where: {
    userId: authenticatedUser.id,
  },
});

This ensures that the query retrieves records associated with the authenticated account.

The server must derive authenticatedUser.id from a verified session, not from a user-controlled request body.

This distinction is essential for preventing insecure direct object reference vulnerabilities.

11. Form Validation and Error Handling

Users do not always submit valid information.

They may leave fields empty, enter incorrect values, or submit unexpected data.

A robust application should validate data on both the client and server.

Libraries such as Zod can help define reusable validation schemas.

Example:

import { z } from "zod";

export const taskSchema = z.object({
  title: z.string().trim().min(1).max(120),
  description: z.string().max(1000).optional(),
});

The server should validate incoming data before interacting with PostgreSQL.

Good error handling should also distinguish between:

Invalid user input
Authentication failures
Authorization failures
Missing records
Database errors
Unexpected server failures

Avoid returning raw database errors or sensitive implementation details to users.

12. Improving Database Performance

As an application grows, database performance becomes increasingly important.

A query that works perfectly with 20 records may become slow with 200,000 records.

Several techniques can improve performance.

Indexing

PostgreSQL indexes help speed up queries that frequently filter or sort by particular fields.

For example, if the application frequently retrieves tasks by user ID, an index on userId may help.

CREATE INDEX idx_tasks_user_id
ON "Task" ("userId");

Indexes improve some read operations but introduce storage and write overhead, so they should be selected based on actual query patterns.

Pagination

Avoid loading thousands of records at once.

Instead, implement pagination.

For example:

const tasks = await prisma.task.findMany({
  skip: 0,
  take: 20,
  orderBy: {
    createdAt: "desc",
  },
});

For large datasets, cursor-based pagination can provide more consistent performance.

Connection Pooling

Production applications may handle many simultaneous requests.

Database connection pooling helps control the number of active connections and avoid exhausting PostgreSQL resources.

The appropriate pooling strategy depends on the deployment platform and database provider.

13. Testing the Application

Testing is not an optional step in professional development.

It helps identify problems before users encounter them.

A complete testing strategy can include:

Unit Testing: Test individual functions, validation rules, and utility logic.

Integration Testing: Verify that API routes interact correctly with PostgreSQL.

End-to-End Testing: Simulate user journeys such as registration, login, task creation, and deletion.

Tools such as Vitest, Jest, and Playwright can support these workflows.

Important scenarios to test include:

Creating a task with valid information
Rejecting an empty title
Preventing unauthorized access
Updating an existing task
Handling a missing task
Displaying errors when the database is unavailable

Testing helps make future code changes safer and easier.

14. Deploying the Application

After completing development and testing, the next step is deployment.

A common deployment setup includes:

Next.js application hosted on Vercel
PostgreSQL hosted on a managed database platform
Environment variables configured securely
Database migrations applied during deployment

Before deploying, verify:

Production database credentials are configured.
Authentication secrets are secure.
Database migrations have been applied.
Sensitive environment files are excluded from Git.
Error handling is configured.
The application builds successfully.
Database backups are available.

For production migrations, use the appropriate deployment migration command, such as:

npx prisma migrate deploy

Do not use development migration workflows against a live production database.

After deployment, monitor application logs, database performance, and error rates.

15. Common Challenges Developers Face

Even with modern tools, full stack development involves challenges.

Database Connection Errors

Incorrect credentials, unavailable database servers, or connection limits can cause failures.

Always verify environment configuration and database connectivity.

Authentication Problems

Improper session validation can expose private information.

Use established authentication libraries and enforce authorization on the server.

Slow Queries

Unoptimized database queries can affect response times.

Use query analysis, appropriate indexes, pagination, and efficient data retrieval.

Frontend and Backend Mismatches

The frontend may expect a different response structure than the backend provides.

TypeScript types, validation schemas, and consistent API contracts help reduce these problems.

Deployment Differences

An application that works locally may fail in production because of missing environment variables, migration issues, or incompatible runtime configuration.

Testing the production build before deployment helps identify these issues earlier.

16. How to Extend This Project

Once the basic task management application is complete, developers can add more advanced features.

Role-Based Access Control

Introduce roles such as administrator, manager, and standard user.

Each role can have different permissions.

File Uploads

Allow users to attach documents or images to tasks using an object storage service.

Real-Time Updates

Use WebSockets or a suitable real-time service to synchronize task changes between users.

Email Notifications

Send reminders when task deadlines approach.

Analytics Dashboard

Display completed tasks, pending tasks, productivity trends, and activity summaries.

AI-Powered Features

Integrate an AI service to summarize tasks, suggest priorities, or convert natural-language instructions into structured task descriptions.

These extensions transform a basic CRUD project into a more complete software product.

17. Lessons Learned from Building with Next.js and PostgreSQL

Building a full stack application teaches several important engineering principles.

First, application architecture matters. Separating database access, validation, UI components, and authentication makes code easier to understand.

Second, data security must be considered from the beginning rather than added at the end.

Third, a working application is not necessarily a production-ready application. Performance, testing, monitoring, accessibility, and deployment all contribute to reliability.

Finally, choosing technologies is only one part of software engineering. Understanding how they interact is what allows developers to build useful products.

Conclusion

Next.js and PostgreSQL provide a practical foundation for building modern full stack applications.

Next.js simplifies routing, rendering, and server-side application logic, while PostgreSQL provides reliable relational data storage.

By combining these technologies with Prisma, TypeScript, secure authentication, validation, and thoughtful database design, developers can create applications that are easier to maintain and extend.

Our task management example demonstrates the essential building blocks: project setup, database modeling, CRUD operations, frontend development, authentication, performance optimization, testing, and deployment.

Whether you are a beginner learning full stack development or an experienced developer expanding your technical portfolio, building a complete application from start to finish is a valuable way to strengthen your engineering skills.

The real achievement is not simply writing code that runs. It is creating a secure, reliable, and useful application that solves an actual problem.

**What would you build first with Next.js and PostgreSQL: a task management system, an ecommerce platform, or a SaaS dashboard? Share your thoughts and project ideas in the comments.

Galaxy Movies

Fri, 02 Oct 2026 08:29:08 +0000

Galaxy Movies is a movie discovery app I built to make finding something to watch faster and less overwhelming.

I wanted the experience to feel simple. Open the site, browse what is popular, search for something specific, open a movie, and quickly get the information needed to decide whether it is worth watching.

The project started as a frontend application and gradually grew into a larger movie discovery platform with streaming availability, movie and cast pages, AI generated content, and a conversational movie recommendation assistant.

What it does

Users can browse popular, new, upcoming, and genre based movies, search by title, explore movie details, view cast and director information, and check where a movie is available to stream.

Movie pages include information such as release date, runtime, genres, ratings, cast, director, trailers, streaming providers, similar movies, and an AI generated summary.

Galaxy Movies also includes Galaxy Bot, a conversational movie assistant that helps users find something to watch based on things like genre, mood, time constraints, streaming preferences, and group preferences.

The assistant can return actual movies available inside Galaxy Movies rather than only responding with plain text recommendations.

Tech stack

The application is built primarily with JavaScript using Next.js and React.

For the interface, I use Chakra UI, while React Query handles client side fetching and caching.

Movie data comes from the TMDB API, and OpenAI powers the AI recommendation and summary features.

The project is deployed on Vercel and also uses Vercel Edge functionality for dynamically generated social preview images.

Performance

Performance has been an important part of the project.

The homepage server renders the initial set of popular movies so users and search engines receive useful content immediately.

Additional movie results are loaded through infinite scrolling and cached with React Query.

Search input is debounced to avoid unnecessary requests, and API responses use caching where appropriate.

I have also spent time improving image loading, movie data caching, and reducing unnecessary network requests.

Galaxy Bot

One of the more interesting parts of the project has been building the movie assistant.

Users can ask questions such as:

What is a good sci-fi movie for tonight?

What should my wife and I watch if I like action movies and she likes comedies?

What are some recent movies worth watching?

The backend sends the conversation to OpenAI while also providing movie specific context when needed.

When the assistant mentions a movie, Galaxy Movies can resolve that recommendation back to a real TMDB movie and turn it into a link to the movie page.

That makes the assistant part of the application rather than a separate chatbot sitting on top of it.

Streaming availability

Galaxy Movies also checks streaming provider information by region.

The goal is to help answer the question that usually comes immediately after finding a movie:

Where can I actually watch this?

Streaming availability can vary by country and change over time, so the application uses current provider data rather than hard coding availability.

Movie discovery

I have tried to keep the main browsing experience intentionally simple.

The homepage focuses on movie posters, search, categories, and quick discovery rather than filling the screen with a large amount of navigation or promotional content.

From there, individual movie pages provide the deeper information.

The project also includes pages for genres, actors, directors, production companies, and streaming services so users can continue exploring naturally.

Why I built it

The original motivation was pretty simple.

There are a lot of movie databases and streaming services, but finding something to actually watch can still take longer than it should.

I wanted to build something that combines traditional movie browsing with streaming information and conversational recommendations while keeping the interface quick and straightforward.

It has also become a project where I can experiment with Next.js performance, API design, AI features, caching, SEO, responsive interfaces, and product design in a real application.

What I'm working on next

I'm continuing to improve the discovery experience, recommendation quality, performance, and overall usability.

I'm especially interested in feedback around how quickly users can understand the application, find a movie they are interested in, and move from discovery to actually deciding what to watch.

Feedback on the architecture, JavaScript, Next.js implementation, performance, or UX is welcome!

What If Full-Stack Features Were Installable?

Thu, 01 Oct 2026 07:36:17 +0000

NextAPI, and an experiment in reusing whole application capabilities instead of code.

Every developer knows the first week of a new project. Before a single line of product code, you wire up authentication, decide how roles work, connect a database, configure Docker and build the shell your pages will live in. Then, once the foundation is in place, you start on the features, and discover you are rebuilding the same team workspace, profile page and admin area you built on the last project.

Boilerplate solved the foundation. It never solved the features.

NextAPI is my attempt to solve both. It began as a Next.js and FastAPI starter and has grown into something more ambitious: a framework where a full-stack feature (its pages, its API, its database model, its permissions and its navigation) can be installed, verified, versioned and rolled back like a package.

This article walks through what that actually means, and why I think it matters.

Part One: A Foundation You Can Use Today

NextAPI Core is a complete full-stack application, ready in minutes. It stands entirely on its own. You never have to touch the module system to get value from it.

Out of the box, you get:

Capability	What it means in practice
Encrypted authentication	Credentials-based auth through NextAuth v5. Login and registration payloads are AES-256-CBC encrypted on the client before a signed JWT is ever issued.
Role-based access control	Admin, user and guest roles embedded in the JWT and enforced on both frontend and backend.
Machine-to-machine API access	API client tokens (`X-API-Key` / `X-API-Secret`) kept separate from user sessions, so integrations never borrow a person's login.
A modern async backend	FastAPI with Pydantic v2 validation and SQLAlchemy 2.0.
Two databases, one switch	SQLite by default with zero setup, or MongoDB with a single environment variable.
Web and native mobile from one codebase	The same frontend ships as Android and iOS apps through Capacitor, authenticating against the same JWT endpoints.
A configurable app shell	Sidebar or top navbar, chosen once.
Production-ready deployment	A Docker Compose stack with frontend, backend and an optional nginx reverse proxy with SSL.

Even setup has been designed to remove the usual failure points. Running npm run setup generates real secrets rather than placeholders, and writes the same encryption key to both the frontend and backend configuration. The two most common ways to break authentication by hand, a forgotten placeholder or keys that drift apart, simply cannot happen.

npm run setup
npm run dev

Frontend on port 3000, backend on port 8000, and you are building your product.

If you would rather start from a genuinely empty canvas, npm run init:blank permanently removes the demo pages, so there is no dead code to carry into production.

From here, the application is yours. Write your own routes, models and components. Install any npm or Python package. Change the architecture. NextAPI is not a hosted platform, and nothing about your application depends on anyone but you.

Part Two: The Problem Package Managers Never Solved

The package ecosystem is extraordinary. Need a Python library? Install it. Need a React component? There are thousands.

But what if you do not need a library? What if you need a feature?

Consider team management. It is not a component. It is a set of pages for teams, members and invitations; API endpoints behind each of them; database collections to store them; permissions governing who can do what; and navigation entries so users can find them.

Those pieces describe one capability. Yet the way we reuse software today scatters them across separate packages, separate copy-pastes and, most often, separate rewrites. Every copy starts drifting the moment it lands.

That led to the question at the heart of NextAPI:

What if the unit of reuse were the feature rather than the library?

Part Three: A Feature With a Contract

In NextAPI, a feature is a module, and every module is described by a single manifest. Here is a real one, lightly trimmed:

{
  "id": "ai-notes",
  "version": "1.0.0",
  "nextapiVersion": ">=1.0.0 <2.0.0",
  "requires": { "modules": ["profile-page@^1.0.0"] },
  "env": {
    "backend": [{ "key": "ANTHROPIC_API_KEY", "required": true, "secret": true }]
  },
  "dependencies": {
    "frontend": { "npm": { "react-markdown": "^9.0.0" } },
    "backend": { "pypi": { "anthropic": "^0.40.0" } }
  },
  "frontend": {
    "routes": [{ "path": "/notes", "protected": true, "label": "Notes" }]
  },
  "backend": {
    "router": { "module": "backend/router.py", "prefix": "/notes" },
    "collection": "module_ai_notes"
  },
  "functions": {
    "uses": ["auth.get_current_user", "profile.get_display_name"]
  }
}

Read it closely, because this is where the idea becomes concrete. In one file, this module declares:

the page it adds, that the page requires sign-in, and the label it shows in navigation;
the API router it contributes and the URL prefix it answers on;
the database collection it owns;
the npm and PyPI packages it needs;
the environment variables it requires, and which are secrets;
the other modules it depends on, with version ranges;
the specific functions it calls from those modules;
and the range of NextAPI versions it is compatible with.

A conventional package gives you code. This manifest gives the framework an understanding of a capability: what it is, what it needs and how it fits into the application around it. Everything else NextAPI does is built on that understanding.

Part Four: Two Commands, and What Really Happens

Installing a module needs no account:

nextapi add @alice/team-workspace
nextapi sync

add only records your intent in the project's lockfile. Nothing in your application changes.

sync is where the real work happens, and its defining principle is simple: nothing is written until the whole install has been proven safe. Before touching a single file, it:

resolves dependency order and checks for circular dependencies;
fetches any modules the new one depends on, automatically;
verifies that every function a module calls is actually provided by the module it depends on;
checks for route, backend package and database collection collisions.

If any check fails, the install is refused up front. An install is never left half-applied.

Only then does sync wire the feature into your real codebase:

your-app
├── app/team/page.tsx                                  new
├── backend/module_alice_team_workspace/router.py      new
├── backend/module_alice_team_workspace/models_mongo.py new
├── config/routes.ts                                   RBAC entry merged
└── .env                                               appended, your values untouched

The page appears in your sidebar or navbar automatically. The RBAC rules are merged into your configuration. The backend lands as its own isolated package.

Part Five: The Hard Problems, Solved in the Open

The idea is easy to state. What makes NextAPI worth taking seriously is how it handles the problems that make installable features genuinely difficult.

It joins your data instead of duplicating it

Suppose your application already has users, and you install a user-management module that also declares a users collection. A naive system creates a second, disconnected collection, and you now have two sources of truth about who can log in.

NextAPI detects the overlap. If the module's fields are compatible with your existing collection, sync offers to link the module to your real data instead:

'@alice/user-management' declares a "users" collection compatible with your
existing UserCollection. Link it instead of creating a separate collection? (y/N)

It goes further than matching field names:

Method adoption. If the module calls methods your collection class does not have yet, sync adds the module's implementations to your model. It is purely additive and never overwrites a method your application already relies on.
Real-data checks. A schema can match on paper and still not match reality. sync samples your actual MongoDB documents, and if a field your model declares as required is missing from existing records, it asks before relaxing it:

'users' collection: 'created_at' is declared required, but missing from
214/1,048 existing documents. Demote 'created_at' to optional in your
host's UserMongo model to match reality? (y/N)

Remembered decisions. Updates to a linked module re-link automatically. If a future version stops matching, it falls back safely and tells you exactly what happened.

When fields do not match, the module installs against its own collection and you receive a precise, field-by-field report of what did not line up, which is something concrete for the module's author to fix.

This is the difference between installing code into an empty project and integrating a feature into a living system.

Modules depend on capabilities, not just packages

Modules can declare the functions they provide and the functions they use. A support-chat module can call profile.get_display_name, provided by a profile module, and the registry confirms that capability exists before either module installs.

Package managers resolve graphs of libraries. NextAPI resolves a graph of application capabilities.

Names never collide

Two authors can both build a module with a /profile page and a profile collection. At install time, NextAPI automatically namespaces pages, backend code and database storage per module. Authors can write as though their module is the only one that will ever exist.

Versioned like real software

Versions follow semver and are immutable once published.
A bad release can be yanked from new installs without breaking anyone already using it.
Compatible version ranges are resolved to a single shared version automatically, and genuine conflicts are reported with both requirements named.
Stateless modules can opt into running multiple major versions side by side.
Stored data carries its own schemaVersion. Changing the shape of persisted documents requires publishing a normalizer that upgrades older documents on read, so no previously stored record ever becomes unreadable.

Every risky change is deliberate and reversible

Some modules replace an existing page rather than adding one: a custom login screen, a redesigned landing page. That requires an explicit acknowledgement written into the manifest itself, so it cannot be scripted past a prompt. Before anything is replaced, the original is captured as a full snapshot, and nextapi rollback /login restores it.

Files you have edited by hand since the last sync are detected and left alone. nextapi list flags drift, and nextapi remove will not discard your changes without --force.

Part Six: It Is Your Code

None of this turns your application into a black box.

After sync, a module's files are committed into your project as ordinary, readable source code, marked in clearly generated regions. You can edit them immediately. There is no runtime dependency on the registry. If the registry disappeared tomorrow, your application would keep running exactly as it does today.

That was a non-negotiable design goal. The registry distributes capabilities. It never owns them.

The registry at nextapi.app is where modules are published, discovered and installed. Building for it is designed to be as approachable as using it.

Build in the browser. Start from a working template and edit in a full code editor that understands TypeScript, JavaScript, Python and JSON, with errors marked on the exact line.
Build with AI. The AI Builder writes an entire module (manifest, backend, page and preview data) from a description. What sets it apart is discipline: it loads design standards before laying out a page, looks up a library's real documentation instead of guessing, lints its own output for accessibility issues such as contrast and reduced motion, and runs the same validation that gates every publish. Its output is identical in form to a hand-written module. The only difference is who typed it.
Publish with confidence. nextapi validate checks the schema, capabilities and file paths locally, and every publish is re-validated on the server. Each module must ship maintainer-facing implementation notes explaining what it assumes about the host application.
Share privately. Publish a private module and share it with specific people by username.
Fork with credit. Fork any public module to adapt it. The original author is recorded permanently and cannot be removed from the fork.

Part Eight: Core Stands on Its Own

This is worth stating plainly, because the registry can make the project appear more complex than it is.

You can use NextAPI Core purely as a full-stack foundation and ignore the module ecosystem entirely. The registry is a layer on top, not a requirement underneath:

                    Registry
                       |
             +---------+---------+
             |         |         |
          Module A  Module B  Module C
             |         |         |
             +---------+---------+
                       |
                  NextAPI Core
                       |
              +--------+--------+
              |                 |
           Next.js           FastAPI
              |                 |
              +--------+--------+
                       |
                    Database

NextAPI should be useful before the ecosystem exists. The registry should make it more powerful, never necessary.

What I Am Actually Building

I am not building another package manager, and I have no interest in replacing npm or PyPI. They solve a different problem, and they solve it well.

What interests me is moving one level higher. A library knows what functions it exports. A NextAPI module knows:

"I add these pages, and they require sign-in."
"I expose these API routes."
"I own this data, and this is the version of its shape."
"I need these permissions, packages and secrets."
"I depend on these capabilities from other modules."
"I belong in the navigation, here."

Once a framework has that information, it can do far more than copy code into a project. It can reason about how a feature fits into an application: whether it is safe, whether it conflicts, whether it should join existing data, and how to undo it.

Where Things Stand

NextAPI is open source under the MIT license and actively evolving. The foundation is solid, the module system already handles problems most tools never attempt, and plenty of hard work remains: richer migrations, broader host compatibility and a growing library of modules.

The underlying idea is one I believe is worth pursuing:

Instead of rebuilding the same full-stack features over and over, what if we could install the capability itself?

That is what NextAPI has become. Not just a starter kit, and not just a registry, but an attempt to move reusable software one step closer to the application itself.

Try it:

Source code: github.com/sup3rus3r/nextapi-core
Module registry and docs: nextapi.app
Support the project: GitHub Sponsors

You Added a Content-Security-Policy Header and Your Next.js App Went Blank. Here's Why.

Tue, 29 Sep 2026 09:08:44 +0000

You read that a Content-Security-Policy header is a good security hardening step. You add a sensible-looking policy to your Next.js config, deploy, and the site loads as a blank or half-working page with a wall of red errors in the console.

Nothing is wrong with your code. The policy is doing exactly what you told it to do, and what you told it to do happens to block Next.js itself.

The Header That Breaks Everything

// next.config.ts
const nextConfig = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: "default-src 'self'; script-src 'self'",
          },
        ],
      },
    ];
  },
};

export default nextConfig;

script-src 'self' says scripts may only load from your own origin as external files. That sounds right, until you remember Next.js injects small inline <script> tags into every page, for hydration data, for the router, for streaming. Inline scripts are exactly what script-src 'self' forbids, so the browser refuses to run them, hydration never completes, and the page looks dead.

The Tempting Wrong Fix

value: "default-src 'self'; script-src 'self' 'unsafe-inline'"

This makes the errors disappear, and it also removes most of the protection you added the header for. 'unsafe-inline' tells the browser to run any inline script, including one an attacker managed to inject through an XSS hole. A CSP with 'unsafe-inline' in script-src still exists, but it no longer does the main job a CSP is supposed to do.

The Actual Fix: A Per-Request Nonce

A nonce is a random, single-use value generated for each request. You put it in the CSP header, and you attach the same value to the scripts you trust. The browser then only runs inline scripts carrying the matching nonce, and an injected script has no way to guess it.

Next.js supports this through middleware:

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const nonce = Buffer.from(crypto.randomUUID()).toString('base64');

  const csp = [
    "default-src 'self'",
    `script-src 'self' 'nonce-${nonce}' 'strict-dynamic'`,
    `style-src 'self' 'nonce-${nonce}'`,
    "img-src 'self' blob: data:",
    "object-src 'none'",
    "base-uri 'self'",
  ].join('; ');

  const requestHeaders = new Headers(request.headers);
  requestHeaders.set('x-nonce', nonce);
  requestHeaders.set('Content-Security-Policy', csp);

  const response = NextResponse.next({ request: { headers: requestHeaders } });
  response.headers.set('Content-Security-Policy', csp);
  return response;
}

Next.js reads the nonce from the request's CSP header and applies it to the framework's own inline scripts automatically. For any script you add yourself, read the nonce and pass it along:

// app/layout.tsx
import { headers } from 'next/headers';
import Script from 'next/script';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const nonce = (await headers()).get('x-nonce') ?? undefined;

  return (
    <html lang="en">
      <body>
        {children}
        <Script src="https://analytics.example.com/script.js" nonce={nonce} strategy="afterInteractive" />
      </body>
    </html>
  );
}

'strict-dynamic' in the policy lets a nonced script load further scripts it depends on, which keeps things like analytics loaders working without you allowlisting every domain by hand.

The Tradeoff Nobody Mentions Upfront

A nonce has to be unique per request, and it has to be baked into the HTML the server sends. That means any page using it must be rendered dynamically on each request. A statically generated page is built once ahead of time, so it cannot contain a fresh nonce for every visitor.

This is the same static versus dynamic rendering boundary covered in my earlier posts on cookies() and searchParams. Reading the nonce from headers() opts the route into dynamic rendering, so turning on nonce-based CSP across your whole site gives up static generation for every route it covers.

For a mostly static marketing site, that is a real cost. Two reasonable ways to handle it:

Apply the strict nonce policy only where it matters most, like authenticated dashboards and anything handling user input, and use a hash-based or more permissive policy for purely static pages.

Use hash-based CSP for static pages, where the script contents are known at build time, so each inline script's hash can be allowlisted instead of requiring a per-request nonce.

How to Test It Without Breaking Production

// Ship this first, it reports violations without blocking anything
{
  key: 'Content-Security-Policy-Report-Only',
  value: "default-src 'self'; script-src 'self' 'nonce-...'",
}

Content-Security-Policy-Report-Only logs every violation to the console and to a reporting endpoint without actually blocking a thing. Run it for a while, fix what it flags, then switch to the enforcing header. This is how you avoid the blank-page deploy from the top of this post.

The Actual Rule

A strict CSP and Next.js's inline scripts are incompatible unless you use nonces or hashes, and nonces mean dynamic rendering. Do not reach for 'unsafe-inline' to make errors go away, since that removes the protection you were adding. Start in report-only mode, decide which routes genuinely need the strictest policy, and accept that those routes will render per request.

I go through this same tradeoff when hardening client projects and the templates at pixelanas.com, and I write up more of these security and rendering details on the blog as I run into them.

If you have a CSP on a Next.js app right now, check whether it contains 'unsafe-inline' in script-src. If it does, it is worth knowing how much protection it is really giving you. Drop what you find in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Forgetting default.tsx in a Next.js Parallel Route Can 404 Your Entire Page, Not Just One Slot

Sun, 27 Sep 2026 09:32:05 +0000

This is a genuinely surprising failure mode the first time you hit it, since the natural assumption is that an unmatched parallel route slot would just render nothing, not take down a page that has nothing to do with the slot in question.

The Setup From an Earlier Post, Extended

Building on the intercepting route modal pattern from an earlier post, the @modal slot renders the modal when a specific route is intercepted. But a parallel route slot needs to render something for every URL within its scope, not just the one specific route it was built for.

app/
├── @modal/
│   ├── (.)photo/
│   │   └── [id]/
│   │       └── page.tsx    // renders when a photo route is intercepted
│   └── (missing: default.tsx)
├── photo/
│   └── [id]/
│       └── page.tsx
├── settings/
│   └── page.tsx             // a completely unrelated route
├── layout.tsx
└── page.tsx

Why Visiting an Unrelated Page Can Break Entirely

The @modal slot is defined at the root layout level here, which means it's part of every route rendered under that layout, not just the photo routes it was actually built for. Next.js needs to know what @modal should render for every single route within its scope, including /settings, which has nothing to do with photos or modals at all. If there's no page.tsx inside @modal matching /settings, and critically, no default.tsx file to serve as a fallback for exactly this situation, Next.js has no content to render for that slot on that route, and without a fallback, it treats this as a genuine 404 for the entire page, not just an empty modal slot.

Why This Specific Failure Mode Is So Confusing

The intercepting modal pattern itself works perfectly, clicking a photo from the grid correctly shows the modal, refreshing correctly shows the full page, exactly the behavior covered in the earlier post. The /settings page, something that looks completely unrelated to any of that photo and modal logic, is what actually breaks, with a full 404, and nothing about that page's own code gives any indication why. The actual cause lives entirely in the parallel route configuration at the layout level, several files away from the page that's actually failing, which makes this a genuinely disorienting bug to trace the first time.

The Fix: A default.tsx for Every Parallel Slot

// app/@modal/default.tsx
export default function Default() {
  return null; // this slot simply renders nothing when there's no active modal
}

default.tsx tells Next.js exactly what to render for this slot whenever the current route doesn't match anything more specific within it. Returning null here is completely correct and intentional, for any route that isn't specifically showing a modal, @modal should render nothing, and default.tsx is what makes that an explicit, defined behavior instead of an unhandled gap that produces a full 404.

Why This Is Easy to Miss When First Setting Up Parallel Routes

Most tutorials and examples for intercepting routes focus entirely on the specific route being intercepted, since that's the actual feature being demonstrated, and default.tsx is easy to treat as an afterthought or skip in a quick example, since the demo itself often only ever navigates between the two or three routes that were actually set up correctly. The gap only becomes visible once someone navigates to a genuinely unrelated route that was never part of the original example, exactly the kind of route a real, full application has plenty of.

The Broader Rule

Every parallel route slot needs a default.tsx, without exception, the moment that slot exists anywhere in a layout that also renders routes the slot has no specific content for. This isn't an edge case fallback for rare situations, it's the default, expected behavior for the overwhelming majority of routes in any real application, since a slot built for one specific interaction, a modal, a sidebar variant, is inherently the exception, not the rule, across a site's full set of routes.

Checking Your Own Parallel Routes

find app -type d -name "@*"

For every parallel route slot this turns up, confirm a default.tsx exists directly inside it. If it doesn't, any route within that layout's scope that isn't specifically handled by that slot is at genuine risk of a full 404, not a minor rendering gap, the moment someone actually navigates there.

I set up a default.tsx as the very first file whenever I add a parallel route slot to any project now, client work included, for exactly this reason, it costs one trivial file and prevents a genuinely confusing, hard-to-trace production bug. If you're exploring more Next.js patterns like this, I write about them regularly at pixelanas.com/blog.

If you're using parallel routes anywhere, run the check above right now and confirm every slot has its fallback file. If one doesn't, you've got a real, ready-to-happen 404 waiting on some route you haven't tested yet. Drop what you find in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Why Your useEffect Runs Twice in Development (And Why You Shouldn't "Fix" It)

Sat, 26 Sep 2026 09:20:46 +0000

This causes a very specific, very common reaction, a developer sees a console.log inside useEffect fire twice in the browser console during local development, assumes something's genuinely broken, and starts debugging a bug that doesn't actually exist.

What's Actually Happening

'use client';
import { useEffect } from 'react';

export function Tracker() {
  useEffect(() => {
    console.log('Effect ran'); // logs twice in development, once in production
    trackPageView();
  }, []);

  return null;
}

In development, with React's Strict Mode enabled, which the Next.js App Router enables by default, React deliberately mounts a component, runs its effects, unmounts it, and immediately remounts it again, running the effects a second time. This is not a bug, and it's not accidental, it's a specific, intentional development-only behavior designed to help surface exactly the kind of bug this pattern causes in the first place, effects with real, unintended side effects or missing cleanup.

Why React Does This on Purpose

React is preparing for a future where components can be safely paused, discarded, and remounted, for features like offline support and certain rendering optimizations, and that capability genuinely requires effects to be safely re-runnable, mount, unmount, mount again, without producing broken or duplicated behavior. The double-invoke in development is a deliberate stress test, if your effect breaks when run twice in a row, mount, unmount, mount, it's revealing a genuine correctness gap, code that assumes it only ever runs once, which was never actually a safe assumption to begin with, even before Strict Mode made it visible.

Why the Instinct to "Fix" This Is Usually Wrong

Seeing double logs or double network calls in development and reaching for a way to suppress it, disabling Strict Mode entirely, or adding a fragile useRef guard specifically to prevent the second invocation, treats the symptom as the problem. The actual problem, if there is one, is that the effect wasn't written to safely handle being cleaned up and re-run, which is a real gap worth fixing properly, not hiding by preventing Strict Mode from ever revealing it again.

// ❌ A common "fix" that just hides the signal instead of addressing what it revealed
const hasRun = useRef(false);

useEffect(() => {
  if (hasRun.current) return;
  hasRun.current = true;
  trackPageView();
}, []);

This pattern specifically defeats the entire point of Strict Mode's double-invoke check, and worse, it can behave inconsistently across React versions and concurrent rendering scenarios in ways that are genuinely harder to reason about than just writing the effect correctly in the first place.

The Actual Fix: Write Effects That Are Safe to Run Twice

For something like an analytics call, the real question worth asking is whether firing it twice in development actually matters, and for most analytics providers, it doesn't, in production, without Strict Mode's double-invoke, it only fires once anyway. The development-only double log is not the same as double-counting real production analytics data, a distinction worth confirming directly rather than assuming.

useEffect(() => {
  // In production, this fires once. In development, Strict Mode fires it
  // twice, which is expected and does not reflect production behavior.
  trackPageView();
}, []);

For an effect that sets up something genuinely stateful, a subscription, an interval, an event listener, the actual fix is a real, correct cleanup function, which is precisely what Strict Mode's double-invoke is designed to verify you've written:

useEffect(() => {
  const interval = setInterval(() => {
    checkForUpdates();
  }, 5000);

  return () => clearInterval(interval); // correctly cleans up, safe to run twice
}, []);

With a correct cleanup function, the double-invoke in development runs cleanly, set up, tear down, set up again, exactly the pattern Strict Mode exists to confirm your code actually handles safely. If removing the cleanup function causes something to visibly break or duplicate in development, that's Strict Mode doing its job, not React misbehaving.

Where This Actually Matters for Real Bugs, Not Just Console Noise

This connects directly to the stale fetch race condition covered in an earlier post, an effect fetching data without a cleanup function that ignores stale responses is exactly the kind of effect that also breaks under Strict Mode's double-invoke in development, showing a flash of duplicated or incorrect state before settling, which is a genuine, useful early warning for a bug that would otherwise only surface in production under real network timing variance.

The Actual Rule

A useEffect that produces visibly different or broken behavior when Strict Mode runs it twice in development almost always has a real gap, missing or incorrect cleanup, not properly guarding against being re-invoked, that would eventually cause a genuine bug in production too, just under different, harder-to-reproduce conditions. The fix is writing the effect to genuinely handle mount, unmount, remount correctly, not suppressing the specific mechanism designed to reveal that it doesn't.

I keep Strict Mode enabled across every project I build, client work and the templates at pixelanas.com alike, specifically because catching this category of bug in development, as annoying as the double logs are at first, is far cheaper than debugging the same underlying issue once it surfaces as an intermittent, hard-to-reproduce production bug instead.

If you've disabled Strict Mode, or added a ref-based guard specifically to suppress double-invoked effects, worth reconsidering whether that's hiding a real, fixable gap rather than actually solving anything. Drop your own experience with this in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

MUI v9 Theme Setup in Next.js 16: Full 2026 Guide

Sat, 26 Sep 2026 03:07:57 +0000

You installed @mui/material, dropped a <Button> on the page, and it looked... fine. Then you added a custom color, refreshed the page, and for a split second saw the default MUI blue before your color kicked in. Or worse — your styles randomly break depending on which route loads first.

None of that is a coincidence. It's what happens when MUI's styling engine (Emotion) meets Next.js's server-streaming App Router without the right glue in between. MUI ships an official package specifically for this, and most tutorials online still show the old Pages Router setup or skip the dark mode flash entirely.

By the end of this guide, you'll have a complete, production-ready MUI theme wired into a Next.js 16 App Router project — proper SSR style injection, a TypeScript-friendly custom theme, Google Fonts through next/font, a flash-free light/dark mode toggle, and the correct way to write mode-aware styles so they don't flicker.

Why This Is Tricky

Next.js's App Router renders on the server and streams HTML to the browser in chunks. MUI's default styling engine, Emotion, generates CSS at render time and needs to know how to collect all of that generated CSS and inject it into the <head> before the streamed HTML reaches the browser — otherwise you get unstyled flashes or duplicated styles.

On top of that, MUI components that use hooks (like useState for a theme toggle) need to be Client Components, but your root layout is a Server Component by default. If the Server vs. Client Component split isn't second nature to you yet, it's worth a quick read before this guide — almost every mistake in a MUI + Next.js setup comes down to getting that boundary wrong. Get it wrong here and you'll see:

A flash of unstyled or default-themed content (FOUC)
Hydration mismatch warnings in the console
Dark mode flashing light for a split second on every page load

MUI's official @mui/material-nextjs package exists specifically to solve the streaming/cache problem, and a few small App Router patterns solve the rest. Let's build it properly.

Prerequisites

This guide assumes:

Next.js 16 with the App Router
React 19.2 (Next.js 16's default)
TypeScript in strict mode
npm (swap for yarn/pnpm commands as needed)

Step 1: Install MUI and Its Dependencies

MUI's core package is @mui/material, and it needs Emotion (its default style engine) plus the official Next.js integration package.

npm install @mui/material @emotion/react @emotion/styled @mui/material-nextjs @mui/icons-material

Here's what each package actually does:

Package	Purpose
`@mui/material`	The core component library (buttons, inputs, layout, etc.)
`@emotion/react` / `@emotion/styled`	MUI's default CSS-in-JS engine — generates the actual styles
`@mui/material-nextjs`	Official adapter that makes Emotion's SSR streaming work correctly with the App Router
`@mui/icons-material`	Material Design icon set (optional, but almost every project ends up needing it)

Version note: This guide targets MUI v9 with Next.js 16. Keep the MUI packages on compatible v9 releases, and use the v16-appRouter integration entry point.

💡 Tip: MUI's current package layout uses Node.js package exports to provide appropriate ESM and CommonJS entry points, so this setup doesn't require special MUI bundler configuration.

A note on the versioned import paths

You'll notice the import in the next step is @mui/material-nextjs/v16-appRouter, not just @mui/material-nextjs. This isn't cosmetic — the package ships a separate entry point per Next.js major version, because each new Next.js major has occasionally changed how App Router streaming/rendering internals work under the hood. Using the wrong one for your Next.js version is a real (if often silently-working) mismatch, so pick the entry point that matches your installed Next.js major:

Next.js version	`@mui/material-nextjs` entry point
Next.js 13	`v13-appRouter`
Next.js 14	`v14-appRouter`
Next.js 15	`v15-appRouter`
Next.js 16	`v16-appRouter`

⚠️ Common Mistake: Copy-pasting an older tutorial's v15-appRouter (or even older) import into a Next.js 16 project. It may still build without errors, but you're no longer using the entry point MUI actually maintains against your Next.js version — always match the number to your installed next major.

Step 2: Add the App Router Cache Provider

This is the piece almost every outdated tutorial skips or gets wrong. AppRouterCacheProvider is what collects Emotion's generated CSS during server rendering and streams it into the <head> correctly, instead of leaving it to render inline in the <body> (which causes the unstyled flash).

Create your root layout:

// app/layout.tsx
import type { Metadata } from "next";
import { AppRouterCacheProvider } from "@mui/material-nextjs/v16-appRouter";

export const metadata: Metadata = {
  title: "My MUI App",
  description: "A Next.js 16 app styled with MUI",
};

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en">
      <body>
        <AppRouterCacheProvider>
          {children}
        </AppRouterCacheProvider>
      </body>
    </html>
  );
}

What's happening here: AppRouterCacheProvider wraps everything under <body>. As Next.js streams your page in chunks, this provider intercepts every bit of CSS Emotion generates along the way and inserts it into <head> ahead of the content that needs it — so by the time a chunk of HTML reaches the browser, its styles are already there.

💡 If you also need to set page titles, Open Graph tags, or other <head> data alongside this setup, that's handled separately through Next.js's own Metadata API — the metadata export above is a small example of it, not something AppRouterCacheProvider manages.

At this point, run your dev server and add any MUI component — the styles should already apply correctly with no flash. Now let's make the theme actually yours.

Step 3: Create a Custom Theme File

A "theme" in MUI is just a JavaScript object describing your colors, typography, spacing, and component overrides. Centralizing it in one file means every component in your app pulls from the same design tokens instead of scattered inline styles.

// theme/theme.ts
"use client";

import { createTheme } from "@mui/material/styles";

const theme = createTheme({
  cssVariables: true,
  palette: {
    primary: {
      main: "#0F62FE",
    },
    secondary: {
      main: "#6929C4",
    },
  },
  shape: {
    borderRadius: 10,
  },
  typography: {
    fontFamily: "var(--font-roboto)",
  },
});

export default theme;

What's happening here:

"use client" is required at the top of this file. MUI recommends creating the theme in a Client Component module when using it with the App Router because the theme object is consumed by the client-side ThemeProvider, and the theme contains more than plain serializable configuration data.
Related: Server vs. Client Components in Next.js 16 covers exactly what does and doesn't need this directive.
cssVariables: true tells MUI to expose theme tokens as CSS custom properties such as --mui-palette-primary-main. MUI components can then reference these variables, which is particularly useful for switching color schemes without requiring a full CSS regeneration. This is the modern MUI approach — it plays nicer with server rendering and is what makes the flash-free dark mode in Step 5 possible.
palette.primary / palette.secondary override MUI's default blue/purple with your own brand colors. Every component (<Button color="primary">, <Chip color="secondary">, etc.) automatically picks these up.
typography.fontFamily references a CSS variable we'll define in the next step using next/font — this is the correct way to combine MUI with Next.js's font optimization.

💡 Tip: Keep this file focused on your app's design tokens (colors, spacing, typography), and use component-level sx props for one-off styling. Don't try to theme every possible edge case up front — add overrides as you actually need them.

Step 4: Load Fonts with `next/font` and Wire Up the Theme Provider

Next.js's built-in font optimization (next/font) self-hosts Google Fonts at build time, avoiding a render-blocking request to Google's font CDN. MUI's docs specifically recommend combining it with the theme via a CSS variable rather than passing the font name as a plain string.

// app/layout.tsx
import type { Metadata } from "next";
import { Roboto } from "next/font/google";
import { AppRouterCacheProvider } from "@mui/material-nextjs/v16-appRouter";
import { ThemeProvider } from "@mui/material/styles";
import CssBaseline from "@mui/material/CssBaseline";
import theme from "@/theme/theme";

const roboto = Roboto({
  weight: ["300", "400", "500", "700"],
  subsets: ["latin"],
  display: "swap",
  variable: "--font-roboto",
});

export const metadata: Metadata = {
  title: "My MUI App",
  description: "A Next.js 16 app styled with MUI",
};

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en" className={roboto.variable}>
      <body>
        <AppRouterCacheProvider>
          <ThemeProvider theme={theme}>
            <CssBaseline />
            {children}
          </ThemeProvider>
        </AppRouterCacheProvider>
      </body>
    </html>
  );
}

What's happening here:

Roboto({ ... variable: "--font-roboto" }) generates a CSS variable holding the correct font-family string, and Next.js injects the actual @font-face rules automatically — no manual <link> tags.
Adding className={roboto.variable} to <html> makes that CSS variable available everywhere in your app, including inside the MUI theme file from Step 3 (fontFamily: "var(--font-roboto)").
<ThemeProvider theme={theme}> makes your custom theme available to every MUI component via context — this is what actually applies your colors and typography.
<CssBaseline /> is MUI's version of a CSS reset — it normalizes margins, sets a consistent box-sizing, and applies your theme's background/text colors to <body>. Almost every MUI project should include it once, at the root.

⚠️ Common Mistake: Passing theme={theme} where theme was created without "use client" in its own file, then importing it into a Server Component layout directly. Keep the theme creation itself client-side (as shown in Step 3) to avoid subtle serialization issues — ThemeProvider here is already a Client Component internally, so this composition is safe.

At this point, your fonts, colors, and typography are fully wired up with zero flash of unstyled content. Now let's add dark mode.

Step 5: Add Flash-Free Dark Mode

The trickiest part of theming in Next.js isn't picking colors — it's avoiding the flash where a user's saved "dark mode" preference briefly shows light mode before JavaScript hydrates and corrects it. MUI's cssVariables mode ships a dedicated component for exactly this: InitColorSchemeScript.

First, update the theme to support both color schemes:

// theme/theme.ts
"use client";

import { createTheme } from "@mui/material/styles";

const theme = createTheme({
  cssVariables: {
    colorSchemeSelector: "class",
  },
  colorSchemes: {
    light: {
      palette: {
        primary: { main: "#0F62FE" },
        secondary: { main: "#6929C4" },
      },
    },
    dark: {
      palette: {
        primary: { main: "#7CA9FF" },
        secondary: { main: "#B490E8" },
      },
    },
  },
  shape: {
    borderRadius: 10,
  },
  typography: {
    fontFamily: "var(--font-roboto)",
  },
});

export default theme;

What changed: instead of one flat palette, we now define colorSchemes.light and colorSchemes.dark, each with its own palette. colorSchemeSelector: "class" tells MUI to switch schemes by toggling a CSS class (rather than data- attributes or prefers-color-scheme alone), which gives you full manual control over the toggle.

Next, add InitColorSchemeScript to the root layout, before anything else renders:

// app/layout.tsx
import { InitColorSchemeScript } from "@mui/material";
// ...other imports from Step 4

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en" className={roboto.variable} suppressHydrationWarning>
      <body>
        <InitColorSchemeScript attribute="class" />
        <AppRouterCacheProvider>
          <ThemeProvider theme={theme}>
            <CssBaseline />
            {children}
          </ThemeProvider>
        </AppRouterCacheProvider>
      </body>
    </html>
  );
}

What's happening here: InitColorSchemeScript injects a tiny, synchronous inline script that runs before React hydrates. It reads the user's saved preference (from localStorage) and applies the right class to <html> immediately — so the correct theme is already active by the time the browser paints anything. This is exactly what eliminates the flash. If you want the deeper "why" behind pre-hydration scripts like this one, Next.js Rendering Strategies Explained covers how streaming and hydration fit together.

⚠️ If you don't add suppressHydrationWarning to your <html> tag, you will see warnings about "Extra attributes from the server" because InitColorSchemeScript updates that element.

Now build a simple toggle button as a Client Component:

// components/theme-toggle.tsx
"use client";

import IconButton from "@mui/material/IconButton";
import Brightness4Icon from "@mui/icons-material/Brightness4";
import Brightness7Icon from "@mui/icons-material/Brightness7";
import { useColorScheme } from "@mui/material/styles";

export default function ThemeToggle() {
  const { mode, setMode } = useColorScheme();

  if (!mode) {
    // Renders on the server before the client has resolved a mode —
    // returning null here avoids a hydration mismatch.
    return null;
  }

  return (
    <IconButton
      onClick={() => setMode(mode === "light" ? "dark" : "light")}
      color="inherit"
      aria-label="Toggle light and dark theme"
    >
      {mode === "dark" ? <Brightness7Icon /> : <Brightness4Icon />}
    </IconButton>
  );
}

What's happening here: useColorScheme() is a hook MUI provides specifically for cssVariables-based themes — it gives you the current mode and a setMode function that updates both the DOM class and localStorage for you. The if (!mode) return null guard matters: on the very first client render, mode can briefly be undefined before MUI resolves it, and rendering nothing during that split second avoids a server/client mismatch warning.

💡 Tip: mode can be "light", "dark", or "system". If you want a three-way toggle (light/dark/follow OS), cycle through all three values instead of just two in the onClick handler.

Step 6: Write Mode-Aware Styles the Right Way — Avoid `theme.palette.mode`

Here's a mistake that's easy to make even after everything above is set up correctly: once a component needs a color that depends on light vs. dark mode, it's tempting to reach for a plain conditional:

// ❌ Don't do this with CSS variables enabled
<Card
  sx={(theme) => ({
    backgroundColor: theme.palette.mode === "dark" ? "#000" : "#fff",
  })}
/>

This looks harmless, but MUI's own docs explicitly warn against it: theme.palette.mode reflects whatever mode was resolved at render time, and on the server that's always a guess (or the default). The result is the exact SSR flicker you just spent Step 5 eliminating — the server renders one color, the client corrects it a moment later, and you see a flash.

The fix is theme.applyStyles(), which generates real CSS rules scoped to each mode instead of picking one value at render time:

// ✅ Correct — no flicker, works with CSS variables
import Card from "@mui/material/Card";

<Card
  sx={[
    {
      backgroundColor: "#fff",
    },
    (theme) =>
      theme.applyStyles("dark", {
        backgroundColor: "#000",
      }),
  ]}
/>;

What's happening here: instead of computing a single color based on the current mode, applyStyles("dark", {...}) generates mode-specific CSS that is activated by the color-scheme selector configured in the theme. Both the light and dark rules can exist in the stylesheet, while the active selector on <html> determines which styles apply.

The same pattern works with the styled() API:

// components/themed-box.tsx
"use client";

import { styled } from "@mui/material/styles";

export const ThemedBox = styled("div")(({ theme }) => [
  {
    color: "#111",
    backgroundColor: theme.palette.background.paper,
  },
  theme.applyStyles("dark", {
    color: "#fff",
    backgroundColor: theme.palette.grey[900],
  }),
]);

⚠️ Common Mistake: Sprinkling theme.palette.mode === "dark" checks throughout sx props "just to get something working," then wondering why dark mode flickers even after adding InitColorSchemeScript. InitColorSchemeScript only prevents the class on <html> from being wrong on first paint — it does nothing to fix a component that's still choosing its color at render time instead of via CSS. Audit your sx props for palette.mode checks and swap them for applyStyles() as you find them.

💡 Tip: You can pass an array of style objects (as shown above) or plain objects — theme.applyStyles() composes fine with any other static styles in the same sx array.

Step 7: Verify Everything Works

Drop the toggle into a page and confirm the full setup:

// app/page.tsx
import Button from "@mui/material/Button";
import Typography from "@mui/material/Typography";
import Stack from "@mui/material/Stack";
import ThemeToggle from "@/components/theme-toggle";

export default function HomePage() {
  return (
    <Stack spacing={3} sx={{ p: 4 }}>
      <Stack direction="row" sx={{ justifyContent: "center", alignItems: "center" }}>
        <Typography variant="h4">MUI + Next.js 16</Typography>
        <ThemeToggle />
      </Stack>
      <Typography variant="body1">
        This button, color, and font are all coming from your custom theme.
      </Typography>
      <Button variant="contained" color="primary">
        Themed Button
      </Button>
    </Stack>
  );
}

Refresh the page a few times with dark mode on — there should be zero flash of the wrong theme, and the button color should match your custom palette instead of MUI's default blue.

app/page.tsx does not need "use client" just because it renders ThemeToggle. Next.js allows Server Components to render Client Components; only the interactive subtree needs the client boundary.

Frequently Asked Questions

Do I need `@mui/material-nextjs` if I'm only using the Pages Router?

The Next.js integration package supports both routers. For the Pages Router, use the versioned pagesRouter entry point that matches your Next.js version, such as v13-pagesRouter for Next.js 13. The setup differs from the App Router and uses _document.tsx/_app.tsx rather than the App Router cache-provider setup.

Why does my theme file need `"use client"` if `ThemeProvider` is used in a Server Component layout?

ThemeProvider itself is already a Client Component internally, so it's safe to render from a Server Component layout. The "use client" on the theme file is a safety measure — createTheme() returns a rich object with methods, and keeping its creation explicitly client-side avoids subtle serialization issues as your theme grows more complex.

Why can't I just check `theme.palette.mode === "dark"` in my styles?

You can, but only if you don't care about the SSR flicker — MUI's own docs say directly that any theme.palette.mode check will flash the wrong mode on first load when CSS variables are enabled, because the server has no way to know the client's saved preference at render time. theme.applyStyles("dark", {...}) avoids this entirely by generating mode-scoped CSS instead of picking a value during render. See Step 6.

Can I use MUI with Tailwind CSS in the same Next.js project?

Yes. The important issue is CSS cascade and style precedence rather than class-name collisions. MUI's enableCssLayer option places generated MUI styles inside an @layer mui layer, making it easier to control how MUI styles interact with Tailwind CSS, CSS Modules, and other global styles.

My styles show up correctly but flash unstyled for a split second — what's wrong?

Almost always means AppRouterCacheProvider isn't wrapping your whole app, or it's nested in the wrong place (it needs to be a direct wrapper inside <body>, around everything else). Double-check Step 2's structure.

Do I still need `CssBaseline`?

No, CssBaseline isn't technically required. It is commonly recommended because it provides MUI's baseline/reset styles and applies theme-aware background and text defaults.

Wrapping Up

You now have a complete, flash-free MUI setup in Next.js 16 — the official AppRouterCacheProvider handling SSR streaming correctly (using the Next.js 16-matched v16-appRouter entry point), a typed custom theme with your own colors and next/font-optimized typography, a working light/dark toggle powered by MUI's native CSS variables, and mode-aware component styles written with theme.applyStyles() instead of a flicker-prone palette.mode check. This is the same foundation you'd want under a real dashboard, admin panel, or SaaS product.

From here, a natural next step is exploring MUI's styled() API and sx prop for component-level customization, or building out a full design system with typed theme augmentation (declare module "@mui/material/styles") for custom palette keys.

Continue Learning

Server vs Client Components in Next.js 16 (2026 Guide) — go deeper on the Server/Client boundary this guide's "use client" theme file relies on.
How to Add Metadata in Next.js 16 (2026 Beginner's Guide) — pair this theme setup with proper per-page titles, Open Graph tags, and SEO metadata.
Next.js Rendering Strategies Explained: SSR, SSG, CSR, ISR & Cache Components (2026) — understand the streaming/hydration model that makes InitColorSchemeScript necessary in the first place.
SaaS Starter Architecture with Next.js 2026 — see where a themed component library like this one fits into a larger app structure.

📦 Source Code: View on GitHub

Your useEffect Data Fetch Might Show Stale Data If a User Navigates Quickly

Fri, 25 Sep 2026 13:18:13 +0000

This is a genuinely common race condition, and it's specifically the kind that only shows up under real usage conditions, someone clicking between items quickly, a slow network, exactly the situations casual development testing on a fast local connection rarely reproduces.

The Setup That Looks Completely Standard

'use client';
import { useState, useEffect } from 'react';

export function UserDetail({ userId }: { userId: string }) {
  const [user, setUser] = useState(null);

  useEffect(() => {
    fetch(`/api/users/${userId}`)
      .then((res) => res.json())
      .then((data) => setUser(data));
  }, [userId]);

  return <div>{user ? user.name : 'Loading...'}</div>;
}

This is close to the most common way to fetch data based on a changing prop in a Client Component, and it works completely correctly the vast majority of the time. It also has a real race condition that only shows up under a specific, genuinely common sequence of events.

The Exact Sequence That Triggers the Bug

A user clicks on user A in a list, userId becomes A's ID, the effect fires, a request for A's data starts. Before that request resolves, network latency, a slow connection, the user clicks user B instead, userId becomes B's ID, the effect fires again, a second, separate request for B's data starts. Now two requests are in flight simultaneously.

If B's request happens to resolve faster than A's, perfectly plausible depending on server load, caching, or just network variance, B's data renders correctly first. Then A's slower, now-stale request finally resolves, and its .then() callback runs setUser(data) with A's data, overwriting B's correct, current data with A's outdated, no-longer-relevant response. The component now displays user A's name and information while userId itself is actually set to B, a genuine, visible mismatch between what's shown and what's actually selected.

Why This Feels Random Rather Than Reliably Broken

This only manifests when the specific timing lines up, a slower first request resolving after a faster second one. On a fast, consistent local connection during development, requests often resolve close enough to their sending order that this exact interleaving rarely happens, which is exactly why it's easy to ship without ever seeing it locally, and exactly why it tends to surface first as a confusing, hard-to-reproduce bug report from a real user on a real, more variable connection.

The Actual Fix: Ignore Stale Responses Explicitly

'use client';
import { useState, useEffect } from 'react';

export function UserDetail({ userId }: { userId: string }) {
  const [user, setUser] = useState(null);

  useEffect(() => {
    let ignore = false;

    fetch(`/api/users/${userId}`)
      .then((res) => res.json())
      .then((data) => {
        if (!ignore) {
          setUser(data);
        }
      });

    return () => {
      ignore = true; // marks this specific effect's request as stale on cleanup
    };
  }, [userId]);

  return <div>{user ? user.name : 'Loading...'}</div>;
}

The ignore flag, scoped locally to each individual effect invocation, gets set to true in the cleanup function, which React runs automatically the moment userId changes again, before the next effect invocation starts. When A's slow request finally resolves, its specific closure's ignore flag is already true, since the effect was cleaned up the moment the user clicked B, and the stale setUser(data) call for A's outdated data simply never happens. Only B's request, whose ignore flag remains false because its effect was never cleaned up, actually updates state.

An Alternative Using AbortController

For fetch specifically, AbortController provides a more complete version of the same fix, actually canceling the in-flight request rather than just ignoring its eventual result:

useEffect(() => {
  const controller = new AbortController();

  fetch(`/api/users/${userId}`, { signal: controller.signal })
    .then((res) => res.json())
    .then((data) => setUser(data))
    .catch((err) => {
      if (err.name !== 'AbortError') {
        console.error(err); // genuinely handle real errors, ignore expected aborts
      }
    });

  return () => {
    controller.abort();
  };
}, [userId]);

This has a real advantage over the simple ignore flag, the actual network request gets canceled, not just its result discarded, which saves real bandwidth and server load for a request whose result was never going to be used anyway, particularly valuable for anything more expensive than a small JSON response.

Why This Matters More for Search and Filtering Specifically

This exact pattern shows up constantly in search-as-you-type and rapid filtering interactions, exactly the kind of interface covered in an earlier post on search and filtering patterns. A user typing quickly triggers a new request on every keystroke, and without this protection, a slower response to an earlier, now-outdated keystroke can overwrite the correct results for what the user is actually searching for right now, displaying results for a query they've already moved past.

The Actual Rule

Any effect that fetches data based on a value that can change again before the fetch resolves needs a way to distinguish a stale, no-longer-relevant response from a current one. A simple ignore flag set in the cleanup function handles this cheaply for most cases. AbortController handles it more completely, actually canceling the wasted request rather than just discarding its result, and is worth the small amount of extra code for anything with real cost behind each request, a genuinely expensive query, meaningful bandwidth, a rate-limited endpoint.

I handle this exact pattern, mostly with AbortController for anything backed by a real database query, across the dashboards and templates I build at pixelanas.com, since it's exactly the kind of subtle bug that looks fine in every casual test and only shows up once real users start clicking around at real speed.

If you've got a useEffect fetching data based on a changing prop with no stale-response handling, go test it specifically by clicking or navigating quickly between a few items in a row. If you see a flash of the wrong data settling in, that's this exact race condition. Drop what you find in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Why I stopped using online image compressors and built a CLI instead

Thu, 24 Sep 2026 07:44:12 +0000

Four years of optimizing React and Next.js projects taught me one thing: unoptimized images are everywhere, and nobody wants to fix them.

Every project has the same pattern. Heavy PNG and JPG files are sitting inside /public, there is no consistent image pipeline, and some of those files have no business being that large in a production codebase.

This is especially common in small and mid-sized projects. There is no CDN transformation layer or dedicated asset pipeline. Images get added while the product is moving quickly, and the cleanup becomes a task for “later.”

Later, of course, never comes.

Then, at 1am, while refactoring an extremely vibe-coded Next.js project, I found myself doing the cleanup manually again.

Find an image. Upload it to an online compressor. Hit the free limit. Open another tool. Convert a few more. Download everything. Replace the original files. Hunt through the codebase for every import and src path. Hope I did not miss one.

And I finally thought: I am a developer. Why am I doing this by hand?

So I built pixcrush.

npx pixcrush .

One command to convert the images, compress them, and update their matching code references automatically.

“But doesn’t Next.js already optimize images?”

Yes, and if your application uses next/image consistently, you should absolutely take advantage of it.

The Next.js <Image> component can resize images for different devices, lazy-load them, and serve modern formats such as WebP. Files inside /public can be referenced from the root URL, while statically imported images also give Next.js access to their intrinsic dimensions. The official Next.js image documentation explains these runtime optimizations in detail.

But that solves a different layer of the problem.

I wanted to clean up the source assets themselves:

Replace heavy PNG and JPG files with smaller WebP files when conversion is worthwhile.
Update existing imports and string-based image paths across the repository.
Identify images that are no longer referenced.
Make the migration reviewable before touching any files.
Keep the process useful for projects that do not consistently use next/image.

This was not about replacing the Next.js image pipeline. It was about making a tedious codebase migration safe and repeatable.

Why a simple format conversion becomes a code migration

Consider a small project with images referenced in a few different ways:

import hero from './assets/hero.png';

export function HomePage() {
  return (
    <main>
      <Image src={hero} alt="" />
      <img src="/images/team.jpg" alt="Our team" />
    </main>
  );
}

Converting hero.png and team.jpg is only half of the job. The code now points to files that no longer represent the desired output.

After the migration, the references need to become:

import hero from './assets/hero.webp';

export function HomePage() {
  return (
    <main>
      <Image src={hero} alt="" />
      <img src="/images/team.webp" alt="Our team" />
    </main>
  );
}

Now multiply that across .js, .jsx, .ts, .tsx, .html, and .json files, plus nested apps inside a Turborepo.

That is no longer an image-conversion task. It is a codemod with image processing attached.

The workflow I wanted

I wanted the tool to perform five clear phases:

Scan the repository for supported images and source files.
Determine which images are actually referenced.
Convert used PNG and JPG files to WebP.
Update only the references connected to successful conversions.
Report what changed, what was skipped, and what needs human review.

The default command is intentionally small:

npx pixcrush .

For a first pass on an unfamiliar project, I prefer starting with a dry run:

npx pixcrush . --dry-run

This previews the migration without writing files.

Step 1: Find the images and their references

pixcrush scans for PNG, JPG, and JPEG files while ignoring directories such as node_modules, .next, dist, build, and .git.

It separately collects the source files that may contain references:

.js  .jsx  .ts  .tsx  .html  .htm  .json

Finding image files is easy. Determining whether they are used is the interesting part.

For JavaScript and TypeScript, pixcrush parses the source with Babel using the JSX and TypeScript plugins. Babel’s parser produces an abstract syntax tree, which makes it possible to inspect actual string literals instead of blindly replacing every .png substring. Babel documents its JSX and TypeScript parsing support in the @babel/parser reference.

The tracker resolves several common patterns:

import logo from './logo.png';

<Image src="/images/hero.jpg" alt="" />

const imagePath = '@/assets/product.png';

It also handles image-bearing values in HTML and JSON, including srcset-style strings and query parameters.

For absolute paths such as /images/hero.jpg, pixcrush reconciles the reference with matching public directories. This matters in monorepos, where the real file may be located at something like:

apps/web/public/images/hero.jpg

Images without a resolved reference are reported as unused instead of being converted automatically.

Step 2: Convert in memory, and keep the original when WebP is larger

The actual image conversion uses Sharp, which supports WebP output and exposes a configurable quality setting.

The important part is not just calling .webp(). pixcrush creates the WebP data in memory first:

const webpBuffer = await sharp(imagePath)
  .webp({ quality })
  .toBuffer();

Sharp’s toBuffer() documentation confirms that WebP output can be generated directly as a buffer. That lets pixcrush compare the proposed output with the original before writing anything.

if (webpBuffer.length >= originalSize) {
  // Skip this conversion.
}

WebP is often smaller, but “modern format” does not automatically mean “smaller file” for every source image. If the generated WebP would be the same size or larger, pixcrush skips it.

More importantly, skipped images are not added to the rewrite map. Their code references remain unchanged.

The default WebP quality is 80, and it can be adjusted:

npx pixcrush . --quality 90

Step 3: Rewrite code without reformatting the entire file

The riskiest part of the migration is not creating a .webp file. It is changing the code safely.

A global find-and-replace is tempting:

.png → .webp

It is also far too broad. It can modify unrelated text, references to images that were skipped, or paths that do not resolve to a file pixcrush converted.

Instead, pixcrush builds a map containing only successful conversions:

/absolute/path/hero.png → /absolute/path/hero.webp

It parses each JavaScript or TypeScript source file, visits its string literals, resolves candidate image paths, and creates targeted text replacements only for matches in that conversion map.

The replacements are applied from the end of the file toward the beginning. This prevents an earlier edit from shifting the offsets required by a later edit.

There is another subtle benefit: pixcrush does not regenerate the entire source file from the AST. It replaces only the extension inside the matched string. Existing formatting, comments, quote styles, and surrounding code remain untouched.

Query strings are preserved too:

/images/hero.png?v=2

becomes:

/images/hero.webp?v=2

The safety rules matter more than the happy path

Code-modifying tools should be conservative. I would rather have pixcrush warn about one path than confidently break a project.

These are the guardrails I added:

Dry runs do not write files

npx pixcrush . --dry-run

This runs the analysis, conversion calculation, and reference-matching flow without writing the WebP files or modified source.

Dynamic paths are reported, not guessed

pixcrush can understand a static value:

<img src="/products/shoe.png" alt="" />

It cannot safely resolve every runtime value:

<img src={`/products/${product.slug}.png`} alt="" />

Dynamic template paths are warned about so they can be reviewed manually.

Parse failures block destructive cleanup

If a source file cannot be parsed, pixcrush records the failure. When --delete-originals is enabled, original and unused images are deleted only if both the analysis and rewrite phases completed without parse failures.

Framework metadata images are excluded

Files such as favicons, Apple touch icons, Open Graph images, Twitter images, and common PWA manifest icons may be discovered through framework conventions rather than ordinary source references.

pixcrush excludes these patterns from the migration instead of incorrectly treating them as orphans.

External and inline images are left alone

HTTP URLs and data: values are not local assets, so the tracker ignores them.

Running the full migration

My preferred workflow is:

# 1. Preview the migration
npx pixcrush . --dry-run

# 2. Review the reported conversions, warnings, and unused files

# 3. Run the migration
npx pixcrush .

# 4. Run the application and its tests

# 5. Remove converted originals only when ready
npx pixcrush . --delete-originals

The final summary includes:

Images converted
Space saved
Source files updated
Unused images detected
Dynamic references or parsing issues requiring review

I still recommend running this on a clean Git branch. A dry run reduces surprises; Git gives you the final, exact review surface.

What pixcrush does not handle yet

The current limitations are intentional and worth stating clearly:

CSS files are not parsed, so references inside url(...) are not rewritten. An image referenced only from CSS may also appear in the unused-image report; review that list carefully before using --delete-originals.
Dynamic paths are detected but not automatically converted.
The image inputs are currently PNG, JPG, and JPEG.
Framework-convention metadata images are excluded for safety.

If a project relies heavily on CSS backgrounds or dynamically generated filenames, expect some manual work after the automated pass.

“Automated” should not mean “pretend every edge case is safe.”

What changed for me

The biggest improvement is not that Sharp can produce a WebP file. The biggest improvement is that the full cleanup is now one reviewable operation.

The old workflow looked like this:

find → upload → hit a limit → try another tool → download
→ replace files → search the codebase → update paths → repeat

The new workflow is:

npx pixcrush . --dry-run
npx pixcrush .

That is the kind of automation I like: not a new platform, dashboard, subscription, or upload queue. Just a local tool that removes a chore and then gets out of the way.

Try it

pixcrush is open source and runs locally:

npx pixcrush .

If you try it on a real React, Next.js, or Turborepo project, I would especially love feedback on path-resolution edge cases and file types worth supporting next.

Connect with me ✌🏻:

LinkedIn: Karishma garg
Twitter: _karishma10
GitHub: karishma-dev
Portfolio: www.karishma.dev

That bcrypt.hash(password, 10) You Copy-Pasted Might Not Be as Secure as You Think

Wed, 23 Sep 2026 11:43:06 +0000

Almost every auth tutorial, including some of my own examples in earlier posts, uses bcrypt.hash(password, 10) without much explanation of what that number actually controls or why it's 10 specifically rather than some other value. It's worth understanding, because the right number isn't fixed, it's a moving target that most codebases never revisit after the initial copy-paste.

What the Salt Rounds Number Actually Controls

bcrypt's cost factor, the second argument, controls how computationally expensive hashing a single password is, specifically by determining how many times an internal key-setup routine repeats. It's not a linear scale, each increment roughly doubles the computation required. A cost factor of 10 means roughly 1,024 iterations of that internal routine. 11 means roughly 2,048. 12 means roughly 4,096.

This deliberate slowness is the entire point. A fast hash function is great for most use cases and terrible for passwords specifically, since a fast hash lets an attacker who's obtained a database of hashed passwords try billions of guesses per second against them. A deliberately slow hash function directly limits how many guesses an attacker can attempt in any given amount of time, even with significant computing power.

Why 10 Specifically, and Why That's Worth Questioning

The number 10 shows up constantly in tutorials and documentation because it was, at the time much of that content was written, a reasonable balance, slow enough to meaningfully limit brute-force attempts, fast enough not to noticeably slow down a real login flow for a legitimate user. That balance point depends entirely on how fast the hardware attempting to brute-force it actually is, and hardware, particularly specialized hardware built for exactly this kind of computation, gets faster every year. A cost factor considered a reasonable balance several years ago represents meaningfully less real protection against modern hardware than it did when that number first became the common default.

Why This Doesn't Show Up as an Obvious Problem

There's no error, no warning, no visible symptom of a salt rounds value that's become outdated relative to current hardware capability. Login continues working exactly as expected for legitimate users. The gap is entirely about resistance to an offline brute-force attempt against a stolen password database, something that only becomes relevant if that database is ever actually compromised, which means the weakness sits completely invisible until the exact moment it matters most.

The Actual Guidance, and Why It's a Moving Target Rather Than a Fixed Number

Security guidance on this specific number gets revised periodically as hardware capability changes, and current recommendations from security-focused organizations trend higher than the value that shows up in most existing tutorials and codebases. Rather than citing a specific number here that will itself become outdated, the actual, durable guidance is this, check current recommendations specifically when setting this up, rather than trusting whatever number happens to be sitting in the tutorial or codebase you're referencing, since that number is a snapshot of a past moment, not a permanently correct value.

A Practical Way to Choose the Right Number for Your Own Server

// A quick, practical way to find a cost factor appropriate for your actual hardware,
// rather than trusting a number copied from somewhere else
import bcrypt from 'bcryptjs';

async function benchmarkCostFactor(rounds: number) {
  const start = Date.now();
  await bcrypt.hash('benchmark-password', rounds);
  return Date.now() - start;
}

// Run this on your actual production server or equivalent hardware,
// and pick the highest cost factor where a single hash still completes
// in a reasonable time for your login flow, commonly cited targets
// are in the range of a few hundred milliseconds

This gives you a real, current answer specific to your actual infrastructure, rather than a number that was correct for someone else's hardware at some point in the past and has simply been carried forward through tutorials and copy-paste ever since.

The Broader Rule This Points To

A security parameter borrowed from a tutorial is a snapshot of what was reasonable when that tutorial was written, not a permanently correct value. This applies beyond just bcrypt cost factors, TLS cipher suite choices, JWT expiration windows, rate limit thresholds, all of these are calibrated against assumptions, about hardware, about attacker capability, about acceptable risk, that shift over time. A value copied once and never revisited quietly drifts from "reasonable" toward "outdated" without any code change ever signaling that drift.

What to Actually Do About Your Own Codebase

Check what cost factor your app is actually using right now, and compare it against current guidance rather than assuming a number from an older tutorial or your own original setup is still appropriate. If it's genuinely outdated, increasing it is straightforward for new passwords going forward, though existing stored hashes were created with the old cost factor and remain at that lower value unless you specifically implement a rehash-on-next-login pattern, checking and upgrading a user's stored hash cost factor the next time they successfully log in with their correct password.

Check what cost factor your own app is actually using, and when you last revisited that number versus just inheriting it from the original setup or a tutorial. Drop what you find in the comments, genuinely curious how many people have actually reconsidered this since first setting it up versus never touching it again.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Why Your Next.js Modal Route Works Perfectly Until Someone Refreshes the Page

Tue, 22 Sep 2026 08:14:06 +0000

This one isn't really a bug, it's a genuinely common point of confusion about a feature working exactly as designed, and understanding why it behaves this way changes how you'd actually build around it, rather than fighting it.

Intercepting routes are what makes an Instagram-style interaction possible in the App Router, click a photo in a grid, it opens as a modal overlay on top of the current page, without a full navigation, while the URL still updates to something shareable and bookmarkable.

app/
├── @modal/
│   ├── default.tsx
│   └── (.)photo/
│       └── [id]/
│           └── page.tsx    // renders as a modal when intercepted
├── photo/
│   └── [id]/
│       └── page.tsx        // the actual full page
├── layout.tsx
└── page.tsx                 // the grid

Click a photo from the grid, and the (.)photo/[id] route intercepts the navigation, rendering the modal version in the @modal slot on top of the grid, without a full page transition. The URL correctly updates to /photo/123. It feels seamless, and it's a genuinely well-built pattern for exactly this kind of interaction.

Where the Confusion Starts

Someone building this, testing by clicking through the grid, sees exactly the intended modal behavior. Then they refresh the page while the modal is open, or share that /photo/123 URL with someone else, or that someone else pastes it directly into a new browser tab, and instead of the modal, they get the full, standalone photo/[id]/page.tsx page, no grid behind it, no modal chrome, just the plain page rendering on its own.

The natural first reaction is that something's broken, the modal "isn't working" on refresh. It's actually working exactly as designed, just not in the way that first reaction assumes.

Why This Is Correct, Not Broken

Interception is specifically a client-side navigation behavior. It only intercepts a navigation that happens through Next.js's client-side router, clicking a <Link>, calling router.push(), moving from one already-loaded page to another within the same app session. A hard refresh, a direct URL visit, or someone opening that link in a completely fresh browser tab isn't a client-side navigation at all, it's a fresh, full server request for that specific URL, with no prior page state to intercept from, no grid already rendered behind it to interrupt. Next.js correctly falls back to rendering the actual underlying route, the full page, because that's genuinely the only thing that makes sense in a context where there's no previous client-side navigation to interrupt in the first place.

This is why the folder structure includes both the intercepted route ((.)photo/[id], the modal version) and the actual route (photo/[id], the full page) as separate, real routes. The full page isn't a fallback or an error state, it's the intended, correct experience for anyone arriving at that URL directly, someone who shared or bookmarked the link, a search engine crawling it, anyone without an existing client-side session to interrupt.

The Actual Design Implication

This isn't something to work around, it's something to design for deliberately. The full, non-modal version of the route needs to be a genuinely complete, standalone page on its own merits, not a stripped-down fallback that only half-works, since a real share of your actual traffic to that URL, direct visits, refreshes, shared links, search engines, will land there specifically, not on the modal version.

// app/photo/[id]/page.tsx
// This needs to be a genuinely complete page, not an afterthought,
// since direct visits, refreshes, and shared links all land here specifically
export default async function PhotoPage({ params }) {
  const { id } = await params;
  const photo = await getPhoto(id);

  return (
    <div>
      <BackToGridLink /> {/* since there's no grid rendered behind this version */}
      <PhotoDisplay photo={photo} />
      <PhotoMetadata photo={photo} />
    </div>
  );
}

Including something like a clear way back to the grid, since this version genuinely doesn't have the grid rendered behind it the way the modal does, treats this as the real, complete experience it needs to be for a meaningful share of actual visitors, rather than assuming everyone always arrives via the modal path.

Why This Actually Matters for SEO Too

This split has a genuine upside worth being deliberate about. Since the full page is a real, standalone route, it's exactly what search engines actually crawl and index, a real, complete, server-rendered page for that specific photo, with its own metadata, its own content, rather than something only reachable through a client-side modal interaction a crawler would never trigger. Building the full page version to be genuinely complete isn't just handling an edge case gracefully, it's the version doing real SEO work for that specific piece of content.

The Actual Rule

Intercepting routes are a client-side navigation enhancement layered on top of real, independently functional routes, not a replacement for them. The full, non-intercepted version of the route needs to be built as a genuinely complete experience on its own, since refreshes, direct visits, shared links, and search engine crawlers all land there specifically, not on the modal version, and treating it as an afterthought means a real share of your actual traffic gets an incomplete experience.

If you're building or have built an intercepting route pattern, worth checking whether the full, non-modal version genuinely stands on its own, or was built assuming everyone always arrives through the modal. Drop your experience with this pattern in the comments, curious how many people hit this exact confusion the first time before understanding why it's actually correct.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Multi-Tenant Architecture in Next.js 16 (2026)

Sun, 20 Sep 2026 03:02:16 +0000

Every SaaS product hits the same wall eventually: you built it for one company, and now you need it to work for a hundred — each with their own users, their own data, and their own little corner of the app, like acme.yourapp.com. Bolt that on badly and you get the nightmare scenario every backend developer fears: one bug in a WHERE clause, and Company A's customer list shows up in Company B's dashboard.

That's the entire problem multi-tenant architecture solves. It's not one trick — it's a set of decisions about routing, data isolation, and access control that, done right, make "which company does this user belong to?" a question your app can never get wrong, even if a developer forgets to ask it.

By the end of this guide, you'll have a working multi-tenant Next.js 16 app: subdomain-based routing through proxy.ts, a tenant data model backed by Postgres Row Level Security so isolation is enforced by the database — not just your application code — and a path to deploying it on Vercel with wildcard domains.

Quick Answer: What Is Multi-Tenant Architecture?

Multi-tenant architecture is a software design where a single application instance and (usually) a single database serve multiple independent customers — called tenants — while keeping each tenant's data, users, and configuration completely isolated from every other tenant. Instead of deploying a separate copy of your app per customer, one codebase and one deployment serve everyone, and the app itself decides which tenant a request belongs to and what data that tenant is allowed to see.

Think of it like an apartment building: one building (your app), many separate units (tenants), each with its own locked door (data isolation) — but the plumbing, the elevator, and the foundation (your codebase and infrastructure) are shared.

Single-Tenant vs. Multi-Tenant: The Difference That Matters

	Single-Tenant	Multi-Tenant
Deployment	One app + one database per customer	One app (usually one database) for all customers
Infrastructure cost	Scales linearly with customers	Shared, scales with usage not customer count
Data isolation	Physical (separate databases)	Logical (enforced in code and/or the database)
Updates/bug fixes	Deploy to every customer separately	Deploy once, everyone gets it
Customization per customer	Easy — each customer has an isolated deployment/configuration	Harder — needs a plan/feature-flag system
Best for	Enterprise clients needing full data isolation or compliance	SaaS products with many small-to-mid customers

Many collaboration and SaaS platforms expose workspace/organization concepts that follow the multi-tenant model. You don't get your own copy of Slack's servers when you sign up; you get a workspace, which is just a tenant inside their shared infrastructure.

💡 Tip: "Tenant" is deliberately generic — in your app it might be called a workspace, organization, team, company, or account. The underlying pattern is identical regardless of what you call it in your UI.

Why This Is Tricky

Multi-tenancy isn't hard because the concept is complicated — it's hard because the cost of getting it wrong is severe (a data leak between customers), and there are genuinely several valid ways to build it, each with real tradeoffs. Before writing any code, you need to answer two separate questions:

How do I identify which tenant a request belongs to? (subdomain, custom domain, or URL path)
How do I keep each tenant's data isolated? (separate databases, separate schemas, or one shared table set with a tenant_id column)

Get the first one wrong and tenants can't reach the right version of your app. Get the second one wrong and — worst case — tenants can see each other's data. We'll cover both, and this guide focuses on the combination most SaaS products actually ship with: subdomain-based routing plus a shared database with row-level isolation, because it's the cheapest to run and the fastest to build on, while still giving you database-enforced security.

The Three Data Isolation Models

Model	How it works	Isolation strength	Cost & complexity
Database-per-tenant	Every tenant gets a fully separate database	Strongest — physical separation	Highest — migrations, backups, and connections multiply per tenant
Schema-per-tenant	One database, one Postgres schema per tenant	Strong — separate tables per tenant	Medium — still need to manage N schemas, but one database to back up
Shared tables + `tenant_id`	One database, one set of tables, every row tagged with a `tenant_id`	Depends entirely on enforcement — weak if only in app code, strong with Postgres Row Level Security	Lowest — one schema, one migration, scales to thousands of tenants easily

For most SaaS products — and everything in this guide — shared tables with a tenant_id column, enforced by Postgres Row Level Security (RLS), is the right default. It's the cheapest to operate, the easiest to migrate, and — critically — RLS means isolation is enforced by the database itself, not just by remembering to add .eq("tenant_id", ...) to every query. Reach for schema-per-tenant or database-per-tenant only when a specific customer has a compliance requirement (like data residency) that a shared database genuinely can't satisfy.

Related: Supabase RLS Policy Generator — generates the exact kind of tenant-scoped policies this guide writes by hand, in seconds.

Three Ways to Identify a Tenant

Strategy	Example URL	Pros	Cons
Subdomain	`acme.yourapp.com`	Clean URLs, easy to brand, works great with wildcard SSL	Needs wildcard DNS + nameserver setup
Custom domain	`app.acme.com`	Best for enterprise/white-label, tenant owns their domain	Most setup work — DNS verification, SSL provisioning per domain
Path-based	`yourapp.com/acme/dashboard`	Zero DNS config, works anywhere immediately	Tenant is visible and editable in every URL, no per-tenant branding

This guide builds subdomain-based routing, since it's the sweet spot most SaaS products land on — better UX and branding than path-based, far less setup work than per-tenant custom domains. We'll touch on custom domains near the end for when you're ready to offer that too.

What We're Building

Next.js 16 with the App Router
TypeScript in strict mode
Supabase (Postgres) for the database, using Row Level Security for tenant isolation
Tailwind CSS for the (minimal) UI

By the end, visiting acme.localhost:3000 will resolve to Acme's tenant context, acme.yourapp.com will do the same in production, and every database query for tenant data will be protected by RLS — so even a bug in your own code can't leak one tenant's rows to another.

tenant1.yourapp.com/dashboard
        ↓
   proxy.ts resolves "tenant1" → looks up tenant in DB
        ↓
   Tenant ID attached to the request as a header
        ↓
   Server Component reads the header, fetches tenant-scoped data
        ↓
   Postgres RLS double-checks: is this row actually this tenant's?

Step 1: Project Setup

If you're starting fresh:

npx create-next-app@latest multi-tenant-app

Choose TypeScript, Tailwind CSS, App Router, and the src/ directory if you prefer it (this guide omits src/ for shorter paths). You'll also need Supabase:

npm install @supabase/supabase-js @supabase/ssr

Add your environment variables:

# .env.local
NEXT_PUBLIC_SUPABASE_URL=https://yourproject.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your_publishable_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# The root domain your app is served from. In development this keeps
# its port (localhost:3000); in production it's your bare domain.
NEXT_PUBLIC_ROOT_DOMAIN=localhost:3000

⚠️ Common Mistake: SUPABASE_SERVICE_ROLE_KEY must never be prefixed with NEXT_PUBLIC_. It bypasses every Row Level Security policy in your database — treat it exactly like a database root password, server-only, never shipped to the browser.

Step 2: Resolve the Tenant in `proxy.ts`

In Next.js 16, the file previously called middleware.ts was renamed to proxy.ts — same job, same file conventions, just a new name and a change in default runtime (it now runs on the Node.js runtime by default, which matters here since we're making a database call on every request).

💡 Think of proxy.ts like a receptionist at the front desk of your building. Every visitor (request) talks to the receptionist first. The receptionist checks which company (tenant) they're visiting based on which door they walked through (the subdomain), confirms that company actually exists in the building directory, and then tells the elevator (your app) exactly where to send them — before the visitor ever reaches an office.

First, a small server-only lookup function:

// lib/supabase/service-client.ts
import "server-only";
import { createClient } from "@supabase/supabase-js";

// Service-role client — bypasses RLS, has no user session attached.
// Only ever call this for trusted, server-only reads like tenant lookups.
// Never import this into a Client Component.
export const supabaseAdmin = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

// lib/tenant/get-tenant-by-subdomain.ts
import "server-only";
import { supabaseAdmin } from "@/lib/supabase/service-client";

export type TenantSummary = {
  id: string;
  slug: string;
};

export async function getTenantBySubdomain(
  subdomain: string
): Promise<TenantSummary | null> {
  const { data, error } = await supabaseAdmin
    .from("tenants")
    .select("id, slug")
    .eq("slug", subdomain)
    .maybeSingle();

  if (error || !data) return null;
  return data;
}

If you already have Supabase auth wired up (see our Supabase Auth vs Firebase Auth guide if not), you likely already have these two files for keeping the auth session refreshed on every request:

// lib/supabase/proxy.ts
import { createServerClient } from "@supabase/ssr";
import { NextResponse, type NextRequest } from "next/server";

export async function updateSession(request: NextRequest) {
    let supabaseResponse = NextResponse.next({ request });

    const supabase = createServerClient(
        process.env.NEXT_PUBLIC_SUPABASE_URL!,
        process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
        {
            cookies: {
                getAll() {
                    return request.cookies.getAll();
                },

                setAll(cookiesToSet, headers) {
                    cookiesToSet.forEach(({ name, value }) =>
                        request.cookies.set(name, value)
                    );

                    supabaseResponse = NextResponse.next({
                        request,
                    });

                    cookiesToSet.forEach(({ name, value, options }) =>
                        supabaseResponse.cookies.set(name, value, options)
                    );
                    Object.entries(headers).forEach(([key, value]) =>
                        supabaseResponse.headers.set(key, value)
                    );
                },
            },
        }
    );

    await supabase.auth.getClaims();

    return supabaseResponse;
}

// lib/supabase/server.ts
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

export async function createClient() {
  const cookieStore = await cookies();

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll();
        },

        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            );
          } catch {
            // Ignore if called from Server Component
          }
        },
      },
    }
  );
}

⚠️ Don't skip this if you have authentication. Tenant resolution and session refresh are two separate concerns, but they both have to happen in the same proxy.ts run. If you only resolve the tenant and never call updateSession, Supabase's access token is never refreshed on the server, and signed-in users get logged out once it expires — even though nothing about tenant routing looks broken.

Now the proxy itself, composing both:

// proxy.ts
import { NextRequest, NextResponse } from "next/server";
import { updateSession } from "@/lib/supabase/proxy";
import { getTenantBySubdomain } from "@/lib/tenant/get-tenant-by-subdomain";

// Keep the port for building an absolute redirect URL later; strip it
// only when comparing hostnames.
const ROOT_DOMAIN_ENV = process.env.NEXT_PUBLIC_ROOT_DOMAIN ?? "localhost:3000";
const ROOT_DOMAIN = ROOT_DOMAIN_ENV.split(":")[0];

// Subdomains that belong to your main app, not a tenant.
const RESERVED_SUBDOMAINS = new Set(["www", "app", "admin", "api"]);

export async function proxy(request: NextRequest) {
  // Refresh the Supabase auth session first. This may rewrite Set-Cookie
  // headers if the access token needed rotating — we copy those onto
  // whatever response we ultimately return below.
  const supabaseResponse = await updateSession(request);

  const host = (request.headers.get("host") ?? "").split(":")[0];
  const subdomain = getSubdomain(host);

  // No subdomain, or a reserved one — this is the marketing site or the
  // main app shell, not a tenant. Nothing tenant-related to attach.
  if (!subdomain || RESERVED_SUBDOMAINS.has(subdomain)) {
    return supabaseResponse;
  }

  const tenant = await getTenantBySubdomain(subdomain);

  if (!tenant) {
    return redirectToTenantNotFound(request, subdomain);
  }

  // Strip any inbound tenant headers so a client can never forge them —
  // only this proxy is allowed to set x-tenant-*.
  const requestHeaders = new Headers(request.headers);
  requestHeaders.delete("x-tenant-id");
  requestHeaders.delete("x-tenant-slug");
  requestHeaders.set("x-tenant-id", tenant.id);
  requestHeaders.set("x-tenant-slug", tenant.slug);

  // Rebuild the response so the tenant headers ride along on the
  // *request* (this is what makes them readable via headers() in a
  // Server Component), then carry over any refreshed auth cookies.
  const response = NextResponse.next({ request: { headers: requestHeaders } });
  supabaseResponse.cookies.getAll().forEach((cookie) => {
    response.cookies.set(cookie);
  });

  return response;
}

// Redirects to the ROOT domain, not the unknown tenant's subdomain —
// redirecting back to the same bad host would just re-trigger this
// same lookup and loop forever.
//
// Built as a brand-new URL rather than mutating a clone of request.url.
// Cloning request.url first (new URL(request.url)) means the object
// starts out with the tenant subdomain already baked into it, and
// reassigning .host on that object is not reliable for fully replacing
// an existing hostname — in practice it can end up only changing the
// port and leaving the old subdomain in place (e.g. producing
// "unknowndomain.localhost:3000" instead of "localhost:3000"), which
// silently recreates the exact loop this function exists to prevent.
// Constructing the URL from a plain template string sidesteps that
// entirely, since there's no stale hostname left for anything to retain.
function redirectToTenantNotFound(request: NextRequest, subdomain: string) {
  const protocol = request.nextUrl.protocol; // "http:" or "https:"
  const notFoundUrl = new URL(`${protocol}//${ROOT_DOMAIN_ENV}/tenant-not-found`);
  notFoundUrl.searchParams.set("tenant", subdomain);
  return NextResponse.redirect(notFoundUrl);
}

function getSubdomain(host: string): string | null {
  if (host === ROOT_DOMAIN || host === `www.${ROOT_DOMAIN}`) return null;
  if (!host.endsWith(`.${ROOT_DOMAIN}`)) return null;

  return host.slice(0, -(ROOT_DOMAIN.length + 1));
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

What's happening here:

updateSession(request) runs first and unconditionally — auth refresh shouldn't depend on whether the host happens to be a tenant subdomain.
redirectToTenantNotFound() builds a brand-new URL pointed at ROOT_DOMAIN_ENV (your real app domain) instead of the unresolved tenant subdomain. The next time proxy runs against that new URL, getSubdomain() returns null for the root domain and the request just passes through — no loop. This has to be a fresh URL, not a mutated clone of the incoming request's URL — cloning request.url first means the tenant subdomain is already baked into the object, and reassigning .host on it is not reliable for fully replacing that hostname (in practice it can end up changing only the port while the old subdomain silently survives, e.g. unknowndomain.localhost:3000 instead of localhost:3000), which just recreates the same loop this function exists to prevent.
The ?tenant= query param survives the redirect, so your /tenant-not-found page can show which subdomain didn't resolve.
We only build requestHeaders (and delete any inbound x-tenant-* values) once we know a real tenant was found — there's nothing to strip or attach on the reserved/no-subdomain path, since supabaseResponse is returned as-is.
supabaseResponse.cookies.getAll() returns whatever refreshed auth cookies Supabase's client queued up; copying them onto the new tenant-aware response means neither concern silently overwrites the other.

A minimal page for the redirect target:

// app/tenant-not-found/page.tsx
interface PageProps {
  searchParams: Promise<{ tenant?: string }>;
}

export default async function TenantNotFoundPage({ searchParams }: PageProps) {
  const { tenant } = await searchParams;

  return (
    <div className="mx-auto max-w-md space-y-3 p-8 text-center">
      <h1 className="text-2xl font-semibold">Workspace not found</h1>
      <p className="text-sm text-muted-foreground">
        {tenant
          ? `We couldn't find a workspace at "${tenant}".`
          : "That workspace doesn't exist."}
      </p>
    </div>
  );
}

⚠️ Common Mistake: Running your tenant lookup on the Edge runtime by explicitly setting runtime: 'edge'. Don't — proxy.ts in Next.js 16 runs on the Node.js runtime by default (and throws if you try to override it), which is exactly what you want here, since a database client typically needs Node.js APIs that aren't available on the Edge runtime.

💡 Tip: For a small application, this direct indexed lookup is straightforward. At higher traffic, cache the subdomain → tenant mapping in Redis/KV/Edge Config or another low-latency store so proxy doesn't hit Postgres on every request.

Step 3: Testing Subdomains Locally

You don't need to edit your /etc/hosts file for this. Modern browsers (Chrome, Firefox, Safari) automatically resolve any *.localhost address to 127.0.0.1 — it's a reserved TLD, not a Next.js feature. So once your dev server is running:

npm run dev

Visiting http://acme.localhost:3000 in your browser just works, as long as NEXT_PUBLIC_ROOT_DOMAIN=localhost:3000 is set in .env.local and a tenant with slug = 'acme' exists in your database.

💡 Tip: If a subdomain isn't resolving locally, it's almost always a browser/network quirk (some corporate VPNs or older browsers don't support .localhost resolution) rather than a bug in your code — try a different browser before debugging proxy.ts.

Step 4: Model Tenants and Isolation in Postgres

This is the part that actually keeps tenants' data apart. Run this in the Supabase SQL editor.

-- Core tenant table. The slug doubles as a DNS label (acme.yourapp.com),
-- so its constraint is stricter than a generic "url-safe string" check:
-- no leading/trailing hyphens, and capped at 63 characters (the DNS
-- label limit), on top of lowercase alphanumerics and hyphens.
create table public.tenants (
  id uuid primary key default gen_random_uuid(),
  slug text unique not null check (
    char_length(slug) between 1 and 63
    and slug ~ '^[a-z0-9-]+$'
    and slug !~ '(^-|-$)'
  ),
  name text not null,
  plan text not null default 'free',
  created_at timestamptz not null default now()
);

-- Who belongs to which tenant, and with what role
create table public.memberships (
  user_id uuid not null references auth.users(id) on delete cascade,
  tenant_id uuid not null references public.tenants(id) on delete cascade,
  role text not null default 'member' check (role in ('owner', 'admin', 'member')),
  created_at timestamptz not null default now(),
  primary key (user_id, tenant_id)
);

-- An example tenant-scoped resource — every real table in your app
-- (invoices, documents, tasks, whatever) follows this same shape.
create table public.projects (
  id uuid primary key default gen_random_uuid(),
  tenant_id uuid not null references public.tenants(id) on delete cascade,
  name text not null,
  created_at timestamptz not null default now()
);

-- The composite primary key (user_id, tenant_id) already gives Postgres
-- a btree index usable for "where user_id = ?" lookups, since a
-- multi-column index supports equality search on a leading prefix of
-- its columns — a separate single-column index on user_id would just
-- be a redundant duplicate. What that composite index can't serve
-- efficiently is "where tenant_id = ?" on its own, since tenant_id
-- isn't the leading column — that's the index actually worth adding.
create index idx_memberships_tenant_id on public.memberships (tenant_id);
create index idx_projects_tenant_id on public.projects (tenant_id);

alter table public.tenants enable row level security;
alter table public.memberships enable row level security;
alter table public.projects enable row level security;

What's happening here: tenants is your list of customers. memberships is the join table linking Supabase's built-in auth.users to tenants — one user can belong to multiple tenants (think: a consultant working with several client workspaces). projects is a stand-in for any real, tenant-owned data table — invoices, documents, tasks, whatever your app actually stores.

Write the RLS Policies

A tenant_id column on a table means nothing on its own — it's just data. Row Level Security is what turns that column into an actual security boundary, enforced by Postgres itself rather than trusted to every query you (or a future teammate) ever write.

-- Security-definer helper: returns every tenant_id the current user
-- belongs to. Wrapping it this way avoids the classic recursive-RLS
-- trap (a policy on "projects" querying "memberships", which has its
-- own RLS that would otherwise re-trigger the same check).
--
-- It lives in a dedicated "private" schema rather than "public" —
-- Supabase's Data API (PostgREST) only exposes schemas you've explicitly
-- opted into (public by default), so putting security-definer functions
-- in "private" keeps them uncallable directly over the REST/RPC API.
-- A security-definer function sitting in "public" is callable by anyone
-- who can reach your API, running with the *creator's* privileges —
-- that's a real privilege-escalation surface if it isn't locked down.
create schema if not exists private;

create or replace function private.user_tenant_ids()
returns setof uuid
language sql
security definer
stable
set search_path = ''
as \(
  select tenant_id
  from public.memberships
  where user_id = (select auth.uid())
\);

-- Postgres grants EXECUTE on every new function to PUBLIC by default —
-- revoke it explicitly, then grant only to the role that actually needs it.
revoke execute on function private.user_tenant_ids() from public;
revoke execute on function private.user_tenant_ids() from anon;
grant usage on schema private to authenticated;
grant execute on function private.user_tenant_ids() to authenticated;

-- Members can see their own membership rows
create policy "memberships_select_own"
on public.memberships
for select
to authenticated
using ( user_id = (select auth.uid()) );

-- Members can see the tenants they belong to
create policy "tenants_select_member"
on public.tenants
for select
to authenticated
using ( id in (select private.user_tenant_ids()) );

-- Members can only see, create, edit, or delete projects that belong
-- to a tenant they're actually part of
create policy "projects_select_tenant_member"
on public.projects
for select
to authenticated
using ( tenant_id in (select private.user_tenant_ids()) );

create policy "projects_insert_tenant_member"
on public.projects
for insert
to authenticated
with check ( tenant_id in (select private.user_tenant_ids()) );

create policy "projects_update_tenant_member"
on public.projects
for update
to authenticated
using ( tenant_id in (select private.user_tenant_ids()) )
with check ( tenant_id in (select private.user_tenant_ids()) );

create policy "projects_delete_tenant_member"
on public.projects
for delete
to authenticated
using ( tenant_id in (select private.user_tenant_ids()) );

What's happening here: user_tenant_ids() is a security definer function — it runs with elevated privileges internally, which lets it read memberships (bypassing that table's own RLS just for this lookup) without creating a circular dependency. set search_path = '' forces every identifier inside the function body to be fully schema-qualified (notice public.memberships, not just memberships) — without this, a malicious or accidental object created earlier in the search path could get resolved instead of the table you actually meant, which is exactly the class of attack Supabase's own linter flags as "Function Search Path Mutable." The revoke/grant pair closes the other half of the gap: by default Postgres lets any role call a newly created function, so without the explicit revoke, anon (unauthenticated requests) could call it too.

Every policy on projects then just asks "is this row's tenant_id one this user belongs to?" Wrapping auth.uid() in (select ...) lets Postgres cache the result once per statement instead of re-evaluating it for every row — a meaningful performance win once your tables have real data in them.

💡 Tip: Notice there's no policy granting using (true) anywhere. Every single operation is explicitly scoped to tenant membership — this is deliberate. A missing policy means Postgres denies access by default, which is exactly the fail-safe direction you want security to fail in.

⚠️ Common Mistake: Putting a security definer helper function in the public schema "because that's where everything else is." If a schema is exposed through Supabase's Data API settings (public is, by default), every function in it is a potential RPC endpoint — private (or any schema you deliberately keep out of the exposed-schemas list) is the safer default for anything that runs with elevated privileges.

Related: Supabase Auth vs Firebase Auth in 2026 if you haven't wired up authentication yet.

Step 5: Read the Tenant in Server Components

Now that proxy.ts attaches x-tenant-id to every request, build a small Data Access Layer function that reads it — this is the single place the rest of your app goes to ask "which tenant is this?"

// lib/tenant/get-current-tenant.ts
import "server-only";
import { cache } from "react";
import { headers } from "next/headers";
import { redirect } from "next/navigation";
import { supabaseAdmin } from "@/lib/supabase/service-client";

export type Tenant = {
  id: string;
  slug: string;
  name: string;
  plan: string;
};

export const getCurrentTenant = cache(async (): Promise<Tenant> => {
  const headersList = await headers();
  const tenantId = headersList.get("x-tenant-id");

  if (!tenantId) {
    // No tenant header means this request never went through a tenant
    // subdomain — proxy.ts only sets it for tenant*.yourapp.com traffic.
    redirect("/");
  }

  const { data: tenant, error } = await supabaseAdmin
    .from("tenants")
    .select("id, slug, name, plan")
    .eq("id", tenantId)
    .maybeSingle();

  if (error || !tenant) {
    redirect("/tenant-not-found");
  }

  return tenant;
});

What's happening here: headers() is async in Next.js 16, so it has to be awaited. Wrapping the whole function in React's cache() means no matter how many components on the same page call getCurrentTenant(), the actual header read and database lookup only run once per request.

Next, a helper that also confirms the signed-in user actually belongs to this tenant — not just that the tenant exists:

// lib/tenant/require-tenant-member.ts
import "server-only";
import { redirect } from "next/navigation";
import { createClient } from "@/lib/supabase/server";
import { getCurrentTenant } from "./get-current-tenant";

export async function requireTenantMember() {
  const tenant = await getCurrentTenant();
  const supabase = await createClient();

  const {
    data: { user },
  } = await supabase.auth.getUser();

  if (!user) {
    redirect(`/login?tenant=${tenant.slug}`);
  }

  // This query runs through the cookie-based client, so RLS applies —
  // it can only ever return a row for the signed-in user themselves.
  const { data: membership } = await supabase
    .from("memberships")
    .select("role")
    .eq("tenant_id", tenant.id)
    .eq("user_id", user.id)
    .maybeSingle();

  if (!membership) {
    redirect("/not-a-member");
  }

  return { tenant, user, role: membership.role };
}

Use it in a page:

// app/dashboard/page.tsx
import { requireTenantMember } from "@/lib/tenant/require-tenant-member";
import { createClient } from "@/lib/supabase/server";

export default async function DashboardPage() {
  const { tenant, user } = await requireTenantMember();
  const supabase = await createClient();

  // The explicit tenant_id filter selects the active tenant represented
  // by this request. RLS provides the database-level safety net that
  // prevents the signed-in user from accessing tenants they don't belong to.
  const { data: projects } = await supabase
    .from("projects")
    .select("id, name, created_at")
    .eq("tenant_id", tenant.id)
    .order("created_at", { ascending: false });

  return (
    <div className="mx-auto max-w-2xl space-y-6 p-8">
      <div>
        <h1 className="text-2xl font-semibold">{tenant.name}</h1>
        <p className="text-sm text-muted-foreground">Signed in as {user.email}</p>
      </div>

      <ul className="space-y-2">
        {projects?.map((project) => (
          <li key={project.id} className="rounded-lg border p-3">
            {project.name}
          </li>
        ))}
      </ul>
    </div>
  );
}

What's happening here: notice the .eq("tenant_id", tenant.id) filter is still there in the app code, even though RLS would block cross-tenant rows either way. This is defense in depth — the query filter makes the intent obvious to any developer reading the code, and RLS is the safety net that catches the case where someone forgets it.

Writing Tenant-Scoped Data with a Server Action

// actions/create-project.ts
"use server";

import { revalidatePath } from "next/cache";
import { createClient } from "@/lib/supabase/server";
import { requireTenantMember } from "@/lib/tenant/require-tenant-member";

export async function createProject(formData: FormData) {
  const { tenant } = await requireTenantMember();
  const supabase = await createClient();

  const name = (formData.get("name") as string | null)?.trim();

  if (!name) {
    return { error: "Project name is required." };
  }

  const { error } = await supabase
    .from("projects")
    .insert({ name, tenant_id: tenant.id });

  if (error) {
    return { error: error.message };
  }

  revalidatePath("/dashboard");
  return { success: true };
}

What's happening here: requireTenantMember() runs first, so an unauthenticated or non-member request never reaches the database at all. Even so, the insert explicitly sets tenant_id: tenant.id rather than trusting a value from the form — never let tenant identity come from client-submitted data, always derive it server-side from the resolved tenant context.

⚠️ Common Mistake: Accepting a tenantId field from formData or a request body and trusting it. The tenant a user is allowed to write to should always come from getCurrentTenant() / the resolved request context — never from anything the client sent.

Related: Role-Based Access Control (RBAC) in Next.js 16 pairs naturally with this — once you have tenants, you'll usually want owner/admin/member permissions within each tenant too, not just membership.

Step 6: Deploy Wildcard Domains on Vercel

To get acme.yourapp.com, beta-co.yourapp.com, and every future tenant's subdomain working automatically in production, you need a wildcard domain pointed at your Vercel project.

Point your domain to Vercel's nameservers (ns1.vercel-dns.com and ns2.vercel-dns.com). Vercel needs to control your DNS to automatically issue SSL certificates for each new subdomain.
In your Vercel project's Domains settings, add the apex domain: yourapp.com.
Add a wildcard domain: *.yourapp.com.

Once that's done, any single-label subdomain — acme.yourapp.com, beta-co.yourapp.com — automatically resolves to your deployment, with Vercel issuing a certificate for each one on the fly. No per-tenant DNS work required on your end.

⚠️ A wildcard certificate for *.yourapp.com covers exactly one DNS label — it matches acme.yourapp.com but not a deeper subdomain like docs.acme.yourapp.com. That kind of nested subdomain would need its own certificate and DNS entry, and this guide's getSubdomain() parser doesn't handle it either (it would slice docs.acme.yourapp.com down to the single string "docs.acme", which isn't even a valid slug under the constraint from Step 4). If you need per-tenant sub-paths like that, treat it as a separate, deliberate feature — don't assume it falls out of wildcard support for free.

Update your production environment variable to match:

NEXT_PUBLIC_ROOT_DOMAIN=yourapp.com

💡 Tip: If tenants will ever be able to publish their own content or run their own code on your subdomains (not just view data you control), submit your domain to the Public Suffix List so browsers isolate cookies between tenant1.yourapp.com and tenant2.yourapp.com. This matters more for user-generated-content platforms than a typical internal-dashboard SaaS.

⚠️ Important: If you become a platform that gives mutually untrusted customers control over content or code on separate subdomains, investigate whether your domain qualifies for the PSL PRIVATE section. This changes browser cookie boundaries, so understand the consequences before applying.

What About Custom Domains?

Letting a tenant use their own domain (app.acme.com instead of acme.yourapp.com) is a common upsell for higher-tier plans, but it's meaningfully more setup: you provision the domain onto your Vercel project programmatically (via the Vercel SDK), verify the tenant actually owns it with a TXT record, and let Vercel auto-issue SSL once verified. The tenant-resolution logic in proxy.ts from Step 2 extends naturally — you'd just add a lookup by full hostname (domain_${hostname}) before falling back to subdomain parsing. Treat this as a Phase 2 feature; ship subdomains first.

Production Checklist

[ ] proxy.ts deletes inbound x-tenant-* headers before setting its own — never trust client-supplied tenant headers
[ ] An unresolved tenant subdomain redirects to the root domain, not the tenant's own (bad) host — otherwise it loops
[ ] proxy.ts refreshes the Supabase auth session on every request, not just tenant headers
[ ] Every tenant-owned table has a tenant_id column, a matching index, and RLS enabled
[ ] RLS policies exist for select, insert, update, and delete — not just select
[ ] No policy anywhere uses a bare using (true) unless a resource is genuinely meant to be public
[ ] Server Actions derive tenant_id from the resolved server-side tenant context, never from client-submitted form data
[ ] Reserved subdomains (www, app, admin, api) are excluded from tenant resolution
[ ] Tenant slugs are constrained as valid single-label DNS names (no leading/trailing hyphens, ≤63 characters)
[ ] Wildcard domain (*.yourapp.com) and apex domain are both added in Vercel, with nameservers delegated
[ ] anon/authenticated table grants are explicitly restricted to only the operations the app requires

Wrapping Up

Multi-tenant architecture in Next.js 16 comes down to two layers working together: proxy.ts figures out which tenant a request belongs to and hands that context downstream as a header, while Postgres Row Level Security makes sure that context is actually enforced — not just trusted — every time data gets read or written. Get those two pieces right, and "which company does this row belong to?" stops being a question your application code has to get right on every single query; it becomes a guarantee your database makes for you.

From here, natural next steps are layering role-based permissions on top of tenant membership (owner vs. admin vs. member), building a tenant-scoped billing flow with Stripe subscriptions, and revisiting session vs. JWT if you want tenant context embedded directly in the session instead of resolved fresh on every request.

Continue Learning

Free Developer Tools

Supabase RLS Policy Generator — generate strict, tenant/team-scoped Row Level Security policies like the ones in this guide, including the auth.uid() performance wrapper and a security-definer helper function, without hand-writing SQL.

generateMetadata and Your Page Component Are Probably Querying the Same Data Twice

Sat, 19 Sep 2026 10:48:58 +0000

I wrote earlier about cache() fixing redundant database queries when multiple components in a tree independently call the same query function. There's one specific, extremely common place this exact pattern shows up that's worth calling out directly, because it's not an edge case, it's the default shape of nearly every dynamic page with SEO metadata.

The Setup Almost Every Dynamic Page Has

// app/blog/[slug]/page.tsx
import { getPost } from '@/lib/queries/posts';

export async function generateMetadata({ params }) {
  const { slug } = await params;
  const post = await getPost(slug); // query #1

  return {
    title: post.title,
    description: post.excerpt,
  };
}

export default async function BlogPost({ params }) {
  const { slug } = await params;
  const post = await getPost(slug); // query #2, same post, same request

  return (
    <article>
      <h1>{post.title}</h1>
      <div>{post.content}</div>
    </article>
  );
}

This is the completely standard pattern from the Next.js metadata setup covered in an earlier post, and it's genuinely necessary, generateMetadata needs the post's title and excerpt for the meta tags, the page component needs the post's full content to actually render it. Both run for every single request to this page. Both call getPost(slug) independently. Without a specific fix, that's two full database round trips for what is, semantically, the exact same piece of data, fetched twice, for every single page view.

Why This Specific Case Matters More Than It Might Seem

This isn't a rare pattern someone might occasionally write, it's the default shape of generateMetadata combined with any dynamic page, which means it's quietly doubling database load on nearly every content-driven page across an entire site, blog posts, product pages, any dynamically rendered detail page with SEO metadata. A site with meaningful traffic on these pages is paying for twice the database queries it actually needs, on some of its most frequently visited pages, for no functional reason.

The Fix: Wrap the Query in React's cache()

// lib/queries/posts.ts
import { cache } from 'react';
import { connectDB } from '@/lib/db';
import Post from '@/models/Post';

export const getPost = cache(async (slug: string) => {
  await connectDB();
  return Post.findOne({ slug }).lean();
});

That's the entire fix, no changes needed anywhere else. generateMetadata and the page component both still call getPost(slug) exactly as before, the code looks identical. What changes is that React's request memoization now recognizes both calls, same function, same argument, within the same render pass, and only actually executes the underlying query once, returning the cached result for the second call.

Why This Is Worth Checking Specifically, Not Just Generally

The earlier post on this topic covered the general pattern, multiple components in a tree calling the same query. This specific case is worth checking on its own because it's so easy to miss precisely because generateMetadata and the page component don't look like they're part of the same "component tree" in the way nested components obviously are. They're two separate exported functions in the same file, and it's genuinely easy to write both, each looking completely correct in isolation, without ever noticing they're duplicating a database call for the same request.

A Quick Way to Verify This Is Actually Happening

Add a temporary log inside the un-cached query function and load the page once:

export async function getPost(slug: string) {
  console.log('getPost called for:', slug); // temporary
  await connectDB();
  return Post.findOne({ slug }).lean();
}

If you see that log line twice for a single page load, that's this exact issue, confirmed directly rather than assumed. After wrapping the function in cache(), the same test should show it logging only once per request.

Where This Doesn't Apply

If generateMetadata and the page component genuinely need different data, metadata pulling from a lighter, separate summary endpoint while the page fetches full content from somewhere else entirely, there's no duplication to fix, since they're not actually calling the same underlying function with the same arguments in the first place. This fix specifically applies when both are calling the identical query function, which, for most blog and content-driven page setups, is exactly the common case.

The Actual Rule

Any query function called both inside generateMetadata and inside the page component it belongs to should be wrapped in cache(), as close to a universal default as a rule gets in this specific area. It costs nothing to add, changes no calling code, and directly eliminates a real, silent, doubled database query that exists by default on essentially every dynamically rendered page with SEO metadata.

Go check any page in your own project using generateMetadata alongside a matching page component, specifically whether the underlying query function is wrapped in cache(). If it's not, you're very likely double-querying on every single page load for that route. Drop what you find in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Setting dynamicParams to false Can Make Brand New Content 404 Until Your Next Deploy

Thu, 17 Sep 2026 11:41:42 +0000

This one's a genuinely reasonable setting that causes a genuinely confusing symptom, a brand new piece of content, added correctly, visible in your CMS, just returns a 404 on the live site, with nothing in your code actually wrong.

What dynamicParams Actually Controls

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await getAllPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

export const dynamicParams = false; // reject anything not in the list above

export default async function BlogPost({ params }) {
  const { slug } = await params;
  const post = await getPost(slug);
  if (!post) notFound();
  return <article>{post.content}</article>;
}

generateStaticParams runs at build time, pre-rendering a page for every slug it returns. dynamicParams controls what happens for a slug that shows up in a request but wasn't in that build-time list. The default is true, meaning Next.js will attempt to render that path on demand anyway, genuinely useful behavior for content added after the last build. Setting it explicitly to false tells Next.js to immediately 404 anything not in the pre-generated list, full stop, no attempt to render it fresh.

Why Someone Sets This Deliberately

dynamicParams = false is a reasonable, intentional choice in specific situations, guaranteeing that only explicitly known, build-time-verified paths are ever servable, useful for something like a fixed set of product pages where an unexpected slug showing up would genuinely indicate a bug or a malicious request, not legitimate new content. It's not a mistake in that context, it's a deliberate constraint.

Where This Actually Causes Real Problems

For content that genuinely grows over time, a blog, a CMS-driven catalog, anything where new items get added independently of a code deployment, this exact setting means every new item is completely inaccessible, a real 404, until the next build actually happens and includes it in generateStaticParams's output.

1. Blog post published in the CMS at 2:00 PM
2. Someone shares the link
3. Visitor clicks it, gets a 404
4. The post is completely correct in the CMS, the slug is right, everything's fine there
5. The site just has no idea this post exists yet, since the last build predates it

This is exactly the kind of gap that's genuinely confusing to diagnose, since checking the CMS shows everything looks correct, checking the code shows the query logic is fine, and the actual cause, a build-time snapshot that's now stale, doesn't announce itself anywhere obvious.

The Actual Fix, Depending on What You Actually Need

If new content should be servable immediately without waiting for a rebuild, this is almost always the right default, just don't set dynamicParams to false at all, or set it explicitly to true:

export const dynamicParams = true; // or simply omit this line, true is the default

New slugs not in the build-time list get rendered on demand, then, depending on your caching setup, can be cached going forward, giving you both immediate availability and good performance after the first request.

If you genuinely need the strict guarantee dynamicParams = false provides, a fixed, known set of pages where anything else really should 404, pair it with a deliberate process for triggering a new build whenever new content is actually added, a webhook from your CMS triggering a redeploy, rather than relying on a periodic or manual build schedule that leaves a real gap between content going live and the site actually knowing about it.

// A CMS webhook triggering an on-demand revalidation or rebuild
// whenever new content is actually published, closing the gap

Why This Interacts Badly With Good SEO Practices

This is a genuinely important compounding issue. If you've set up automatic sitemap generation, covered in an earlier post, and someone shares a freshly published post before the next build happens, both the visitor clicking the link and, worse, a search engine crawler attempting to index that URL early, encounter a real 404. A crawler hitting a 404 on a URL is a real, negative signal, not a neutral non-event, and repeated early 404s on genuinely valid content can meaningfully hurt how quickly and how well that content ends up indexed once it is actually available.

How to Check If This Is Affecting You

If you're using dynamicParams = false anywhere, specifically check how long the gap actually is between content being published in your CMS and the next site build or deploy happening. If that gap is measured in hours or days rather than minutes, and the content in question is meant to be immediately live, that gap is a real, live problem, not a theoretical edge case.

grep -rn "dynamicParams" --include="*.tsx" app/

The Actual Rule

dynamicParams = false is a deliberate access-control decision, not a performance optimization, and it should only be used where truly unexpected paths genuinely should be rejected. For any content source that grows independently of your deployment schedule, a blog, a CMS-driven catalog, user-generated content, the default true behavior, or an explicit true, is almost always what you actually want, letting new content render on demand rather than waiting on the next build to even acknowledge it exists.

If you're using dynamicParams = false anywhere in a project with content that grows outside your deploy cycle, worth checking today whether new content is actually reachable the moment it's published, or silently 404ing until the next deploy catches up. Drop what you find in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Using searchParams in a Next.js Page Silently Opts It Out of Static Rendering Too

Tue, 15 Sep 2026 09:33:11 +0000

I wrote earlier about a buried cookies() call silently forcing an entire page into dynamic rendering. searchParams causes the exact same category of behavior, through a completely different, and in some ways more surprising, mechanism, since using it doesn't look like reading anything server-specific at all.

Why This One Is Extra Surprising

cookies() and headers() at least sound like they're reaching into something request-specific, so forcing dynamic rendering feels intuitive once you think about it. searchParams just looks like reading a prop, a completely normal-looking destructure at the top of a page component. There's nothing about the syntax that signals "this is a server-specific value tied to this exact request."

// app/products/page.tsx
export default function ProductsPage({
  searchParams,
}: {
  searchParams: Promise<{ category?: string; page?: string }>;
}) {
  // reading searchParams here means this page can no longer be
  // statically generated, full stop, regardless of what else it does
}

The moment a page component accepts and uses searchParams, Next.js treats the entire page as dynamic. This makes complete sense once you think through why, the query string is part of the actual request URL, and a page reading it necessarily produces different output for /products?category=shoes versus /products?category=hats, which is inherently incompatible with generating one fixed, static HTML output ahead of time. It's correct, intentional behavior. It's just not obviously signaled by the code itself the way reading cookies() is.

Where This Actually Costs You

For a genuinely filterable page, a product listing with category and sort filters, this dynamic behavior is exactly correct and necessary, the whole feature depends on rendering different content per query string. This isn't a bug to fix in that case.

The actual cost shows up when searchParams gets accepted by a page component out of habit, or copied from a similar page, without the page actually using the specific query params in any way that changes its output.

// app/about/page.tsx
export default function AboutPage({
  searchParams, // accepted but never actually used for anything meaningful
}: {
  searchParams: Promise<{ [key: string]: string | undefined }>;
}) {
  return (
    <div>
      <h1>About Us</h1>
      <p>We build things.</p>
    </div>
  );
}

If this component's type signature includes searchParams but the actual rendered output never varies based on it, simply accepting the prop can still be enough to affect how Next.js treats the route, depending on whether the value is actually read and used within the render. A genuinely static about page, forced into unnecessary dynamic rendering because of a leftover parameter or copy-pasted type signature from a different page, loses real caching benefit for no actual functional reason.

How to Tell If This Is Actually Happening

Same check as the earlier cookies() post, run a real build and look at the route summary:

npm run build

A route marked dynamic (ƒ) that you'd expect to be static (○) is worth investigating. If the page genuinely needs to vary based on query parameters, that's correct and expected. If it doesn't, actually use those params to produce different output, the fix is simply not accepting or reading searchParams in that component at all.

The Distinction That Actually Matters

Does this specific page's rendered output genuinely need to differ based on the query string? If yes, dynamic rendering triggered by searchParams is correct, intentional, and not something to fight against, the feature depends on it.

Is searchParams present in the component's signature or destructured, but never actually used to change what gets rendered? That's the case worth fixing, either by removing the unused parameter entirely, or, if the params are genuinely needed for something that doesn't affect the main rendered content, handling that specific piece in a way that doesn't force the whole page dynamic, a client-side read via useSearchParams() inside a small Client Component, for something that only needs to react to params after the initial static render.

// A pattern that keeps the main page static while still reacting to query params
// for a small, specific piece of UI that genuinely needs them
export default function ProductsPage() {
  return (
    <div>
      <h1>Our Products</h1>
      <ProductGrid /> {/* genuinely static content */}
      <QueryAwareBanner /> {/* small client component reading useSearchParams() */}
    </div>
  );
}

The Broader Pattern

This is the same underlying lesson as the cookies() post, applied to a different, less obviously "server-specific" mechanism. Next.js's static-versus-dynamic decision is driven by what a page actually reads and depends on, not by how obviously server-related that code looks at a glance. searchParams, cookies(), and headers() all trigger the same category of behavior, and all three are easy to include without actually needing what they provide, especially when copying a page's structure from a similar one that genuinely did need it.

Go check your own build output for any page accepting searchParams that doesn't actually use it to change what gets rendered. If you find one, that's a free, easy static-rendering win sitting right there. Drop what you find in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Wrapping redirect() in a try/catch in Next.js Can Silently Swallow the Redirect

Mon, 14 Sep 2026 08:46:50 +0000

This one catches people specifically because the code looks like careful error handling, and it's actually the thing breaking the exact feature it's wrapped around.

The Setup That Looks Like Responsible Error Handling

// actions/auth.ts
'use server';

export async function login(formData: FormData) {
  try {
    const email = formData.get('email') as string;
    const password = formData.get('password') as string;

    const user = await verifyCredentials(email, password);
    if (!user) {
      return { error: 'Invalid credentials' };
    }

    await setSessionCookie(user);
    redirect('/dashboard');
  } catch (error) {
    console.error('Login failed:', error);
    return { error: 'Something went wrong' };
  }
}

This looks like exactly the kind of defensive coding you'd want, wrap the risky operations, catch anything unexpected, return a clean error instead of crashing. It also means a successful login never actually redirects anywhere, and the console gets a confusing, misleading error log every single time someone logs in correctly.

Why This Happens

redirect() in Next.js doesn't work like a normal function returning a value that tells the framework "please navigate now." It works by throwing a special internal error, effectively an escape hatch, that Next.js's own machinery catches at a higher level in the rendering or request lifecycle, and uses to actually trigger the navigation. This is genuinely how the feature is implemented under the hood, not a bug, it's a deliberate mechanism for interrupting normal execution flow to redirect.

A try/catch block doesn't know or care that this particular thrown error is special. It catches everything thrown within its boundary, indiscriminately, which includes this internal redirect signal exactly the same way it would catch a genuine database error or a network failure. Your catch block intercepts it, logs a confusing "Login failed" message for what was actually a completely successful login, and returns your generic error response instead of ever letting the redirect signal propagate up to where Next.js needs to see it.

Why the Console Log Makes This Extra Confusing

The logged error typically has a distinctive-looking message or code related to Next.js's internal redirect mechanism, not a normal JavaScript error you'd immediately recognize. Someone unfamiliar with this specific gotcha sees an unfamiliar-looking error logged on every successful login and reasonably assumes something is actually broken, when the "error" being caught is, ironically, the successful outcome trying to happen.

The Actual Fix: Call redirect() Outside the try/catch

// actions/auth.ts
'use server';

export async function login(formData: FormData) {
  const email = formData.get('email') as string;
  const password = formData.get('password') as string;

  let user;
  try {
    user = await verifyCredentials(email, password);
  } catch (error) {
    console.error('Login failed:', error);
    return { error: 'Something went wrong' };
  }

  if (!user) {
    return { error: 'Invalid credentials' };
  }

  await setSessionCookie(user);
  redirect('/dashboard'); // outside any try/catch, free to throw its internal signal cleanly
}

Scoping the try/catch specifically around the operation that can genuinely fail in an unexpected way, the credential verification, database call, whatever's actually risky, and calling redirect() afterward, outside that block entirely, means its internal throw mechanism reaches Next.js cleanly, without your own error handling accidentally standing in the way.

If You Need Try/Catch Around Code That Includes a redirect() Call

Sometimes the structure genuinely requires a broader try block. In that case, explicitly re-throw anything that looks like a Next.js redirect or notFound signal, rather than treating everything caught as a genuine error:

import { isRedirectError } from 'next/dist/client/components/redirect';

try {
  // some code that includes a redirect() call somewhere within it
} catch (error) {
  if (isRedirectError(error)) {
    throw error; // let it propagate, this isn't a real error
  }
  console.error('Actual error:', error);
  return { error: 'Something went wrong' };
}

This pattern is more defensive but also more fragile, since it depends on an internal Next.js utility rather than a fully public, stable API. Restructuring the code to keep redirect() outside any try/catch entirely, the first fix above, is the cleaner, more robust solution whenever the code can reasonably be organized that way.

Where Else This Bites

The exact same issue applies to notFound(), which uses the same underlying throw-based mechanism. Any Server Action, Server Component, or route handler with a broad try/catch wrapping code that also calls redirect() or notFound() anywhere within that boundary is at risk of this exact silent failure, not just login flows specifically.

The Actual Rule

Never let a try/catch block unintentionally wrap a call to redirect() or notFound(). Scope error handling tightly around the specific operations that can genuinely throw a real error, and keep redirect and not-found calls outside that boundary, or explicitly detect and re-throw them if the structure genuinely requires a broader catch.

If you've got a Server Action with a broad try/catch that also calls redirect() somewhere inside it, go check whether that redirect is actually firing, or silently getting logged as a mysterious error instead. Drop what you find in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

That .lean() Query Optimization Might Be Leaking Password Hashes in Your API Response

Fri, 11 Sep 2026 08:29:25 +0000

I've recommended .lean() in earlier posts, it's genuinely the right call for read-heavy queries, faster, lighter, no Mongoose document overhead. There's a real gap it opens up that's worth calling out specifically, because it silently undoes a common, otherwise-good security pattern, and the failure is invisible unless you specifically go check the actual API response.

The Setup That Looks Like a Solid Security Pattern

// models/User.ts
const UserSchema = new Schema({
  name: String,
  email: String,
  password: { type: String, select: false }, // excluded from queries by default
}, {
  toJSON: {
    transform: (doc, ret) => {
      delete ret.password; // extra safety net, strips it even if somehow selected
      delete ret.__v;
      return ret;
    },
  },
});

This is a reasonable, defense-in-depth setup, select: false keeps the password out of normal queries by default, and the toJSON transform is a second safety net stripping it from anything that does get serialized, in case it was ever explicitly selected somewhere. Two layers, looks solid.

Where This Quietly Breaks

// app/api/users/route.ts
export async function GET() {
  const users = await User.find().select('+password').lean();
  // some legitimate internal reason to select password here, comparing hashes, an admin tool, etc.
  return Response.json({ users });
}

.lean() returns plain JavaScript objects, not real Mongoose documents. That toJSON transform you configured on the schema is a method that exists on Mongoose document instances specifically, it never runs on a plain object. Response.json({ users }) calls JSON.stringify under the hood, which on a lean plain object just serializes every property directly, no transform, no stripping, nothing. If password was selected anywhere in that query chain, it goes straight into the API response, completely bypassing the safety net you specifically built to prevent exactly that.

Why This Is Genuinely Easy to Introduce

The select('+password') and .lean() combination often gets added at different times, for different reasons, by different people, or by the same developer months apart with the original toJSON safety net long forgotten. Someone adds .lean() to a query for a legitimate performance reason, weeks or months after the select('+password') was added for some specific internal need, comparing a password during a migration script, an admin debugging tool, and neither change alone looks dangerous in isolation. The combination is what's dangerous, and nothing about reviewing either change independently reveals that.

The Actual Fix: Never Rely on toJSON as Your Only Safety Net

The real lesson here isn't "don't use .lean()", it's genuinely great for performance and you should keep using it. The lesson is that toJSON transforms are not a reliable safety net for anything you might combine with .lean(), so the actual stripping needs to happen explicitly, regardless of whether the query happens to be lean or not.

// lib/serializers/user.ts
export function toSafeUser(user: any) {
  const { password, __v, ...safe } = user;
  return safe;
}

// app/api/users/route.ts
import { toSafeUser } from '@/lib/serializers/user';

export async function GET() {
  const users = await User.find().lean(); // no need to select password here at all
  return Response.json({ users: users.map(toSafeUser) });
}

An explicit serializer function works identically whether the input came from a lean query or a real document, since it's just plain object destructuring, not relying on a Mongoose-specific lifecycle hook that only fires under certain conditions.

The Broader Rule This Points To

Never assume a security-relevant transform tied to a document lifecycle method still applies once you've introduced .lean(), .toObject(), or any pattern that returns a plain object instead of a real document instance. toJSON, toObject transforms, and virtuals are all Mongoose document features, tied specifically to the document class, not properties of the raw data itself. The moment you're working with a plain object, none of that schema-level behavior comes along automatically, and any security assumption riding on it needs to be re-verified explicitly, not assumed to still hold.

Check Your Own API Routes

grep -rn "lean()" --include="*.ts" app/api/

For each match, check two things, does the underlying query ever select a genuinely sensitive field, and does the response actually get filtered explicitly, not just relying on a schema-level transform that a lean query never triggers. If a route selects a sensitive field for some legitimate internal reason and also calls .lean(), that combination is worth verifying directly against the actual JSON response, not just the code.

If you've got .lean() anywhere near a query that ever selects a genuinely sensitive field, go check the actual raw response, not just the code, this specific combination is exactly the kind of thing that looks completely fine on read-through and only reveals itself in the real serialized output. Drop what you find in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

A Wildcard in Your next.config Image remotePatterns Might Turn Your Site Into an SSRF Proxy

Thu, 10 Sep 2026 08:17:19 +0000

next/image optimizing external images is genuinely convenient, resizing, format conversion, all handled automatically through Next.js's built-in image optimization endpoint. That endpoint fetches the remote image server-side before serving the optimized version to the browser, and that server-side fetch is exactly the mechanism that becomes a real problem if remotePatterns is configured too loosely.

The Configuration That Looks Convenient

// next.config.ts
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**', // "just let any https image load, easier than maintaining a list"
      },
    ],
  },
};

This shows up constantly, especially on projects where images come from a genuinely wide variety of sources, user-uploaded content pointing at various CDNs, a CMS that could reference images from anywhere. The wildcard hostname feels like a reasonable convenience, avoid maintaining an explicit allowlist, just accept any https image URL.

Why This Is Actually a Real Vulnerability

Next.js's image optimization endpoint, /_next/image, accepts a url parameter and fetches it server-side. With hostname: '**', that endpoint will fetch essentially any URL an attacker provides, as long as it's https. This turns your own server into a general-purpose URL-fetching proxy, controllable by anyone who can construct a request to that endpoint, which is a textbook Server-Side Request Forgery setup.

https://yoursite.com/_next/image?url=https://internal-admin-panel.yourcompany.com/&w=640&q=75

If your infrastructure has any internal services reachable from where your Next.js app runs, an internal admin panel, a cloud metadata endpoint, an internal API with no separate auth layer because it was assumed to only be reachable from inside your own network, a wildcard remotePatterns configuration means your own server will happily make that request on an attacker's behalf and, depending on exactly how the endpoint's response gets exposed, potentially leak some information about what came back.

The Specific, Well-Known Version of This: Cloud Metadata Endpoints

This is the classic SSRF target, and it's directly relevant here. Most cloud providers expose an internal metadata endpoint, http://169.254.169.254/, reachable only from within their own infrastructure, that can return real credentials or configuration data for the running instance. A wildcard image proxy is exactly the kind of mechanism that's been used in real-world SSRF attacks to reach exactly this endpoint from inside cloud environments, since the request originates from your own server, which does have network access to it, not from the attacker's machine, which doesn't.

The Fix: An Actual Allowlist, Not a Wildcard

// next.config.ts
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'res.cloudinary.com',
      },
      {
        protocol: 'https',
        hostname: 'yourbucket.s3.amazonaws.com',
      },
      {
        protocol: 'https',
        hostname: 'lh3.googleusercontent.com', // if accepting Google account avatars, for example
      },
    ],
  },
};

An explicit list of the actual, known image sources your app legitimately uses closes this off entirely. The image optimization endpoint will only fetch from hosts on this list, regardless of what URL parameter someone tries to pass in, which is the entire point, the server should only ever be willing to fetch from sources you've actually decided to trust, not from anywhere an attacker can construct a URL for.

What If You Genuinely Need Broad, User-Controlled Image Sources

For a case like user-generated content where images could legitimately come from many different, unpredictable domains, a wildcard isn't the only option, and it's worth resisting it even here. A more careful approach validates and stores the actual final image URL at upload time, ideally re-hosting the image on your own trusted storage rather than proxying an arbitrary external URL live on every request, which removes the SSRF surface entirely rather than trying to sanitize URLs on the fly, a genuinely hard problem to get completely right.

The Broader Rule

Any server-side mechanism that fetches a URL based on client-supplied input is a potential SSRF vector, and next/image's remotePatterns wildcard is a specific, easy-to-overlook instance of a much more general pattern. The same caution applies to any custom endpoint you build that fetches a URL, downloads a file, or proxies a request based on something a client sent, not just this one specific Next.js feature.

Check Your Own Config

grep -A 5 "remotePatterns" next.config.ts

If you see hostname: '**' or a similarly broad wildcard, and your app has any internal services or cloud infrastructure reachable from where it runs, this is worth tightening today, not eventually. Replace it with an explicit list of the actual domains your images genuinely come from.

If you're running a wildcard remotePatterns config right now, genuinely curious what led to it, deliberate convenience tradeoff, or just copied from a tutorial without thinking through what it actually opens up. Drop your situation in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

How I Built a Digital Invitation Platform with Next.js, Supabase, and Vercel

Wed, 09 Sep 2026 11:03:45 +0000

How I Built a Digital Invitation Platform with Next.js, Supabase, and Vercel

I wanted to build a small product that solved a problem people actually have, rather than another project that would only live in a GitHub repository.

That idea eventually became InviteVia, a digital invitation platform for weddings, birthdays, engagements, parties, and other events.

The initial idea sounded simple: let someone create an invitation, share it with their guests, and collect RSVPs.

The interesting part was everything that came after that.

Starting with a simple MVP

I decided to keep the first version as simple as possible.

The core flow was straightforward. A user creates an invitation, adds the event information, publishes it, and gets a shareable URL. Guests open the URL and can view the invitation and respond to the event.

One decision I made early was not requiring guests to create an account just to RSVP.

From a developer perspective, authentication would have been relatively easy to add. From a user's perspective, however, it would add another unnecessary step.

For an event invitation, I would rather remove friction than add another login screen.

Why I chose Next.js

I built the application with Next.js and TypeScript.

Next.js made sense for this project because the application has both interactive parts and pages that benefit from being discoverable by search engines.

The invitation itself is also something that needs to load quickly when somebody receives a link through WhatsApp, Instagram, SMS, or another messaging platform.

I wanted the application architecture to support both the product experience and the SEO side of the project without maintaining a separate frontend application.

Supabase for the backend

For the backend, I used Supabase.

It gave me authentication, PostgreSQL, database access, and other backend functionality without having to build all of those services from scratch.

For an MVP, this was especially useful because I wanted to spend more time working on the actual invitation experience rather than building infrastructure that already exists.

The database structure revolves around the things the product actually needs: users, invitations, events, guests, and RSVP information.

Keeping those relationships simple was important because I knew the application might eventually need to support more complex event features.

One of the things I wanted InviteVia to do well was sharing.

When somebody sends an invitation URL through a messaging application or social network, the link should not just appear as a random URL.

It should have a useful preview containing the event information and an appropriate image.

This led me to implement dynamic Open Graph images using Vercel's OG image generation.

Instead of creating a static image for every invitation, the application can generate a preview based on the invitation data.

That means different invitations can have different previews while still using the same underlying application.

For me, this was one of the more interesting parts of the project because it sits somewhere between frontend development, backend data, and SEO/social sharing.

Making RSVP as frictionless as possible

Another problem I wanted to solve was the RSVP experience.

Imagine receiving a wedding invitation and being asked to create an account, verify your email, and remember another password before you can simply answer "Yes."

That felt unnecessary.

So I designed the RSVP flow around the guest rather than the account system.

A guest can open the invitation, see the event information, and respond without creating an account.

The goal is simple: if someone has the invitation link, they should be able to interact with the invitation.

This sounds like a small product decision, but removing a few steps from a user flow can make a significant difference.

Building for multiple languages

InviteVia is also designed for an international audience.

Instead of building the application around a single language and adding localization later, I decided to support multiple languages from the beginning.

The platform currently supports 19 languages.

That introduced another layer of complexity because localization is not just translating strings. Routes, metadata, page titles, descriptions, structured content, and user-generated information all need to work correctly across languages.

It also made me think much more carefully about how I structure the application.

The SEO side of the project

SEO became another interesting engineering problem.

A digital invitation platform has many pages that can potentially be discovered through search engines, but simply generating thousands of pages is not enough.

The pages need useful content, correct metadata, sensible heading structures, canonical URLs, and proper language relationships.

I also had to think about how dynamically generated invitation pages should behave when they are crawled.

This is where building a product and working on SEO start to overlap. Technical decisions made in the application can directly affect how search engines understand the site.

What I learned from building it

The biggest lesson was that building the product is only one part of the work.

It is relatively easy to create a page that looks good and works locally.

It is much harder to build something that is fast, accessible, discoverable, easy to share, and simple enough for someone who has never seen the application before.

I also learned that small product decisions can have a surprisingly large impact.

Not requiring an account for guests, generating dynamic social previews, supporting multiple languages, and keeping the invitation URL simple were all decisions that seemed small when I made them.

Together, they became an important part of the product experience.

Where InviteVia is going

InviteVia started as an MVP, but I am treating it as a real product rather than just a portfolio project.

The next challenges are not only technical. They involve understanding how people actually use the invitations, improving the creation experience, making RSVP management better, and finding sustainable ways to bring new users to the platform.

For me, that is what makes building a product more interesting than building another demo.

You have to keep solving problems that you did not anticipate when you wrote the first line of code.

If you want to see the project, you can find it at InviteVia.

I am still building and improving it, so this is very much a work in progress.

Using an Array Index as a React key Can Leak Form State Between Completely Different Items

Wed, 09 Sep 2026 08:21:44 +0000

This is one of those React gotchas that's been written about for years and still shows up constantly in real code, specifically because it looks completely correct and works fine in the exact scenario most people test.

The Setup That Looks Fine

// components/QueueList.tsx
'use client';

export function QueueList({ entries }: { entries: QueueEntry[] }) {
  return (
    <div>
      {entries.map((entry, index) => (
        <QueueRow key={index} entry={entry} />
      ))}
    </div>
  );
}

function QueueRow({ entry }: { entry: QueueEntry }) {
  const [isEditing, setIsEditing] = useState(false);
  const [note, setNote] = useState('');

  return (
    <div>
      {isEditing ? (
        <input value={note} onChange={(e) => setNote(e.target.value)} />
      ) : (
        <span>{entry.name}</span>
      )}
      <button onClick={() => setIsEditing(!isEditing)}>Edit</button>
    </div>
  );
}

key={index} compiles fine, renders fine, and works completely correctly for a list that never reorders or has items removed from the middle. It's also a ticking bug for the exact moment that stops being true, which, for a live queue, a to-do list, anything backed by real-time or user-driven changes, is basically guaranteed to happen eventually.

What Actually Breaks

Say a user clicks "Edit" on the third row in a five-person queue, typing a note into that row's input. Then, before they finish, the first person in the queue gets called and removed from the list. React re-renders with four entries instead of five, and here's the actual bug, React uses the key to decide whether a given DOM node and its associated state represent the same conceptual item across renders or a genuinely new one.

With key={index}, the item that used to be at index 3 (where the user was editing) is now a completely different person's data, since everyone shifted up by one position after the removal. But React sees key={2} existed before and key={2} exists now, same key, so as far as React's reconciliation is concerned, this is the same component instance, not a new one. The isEditing and note state that belonged to the original row stays attached to whatever now occupies that same index. The user's open text input, and whatever they'd started typing, is now sitting on a completely different person's row, potentially about to submit a note meant for someone else onto someone else's queue entry.

Why This Is So Easy to Miss in Testing

Most manual testing during development involves a list that doesn't change while you're interacting with it, you open an edit field, you look at it, maybe you close it, and move on. The bug specifically requires the list to reorder or shrink while some item has open local state, exactly the kind of timing-dependent interaction that's easy to never happen to trigger during normal development testing, and completely likely to happen in production the moment two things occur close together in real usage, someone editing a note right as a queue updates in real time, for instance.

The Fix: Key by Something Stable and Unique to the Item

export function QueueList({ entries }: { entries: QueueEntry[] }) {
  return (
    <div>
      {entries.map((entry) => (
        <QueueRow key={entry.id} entry={entry} /> {/* stable, unique, tied to the actual item */}
      ))}
    </div>
  );
}

Using the entry's actual database ID, something that stays attached to that specific piece of data regardless of its position in the array, means React correctly tracks each row as the same conceptual item across reorders and removals. If the person originally at index 3 moves to index 2 after someone ahead of them is removed, React now correctly recognizes it's the same person, keyed by entry.id, not a coincidentally-matching array position, and their open edit state, their typed note, moves correctly along with them instead of staying pinned to a now-different row.

Where This Specifically Bites Harder: AnimatePresence

This gets worse, not just wrong but visually confusing, combined with exit animations. If you're using AnimatePresence for a list, covered in an earlier post on animation patterns, keying by index actively breaks the exit animation's ability to correctly identify which item is actually leaving.

// ❌ AnimatePresence can't correctly animate the actual removed item
<AnimatePresence>
  {entries.map((entry, index) => (
    <motion.div key={index} exit={{ opacity: 0 }}>
      {entry.name}
    </motion.div>
  ))}
</AnimatePresence>

// ✅ Correctly animates the specific item that was actually removed
<AnimatePresence>
  {entries.map((entry) => (
    <motion.div key={entry.id} exit={{ opacity: 0 }}>
      {entry.name}
    </motion.div>
  ))}
</AnimatePresence>

With an index-based key, removing the first item doesn't register as "index 0 left," it registers as "every remaining item shifted to a new key," which can cause the exit animation to fire on the wrong visual element, or fail to trigger the intended fade-out on the item that was actually removed at all.

The Actual Rule

Any list where items can be reordered, filtered, or removed from anywhere other than strictly the end needs a key tied to the item's own stable identity, not its position. A database ID, a UUID, anything genuinely unique and attached to that specific piece of data works. Array index is only ever safe for a list that's guaranteed static, never reordered, never filtered, items only ever appended at the end and never removed, a genuinely narrow set of real-world cases.

Go check any list in your own codebase using key={index}, specifically ones with any local state inside each item, an expanded row, an open edit mode, a checked checkbox, and check whether that list can ever reorder or have items removed from the middle. If it can, this bug is very likely already there, whether or not anyone's noticed yet. Drop what you find in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Next.js Full-Stack Auth Template

Wed, 09 Sep 2026 05:55:26 +0000

Setting up a complete, production-grade auth flow shouldn't take days.

I built an open-source starter template combining Next.js, Better-Auth, Drizzle ORM, and PostgreSQL to streamline the entire setup.

What it includes:

Email/Password & Social OAuth (Google & GitHub)
PostgreSQL schema management & migrations with Drizzle ORM
Server-side route protection via Next.js layouts
Full client and server type safety

I've shared the entire codebase and published a comprehensive architectural breakdown explaining the full setup step-by-step.

Live Demo: website-link
GitHub Repository: repo-link
Full Step-by-Step Guide: article-link
Video Demo: video-link

Rendering new Date() in a Server Component Is a Silent Timezone Bug Waiting to Happen

Tue, 08 Sep 2026 08:04:36 +0000

If you've ever seen a hydration mismatch warning in the console for a timestamp, and just suppressed it with suppressHydrationWarning because the page still worked, it's worth actually understanding what that warning was telling you, because the underlying issue doesn't go away just because the warning did.

The Setup That Looks Completely Normal

// app/dashboard/page.tsx
export default function DashboardPage() {
  return (
    <div>
      <h1>Dashboard</h1>
      <p>Last updated: {new Date().toLocaleString()}</p>
    </div>
  );
}

This renders a timestamp. It looks correct in the browser. It also has two separate problems stacked on top of each other, one causing a visible React warning, the other causing a genuinely wrong displayed value that never throws any warning at all.

Problem One: The Hydration Mismatch

The server renders this component once, at whatever exact moment the request is processed, producing a specific timestamp string. Then React hydrates that same component on the client, and new Date().toLocaleString() runs again, this time at whatever moment hydration actually happens, milliseconds or sometimes longer after the server render. Two different calls to new Date(), two different actual timestamps, and React's hydration process expects the server-rendered HTML and the client's first render to match exactly. When they don't, React logs a hydration mismatch warning and, depending on the specifics, may discard and re-render the mismatched content client-side.

Problem Two, the One That Doesn't Even Warn You: Timezone

This is the one that actually causes wrong data, not just a console warning. toLocaleString() without an explicit locale and timezone uses the runtime environment's local timezone setting, and the server's runtime environment and the visitor's browser are very often not in the same timezone at all. A server running in UTC, common for most cloud infrastructure, formats "3:00 PM" in UTC. If a visitor's browser is in a different timezone, the hydrated client-side render of the exact same underlying timestamp shows a completely different clock time, "3:00 PM" during server rendering, silently replaced by something like "10:00 AM" once client-side hydration takes over and reformats it in the visitor's actual local timezone.

Neither of these values is actually wrong in isolation, they're both technically correct representations of the same underlying moment. The problem is a visitor briefly seeing one, then having it silently change to a different clock time right in front of them, or worse, seeing whichever version happens to persist without ever realizing the other one was theoretically shown first.

Why Suppressing the Warning Doesn't Fix Anything

// This makes the console warning go away. It does not fix the actual mismatch.
<p suppressHydrationWarning>Last updated: {new Date().toLocaleString()}</p>

suppressHydrationWarning tells React to stop complaining about a mismatch on this specific element, it does nothing to prevent the mismatch from happening, and it does nothing about the underlying timezone confusion. It's treating the symptom, a noisy console warning, while leaving the actual bug, a timestamp that renders differently depending on server versus client timezone, completely intact.

The Actual Fix: Format Explicitly, or Defer to the Client Deliberately

Option one, format with an explicit, fixed timezone, removing ambiguity entirely by never relying on either environment's local timezone setting:

export default function DashboardPage({ lastUpdated }: { lastUpdated: Date }) {
  const formatted = lastUpdated.toLocaleString('en-US', {
    timeZone: 'UTC',
    dateStyle: 'medium',
    timeStyle: 'short',
  });

  return <p>Last updated: {formatted} UTC</p>;
}

This produces the same, deterministic string regardless of where the server runs or where the visitor's browser happens to be, since the timezone is explicitly fixed rather than implicitly inferred from either environment.

Option two, if you genuinely want the visitor's own local time, defer that specific formatting to the client deliberately, rather than accidentally:

'use client';
import { useState, useEffect } from 'react';

export function LocalTimestamp({ date }: { date: string }) {
  const [formatted, setFormatted] = useState<string | null>(null);

  useEffect(() => {
    setFormatted(new Date(date).toLocaleString());
  }, [date]);

  return <span>{formatted ?? 'Loading...'}</span>;
}

Rendering nothing (or a neutral placeholder) on the server, then formatting in the visitor's actual local timezone only after mounting client-side, means there's no mismatch to begin with, since the server never rendered a locale-specific value for the client to potentially disagree with in the first place.

The Rule Worth Remembering

Anything genuinely time-sensitive or locale-sensitive rendered in a Server Component needs an explicit, fixed format, not an implicit one that depends on which environment happens to be doing the formatting. If you actually want the visitor's own local time specifically, that formatting decision belongs on the client, deliberately, not as an accidental side effect of a Server Component's output silently disagreeing with its own hydration.

If you've got a suppressHydrationWarning sitting on a timestamp somewhere in your codebase, worth going back and checking whether it's actually just hiding this exact timezone issue rather than a harmless cosmetic mismatch. Drop what you find in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

revalidatePath Might Not Be Invalidating What You Think It Is

Sat, 05 Sep 2026 07:06:12 +0000

If you've ever called revalidatePath after a mutation, watched the data still show up stale on the page, and fixed it by just also calling revalidatePath on a few more related paths until it finally worked, you were probably fighting the actual behavior of the function rather than a bug in your own code. This one has a genuinely confusing default that catches a lot of people, myself included the first time I ran into it.

The Setup That Looks Like It Should Just Work

// actions/posts.ts
'use server';
import { revalidatePath } from 'next/cache';

export async function createPost(formData: FormData) {
  await Post.create({ title: formData.get('title') });
  revalidatePath('/blog');
}

A new post gets created, revalidatePath('/blog') runs, and yet the blog index sometimes still shows the old, stale list on the very next visit. Nothing throws an error. It just quietly doesn't update the way you'd expect, and the natural instinct is to assume the mutation itself failed, when the actual data was written correctly the whole time.

What's Actually Happening

revalidatePath takes an optional second argument, 'page' or 'layout', and it changes what actually gets invalidated:

revalidatePath('/blog');              // defaults to invalidating just this specific path
revalidatePath('/blog', 'page');      // same as above, explicit
revalidatePath('/blog', 'layout');    // invalidates this path AND all paths sharing its layout

Without the second argument, revalidatePath('/blog') only invalidates that exact path. If your blog index is actually rendered through a layout that also affects nested routes, /blog/[slug], and you're expecting a change on the index to also refresh those nested pages, the default page-scoped call doesn't do that. You need the 'layout' variant explicitly if the invalidation is meant to cascade.

An Even More Common Gotcha: Dynamic Segments

// This does NOT invalidate /blog/my-first-post or any other specific slug
revalidatePath('/blog/[slug]');

// This DOES invalidate the specific rendered path
revalidatePath('/blog/my-first-post');

Passing the literal route pattern, [slug] included as text, does not magically invalidate every dynamically rendered version of that route. revalidatePath needs the actual, real path that was rendered, not the file-system pattern that generated it. If you're revalidating a specific post after an edit, you need the specific slug, not the dynamic segment's placeholder syntax.

Why This Is Genuinely Confusing to Debug

The failure mode here is not an error, it's stale data that sometimes seems to resolve itself anyway, since a full page reload, a different route triggering revalidation elsewhere, or the cache eventually expiring on its own can mask the actual bug intermittently. This makes it feel inconsistent and hard to reproduce reliably, when the actual rule underneath it is completely deterministic, it's just not the rule most people assume by default.

When to Reach for revalidateTag Instead

For anything genuinely complex, several routes that share underlying data but don't share a clean path or layout relationship, revalidateTag is usually the more precise, more maintainable tool, tagging the actual data dependency rather than trying to map out every path relationship by hand.

// lib/queries/posts.ts
export const getPosts = unstable_cache(
  async () => Post.find().sort({ createdAt: -1 }).lean(),
  ['posts-list'],
  { tags: ['posts'] }
);

export const getPost = unstable_cache(
  async (slug: string) => Post.findOne({ slug }).lean(),
  ['post-detail'],
  { tags: ['posts'] }
);

// actions/posts.ts
'use server';
export async function createPost(formData: FormData) {
  await Post.create({ title: formData.get('title') });
  revalidateTag('posts'); // invalidates every cached query tagged 'posts', regardless of path
}

This sidesteps the entire path-matching question, since it invalidates based on what data was actually affected, not which specific URL path happens to render that data.

The Actual Checklist

If you need a change to cascade to nested routes under a shared layout, pass 'layout' explicitly, the default won't do this for you.

Never pass a route pattern with the literal [param] syntax expecting it to match every rendered instance. Pass the actual, specific path that was rendered.

For data shared across multiple, not-cleanly-related paths, reach for revalidateTag instead of trying to enumerate every affected path by hand with revalidatePath.

If a page still seems stale after revalidation, check whether the actual issue is a missing 'layout' argument or a route pattern being passed literally, before assuming the underlying mutation itself failed.

If you've hit stale data after a revalidatePath call and eventually "fixed" it by adding a few more calls until it worked, genuinely curious whether it turned out to be one of these two issues, or something else entirely. Drop what actually fixed it in the comments.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Next.js Automatically Dedupes fetch() Calls. Your MongoDB Queries Don't Get That for Free.

Fri, 04 Sep 2026 10:14:16 +0000

Here's something that trips up almost everyone moving from a fetch-based API to a direct MongoDB connection in Next.js, and it's costing real database load on projects that don't even realize it's happening.

Next.js automatically deduplicates fetch() calls with identical parameters within a single render pass. If your layout, your page, and three nested components all call fetch('/api/user'), Next.js is smart enough to only actually make that request once and reuse the result everywhere else it's called. This is called request memoization, and it's one of the quieter, genuinely useful things the App Router does for you automatically.

Direct database queries get none of this. Nothing.

What This Actually Looks Like

// lib/queries/user.ts
import { connectDB } from '@/lib/db';
import User from '@/models/User';

export async function getCurrentUser(userId: string) {
  await connectDB();
  return User.findById(userId).lean();
}

// app/dashboard/layout.tsx
export default async function DashboardLayout({ children }) {
  const user = await getCurrentUser(userId); // query #1
  return <div><Sidebar user={user} />{children}</div>;
}

// app/dashboard/page.tsx
export default async function DashboardPage() {
  const user = await getCurrentUser(userId); // query #2, same user, same request
  return <Header user={user} />;
}

// components/UserMenu.tsx (Server Component, rendered inside the page)
export default async function UserMenu() {
  const user = await getCurrentUser(userId); // query #3
  return <Menu user={user} />;
}

Three separate calls to getCurrentUser, same user ID, same single incoming request from the browser. If this were fetch('/api/user') instead of a direct Mongoose query, Next.js would automatically collapse these into one actual network call. Since it's a direct database query, none of that automatic deduplication applies. This is three real round trips to MongoDB, for data that was identical all three times, on every single page load.

Why This Doesn't Show Up in Development

On a local database with almost no latency and no real load, three redundant queries feel instant, indistinguishable from one. This is exactly why it's so easy to ship without noticing. The cost only becomes visible under real production conditions, real network latency to your database, real concurrent traffic, where those extra round trips add up into measurably slower page loads and meaningfully higher database load than the page actually needed.

The Actual Fix: React's cache() Function

React ships a cache() function specifically for this. It memoizes a function's result within a single render pass, exactly the same behavior fetch gets automatically, just applied manually to whatever function you wrap with it.

// lib/queries/user.ts
import { cache } from 'react';
import { connectDB } from '@/lib/db';
import User from '@/models/User';

export const getCurrentUser = cache(async (userId: string) => {
  await connectDB();
  return User.findById(userId).lean();
});

That's the entire fix. Every call to getCurrentUser with the same userId, anywhere in that same render pass, layout, page, nested component, now returns the same cached promise instead of triggering a new query. Three calls become one actual database hit.

The Part People Get Wrong About cache()

This is request-scoped, not persistent across requests. It deduplicates calls within one single render of one single incoming request, then resets completely for the next request. It is not the same thing as unstable_cache, which persists data across multiple requests and needs explicit revalidation.

// cache() - deduplicates within ONE request, resets every time
export const getCurrentUser = cache(async (userId: string) => { ... });

// unstable_cache - persists ACROSS requests, needs revalidateTag to update
export const getPosts = unstable_cache(async () => { ... }, ['posts'], {
  revalidate: 3600,
});

Mixing these up causes two different problems. Using cache() where you needed unstable_cache means you're still hitting the database on every single request, just once instead of three times. Using unstable_cache where you needed cache() means you're persisting data across requests when you actually just wanted to avoid redundant calls within one page load, which can serve stale data longer than intended.

Where I'd Actually Add This

Not everywhere, that would be over-engineering a solution for calls that only ever happen once per request anyway. The pattern worth watching for specifically: any query function, getCurrentUser, getTenant, getSession-adjacent lookups, that reasonably gets called from multiple places in the same component tree, a layout, a page, and a few nested components all independently needing "who is the current user."

Check Your Own Project

Grep your query functions for ones called from more than one component in the same tree, and check whether they're wrapped in cache(). If they're not, and they're not already going through unstable_cache or an equivalent persistent layer, you likely have the exact redundant-query pattern above running silently in production right now.

Curious how many people actually knew about this before reading this post versus assumed Next.js handled it automatically the same way it does for fetch. Drop your honest answer in the comments, genuinely curious how well-known this actually is.

Get the templates: https://pixelanas.gumroad.com

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751