ESLint 세팅하기 (+ lint-staged)

목차

1. ESLint란?

2. ⚙️ ESLint 설치 및 기본 설정

3. 🔗 Prettier 설치 및 ESLint와 연동

4. 📂 설정 파일 작성 (eslint.config.js)

5. 🤖 Husky + lint-staged로 커밋 전 자동 검사 설정

---

1. ESLint란?

ESLint는 JS/TS 코드에서 문법 오류, 스타일 위반, 버그 가능성 등을 사전에 감지하는

정적 분석 도구(linter)이다.

 

ESLint를 프로젝트에 적용하는 과정을 알아보자.

1. ⚙️ ESLint 설치 및 기본 설정 (+플러그인 추가)
2. 🔗 Prettier 설치 및 ESLint와 연동
3. 📂 설정 파일 작성 (eslint.config.js)
4. 🤖 Husky + lint-staged로 커밋 전 자동 검사 설정

 

---

2. ⚙️ ESLint 설치 및 기본 설정

명령어로 eslint를 설치하자

npm install -D eslint
npx eslint --init

 

 

이 때 필요한 플러그인들을 같이 추가해도 된다.

npm install -D \
    eslint \
    @typescript-eslint/parser \
    @typescript-eslint/eslint-plugin \
    eslint-plugin-react \
    eslint-plugin-react-hooks \
    eslint-plugin-jsx-a11y \
    eslint-plugin-prettier \
    eslint-config-prettier \
    eslint-plugin-storybook

• @typescript-eslint/parser : ESLint가 TypeScript 문법을 이해할 수 있게 해주는 파서
• @typescript-eslint/eslint-plugin : TypeScript 전용 린트 규칙을 제공하는 플러그인
• eslint-plugin-react : React 문법 및 컴포넌트 관련 린트 규칙 제공
• eslint-plugin-react-hooks : React Hooks 사용 규칙을 검사 (rules-of-hooks, exhaustive-deps 등)
• eslint-plugin-jsx-a11y : JSX 코드에서 접근성(a11y) 관련 문제를 감지
• eslint-plugin-prettier : Prettier 포맷팅 오류를 ESLint로 표시
• eslint-config-prettier : Prettier와 충돌하는 ESLint 규칙을 비활성화
• eslint-plugin-storybook : Storybook 코드에 맞는 린트 규칙 제공 (구성 요소, 메타 정의 등)

 

 

원래라면 Prettier도 같이 설치/설정 해야한다. 근데 따로 정리해서 내용이 나눠짐

>> Prettier 관련 글

 

---

3. 🔗 Prettier와 ESLint 연동

코드 스타일 자동 포맷터인 prettier와 ESLint는 충돌할 가능성도 있다.

둘이 충돌하지 않도록 하기 위해 eslint-config-prettier를 함께 사용한다.

 

충돌 방지를 위해 아래에 작성할 .eslintrc파일에 아래 설정을 추가한다.

"extends": ["plugin: "pretier/recomended"]

이 설정으로 ESLint는 Prettier와 충돌하는 코드 스타일 규칙을 끈다.

 

---

4. 📂 설정 파일 작성 (.eslintrc, .eslintignore)

eslint 규칙을 작성하는 .eslint.config.js를 작성하자.

 

처음에는 .eslintrc로 작성을 했었으나, 유지보수의 용이와 성능 향상 목적으로 ESLint v9 부터는 Flat Config 방식이 도입되어
eslint.config.js가 기본 설정 방식으로 바뀌었다고 한다. >>

 

eslint의 검사에서 무시할 파일들을 작성하는 .eslintignore을 작성하자.

 

.eslint.config.js (ESLint Flat Config 형식)

import { FlatCompat } from "@eslint/eslintrc";
import tsPlugin from "@typescript-eslint/eslint-plugin";
import reactPlugin from "eslint-plugin-react";
import reactHooksPlugin from "eslint-plugin-react-hooks";
import prettierPlugin from "eslint-plugin-prettier";
import jsxA11yPlugin from "eslint-plugin-jsx-a11y";
import storybookPlugin from "eslint-plugin-storybook";

import { dirname } from "path";
import { fileURLToPath } from "url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const compat = new FlatCompat({
  baseDirectory: __dirname,
});

const config = [
  ...compat.extends("next/core-web-vitals", "next/typescript"),
  {
    plugins: {
      "@typescript-eslint": tsPlugin,
      react: reactPlugin,
      "react-hooks": reactHooksPlugin,
      prettier: prettierPlugin,
      "jsx-a11y": jsxA11yPlugin,
      storybook: storybookPlugin,
    },
    languageOptions: {
      parserOptions: {
        ecmaVersion: 2020,
        sourceType: "module",
      },
    },
    rules: {
      "react/react-in-jsx-scope": "off",
      "@typescript-eslint/no-unused-vars": [
        "error",
        {
          vars: "all",
          varsIgnorePattern: "^_",
          args: "after-used",
          argsIgnorePattern: "^_",
        },
      ],
      "require-jsdoc": "off",
      "react/display-name": "off",
      "react-hooks/exhaustive-deps": "warn",
      "prettier/prettier": "error",
      "jsx-a11y/anchor-is-valid": [
        "error",
        {
          components: ["Link"],
          specialLink: ["hrefLeft", "hrefRight"],
          aspects: ["invalidHref", "preferButton"],
        },
      ],
    },
  },
];

export default config;

 

각 항목들 간단한 설명

import { FlatCompat } ...	FlatCompat은 기존 .eslintrc 기반 설정을 ESLint Flat Config 방식으로 변환해주는 도우미다. Next.js 등의 설정들이 아직 FlatConfig를 직접 지원하지 않기 때문에 필요하다. >>
import ...(Plugin)	FlatConfig 방식에서는 플러그인을 직접 import해서 등록해야한다.
import dirname import fileURLToPath	FlatCompat에 현재 파일 위치를 전달하기 위해 현재 파일 경로를 구하는 코드이다. ESM 환경이기 때문에 이런 방식을 사용한다.
const compat	.eslintrc에서 사용하던 extends: "next/core-web-vitals"같은 설정을 FlatConfig에서도 사용 가능하도록 변환해준다.
const config = [ ...compat.extends(...),	Next.js 프로젝트에서 추천하는 기본 ESLint 설정을 불러와 config 배열에 포함시킨다.
plugins: { ... }	import한 플러그인들을 ESLint에 명시적으로 등록한다.
languageOptions: { ... }	최신 JS 문법, 모듈 시스템을 사용한다고 파서 설정을 한다.
rules : { ... }	⋅ react-injsx-scope : React17부터 JSX를 사용할 때 react를 import하지 않아도 돼서 off ⋅ no-unused-vars : 사용되지 않는 변수/매개변수를 에러처리(이름이 _로 시작하면 무시) ⋅ require-jsdoc : JSDoc 주석 필수 규칙 off ⋅ display-name : 익명 함수 컴포넌트에 displayName 없다고 경고 x ⋅exhaustive-deps : useEffect 등에서 의존성 배열 누락 시 경고 ⋅prettier/prettier : Prettier 포맷팅 오류 시, ESLint 에러로 처리 anchor-is-valid : Link 컴포넌트 유효성 검사 (빈 href, 잘못된 링크 등 검사)
export default config;	위에서 작성한 ESLint 설정을 export ⋅ Flat Config에서는 설정 파일이 반드시 config 객체 배열을 export default 해야 한다.(배열형 설정 방식) ⋅ 객체 단위로 설정이 병합되며, 나중 순서에 등장한 설정이 우선 적용된다. ⋅ 배열 표현 없이 export default config [...]와 같은 방식으로 작성하면 Flat Config 문법 요구사항 미달로     ESLint가 인식하지 못할 수 있으므로, 방식을 맞추자.

 

 

.eslintignore

ESLint 최신 버전(9.x 이상) 부터는 .eslintignore 대신 eslint.config.js내에 ignores 옵션을 사용하는 방식을 권장해서

.eslintignore를 작성하는 게 아니다.

---

5. 🤖 Husky + lint-staged로 커밋 전 자동 검사 설정

위 작성한 설정들을 자동으로 효율적으로 적용하기 위해 Husky와 lint-staged가 필요하다.

• husky : 자동화
• lint-staged : 효율 (staging 파일만 검사한다.)

 

Husky

분명 글을 썼던 기억이 있는데.. 이건 아무튼 따로 정리할 거다.

 

lint-staged

1. husky pre-commit 훅 설정

husky의 pre-commit 훅에서 npx lint-staged를 실행하도록 명령어를 작성한다.

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

 

 

이러면 pre-commit 파일에 내용이 작성되는데, 여기서 lint 검사 에러 발생시 확실하게 커밋 중지하고 싶다!!

하면 exit 1을 명시해서 확실하게 중지시키도록 수정하자.

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx lint-staged || exit 1

 

 

2. package.json 설정

package.json에 lint-staged에 대한 명령어 단축어를 작성하자.

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

• .ts, .tsx, .js 확장자를 가진 파일을 대상으로 한다.
  1. ESLint 자동 수정 + 경고 한개라도 있으면 커밋 실패(max-warnings=0)
      → 팀 규모가 크거나 레거시 코드가 많을 경우, 경고를 허용하고 점진적 개선을 하는 것이 현실적이다.(max-warnings=10)
  2. Prettier로 코드 스타일 포맷 적용
  3. ESLint 자동 수정을 한 번 더 수행하여 포맷팅 이후 발생할 수 있는 이슈를 잡음
• .json, .md, .css, .html 확장자를 가진 파일을 대상으로 한다.
  → 린트 검사를 하지 않고 Prettier 코드 스타일 포맷만 적용

위와 같이 eslint --fix를 두 번 적용하면 더 품질이 높은 검사를 할 수 있으나, 속도 및 효율이 조금 떨어진다.

간결하게 아래와 같이 린트를 수행해도 잘 설계된 설정에서는 대부분의 포맷팅/충돌 문제는 발생하지 않는다.

"*.{ts,tsx,js}": [
  "prettier --write",
  "eslint --fix --max-warnings=0"
]

 

 

 

 

 

참고

https://eslint.org/docs/latest/

Documentation - ESLint - Pluggable JavaScript Linter

https://github.com/lint-staged/lint-staged

GitHub - lint-staged/lint-staged: 🚫💩 — Run tasks like formatters and linters against staged git files

https://cwdeveloper.tistory.com/67

husky + lint-staged가 필요한 이유 (prettier + eslint)

https://velog.io/@jaychang99/Husky-lint-staged-%EC%A0%95%EB%B3%B5%ED%95%98%EA%B8%B0

Husky, lint-staged 정복하기.