ESLint v9 이후의 flat config 기준으로 다시 정리했습니다. - 26. 06.
ESLint 설정 방법에 대해 정리한 글입니다. 제가 TypeScript, React, Next.js 프로젝트를 진행할 때 주로 사용하는 설정을 기준으로 작성했습니다.
먼저 짚고 가기
ESLint
ESLint는 JavaScript, TypeScript, JSX 코드를 분석해서 버그 가능성이 높은 패턴이나 팀에서 금지한 작성 방식을 찾아주는 도구입니다. 예전에는 포매팅 규칙도 많이 담당했지만, ESLint v8.53.0부터 포매팅 규칙이 deprecated 되었고 ESLint v10부터 제거되었습니다.
그래서 지금은 ESLint를 "코드 품질과 규칙 검사"에 두고, 포매팅은 Prettier에 맡기는 구성이 가장 단순합니다.
2026년 6월 기준 ESLint의 현재 릴리스 라인은 v10입니다. 다만 v9도 아직 maintenance 상태이고, flat config를 사용하는 프로젝트라면 v9와 v10의 설정 형태는 크게 다르지 않습니다.
Next.js를 같이 쓴다면 사용하는 Next.js와 eslint-config-next 버전을 먼저 확인하는 것이 좋습니다. 이 글을 갱신하는 시점의 eslint-config-next@16.2.6은 eslint >=9.0.0을 peer dependency로 요구합니다. 즉 ESLint v9를 유지해도 되고, 프로젝트 의존성이 맞으면 v10을 사용해도 됩니다.
Prettier
Prettier는 코드를 다시 출력해서 줄바꿈, 공백, 괄호, 따옴표 같은 형식을 일관되게 맞춰주는 formatter입니다.
ESLint 쪽에서는 포매팅 규칙을 직접 관리하고 싶다면 ESLint Stylistic을 사용할 수 있다고 안내하지만, Prettier와 같은 결과를 ESLint 규칙으로 전부 맞추려면 설정이 꽤 복잡해집니다. 그래서 저는 formatter는 Prettier에 맡기고, ESLint에서는 Prettier 결과가 어긋났는지만 error로 띄우는 방식을 선호합니다.
패키지 구성과 설치
이 글의 예제는 TypeScript, React, Next.js 프로젝트를 기준으로 합니다. Next.js를 쓰는 경우와 일반 TypeScript/React 프로젝트를 쓰는 경우에 필요한 패키지가 조금 다릅니다.
설치 명령은 묶음별로 나눴습니다. 전부 한 번에 설치해도 되지만, 어떤 패키지가 왜 필요한지 확인하면서 복사하기에는 묶음 단위가 더 편합니다.
Next.js 프로젝트
eslint: ESLint 코어 패키지입니다.eslint-config-next: Next.js, React, React Hooks 규칙을 포함한 공유 설정입니다.
Next.js TypeScript 프로젝트에서는 eslint-config-next/typescript를 함께 사용하면 됩니다. Next.js 공식 문서에 따르면 이 설정은 typescript-eslint 기반 TypeScript 전용 lint 규칙을 추가합니다.
따라서 일반적인 Next.js 프로젝트에서는 typescript-eslint, @typescript-eslint/eslint-plugin, eslint-plugin-react, eslint-plugin-react-hooks, @next/eslint-plugin-next를 따로 설치하지 않아도 됩니다. 이미 create-next-app이나 Codemods로 설정된 프로젝트라면 위 패키지도 이미 설치되어 있을 수 있습니다.
@next/eslint-plugin-next는 Next.js 규칙만 직접 주입하고 싶을 때 설치합니다. 기존 ESLint 설정에 충돌 가능성이 있거나, eslint-config-next 전체를 쓰기 어려운 경우에 사용하는 선택지입니다.
Next.js 16부터는 next lint가 제거되었고 ESLint CLI를 직접 사용합니다.
일반 TypeScript 프로젝트
eslint: ESLint 코어 패키지입니다.@eslint/js: JavaScript 권장 규칙을 flat config에서 가져올 때 사용합니다.typescript-eslint: TypeScript ESLint의 권장 규칙과 플러그인을 가져올 때 사용합니다.globals: Node.js, browser 같은 전역 변수를 설정할 때 사용합니다.
Next.js가 아닌 프로젝트에서 flat config로 typescript-eslint를 사용한다면 @typescript-eslint/parser와 @typescript-eslint/eslint-plugin을 따로 설치하지 않아도 됩니다. typescript-eslint 패키지가 parser와 plugin을 함께 제공하고, 필요한 경우 tseslint.parser, tseslint.plugin으로 꺼내 쓸 수 있습니다.
Prettier 연동
prettier: 코드 포매터입니다.eslint-config-prettier: ESLint의 포매팅 관련 규칙을 꺼서 Prettier와 충돌하지 않게 합니다.eslint-plugin-prettier: Prettier 실행 결과를 ESLint rule error로 표시합니다.
eslint-plugin-prettier는 필수는 아닙니다. 에디터나 CI에서 prettier --check를 따로 실행한다면 생략할 수 있습니다. 저는 AI 에이전트나 팀원이 eslint만 실행해도 포매팅 오류를 같이 보게 만들고 싶을 때 사용합니다.
import 정렬
eslint-plugin-import-x: import/export 관련 규칙을 제공합니다. 예제에서는import-x/order로 import 문을 그룹별로 정렬합니다.
일반 React 프로젝트
eslint-plugin-react: React 컴포넌트 관련 규칙을 제공합니다.eslint-plugin-react-hooks: hooks 규칙과 React Compiler 관련 lint를 제공합니다.
Next.js에서 eslint-config-next를 사용한다면 이 묶음은 따로 설치하지 않아도 됩니다. Next.js 공식 문서에 따르면 eslint-config-next에는 @next/eslint-plugin-next와 함께 eslint-plugin-react, eslint-plugin-react-hooks가 이미 포함되어 있습니다.
TypeScript 프로젝트에서는 prop type을 TypeScript가 담당하므로
react/prop-types는 꺼두는 편이 좋습니다.
eslint-plugin-react-hooks 최신 문서에는 기존 hooks 규칙뿐 아니라 React Compiler 진단 규칙도 포함되어 있습니다.
React 공식 문서의 recommended preset에는 exhaustive-deps, rules-of-hooks 외에도 immutability, purity, refs, set-state-in-effect, static-components, use-memo 같은 규칙이 들어갑니다.
위 이슈들처럼 flat config와 recommended preset 주변에는 버전별 이슈가 있었기 때문에, hooks 규칙은 설치한 버전의 공식 문서를 확인한 뒤 적용하는 것이 좋습니다.
프로젝트 상황에 따라 React Compiler 관련 규칙이 너무 공격적으로 느껴지면 필요한 규칙만 끄고 시작해도 됩니다.
설정 방법
IDE에 ESLint 설치
VSCode의 확장탭에서 ESLint 혹은 dbaeumer.vscode-eslint를 검색하여 설치합니다.
eslint.config.mjs
아래 예제는 이 글을 작성할 때 사용 중인 Next.js 프로젝트 기준 설정입니다. eslint-config-next로 Next.js, React, React Hooks, TypeScript 규칙을 가져오고, 직접 설치한 eslint-plugin-import-x, eslint-plugin-prettier만 추가로 주입합니다.
eslint-config-next에는 React, React Hooks, Next.js 규칙이 이미 포함되어 있습니다. TypeScript 프로젝트에서는 eslint-config-next/typescript를 함께 spread하면 typescript-eslint 기반 규칙도 적용됩니다. 그래서 위 예제처럼 Next.js 설정은 공유 설정에 맡기고, import 정렬이나 Prettier처럼 직접 설치한 플러그인만 추가로 주입하는 편이 관리하기 쉽습니다.
prettier.config.js
VSCode 설정
소스코드를 내려받은 사용자가 같은 확장과 저장 시 동작을 사용하도록 .vscode 설정을 추가합니다.
결론
ESLint v9 이후에는 flat config가 기본 흐름이 되었고, Next.js 16부터는 next lint 대신 ESLint CLI를 직접 사용합니다.
지금은 ESLint를 코드 품질과 규칙 검사에 집중시키고, Prettier는 formatter로 분리하는 구성이 가장 관리하기 쉽습니다. Next.js 프로젝트라면 eslint-config-next/core-web-vitals, eslint-config-next/typescript를 먼저 사용하고, 일반 TypeScript/React 프로젝트라면 typescript-eslint, React hooks 규칙, import 정렬 정도부터 잡아도 팀 코드 스타일을 꽤 안정적으로 맞출 수 있습니다.