Managing Authentication Tokens with Middleware in Next.js and Supabase

By: O. Wolfson

What is middleware?

Middleware is a crucial part of web development that helps manage the flow of information between the user and the server. In a Next.js application, middleware can be used to handle authentication processes efficiently and securely. This blog post explains how to set up middleware in a Next.js project to manage authentication tokens with Supabase effectively.

Middleware is like a checkpoint in a software application that helps manage the flow of information between the user (like when you click on a website) and the server (the place where the website's data is stored). When you use a website, your requests (like clicking on a link or submitting a form) go through middleware before reaching the server. Similarly, when the server sends data back to you, it often goes through middleware before appearing on your screen.

Here’s what middleware can do:

  1. Check Permissions: It can check if you are allowed to visit certain pages or access specific data.
  2. Modify Information: Middleware can change the data as it comes in or goes out. For example, it might compress data to make it travel faster.
  3. Log Activities: It can keep records of what requests are made, which is useful for understanding website traffic or detecting issues.
  4. Manage Sessions: Middleware can help recognize if you’re logged in and keep track of your session as you navigate different pages.

The main purpose of middleware is to streamline and secure the way data travels in an application, ensuring everything runs smoothly and safely as you interact with different parts of a website or app.

Handling authentication effectively and securely in web applications is crucial for protecting user data and ensuring seamless user interactions. In Next.js applications, middleware offers a powerful way to manage authentication processes across your application's lifecycle. This blog post explains how to use a specific middleware setup recommended by Supabase to manage authentication tokens efficiently in a Next.js project.

Read more at the Supabase Docs.

Here is an example below. Purpose of this Middleware The purpose of this middleware is to ensure that each request handled by the server has a valid, up-to-date session, enhancing both security and user experience. By refreshing tokens or updating sessions as necessary, it prevents users from being logged out prematurely and secures the application against session-related vulnerabilities.

Setting Up the Middleware

First, ensure your Next.js and Supabase environment is correctly set up. You should have the Supabase SDK installed and your project should be configured to connect to your Supabase project.

Middleware Code Explanation

Here is a look at the middleware code snippet recommended by Supabase, tailored for a Next.js application:

import { type NextRequest } from "next/server";
import { updateSession } from "@/utils/supabase/middleware";

export async function middleware(request: NextRequest) {
  return await updateSession(request);

export const config = {
  matcher: [

Detailed Breakdown

Imports and Function Setup

  • NextRequest: A type import from next/server, which is used to type the request object in your middleware function.
  • updateSession: A function from your utilities that likely interfaces with Supabase to manage session data.

Middleware Function

  • The middleware function is asynchronous and takes a NextRequest object as its parameter. It awaits the updateSession function, which performs operations necessary to maintain the user's session, such as refreshing authentication tokens.


  • The config object contains a matcher property that defines the paths this middleware applies to. The regular expression excludes:
    • _next/static: Static files generated by Next.js.
    • _next/image: Image optimization outputs from Next.js.
    • favicon.ico and image files: These static files do not require session checks or any authentication-related modifications.

Why This Setup?

This middleware configuration ensures that authentication processes are handled only on routes that potentially modify or require user data, excluding static and optimized content. This approach enhances performance by reducing unnecessary authentication checks on static resources and focuses security measures where they are most needed.


Integrating middleware in Next.js to manage authentication with Supabase provides a structured way to handle user sessions securely and efficiently. By focusing the middleware on specific routes, you ensure that your application remains fast and responsive while maintaining robust security where it matters most. Adapting this setup to include more specific paths or different types of content can further optimize your application's performance and security.