A Minimal Yet Scalable React + TypeScript + styled-components Architecture
카테고리
프로그래밍/소프트웨어 개발
서브카테고리
웹 개발
대상자
- *React + TypeScript 개발자**
- 난이도: 중급 이상 (TypeScript 및 styled-components 경험 필요)
- 도움: 설계 시스템과 컴포넌트 분리, 타입 안전한 테마 관리, 확장 가능한 프로젝트 구조 구축 방법 제공
핵심 요약
theme.ts
파일을 통해 모든 디자인 요소 (색상, 간격)의 단일 소스 진실을 관리합니다.styled-components
와 TypeScript의 연동으로 테마 키 타입 안전성 확보 (DefaultTheme
인터페이스 활용).- 컴포넌트와 페이지 분리 (
components/
vspages/
)로 업무 로직과 스타일 분리를 실현.
섹션별 세부 요약
1. 프로젝트 구조 설계
theme.ts
: 색상, 간격 등 디자인 시스템의 핵심 값을 정의 (예:primary: "#1e88e5"
).GlobalStyles.ts
: CSS 리셋 및theme
기반의 전역 스타일 적용 (body
의background
및color
설정).components/
: 재사용 가능한 컴포넌트 (Button
,Card
)로 구성,styled-components
의 타입 안전한 테마 사용.
2. 컴포넌트 설계 패턴
Button.tsx
:variant
프로퍼티를 통해 테마 기반 색상 조정 (primary
/secondary
),theme.spacing()
함수로 간격 적용.Card.tsx
:theme.spacing(6)
을 활용한 패딩 설정,box-shadow
등 디자인 요소 포함.- 타입 안전성 강화:
ButtonProps
타입 정의로variant
값의 유효성 검증.
3. 테마 적용 및 공급
App.tsx
:ThemeProvider
를 통해theme
객체를 전역에 공급,GlobalStyles
적용.index.tsx
: React 앱의 진입점으로createRoot
를 통해 렌더링.- 확장성:
feature-first
폴더 구조로 전환 가능 (기존 컴포넌트/테마 테스트 영향 없음).
4. 추가 기능 및 최적화
- Storybook: 디자인 시스템 문서화 도구로 사용 가능.
- 다크 모드:
theme.dark.ts
생성 및 React Context로 토글 가능. - 성능 최적화:
babel-plugin-styled-components
사용 시 불필요 코드 제거 및 디스플레이 이름 개선.
결론
- 핵심 팁:
theme.ts
를 통해 디자인 일관성 유지,styled-components
+ TypeScript로 타입 안전성 확보. - 프로젝트 적용: Vite/CRA 레포에 코드 복사 후 즉시 실행 가능.
- 확장성: 테마/컴포넌트 재사용 가능,
feature-first
폴더 구조로의 전환 용이.