ESLint

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

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

1. Strict 엄격: Next.js의 기본 ESLint 설정과 함께 더 엄격한 Core Web Vitals 규칙 세트를 포함합니다. ESLint를 처음 설정하는 개발자들에게 추천하는 설정입니다.

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

2. Base 기본: Next.js의 기본 ESLint 설정을 포함합니다.

{
  "extends": "next"
}

3. 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에서 최적의 linting 경험을 바로 얻기 위해 필요한 모든 것을 포함합니다. 만약 ESLint가 이미 애플리케이션에 설정되어 있지 않다면, 이 설정과 함께 ESLint를 설정하기 위해 next lint를 사용하는 것을 권장합니다.

eslint-config-next를 다른 ESLint 설정과 함께 사용하고 싶다면, 충돌 없이 어떻게 그렇게 할 수 있는지 알아보기 위해 추가 설정 섹션을 참조하세요.

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

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

이 설정은 next.config.js의 설정보다 우선시 됩니다.

ESLint 플러그인

Next.js는 eslint-plugin-next ESLint 플러그인을 제공하며 기본 설정에 이미 번들로 포함되어 있습니다. 이 플러그인을 통해 Next.js 애플리케이션에서 흔히 발생할 수 있는 문제점과 오류를 포착할 수 있습니다. 전체 규칙은 다음과 같습니다.

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

사용자 정의 설정

rootDir

eslint-plugin-next를 사용하는 프로젝트에서 Next.js가 루트 디렉토리에 설치되어 있지 않은 경우(예: 모노레포), .eslintrc의 settings 속성을 사용하여 Next.js 애플리케이션을 찾을 위치를 eslint-plugin-next에 알려줄 수 있습니다.

{
  "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: {
    // 프로덕션 빌드 중 'pages'와 'utils' 디렉토리에서만 \
    // ESLint를 실행합니다 (next build)
    dirs: ['pages', 'utils'], 
  },
}

마찬가지로 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"
  }
}

코어 웹 바이탈스

next lint가 처음 실행될 때 strict 옵션이 선택되면 next/core-web-vitals 규칙 세트가 활성화됩니다.

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

next/core-web-vitals는 코어 웹 바이탈스에 영향을 주는 규칙들을 기본적으로 경고에서 오류로 변경하여 eslint-plugin-next를 업데이트합니다.

next/core-web-vitals 진입점은 Create Next App으로 새로운 애플리케이션을 빌드할 때 자동으로 포함됩니다.

다른 도구와 함께 사용하기

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

next lint를 lint-staged와 함께 사용하여 staged git 파일에서 린터를 실행하려면, 프로젝트의 루트에 있는 .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],
}

기존 설정 마이그레이션

권장 플러그인 규칙 세트

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 플러그인에서 직접 확장하는 것을 권장합니다.