저는 한 스타트업의 커머스 앱 프론트엔드 1인 개발을 진행 했었습니다. 지금은 이직한 전 회사 동료 분의 추천으로 기존 django 로 되어있던 앱을 코틀린과 next.js 로 변경하는 작업에 참여했고, 저는 이 작업에서 next.js 로 변경하는 부분을 맡아서 했습니다. 이번 프로젝트가 슬슬 마무리 단계에 접어들게 되어 회고하기 위해 글을 작성해봅니다.
프로젝트 시작
기존 프로젝트는 고객이 커머스 기능을 진행할 수 있는 대시보드 웹앱, 고객이 커머스 기능으로 선물을 보내면, 여러개의 선물 후보 중 하나를 선택할 수 있도록 하는 모바일 웹앱, 그리고 스타트업 회사 직원분들이 이 서비스를 관리 할 수 있도록 백오피스 웹앱으로 구성되어 있었습니다.
제가 새로 하게된 프로젝트는 기존 구성 중 모바일 앱은 그대로 두고, 대시보드 웹앱과 백오피스 웹앱을 kotlin 과 react 로 새로 구축하는 프로젝트였습니다. 개발자는 백엔드 개발 1명, 프론트엔드 개발 1명으로 진행했고, 디자이너와 기획자가 프로젝트를 시작 하고나서는 없는 상황에서 개발을 진행하게 되었습니다. 개발 기한은 1개월 반이었는데, 이것은 사실 현실적으로 불가능한 기한이긴 했었습니다. 하지만, 제 욕심에 빠른 시일 내에 해결하고 싶었기 때문에 목표 자체는 이렇게 하고 시작하게 되었습니다.
프로젝트 구성
프로젝트 시작하기에 앞서 두개의 웹앱을 1개월 반이라는 시간 안에 개발하는 것은 정석적으로 하게되면 힘들 것이라 생각했습니다. 최대한 자동화 할 수 있는 부분은 자동화하고, 오래 걸리면서 영향이 적은 것은 후순위로 빼며 작업을 해야했습니다. 그래서, 프로젝트 환경 구성 시 다음과 같은 제약사항을 고려했습니다.
- next.js 의 다양한 서버 기능과 최적화 기능을 통해 빠른 시간 내에 두개의 웹 페이지를 개발한다.
- 짧은 시간 안에 많은 것을 만들어야하기 때문에,
shadcn/ui를 이용해 공통 컴포넌트 개발 시간을 단축한다.
- 백엔드 api 는 반복작업이 매우 많기 때문에
orval을 통해 자동화 할 수 있는 부분은 자동화한다.
- 기존
django도tailwind로 스타일링을 했으며,next.js,shadcn/ui모두 default 스타일링은tailwind이므로tailwind로 스타일링 한다.
- 공통 컴포넌트를 라이브러리로 빼기에는 너무 관리 측면에서 무겁다 판단해 코드 복붙으로 관리한다.
- CI 는 모든 테스트를 다 할 수 없기에, 빠르게 구현 할 수 있거나 꼭 필요한 부분만 한다.
- 추가적으로 FSD 아키텍처를 도입하여 도메인에 더 밀접한 폴더 구조를 가져간다.
그래서 저는 두개의 앱 중 빠르게 개발해야하는 대시보드 웹앱을 개발 후 그 앱을 포크(프로젝트 복사) 하여 개발하는 방식을 택하기로 했고, 다음과 같이 프로젝트를 구성하였습니다. 특징적인 부분만 조금 강조하면 다음과 같습니다.
- Next.js 14 버전, FSD 아키텍처 사용
shadcn/ui로 기본적인 공통 컴포넌트 빠르게 구축
react-query로 서버 상태 관리,react-hook-form으로 폼 상태 관리,zustand로 글로벌 상태 관리
zod로 폼 비즈니스 로직 관리
orval을 통해react-query관련 api 등 백엔드 api 호출 부분 코드젠
- CI 에서 백엔드 swagger 변경 감지를 추가해 백엔드 변경 시 CI 실패 로직 추가
auth.js를 통한 인증 관리 → 중도 제거 후 http-only 쿠키로 수정
다음과 같이 구성을 하여 1인 개발을 하더라도 빠른 생산성과 코드 관리, 유지보수를 할 수 있었습니다. 개발을 하며 이렇게 진행하니 어떤 부분이 좋았고, 어떤 부분이 아쉬웠는지를 정리해보고자 합니다.
프로젝트 개발
개발 환경 설정
저의 개발 루틴은 다음과 같이 정했습니다.
- 기획된 사항을 보고 이슈 정리
- 프로젝트에 이슈 추가
- 해당 이슈에 맞게 로컬 브랜치를 새로 만들어 작업
- PR 시 CI 로 다음과 같이 추가
- 백엔드 swagger 변경 감지
- 빌드 테스트
- 메인 브랜치에 머지 후 배포
아래 후기들 옆의 별은 만족도 입니다!
CI 설정 의도 및 후기 ⭐⭐⭐⭐⭐
CI 로 백엔드 API 변경 여부를 둔 이유는 다음과 같습니다.
- 백엔드 변경에 의한 클라이언트 런타임 에러를 줄이기 위함
- 백엔드 개발자 분과 더 편한 소통을 위함
Git 으로 백엔드 swagger 변경 여부를 확인 할 수 있기 때문에, 백엔드 API 의 response 와 request 등 어느 부분이 수정 되었는지 정말 쉽게 알수 있었습니다. 이 덕분에 백엔드 개발자 분도 편하게 소통을 굳이 하지 않아도 배포할 수 있고, (보통은 먼저 알려 주셨어요.) 제가 백엔드 API 의 어느 부분이 어떻게 바뀌었는지 직접 물어볼 필요 없이 바로 알 수 있어 스스로도 편했습니다.
FSD 아키텍처 사용 후기 ⭐⭐⭐⭐
FSD 아키텍처는 거창하게 아키텍처라고 이름이 붙었지만, 결국 프론트엔드 프로젝트의 폴더 관리 방안 중 하나입니다. 미리 정의된 기능 규모에 따른 레이어, 비즈니스 도메인에 따른 슬라이스, 목적에 따른 세그먼트 이렇게 세 계층으로 나누어 폴더 구조를 두는 것인데요. 정말 비즈니스 로직에 맞게 잘 만든 폴더 구조라고 생각합니다. 제 개인 프로젝트들은 앞으로 모두 FSD 를 사용할 것 같습니다. root alias 를 사용하고, index.ts 파일 등으로 export 를 미리 해두면 파일을 옮겨도 그 파일을 import 받은 다른 파일들을 고치지 않아도 된다는 소소한 장점도 있었습니다. (하지만 index.ts 파일등으로 export 몰아하기는 빌드 성능을 떨어뜨린다는 이야기를 들어서 이걸 장점이라고 해야할지는…)
next.js 의 app router 와 약간 상충되는 부분이 있지만, 이는 약간 타협해서 사용했습니다.
각종 프레임워크, 라이브러리 사용 후기
next.js 14 ⭐⭐⭐⭐
next.js 는 리액트 프레임워크로 리액트의 다양한 기능들을 쉽게 사용 할 수 있게 도와줍니다. routing 페이지를 미리 가져온다거나, 이미지 최적화를 해준다거나, 자동으로 페이지 prefetch 를 해준다거나, 서버사이드 렌더링을 위한 서버 컴포넌트를 사용하기 쉽게 만들어주는 등의 다양한 기능을 제공합니다. 저는 next.js 를 짧은 시간 내에 빠르게 개발하기 위해, 그리고 추후 SEO 가 가능해야한다는 것 때문에 선택하게 되었습니다. vercel 을 통한 빠른 개발환경 배포 또한 좋았습니다. 하지만, 개발환경과 배포환경의 서버 렌더링에서 미묘한 차이가 있어(로컬은 모두 서버사이드 렌더), 가끔 로컬 빌드 후 빌드 결과물을 직접 띄우거나 하기도 했습니다. 그리고, 인증이 엮인 부분은 구현하기 정말 어려웠습니다.
shadcn/ui ⭐⭐⭐⭐⭐
shadcn/ui 는 Headless UI 인 Radix UI 기반으로 만들어진 디자인 시스템 라이브러리 느낌의 코드 제너레이터입니다. shadcn/ui 는 npm 으로 다운을 받는게 아니라, console 명령으로 프로젝트에 직접 디자인 시스템 라이브러리 코드를 만들어내어, 직접 디자인을 간단하게 수정 할 수 있습니다. shadcn/ui 는 빠르게 신규 프로젝트에 적용 할 수 있다는 장점이 있어 채택하게 되었습니다. MUI 나 다른 기존 좋은 디자인 시스템 라이브러리도 많지만, 짧은 시간 내에 공통 컴포넌트의 디자인을 빠르게 수정해야하며, tailwind 가 default 여서 next.js 와도 호환이 좋을 것이라고 생각했습니다. 정말 이제는 직접 운영하는 라이브러리가 있지 않는 한, shadcn/ui 로 변경을 하는게 좋다고 생각이 될 정도로 사용 후기가 정말 좋았습니다. 거의 모든 쪽에서 문제가 없었지만, 토스 페이먼츠 결제 위젯 연동 시에
shadcn/ui 의 다이얼로그와 같이 사용했을 때, z-index 문제가 있어서 토스 페이먼츠 결제 위젯을 적용시킬때만 새로 다이얼로그 컴포넌트를 만들어 동작하게 하였습니다.
react-hook-form ⭐⭐⭐⭐
제가 회사에서 ERP 를 개발할 때부터 아주 유용하게 사용하던 폼 상태 관리 라이브러리 입니다. 러닝커브가 약간 있는 편이지만, 복잡한 폼의 경우에도 관리하기 쉽게 되어있어 오래 잘 써먹고 있는 라이브러리 입니다. 이번에 특히 사용자 정보가 담긴 엑셀 파일을 import 해 폼과 연동하는 등의 복잡한 폼 구현에도 쉽게 사용할 수 있어서 아주 좋았습니다. 그리고, 이번에
zod 와 함께 처음 같이 사용해봤는데요. zod 연동이 아주 잘 되어있어, 폼 관련 비즈니스 로직을 구분해 관리하기 쉬웠습니다.
TanStack: Query (react-query) ⭐⭐⭐⭐⭐
가장 많이 사용하고 있는 서버 상태 관리 라이브러리 입니다. 클라이언트 사이드에서 백엔드 API response 를 캐시해 API 호출 자체를 줄이거나, response 를 react 의 상태와 연동하고, 다양한 공통적인 상태 (loading, error)를 함께 관리해주는 아주 좋은 라이브러리입니다. 이번에는 후술할
orval 이라는 라이브러리와 함께 사용해서 클라이언트 사이드에서의 서버 상태를 빠르고 쉽게 관리 할 수 있었습니다.
orval ⭐⭐⭐⭐⭐
orval 은 Open API 스펙에 맞는 API 문서를 보고 그 기준에 맞게 클라이언트에 코드를 만들어주는 코드 제너레이터 입니다. react-query 를 사용하면서, 기계적으로 작성하는 부분이 많다고 느꼈는데 이를 해소해주는 엄청난 라이브러리 였습니다. orval 을 통해 백엔드에 의존적인 typescript 인터페이스나 타입 등을 신경쓰지않고 오히려 정확하게 관리 할 수 있습니다. 게다가, react-query 코드도 자동으로 만들어 주어 정말 많은 개발 시간을 줄여주고, 정확한 로직을 제공해 주었습니다. 처음만 세팅해두면 그 이후로는 크게 고민하지 않아도 되고, 세팅하는 시간도 그리 오래 걸리지 않아서 정말 좋았던 라이브러리 입니다. 하지만,
react-query 의 useInfiniteQuery 와 같은 페이지네이션 API 는 연관시켜 만들어주지는 못 해서 (제가 못 했지 기능은 제공하고 있을 가능성이 큽니다.) 조금 고민했던 순간이 있었습니다.
zustand ⭐⭐⭐⭐
react 환경에서 전역 상태를 관리하기 위해 사용하는 가볍고 좋은 전역 상태 관리 라이브러리 입니다. 사용할 일이 많지는 않았지만, 필연적으로 사용할 수 밖에 없는 상황이 있어서 처음에는 설치하지 않았다가 추후에 설치해 사용했습니다. persist 쪽과 함께 사용하려고 했으나(로컬 스토리지) 이쪽은 지원이 끊긴 것 같았습니다. 일반적인 경우는 react hooks 로 해결하고, zustand 는 정말 전역 상태가 꼭 필요한 경우에만 작게 사용했습니다.
auth.js(next-auth) ⭐⭐⭐
auth.js 는 next.js 인증 관련 라이브러리로 가장 유명한 라이브러리 입니다. 인증이 보안과 관련된 점이 많다보니, 신경쓰지 못 할만한 것들을 미리 잘 만들어두고, 사용하기 쉽게 만들어둔 라이브러리 입니다. 하지만 제가 사용할 때는 정말 애먹었습니다. auth.js 는 next.js 에서 인증 관련된 기능을 개발 할 때 가장 많은 기능을 제공 해주면서도 특정 상황(인증 서버를 백엔드에서 따로 관리하는 경우)에서의 커스터마이징은 정말 어렵고 불편했습니다. 아마 간편 로그인인 OAuth Provider 로그인만 제공하는 그런 경우가 아니라면 사용하지 않을 것 같다는 생각이 들었습니다. 이 라이브러리는 나중에 http-only cookie 로 인증 방식을 변경할 때 제거했습니다.
마치며
정말 간단하게 정리한 회고였는데 다시 보니 라이브러리 사용후기 같은 느낌이 되었네요. 이번 프로젝트를 통해서 새로운 것들을 많이 배우고 적용해본 기회가 된 것 같습니다. 1인 개발을 하며 꼭 필요했던 부분을 직접 사용하고 구축해보면서 직접 장단점을 느껴본 것이 좋았던 것 같습니다. 좀 더 구체적인 문제 사항은 다른 포스트로 소개하도록 하겠습니다. 감사합니다.
