실무에서 마주친 문제와 해결 과정을 정리하는 개인 기술 블로그. 마크다운 글쓰기(에디터, 이미지 업로드, 시리즈/태그), 검색, 조회수·인기글 통계까지 갖춘 풀스택 블로그를 Next.js(BFF) + NestJS(API) 두 저장소로 나눠 만들었습니다.
| 홈 | 검색 |
|---|---|
![]() |
![]() |
| 글 상세 | 다크 모드 |
|---|---|
![]() |
![]() |
https://gyujin-log.vercel.app/
flowchart LR
subgraph Browser["브라우저"]
U["사용자"]
end
subgraph blogRepo["blog (이 저장소)"]
BFF["Next.js Route Handler = BFF<br/>Vercel 배포 (SSG + 온디맨드 ISR)"]
end
subgraph apiRepo["blog-api (별도 저장소)"]
API["NestJS + Prisma<br/>Render 배포"]
DB[("PostgreSQL + Redis<br/>Neon")]
end
U -->|"httpOnly 쿠키 자동 첨부<br/>같은 도메인 /api/* 만 호출"| BFF
BFF -->|"서버-to-서버 REST<br/>Authorization 헤더"| API
API -->|"글 CRUD 시<br/>on-demand revalidate 웹훅"| BFF
API --> DB
브라우저는 NestJS를 직접 호출하지 않고 항상 Next.js의 app/api/* Route Handler(BFF)만 호출합니다. 인증 토큰은 httpOnly 쿠키로만 오가며 브라우저 JS는 절대 값을 읽을 수 없습니다. 글 CRUD가 일어나면 백엔드가 프론트의 /api/revalidate를 호출해 해당 페이지만 즉시 재검증합니다(전체 재빌드 없음).
설계 배경과 각 결정의 이유(왜 BFF인지, 왜 NestJS인지, 왜 온디맨드 ISR인지 등)는 docs/blog-structure-plan.md에 자세히 정리되어 있습니다. 백엔드 설계는 blog-api 저장소의 docs/blog-api-plan.md 참고.
| 영역 | 선택 | 비고 |
|---|---|---|
| 프레임워크 | Next.js 16 (App Router) | Vercel 배포, SSG + 온디맨드 ISR |
| 언어 | TypeScript | strict |
| UI | shadcn(Base UI 기반) + Tailwind CSS 4 | 커스텀 컬러 팔레트("비주얼 아이덴티티" 섹션 참고) |
| 서버 상태 | TanStack Query v5 | 검색/세션/통계 등 CSR 데이터 전부 |
| 클라이언트 상태 | zustand | 로그인 모달 등 순수 UI 상태 |
| 마크다운 | react-markdown + remark-gfm + rehype-pretty-code(Shiki) | 코드 하이라이트 + 복사 버튼 |
| 폼/검증 | 네이티브 HTML(<select>, <input type="checkbox">) |
계획에 없는 라이브러리는 안 씀 |
| 테스트 | Vitest(Browser Mode) + vitest-browser-react, Playwright |
유닛 + E2E |
| 문서화 | Storybook | 컴포넌트 독립 확인/문서화 |
| 백엔드(별도 저장소) | NestJS + Prisma, PostgreSQL(Neon) + Redis(Upstash), Render 웹서비스 배포 | REST API |
yarn install
yarn dev # http://localhost:3000Node 버전은 .nvmrc(v24) 기준입니다. nvm use로 맞춰주세요. 실제 데이터를 보려면 blog-api를 localhost:4000에서 같이 띄워야 합니다.
yarn lint # ESLint
yarn tsc --noEmit -p tsconfig.json # 타입체크
yarn test # Vitest 유닛 테스트 (컴포넌트 + Storybook 스토리)
yarn test:e2e # Playwright E2E (가짜 API 스텁 + yarn dev를 3100 포트로 자동 기동)
yarn build # 프로덕션 빌드PR을 올리면 .github/workflows/ci.yml이 lint + 타입체크 + 유닛 테스트 + E2E 테스트를 자동으로 돌립니다. E2E는 실제 백엔드 대신 고정 픽스처를 주는 스텁 API(e2e/stub-api.mjs)에 붙습니다 — 그래야 CI가 배포 상태나 DB 내용에 휘둘리지 않습니다.
blog-api 연동, 소유자 로그인/글쓰기(작성·수정·삭제·숨김·고정, 이미지 업로드), 검색, 조회수·인기글 통계까지 v1 스코프는 기능 구현·검증이 끝났고 Vercel 배포도 완료되어 운영 중입니다.
댓글·좋아요·방문자(Google) 로그인은 백엔드(blog-api)에는 구현·검증되어 있지만, 로그인 없는 방문자 참여 지표는 조회수 하나로 충분하다고 판단해 v1 프론트 스코프에서 의도적으로 제외했습니다.
단계별 진행 상황은 docs/blog-structure-plan.md의 "다음 단계" 체크리스트에서 확인할 수 있습니다. 문서가 길어 맨 위에 목차를 두었습니다.



