StyleX + ESLint: 베스트 프랙티스가 서로 충돌할 때

Source: Dev.to

설정: 모든 규칙 따르기

Vite 설정

v0.15.0에서 권장되는 enableMediaQueryOrder: true 사용:

// vite.config.js
styleXUnplugin.vite({
  enableMediaQueryOrder: true,
})

ESLint 설정

권장되는 StyleX 플러그인 규칙 사용:

// eslint.config.mjs
rules: {
  "@stylexjs/valid-styles": "error",
  "@stylexjs/sort-keys": "warn", // Keep styles organized!
}

반응형 스타일

올바른 캐스케이드 순서를 가진 인라인 문자열 사용:

const styles = stylex.create({
  container: {
    padding: {
      default: "2rem",
      "@media (max-width: 768px)": "1.5rem", // tablet
      "@media (max-width: 640px)": "1rem",   // mobile
    },
  },
});

큰 브레이크포인트를 먼저 배치하고, 작은 브레이크포인트가 CSS 캐스케이드에서 이를 덮어쓸 수 있도록 합니다.

문제: 유용한 ESLint 경고

npm run lint 실행 결과:

warning  StyleX property key "@media (max-width: 640px)"
         should be above "@media (max-width: 768px)"

npm run lint -- --fix를 실행하면 ESLint가 코드를 “수정”합니다:

padding: {
  default: "2rem",
  "@media (max-width: 640px)": "1rem", // now first (640)
}

“이제 원하는 순서대로 겹치는 미디어 쿼리를 작성할 수 있으며, 컴파일러가 이를 재작성하여 나중에 정의된 쿼리가 앞선 쿼리보다 우선하도록 합니다.”
— StyleX v0.15.0 Release Notes

이 기능은 소스 순서에 의존하지만, StyleX ESLint 플러그인의 sort-keys 규칙이 그 순서를 깨뜨립니다. 두 도구가 충돌합니다.

해결 방법

문제가 upstream에서 해결될 때까지, 반응형 속성을 ESLint 비활성화 블록으로 감싸세요:

const styles = stylex.create({
  container: {
    /* eslint-disable @stylexjs/sort-keys -- max-width cascade: larger breakpoints first */
    padding: {
      default: "2rem",
      "@media (max-width: 768px)": "1.5rem",
      "@media (max-width: 640px)": "1rem",
    },
    /* eslint-enable @stylexjs/sort-keys */
  },
});

블록 주석은 sort-keys 규칙이 중첩된 미디어 쿼리를 재정렬하는 것을 방지하면서, 다른 곳에서는 규칙이 정상적으로 작동하도록 합니다.

주요 요점

• --fix를 무조건 신뢰하지 마세요 – 자동 수정은 린터가 이해하지 못하는 의미적 순서를 깨뜨릴 수 있습니다.
• 린팅 후 반응형 스타일을 테스트하세요 – eslint --fix를 실행한 뒤에도 브레이크포인트가 정상 작동하는지 확인합니다.
• 예외를 문서화하세요 – -- max-width cascade: larger breakpoints first와 같은 주석은 규칙을 비활성화한 이유를 설명합니다.
• upstream 이슈를 제기하세요 – 문제를 보고하면 유지보수자가 규칙을 개선하는 데 도움이 됩니다.

우리가 필요한 수정

@stylexjs/sort-keys 규칙은 다음과 같이 동작해야 합니다:

1. 미디어 쿼리 객체 내부에서는 정렬을 건너뛰기 – @media 키를 감지하고 작성자의 순서를 유지합니다.
2. 특이도에 따라 정렬 – max-width 쿼리는 내림차순, min-width 쿼리는 오름차순이어야 함을 인식합니다.
3. 구성 옵션 제공 – 사용자가 특정 패턴에 대해 정렬을 비활성화할 수 있도록 합니다.

이러한 개선이 적용될 때까지, ESLint 비활성화 주석을 준비해 두세요.

참고:

• GitHub 이슈: #1416 – @stylexjs/sort-keys breaks max‑width media query cascade