Protected routes with middleware in NextJS - Deep Dive

Overview - Protected routes with middleware

What is it?

Protected routes with middleware in Next.js are a way to control access to certain pages or API endpoints. Middleware runs before the request reaches the page or API, checking if the user is allowed to proceed. If the user is not authorized, middleware can redirect them to a login page or show an error. This helps keep parts of your app safe and private.

Why it matters

Without protected routes, anyone could see or change sensitive information in your app. This could lead to privacy leaks or security problems. Middleware lets you check who is making a request early, so you can stop unauthorized users before they see or do anything they shouldn't. This makes your app trustworthy and safe for users.

Where it fits

Before learning protected routes with middleware, you should understand basic Next.js routing and how authentication works. After this, you can learn about advanced security patterns, session management, and server-side rendering with authentication.

Mental Model

Core Idea

Middleware acts like a gatekeeper that checks every request before it reaches a protected page or API, allowing only authorized users through.

Think of it like...

Imagine a club with a bouncer at the door who checks IDs before letting people inside. Middleware is like that bouncer for your app's routes.

┌─────────────┐
│ User Request│
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Middleware │
│ (Gatekeeper)│
└──────┬──────┘
       │
  ┌────┴─────┐
  │ Allowed? │
  └────┬─────┘
       │Yes          No
       ▼             ▼
┌─────────────┐  ┌─────────────┐
│ Protected   │  │ Redirect to │
│ Route/Page  │  │ Login Page  │
└─────────────┘  └─────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Next.js Middleware Basics

Concept: Middleware in Next.js runs code before a request reaches a page or API route.

Middleware is a special file named middleware.js or middleware.ts placed in your Next.js project root or inside the app directory. It intercepts requests and can modify the response or redirect users. Middleware runs on the edge, meaning it executes very fast and close to the user.

Result

You can run code on every request, like logging or checking headers, before the page loads.

Knowing that middleware runs before pages lets you control access early and efficiently.

2

Foundation

Basics of Route Protection Concept

Concept: Protecting routes means only letting certain users access specific pages or APIs.

A protected route checks if a user is logged in or has permission before showing the page. If not, it sends them somewhere else, usually a login page. This keeps private data safe.

Result

Users who are not logged in cannot see protected pages.

Understanding route protection is key to building secure apps that respect user privacy.

3

Intermediate

Checking Authentication in Middleware

🤔Before reading on: do you think middleware can read cookies or headers to check if a user is logged in? Commit to your answer.

Concept: Middleware can read request details like cookies or headers to decide if a user is authenticated.

In Next.js middleware, you can access cookies from the request to find a session token or user ID. If the token is missing or invalid, middleware can redirect the user to login. This check happens before the page loads.

Result

Only requests with valid authentication tokens proceed to protected pages.

Knowing middleware can read cookies lets you build secure checks without loading the full page.

4

Intermediate

Implementing Redirects in Middleware

🤔Before reading on: do you think middleware can stop a request and send a redirect response? Commit to your answer.

Concept: Middleware can stop the normal request flow and send a redirect response to the browser.

If middleware detects an unauthorized user, it returns a redirect response to the login page. This prevents the protected page from loading and sends the user to authenticate first.

Result

Unauthorized users are sent to login before accessing protected content.

Understanding redirects in middleware helps you control user flow smoothly and securely.

5

Intermediate

Using Middleware Matchers for Route Selection

Concept: Middleware can be set to run only on specific routes using matchers.

Next.js middleware supports a config object with a matcher property. This lets you specify which paths middleware should protect, like '/dashboard' or '/profile'. This avoids running middleware on every request, improving performance.

Result

Middleware runs only on routes that need protection, making your app faster.

Knowing how to limit middleware scope prevents unnecessary checks and speeds up your app.

6

Advanced

Handling Edge Cases and Token Expiry

🤔Before reading on: do you think middleware can refresh expired tokens or must it always redirect? Commit to your answer.

Concept: Middleware can detect expired tokens and decide whether to refresh them or redirect users to login.

Tokens often expire for security. Middleware can check token expiry timestamps. If expired, it can redirect to login or call an API to refresh tokens silently. This improves user experience by avoiding unnecessary logouts.

Result

Users stay logged in smoothly or are redirected when needed.

Handling token expiry in middleware balances security with user convenience.

7

Expert

Performance and Security Tradeoffs in Middleware

🤔Before reading on: do you think running heavy logic in middleware is a good idea? Commit to your answer.

Concept: Middleware should be fast and minimal because it runs on every matched request and affects user experience.

Middleware runs on the edge with limited resources and time. Heavy computations or slow network calls can delay responses. Experts design middleware to do quick checks only, offloading complex logic to APIs or client-side code. Also, middleware should avoid exposing sensitive data.

Result

Middleware protects routes efficiently without slowing down the app or risking leaks.

Understanding middleware limits helps build secure, fast apps that scale well.

Under the Hood

Next.js middleware runs on the Edge Runtime, a lightweight JavaScript environment close to the user. When a request matches middleware's configured paths, the middleware function executes before the request reaches the page or API. It can read request headers, cookies, and URL, then return a response or let the request continue. Middleware responses can modify headers, rewrite URLs, or redirect. This early interception allows fast decisions about access control.

Why designed this way?

Middleware was designed to run on the edge to reduce latency and improve security by handling checks before server-side rendering or API logic. Running middleware early prevents unauthorized requests from consuming server resources. The edge runtime is limited to ensure speed and security, so middleware is kept simple and fast. This design balances performance with control.

┌───────────────┐
│ Client Request│
└───────┬───────┘
        │
        ▼
┌───────────────┐
│ Edge Runtime  │
│ (Middleware)  │
└───────┬───────┘
        │
  ┌─────┴─────┐
  │ Check Auth│
  └─────┬─────┘
        │
  ┌─────┴─────┐          ┌───────────────┐
  │ Allow     │          │ Redirect to   │
  │ Request   │          │ Login Page    │
  └─────┬─────┘          └───────────────┘
        │
        ▼
┌───────────────┐
│ Next.js Page  │
│ or API Route  │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does middleware run after the page loads? Commit to yes or no.

Common Belief: Middleware runs after the page has loaded to check user access.

Reality: Middleware runs before the page or API route loads, intercepting requests early.

Why it matters: Believing middleware runs late can cause developers to put security checks in the wrong place, leaving routes unprotected.

Quick: Can middleware access the full Node.js environment? Commit to yes or no.

Common Belief: Middleware can use any Node.js API and run heavy server code.

Reality: Middleware runs in a limited Edge Runtime without full Node.js APIs and must be fast and lightweight.

Why it matters: Trying to use unsupported APIs causes errors and slow responses, breaking route protection.

Quick: Does middleware automatically protect all routes by default? Commit to yes or no.

Common Belief: Middleware protects every route in the app without configuration.

Reality: Middleware only runs on routes specified by matchers or placed in specific folders; it does not protect all routes automatically.

Why it matters: Assuming automatic protection can leave some routes exposed unintentionally.

Quick: Can middleware refresh expired tokens silently? Commit to yes or no.

Common Belief: Middleware can always refresh tokens without redirecting users.

Reality: Middleware can detect expiry but usually must redirect or call APIs; silent refresh is complex and often handled client-side.

Why it matters: Expecting automatic refresh in middleware can lead to broken login flows or security holes.

Expert Zone

1

Middleware runs on the edge with strict time limits, so even small delays add up and affect user experience.

2

Middleware cannot access server-side secrets directly; it must rely on tokens or headers passed from the client or server.

3

Stacking multiple middleware functions requires careful ordering to avoid conflicts or redundant checks.

When NOT to use

Middleware is not suitable for complex authentication flows requiring database queries or heavy logic. Instead, use API routes or server-side functions for those tasks. Also, for public pages with no sensitive data, middleware protection is unnecessary and adds overhead.

Production Patterns

In production, middleware is used to protect dashboards, user profiles, and API endpoints by checking JWT tokens or session cookies. It often redirects unauthorized users to centralized login pages. Middleware matchers limit checks to sensitive routes only. Token expiry handling is combined with client-side refresh logic for smooth user experience.

Connections

HTTP Status Codes

Middleware uses HTTP status codes like 302 to redirect unauthorized users.

Understanding HTTP status codes helps you control user navigation and error handling in middleware.

Edge Computing

Middleware runs on edge servers close to users to reduce latency.

Knowing edge computing principles explains why middleware is fast and limited in capabilities.

Physical Security Checkpoints

Middleware acts like a security checkpoint controlling access to protected areas.

Recognizing middleware as a security checkpoint clarifies its role in preventing unauthorized access early.

Common Pitfalls

#1 Middleware runs on all routes causing slow responses.

Wrong approach:

export const config = { matcher: '/'}; // matches all routes

Correct approach:

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

Root cause:

Not limiting middleware to only protected routes causes unnecessary checks and performance issues.

#2 Trying to use Node.js APIs like fs in middleware.

Wrong approach:

import fs from 'fs'; // used in middleware
export function middleware(req) { const data = fs.readFileSync('file'); return NextResponse.next(); }

Correct approach:

Avoid using Node.js APIs in middleware; use environment variables or tokens instead.

Root cause:

Misunderstanding that middleware runs in a limited Edge Runtime without full Node.js support.

#3 Not handling missing or expired tokens in middleware.

Wrong approach:

export function middleware(req) { const token = req.cookies.get('token'); if (token) { return NextResponse.next(); } }

Correct approach:

export function middleware(req) { const token = req.cookies.get('token'); if (!token || tokenExpired(token)) { return NextResponse.redirect('/login'); } return NextResponse.next(); }

Root cause:

Ignoring token expiry or absence leads to unauthorized access or broken user sessions.

Key Takeaways

Middleware in Next.js runs before pages or APIs to control access efficiently.

It acts like a gatekeeper, checking authentication tokens in requests to protect routes.

Middleware runs on the edge with limited APIs, so it must be fast and simple.

Using matchers limits middleware to only sensitive routes, improving performance.

Proper token handling and redirects in middleware keep users secure and improve experience.