ESLint

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

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

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

yarn lint

애플리케이션에 ESLint가 아직 구성되어 있지 않다면, 설치 및 구성 과정을 안내받게 됩니다.

yarn lint

You'll see a prompt like this:

? How would you like to configure ESLint?

❯ Strict (recommended)
Base
Cancel

다음 세 가지 옵션 중 하나를 선택할 수 있습니다:

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

  .eslintrc.json

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

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

  .eslintrc.json

  {
    "extends": "next"
  }

• Cancel: ESLint 구성을 포함하지 않습니다. 자체 사용자 정의 ESLint 구성을 설정할 계획이 있는 경우에만 이 옵션을 선택하세요.

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

이제 오류를 잡기 위해 ESLint를 실행하고 싶을 때마다 next lint를 실행할 수 있습니다. ESLint가 설정되면 모든 빌드(next build) 중에도 자동으로 실행됩니다. 오류는 빌드를 실패시키지만, 경고는 실패시키지 않습니다.

next build 중에 ESLint를 실행하지 않으려면 ESLint 무시하기 문서를 참조하세요.

개발 중에 코드 편집기에서 직접 경고와 오류를 보기 위해 적절한 통합을 사용하는 것을 권장합니다.

ESLint 구성

기본 구성(eslint-config-next)에는 Next.js에서 최적의 즉시 사용 가능한 린팅 경험을 위해 필요한 모든 것이 포함되어 있습니다. 애플리케이션에 ESLint가 이미 구성되어 있지 않다면, 이 구성과 함께 next lint를 사용하여 ESLint를 설정하는 것을 권장합니다.

eslint-config-next를 다른 ESLint 구성과 함께 사용하고 싶다면, 충돌을 일으키지 않고 이를 수행하는 방법을 알아보려면 추가 구성 섹션을 참조하세요.

다음 ESLint 플러그인의 권장 규칙 세트가 모두 eslint-config-next 내에서 사용됩니다:

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

이는 next.config.js의 구성보다 우선합니다.

ESLint 플러그인

Next.js는 Next.js 애플리케이션에서 일반적인 문제와 이슈를 잡을 수 있게 해주는 ESLint 플러그인인 eslint-plugin-next를 기본 구성에 이미 번들로 제공합니다. 전체 규칙 세트는 다음과 같습니다:

✔️ 권장 구성에서 활성화됨

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

사용자 정의 설정

rootDir

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"], // 프로덕션 빌드(next build) 중에 'pages'와 'utils' 디렉토리에서만 ESLint 실행
  },
};

마찬가지로, next lint에 --dir과 --file 플래그를 사용하여 특정 디렉토리와 파일을 린트할 수 있습니다:

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

next/core-web-vitals 규칙 세트는 next lint를 처음 실행하고 strict 옵션을 선택할 때 활성화됩니다.

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

next/core-web-vitals는 Core Web Vitals에 영향을 미치는 경우 기본적으로 경고인 여러 규칙에 대해 eslint-plugin-next를 오류로 업데이트합니다.

next/core-web-vitals 진입점은 Create Next App으로 구축된 새 애플리케이션에 대해 자동으로 포함됩니다.

TypeScript

Next.js ESLint 규칙 외에도, create-next-app --typescript는 next/typescript와 함께 TypeScript 특정 린트 규칙을 구성에 추가합니다:

{
  "extends": ["next/core-web-vitals", "next/typescript"]
}

이러한 규칙은 plugin:@typescript-eslint/recommended를 기반으로 합니다. 자세한 내용은 typescript-eslint > Configs를 참조하세요.

다른 도구와의 사용

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

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

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

lint-staged

lint-staged와 함께 next lint를 사용하여 스테이징된 git 파일에 대해 린터를 실행하려면, --file 플래그 사용을 지정하기 위해 프로젝트 루트의 .lintstagedrc.js 파일에 다음을 추가해야 합니다.

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
• Next.js 내의 Babel 구성과 다른 특정 parserOptions를 정의한 경우(Babel 구성을 사용자 정의한 경우가 아니라면 권장되지 않음)
• Node.js 및/또는 TypeScript용 resolvers가 정의된 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

이렇게 하면 여러 구성에서 동일한 플러그인이나 파서를 가져올 때 발생할 수 있는 충돌이나 오류의 위험을 제거합니다.

추가 구성

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

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

next 구성은 이미 parser, plugins, settings 속성에 대한 기본값 설정을 처리합니다. 사용 사례에 다른 구성이 필요한 경우가 아니라면 이러한 속성을 수동으로 다시 선언할 필요가 없습니다.

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