Docs

Introduction

Welcome to the next-supa-utils documentation!

next-supa-utils is a purpose-built library designed to eliminate the repetitive Supabase authentication and client initialization boilerplate in Next.js App Router applications.

🚀 Why Use This Over Raw @supabase/ssr?

If you use @supabase/ssr directly, you have to write boilerplate for every environment (Middleware, Server Components, Route Handlers, and Client Components). next-supa-utils eliminates this entirely:

  1. One-Line Middleware: No more manually copying the 40-line chunking/cookie-setting logic from the Supabase docs. Just pass your routes to withSupaAuth().
  2. Type-Safe Server Actions: Stop writing try/catch and cookies().getAll() in every server action. createAction() handles it automatically and forces you to check for errors.
  3. Instant Client Hooks: useSupaUser() and useSupaSession() wrap createBrowserClient, fetch the initial state, and subscribe to real-time onAuthStateChange events out of the box.
  4. App Router Ready: Strictly separated entry points (/client and /server) guarantee you won't accidentally import server code into client components.

Quick Start Overview

To get a sense of how fast you can build with next-supa-utils, here is what a protected server action looks like:

"use server";
import { createAction } from "next-supa-utils/server";

export const getProfile = createAction(async (supabase, userId: string) => {
  const { data, error } = await supabase.from("profiles").select().eq("id", userId).single();
  
  // Handled automatically by createAction wrapper! No need for try-catch blocks.
  if (error) throw error; 
  
  return data;
});

Check out the Installation guide to get started!

NextInstallation