Vite + handlebars.js로 마크업 작업환경 및 프로세스 개선하기

Vite + handlebars.js로 마크업 작업환경 및 프로세스 개선하기

목차

• 개선 배경
• 기존 프로세스의 문제점
• 개선 방향
  • Vite
  • handlebars.js
  • SASS(SCSS)
  • 페이지 단위 → 컴포넌트 단위 구조 전환
  • Build (Rollup.js)
  • Cloudflare Pages를 활용한 검수 프로세스
• 성능 비교
• 확인 필요사항
• 요약

개선 배경

• 팀과 협업사 간 마크업 협업 과정에서 반복적으로 발생하는 이슈와 비효율을 개선하고, 앞으로의 작업 방향성을 제시하기 위해 정리함
• 라이브러리·패키지의 세부 문법이나 사용 가이드보다는, 왜 이 도구들을 도입해야 하는가에 초점을 맞춤

기존 프로세스의 문제점

• 기존 UI 마크업 작업 흐름은 다음과 같았음

작업 착수 → design repo 선 작업 → 1차 작업자 확인
→ 서비스 repo에 반영 → dev 배포 → 2차 기획자 검수
→ Real 배포 → 디자인 검수

• 이 구조에서 누적된 문제점
  • 디자인용 저장소와 실서비스 저장소, 두 곳에서 동일한 페이지를 이중으로 작업해야 함
  • 두 저장소의 CSS가 동기화되지 않아 dev/real 환경 간 불일치가 지속적으로 발생 (작업 속도 지연 + 불필요 비용)
  • HTML/CSS가 전통적인 페이지 단위 구조로 설계되어 있어 복사·붙여넣기가 반복되고, 재사용이 어려운 CSS 구조 탓에 리소스 용량이 계속 무거워짐
  • 내부망이 분리된 환경 특성상 검수를 위해 Git 커밋 & MR → dev 배포 → 확인/수정 3단계를 매번 거쳐야 해서, 수정이 발생할 때마다 이 사이클을 반복해야 함

개선 방향

1) Vite

• 차세대 프론트엔드 번들링 도구로, 빌드와 개발 서버 구동 속도가 매우 빠름
• 내부적으로 사용하는 Go 기반 esbuild는 기존 Webpack, Parcel 대비 10~100배 빠른 속도를 제공함
• 번들링 시 Rollup 기반의 빌드 커맨드를 활용할 수 있어 정적 리소스 배포에 적합한 사전 설정을 제공함

번들링(Bundling): 여러 파일, 주로 JS·CSS 파일을 하나로 결합하는 작업

• 기존 번들러는 소스 코드가 수정될 때마다 전체 파일을 다시 번들링해야 해서, 서비스가 커질수록 갱신 시간이 비례해서 늘어남
• 실측 비교 (동일 저장소 기준)
  • 기존 번들러: 이미지 리소스만 번들링하는데도 약 4.5초 소요
  • Vite: 전체 리소스를 번들링하고 서버를 구동하는데 약 0.3초 소요 (약 15배 개선)
• Vite는 ESM을 이용해 수정된 모듈만 교체하는 방식이라, 앱 사이즈가 커져도 HMR을 포함한 갱신 시간에 영향을 주지 않음

ESM(EcmaScript Modules): ES6에서 도입된, import/export로 모듈을 동적 로드하는 모듈 시스템

2) handlebars.js

• 자바스크립트 템플릿 엔진으로, Mustache(``) 문법 기반의 템플릿 인자를 통해 데이터를 동적으로 표현할 수 있음
• HTML + 브래킷 구성이라 디자이너와도 이해하기 쉬운 구조를 공유할 수 있어 협업에 유리함

3) SASS(SCSS)

• CSS 전처리기로, 복잡한 CSS 작업을 단순화하고 코드 재사용성·가독성을 높여 유지보수를 쉽게 해줌
• 브라우저가 직접 해석할 수 없기 때문에 전처리기 문법으로 작성 후 CSS로 컴파일해서 사용함

CSS Preprocessor: 중첩 선택자, 조건문·반복문, 다양한 단위 연산 등 표준 CSS보다 많은 기능을 제공해 작성·유지보수 시간을 줄여주는 도구

• 주요 장점
  • 변수, 조건문/반복문, Import(모듈화), Nesting, Mixin, Extend/Inheritance 등 CSS의 태생적 한계를 보완하는 기능 제공
  • 팀원 간 스킬 레벨 차이로 인한 구문 수준 편차를 평준화할 수 있음
  • 선택자 중첩으로 반복되는 부모 요소 선택자 작성을 줄일 수 있음

페이지 단위 → 컴포넌트 단위 구조 전환

기존 구조 (HTML + CSS, 페이지 단위)

• 공통 코드/컴포넌트를 별도로 구분할 수 없어 새 페이지마다 불필요한 복사·붙여넣기가 반복됨
• 유지보수·수정 시 관련된 모든 페이지를 각각 수정해야 해서 비용이 누적됨
• 용도·의미에 맞는 컴포넌트 단위가 아닌 페이지 단위 구조라, 페이지 수가 많아질수록 현재 사용 중인 UI를 파악하는 것 자체가 어려워짐

개선 구조 (handlebars.js + SCSS, 컴포넌트 단위)

• handlebars.js 템플릿으로 반복 구조를 효율적으로 관리하고, SCSS 변수·Nesting·Mixin으로 스타일을 모듈화함
• 페이지 단위가 아닌 컴포넌트 단위 설계로 재사용성을 높이고 불필요한 코드 생성을 방지함
• 초기 설계만 잘 갖추면 이후 유지보수에도 지속적으로 긍정적인 영향을 줌

5) Build (Rollup.js)

• 작은 코드 조각을 라이브러리나 애플리케이션처럼 더 크고 복잡한 단위로 컴파일하는 JS 모듈 번들러
• Vite가 지원하는 ES 모듈을 활용해 필요한 기능을 자유도 높게 결합할 수 있고, 최소한의 구성만 포함하기 때문에 더 가볍고 빠름

// vite.config.js (핵심 부분 발췌)
export default {
  build: {
    rollupOptions: {
      input: getHtmlFilesEntries(),
      output: {
        assetFileNames: (assetInfo) => {
          const extType = assetInfo.name.split('.')[1];
          if (/png|jpe?g|svg|gif|tiff|bmp|ico/i.test(extType)) {
            return `assets/[name][extname]`;
          } else if (/woff|woff2|ttf|eot/.test(extType)) {
            return `assets/[name][extname]`;
          }
          // 페이지 그룹별 CSS 파일 매핑
          const cssFiles = {
            default: 'assets/main[extname]',
          };
          return cssFiles[assetInfo.name.split('.')[0]] || cssFiles.default;
        },
        chunkFileNames: `assets/main.js`,
      },
    },
    outDir: '../dist',
  },
};

• CSS/JS를 각각 1개 파일로 압축·빌드해서 네트워크 요청 수와 파일 크기를 줄이고, 브라우저 캐싱을 최적화함
• 오배포 방지를 위해 package.json의 버전 값을 리소스 파일명에 반영하는 버저닝 관리 방식도 향후 도입을 검토 중

6) Cloudflare Pages를 활용한 검수 프로세스

• Git 저장소 연동 또는 CLI(Wrangler) 기반 직접 업로드로 정적 웹 애플리케이션을 배포할 수 있는 CDN 기반 호스팅 서비스

장점

• 내부망이 분리된 환경에서 매번 Git 커밋 & MR → dev 배포 → 확인 3단계를 반복하지 않고, 담당자가 작업 반영 사항을 바로 동일한 환경에서 검수 가능
• wrangler pages deploy 명령어 한 줄로 배포가 가능해 작업 담당자가 별도 학습 없이 바로 사용 가능
• 배포할 때마다 고유 Preview URL이 생성되고 이력이 남아, 이전 배포 산출물과 비교하거나 롤백하기 쉬움

보안 측면

• 기본적으로 HTTPS를 지원해 데이터 전송 구간의 안전은 확보됨
• Cloudflare Access를 연동하면 이메일 인증, SSO 등으로 배포된 페이지에 접근 제어를 걸 수 있어, 대외비성 검수 페이지도 인증된 담당자만 접근하도록 제한 가능
• 배포 이력과 접근 로그가 대시보드에 남아 별도 로깅 체계 없이도 확인이 가능함

검수 프로세스 예시

1. 작업 완료 후 마크업 산출물 빌드
2. 빌드된 산출물(dist) 확인
3. wrangler pages deploy ./dist --project-name=<프로젝트명> 명령어로 배포
4. 발급된 Preview URL을 담당자에게 전달해 화면 확인

성능 비교

확인 필요사항

• Node.js 및 npm 등 개발 환경 세팅 필요
• 협업사 담당자와 마크업 담당자 간 신규 도구에 대한 학습·커뮤니케이션 비용 발생
• 서비스 측과 UI 마크업 측이 공통으로 사용하는 JS 리소스(공통 함수, 플러그인 등)를 어떻게 분기할지 별도 검토 필요
• 사내망 프록시/방화벽 환경에서 Wrangler CLI가 Cloudflare API에 정상 접근 가능한지 사전 확인 필요 (필요 시 보안팀과 아웃바운드 정책 협의)

요약

• 기존 페이지 단위 HTML/CSS 구조는 이중 작업, CSS 비동기화, 무거운 리소스, 반복적인 검수 사이클이라는 네 가지 축의 비효율을 안고 있었음
• Vite + handlebars.js + SCSS 조합으로 컴포넌트 단위 구조로 전환하면서 번들링 속도(약 15배)와 페이지 로드 성능(DomContentLoaded 기준 약 63% 절감)을 동시에 개선함
• Cloudflare Pages를 검수 프로세스에 도입하면 내부망 분리 환경에서 반복되던 커밋 → 배포 → 확인의 3단계 사이클을 단축할 수 있고, Cloudflare Access를 함께 활용하면 접근 제어까지 보완할 수 있음
• 남은 과제는 개발 환경 세팅, 팀 간 학습 비용, 공통 리소스 분기 전략, 그리고 사내 보안 정책과의 정합성 확인임