[네이버 부스트캠프] 우리는 Vite, StoryBook, Tsdoc을 왜 사용할까?

들어가며

부스트캠프 그룹 프로젝트를 시작한 지 2주차가 지나가고 있습니다. 이번 기수는 특별히 주제를 기준으로 랜덤으로 팀이 구성되었습니다. 네이버 부스트캠프에서 추구하는 방향성이 웹 풀스택 개발자 양성이지만, 각자의 선호도와 희망 진로는 다를 수 있다는 점을 고려하며 프로젝트를 진행하고 있습니다. 이러한 상황에서 저는 팀의 유일한 프론트엔드 지망생으로 참여하게 되었습니다.

프로젝트를 준비하고 진행하면서 '어떤 방향으로 나아가야 더 큰 성장을 이룰 수 있을까'라는 고민을 계속했습니다. 단순한 기술적 도전을 넘어서, 다양한 측면에서의 성장을 고려하다 보니 기술 스택과 도구 선정에 특별히 많은 시간을 투자했습니다.

이번 프로젝트의 기술 스택과 개발 방향을 결정하는 데 있어 두 가지 상황을 중점적으로 고려했습니다. 첫 번째는 실제 회사 환경에서의 적용 가능성입니다. 이는 올해 상반기 인턴 경험에서 비롯된 것인데, 당시 사수 없이 혼자 개발을 진행하면서 이전 개발자들이 남긴 문서의 중요성을 절실히 느꼈습니다. 서비스 운영 기간에 비해 개발 문서가 부족하거나 주요 내용이 생략된 경우가 많았고, 이는 실무에서 겪을 수 있는 어려움을 미리 체험하는 계기가 되었습니다. 향후 제가 소속될 회사에서도 개발 인력이 충분한 팀에 합류할 수도 있고, 인턴 때처럼 혼자 프로젝트를 이끌어가야 할 수도 있습니다.

두 번째로 고려한 것은 백엔드 개발자분들과의 페어 프로그래밍 상황입니다. 팀원 중 두 분이 프론트엔드 개발에도 관심이 있으시지만 리액트 경험이 없으신 상태입니다. 이분들과 함께 리액트 개발 과정을 이해하고 컴포넌트 설계 시 고려사항을 공유하며 함께 배워나가는 과정이 되어야 하기에, 코드의 가독성과 유지보수성, 그리고 효율적인 협업을 위한 도구 선정이 더욱 중요해졌습니다.

어떤 기술 스택과 도구를 사용하지?

앞서 언급한 상황들을 고려하며 기획 회의를 진행하고 본격적으로 개발에 돌입하게 되면서 어느 정도 선택을 진행한 상황입니다. 저희는 현재 react + vite + typescript 환경에서 개발을 진행하고 거기에 스토리북, tsdoc(typedoc)을 적용하고 있습니다.

이런 기술 스택과 도구를 고려 하면서 왜 선택했는 지를 확실하게 정리하고 넘어가려고 합니다. 부스트캠프 마스터 클래스 시간에도 한 멘토님이 얘기 해주셨지만 “사용하는 도구에 대해서 사용 하는 이유, 선택한 이유를 확실하게 가져 가면 좋겠다” 라는 점을 해당 글을 통해 녹여 보려고 합니다.

Vite

Vite는 현대적인 웹 프로젝트를 위한 빌드 도구로, 빠른 개발 서버와 최적화된 빌드 과정을 제공합니다. 기존에 React의 경우 CRA라는 도구를 많이 사용했지만, Vite는 더 빠르고 효율적인 개발 환경을 제공합니다. Vite의 장점 중 하나는 빠른 서버 시작 시간인데, 이는 대규모 프로젝트에서 특히 유용합니다. 또한, Vite는 최신 웹 표준을 지원하며 다양한 프레임워크와 호환되어 유연성을 제공합니다.

주요 특징

• 빠른 서버 시작: 네이티브 ES 모듈을 활용하여 번들링 없이 즉시 시작

• 신속한 HMR(Hot Module Replacement): 변경 사항을 빠르게 반영

• 최적화된 빌드: Rollup을 사용하여 효율적인 프로덕션 빌드 생성

• 다양한 프레임워크 지원: React, Vue, Svelte 등 다양한 프레임워크와 호환

  이런 특징 들을 고려하는 동시에 React에서도 공식적으로 vite는 빌드 도구를 선택했다는 점을 참고해서 vite를 사용하려고 합니다. React에서도 vite를 선택한 이유는 아무래도 CRA에 비해서 빠른 개발 서버 시작과 모듈 단위의 HMR을 지원하기 때문일 것입니다. 이러한 특징들은 개발 생산성을 크게 향상시키며, 특히 우리 팀과 같이 다양한 백그라운드를 가진 개발자들이 협업하는 환경에서 매우 유용합니다. 또한, Vite의 간단한 설정과 직관적인 사용법은 프론트엔드 개발에 익숙하지 않은 팀원들도 쉽게 적응할 수 있게 해줍니다

Vite 선택 이유

• 개발 속도 향상: 빠른 서버 시작과 HMR으로 개발 생산성 증대
• 학습 곡선 완화: 간단한 설정으로 백엔드 개발자들의 프론트엔드 참여 용이
• 미래 지향적 기술: ES 모듈을 활용한 최신 개발 트렌드 반영
• 최적화된 성능: 효율적인 빌드 과정으로 애플리케이션 성능 개선

당연히 이런 기술을 선택하면 단점에 대해서도 고려를 해야 됩니다. 단점을 정리해보자면 아래와 같을 것 같습니다.

• 생태계 성숙도: Vite는 비교적 새로운 기술로, 일부 플러그인이나 도구가 아직 완전히 지원되지 않을 수 있습니다.
• 학습 곡선: 기존 웹팩 기반 도구에 익숙한 개발자들에게는 새로운 개념을 학습해야 할 수 있습니다.
• 대규모 프로젝트에서의 성능: 매우 큰 규모의 프로젝트에서는 초기 로딩 시간이 길어질 수 있습니다.

이런 단점이 있지만 아무래도 도구의 기본적인 속도가 많이 차이 난다는 점이 큰 것 같습니다. 단순 비교를 했을 때도 ESBuild를 사용해서 종속성을 미리 번들링 해주기 때문에 10~100배 정도 빠른 속도를 제공한다고 합니다.

대체제

Vite를 만약 안쓴다면 Webpack, parcel, turbopack 등을 고려해볼 수 있을 것 같습니다. 하지만 아무래도 Vite가 제공하는 빠른 개발 환경과 최신 웹 표준 지원이 우리 프로젝트의 요구사항과 잘 맞는다고 판단했습니다. Webpack은 여전히 강력하고 안정적인 도구이지만, 설정의 복잡성과 상대적으로 느린 빌드 시간이 단점으로 작용할 수 있습니다. Parcel은 설정이 거의 필요 없는 제로 구성 접근 방식을 제공하지만, 대규모 프로젝트에서의 유연성이 부족할 수 있어 우리의 선택에서 제외되었습니다.

Storybook

Storybook이란?

Storybook은 UI 컴포넌트를 독립적으로 개발하고 문서화할 수 있는 개발 환경을 제공하는 도구입니다. 특히 컴포넌트 주도 개발(CDD)을 실천하는 데 매우 효과적이며, 복잡한 UI 컴포넌트를 격리된 환경에서 개발하고 테스트할 수 있게 해줍니다. 최근 버전에서는 React, TypeScript와의 통합이 더욱 강화되어, 타입 안정성과 함께 풍부한 문서화 기능을 제공합니다.

주요 특징

• 격리된 개발 환경: 각 컴포넌트를 독립적으로 개발하고 테스트
• 인터랙티브 문서화: 컴포넌트의 다양한 상태와 사용법을 실시간으로 확인
• 자동화된 테스팅: 시각적 회귀 테스트와 접근성 테스트 지원
• 풍부한 애드온: 다양한 기능 확장을 위한 생태계 보유

Storybook 선택 이유

• 컴포넌트 개발 효율성: 독립적인 환경에서의 빠른 개발과 테스트
• 협업 강화: 백엔드 개발자들과의 효율적인 커뮤니케이션 도구로 활용
• 문서화 자동화: 컴포넌트 사용법과 상태 관리의 체계적인 문서화
• 품질 보장: 시각적 테스트를 통한 UI 일관성 유지

배포 및 공유

Storybook의 큰 장점 중 하나는 GitHub Actions를 통한 자동 배포가 가능하다는 점입니다. GitHub Pages를 활용하여 빌드된 Storybook을 호스팅할 수 있어, 팀원들이 언제든지 최신 컴포넌트 문서를 웹에서 확인할 수 있습니다. 이는 특히 원격으로 작업하는 상황이나, 백엔드 개발자들이 컴포넌트의 사용법을 참조해야 할 때 매우 유용합니다.

단점 고려사항

• 초기 설정 복잡성: 프로젝트에 맞는 적절한 설정과 애드온 선택 필요
• 빌드 시간 증가: 스토리 파일이 많아질수록 빌드 시간이 늘어날 수 있음
• 유지보수 부담: 컴포넌트 변경 시 관련 스토리도 함께 업데이트 필요

대체제

컴포넌트 문서화와 테스트를 위해 React Styleguidist, Docz 등을 고려할 수 있습니다. 하지만 Storybook의 풍부한 생태계와 커뮤니티 지원, 그리고 특히 백엔드 개발자들과의 협업 시 유용한 시각적 개발 환경을 제공한다는 점에서 우리 프로젝트에 가장 적합하다고 판단했습니다.

TSDoc

TSDoc이란?

TSDoc은 TypeScript 코드를 위한 표준화된 문서화 포맷으로, Microsoft에서 제안한 문서화 규약입니다. JSDoc의 기능을 TypeScript의 타입 시스템과 통합하여, 코드의 타입 정보와 문서를 함께 관리할 수 있게 해줍니다. 특히 IDE 통합을 통해 개발 시 즉각적인 문서 확인이 가능하다는 장점이 있습니다.

주요 특징

• TypeScript 통합: 타입 시스템과 완벽한 연동
• IDE 지원: VSCode 등에서 즉각적인 문서 확인 가능
• 표준화된 포맷: 일관된 문서화 규약 제공
• TypeDoc 도구 활용: API 문서 자동 생성 및 웹 문서화 지원
• GitHub Pages 배포: 자동화된 문서 배포 및 공유 가능

TSDoc 선택 이유

• 코드 이해도 향상: 명확한 문서화로 팀원 간 코드 이해도 증가
• 유지보수성 강화: 문서와 코드의 동기화로 장기적 유지보수 용이
• 개발 생산성: IDE 통합으로 빠른 개발 지원
• 타입 안정성: TypeScript의 타입 시스템과 통합된 문서화
• 자동화된 문서 생성: TypeDoc을 통한 빠르고 체계적인 API 문서화

TypeDoc 활용

tsdoc은 아무래도 주석이기 때문에 이를 어떻게 문서화 해낼지를 고민해야 됐습니다. 이를 해결 하기 위해서 멘토님께 추천 받았던 TypeDoc을 적용하기로 하였습니다. TypeDoc은 TSDoc 주석을 기반으로 자동으로 API 문서를 생성해주는 강력한 도구입니다.

• 자동 문서화: TSDoc 주석을 HTML 문서로 자동 변환
• 타입 정보 통합: TypeScript의 타입 정보를 문서에 자동으로 포함
• 검색 및 탐색: 생성된 문서에서 쉽게 컴포넌트와 타입을 찾을 수 있음
• GitHub Actions 통합: 자동화된 문서 생성 및 배포 가능

배포 전략

GitHub Actions를 활용하여 TSDoc으로 작성된 문서를 자동으로 생성하고 GitHub Pages에 배포하는 전략을 채택했습니다.

• 코드 변경 시 자동으로 문서가 업데이트됨
• 팀원들이 언제든 최신 API 문서에 접근 가능
• 문서 버전 관리와 이력 추적이 용이
• 외부 협업자들도 쉽게 문서에 접근 가능

단점 고려사항

• 작성 시간 증가: 상세한 문서화에 추가 시간 소요
• 문서 관리 부담: 코드 변경 시 관련 문서도 함께 업데이트 필요
• 학습 곡선: TSDoc 문법과 규약에 대한 학습 필요
• 초기 설정 복잡성: TypeDoc과 GitHub Actions 설정에 추가 작업 필요

단점이 아무래도 스토리북과 동일하게 작성을 하는데 시간이 든다는 문제가 있습니다. 이런 부분에 대해서는 tsdoc을 추천 해주신 멘토님께서 시간이 부족할 때는 gpt나 copilot에 컴포넌트에 대한 설명을 추가하는 방식으로 어느정도 간소화 할 수 있을 것 같습니다. 실제로 이번 주에 컴포넌트를 구현하면서 적용을 해봤는데 적절하게 작성을 해주는 걸 확인할 수 있었습니다.

대체제

일반적인 JSDoc이나 마크다운 기반의 문서화를 고려할 수 있습니다. 하지만 TSDoc과 TypeDoc의 조합은 TypeScript의 타입 시스템과 긴밀하게 통합되어 있고, IDE에서의 즉각적인 문서 확인이 가능하며, 자동화된 문서 생성과 배포가 가능하다는 점에서 우리 프로젝트의 요구사항에 가장 잘 부합합니다. 특히 백엔드 개발자들과의 협업 상황에서, 컴포넌트와 함수의 사용법을 명확하게 전달하고 항상 최신 상태의 문서를 유지할 수 있다는 점이 큰 장점으로 작용했습니다.