[블로그만들기] 03. Next.js 14 블로그 세팅과 커밋 컨벤션 정리
블로그 프로젝트의 첫 걸음
Next.js 14의 App Router와 Contentlayer를 기반으로
프로젝트를 세팅하였습니다.
이 글에서는 프로젝트 구조를 어떻게 설계하고, 어떤 설정을 적용했는지 정리하였습니다.
🧱 사용한 스택 요약
- Next.js 14 (App Router 기반)
- TypeScript
- TailwindCSS (with Typography plugin)
- Contentlayer (MDX 기반 콘텐츠 관리)
- Zustand (전역 상태관리)
- next-themes (다크모드 지원)
- Prettier + Tailwind 플러그인
- Vercel (배포 예정)
프로젝트 초기화
Next.js 14 + App Router 템플릿으로 생성
npx create-next-app@latest blog \
--typescript \
--tailwind \
--eslint \
--app \
--src-dir \
--import-alias "@/*"
cd blog
패키지 설치 (yarn 기준)
# 콘텐츠 관리
yarn add contentlayer next-contentlayer @contentlayer/source-files
yarn add date-fns reading-time
# 상태 관리
yarn add zustand
# 유틸리티
yarn add next-seo next-sitemap next-themes react-icons gray-matter
# 개발 도구
yarn add -D @tailwindcss/typography prettier prettier-plugin-tailwindcss
📦 패키지 설명
📝 콘텐츠 관리 (Markdown 처리)
yarn add contentlayer next-contentlayer @contentlayer/source-files
- contentlayer: 마크다운 파일을 타입과 함께 JSON 형태로 변환
- next-contentlayer: Next.js와 Contentlayer 연동
- @contentlayer/source-files: 로컬 마크다운 파일을 콘텐츠 소스로 사용
📅 날짜 및 텍스트 유틸리티
yarn add date-fns reading-time
- date-fns: 날짜 포맷팅 (
2024년 12월 25일형식) - reading-time: 글 읽는 시간 계산 (
5분 읽기등)
🔄 상태관리
yarn add zustand
- zustand: 간단한 전역 상태관리 (다크모드, 검색 필터 등)
🔍 SEO 및 사이트 최적화
yarn add next-seo next-sitemap
- next-seo: 페이지별 메타태그, OG 태그 관리
- next-sitemap: sitemap.xml, robots.txt 자동 생성
🎨 UI 및 테마
yarn add next-themes react-icons
- next-themes: 다크/라이트 모드 토글 기능
- react-icons: GitHub, Twitter 등 다양한 아이콘
📖 마크다운 메타데이터
yarn add gray-matter
- gray-matter: Markdown 파일의 frontmatter 파싱 (title, date 등)
🛠️ 개발 도구
yarn add -D @tailwindcss/typography prettier prettier-plugin-tailwindcss
- @tailwindcss/typography: Markdown 콘텐츠 스타일링 (
prose클래스) - prettier: 코드 포맷터
- prettier-plugin-tailwindcss: Tailwind 클래스 정렬 지원
🗂 폴더 구조 설계 (MVP 기준)
blog/
├── content/ # MDX 포스트
│ └── posts/
│ ├── first-post.mdx
│ └── second-post.mdx
├── src/
│ ├── app/ # App Router 기반 페이지
│ │ ├── globals.css
│ │ ├── page.tsx
│ │ ├── layout.tsx
│ │ ├── blog/
│ │ │ ├── page.tsx
│ │ │ └── [slug]/
│ │ │ └── page.tsx
│ │ └── api/
│ ├── components/
│ │ ├── ui/
│ │ ├── Header.tsx
│ │ ├── Footer.tsx
│ │ ├── ThemeProvider.tsx
│ │ └── BlogCard.tsx
│ ├── lib/
│ │ ├── utils.ts
│ │ └── store.ts
│ └── styles/
├── public/
├── contentlayer.config.ts
├── tailwind.config.ts
├── next.config.mjs
└── package.json
📚 커밋 컨벤션 (Commit Message Convention)
✅ 기본 형식
<타입>: <변경 요약>
본문 (선택)
BREAKING CHANGE: (선택)
✅ 타입 가이드
| 타입 | 설명 |
|---|---|
feat |
새로운 기능 추가 |
fix |
버그 수정 |
docs |
문서 수정 (README, 주석 등) |
style |
코드 스타일 변경 (포맷팅 등, 기능 변경 없음) |
refactor |
코드 리팩토링 (동작 변경 없음) |
perf |
성능 개선 |
test |
테스트 코드 추가 |
chore |
빌드/배포 설정, 패키지 설치 등 기타 작업 |
ci |
CI 관련 설정 변경 |
content |
✍️ MDX 포스트 추가 또는 수정 등 콘텐츠 관련 작업 전용 |
🐶 Husky란?
Git 훅(Git Hooks)을 쉽게 설정할 수 있게 해주는 도구입니다.
Git 훅이란?
Git이커밋,푸시,병합등의 이벤트가 발생할 때 자동으로 실행되는 스크립트입니다.
❗ 문제 발생
husky - add command is DEPRECATED
error Command failed with exit code 1.
최신 Husky(v9 이상)에서는
husky add명령어가 더 이상 사용되지 않으며, 이전 방식의install,add사용도 비권장(deprecated)입니다.
🔍 원인
husky add는 Husky v9에서 제거되었습니다.- 기존에는 명령어 한 줄로 훅을 생성할 수 있었지만, 이제는 직접 훅 파일을 생성하고 실행 권한을 부여하는 방식으로 변경되었습니다.
- 또한
.husky/_/husky.sh를 포함하던 초기 스크립트도 더 이상 사용하지 않습니다.
✅ 해결 방법 (최신 Husky 방식)
1. 설치 및 준비
yarn add -D husky
npx husky init
.husky/폴더와 기본pre-commit훅이 생성됩니다.package.json에 자동으로 다음 스크립트가 추가됩니다:
"scripts": {
"prepare": "husky install"
}
💡 이 스크립트 덕분에 yarn install 시 자동으로 훅이 다시 연결됩니다.
2. Git 훅 수동 생성
커밋 메시지 포맷 검사를 위한 훅을 수동으로 생성하려면 다음과 같이 설정합니다:
mkdir -p .husky
touch .husky/commit-msg
chmod +x .husky/commit-msg
.husky/commit-msg 파일 내용:
#!/bin/sh
npx --no -- commitlint --edit "$1"
✅ 더 이상 ._/husky.sh를 불러오는 방식은 사용하지 않습니다.
✨ 요약
| 항목 | 권장 방식 (v9 기준) |
|---|---|
| 초기 설치 | npx husky init |
| 훅 파일 추가 | 직접 touch .husky/<hook> 후 chmod +x |
| 실행 내용 추가 | 훅 파일 내부에 bash 명령 명시 |
🎯 왜 Husky를 사용하는가?
- 커밋 메시지 컨벤션 자동 검사
- 포맷팅 되지 않은 코드 커밋 방지
- 푸시 전 테스트 자동 실행
- 팀원 간 일관된 개발 환경 유지
✍️ 마무리
이번 글에서는 프로젝트의 초기 세팅 과정과 사용한 도구들에 대해 정리하였습니다.
저처럼 직접 블로그를 만들고 싶은 분들에게 도움이 되었기를 바랍니다.
댓글남기기