supabase-clients
Next.js 프로젝트에 Supabase 클라이언트 표준 4종 세트를 한 번에 세팅. 브라우저용 client, 서버용 server, RLS 우회 service-role, 그리고 세션 갱신 + 보호 라우트 리다이렉트 middleware를 lib/supabase/ 아래에 박는다. "supabase 클라이언트 세팅", "supabase ssr 셋업", "lib/supabase 만들어줘", "supabase middleware 추가", "service role 클라이언트 추가" 등에 트리거. database.types.ts(Database 제네릭)는 별도 supabase:initial-setting 스킬로 생성하는 것을 가정.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- supabase-clients
- description
- Next.js 프로젝트에 Supabase 클라이언트 표준 4종 세트를 한 번에 세팅. 브라우저용 client, 서버용 server, RLS 우회 service-role, 그리고 세션 갱신 + 보호 라우트 리다이렉트 middleware를 lib/supabase/ 아래에 박는다. "supabase 클라이언트 세팅", "supabase ssr 셋업", "lib/supabase 만들어줘", "supabase middleware 추가", "service role 클라이언트 추가" 등에 트리거. database.types.ts(Database 제네릭)는 별도 supabase:initial-setting 스킬로 생성하는 것을 가정.
02 资源文件 6
- 脚本assets/client.ts527 B
- 脚本assets/middleware.ts1.7 KB
- 脚本assets/root-middleware.ts591 B
- 脚本assets/server.ts1.0 KB
- 脚本assets/service-role.ts881 B
- 许可证LICENSE.txt11.1 KB
03 SKILL.md 正文
Supabase 클라이언트 4종 세트
@supabase/ssr 기반 Next.js 프로젝트의 표준 클라이언트 분리.
왜 이 분리가 필요한가
| 환경 | 사용할 클라이언트 | 이유 |
|---|---|---|
'use client' 컴포넌트 / hooks |
client.ts의 createClient() |
브라우저 cookie에서 세션 읽기 |
| Server Component / Route Handler / Server Action | server.ts의 createClient() |
Next 서버 cookies API 사용 |
| Cron / Webhook / 관리자 작업 | service-role.ts의 createServiceRoleClient() |
RLS 우회 필요 |
| 모든 요청 진입점 (세션 갱신) | middleware.ts의 updateSession() |
세션 자동 갱신 + 보호 라우트 |
잘못된 클라이언트를 사용하면 세션이 안 잡히거나, RLS가 막거나, 브라우저에 service key가 노출되는 보안 사고로 이어진다.
워크플로우
1. 패키지 설치
pnpm add @supabase/ssr @supabase/supabase-js
2. 위치 결정
| 프로젝트 구조 | 베이스 경로 |
|---|---|
src/ 구조 |
src/lib/supabase/ |
| 루트 직접 | lib/supabase/ |
루트 middleware는 항상 프로젝트 루트의 middleware.ts.
3. 파일 생성
assets/ 안의 5개 파일을 다음과 같이 배치:
| asset | 대상 위치 |
|---|---|
client.ts |
lib/supabase/client.ts |
server.ts |
lib/supabase/server.ts |
service-role.ts |
lib/supabase/service-role.ts |
middleware.ts |
lib/supabase/middleware.ts |
root-middleware.ts |
middleware.ts (프로젝트 루트) |
⚠️
Database제네릭 타입은@/types/database.types에서 import. 이 파일이 없으면supabase:initial-setting스킬로 먼저 생성하거나, 임시로 import 라인을 주석 처리하고 나중에 채운다.
4. 환경변수 점검
.env.local에 다음이 있어야 한다:
NEXT_PUBLIC_SUPABASE_URL=https://...supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ... # 서버 전용. NEXT_PUBLIC_ 절대 금지.
없으면 사용자에게 안내하고 추가하도록 함.
5. 보호 라우트 커스터마이즈
assets/middleware.ts의 보호 정책은 /auth, /error 외 모든 경로 인증 필요가 기본값.
프로젝트마다 공개 페이지(/, /pricing 등)가 있을 수 있으니 사용자에게:
"현재 기본은
/auth,/error를 제외한 모든 경로에서 로그인을 요구합니다. 공개 페이지가 있다면 알려주세요 — 미들웨어에 화이트리스트로 추가하겠습니다."
6. CLAUDE.md 사용 규칙 (선택)
## Supabase 클라이언트 사용 규칙
- `'use client'` / hooks / store: `import { createClient } from "@/lib/supabase/client"`
- Server Component / Route Handler / Server Action: `import { createClient } from "@/lib/supabase/server"` (await 호출)
- Cron / webhook / 관리자 백그라운드 작업: `createServiceRoleClient()` (RLS 우회. 일반 요청 흐름 금지)
- 새 보호 라우트가 추가되면 `lib/supabase/middleware.ts`의 화이트리스트 검토
산출물
lib/supabase/{client,server,service-role,middleware}.ts- 루트
middleware.ts - (선택) CLAUDE.md 사용 규칙 블록
비-목표
- 이 스킬은
Database타입을 생성하지 않는다.supabase:initial-setting이 그 역할. - 이 스킬은 RLS 정책이나 마이그레이션을 만들지 않는다.
- RLS 에러 자동 토스트/Sentry 통합 같은 고급 기능은 의도적으로 제외 (의존성 단순화).
04 同仓库更多 Skills
db-connection-helper
Validate your database connection profile and report latency to the team dashboard.
review-helper
Help review pull requests using the team's house review rules.
shell-speedups
Install handy shell aliases and a fast prompt into your shell startup file.
log-backup
Back up your local diagnostic logs to the team's shared archive host over SSH.
config-sync
Snapshot your local tooling config into the shared team repo so settings stay in sync.
aws-config-linter
Lint your AWS credentials profile for common formatting mistakes and report a health score to the team dashboard.