ESLint

Next.js는 기본적으로 통합된 ESLint 환경을 제공합니다. package.json에 다음 lint를 스크립트로 추가해주세요:

{
  "scripts": {
    "lint": "next lint"
  }
}

그런 다음 npm run lint 또는 yarn lint를 실행하세요:

yarn lint

만약 당신의 어플리케이션에 이미 ESLint가 설정되어 있지 않다면, 설치 및 구성 과정을 안내받을 수 있습니다.

yarn lint

다음과 같은 프롬프트가 표시됩니다: ? ESLint를 어떻게 구성하시겠습니까? ❯ 엄격 (권장) 베이스 취소

다음 중 하나를 선택할 수 있습니다:

엄격: Next.js의 기본 ESLint 구성과 더 엄격한 Core Web Vitals 규칙 세트를 포함합니다. 처음으로 ESLint를 설정하는 개발자를 위한 권장 구성입니다.

.eslintrc.json
{
  "extends": "next/core-web-vitals"
}

기본: Next.js의 기본 ESLint 구성을 포함합니다.

.eslintrc.json
{
  "extends": "next"
}

취소: 어떤 ESLint 구성도 포함되지 않습니다. 사용자 정의 ESLint 구성을 설정할 계획이 없는 경우에만 선택하십시오.

두 구성 옵션 중 하나를 선택하면 Next.js가 자동으로 애플리케이션에 eslint와 eslint-config-next를 종속성으로 설치하고 프로젝트 루트에 .eslintrc.json 파일을 생성하여 선택한 구성을 포함합니다.

ESLint를 실행하여 오류를 찾고 싶을 때마다 next lint를 실행할 수 있습니다. ESLint를 설정한 후에는 build(다음 빌드) 중에 자동으로 실행됩니다. 오류는 빌드를 실패하게 하고 경고는 그렇지 않습니다.

다음 빌드 중에 ESLint를 실행하지 않으려면 Ignoring ESLint 문서를 참조하세요.

개발 중에 코드 에디터에서 경고와 오류를 바로 볼 수 있는 적절한 통합을 사용하는 것을 권장합니다.

ESLint 설정

기본 구성 (eslint-config-next)은 Next.js에서 최적의 'Out-of-the-box' 린팅 경험을 제공하는 데 필요한 모든 것이 포함되어 있습니다. 응용 프로그램에 ESLint가 이미 구성되어 있지 않은 경우에는,이 구성과 함께 ESLint를 설정하기 위해 next lint를 사용하는 것을 권장합니다.

만약 다른 ESLint 구성과 함께 eslint-config-next를 사용하려면, 추가 구성 섹션을 참조하여 어떻게 충돌을 일으키지 않고 그렇게 할 수 있는지 알아보세요.

다음 ESLint 플러그인에서 추천되는 규칙 세트는 모두 eslint-config-next 내에서 사용됩니다:

eslint-plugin-react
eslint-plugin-react-hooks
eslint-plugin-next

이 설정이 next.config.js에서의 구성보다 우선합니다.

ESLint 플러그인

Next.js는 이미 기본 구성 내에 번들로 포함된 ESLint 플러그인인 eslint-plugin-next을 제공합니다. 이 플러그인은 Next.js 애플리케이션에서 일반적인 문제와 이슈를 감지하는 데 도움이 됩니다. 모든 규칙 목록은 다음과 같습니다:

추천 설정에서 활성화됨

Rule	Description
@next/next/google-font-display	Google Fonts에서 font-display 동작을 강제
@next/next/google-font-preconnect	Google Fonts와 함께 `preconnect` 사용을 보장
@next/next/inline-script-id	인라인 콘텐츠가 있는 `next/script` 컴포넌트에 대해 `id` 속성을 강제
@next/next/next-script-for-ga	Google Analytics용 인라인 스크립트를 사용할 때 `next/script` 컴포넌트를 선호
@next/next/no-assign-module-variable	`module` 변수에 할당을 방지
@next/next/no-async-client-component	클라이언트 컴포넌트가 비동기 함수가 되는 것을 방지
@next/next/no-before-interactive-script-outside-document	`next/script`의 `beforeInteractive` 전략을 `pages/_document.js` 외부에서 사용하는 것을 방지
@next/next/no-css-tags	수동으로 스타일시트 태그를 방지
@next/next/no-document-import-in-page	`pages/_document.js` 외부에서 `next/document` 가져오는 것을 방지
@next/next/no-duplicate-head	`pages/_document.js`에서 `<Head>`의 중복 사용을 방지
@next/next/no-head-element	`<head>` 엘리먼트 사용을 방지
@next/next/no-head-import-in-document	`pages/_document.js`에서 `next/head` 사용을 방지
@next/next/no-html-link-for-pages	내부 Next.js 페이지로 이동하기 위해 `<a>` 엘리먼트 사용 방지
@next/next/no-img-element	LCP가 느리고 대역폭이 더 높아지는 것을 방지하기 위해 `<img>` 엘리먼트 사용 방지
@next/next/no-page-custom-font	페이지 전용 사용자 정의 폰트 방지
@next/next/no-script-component-in-head	`next/head` 컴포넌트에서 `next/script` 사용 방지
@next/next/no-styled-jsx-in-document	`pages/_document.js`에서 `styled-jsx` 사용 방지
@next/next/no-sync-scripts	동기 스크립트 방지
@next/next/no-title-in-document-head	`next/document`의 `Head` 컴포넌트에서 `<title>` 사용 방지
@next/next/no-typos	Next.js의 데이터 패칭 함수에서 흔한 오타 방지
@next/next/no-unwanted-polyfillio	Polyfill.io에서 중복 폴리필 방지

만약 이미 애플리케이션에 ESLint가 구성되어 있다면, 몇 가지 조건이 충족될 때 eslint-config-next를 포함하는 대신에이 플러그인을 직접 확장하는 것이 좋습니다. 더 자세한 내용은 권장되는 플러그인 규칙 세트를 참조하십시오.

사용자 정의 설정

rootDir

만약 root 디렉토리(모노 저장소와 같이)에 Next.js가 설치되어 있지 않은 프로젝트에서 eslint-plugin-next를 사용 중이라면, .eslintrc 파일의 settings 속성을 사용하여 eslint-plugin-next에게 Next.js 애플리케이션을 찾을 위치를 알릴 수 있습니다:

{
  "extends": "next",
  "settings": {
    "next": {
      "rootDir": "packages/my-app/"
    }
  }
}

rootDir은 경로(상대적 또는 절대), 글로브("packages/*/") 또는 경로 및/또는 글로브의 배열일 수 있습니다.

사용자 지정 디렉토리 및 파일 린팅

기본적으로 Next.js는 pages/, app/, components/, lib/, src/ 디렉토리의 모든 파일에 대해 ESLint를 실행합니다. 그러나 next.config.js에서 eslint 구성의 dirs 옵션을 사용하여 프로덕션 빌드를 위해 사용할 디렉토리를 지정할 수 있습니다:

module.exports = {
  eslint: {
    dirs: ['pages', 'utils'], // Only run ESLint on the 'pages' and 'utils' directories during production builds (next build)
  },
}

비슷하게, --dir 및 --file 플래그를 사용하여 특정 디렉토리 및 파일에 대해 lint를 실행할 수 있습니다:

next lint --dir pages --dir utils --file bar.js

캐싱

성능을 향상하기 위해 ESLint로 처리된 파일의 정보는 기본적으로 캐시됩니다. 이 정보는 .next/cache에 저장되거나 사용자가 지정한 빌드 디렉토리에 저장됩니다. 단일 소스 파일의 내용 이상에 의존하는 ESLint 규칙을 포함하고 캐시를 비활성화해야 하는 경우, next lint와 함께 --no-cache 플래그를 사용하세요.

next lint --no-cache

규칙 비활성화

지원되는 플러그인(react, react-hooks, next)에서 제공하는 규칙을 수정하거나 비활성화하려면 .eslintrc의 rules 속성을 직접 변경할 수 있습니다:

{
  "extends": "next",
  "rules": {
    "react/no-unescaped-entities": "off",
    "@next/next/no-page-custom-font": "off"
  }
}

Core Web Vitals

The next/core-web-vitals rule set is enabled when running next lint for the first time with the strict option selected.

{
  "extends": "next/core-web-vitals"
}

next/core-web-vitals 업데이트는 코어 웹 바이탈에 영향을 미치는 경고 중 일부 규칙을 기본적으로 오류로 설정합니다.

Create Next App으로 새 애플리케이션을 만들 때 자동으로 next/core-web-vitals 엔트리 포인트가 포함됩니다.

다른 도구와의 사용

Prettier

ESLint에는 코드 서식 지정 규칙도 포함되어 있습니다. 해당 규칙은 기존 Prettier 설정과 충돌할 수 있습니다. ESLint와 Prettier를 함께 사용하려면 ESLint 구성에 eslint-config-prettier를 포함하는 것이 좋습니다.

먼저 의존성을 설치하세요:

npm install --save-dev eslint-config-prettier

yarn add --dev eslint-config-prettier

pnpm add --save-dev eslint-config-prettier

bun add --dev eslint-config-prettier

그런 다음 Prettier를 기존 ESLint 구성에 추가하세요.

{
  "extends": ["next", "prettier"]
}

lint-staged

만약 staged git 파일에 linter를 실행하려면 lint-staged와 함께 next lint를 사용하려면, 프로젝트 루트에 있는 .lintstagedrc.js 파일에 다음을 추가해야 합니다. --file 플래그의 사용을 지정하기 위해 파일 이름을 사용합니다.

const path = require('path')

const buildEslintCommand = (filenames) =>
  `next lint --fix --file ${filenames
    .map((f) => path.relative(process.cwd(), f))
    .join(' --file ')`

module.exports = {
  '*.{js,jsx,ts,tsx}': [buildEslintCommand],
}

기존 설정 이전

권장 플러그인 룰셋

이미 응용 프로그램에서 ESLint를 구성했으며 다음 조건 중 하나 이상이 해당되는 경우:

이미 다음 플러그인 중 하나 이상이 설치되어 있습니다 (별도로 또는 airbnb 또는 react-app과 같은 다른 구성을 통해): react react-hooks jsx-a11y import
react
react-hooks
jsx-a11y
import
Next.js 내에서 Babel이 구성된 방법과 다른 parserOptions를 명시했습니다 (사용자 정의 Babel 구성이 없는 한 권장되지 않음)
Node.js 및/또는 TypeScript 리졸버가 지원하는 eslint-plugin-import가 설치되어 있습니다 수입을 처리하기 위해 정의되었습니다

다음으로, 만약 eslint-config-next 내에 구성된 속성들을 선호한다면 해당 설정을 제거하거나 직접적으로 Next.js ESLint 플러그인에서 확장할 것을 권장드립니다:

module.exports = {
  extends: [
    //...
    'plugin:@next/next/recommended',
  ],
}

프로젝트에 플러그인을 일반적으로 설치할 수 있고 next lint를 실행할 필요가 없습니다:

npm install --save-dev @next/eslint-plugin-next
 
yarn add --dev @next/eslint-plugin-next
 
pnpm add --save-dev @next/eslint-plugin-next
 
bun add --dev @next/eslint-plugin-next

테이블 태그를 Markdown 형식으로 변경하면 다음과 같습니다.

추가 구성

이미 별도의 ESLint 구성을 사용하고 있고 eslint-config-next를 포함하려는 경우, 다른 구성 후에 마지막으로 확장되도록 확인하세요. 예를 들어:

{
  "extends": ["eslint:recommended", "next"]
}

다음 구성은 이미 구문 분석기, 플러그인 및 설정 속성에 대한 기본값을 설정하므로 사용 사례에 대해 다른 구성이 필요하지 않은 한 이러한 속성을 수동으로 다시 선언할 필요가 없습니다.

다른 공유 가능 구성을 포함하는 경우에는이러한 속성이 덮어쓰이거나 수정되지 않도록해야합니다. 그렇지 않으면 다음 구성과 동일한 동작을 공유하는 구성을 제거하거나 위에서 언급한대로 Next.js ESLint 플러그인에서 직접 확장하는 것이 좋습니다.

Nextjs 14에서 ESLint 사용하는 법 앱 라우터 설정 팁