Vercel 빌드 실패: ESLint import/order 규칙

배경

로컬에서는 정상 동작하는 코드를 PR 올렸는데, Vercel 빌드에서 ESLint 에러가 발생했다.

에러 내용

./src/app/(dashboard)/machine/[id]/page.tsx
39:1  Error: There should be at least one empty line between import groups  import/order
40:1  Error: `@tanstack/react-query` import should occur before import of `./_components/tabs/PictureListTabContent`  import/order

문제가 된 코드:

// ... 로컬 import들 ...
import type { MachineProjectResponseDtoType, MachineProjectTabValueType } from '@/@core/types'
import { isMobileContext } from '@/@core/contexts/mediaQueryContext'
import { useQueryClient } from '@tanstack/react-query' // ← 여기가 문제

@tanstack/react-query는 npm 외부 패키지인데, 프로젝트 내부 import(@/, @core/) 뒤에 넣었다.

원인

프로젝트의 .eslintrc.js에 import/order 규칙이 설정되어 있었다.

'import/order': [
  'error',
  {
    groups: ['builtin', 'external', ['internal', 'parent', 'sibling', 'index'], ['object', 'unknown']],
    pathGroups: [
      { pattern: 'react', group: 'external', position: 'before' },
      { pattern: 'next/**', group: 'external', position: 'before' },
      { pattern: '@/**', group: 'internal' },
    ],
    'newlines-between': 'always-and-inside-groups'
  }
]

이 규칙에 따르면 import 순서는 다음과 같다:

1. builtin   → Node.js 내장 모듈 (fs, path 등)
2. external  → npm 패키지 (@tanstack/react-query, classnames 등)
3. internal  → 프로젝트 내부 경로 (@/**, @core/** 등)

• 각 그룹 사이에는 빈 줄이 필요 (newlines-between: 'always-and-inside-groups')
• @/** 패턴은 internal 그룹으로 분류됨
• @tanstack/react-query는 npm 패키지이므로 external 그룹

즉, external인 @tanstack/react-query가 internal import 뒤에 와서 순서 위반이 발생한 것이다.

해결

외부 패키지 import를 로컬 import 위로 올리고, 그룹 사이에 빈 줄을 넣었다.

import { useForm } from 'react-hook-form'

import { useQueryClient } from '@tanstack/react-query' // external 그룹

import PictureListTabContent from './_components/tabs/PictureListTabContent' // internal 그룹

정리

• 로컬에서 안 잡히는 이유: IDE에서 ESLint가 실시간으로 잡아주지 않거나, next build 단계에서만 lint가 실행되는 경우가 있다.
• @tanstack/react-query처럼 @로 시작하는 npm 패키지는 프로젝트 alias(@/, @core/)와 헷갈리기 쉽다. npm 패키지 = external, 프로젝트 경로 alias = internal으로 구분하면 된다.
• Vercel 배포 전에 npm run build를 로컬에서 한번 돌려보는 습관을 들이면 이런 실수를 미리 잡을 수 있다.