Skip to content
QyujinLeePublic

About

gyujin's dev blog

Resources

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

gyujin's log

실무에서 마주친 문제와 해결 과정을 정리하는 개인 기술 블로그. 마크다운 글쓰기(에디터, 이미지 업로드, 시리즈/태그), 검색, 조회수·인기글 통계까지 갖춘 풀스택 블로그를 Next.js(BFF) + NestJS(API) 두 저장소로 나눠 만들었습니다.

Next.js React TypeScript TanStack Query Tailwind CSS Vitest Playwright Storybook

스크린샷

홈 검색
홈 화면 검색 화면
글 상세 다크 모드
글 상세 화면 다크 모드 홈 화면

데모

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
Loading

브라우저는 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:3000

Node 버전은 .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의 "다음 단계" 체크리스트에서 확인할 수 있습니다. 문서가 길어 맨 위에 목차를 두었습니다.

About

gyujin's dev blog

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages