Next.js + Supabase Auth
선택적 읽기 규칙
다음 항목부터 시작하세요:
references/senior-master-standard.mdreferences/usage-routing.mdreferences/quality-checklist.md
그런 다음 사용자의 실제 작업과 일치하는 상속된 문서, 스크립트, 자산 또는 예제만 로드하세요.
Next.js App Router와 Supabase Auth의 전문적인 통합
기능
- nextjs-auth
- supabase-auth-nextjs
- auth-middleware
- auth-callback
전제 조건
- 필수 스킬: nextjs-app-router, supabase-backend
패턴
Supabase 클라이언트 설정
다양한 컨텍스트에 맞게 올바르게 구성된 Supabase 클라이언트 생성
사용 시기: Next.js 프로젝트에서 인증 설정 시
// lib/supabase/client.ts (브라우저 클라이언트)
'use client'
import { createBrowserClient } from '@supabase/ssr'
export function createClient() {
return createBrowserClient(
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'
export async function createClient() {
const cookieStore = await cookies()
return createServerClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
{
cookies: {
getAll() {
return cookieStore.getAll()
},
setAll(cookiesToSet) {
cookiesToSet.forEach(({ name, value, options }) => {
cookieStore.set(name, value, options)
})
},
},
}
)
}
인증 미들웨어
미들웨어에서 라우트 보호 및 세션 새로 고침
사용 시기: 라우트 보호 또는 세션 새로 고침이 필요할 때
// middleware.ts
import { createServerClient } from '@supabase/ssr'
import { NextResponse, type NextRequest } from 'next/server'
export async function middleware(request: NextRequest) {
let response = NextResponse.next({ request })
const supabase = createServerClient(
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, options }) => {
response.cookies.set(name, value, options)
})
},
},
}
)
// 만료된 세션 새로 고침
const { data: { user } } = await supabase.auth.getUser()
// 대시보드 라우트 보호
if (request.nextUrl.pathname.startsWith('/dashboard') && !user) {
return NextResponse.redirect(new URL('/login', request.url))
}
return response
}
export const config = {
matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}
인증 콜백 라우트
OAuth 콜백 처리 및 코드를 세션으로 교환
사용 시기: OAuth 제공자(Google, GitHub 등) 사용 시
// app/auth/callback/route.ts
import { createClient } from '@/lib/supabase/server'
import { NextResponse } from 'next/server'
export async function GET(request: Request) {
const { searchParams, origin } = new URL(request.url)
const code = searchParams.get('code')
const next = 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`)
}
서버 액션 인증
서버 액션에서 인증 작업 처리
사용 시기: 서버 컴포넌트에서 로그인, 로그아웃 또는 회원가입 시
// app/actions/auth.ts
'use server'
import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'
import { revalidatePath } from 'next/cache'
export async function signIn(formData: FormData) {
const supabase = await createClient()
const { error } = await supabase.auth.signInWithPassword({
email: formData.get('email') as string,
password: formData.get('password') as string,
})
if (error) {
return { error: error.message }
}
revalidatePath('/', 'layout')
redirect('/dashboard')
}
export async function signOut() {
const supabase = await createClient()
await supabase.auth.signOut()
revalidatePath('/', 'layout')
redirect('/')
}
서버 컴포넌트에서 사용자 정보 가져오기
서버 컴포넌트에서 인증된 사용자에 접근
사용 시기: 서버 측에서 사용자별 콘텐츠 렌더링 시
// app/dashboard/page.tsx
import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'
export default async function DashboardPage() {
const supabase = await createClient()
const { data: { user } } = await supabase.auth.getUser()
if (!user) {
redirect('/login')
}
return (
<div>
<h1>환영합니다, {user.email}</h1>
</div>
)
}
검증 확인 사항
인증 확인에 getSession() 사용
심각도: 오류
메시지: getSession()은 JWT를 확인하지 않습니다. 보안 인증 확인에는 getUser()를 사용하세요.
수정 조치: 보안에 중요한 확인 사항에 대해 getSession()을 getUser()로 대체하세요.
OAuth 콜백 라우트 누락
심각도: 오류
메시지: OAuth를 사용하지만 app/auth/callback/route.ts에 콜백 라우트가 없습니다.
수정 조치: OAuth 리디렉션을 처리하기 위해 app/auth/callback/route.ts를 생성하세요.
서버 컨텍스트에서 브라우저 클라이언트 사용
심각도: 오류
메시지: 서버 컨텍스트에서 브라우저 클라이언트가 사용되었습니다. createServerClient를 대신 사용하세요.
수정 조치: @supabase/ssr에서 createServerClient를 가져와 사용하세요.
미들웨어 없는 보호된 라우트
심각도: 경고
메시지: middleware.ts가 없습니다. 라우트 보호를 위해 미들웨어 추가를 고려하세요.
수정 조치: 라우트를 보호하고 세션을 새로 고치기 위해 middleware.ts를 생성하세요.
하드코딩된 인증 리디렉션 URL
심각도: 경고
메시지: 하드코딩된 localhost 리디렉션입니다. 환경 유연성을 위해 origin을 사용하세요.
수정 조치: window.location.origin 또는 process.env.NEXT_PUBLIC_SITE_URL을 사용하세요.
오류 처리가 없는 인증 호출
심각도: 경고
메시지: 오류 처리가 없는 인증 작업입니다. 항상 오류를 확인하세요.
수정 조치: { data, error }를 분해하고 오류 사례를 처리하세요.
재검증 없는 인증 액션
심각도: 경고
메시지: revalidatePath가 없는 인증 액션입니다. 캐시에 오래된 인증 상태가 표시될 수 있습니다.
수정 조치: 인증 작업 후 revalidatePath('/', 'layout')를 추가하세요.
클라이언트 전용 라우트 보호
심각도: 경고
메시지: 클라이언트 측 라우트 보호는 콘텐츠가 깜빡이는 현상을 보여줍니다. 미들웨어를 사용하세요.
수정 조치: 더 나은 사용자 경험을 위해 보호 로직을 middleware.ts로 이동하세요.
협업
위임 트리거
- database|rls|queries|tables -> supabase-backend (인증에 데이터베이스 계층 필요)
- route|page|component|layout -> nextjs-app-router (인증에 Next.js 패턴 필요)
- deploy|production|vercel -> vercel-deployment (인증에 배포 설정 필요)
- ui|form|button|design -> frontend (인증에 UI 컴포넌트 필요)
전체 인증 스택
스킬: nextjs-supabase-auth, supabase-backend, nextjs-app-router, vercel-deployment
워크플로:
1. 데이터베이스 설정 (supabase-backend)
2. 인증 구현 (nextjs-supabase-auth)
3. 라우트 보호 (nextjs-app-router)
4. 배포 설정 (vercel-deployment)
보호된 SaaS
스킬: nextjs-supabase-auth, stripe-integration, supabase-backend
워크플로:
1. 사용자 인증 (nextjs-supabase-auth)
2. 고객 동기화 (stripe-integration)
3. 구독 게이팅 (supabase-backend)
관련 스킬
다음과 함께 잘 작동합니다: nextjs-app-router, supabase-backend
사용 시기
- 사용자가 언급하거나 암시하는 경우: supabase auth next
- 사용자가 언급하거나 암시하는 경우: authentication next.js
- 사용자가 언급하거나 암시하는 경우: login supabase
- 사용자가 언급하거나 암시하는 경우: auth middleware
- 사용자가 언급하거나 암시하는 경우: protected route
- 사용자가 언급하거나 암시하는 경우: auth callback
- 사용자가 언급하거나 암시하는 경우: session management
제한 사항
- 이 스킬은 작업이 위에 설명된 범위와 명확하게 일치하는 경우에만 사용하세요.
- 출력물을 환경별 검증, 테스트 또는 전문가 검토를 대체하는 것으로 취급하지 마세요.
- 필수 입력, 권한, 안전 경계 또는 성공 기준이 누락된 경우 중단하고 명확히 설명을 요청하세요.