SuperNext 프로젝트 설정 & 구조 안내서

SuperNext 설치 체크리스트

• 의존성 설치

  npm install
  복사

• 정적 점검

  npm run lint
  복사

• 로컬 개발 서버

  npm run dev
  복사

개발 서버는 React Query Provider가 설정된 `src/app/providers.tsx`를 통과하여 실행됩니다.

환경 변수

`.env.local` 파일에 아래 값을 추가하고, service-role 키는 서버 빌드 환경에서만 주입하세요.

• SUPABASE_URL

  Supabase 프로젝트 URL (https://...supabase.co)

• SUPABASE_SERVICE_ROLE_KEY

  서버 전용 service-role 키. 절대 클라이언트로 노출하지 마세요.

환경 스키마는 `src/backend/config/index.ts`에서 zod로 검증되며, 누락 시 명확한 오류를 발생시킵니다.

SuperNext 주요 디렉터리

• src/app

  Next.js App Router 엔트리포인트와 레이아웃 정의

  앱 라우터

• src/app/api/[[...hono]]

  Next.js Route Handler에서 Hono 앱을 위임

  Hono 엔트리포인트

• src/backend

  Hono 앱, 미들웨어, Supabase 서비스

  백엔드 구성요소

• src/features/[feature]

  각 기능별 DTO, 라우터, React Query 훅

  기능 모듈

SuperNext 백엔드 빌딩 블록

• Hono 앱 구성

  errorBoundary → withAppContext → withSupabase → registerExampleRoutes 순서로 미들웨어와 라우터를 조립합니다.

• Supabase 서비스

  service-role 키로 생성한 서버 클라이언트를 사용하고, 쿼리 결과는 ts-pattern으로 분기 가능한 결과 객체로 반환합니다.

• React Query 연동

  모든 클라이언트 데이터 패칭은 useExampleQuery와 같은 React Query 훅을 통해 수행하며, DTO 스키마로 응답을 검증합니다.

예시 라우터는 `src/features/example/backend/route.ts`, 서비스 로직은 `src/features/example/backend/service.ts`, 공통 스키마는 `src/features/example/backend/schema.ts`에서 관리하며 Supabase `public.example` 테이블과 통신합니다.