Next.js 15 + Supabase Auth + PWA

Complete implementation guide for adding Supabase authentication to a Next.js 15 App Router PWA

📚 Overview

This application serves as a complete reference implementation for integrating Supabase authentication into a Next.js 15 Progressive Web App.

Tech Stack:

✅ Next.js 15.5.4 (App Router)
✅ React 19.1.0
✅ Supabase Auth (@supabase/ssr)
✅ TypeScript
✅ Tailwind CSS v4
✅ PWA Support (@ducanh2912/next-pwa)

🏗️ Architecture

Auth Flow

User signs up with email/password
Supabase sends confirmation email
User clicks confirmation link
Route handler verifies token and logs user in
Middleware refreshes session on every request
Session stored in cookies (httpOnly, secure)

Key Components

Server Client: Used in Server Components, Route Handlers, and Server Actions
Browser Client: Used in Client Components ("use client")
Middleware Client: Refreshes sessions on every request
Middleware: Runs before every page load to maintain auth state

🚀 Implementation Guide (7 Phases)

Follow these phases in order. Each phase builds on the previous one. Test pages are provided to verify each phase works correctly.

Phase 1: Setup & Dependencies

Install packages, configure environment, verify TypeScript paths

• Install @supabase/ssr and @supabase/supabase-js

• Configure .env.local with Supabase credentials

• Verify tsconfig.json path aliases

• Create lib/utils.ts

Test →

Phase 2: Supabase Clients

Create server, browser, and middleware Supabase clients

• Create lib/supabase/server.ts

• Create lib/supabase/client.ts

• Create lib/supabase/middleware.ts

Test →

Phase 3: Middleware

Set up middleware to refresh auth sessions automatically

• Create src/middleware.ts

• Configure matcher to exclude static files

• Implement session refresh on every request

Test →

Phase 4: Auth Routes

Create authentication pages and route handlers

• Create /auth/login page

• Create /auth/sign-up page

• Create /auth/confirm route handler

• Create /auth/error and /auth/sign-up-success pages

Test →

Phase 5: Auth Components & Forms

Build login, signup, logout components with full functionality

• Create LoginForm component

• Create SignUpForm component

• Create LogoutButton component

• Create AuthButton component

• Add AuthButton to header

Test →

Phase 6: Supabase Dashboard Config

Configure production redirect URLs and optional settings

• Add production URLs to Supabase redirect list

• Configure Site URL

• Optional: Customize email templates

• Optional: Configure custom SMTP

Guide →

Phase 7: Protected Pages & Integration

Add protected pages, feature gating, and final testing

• Create protected page examples

• Implement feature gating patterns

• End-to-end integration testing

• Production readiness checklist

Test →

📁 Key Files & Structure

src/
├── middleware.ts
├── lib/
│   ├── supabase/
│   │   ├── server.ts
│   │   ├── client.ts
│   │   └── middleware.ts
│   └── utils.ts
├── components/
│   ├── login-form.tsx
│   ├── sign-up-form.tsx
│   ├── logout-button.tsx
│   └── auth-button.tsx
├── app/
│   ├── auth/
│   │   ├── login/page.tsx
│   │   ├── sign-up/page.tsx
│   │   ├── confirm/route.ts
│   │   ├── error/page.tsx
│   │   └── sign-up-success/page.tsx
│   └── components/
│       ├── Header.tsx
│       └── NavDropdown.tsx
└── .env.local

Key files explained:

• middleware.ts - Session refresh middleware
• lib/supabase/server.ts - Server-side client
• lib/supabase/client.ts - Browser-side client
• lib/supabase/middleware.ts - Middleware client
• components/ - Auth forms and buttons
• app/auth/ - Authentication pages and handlers

💻 Common Code Patterns

Check Auth in Server Component

import { createClient } from "@/lib/supabase/server";

export default async function MyPage() {
  const supabase = await createClient();
  const { data } = await supabase.auth.getUser();
  const user = data?.user;

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

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

Check Auth in Client Component

"use client";
import { createClient } from "@/lib/supabase/client";
import { useEffect, useState } from "react";

export function MyComponent() {
  const [user, setUser] = useState(null);

  useEffect(() => {
    const supabase = createClient();
    supabase.auth.getUser().then(({ data }) => {
      setUser(data.user);
    });
  }, []);

  return user ? <div>Logged in!</div> : <div>Not logged in</div>;
}

Protected Route Pattern

import { createClient } from "@/lib/supabase/server";
import { redirect } from "next/navigation";

export default async function ProtectedPage() {
  const supabase = await createClient();
  const { data } = await supabase.auth.getUser();
  
  if (!data.user) {
    redirect("/auth/login");
  }

  return <div>Protected content for {data.user.email}</div>;
}

🔧 Troubleshooting

Email confirmation not working?

Check that your production URL is added to Supabase redirect URLs with the /** wildcard

Session not persisting?

Ensure middleware is configured correctly and calling updateSession()

Random logouts?

Make sure middleware is calling await supabase.auth.getClaims() to refresh the session

TypeScript errors with env vars?

Add ! assertion: process.env.NEXT_PUBLIC_SUPABASE_URL!

🔗 Resources

This implementation guide serves as a reference for developers implementing Supabase authentication in Next.js 15 Progressive Web Apps.

All code is tested and production-ready. Feel free to use as a template! 🚀