Next.js 15 introduces stricter rules about where and how you can fetch data, especially when dealing with authentication and cookies. This guide explains the essential concepts and shows you exactly what to do.

The Two Types of Server Code

Think of Next.js 15 as having two distinct environments for server code:

1. Server Components (Read-Only Zone)

• Files: layout.tsx, page.tsx, and other components
• Purpose: Display data to users
• What you CAN do: Fetch data from databases, call APIs, read cookies
• What you CANNOT do: Modify cookies, redirect users, change session data

2. Server Actions (Action Zone)

• Files: Functions marked with "use server"
• Purpose: Handle user interactions and data changes
• What you CAN do: Everything! Read/write cookies, redirect, modify sessions
• When they run: Only when users submit forms or trigger actions

Why This Separation Exists

Server Components need to be predictable and cacheable. If they could modify cookies or redirect users, it would break React's rendering model and cause unpredictable behavior.

The Cookie Problem (And How to Fix It)

The Error You'll See

Error: Cookies can only be modified in a Server Action or Route Handler

Why It Happens

When you use Supabase (or similar auth libraries) in a Server Component like this:

// ❌ This will break in layout.tsx or page.tsx
const supabase = await createClient();
const { data: user } = await supabase.auth.getUser(); // Tries to write cookies!

The getUser() method might refresh tokens and attempt to write new cookies, but Server Components can't do that.

The Solution: Separate Your Clients

For Server Components (reading data):

// utils/supabase/server-read.ts
export async function createReadOnlySupabase() {
  const cookieStore = await cookies();

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll: () => cookieStore.getAll(),
        // No setAll method = read-only
      },
    }
  );
}

For Server Actions (changing data):

// utils/supabase/server-action.ts
export async function createActionSupabase() {
  const cookieStore = await cookies();

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll: () => cookieStore.getAll(),
        setAll: (cookiesToSet) => {
          cookiesToSet.forEach(({ name, value, options }) => {
            cookieStore.set(name, value, options);
          });
        },
      },
    }
  );
}

Practical Examples

✅ Correct: Reading User Data in a Server Component

// app/dashboard/page.tsx
export default async function DashboardPage() {
  const supabase = await createReadOnlySupabase();
  const { data: user } = await supabase.auth.getUser();

  if (!user) {
    return <div>Please log in</div>;
  }

  return <div>Welcome, {user.email}!</div>;
}

✅ Correct: Logging Out with a Server Action

// app/actions/auth.ts
"use server";
export async function logout() {
  const supabase = await createActionSupabase();
  await supabase.auth.signOut();
  redirect("/login");
}

// app/components/LogoutButton.tsx
export function LogoutButton() {
  return (
    <form action={logout}>
      <button type="submit">Sign Out</button>
    </form>
  );
}

Important Changes in Next.js 15

Cookies Are Now Async

In Next.js 15, you must await the cookies() function:

// ✅ Correct
const cookieStore = await cookies();

// ❌ Wrong (worked in Next.js 14)
const cookieStore = cookies();

Stricter Cookie Rules

The rules about cookie modification are now enforced at runtime:

Quick Reference Guide

When building a page that shows data:

• Use Server Components
• Use read-only Supabase client
• Perfect for dashboards, profiles, lists

When handling user actions:

• Use Server Actions
• Use full Supabase client
• Perfect for login, logout, form submissions

When you need full control:

• Use Route Handlers (app/api/)
• Handle complex logic, file uploads, webhooks

Common Mistakes to Avoid

1. Don't call auth methods in Server Components - Use Server Actions instead
2. Don't forget to await cookies() - It's async in Next.js 15
3. Don't mix read and write operations - Keep them in separate functions
4. Don't try to redirect from Server Components - Use Server Actions

Summary

Next.js 15's strict separation keeps your app fast and predictable. Remember:

• Server Components = Read data, show UI
• Server Actions = Handle user interactions, modify data
• Use the right Supabase client for each context

Follow these patterns, and you'll avoid the common errors that trip up many developers when upgrading to Next.js 15.