사내 SCSS 모듈화 진행기 - 배포 방식 고민부터 Git 방식 선택까지

• 배경

기존 프로젝트들에서 SCSS 코드가 중복되고 일관성이 부족한 문제가 있었습니다. 각 프로젝트마다 비슷한 스타일 코드를 반복해서 작성하고 있었고, 디자인 시스템의 변경사항을 여러 프로젝트에 적용하는 것이 번거로웠습니다.

• 목표

공통 SCSS 컴포넌트를 모듈화하여 재사용성 증대
디자인 시스템의 일관성 유지
프로젝트 간 스타일 코드 중복 제거
유지보수성 향상
퍼블리싱 팀도 쉽게 사용할 수 있는 배포 방식 구축

• 배포 방식 고민 과정

SCSS 모듈화를 진행하면서 가장 고민이 되었던 부분은 어떤 방식으로 배포하고 관리할 것인가? 였습니다. 개발팀뿐만 아니라 퍼블리싱 팀도 쉽게 사용할 수 있어야 했고, 동시에 보안과 관리 효율성도 고려해야 했습니다.

1. 사내 NPM Registry (Verdaccio) 방식

첫 번째로 고려한 방식은 Verdaccio를 사용한 사내 NPM Registry 구축이었습니다.

장점

npm 생태계와 완벽 호환
패키지 버전 관리 자동화
의존성 관리 용이
표준적인 배포 방식

단점

별도 서버 운영 필요
초기 설정 복잡도
서버 관리 비용
퍼블리싱 팀의 npm 명령어 학습 필요

# Verdaccio 설치 및 실행
npm install -g verdaccio
verdaccio
 
# 사내 registry 설정
npm config set @your-company:registry http://localhost:4873/
npm publish --registry=http://localhost:4873/

2. 웹 개시 방식 (CDN/CloudFront)

두 번째로 검토한 방식은 웹 개시 방식으로, CloudFront나 일반 웹 서버를 통해 SCSS 파일을 직접 제공하는 방식이었습니다.

장점

간단한 URL로 접근 가능
캐싱 최적화
별도 도구 설치 불필요
브라우저에서 직접 확인 가능

단점

치명적 한계: @mixin 사용 불가
컴파일 시 경로 해석 문제
버전 관리 복잡
의존성 관리 어려움

// 웹 개시 방식 - 불가능한 예시
@import 'https://cdn.your-company.com/scss/mixins.scss'; // 작동하지 않음

이 방식은 SCSS가 모두 CSS로 빌드되어 배포되기 때문에 @mixin 방식을 사용할 수 없다는 치명적인 단점 때문에 초기에 배제되었습니다.

3. Git 방식 (최종 선택)

세 번째로 고려하고 최종 선택한 방식은 Git Repository를 직접 활용하는 방식입니다.

선택 이유

간편성: npm의 Git 직접 설치 기능 활용
보안성: AWS CodeCommit을 통한 사내 저장소 관리
접근성: 퍼블리싱 팀도 쉽게 사용 가능
유연성: 브랜치, 태그를 통한 버전 관리
비용 효율성: 별도 서버 운영 불필요

• Git 방식 선택의 결정적 요인

퍼블리싱 팀 접근성 고려

퍼블리싱 팀이 기존에 사용하던 방식과 크게 다르지 않아야 했습니다. Git 방식은 단순히 @use 문의 경로만 수정하면 되는 수준이었고, 새로운 도구나 개념을 학습할 필요가 없었습니다.

// 기존 방식
@use "../abstract/abstract" as *;
 
// 변경된 방식
@use "scss/abstract/abstract" as *;

WAS 소스 수정 사항

기존 빌드 시스템에서 node_modules 경로를 인식하도록 build, gulp 과정에 includePaths: ['node_modules']를 추가했습니다.

실제 테스트 결과

팀 내 테스트를 통해 다음을 확인했습니다:

기존 구조 유지: 기존 소스의 구조 변경 없이 경로만 수정
선택적 import: 기존처럼 common만 또는 abstract만 import도 가능
간편한 업데이트: npm update scss로 간단한 버전 업데이트
별도 관리 불필요: 추가적인 서버 운영이나 관리 작업 없음
엔터프라이즈 호환: 망 분리 환경에서도 Git 파일을 압축하여 배포 가능

버전 관리 전략 검증

다양한 Git 참조 방식을 테스트한 결과:

// 태그 방식 (동작하지 않음)
"scss": "git+https://git-codecommit.your-region.amazonaws.com/scss#v1.0.0"
 
// 브랜치 방식 (✅ 선택됨)
"scss": "git+https://git-codecommit.your-region.amazonaws.com/scss#develop"
 
// 커밋 해시 방식 (테스트 예정)
"scss": "git+https://git-codecommit.your-region.amazonaws.com/scss#a1b2c3d"

최종적으로 브랜치를 통한 버전 관리 방식을 채택했습니다.

• 모듈화 진행 과정

1. 공통 컴포넌트 분석

기존 프로젝트들을 분석하여 자주 사용되는 스타일 패턴들을 파악했습니다:

버튼 컴포넌트
폼 요소 스타일
레이아웃 유틸리티
색상 팔레트
타이포그래피
아이콘 세트

2. SCSS 모듈 구조 설계

실제 프로젝트 구조를 기반으로 다음과 같이 설계했습니다:

scss/
├── package.json
├── abstract/          # 변수, 믹스인, 함수 및 기본 스타일
│   ├── _color.scss
│   ├── _fontStyle.scss
│   └── _commonMixIn.scss
├── common/           # 일반적인 UI 컴포넌트 및 범용 유틸리티
│   ├── _baseModule.scss
│   └── _popup.scss
├── iconSet/          # 아이콘 관리
│   ├── _iconSet.scss
│   ├── svg-form/
│   └── svg-ic/
└── README.md

3. Git 저장소 설정

AWS CodeCommit을 사용하여 사내 SCSS 모듈을 관리하기로 결정했습니다.

# 저장소 생성
aws codecommit create-repository --repository-name scss --repository-description "사내 SCSS 모듈화 프로젝트"
 
# 초기 설정
git init
git add .
git commit -m "Initial commit: SCSS 모듈화 프로젝트 시작"
git remote add origin https://git-codecommit.your-region.amazonaws.com/scss
git push -u origin main

4. 패키지 설정

package.json 파일을 통해 모듈의 메타데이터와 의존성을 관리합니다:

{
  "name": "scss",
  "version": "1.0.0",
  "description": "사내 SCSS 모듈화 프로젝트",
  "main": "abstract/abstract.scss",
  "style": "abstract/abstract.scss",
  "scripts": {
    "build-css": "sass --load-path node_modules main.scss output.css"
  },
  "keywords": ["scss", "css", "design-system"],
  "author": "your-team",
  "license": "MIT"
}

• 사용 방법

설치

프로젝트에서 다음 명령어로 SCSS 모듈을 설치합니다:

npm i git+https://git-codecommit.your-region.amazonaws.com/scss

사용 예시

// 기존 방식
@use "../abstract/abstract" as *;
 
// 새로운 방식
@use "scss/abstract/abstract" as *;
 
// 선택적 import도 가능
@use "scss/common/baseModule" as *;
@use "scss/iconSet/iconSet" as *;

소스 최신화 방법

# 패키지 버전 업데이트
npm update scss
 
# 또는 특정 브랜치로 업데이트
npm install git+https://git-codecommit.your-region.amazonaws.com/scss#develop

• 배포 방식별 비교 결과

방식	장점	단점	퍼블리싱 팀 접근성	선택 여부
Verdaccio	npm 생태계 호환, 표준적 방식	서버 운영 필요, 학습 비용	보통	❌
웹 개시	간단한 URL 접근	Mixin 사용 불가	좋음	❌
Git 방식	간편성, 보안성, 비용 효율성	Git 이해 필요	매우 좋음	✅

• 도입 효과

1. 개발 효율성 증대

재사용 가능한 컴포넌트로 개발 시간 30% 단축
검증된 스타일 패턴 사용으로 품질 향상

2. 일관된 디자인 시스템

모든 프로젝트에서 동일한 스타일 가이드 적용
브랜드 일관성 유지

3. 유지보수성 향상

중앙 집중식 관리로 업데이트 용이
버전 관리를 통한 안정성 확보

4. 팀 협업 개선

퍼블리싱 팀과 개발팀 간 원활한 협업
별도 학습 없이 기존 방식 활용

5. 보안성 강화

사내 CodeCommit 사용으로 외부 노출 위험 최소화
접근 권한 관리 가능

• 향후 계획

컴포넌트 확장: 기능별 추가 UI 컴포넌트들을 모듈로 분리
문서화: 각 컴포넌트의 사용법과 예시 문서 작성 (완)
팀 교육: 사용 방법 가이드 배포 및 교육 진행 (완)
성능 최적화: 불필요한 코드 제거 및 최적화
디자인 토큰: 더 체계적인 디자인 시스템 구축

• 결론

SCSS 모듈화를 통해 프로젝트 간 스타일 코드의 일관성과 재사용성을 크게 향상시킬 수 있었습니다. Git을 통한 버전 관리와 npm 패키지 형태의 배포로 효율적인 관리가 가능해졌습니다.

특히 npm i git+https://git-codecommit.your-region.amazonaws.com/scss 명령어 하나로 간단하게 설치할 수 있어 팀 내 도입 장벽이 낮아졌습니다.

앞으로도 지속적인 개선과 확장을 통해 더욱 완성도 높은 디자인 시스템을 구축해 나갈 예정입니다.

Yong's Park

Recent

배포 방식 비교

Verdaccio Docker 서버 이전 후기 - Git 방식에서 서버 방식으로의 회귀