프로젝트 셋업

관리자 허브의 토대는 가벼운 Next.js 16 + TypeScript strict + Tailwind 4. 관리자 앱은 공개 사이트가 아니므로 SEO · i18n 은 제거.

1. 프로젝트 생성

pnpm create next-app admin-platform \
  --typescript --tailwind --app --turbopack \
  --src-dir --import-alias "@/*"
cd admin-platform

--src-dir : src/app/ 구조 (관례)
--import-alias "@/*" : @/src/... 대신 @/* 로 짧게

2. TypeScript strict 보강

tsconfig.json:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "forceConsistentCasingInFileNames": true,
    "exactOptionalPropertyTypes": true
  }
}

noUncheckedIndexedAccess 는 배열 · 객체 접근이 undefined 를 포함하게 만들어 실수를 줄입니다. 초반 비용이 있지만 관리자 앱처럼 조건 분기 많은 코드에 도움.

3. shadcn/ui 설치

pnpm dlx shadcn@latest init
pnpm dlx shadcn@latest add button input select table card dialog scroll-area

components.json 의 style 은 default, tailwindCSS 는 new-york. 관리자 앱은 밀도 있는 디자인이 유리하므로 default.

4. 기본 디렉토리 구조

src/
├── app/
│   ├── admin/                    # 모든 관리자 페이지
│   │   ├── layout.tsx           # AuthGuard
│   │   ├── dashboard/
│   │   └── blog/posts/
│   ├── api/                     # BFF 라우트
│   └── login/
├── shared/
│   ├── lib/
│   │   ├── db.ts                # 풀 싱글톤
│   │   ├── auth/
│   │   └── audit.ts
│   ├── components/
│   │   ├── AdminResourceTable.tsx
│   │   ├── AuthGuard.tsx
│   │   └── Sidebar.tsx
│   └── constants/
│       └── routes.ts            # PATHS SSOT

src/shared/ 에 공용 lib · 컴포넌트 · 상수
app/admin/ 아래가 관리 UI, app/api/ 아래가 BFF

5. 환경변수 규약

# .env.local
# 도메인 prefix 로 DB 분리
BLOG_DB_HOST=localhost
BLOG_DB_PORT=5435
BLOG_DB_NAME=blog
BLOG_DB_USER=postgres
BLOG_DB_PASSWORD=postgres

MARKET_DB_HOST=localhost
MARKET_DB_PORT=5433
# ...

# OAuth
KAKAO_CLIENT_ID=...
KAKAO_CLIENT_SECRET=...
NAVER_CLIENT_ID=...
NAVER_CLIENT_SECRET=...

# 세션
JWT_SECRET_KEY=change-me-32-bytes
SESSION_EXPIRES_IN=86400

# 관리자 화이트리스트
ADMIN_ALLOWED_EMAILS=admin@example.com,ops@example.com

.env.local 은 git ignore, .env.dev · .env.prod 는 의도적으로 커밋 (private repo 전제) — 팀 정책에 따라 조정.

6. 개발 서버 확인

pnpm dev

http://localhost:3000 에서 Next 기본 페이지. 다음 단계에서 /login · /admin/dashboard 를 실제 만듭니다.

하고픈 말

관리자 앱은 공개 사이트보다 디자인 자유도가 큽니다. shadcn/ui 그대로 가도 되고, Radix primitive 위에 직접 쌓아도 됩니다. 중요한 건 "모든 페이지가 같은 컴포넌트 서랍에서 나옴" — 3 ~ 5 번째 페이지부터 차이가 납니다.

03-multiple-pg-pools