Binyard

Appearance

lint-staged 정리 ​

🧩 Reference

  • lint-staged: Git staged 상태의 파일만 린트/포맷을 실행하는 도구
  • Git staged: git add로 커밋 대상으로 추가된 파일
  • Husky와 함께 사용하여 커밋 전 자동 검사 구현

왜 lint-staged가 필요할까? ​

프로젝트가 커질수록 전체 파일에 대해 ESLint나 Prettier를 실행하면 시간이 오래 걸린다.
커밋할 때마다 변경하지 않은 수백 개의 파일까지 검사하는 것은 비효율적이다.
lint-staged는 변경된 파일(staged files)만 검사하여 커밋 속도를 빠르게 유지한다.


🧩 프로젝트에 적용하면서 깨달은 점

  • 전체 프로젝트를 검사하는 것보다 훨씬 빠르다.
  • 커밋 전 자동으로 코드 품질을 검증하면 리뷰 시간이 줄어든다.
  • ESLint, Prettier를 자동으로 실행하여 코드 일관성을 유지할 수 있다.

lint-staged란? ​

lint-staged는 Git에 staged된 파일만 대상으로 특정 명령어를 실행하는 도구다.

bash
# 일반적인 ESLint 실행 (전체 파일)
npx eslint .

# lint-staged 실행 (staged 파일만)
npx lint-staged

쉽게 말해, git add로 커밋 대상에 추가된 파일만 검사한다.


설치 및 설정 ​

1. lint-staged 설치 ​

bash
npm install -D lint-staged

2. package.json에 설정 추가 ​

json
{
  "lint-staged": {
    "*.{ts,tsx,js}": ["eslint --fix", "prettier --write"],
    "*.{css,md}": ["prettier --write"]
  }
}

설정 상세 설명 ​

TypeScript/JavaScript 파일 ​

json
"*.{ts,tsx,js}": [
  "eslint --fix", // ESLint로 코드 품질 검사 및 자동 수정
  "prettier --write", // Prettier로 포맷 자동 정리
]

실행 순서:

  1. ESLint → 코드 품질 문제 수정
  2. Prettier → 포맷 정리

CSS/Markdown 파일 ​

json
"*.{css,md}": [
  "prettier --write"  // Prettier로 포맷만 정리
]

CSS와 Markdown 파일은 ESLint 검사가 필요 없으므로 Prettier만 실행한다.


Husky와 함께 사용하기 ​

lint-staged는 보통 Husky와 함께 사용하여 커밋 전 자동 실행을 구현한다.

.husky/pre-commit ​

bash
# .husky/pre-commit
npx lint-staged

전체 워크플로우 ​

1. 개발자가 코드 수정
   ↓
2. git add로 파일 추가 (staged)
   ↓
3. git commit 실행
   ↓
4. Husky의 pre-commit hook 실행
   ↓
5. lint-staged 실행
   ↓
6. staged 파일에 대해:
   - ESLint --fix
   - Prettier --write
   ↓
7. 모두 통과 → 커밋 완료
   실패 → 커밋 중단

lint-staged의 장점 ​

1. 속도 ​

전체 프로젝트를 검사하는 것보다 훨씬 빠르다.

bash
# 전체 프로젝트 검사 (느림)
npx eslint .          # 300개 파일 검사 → 30초
npx prettier . --write

# lint-staged (빠름)
npx lint-staged       # 변경된 3개 파일만 검사 → 2초

2. 자동화 ​

개발자가 수동으로 명령어를 실행하지 않아도 커밋 시점에 자동으로 검사가 실행된다.

3. 일관성 ​

모든 팀원의 커밋이 동일한 코드 품질 기준을 통과하게 된다.


참고: 전체 프로젝트 검사가 필요한 경우 ​

lint-staged는 변경된 파일만 검사하므로, 가끔은 전체 프로젝트 검사가 필요할 수 있다.

예를 들어:

  • 공통 타입 변경 시 영향받는 모든 파일 확인
  • ESLint 규칙 변경 후 전체 프로젝트 재검사

이런 경우 별도의 스크립트를 사용한다:

json
{
  "scripts": {
    "lint": "eslint .",
    "format": "prettier . --write",
    "type-check": "tsc --noEmit"
  }
}
bash
# 전체 프로젝트 검사
npm run lint
npm run format
npm run type-check


💡 정리

  • lint-staged는 Git staged 파일만 대상으로 명령어를 실행하는 도구다.
  • 전체 프로젝트를 검사하는 것보다 훨씬 빠르다.
  • 새로운 프로젝트에서는 ESLint, Prettier를 순서대로 실행하여 코드 품질을 보장한다.
  • Husky와 함께 사용하여 커밋 전 자동 검사를 구현했다.
  • 변경된 파일만 검사하므로 커밋 속도가 빠르다.
  • Type Check는 선택사항이며, 필요시 추가할 수 있다.