ESLint flat config 규칙 적용 안됨 해결: eslint.config.js 기준

flat config란

현재 ESLint의 기본 설정 체계는 flat config입니다.

대표 설정 파일 이름은 다음과 같습니다.

eslint.config.js
eslint.config.mjs
eslint.config.cjs

프로젝트 루트에서 ESLint가 설정 파일을 찾을 수 있어야 합니다.

가장 작은 설정부터 시작하기

예제:

import js from '@eslint/js';
import { defineConfig } from 'eslint/config';

export default defineConfig([
  js.configs.recommended,
  {
    files: ['src/**/*.js'],
    rules: {
      'no-console': 'warn',
    },
  },
]);

이 설정은 기본 recommended 규칙을 사용하고 src 아래 JavaScript 파일에 no-console 경고를 추가합니다.

package.json script

{
  "scripts": {
    "lint": "eslint ."
  }
}

실행합니다.

pnpm lint

에디터에 표시되는 밑줄보다 CLI 결과를 기준으로 검증합니다.

규칙이 적용되지 않는 가장 흔한 이유

files 패턴이 대상 파일과 맞지 않습니다

{
  files: ['src/**/*.js'],
  rules: {
    'no-console': 'warn',
  },
}

대상 파일이 .jsx나 .ts라면 이 설정이 적용되지 않을 수 있습니다.

실제 프로젝트 확장자에 맞게 범위를 작성합니다.

{
  files: ['src/**/*.{js,jsx}'],
}

JSX를 실제로 파싱하려면 files 패턴만 바꾸는 것으로는 충분하지 않습니다. languageOptions.parserOptions.ecmaFeatures.jsx를 true로 설정하고, React를 사용하는 경우 해당 프레임워크의 lint 설정도 별도로 구성합니다. 아래 TaskFlow 최종 예제는 JSX를 사용하지 않는 JavaScript/Vite 앱입니다.

TypeScript 프로젝트는 TypeScript용 플러그인과 설정을 별도로 구성해야 합니다. 개발환경 과정에서는 JavaScript/Vite 기준의 적용 원리를 먼저 확인합니다.

ignores로 제외됐습니다

{
  ignores: ['dist/**'],
}

검사하려는 파일이 ignore 패턴에 포함됐는지 확인합니다.

뒤쪽 설정이 앞쪽 설정을 덮습니다

flat config는 설정 객체 배열을 사용합니다.

같은 파일에 여러 설정이 적용되면 뒤쪽 값이 최종 결과에 영향을 줄 수 있습니다.

export default [
  {
    rules: {
      'no-console': 'warn',
    },
  },
  {
    files: ['src/debug.js'],
    rules: {
      'no-console': 'off',
    },
  },
];

src/debug.js에서는 no-console이 꺼집니다.

config 파일 위치 확인

다른 폴더에서 ESLint를 실행하면 예상한 config를 찾지 못할 수 있습니다.

현재 위치를 확인합니다.

Windows PowerShell:

Get-Location

그리고 package.json과 eslint.config.js가 어느 루트에 있는지 비교합니다.

workspace 프로젝트에서는 루트와 앱 폴더의 역할을 명확히 해야 합니다.

CLI와 VS Code가 다르게 보일 때

VS Code ESLint extension 상태와 CLI는 별개로 확인합니다.

pnpm lint

CLI가 정상인데 에디터 표시가 이상하면 extension 설정과 workspace를 확인합니다.

반대로 에디터에서 경고가 없더라도 CLI가 실패한다면 CI나 배포 과정에서도 실패할 수 있습니다.

따라서 완료 기준은 CLI입니다.

문제 재현

src/debug.js:

const message = 'TaskFlow';
console.log(message);

const unused = true;

실행:

pnpm lint

예상 결과:

no-console 경고
no-unused-vars 오류 또는 경고

규칙 강도는 프로젝트 정책에 맞게 조정합니다.

오류 해결 순서

1. 실행 위치
2. eslint.config.* 존재 여부
3. 대상 파일 확장자
4. files 패턴
5. ignores
6. config 배열 순서
7. plugin 설치 상태
8. CLI 직접 실행
9. VS Code extension 상태

자주 발생하는 실수

.eslintrc 예제를 그대로 섞습니다

기존 eslintrc와 flat config는 구조가 다릅니다. 현재 프로젝트가 어떤 체계를 사용하는지 먼저 확인합니다.

env를 그대로 사용합니다

flat config에서는 languageOptions.globals 같은 구조를 사용합니다.

에디터에 밑줄이 없으니 정상이라고 판단합니다

완료 기준은 CLI 실행입니다.

pnpm lint

dist까지 검사합니다

빌드 산출물은 ignores로 제외합니다.

학습 완료 체크리스트

• eslint.config.js의 역할을 설명할 수 있습니다.
• flat config가 배열 구조라는 것을 이해했습니다.
• files와 ignores를 구분할 수 있습니다.
• 뒤쪽 설정이 결과에 영향을 줄 수 있음을 이해했습니다.
• CLI와 VS Code extension 상태를 분리해 확인할 수 있습니다.
• 규칙이 적용되지 않을 때 재설치보다 설정 범위를 먼저 확인합니다.

pnpm install
pnpm dev

import js from '@eslint/js';
import { defineConfig } from 'eslint/config';
import globals from 'globals';

export default defineConfig([
  { ignores: ['dist/**'] },
  js.configs.recommended,
  {
    files: ['src/**/*.js'],
    languageOptions: { globals: globals.browser },
    rules: { 'no-console': 'warn' },
  },
]);

pnpm --filter @taskflow/web add -D eslint @eslint/js globals

dev-env-step-04-vite-env

eslint.config.js 추가
lint script 확정
dist ignore
src JavaScript 검사 범위 확정
CLI 검증 기준 확정

package.json
eslint.config.js

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint ."
  }
}

pnpm lint
pnpm dev

dev-env-step-05-eslint-flat

node_modules/
dist/
storybook-static/
.env.local
.env.*.local

VITE_API_URL=https://api.example.invalid
VITE_APP_NAME=TaskFlow

import js from '@eslint/js';
import { defineConfig } from 'eslint/config';
import globals from 'globals';

export default defineConfig([
  { ignores: ['dist/**'] },
  js.configs.recommended,
  {
    files: ['src/**/*.js'],
    languageOptions: { globals: globals.browser },
    rules: { 'no-console': 'warn' },
  },
]);

<!doctype html>
<html lang="ko">
<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>TaskFlow 개발환경</title></head>
<body><main id="app"></main><script type="module" src="/src/main.js"></script></body>
</html>

{
  "name": "@taskflow/web",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "vite build",
    "lint": "eslint ."
  },
  "devDependencies": {
    "vite": "8.3.0",
    "eslint": "10.11.0",
    "@eslint/js": "10.0.1",
    "globals": "17.12.0"
  }
}

const apiUrl = import.meta.env.VITE_API_URL;
const appName = import.meta.env.VITE_APP_NAME;

if (!apiUrl) {
  throw new Error('VITE_API_URL 환경 변수가 필요합니다.');
}

export const env = {
  apiUrl,
  appName: appName || 'TaskFlow',
};

import './style.css';
import { env } from './config/env.js';

const app = document.querySelector('#app');
const title = document.createElement('h1');
title.textContent = env.appName;
const status = document.createElement('p');
status.textContent = '개발환경 스타터가 실행 중입니다.';
const api = document.createElement('p');
api.id = 'api-url';
api.textContent = `API URL: ${env.apiUrl}`;
app.append(title, status, api);

body { margin: 0; color: #202020; background: #f6f6f6; font: 16px/1.6 system-ui, sans-serif; }
main { max-width: 720px; margin: 64px auto; padding: 24px; }
h1 { font-size: 30px; font-weight: 500; }
p { overflow-wrap: anywhere; }

# TaskFlow 개발환경

이 스타터는 개발환경 진단을 위한 최소 Vite/vanilla JavaScript 앱입니다. 할 일 관리 기능이나 API 서버는 포함하지 않습니다.

Node.js 24.19.0, pnpm 11.19.0으로 검증했습니다. 루트는 pnpm만 사용하며 apps/*만 workspace입니다. labs의 npm/Yarn/pnpm 실습은 독립 프로젝트입니다.

## 2회차

메인 앱은 pnpm을 유지합니다. labs/yarn-modern은 독립 Yarn 실습입니다.

## 3회차

apps/web/.env.example을 apps/web/.env.local로 복사합니다. .invalid 주소는 표시만 하며 실제 API 호출은 하지 않습니다. 공개 샘플값만 제공하고 로컬 파일은 ZIP에서 제외합니다.

## 4회차

Vite 루트는 apps/web입니다. env.js가 필수 VITE_API_URL을 검사하고 화면에 공개 URL을 표시합니다.

## 5회차

ESLint 설정과 의존성은 apps/web에 있습니다. 루트 pnpm lint가 앱의 eslint .을 호출합니다.

{
  "name": "taskflow",
  "private": true,
  "packageManager": "pnpm@11.19.0",
  "engines": {
    "node": ">=24"
  },
  "scripts": {
    "dev": "pnpm --filter @taskflow/web dev",
    "build": "pnpm --filter @taskflow/web build",
    "lint": "pnpm --filter @taskflow/web lint"
  }
}

packages:
  - "apps/*"

# TaskFlow 개발환경 05 완료 체크포인트

Node.js 24.19.0 / pnpm 11.19.0 검증 기준입니다. pnpm을 별도로 설치한 환경에서 실행하세요. ZIP에는 node_modules, dist, 로컬 환경 변수, 실제 비밀값이 없습니다.

1. 이 폴더에서 `pnpm install --frozen-lockfile`
2. PowerShell: `Copy-Item apps/web/.env.example apps/web/.env.local` 또는 macOS/Linux: `cp apps/web/.env.example apps/web/.env.local`
3. `pnpm dev` 후 http://127.0.0.1:5173 확인
4. `pnpm build`
5. `pnpm lint`

apps/web가 Vite 루트입니다. 환경 변수도 이 폴더에 둡니다. 표시용 API 주소에 실제 요청을 보내지 않습니다. labs는 메인 workspace에서 제외되어 각 폴더에서 별도 설치합니다.

원문 단계별 전체 파일과 실행 검증 범위는 docs/development-environment.md를 확인하세요.

nodeLinker: node-modules

{
  "name": "taskflow-yarn-lab",
  "private": true,
  "type": "module",
  "packageManager": "yarn@4.18.0",
  "scripts": {
    "dev": "node src/main.js",
    "lint": "node --check src/main.js"
  }
}

console.log('TaskFlow Yarn 독립 실습');

다음 학습

다음 글부터는 정상 개발환경을 일부러 깨뜨립니다.

먼저 npm의 peer dependency 충돌을 별도 lab에서 재현하고 ERESOLVE 오류를 읽는 방법부터 학습합니다.

다음 글: npm install 의존성 충돌 해결: ERESOLVE 오류가 날 때 해결법

공식 문서

• ESLint Configuration Files: https://eslint.org/docs/latest/use/configure/configuration-files
• ESLint Migration Guide: https://eslint.org/docs/latest/use/configure/migration-guide