Steiger 사용법 및 실제 구성 가이드

본 문서는 as 프로젝트에서 FSD(Feature Sliced Design) 아키텍처 의존성 및 구조 검증을 위해 사용되는 Steiger 린터의 실제 구성과 사용법을 다룹니다.

1. Steiger 개요

Steiger는 FSD 아키텍처의 철학(단방향 의존성 흐름, Public API 접근 등)이 코드베이스에서 물리적으로 올바르게 지켜지고 있는지를 검증하는 FSD 전용 정적 분석 린터입니다.
일반적인 코드 포맷터나 문법 린터(ESLint, Prettier)와 달리, 파일 시스템의 폴더 구조와 파일 간의 import 관계를 추적하여 아키텍처 위반 사항을 진단합니다.

2. 프로젝트 내 실제 구성 및 실행 방법

① 실행 스크립트 정의

apps/as/package.json 파일에 다음과 같이 린트 스크립트가 내장되어 있습니다.

"scripts": {
  "lint:fsd": "steiger ."
}

② 린트 실행 명령어

터미널에서 아래 명령을 실행하여 as 애플리케이션의 FSD 구조를 검사합니다.

# 모노레포 루트 디렉토리 기준
pnpm --filter as lint:fsd

# 또는 apps/as 디렉토리 기준
pnpm run lint:fsd

3. Steiger의 기본 동작 원리

별도의 설정 파일(steiger.config.ts)이 프로젝트에 생성되어 있지 않은 경우, Steiger는 아래와 같이 동작합니다.

기본 FSD 규칙셋(Standard Ruleset) 자동 채택: @feature-sliced/steiger-plugin의 권장(recommended) 규칙들을 메모리에 로드하여 적용합니다.
프로젝트 루트 탐색: 실행 인자로 전달된 경로(여기서는 현재 경로인 .) 아래의 모든 디렉토리를 순회하며 src/ 내부의 레이어 구조를 감지합니다.
의존성 트리 분석: shared ➔ entities ➔ features ➔ widgets ➔ pages ➔ app 순으로 올라가는 레이어 위계를 확인하여, 역참조(예: entities가 features를 가져옴)가 발생하는 위치를 찾아냅니다.

4. Steiger가 감시하는 주요 FSD 아키텍처 규칙

Steiger가 실시간으로 코드를 분석하며 잡아내는 대표적인 아키텍처 오류들은 다음과 같습니다.

규칙명 (Rule ID)	설명 및 예시
`fsd/no-public-api-bypass`	슬라이스의 Public API(`index.ts`)를 통하지 않고 내부 파일 경로를 직접 임포트할 때 감지합니다. ➔ 오류: `import { Form } from '@/features/auth/ui/form'` ➔ 해결: `import { Form } from '@/features/auth'`
`fsd/no-forbidden-imports`	상위 레이어가 하위 레이어의 모듈을 가져와 상호 의존하거나 순환 참조가 발생할 때 감지합니다. ➔ 오류: `entities/user` 슬라이스 안에서 `widgets/header`를 참조하는 경우
`fsd/no-segmentless-slices`	슬라이스 디렉토리 바로 아래에 세그먼트(`ui`, `model`, `api` 등) 없이 코드 파일이 직접 위치할 때 감지합니다.

5. 알려진 팁 및 문제 해결 (tsconfck 관련 오류)

일부 환경에서 steiger .를 실행할 때, 내부 컴파일러 설정 검사기인 tsconfck 라이브러리가 .eslintrc.json과 같은 설정 파일 내의 "extends": "next/core-web-vitals" 속성을 TypeScript 설정 파일의 extends로 오인하여 모듈 해석 오류(MODULE_NOT_FOUND)를 유발하는 경우가 발생할 수 있습니다.

이와 같은 환경적 이슈가 발생할 경우 아래의 우회법을 참고하십시오.

빌드 파이프라인에서 파일 범위 한정: Steiger 검사 시 설정 파일들이 불필요하게 스캔 대상에 포함되지 않도록 빌드 린트 파이프라인 설정을 조정하거나, 대상 소스 코드 경로(src)를 명확하게 지정하여 탐색 범위를 제한합니다.
steiger 설정 파일 커스텀: 프로젝트의 필요에 따라 steiger.config.ts 파일과 해당 플러그인을 프로젝트 devDependencies에 명시적으로 추가하여 ignores 옵션으로 .eslintrc.json 등 설정 파싱 에러를 유발하는 대상을 제외하도록 설정하여 운영합니다.

4.1 KiB Raw Blame History