프로젝트 설정과 클라이언트

Supabase를 사용하려면 먼저 콘솔에서 프로젝트를 생성하고, 발급받은 URL과 키로 클라이언트를 초기화해야 합니다. 이 강의에서는 프로젝트 생성부터 @supabase/supabase-js 설치, 그리고 안전한 환경변수 관리까지 살펴봅니다.

학습 목표

• Supabase 콘솔에서 새 프로젝트를 생성하는 흐름을 안다.
• @supabase/supabase-js v2를 설치하고 클라이언트를 초기화한다.
• Project URL과 anon key의 역할을 구분한다.
• 환경변수를 사용해 키를 안전하게 관리한다.

프로젝트 생성

Supabase 콘솔에 접속해 New project를 클릭합니다. 조직(Organization)을 선택하고 다음 항목을 입력합니다.

• Name — 프로젝트 이름
• Database Password — Postgres 데이터베이스 비밀번호 (안전하게 보관)
• Region — 사용자와 가까운 지역 선택

프로젝트가 생성되면 잠시 후 Postgres 인스턴스가 준비됩니다. 생성된 프로젝트의 Settings → API 메뉴에서 연결에 필요한 값들을 확인할 수 있습니다.

supabase-js 설치

프론트엔드 또는 서버 프로젝트에 클라이언트 SDK를 설치합니다.

npm install @supabase/supabase-js

v2부터는 createClient 함수 하나로 모든 기능에 접근합니다.

클라이언트 초기화

Settings → API에서 Project URL과 anon public 키를 복사해 클라이언트를 만듭니다.

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  'https://xxxxxxxx.supabase.co', // Project URL
  'your-anon-key',                // anon public key
);

export default supabase;

이 supabase 객체로 데이터베이스 조회, 인증, 스토리지 등 모든 기능을 사용합니다.

URL과 anon key의 역할

값	설명	노출 가능 여부
Project URL	API 엔드포인트 주소	가능
anon key	익명 사용자 권한의 공개 키	가능 (단, RLS 필수)
service_role key	모든 권한을 가진 관리자 키	절대 불가

anon key는 클라이언트에 노출되어도 괜찮지만, 데이터 보호는 전적으로 Row Level Security 정책에 의존합니다.

⚠️ 주의 — service_role 키는 RLS를 우회하는 강력한 키입니다. 절대 클라이언트 코드나 깃 저장소에 포함하지 마세요. 서버 환경에서만 사용해야 합니다.

환경변수로 관리하기

키를 코드에 직접 적지 말고 환경변수로 분리합니다. Next.js에서는 NEXT_PUBLIC_ 접두사가 붙은 변수만 브라우저에 노출됩니다.

# .env.local
NEXT_PUBLIC_SUPABASE_URL=https://xxxxxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

import { createClient } from '@supabase/supabase-js';

export const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
);

💡 TIP — .env.local은 반드시 .gitignore에 포함해 커밋되지 않도록 하세요. 배포 환경에서는 호스팅 서비스의 환경변수 설정 화면에 같은 값을 등록합니다.

요약

• Supabase 콘솔에서 프로젝트를 만들면 Postgres 인스턴스와 API가 준비됩니다.
• @supabase/supabase-js v2를 설치하고 createClient로 클라이언트를 초기화합니다.
• Project URL과 anon key는 공개 가능하지만 service_role 키는 비밀로 유지합니다.
• 키는 환경변수로 분리하고, anon key의 보안은 RLS로 보장합니다.

연습문제

1. Supabase 프로젝트를 생성할 때 입력해야 하는 필수 항목 세 가지는 무엇인가?
2. createClient에 전달하는 두 가지 인자는 각각 무엇인가?
3. anon key와 service_role key의 가장 큰 차이는 무엇인가?
4. Next.js에서 브라우저에 노출되는 환경변수를 만들려면 어떤 규칙을 따라야 하는가?

힌트 — 콘솔의 Settings → API 화면과 Next.js 환경변수 규칙을 떠올려 보세요.