
03
어드민 보일러플레이트
재사용 개발 보일러플레이트
- 기간
- 2025.11 – 2026.03
- 상태
- 4개 프로젝트 적용
- 형태
- Next.js 어드민 보일러플레이트
- 기여도
- 단독 설계 · 개발 · 문서화
- SKILLS
- Next.js
- React
- TypeScript
- Tailwind CSS
- shadcn/ui
- React Hook Form
- Supabase
- NextAuth
- Claude Code
개요
프리랜서 업무 시 고객사 프로젝트의 어드민 개발 효율성을 목적으로 구성한 보일러플레이트입니다.
어드민 개발에서 자주 사용되는 화면 구조와 공유 UI 및 CRUD 서버 함수 등으로 구성되어있으며, 프로젝트별 요구사항에 대응하고 구조를 고민하는 비용을 줄이고자 기획되었습니다.
구축 후 4개 프로젝트에 적용하고, 적용 과정에서 기능 및 구조를 개선했습니다.
담당 범위
- 기본 UI · CRUD 함수 · 관리 모듈 구조 설계 및 개발
- 프로젝트 초기화 · 개발 컨벤션과 워크플로우 구성
- 고객사 프로젝트 적용 및 구조 개선 · 유지보수
주요 사례
관리 모듈 중심 어드민 개발 구조 설계
설계 목적
- 관리 화면 별 공유되는 기능과 도메인별 기능을 인프라, 관리 모듈로 구분하여 개발 영역 설계
- 프로젝트별 개발 작업을 관리 모듈 중심으로 진행하여 인프라 재구성 비용 최소화
- 인프라에서 관리 모듈의 기본 컴포넌트 구조를 제공, 화면 구성과 데이터 연결의 설계 비용 절감
- 기본 구조 위에서 프로젝트별 요구사항에 따른 화면과 업무 로직 작성 가능한 자유도 확보
구조 및 개발 방식
_base레이어에 기본 UI와 데이터 처리 기능 배치, 관리 모듈에서 사용하는 구조로 구성- 모듈별
config.ts로 기본 동작을 설정하여 인프라 코드의 수정 범위 최소화 - 기본 컴포넌트 구조 제공, 기존 모듈을 복제 · 수정하여 새 관리 기능을 추가하도록 구성
- 화면과 업무 로직은 모듈별로 직접 작성하여 프로젝트별 요구사항에 대응
유지보수 부담을 줄이기 위한 구조 단순화
문제 상황
- 실제 프로젝트 개발시 중첩된 Server Action 팩토리의 실행 플로우와 구조 파악의 어려움 발생
- Supabase SDK로부터 응답받은 필드명을 camelCase로 변환하는 레이어에서 필드명 작성 병목 발생
문제 해결
- 코드의 중복을 감수하고 모듈에서 로직을 직접 확인할 수 있는 것이 유지보수에 적합하다고 판단함
- 기본 CRUD의 재사용은 유지, 서버액션 팩토리 함수를 제거하여 모듈에서 기본 함수를 직접 호출하거나 비즈니스 로직을 작성하는 방식으로 변경
- 1인 풀스택 개발 환경에서는 camelCase 표기 통일보다 DB · 서버 · 화면에서 같은 필드명을 사용하는 편이 데이터 추적과 수정에 적합하다고 판단
- 필드명 변환 계층을 제거하고 DB의 snake_case 필드명을 그대로 사용하도록 통일
결과
- 함수 구조 파악 비용과 모듈별 커스텀 요구사항의 구현 시 의사 결정 비용 감소
- 필드명 변환을 위한 타입과 함수를 별도로 관리하는 부담 제거
개발 워크플로우
Supabase 기반 프로젝트 초기화 및 유지보수
Supabase 초기화 흐름은 PC에 프로그램을 설치하는 과정에 착안해 설계했습니다. 새 프로젝트를 시작할 때 앱을 구동하기 위한 필수 구조를 초기화하도록 마이그레이션을 구성했습니다. 그 외 기본 관리 테이블들은 별도의 마이그레이션 파일로 준비해두어 필요 시 적용할 수 있도록 하였습니다.
개발 중에는 로컬 Supabase CLI에서 마이그레이션 기반으로 작업하도록 컨벤션을 정했습니다. 이러한 구성으로 초기 세팅을 빠르게 가져가고, 개발 중에도 불필요한 의사결정을 줄여 기능 구현에 집중할 수 있게 했습니다.