React Supabase 연동 방법: 빠르게 배우는 개발 가이드

1. React와 Supabase를 함께 쓰는 이유

React Supabase 연동 방법의 출발점은 React가 화면을 담당하고 Supabase가 데이터와 API를 담당한다는 구조를 이해하는 것입니다. Supabase는 PostgreSQL 기반의 BaaS이므로 별도 서버를 직접 만들지 않아도 인증, 데이터베이스, API를 빠르게 붙일 수 있습니다.

이 조합은 작은 서비스, MVP, 내부 도구처럼 빠른 구현이 중요한 프로젝트에 특히 잘 맞습니다. SQL에 익숙하다면 데이터 구조를 이해하기 쉽고, React 쪽은 UI에 집중할 수 있습니다.

• React는 UI와 상태 관리를 맡습니다.
• Supabase는 데이터 저장, 조회, 인증, API를 맡습니다.
• 서버 구축 부담을 줄이고 개발 속도를 높일 수 있습니다.

Supabase 프로젝트 생성부터 환경 변수 설정, CRUD 구현까지의 흐름을 한 번에 잡으면 전체 구조가 훨씬 명확해집니다.

2. Supabase 프로젝트 생성과 연결 정보 확인

가장 먼저 Supabase 대시보드에서 새 프로젝트를 생성합니다. 프로젝트 이름, 데이터베이스 비밀번호, 리전을 설정한 뒤 생성하면 됩니다.

생성 후에는 Project URL과 anon/publishable key를 반드시 확인해야 합니다. 이 값은 React 앱이 Supabase와 연결될 때 필요하므로, 다음 단계로 넘어가기 전에 먼저 확보하는 것이 좋습니다.

확인 항목	의미
Project URL	React가 연결할 Supabase 주소
anon/publishable key	공개 클라이언트용 연결 키
리전	데이터베이스가 위치한 지역

프로젝트만 만들고 끝이라고 생각하기 쉽지만, 실제로는 연결 정보 확보가 먼저입니다. 이 단계가 정리되어야 이후 설정이 매끄럽게 이어집니다.

3. React 프로젝트 준비와 Supabase 클라이언트 설치

기존 React 프로젝트가 있다면 해당 폴더에서 진행하면 되고, 없다면 Vite 기반으로 새 프로젝트를 시작하는 방식이 빠릅니다. 그다음 Supabase 클라이언트 라이브러리를 설치합니다.

핵심 패키지는 @supabase/supabase-js이며, React 앱이 Supabase API와 통신할 수 있도록 해주는 공식 도구입니다. 설치만으로 연결이 끝나는 것은 아니고, 이후 createClient를 만들기 위한 준비 단계로 이해하면 됩니다.

npm install @supabase/supabase-js

yarn add @supabase/supabase-js

• 패키지는 한 번만 설치하면 됩니다.
• 클라이언트 생성 코드는 별도 파일로 분리하는 것이 좋습니다.
• 설치 후에는 환경 변수 설정으로 넘어갑니다.

4. 환경 변수 설정과 createClient 구성

React 환경 변수 설정 Supabase는 보안과 유지보수를 위해 꼭 필요합니다. URL과 키를 코드에 직접 넣지 말고 .env.local 같은 환경 변수 파일에 저장해야 합니다.

Vite를 사용한다면 환경 변수 이름 앞에 VITE_ 접두사를 붙여야 합니다. 예를 들어 VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY 형태로 지정합니다.

VITE_SUPABASE_URL=your-project-url
VITE_SUPABASE_ANON_KEY=your-anon-key

그다음 전용 파일에서 createClient를 한 번만 생성해 재사용합니다. 이렇게 하면 코드가 분산되지 않고 관리가 쉬워집니다.

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

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY

export const supabase = createClient(supabaseUrl, supabaseAnonKey)

중요한 점은 Vite 프로젝트에서 접두사를 빼면 값이 읽히지 않을 수 있다는 것입니다. 환경 변수는 나중에 키를 교체할 때도 유리하므로, 처음부터 분리해 두는 편이 안전합니다.

5. 테이블 준비와 데이터 구조 설계

React에서 데이터를 보여주려면 먼저 Supabase에 테이블이 있어야 합니다. 예를 들어 posts, todos, items 같은 테이블을 만들고, 앱이 필요로 하는 컬럼을 맞춰 두면 됩니다.

중요한 것은 단순히 테이블을 만드는 것이 아니라, 화면에서 실제로 읽고 쓸 데이터 구조를 먼저 생각하는 것입니다. 필요하면 JSONB 같은 타입을 사용해 유연하게 저장할 수도 있습니다.

예시 테이블	주요 컬럼
posts	id, title, content, created_at
todos	id, task, done, created_at
items	id, name, description, response_data

이 구조는 이후 조회와 CRUD 예제와 바로 연결됩니다. 즉, 테이블 설계가 곧 화면 설계의 기반이라고 볼 수 있습니다.

6. 데이터 조회와 기본 CRUD 구현

실제 연결은 보통 useEffect와 useState로 시작합니다. 컴포넌트가 처음 렌더링될 때 supabase.from('테이블명').select('*')로 데이터를 가져와 상태에 저장하면 됩니다.

조회가 되면 다음은 CRUD입니다. insert()는 추가, update()는 수정, delete()는 삭제를 담당하며, 조건은 보통 eq()로 지정합니다.

useEffect(() => {
  const fetchData = async () => {
    const { data, error } = await supabase.from('posts').select('*')

    if (error) console.error(error)
    else setPosts(data)
  }

  fetchData()
}, [])

함수	역할	함께 자주 쓰는 것
insert()	데이터 추가	객체 데이터
update()	데이터 수정	eq() 조건
delete()	데이터 삭제	eq() 조건
select()	데이터 조회	‘*’ 또는 컬럼명

이 흐름을 익히면 React와 Supabase의 기본 연결은 끝난 것입니다. 단순 조회 앱에서 실무형 데이터 앱으로 확장하는 핵심도 바로 이 패턴에 있습니다.

7. 권한 정책과 자주 하는 실수

데이터가 보이지 않을 때는 권한 정책을 먼저 확인해야 합니다. Supabase는 테이블별 정책을 둘 수 있어서, 공개 조회를 허용하지 않으면 select()가 실패할 수 있습니다.

초보자 단계에서는 읽기만 허용하는 정책부터 확인하면 충분합니다. 코드가 맞는데 데이터가 안 보이면 정책을 보는 순서가 가장 효율적입니다.

• VITE_ 접두사 누락은 환경 변수 미인식의 원인이 됩니다.
• 테이블명 오타는 조회 실패로 바로 이어집니다.
• 키를 코드에 직접 넣으면 보안 관리가 어려워집니다.
• 클라이언트를 여러 곳에서 중복 생성하면 유지보수가 불편해집니다.
• 정책 미설정은 데이터 미표시의 대표적인 원인입니다.

문제를 찾을 때는 환경 변수, 테이블명, 정책 순서로 점검하면 빠릅니다. 이 순서를 기억하면 초보자도 원인을 훨씬 쉽게 찾을 수 있습니다.

8. 자주 묻는 질문 (FAQ)

React와 Supabase를 처음 연결할 때 가장 중요한 것은 무엇인가요?

가장 중요한 것은 환경 변수와 createClient입니다. URL과 키를 분리해 저장하고, 전용 파일에서 클라이언트를 한 번만 생성해 재사용해야 합니다.

Supabase 키를 React 코드에 직접 넣어도 되나요?

권장하지 않습니다. URL과 키는 .env.local에 저장하고, React에서는 환경 변수로 읽는 방식이 유지보수와 보안에 유리합니다.

Vite 프로젝트에서 환경 변수가 안 읽히는 이유는 무엇인가요?

Vite는 환경 변수 이름 앞에 VITE_ 접두사가 필요합니다. 이 접두사가 없으면 값이 인식되지 않을 수 있습니다.

데이터는 저장되는데 화면에 안 보일 때는 무엇을 확인해야 하나요?

먼저 테이블명 오타를 확인하고, 그다음 정책을 확인해야 합니다. 마지막으로 쿼리 결과를 콘솔에서 점검하면 원인 파악이 쉽습니다.

CRUD 중 가장 먼저 익혀야 하는 것은 무엇인가요?

보통 select()로 조회부터 익히는 것이 좋습니다. 조회가 되면 insert(), update(), delete() 순서로 확장하면 됩니다.