Kimpuro's Boilerplate

2025. 02 ~

이 개인 프로젝트를 시작하게 된 이유는 이전에 진행했던 팀 프로젝트들에서 느꼈던 불편함들을 해결하기 위해서였습니다.

저는 여러 번의 프론트엔드 학습용 팀 프로젝트를 진행했는데, 대부분의 팀 프로젝트에서 문제가 되는 코드를 작성한 팀원은 그 사실조차 모르고 있는 경우가 많았습니다. 이로 인해 Git에서 문제가 된 코드를 작성한 사람이 누구인지 로그를 찾아서 수정 요청을 해야 했고, 이 일명 '범인 찾기' 과정을 자주 겪었습니다. 이러한 상황을 미연에 방지하기 위해서는 단순한 오류 메시지가 아닌, 보다 강력한 방식으로 문제를 사전에 차단해야겠다고 생각하게 되었습니다.

이전 팀 프로젝트에서 빌드나 배포 시에 발생한 문제들, 그리고 커밋 로그에서 생긴 문제들이 프로젝트 사전 설정만으로 해결된 경험이 있었습니다.
팀 프로젝트에서 발생할 수 있는 여러 문제들을 미리 프로젝트 세팅을 통해 해결할 수 있는 보일러플레이트들을 만들어두고, 이를 개발 환경에 맞춰 자유롭게 선택할 수 있는 CLI Tool이 있으면 좋겠다고 생각하게 되었습니다. 이 아이디어에서 출발하여 프로젝트를 시작하게 되었습니다.

프로젝트 소개

NPM

이 프로젝트는 개발 환경에 맞는 보일러플레이트를 선택할 수 있는 CLI Tool을 개발하는 것을 목표로 합니다.

이 도구는 팀 프로젝트를 원활하게 진행할 수 있도록 필요한 구조와 기능을 제공합니다. 또한, 다양한 규칙들이 사전에 정의되어 있어 팀원들이 일관된 개발 환경과 규칙을 따를 수 있도록 도와줍니다.

해결하려는 문제

팀 프로젝트의 팀원들 간의 코드 스타일이 다른 문제
팀원들 간의 폴더 네이밍과 구조 불일치 문제
Lint나 타입 에러가 해결되지 않은 상태로 코드가 푸시되는 문제
테스트 코드 통과 여부가 확인되지 않은 코드가 푸시되는 문제
여러 규칙이 생겨 커밋 생성 방법이 어려워지는 문제

목적

상황에 맞는 프로젝트 템플릿을 쉽게 선택하여 사용할 수 있도록 NPM 패키지로 제작

팀 구성

개인 프로젝트

기술 스택

Vite, Next.js, Node.js, Git, NPM

README

KimPuro's Next.js team project Boilerplate

이 템플릿 레포지토리는 Next.js를 사용한 팀 프로젝트를 위한 보일러플레이트입니다.
Next.js, React 및 Tailwind CSS를 사용하여 프로젝트를 시작할 수 있습니다.
팀 프로젝트를 원활하게 진행하기 위한 구조와 기능을 제공합니다. 또한 각종 규칙이 사전 정의되어 있습니다.

🚀 Getting Started

아래는 이 템플릿을 사용하는 3가지 방법입니다.

1. npx로 설치

npx @kimpuro/next-14-ts-team

2. GitHub template을 사용

3. git clone을 통해 직접 다운로드

git clone https://github.com/kimpuro/next-14-js-boilerplate.git
cd <project-directory>

패키지 매니저는 pnpm을 사용하는 것을 권장드립니다. 아래의 명령어를 통해 의존성을 설치할 수 있습니다:

pnpm i

아래의 명령어를 통해 개발 서버를 시작할 수 있습니다:

pnpm run dev

📁 Project Structure

이 템플릿은 통상적으로 사용되는 Next.js 프로젝트 구조를 따릅니다.

public/
- fonts/ - 커스텀 폰트 파일
- icons/ - 아이콘 파일
- images/ - 이미지 파일
src/
- app/
  - api/ - APi route 관련 코드
- components/ - 리액트 컴포넌트
- hooks/ - 리액트 커스텀 훅
- libs/ - 라이브러리 관련 코드
- services/ - 외부 API 호출을 위한 서비스 함수
- states/ - 글로벌 상태 관리
- styles/ - 스타일 관련 코드
- utils/ - 유틸리티 함수
- types/ - 타입 스크립트 타입
__tests__/ - 테스트 코드

📚 Commit

이 템플릿에서는 husky, commitlint, comitizen를 사용하여 커밋 메시지 규칙을 적용하고 있으며 Conventional Commits와 AngularJs Git Commit Message Conventions를 따릅니다.
사전 설정된 규칙에 맞지 않는 커밋 메시지를 작성한다면 커밋이 거부됩니다.

How to commit

pnpm commit을 사용하여 미리 정의되어 있는 컨벤션에 맞게 커밋을 생성할 수 있습니다:

git add .
pnpm commit

컨벤션을 지킨다면 pnpm commit 명령어가 아닌 git 만을 사용해서 커밋 진행도 가능합니다:

git add .
git commit -m "feat: add new feature"

pre-commit

husky를 사용해 pre-commit 단계에서 아래와 같은 작업을 수행합니다.

prettier를 사용해 스테이징된 파일만을 대상으로 코드 포맷팅을 진행합니다.
prettier로 수정된 파일의 변경 사항을 다시 스테이징합니다.
타입스크립트 컴파일러에서 타입 오류를 검사합니다.
프로젝트의 Linter를 실행하여 코드의 품질과 스타일 규칙을 확인합니다.
jest를 사용해 테스트 코드를 실행합니다.
commitlint를 사용해 커밋 메시지의 형식을 확인합니다.

위의 과정들을 전부 통과한다면 커밋이 생성됩니다.

Commit Message Type

✨ feat: 새로운 기능의 추가, 기존 기능을 수정
🐛 fix: 버그 수정
📝 docs: 문서 관련 수정
🎨 style: 코드의 의미에 영향을 미치지 않는 변경 사항(공백, 서식, 세미콜론 누락 등)
♻️ refactor: 기능의 변화가 없는 코드 리팩터링
⚡ perf: 성능 향상을 위한 코드 변경
✅ test: 테스트 코드 추가, 기존 테스트 코드 변경
🔧 build: 빌드 시스템이나 외부 종속성에 영향을 미치는 변경 사항(예시 : gulp, broccoli, npm)
👷 ci: CI 구성 파일 및 스크립트 추가, 변경
🔨 chore: 소스 또는 테스트 파일을 수정하지 않는 기타 변경 사항
⏪ revert: 이전 커밋을 되돌림

pnpm commit과 git commit 명령어는 commit 생성까지만 진행되기 때문에 추가적으로 git push를 진행해 주셔야 합니다.

CHANGELOG

위에 정의된 커밋 컨벤션을 지킨다면 CHANGELOG.md 파일을 자동으로 생성할 수 있습니다.
CHANGELOG.md 파일은 git -cliff를 사용하여 생성할 수 있습니다.
git-cliff가 설치되어 있지 않다면 Rust 기반 패키지 매니저인 cargo를 사용하여 설치해 주세요

아래의 명령어를 통해 CHANGELOG.md 파일을 생성할 수 있습니다:

git cliff -o CHANGELOG.md

💡 ESLint & Prettier

이 템플릿에는 사전 정의된 ESLint와 Prettier 설정이 포함되어 있습니다.
.eslintrc.json과 .prettierrc 파일을 통해 설정을 확인할 수 있습니다.

eslintrc.json:

{
  "extends": ["next", "prettier"],
  "rules": {
    "react/react-in-jsx-scope": "off"
  },
  "settings": {
    "import/resolver": {
      "alias": {
        "map": [["@", "./"]],
        "extensions": [".js", ".jsx", ".ts", ".tsx"]
      }
    }
  }
}

.prettierrc:

{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "all",
  "useTabs": false,
  "tabWidth": 2,
  "printWidth": 80,
  "arrowParens": "always",
  "plugins": ["prettier-plugin-tailwindcss"]
}

Pull Request Template

이 템플릿에는 사전 생성된 Pull Request 템플릿이 포함되어 있습니다.
Pull Request를 생성하신다면 아래와 같은 템플릿으로 자동 생성됩니다. 체크 버튼을 클릭하시면서 작성하시면 됩니다.

📝 etc

수정하고 싶은 부분이나 추가하고 싶은 기능이 있다면 언제든지 PR을 보내주세요.

예상되는 질문

규칙을 잘 정해두면 해결되는 문제가 아닌가?

몇 번의 팀 프로젝트를 진행하면서 팀 프로젝트의 규칙에 대해 문서화도 해보고, 팀원들과 여러 번 대화도 해보았지만, 규칙이 잘 지켜지지 않는 경우가 많았습니다. 이 도구는 팀 프로젝트의 규칙을 준수할 수 있도록 돕는 일종의 보조 장치입니다. 규칙을 단순히 문서화하는 것에 그치지 않고, 실제로 자동화된 방식으로 적용할 수 있도록 만들어졌습니다.

왜 CI 도구에서 진행하지 않는가?

사실 이러한 문제들은 Circle CI와 같은 CI 도구를 통해 해결할 수 있습니다. 하지만 몇 가지 이유로 CI 도구 대신 로컬 환경에서 해결하고자 했습니다.

이 보일러플레이트는 기업의 프로덕트가 아닌 소규모 팀 프로젝트를 위해 만들어졌습니다.
- 소규모 팀 프로젝트는 주기가 짧고 빠르게 진행되며, CI 파이프라인을 세팅하는 데 시간이 많이 걸릴 수 있습니다. 또한 소규모 프로젝트에서는 CI 도구 설정에 필요한 비용과 시간을 절약하는 것이 중요합니다.
- 취미 프로젝트나 작은 팀 프로젝트에서는 비용을 아끼는 것이 중요한 요소일 수 있습니다. 팀원들이 자금 여유가 없을 수 있기 때문에, 비용을 줄이기 위해 CI 도구 대신 로컬 환경에서 모든 팀원이 동일한 테스트를 진행할 수 있도록 구성했습니다.

커밋을 막아버리는 방식이라면 문제가 생기지 않는가?

빠르게 커밋을 하고 작업을 이어가야 할 때는 타입스크립트나 린트 관련 ignore 명령어나, git commit의 --no-verify 명령어를 통해 커밋을 진행할 수 있습니다.
대부분의 팀 프로젝트에서는 코드 작성자가 자신이 작성한 코드에 문제가 있다는 사실을 알지 못하는 경우가 많습니다. 이로 인해 범인 찾기처럼 문제가 발생한 코드를 추적하고 수정하는 데 시간과 노력이 듭니다. 이 도구는 이러한 상황을 방지하고, 오류를 사전에 차단하는 방식으로 팀의 효율성을 높이는 데 도움을 주는 것입니다.

회고

이 패키지를 제작하고 NPM에 배포한 후 실제 팀 프로젝트에서 사용해본 경험과 팀원들의 피드백을 통해 많은 것을 배웠습니다.
팀원들 역시 그동안 불편했던 부분들이 이 보일러플레이트를 통해 한 번에 해결되는 점에 대해 매우 긍정적으로 반응했습니다. 또한 이를 배우고 싶다고 하셔서 이후 2회의 스터디를 진행했습니다.

팀원들의 반응을 보며 깨달은 점은, 다른 팀원이 모범적인 코드를 작성하거나 제가 Three.js로 멋진 3D 컴포넌트를 만들었을 때보다, 개발 환경이 개선되었을 때의 반응이 훨씬 더 긍정적이었다는 점입니다.

좋은 코드를 작성하는 것도 중요하지만, 개발을 하면서 가장 와닿는 부분은 결국 개발 환경과 그에 따른 효율성임을 다시 한 번 실감했습니다. 앞으로도 개발자 경험을 향상시킬 수 있는 다양한 방법에 대해 계속 고민하고, 실천해 나가야겠다는 다짐을 하게 되었습니다.

배운 점

라이브러리의 제작 과정
NPM에 라이브러리를 배포하는 방법
git hooks의 활용

개선할 점

현재는 Next.js 프로젝트에만 적용되는 보일러플레이트지만, 이를 단순한 보일러플레이트가 아닌 진정한 CLI Tool로 발전시키는 것이 제 목표입니다.
다양한 개발 환경에 맞춰서, 예를 들어 Vite를 사용하는 환경이나 React 버전이 다른 환경 등도 선택할 수 있도록 버전 옵션을 추가하는 방향으로 개발을 확장하고자 합니다. 결론적으로 이 프로젝트는 제가 개발자로서 활동하는 동안 계속해서 발전시켜 나갈 예정입니다.