Node.js에서 Husky 사용 설명

#nodejs#git

이 글은 AI가 작성했습니다.

Overview

이 문서는 Node.js 프로젝트에서 Husky를 사용해 Git 훅을 설정하고 관리하는 방법을 설명한다. 설치·초기화 과정, 주요 훅 예제, lint-staged 통합, CI(연속 통합) 관련 고려사항 및 일반적인 문제 해결 방법을 포함한다.

Husky 개요

Husky는 Git 훅을 쉽게 설치하고 관리할 수 있게 해주는 도구이다. 프로젝트 수준에서 훅 스크립트를 저장하는 방식으로 동작하며, 코드 품질 검사(예: lint, 테스트, 커밋 메시지 규칙 검증)를 커밋 또는 푸시 시점에 자동화하는 데 사용된다. Husky 자체는 Git 훅을 대체하는 것이 아니라 Git의 훅 실행 흐름에 스크립트를 연결한다.

설치 및 초기화

Husky v7 이상을 기준으로 설명한다.

  1. Husky 설치
  • npm: npm install --save-dev husky
  • pnpm: pnpm add -D husky
  • yarn: yarn add -D husky
  1. 훅 디렉터리 초기화
  • 한 번만 실행: npx husky install
  • package.json에 자동 설치를 추가하려면 prepare 스크립트 설정: package.json(부분) 4 spaces indent to form a code block { “scripts”: { “prepare”: “husky install” } }
  1. 훅 추가
  • 예: pre-commit 훅 추가
    • npx husky add .husky/pre-commit "npm test"

Husky는 .husky 디렉터리 내부에 훅 스크립트 파일을 생성한다. 생성된 파일은 쉐뱅(예: #!/usr/bin/env sh)으로 시작하며 실행 가능하도록 권한이 설정되어야 한다(chmod +x .husky/*) — npx husky add는 일반적으로 실행 권한을 설정한다.

예제: pre-commit (테스트 또는 린트 실행)

  • 설치 및 초기화:

    • npm install --save-dev husky
    • npx husky install
    • package.json에 prepare 스크립트 추가 권장

  • pre-commit 훅 생성:

    • npx husky add .husky/pre-commit "npm test"

위 설정으로 git commit 시 npm test가 실행된다. 테스트가 실패하면 커밋은 중단된다.

예제: commit-msg (커밋 메시지 규칙 검증)

Conventional Commits 나 커스텀 규칙을 적용하려면 commitlint 같은 도구와 결합한다.

  • commitlint 설치:

    • npm install --save-dev @commitlint/config-conventional @commitlint/cli

  • commitlint 설정 파일 생성(예: commitlint.config.js): 4 spaces indent to form a code block module.exports = { extends: [‘@commitlint/config-conventional’] };

  • commit-msg 훅 추가:

    • npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

훅은 커밋 메시지를 검사하고 규칙에 맞지 않으면 커밋을 거부한다.

lint-staged 통합

파일 단위로 린트/포맷 작업을 병렬 처리하려면 lint-staged를 사용하고 pre-commit 훅에서 호출하면 효율적이다.

  • 설치:

    • npm install --save-dev lint-staged

  • package.json 설정 예: 4 spaces indent to form a code block { “lint-staged”: { “.js”: [ “eslint —fix”, “git add” ], “.ts”: [ “eslint —fix”, “git add” ] } }

  • pre-commit 훅에서 lint-staged 호출:

    • npx husky add .husky/pre-commit "npx lint-staged"

이 구성은 변경된 파일에 대해서만 ESLint 자동수정을 적용하고, 수정된 파일을 다시 스테이징한 뒤 커밋을 진행한다.

CI에서의 고려사항

  • 기본적으로 Git 훅은 로컬 개발 환경에서 작동한다. CI 파이프라인에서는 보통 훅이 자동으로 실행되지 않으므로, CI에서 동일한 검사를 실행하려면 별도의 CI 스텝으로 추가해야 한다(예: npm test, npm run lint).
  • package.json에 prepare 스크립트를 추가하면 패키지 설치 시 Husky가 설치될 수 있다. 그러나 많은 CI 환경은 훅 실행을 필요로 하지 않으므로 CI에서 훅을 신뢰하는 것은 권장되지 않는다.
  • Git이 없는 컨테이너 환경 또는 shallow clone 환경에서는 훅 동작이 제한될 수 있다. CI에서 훅을 강제하려면 명시적으로 npx husky install을 실행하거나 관련 스크립트를 CI 구성에 포함시킨다.

문제 해결(트러블슈팅)

  • 훅이 실행되지 않을 때

    • .husky 디렉터리가 존재하는지 확인.
    • Git의 core.hooksPath 설정이 변경돼 있지 않은지 확인: git config core.hooksPath 체크.
    • 훅 파일이 실행 권한을 갖추었는지 확인: chmod +x .husky/*.
    • package manager의 prepare 스크립트가 설정되어 있는지 확인하고, 설치 후 npx husky install을 수동 실행해 본다.

  • Windows에서 줄 바꿈 문제

    • CRLF 변환으로 인해 쉘 스크립트가 제대로 실행되지 않을 수 있다. .gitattributes로 .husky/* text eol=lf를 지정하거나 파일 엔딩을 LF로 유지한다.

  • commit-msg 훅에서 파라미터 처리 문제

    • commit-msg 훅은 커밋 메시지 파일 경로를 첫 번째 인수로 받는다. 훅 스크립트에서 "$1" 형식으로 전달하는지 확인한다.

  • Husky가 패키지 제거 후에도 훅이 남아 있을 때

    • .husky 폴더와 prepare 스크립트를 제거하고 git config --unset core.hooksPath를 확인한다.

권장 관행

  • CI 파이프라인에 동일한 검사(테스트, 린트, 타입체크)를 명시적으로 포함시킨다. 훅은 개발자 워크플로우를 돕지만 CI 검사를 대신하지 않는다.
  • 훅 스크립트는 가능하면 빠르게 동작하도록 구성한다(파일 단위 검사, lint-staged 사용).
  • 팀 표준(커밋 메시지 규칙, lint 규칙)을 문서화하고, 공통 설정 파일을 저장소 루트에 유지한다.
  • 훅에 민감한 작업(예: 대규모 포맷팅)은 별도 스크립트로 분리하고 필요 시 수동 실행하도록 한다.