1. VOIM 익스텐션 소개

• 글자 크기 및 굵기 조정
• 웹사이트의 고대비 테마 설정
• 포커스 트랩 및 키보드 탐색 등 접근성 강화 기능
• 쿠팡 상세 정보 및 장바구니 요약 제공

2. 리팩토링을 하게 된 배경

---

구조적 리스크 발견

• UI와 상태 관리, 저장 로직이 혼재되어 테스트/재사용 어려움
• 페이지 단위로만 나뉜 폴더 구조 → 역할 파악이 어렵고 신규 개발자 온보딩에 시간 소요
• 포커스 트랩 등 접근성 기능의 일관성 부족 → 일부 설정이 UI에 반영되지 않음
• 테스트 코드/문서화 부족 → 기능 추가 시 리스크 증가

---

리팩토링이 꼭 필요한 이유

---

3. 기술적 문제와 리팩토링 방향

---

❌ 현재 구조의 기술적 한계

1) 역할과 관심사의 혼재

• UI 컴포넌트 내부에 상태 관리, 저장소 연동, 스타일링 로직이 모두 혼합
• 가독성과 재사용성 저하, 사이드 이펙트 발생 가능성 증가

2) 비효율적인 디렉토리 구조

• components, content 등 위치 기반 폴더 분류
• 기능/역할 단위가 아닌 구성으로 코드 파악 및 재사용 어려움

3) 전역 상태 관리의 부재

• chrome.storage를 각 컴포넌트가 직접 호출 → 비동기/불안정 상태 발생
• 설정 변경이 UI에 즉시 반영되지 않거나, 일부 컴포넌트만 반영됨

4) 테스트 및 문서화 부족

• 주요 기능에 대한 테스트 코드 없음, 수동 테스트에 의존
• 유지보수 시 오류 가능성 높고, 신규 개발자 온보딩 어려움

---

✅ 리팩토링 방향 및 해결 목표

1) 관심사 분리 및 역할 기반 구조 재설계

• UI, 상태 관리, 로직, 스타일링을 모듈화하고 책임을 분리
• container와 presenter 계층 구분으로 컴포넌트 재사용성 강화

2) 역할 기반 디렉토리 구조로 재편

• 전체 코드를 content, background, iframe, service 영역으로 구분
• FSD(Feature-Sliced Design) 패턴 적용 → 명확한 기능 책임 분배

3) 안정적이고 일관된 상태 관리 도입

• 전역 상태를 상태 관리 라이브러리 or Context API로 통합 관리
• chrome.storage와의 동기화를 추상화하여 일관성 확보

4) 테스트 기반 개발 환경 구축

• 주요 로직 및 UI 컴포넌트에 대해 유닛 테스트, 스냅샷 테스트 도입
• CI 환경에서 자동 검증 가능하도록 설정하여 안정적인 코드 배포 가능

---

이번 리팩토링은 단순한 기능 추가가 아닌,

VOIM이 '정보 접근성을 높이는 도구'로서 장기적으로 신뢰받을 수 있도록 하는 기술적 기반 마련입니다.

4. 해결계획

1) 디렉토리 구조 개편

• 전체 코드를 크게 컨텐츠(Content), 백그라운드(Background), 아이프레임(Iframe), 서비스(Service) 4개 영역으로 분리
• 컨텐츠: 웹페이지에 주입되는 컨텐츠 스크립트들을 담당
• 백그라운드: 크롬 익스텐션 백그라운드 스크립트 코드 관리
• 아이프레임: 컨텐츠 스크립트에서 삽입하는 아이프레임 루트를 기준으로 한 React 앱 구성
  • FSD(Feature-Sliced Design) 패턴 적용, container와 presenter 계층으로 명확한 역할 분리
• 서비스: 백그라운드와 컨텐츠 양쪽에서 공통으로 사용하는 기능들을 싱글톤 패턴 기반의 서비스 클래스로 통합 관리

/src
│
├── background/         # 크롬 백그라운드 스크립트
│   └── index.ts
│
├── content/            # 웹페이지에 삽입되는 스크립트
│   └── observer.ts
│
├── iframe/             # 실제 사용자 UI가 들어가는 React 앱 (아이프레임 기반)
│   ├── app/            # 앱 전역 설정 (라우팅, 테마 등)
│   ├── entities/       # 상태 + 도메인 로직 (예: Setting, User)
│   ├── features/       # 사용자 기능 단위 (예: FontControl, ContrastMode)
│   ├── shared/         # 공통 UI 컴포넌트, util 함수, hooks
│   ├── widgets/        # 조합된 UI 덩어리 (예: ControlPanel, Toolbar)
│   └── pages/          # 루트 페이지 (예: IframeRoot.tsx)
│
├── service/            # content/background에서 공통 사용하는 기능 (Storage, Messaging 등)
│   ├── storageService.ts
│   ├── messagingService.ts
│   └── accessibilityService.ts
│
├── styles/             # 전역 스타일 및 Tailwind 설정
│
├── types/              # 글로벌 타입 정의
│
└── manifest.json       # 크롬 익스텐션 설정 파일

iframe/
├── app/
│   ├── App.tsx
│   └── router.ts
│
├── entities/
│   └── setting/
│       ├── model/        # Zustand/Context 등 상태
│       ├── service/      # setting 관련 추상화된 동작
│       └── types.ts
│
├── features/
│   └── font-control/
│       ├── ui/           # <FontSizeSelector />
│       └── model/        # 관련 로직
│
├── widgets/
│   └── ControlPanel/
│       ├── index.tsx
│       └── style.css
│
├── shared/
│   ├── ui/               # Button, Slider 등
│   ├── lib/              # chromeAPI wrapper 등
│   └── hooks/

2) 상태 관리 및 서비스 통합

• 공통 기능(데이터 저장, 메시지 전달 등)을 서비스 클래스로 캡슐화하여 중복 코드 제거 및 유지보수 편의성 증대
• React 상태 관리는 컨테이너 컴포넌트 내에서 관리하며, 프레젠터 컴포넌트는 UI 렌더링에 집중하도록 역할 분리

3) UI 컴포넌트 구조 개선

• FSD 패턴을 활용해 계층별 책임과 관심사를 명확히 분리
• 재사용 가능한 UI 컴포넌트와 상태 관리 로직을 분리하여 확장성 강화

4) 개발 환경 및 코드 품질 향상

• TypeScript 적용 및 ESLint, Prettier 설정 강화로 일관된 코드 스타일 유지
• 테스트 커버리지 확대로 주요 컴포넌트 및 서비스 기능에 대한 안정성 확보

세부 계획

1. 기존 구조 및 코드 문제점 목록화
2. 역할 기반 디렉토리 구조 초안 작성
3. 공통 기능을 서비스 클래스로 추출
4. 상태 관리 체계 수립 (예: Context or 상태 라이브러리)
5. 각 영역(content, background, iframe)별 리팩토링 착수
6. 테스트 및 문서화 범위 정의 및 도입
7. 빌드, 배포, 모니터링 체계 정비

5. 마무리

💬 같이 보면 좋은 글

• 📦 React 기반 Chrome Extension 구조 설계 가이드
• 📁 FSD(Feature-Sliced Design) 패턴 요약
• ♿ 웹 접근성 개선 사례: 실무에서 만난 A11y 문제들