콘텐츠로 이동

린트와 코딩 스타일

화면 코드를 바꾸면 web/에서 npm run check를 실행해요. 다섯 가지 검사를 차례로 돌리고, 하나라도 실패하면 거기서 멈춰요.

web/package.json
"check": "npm run lint:ui && npm run lint && npm run knip && npm test && npm run build",
  1. lint:ui: 화면 규칙과 층 규칙을 검사해요(node scripts/check-ui.mjs).
  2. lint: ESLint로 일반 린트를 돌려요(eslint .).
  3. knip: 안 쓰는 파일, 내보내기, 패키지를 찾아요.
  4. test: web/scripts/의 *.test.mjs를 Node 테스트 러너로 돌려요(node --test scripts/*.test.mjs).
  5. build: 타입을 검사하고 빌드해요(tsc --noEmit && vite build).

ESLint로 표현하기 어려운 화면 규칙은 web/scripts/check-ui.mjs가 맡아요. 주석 안의 글은 검사하지 않고 코드만 봐요.

범위 막는 것
모든 파일 아래 층이 위 층을 가져오기, 같은 층의 다른 슬라이스를 가져오기, pages에서 옆 주소의 코드를 가져오기, lucide-react 가져오기, @/shared/lib/utils 가져오기
화면 파일 팔레트 색 클래스(bg-red-500 등), space-x-*·space-y-*, dark:로 색 덮어쓰기, 인라인 style 속성, !important, 색 값 직접 쓰기, *.module.css 가져오기

키트 부품(shared/ui/kit), 본문 편집기, 테마(app/theme)는 원본의 규칙을 따르므로 화면 파일 규칙에서 빠져요. 층 규칙은 모든 파일에 걸려요. 인라인 style이 데이터 값이라 꼭 필요하면, 같은 줄이나 윗줄에 // check-ui: allow-style <사유>를 적어요.

web/eslint.config.js는 ESLint와 typescript-eslint의 권장 규칙 위에 몇 가지를 더해요. 생성한 파일(routeTree.gen.ts, schema.d.ts)과 dist는 검사하지 않아요.

web/eslint.config.js
{
files: ['src/**/*.{ts,tsx}'],
languageOptions: {
globals: globals.browser,
parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
},
plugins: { 'react-hooks': reactHooks },
rules: {
// 훅 규칙만 쓴다. React Compiler용 규칙(refs · set-state-in-effect …)은 컴파일러를 쓰지 않아 켜지 않는다.
'react-hooks/rules-of-hooks': 'error',
'react-hooks/exhaustive-deps': 'warn',
// 사용 중단으로 표시된 API를 부르면 알린다(라이브러리가 다음 판에서 지울 것).
'@typescript-eslint/no-deprecated': 'error',
// 구조 없는 문서 JSON(ProseMirror 노드 · 속성)을 다루는 곳에 남아 있다. 새로 쓰지 않도록 알린다.
'@typescript-eslint/no-explicit-any': 'warn',
},
},
규칙 수준 뜻
unused-imports/no-unused-imports 오류 안 쓰는 import. eslint --fix가 지워요
unused-imports/no-unused-vars 오류 안 쓰는 변수. 일부러 쓰지 않는 값은 이름을 _로 시작해요
react-hooks/rules-of-hooks 오류 훅을 조건문이나 반복문 안에서 부르기
react-hooks/exhaustive-deps 경고 Effect·메모의 의존 목록에서 빠진 값
@typescript-eslint/no-deprecated 오류 사용 중단으로 표시된 API 부르기. 타입 정보를 읽어 검사해요
@typescript-eslint/no-explicit-any 경고 any 타입

web/knip.config.ts는 src/shared/ui 아래 파일을 모두 진입점으로 봐요. 키트 부품은 부품 전체가 공개 API라서, 아직 쓰지 않는 하위 부품도 남겨 두기 때문이에요. 같은 파일 안에서만 쓰는 내보내기는 알리지 않아요.

검사기가 막지 않지만 지키는 것이에요.

  • 컴포넌트는 PascalCase 파일 하나에 하나씩 두고, 페이지 컴포넌트에는 Page를 붙여요. 훅은 use로 시작하고, 일반 도구와 설정 파일은 kebab-case예요.
  • 다른 값에서 계산되는 값을 state에 복사해 Effect로 맞추지 않아요. 사용자 명령은 이벤트 핸들러나 mutation이 처리하고, Effect는 외부 구독과 동기화에만 쓰고 해제해요.
  • useMemo·useCallback은 측정한 비용이 있거나 참조가 같아야 하는 경계에만 써요.
  • StrictMode에서 드러난 수명주기 문제를 “한 번만 실행” 플래그로 숨기지 않아요.