Next.js 16 + Supabase + GitHub OAuth

Browser  ──sign in──▶  Supabase  ──▶  GitHub
                                       │
   GitHub ──callback──▶ Supabase ◀──────┘
                           │
                           ▼
   /auth/callback?code=... ──exchange──▶ session cookies
                           │
                           ▼
              proxy.ts refreshes on every request
                           │
                           ▼
           Server Components read the user

npx create-next-app@latest my-app --typescript --tailwind --app --no-src-dir
cd my-app

npm install @supabase/supabase-js @supabase/ssr

# .env.local  (gitignored)
NEXT_PUBLIC_SUPABASE_URL=https://<your-project-ref>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<your-anon-or-publishable-key>

# Server-only. Bypasses RLS entirely — never prefix this with NEXT_PUBLIC_.
SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key>

// lib/supabase/client.ts
import { createBrowserClient } from "@supabase/ssr";
import type { Database } from "@/types/supabase";

export function createClient() {
  return createBrowserClient<Database>(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
  );
}

// lib/supabase/server.ts
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";
import type { Database } from "@/types/supabase";

export async function createClient() {
  const cookieStore = await cookies();

  return createServerClient<Database>(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll();
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options),
            );
          } catch {
            // Called from a Server Component, which cannot set cookies.
            // Safe to ignore — proxy.ts refreshes the session instead.
          }
        },
      },
    },
  );
}

# Official codemod handles both the filename and the function name
npx @next/codemod@canary middleware-to-proxy .

// proxy.ts
import { createServerClient } from "@supabase/ssr";
import { NextResponse, type NextRequest } from "next/server";
import type { Database } from "@/types/supabase";

export async function proxy(request: NextRequest) {
  let response = NextResponse.next({ request });

  const supabase = createServerClient<Database>(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return request.cookies.getAll();
        },
        setAll(cookiesToSet) {
          cookiesToSet.forEach(({ name, value }) =>
            request.cookies.set(name, value),
          );
          response = NextResponse.next({ request });
          cookiesToSet.forEach(({ name, value, options }) =>
            response.cookies.set(name, value, options),
          );
        },
      },
    },
  );

  // Revalidates the token. Required for Server Components to see the user.
  await supabase.auth.getClaims();

  return response;
}

export const config = {
  matcher: [
    /*
     * Everything except:
     *  - _next/static, _next/image  (build output)
     *  - favicon.ico, robots.txt, sitemap.xml  (crawler metadata)
     *  - image files
     */
    "/((?!_next/static|_next/image|favicon\\.ico|robots\\.txt|sitemap\\.xml|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
  ],
};

GitHub → Settings → Developer settings → OAuth Apps → New OAuth App

Application name:     Your App Name
Homepage URL:         https://www.yourdomain.com
Authorization callback URL:
                      https://<your-project-ref>.supabase.co/auth/v1/callback

                      ^^^ Supabase, NOT https://yourdomain.com/auth/callback

Then copy the Client ID and generate a Client Secret.

Supabase Dashboard → Authentication → Providers → GitHub
  Enabled:        yes
  Client ID:      <from GitHub>
  Client Secret:  <from GitHub>

Supabase Dashboard → Authentication → URL Configuration
  Site URL:       https://www.yourdomain.com
  Redirect URLs:  https://www.yourdomain.com/auth/callback
                  http://localhost:3000/auth/callback

Add both the production and localhost callbacks, or local development breaks.

"use client";

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

export function SignInButton() {
  const supabase = createClient();

  async function signIn() {
    await supabase.auth.signInWithOAuth({
      provider: "github",
      options: {
        redirectTo: `${window.location.origin}/auth/callback`,
      },
    });
  }

  return <button onClick={signIn}>Sign in with GitHub</button>;
}

// app/auth/callback/route.ts
import { NextResponse, type NextRequest } from "next/server";
import { createClient } from "@/lib/supabase/server";

// Only allow same-origin paths: must start with a single "/",
// not "//" (protocol-relative) and must not contain a scheme.
function safeRedirectPath(raw: string | null): string {
  if (!raw) return "/";
  if (!raw.startsWith("/") || raw.startsWith("//")) return "/";
  if (/^\/[^/]*:/.test(raw)) return "/";
  return raw;
}

export async function GET(request: NextRequest) {
  const { searchParams, origin } = new URL(request.url);
  const code = searchParams.get("code");
  const next = safeRedirectPath(searchParams.get("next"));

  if (code) {
    const supabase = await createClient();
    const { error } = await supabase.auth.exchangeCodeForSession(code);
    if (!error) {
      return NextResponse.redirect(`${origin}${next}`);
    }
  }

  return NextResponse.redirect(`${origin}/auth/error`);
}

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

export default async function ProtectedPage() {
  const supabase = await createClient();

  // Verified — safe for authorization
  const { data, error } = await supabase.auth.getClaims();
  if (error || !data?.claims) redirect("/login");

  return <p>Signed in as {data.claims.sub}</p>;
}

// getUser()    → network round trip, freshest user record
// getClaims()  → verifies JWT signature, cheap, use for page protection
// getSession() → NO verification. Never trust it in server code.

-- Enable RLS on every table. A table without it is world-readable
-- and world-writable through the anon key.
alter table profiles enable row level security;

-- Anyone may read
create policy "profiles are publicly readable"
  on profiles for select
  using (true);

-- Only the owner may insert their own row
create policy "users insert their own profile"
  on profiles for insert to authenticated
  with check (auth.uid() = id);

-- Only the owner may update it
create policy "users update their own profile"
  on profiles for update to authenticated
  using (auth.uid() = id)
  with check (auth.uid() = id);

Symptom                          │ Cause
─────────────────────────────────┼──────────────────────────────────────
redirect_uri is not associated   │ GitHub callback points at your app.
  with this application          │ It must point at Supabase.
─────────────────────────────────┼──────────────────────────────────────
Lands on homepage with ?code=    │ redirectTo not in Supabase's Redirect
  still in the URL, logged out   │ URLs. It fell back to Site URL.
─────────────────────────────────┼──────────────────────────────────────
Works, then logged out ~1 hour   │ proxy.ts not running. Check the
  later                          │ filename — middleware.ts is inert
                                 │ in Next.js 16.
─────────────────────────────────┼──────────────────────────────────────
User visible in Client but not   │ Session never reached the server.
  in Server Components           │ Check the matcher covers the route.
─────────────────────────────────┼──────────────────────────────────────
Works locally, fails deployed    │ Production callback URL missing from
                                 │ the allowlist, or canonical host
                                 │ mismatch (www vs apex).
─────────────────────────────────┼──────────────────────────────────────
Queries return zero rows for a   │ RLS enabled with no SELECT policy.
  signed-in user                 │