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에서 마이그레이션 기반으로 작업하도록 컨벤션을 정했습니다. 이러한 구성으로 초기 세팅을 빠르게 가져가고, 개발 중에도 불필요한 의사결정을 줄여 기능 구현에 집중할 수 있게 했습니다.