mason-log.

📕 1. 개요 : 반성.

마인드셋.

• 항상 개발 블로그를 써야겠다고 마음먹고 만들고 시작은 해봤지만, 정작 오래 유지해본 적이 없었다.

• 일에 바쁘다는 핑계도 있었고, 회사 업무가 바빠서, 혹은 사이드 프로젝트를 하다 보면 기록 정리는 우선순위에서 항상 뒤로 밀려 있었다.

• 그럼에도 이제는 차근차근 다시 써야겠다는 생각이 들었고, 천천히 쌓아가는 습관을 만들어 보려고 한다.

• 글도 여러 플랫폼에 흩어진 채 쓰다가 말기를 반복했다. 흩어졌던 GitHub 계정을 하나로 모았던 것처럼 기록에도 선택과 집중이 필요하다고 생각했다.

• 그래서 이번에는 "의무적으로 쓰는 블로그" 가 아니라 "쓰고 싶은 블로그" 를 만들고 꾸준히 유지해보고 싶어졌다.

👨🏻‍⚕️ 2. 목표 : 리뉴얼 구상.

이전 버전 정리.

• ver1 (Jekyll) : 테마 커스텀은 자유로웠지만 Ruby 생태계 이해 부족으로 유지보수에 한계를 느낌. (Jekyll은 Ruby로 만든 정적 웹사이트 생성기인데, 디자인이나 로직 또한 오픈소스를 활용하면서 만족하지 못하는 부분들이 있었고, Ruby에 대한 지식이 부족한 상태에서 구현한 블로그였다.)

• ver2 (React) : React/Next.js + TS 환경으로 급하게 만든 심플한 구조. 포스팅 수를 채우기 위한 영양가없는 포스팅이 늘어나며 방향성을 잃었고, 결국 전체 폐기.

ver3 에서 가져가고 싶은 방향.

• 이해하기 쉽고, 부담없이 재미있게 쓰고 싶다.

• 깔끔한 UI/UX와 포스팅 작성이 용이하고, 기능은 로그인/댓글/방문자 수 기능 구현정도를 목표로 한다.

목표 : 익숙한 스택 위에서 가독성, 운영 편의, 확장성을 모두 갖춘 블로그로 재구축한다.

🤔 3. 선택 : 기술 스택 및 개선 방향.

기술 스택 선택.

• Next.js 15 (Pages Router 유지): 블로그 특성상 App Router의 서버 컴포넌트 이점이 크지 않아 기존 Pages 구조를 유지했다.

• 상태 관리는 Recoil + recoil-persist(테마/뷰 모드), 데이터는 Firebase Firestore(방문자 수, 댓글, 방명록)로 관리한다. (기존 ver2에서 recoil을 사용하고 있어서, zustand로 수정했을때 스토어 설계, persist 마이그레이션 등 작업 공수를 줄이고자 유지함.)

• 스타일링은 emotion, 마크다운 렌더링은 remark/rehype + highlight.js를 사용했다.

포스팅 마크다운과 미디어 처리 개선.

• 기존에는 "렌더링만 되는 마크다운"이었다면(작성할때마다 힘들었다), ver3에서는 쓰고, 읽는 경험이 좋은 마크다운으로 바뀌었다.

• 이미지/비디오는 사용하기 용이하도록 개별 max-width를 제어하였고, 미디어가 포함된 단락은 자동으로 p.media 클래스를 부여했다. 모바일 해상도에서 원하는 UI를 제공하기 위해 처리했다.

• 코드 블록은 언어별 하이라이트 적용, 링크는 자동으로 새 탭 + noopener 처리했다.

• PC 화면에서는 h2를 기준으로 TOC를 만들고, 스크롤 위치에 따라 현재 섹션을 활성화했다. 긴 포스팅에서도 위치를 놓치지 않게 하기 위한 선택이었다.

🔐 4. 인증 : GitHub OAuth.

• 현재는 방문자가 활동 할 수 있는 기능이 게시물 댓글 정도밖엔 없지만, 추후 로그인 후 활동 범위를 조금씩 늘려볼 생각이다.

• 로그인은 Github 계정으로 할 수 있으며, 인증/인가 처리는 다음과 같이 구현했다.

GitHub OAuth 인증 흐름.

• Next.js API Routes로 프론트와 백엔드를 분리하지 않고 인증과 세션 검증을 처리했다.

• 별도의 서버 없이 로그인, 토큰 발급, 검증 로직을 하나의 코드베이스 에서 관리할 수 있었고, 블로그 규모에서는 충분히 합리적인 선택이라고 생각한다.

• 인증 과정은 /api/oauth/github/callback에서 모두 처리한다.

• GitHub로부터 전달받은 code를 access token으로 교환한 뒤, 이를 기반으로 자체 JWT를 발급하고 signAuthToken으로 서명한다.

• 서명된 토큰은 Set-Cookie 헤더를 통해 HttpOnly 쿠키로 저장한다.

• 이 구조로 프론트에서는 토큰을 직접 다루지 않아도 되고, 스크립트로 읽을 수 없는 HttpOnly 쿠키에 세션을 두어 XSS로 토큰이 바로 노출되는 위험을 줄일 수 있다.

• 흐름도 (* 시퀀스 다이어그램 - mermaid)

데이터 관리.

• Firestore를 사용해 댓글과 대댓글을 슬러그별 문서로 저장하고 수정, 삭제 기능을 구현했다.

• 방문자 수는 service/info.visitors에 누적(로컬스토리지를 기준으로 하루 1회만 증가하도록 처리), UI에는 get으로 최신값 표시.

• 현재 추가 기능 개발 중인 방명록도 동일한 코멘트 스키마를 재사용해 관리하며 활용 예정이다.

👨🏻‍💻 5. 관리 : 포스팅 빌드 & 배포.

포스트 미디어 동기화 처리.

• 포스트 콘텐츠는 content/posts/{slug} 구조로 관리하며, 마크다운(index.md)과 이미지, 비디오 같은 미디어 파일을 함께 둔다.

• 빌드 전(predev / prebuild) 단계에서 scripts/copy-post-images.js 스크립트를 실행해, 각 포스트 폴더 안의 index.md를 제외한 모든 미디어 파일(jpg, png, webp, svg, mp4 등)을 public/posts/{slug}로 복사한다.

• 이 과정을 통해 런타임에서는 모든 미디어를 정적 파일로 안정적으로 서빙 한다.

산출물 관리.

• 빌드 과정에서 생성되는 public/posts 디렉터리는 gitignore로 처리해서 레포에는 원본 콘텐츠만 남기고, 정적 산출물은 항상 빌드 시점에 생성하도록 레포를 깔끔하게 유지한다.

🥸 6. 마무리 : 습관 만들기.

• mason-log ver3는 기능을 늘리기 위한 리뉴얼 보단, 계속 글을 쓰기 위한 습관을 만드는 작업이었다.

• 이제 기술적인 기반은 어느 정도 정리됐고, 앞으로는 완성도를 높이기보다 꾸준히 기록하는 것에 더 집중하려고 한다.

• 거창한 목표보다는, 생각이 정리될 때마다 가볍게 남길 수 있는 공간으로 이 블로그를 유지 하는 게 지금의 목적이다.