작년 1월부터 나는 모아동이라는 대학교 동아리를 모아 보는 사이트를 운영하고 있다.

2025년은 나에겐 모아동의 해였다고 해도 과언이 아닐 정도로 많은 노력을 투자했다.

그래서 2025 회고를 적을까하다가, 정말 많은 시간을 이 프로젝트에 투자했기에 오로지 이 프로젝트를 위한 회고를 써 주겠다 마음을 먹은 것이다.

2025년 1월

이 프로젝트를 하기 전, 나는 대학교 학생증 QR을 인식해 출석체크 및 인원관리를 하는 프로젝트를 했었다.

어찌저찌해서 GDG Busan DevFest에서 사이드부스를 운영하게 되었고 충분히 가능성있고 확장가능한 서비스라는 피드백을 받았다. 하지만 정말 큰 문제가 있었다. 그건 바로 개인정보문제였다.

학생들의 개인정보를 DB에 저장해야 인식이 가능했는데, 학교 전담 변호사분과도 얘기해야 했고, 당장 내가 속해있던 동아리 내부에서도 사용을 꺼려하는 사람들이 일부 있었다.

기존 팀원들끼리 다시 의견을 모았다. 결국 개인정보가 문제가 될 것이고, 우리는 다른 방법으로 학교 내에 가치를 전달해야 한다.

그래서 나온 아이디어가 바로 동아리 서비스였다. 다른 학교에서도 성공한 서비스가 있었다. 심지어 우리 학교에서도 몇 년 전 앱으로 출시했다가 금방 망한 사례가 있었다. 하지만 우리는 믿음이 있었다.

신입생들의 이야기

아무 이유없이 프로젝트를 시작할 수는 없었다. 10명이라도 좋으니 수요를 관찰하고 만들어보자는게 우리의 생각이었다.

다행히도 동아리 내에 신입생들이 많이 있어서 그들의 의견을 쉽게 들을 수 있었다. 그들의 의견은 이랬다.

"에브리타임에서만 동아리를 찾는게 불편하다. 항상 올라오는 글을 직접 찾아봐야한다.

"학교에 어떤 동아리가 있는지 모르겠다. 한 번에 볼 수 있는 곳이 있으면 좋겠다."

우리 학교는 68개가 넘는 다양한 동아리가 있는데 인스타나 학교 홈페이지를 찾아봐도 정보가 없으니 알 수가 없다. 사실 신입생뿐만 아니라 재학생들도 자신이 한 동아리 외에는 잘 모르는 분위기였다.

무엇보다 처음 온 신입생들은 에브리타임 새내기게시판만을 사용할 수 있는데, 일부 동아리들은 새내기가 아니라 동아리게시판에 올리니 신입생들이 얻을 수 있는 정보가 제한적이었다.

바로 시작하자

주변 신입생들의 얘기를 듣고 수요가 있다고 판단했다. 무엇보다 다른 대학교의 잘 된 선례가 있으니, 우리가 못 할 게 뭐가 있냐는 생각도 있었다.

물론 잘 되기 위해서는 디자인적 완성도가 필수라고 생각했다. 무엇보다 개발자들 중 디자인을 좋아하거나 잘 하는 사람도 없었다. 그래서 같은 학교 시각디자인전공 디자이너 한 분은 섭외했다.

그렇게 프론트 2명, 백엔드 4명, 디자이너1명으로 팀이 꾸려졌다. 첫 회의는 새마음 새뜻으로 1월 2일에 시작했다. 2월말부터 동아리 모집이 시작되기에 디자인과 개발을 합쳐 1개월 반 정도 남아있었다.

문제는 개발이 아니다

우리가 개발해야 할 건 동아리 목록과 배너가 있는 메인페이지, 그리고 각 동아리 상세정보가 있는 상세페이지였다. 개발은 정말 간단했다. 어 근데 이걸 어떻게 동아리 관리자들이 쓰게 하지?라는 생각이 몰려왔다.

68개의 동아리 관리자들은 이미 에브리타임으로 동아리를 홍보하고 있었다. 1차목표는 에브리타임에 홍보를 올릴 때 우리 서비스링크를 첨부하게 하기 였다.

그들과 컨택하기 위해서는 모든 동아리를 관리하는 총동아리연합회의 힘이 필요했다. 하지만 총동연측에선 완성될지 모르는 단계에서 관리자들에게 사용하라고 부추기기엔 리스크가 있다는 입장이었다.

그리고 1개월 반만에 관리자들을 위한 기능도 추가하는 건 무리라고 판단했다. 그렇게 야심찬 3월의 부흥은 물거품으로 돌아갔다.

약간의 희망

팀의 목표는 "대학교 학생들 모두가 우리 서비스로 동아리를 찾고 지원한다."였다. 그러기 위해서는 온전히 우리 힘으로만 할 수는 없었다.

홍보를 하려면 홍보 플랫폼이 있어야 하는데, 자체적인 홍보효과가 없으니 그것마저 에브리타임의 힘을 빌려야 했다.

총동연의 도움이라면 충분히 홍보효과를 볼 수 있었지만, 그들은 새로운 시도보다는 기존의 안정성을 택했다.

장기적으로 우리 서비스가 안정적으로 유지되려면 모든 동아리를 관리하고 있는 총동아리연합회의 힘이 무조건 필요하다고 생각했다. 그들을 설득하기 위해서는 일단 신뢰성을 쌓아야 했다.

총동연과의 첫 미팅

개강 후 총동아리연합회 회장과 첫 대면 미팅을 가졌다. 우리가 얘기한 신입생들의 고충을 동감해주었고, 6월말까지 모든 동아리를 섭외하겠다는 공동의 목표를 세웠다.

그때까지 서비스 완성도를 높이는 일에 집중해야 했다.

관리자 기능?

그 당시에는 우리 서비스를 많은 사람들이 사용하려면 먼저 동아리 관리자를 섭외해야한다고 생각했다. 관리자들이 사용한다면 학생들도 신뢰하고 이용할 것이라는 믿음 때문이었다. 훗날 이 믿음은 서비스를 더 늪으로 가져갔다.

돌아와서 관리자들이 겪는 어려움이 무엇인지부터 파악해야 했다. 총동연의 힘을 빌려 관리자들만 모아 둔 단톡을 만드는 것까진 성공했기에, 편하게 구글폼으로 피드백을 받을 수 있었다.

그 많은 관리자들 중 비록 20퍼센트가 안 되는 인원들이 피드백에 응해줬고, 그 중 다수가 동아리 지원과 SNS 공유 기능을 원했다.

SNS 공유 기능은 매우 간단했지만, 지원하기는 신경 쓸 부분이 많았다.

• 모집기간 설정 기능
• 외부지원폼 설정 기능 (구글, 네이버 등)
• 서비스 자체 지원서 기능

이번에도 개발 자체의 문제는 없었다. 모집시기까지는 아직 3개월이라는 시간이 있었다. 그 사이에 우리는 빠르게 관리자 기능을 개발하기 시작했다.

첫 홍보

5월에는 학생들에게 서비스를 처음 홍보했다. 모집기간은 방학이 시작되는 7월, 그 전에 미리 서비스를 각인시켜줘야겠다는 생각이 들었다.

학생들이 홍보하기 가장 좋은 곳은 아무래도 에브리타임이다. 간단한 사진과 글을 적어 올렸고 다행히도 반응이 좋았다.

덕분에 당일 사용자가 300명에 가깝게 들어왔고, 우리는 가능성을 맛봤다.

내부지원서라는 위기

관리자들이 사용할 수 있는 지원서를 만들기 위한 계획을 세웠다. 맹점은 관리자들은 이미 구글폼, 네이버폼 등의 외부 사이트를 사용하고 있었고, 굳이 우리 서비스 내부의 지원서 기능을 사용할 이유가 없었다.

하지만 우리는 그 부분을 크게 받아들이지 않고 내부지원서 기능을 감행했다. 지원서뿐만 아니라 정보 수정을 위한 관리자 기능이 우선순위였다. 3개월, 즉 12주에서 시험기간을 제외하고 6주만에 그 기능들을 모두 완성해야 했다.

간과한 것은 동시에 동아리 관리자들이 우리 서비스의 지원서 기능을 사용하도록 설득해야 한다는 것이었다.

관리자 기능에 생각보다 많은 리소스가 들어갔고, 결국 6월말 지원서 기능을 완성하지 못했다. 우리가 보여줄 수 있는 건 메인 페이지, 상세 페이지 둘 뿐이었다. 지금 생각해보면 외부지원서폼만 넣도록 설정해뒀다면 서비스상 큰 문제가 없었을 것이다.

결과적으로 동아리 관리자가 사용할 수 있는 건 정보 수정밖에 없었다. 중간중간에 몇 번 총동연에 부탁하여 전체 동아리에 우리 서비스를 홍보했었지만, 동아리를 하지 않는 학생들은 서비스에 대해 잘 모르고 있었다. 우리의 타겟은 동아리를 하지 않는 인원들인데, 정작 홍보는 동아리를 하고 있는 사람들한테만 한 것이다.

동아리 관리자들도 에브리타임에 올리면 되는데, 굳이 학생들이 잘 안 쓰는 서비스를 사용할 이유는 없었다.

2025년 7월

모집기간이 시작되었을 때 에브리타임에 모집공고가 올라올 때마다 직접 서비스에 내용을 채워넣었다. 그리고 1주마다 에브리타임에 올리며 서비스를 홍보했다.

그렇게 2개월동안 홍보했지만 누적사용자는 1400명에 불과했다.

신입생들은 이미 에브리타임에 익숙해져 있었고, 웹이라는 특성때문에 리텐션을 유지하는 것은 더 어려웠다.

새로운 마음으로

지원서 기능에서의 병목, 그리고 동아리 관리자 포섭 실패가 있었지만 서비스에 대한 믿음은 여전했다.

새로운 팀원

8월이 되었을 무렵, 나를 포함한 2명이 부스트캠프를 하게 되었고 개발 리소스를 다 쳐내기 힘들다고 판단했다.

그리하여 3명을 더 뽑았고 이는 패착이었다.

첫 번째는 문서 부족이었다. 새로운 팀원들은 기존 프로젝트 구조를 모르기에 문서가 필요하다. 그 당시 문서라고는 테스스택, 회의록, 미팅 자료가 전부였다.

두 번째는 기존 개발자들이 온보딩에 사용할 시간이 없었다. 진행하던 개발과 부트캠프를 병행하면서도 새로운 팀원들을 기존 팀에 적응시키기엔 역부족이었다.

마지막은 7개월 간 달려 온 기존 팀원들과 새로운 팀원들의 싱크를 맞추는 일이었다. 그 간극은 풀 수 있는 과제라기보단 열정의 온도를 맞추는 일에 더 가까웠다.

빠른 이별

팀 생산성은 저하되었고 쳐내지 못 한 일들이 다음 스프린트로 계속 미뤄지는 현상이 발생했다. 이렇게 가면 저번과 같은 결과를 불러올 것이라는 두려움이 닥쳤다. 그럴수록 객관적인 시선이 필요했다.

모아동이 시작되기 초기부터 협업, 애자일, 홍보 등 많은 면에서 도움을 주었던 현업자 선배에게 나는 조언을 구했다. 활발하지 않은 소통과 팀 생산성이 저하된 상황에서 팀장이 해야 할 일은 빠르게 핵심 인원만 남기는 것이라는 조언을 들었다. 무엇보다 열정적인 팀원의 생산력을 낮추는 일을 방지하기 위해서라도 결정해야 한다고 했다.

지금 생각해보면 이 순간이 개인적으로 가장 힘들었던 상황인 동시에 성장할 수 있었던 큰 발판이었던 것 같다.

그렇게 회의에서 내가 느낀 점들을 설명하며 개발보다는 홍보에 집중할 미래를 그려갈 사람만 남아달라고 했다. 3명이 나갔고 남은 사람은 총 8명이었다. 목표가 같은 사람끼리 남았기에 더 큰 활력을 불어넣어 주었다.

2026년

2025년 우리는 두 번의 실패를 겪었다. 다음해에도 성공하지 못 한다면 어떻게 해야 할까라는 불안감이 있었다. 그래도 투자한 시간이 있어 쉽게 포기할 생각은 없었다.

방학동안 10명 정도 동아리 관리자들을 만나면서 들은 공통된 의견은 학생들이 잘 몰라서 사용하기 어렵다였다. 정리하자면

• 동아리 관리자들은 신뢰성있는 서비스여야 사용한다.
• 총동아리연합회는 신뢰성이 보장된 단체다.

그와 별개로 관리자들이 사용유무와 사용자들의 사용유무는 비례하지 않는다고 생각했다. 공통된 것은 신뢰성있는 서비스여야 모두가 사용한다였다.

미팅에서의 성과

총동아리연합회도 1년이 지나 새로운 인원들로 교체되었다.

새로운 회장과 첫 미팅을 했다. 회장은 작년 홍보쪽을 담당하던 분이었다. 그때부터 모아동을 눈여겨봤다고 했다. 적극적으로 사용하고 싶었는데 아쉬웠다고 했다.

우리는 다양한 홍보방식을 제안했다. 2월부터 신입생이 들어올텐데 그때 만들어지는 모든 과 단톡에 홍보하기, 총동연 인스타에 서비스 홍보 게시물 올리기 등이 있었다. 다행히도 모든 제안을 흔쾌히 받아주었고, 그때부터 팀에는 확실한 동기부여가 생기기 시작했다.

이것 말고도 여러 가지 방안들이 오갔고 기대가 현실이 되는 순간이었다.

아래는 올해 진행했던 미팅 기록인데 대작전의 이름만큼 절실했다.

앱 도입

웹은 최초 접근성이 좋지만 유지력은 떨어진다. 앱은 다운받고 어디 들어갈 필요없이 클릭 한 번으로 서비스에 접근할 수 있다.

무엇보다 알림기능은 장기적으로 유리할 것이라 생각했다. 모집정보, 모집기간 등 계속해서 사용자를 끌어오기 위해서 필수적이라고 판단했다.

팀에는 모바일 엔지니어로 일하고 계신 현업자 선배가 있었고, 덕분에 빠르게 React Native 웹뷰기반으로 앱을 만들 수 있었다.

안정화

신입생이 들어오기 전, 첫 홍보를 했다. 이전처럼 에브리타임으로 진행했고 역시나 좋은 반응이었다. 그러나 그게 끝이 아니었다.

모아동에 대한 글이 에브리타임에 자주 올라오기 시작했다. 동시에 바이럴인지 몰라도 앱다운로드수가 기하급수적으로 늘었다. 1개월간 무려 1000명이 넘게 앱을 다운받았다. 오로지 글 하나로 유입된 사용자였기에 입소문의 힘은 강력하다는 것을 체감했다.

동아리소개한마당

3월에 열리는 동아리 소개 한마당은 모집 시즌에 지원하지 못한 학생들을 위해 하루 동안 오프라인 부스를 운영하며 추가 모집을 진행하는 행사이다.

아직 지원하지 못 한 학생들을 위해 모아동이 할 수 있는 일은 아직 있었다. 행사 일주일을 남기고 행사에 참여하는 동아리 부스 지도와 공연 시간표의 디자인+개발을 완성했다. 당시 개발기록

운좋게도 우리 모아동팀 또한 행사에서 부스를 하게 되어 겸사겸사 홍보를 했다. 개인적으로는 현장실습때문에 못 갔지만 열심히 부스를 이끌어 준 팀원들한테 정말 고마웠다.

행사 후기

행사 전 팝업과 배너로 미리 홍보를 했어서 그런지 사용자가 많이 들어왔다. 당일을 포함하여 무려 5000명 가까이 우리 사이트에 방문했고, 앱다운로드수는 2500이 넘었다.

불과 2개월 전 10명도 들어오지 않던 서비스였는데 이렇게나 성장했다는 게 신기했다. 무엇보다 많은 사람들이 우리 서비스로 동아리를 찾고 지원한다는 우리의 첫 번째 목표를 달성한 것 같아서 뿌듯했다.

다음 목표

동아리 지원이라는 1차 목표를 달성한 후, 우리는 새로운 목표를 다시 세웠다.

지원 시기에만 사용되는 앱은 지속적인 가치를 만들기 어렵다고 판단했기 때문이다.

하지만 동아리 활동은 학기 내내 이어진다. 그래서 동아리원뿐만 아니라 모든 학생들이 각 동아리의 행사와 활동을 확인할 수 있도록 홍보 게시판 기능을 기획했다. 현재 대부분의 기능 개발을 마쳤고, 다음 주 중으로 배포할 예정이다.

끝이 아닌 시작

앞서 이야기한 기능 외에도 다른 학교로의 확장, 서비스를 통한 수익 모델 구축 등 여러 계획을 가지고 있다. 때로는 현실적인 목표만큼이나, 야심찬 포부도 필요하다.

돌이켜보면 이렇게 오랜 기간 팀 프로젝트를 이어온 것은 처음이었다. 기술이 특별히 뛰어났던 것도, 아이디어가 압도적으로 독창적이었던 것도 아니었다. 다만 정말로 사람들이 사용하는 서비스를 만들고 운영해 보고 싶다는 마음이 컸다.

1년이 넘는 시간 동안 함께해 준 팀원들에게 다시 한 번 감사의 마음을 전하며, 이 프로젝트가 하나의 마무리가 아니라 더 큰 도전을 향한 새로운 시작이 되기를 기대한다.

2026년도 화이팅!!!

지금은 사용하지 않는 CRA에서는 React.FC를 템플릿에서 제거한 PR을 확인할 수 있다. 그렇다면 왜 React.FC 사용을 지양해야 할까? 무조건 쓰지 말아야 하는 걸까?

// ❌ 지양                                                                                                                                      
  const Button: React.FC<ButtonProps> = ({ children }) => {                                                                                       
    return <button>{children}</button>;                                                                                                           
  };

// ✅ 권장
  const Button = ({ children }: ButtonProps) => {
    return <button>{children}</button>;
  };

1. children 이 암묵적으로 포함된다.

React.FC는 자동으로 children을 props에 추가하므로, children을 받지 않는 컴포넌트에서도 children을 넘길 수 있어서 버그 가능성이 생긴다. (React 18에서는 제거됐지만 레거시에서 고려할 필요)

2. 제네릭 컴포넌트를 못 만든다.

// ❌ React.FC로는 불가능
const List: React.FC<ListProps<T>> = ... // T를 어디에?

// ✅ 직접 선언하면 가능
const List = <T,>(props: ListProps<T>) => { ... };

3. compound component가 번거롭다.

예시: Dropdown

// ❌ React.FC — sub-component마다 타입 선언에 다 적어야 함                                                                                     
  const Dropdown: React.FC<DropdownProps> & {                                                                                                     
    Trigger: React.FC<TriggerProps>;                                                                                                              
    Menu: React.FC<MenuProps>;
    Item: React.FC<ItemProps>;
  } = ({ children }) => {
    return <div className="dropdown">{children}</div>;
  };

  Dropdown.Trigger = ({ children }) => <button>{children}</button>;
  Dropdown.Menu = ({ children }) => <ul>{children}</ul>;
  Dropdown.Item = ({ label, onClick }) => <li onClick={onClick}>{label}</li>;

React.FC<DropdownProps>로 타입을 선언하면, TypeScript는 Dropdown이 정확히 그 타입만 가진다고 본다.

  // TypeScript가 보는 관점:
  const Dropdown: React.FC<DropdownProps> = ...                                                                                                        
  // → Dropdown의 타입 = (props: DropdownProps) => ReactElement | null
  // → 그 외 프로퍼티? 없음

Dropdown.Trigger는 React.FC에 없는 프로퍼티기에, 미리 “이 함수에는 Trigger, Menu, Item이 있어.”라고 intersection(&) 으로 알려줘야 한다.

const Dropdown: React.FC<DropdownProps> & {
    Trigger: React.FC<TriggerProps>;   // ← "Trigger도 있을 거야"
    Menu: React.FC<MenuProps>;         // ← "Menu도 있을 거야"
    Item: React.FC<ItemProps>;         // ← "Item도 있을 거야"
  } = ({ children }) => { ... };

하지만 서브 컴포넌트가 많아질수록 React.FC로 타입 선언을 일일이 해 줘야 하기에 매우 번거롭고, 코드도 복잡해진다.

반면 FC 없이는 TS가 타입 추론만 하고 고정하지는 않는다. 그래서 프로퍼티를 붙이면 자동으로 타입을 추론한다.

const Dropdown = ({ children }: DropdownProps) => { ... };

Dropdown.Trigger = ... // 자동 추론해서 반영

정리

FC를 쓰면 타입이 잠겨서 미리 다 열거해야 하고, 안 쓰면 타입이 열려있어서 그냥 붙이기만 하면 되는 것으로 이해할 수 있겠다.

React.FC를 사용하는 예시

const TRIGGER_TYPE_ICON_MAP: Record<
  TriggerType,
  React.FC<{ color?: string; size?: string }>
> 

여기서 React.FC를 쓴 이유는 compound component가 아니라 Record의 value 타입을 지정하는 용도이기 때문이다.

⇒ “이 Record의 value는 color와 size props를 받는 React 컴포넌트다.”라는 타입 제약을 뜻한다.

만약 React.FC없이 같은 걸 표현하려면

  const TRIGGER_TYPE_ICON_MAP: Record<
    TriggerType,
    (props: { color?: string; size?: string }) => React.ReactElement | null
  >

더 길고 번거롭다. 그래서 컴포넌트 타입을 참조용으로 쓸 때는 React.FC가 간결하다.

예시는 타입 참조기 때문에 children을 암묵적으로 포함하지 않으며, 타입 파라미터로 넘기면 되니까 제네릭과 상관이 없고, compound와도 무관하기 때문에 가독성과 간결함을 위해 사용한 것이다.

ex. 타입 참조 시 - FC로 제네릭 문제는 없음

  type ListProps<T> = {
    items: T[];
    renderItem: (item: T) => React.ReactNode;
  };

  // 타입 참조에서는 T를 구체적으로 지정하니까 문제없음
  type Props = {
    userList: React.FC<ListProps<User>>;
    productList: React.FC<ListProps<Product>>;
  };

선언 시에는 를 함수 앞에 붙여야 하는데 FC 문법 구조상 넣을 곳이 없고, 타입 참조 시에는 이미 <User> 같이 구체적인 타입을 넣기 때문에 문제가 생기지 않는다.

참고

https://www.reddit.com/r/reactjs/comments/ys70t9/is_is_still_problematic_to_use_reactfc_if_our/?tl=ko

https://github.com/facebook/create-react-app/pull/8177

작년부터 저는 모아동이라는 대학교 동아리 서비스를 개발하여 지금까지 운영중이에요. 3월 5일 열리는 동아리 소개 한마당은 동아리에 마지막으로 지원할 수 있는 행사에요.

요구사항

3월 5일에 열리는 동아리 소개 한마당에서 사용되는 동아리 부스 지도를 만들어야 했어요. 테스트까지 생각하면 촉박한 시간이었기에 figma MCP를 사용해 빠르게 개발하는 것을 선택했어요.

codex에 figma mcp 연결

저는 터미널에서 codex를 쓰고 있었어요. 그래서 .codex/config.toml 에서 직접 수정해야 합니다.

권한 변경

[projects."/Users/..../Desktop/moadong"]
trust_level = "untrusted"

제가 작업하고 있는 디렉토리의 권한을 볼 수 있어요. 디폴트는 untrusted기 때문에 trusted로 바꿔야 합니다.

figma mcp 붙이기

ide는 Cursor를 사용하고 있어요. Cursor에서 MCP를 사용하기 위해 Remote MCP Cient 기능을 활성화해야 해요. 이는 외부 MCP 서버 (여기선 Figma MCP)에 연결이 가능하도록 만드는 스위치라고 보면 됩니다.

[features]
rmcp_client = true

이제 Figma MCP 서버 연결 정보를 넣어줍니다.

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

• url: Figma 공식 MCP 서버주소에요. Cursor는 여기로 API 요청을 보내요.
• bearer_token_env_var: 인증 토큰을 직접 쓰는 것이 아니라 환경변수에 저장된 값을 사용하도록 하는 설정이에요.

export FIGMA_OAUTH_TOKEN=피그마_토큰

이렇게 세팅되어야 해요. Cursor는 실행할 때

Authorization: Bearer <환경변수값>

이렇게 헤더를 붙여 Figma MCP에 요청을 보내요.

• http_headers: Figma MCP를 리전 기반으로 동작해요. 저는 us-east-1을 썼어요.

Figma token 발급

Figma Token은 홈에서 프로필 클릭하면 setting이 나오는데요. 거기서 Security를 보면 액세스 토큰을 발급할 수 있어요.

token 적용

token을 적용하는 것은 두 개의 방법이 있어요. mac인 경우 ~/.zshrc에

'export FIGMA_OAUTH_TOKEN=발급받은토큰'

이걸 저장하고 source ~./zshrc로 저장하면 됩니다.

두 번째는 mcp를 쓸 터미널에서 미리 'export FIGMA_OAUTH_TOKEN=발급받은토큰'를 입력하면 터미널에서 token을 사용할 수 있어요.

Figma node-id

저는 cursor ide에서 터미널로 codex를 켜서 작업했고, codex 실행 전에 터미널에 피그마 토큰을 주입하는 것으로 했습니다.

Figma에서는 node-id로 컴포넌트를 읽을 수 있습니다. https://www.figma.com/design/...?node-id=8847-8004&m=draw 컴포넌트를 클릭하면 이런 식으로 된 URL을 볼 수 있는데, node-id를 codex에게 던져주면 해당 컴포넌트를 읽을 수 있습니다.

Cursor - Codex - Figma MCP 통신 순서

실제로는 Cursor(또는 Codex 실행 환경)가 MCP 클라이언트 역할을 하고, Figma 공식 MCP 서버와 통신합니다. 요청은 내가 링크(노드 id 포함)를 입력하는 순간부터 아래 순서로 진행돼요.

1. 사용자 입력
   • Figma URL(예: ...?node-id=8851-6378)을 Codex에 전달
2. Codex가 node-id 추출
   • 링크에서 fileKey, node-id를 파싱해서 어떤 프레임을 읽을지 결정
3. MCP 서버 설정 확인
   • ~/.codex/config.toml의 [mcp_servers.figma] 설정 사용
   • bearer_token_env_var = "FIGMA_OAUTH_TOKEN"로 토큰을 환경변수에서 읽음
4. Figma MCP 서버로 요청 전송
   • Codex → https://mcp.figma.com/mcp
   • 헤더:
     • Authorization: Bearer
     • X-Figma-Region: us-east-1
5. Figma MCP가 Figma 데이터 조회
   • 해당 노드의 구조(텍스트, 레이아웃, 스타일), 메타데이터, 스크린샷/에셋 URL 반환
6. Codex가 결과를 코드로 변환
   • 반환된 디자인 컨텍스트를 기준으로 코드 생성/수정
   • 필요하면 여러 노드를 순차 조회해 화면 전체 구성 완성

요구사항 전달하기

내가 준 node-id 4개를 읽고 특정 파일 내에 동아리 부스지도 컴포넌트를 만들어줘.
아래 1/4 ~ 4/4 보여주도록 추가해주고 점선 누르면 슬라이드 이동도 가능해야해

결과적으로 기존 컴포넌트를 깨뜨리지 않으면서 요구사항과 동일하게 구현하는 데 성공했습니다. 프로젝트에서는 이미 Swiper 라이브러리를 사용하고 있었고, Codex가 프로젝트 구조를 파악한 뒤 기존 Swiper 기반 구조에 맞춰 슬라이드를 구현해주는 것을 확인할 수 있었습니다.

후기

작년 10월에도 Figma MCP를 이용해 컴포넌트를 구현한 적이 있었는데 그때는 픽셀도 제각각에다가 결과물도 좋지 않았어요. 제가 직접 구현하는게 더 빠를 정도였으니까요. 5개월이 지난 지금 Figma MCP의 성능은 훨씬 좋아졌고 직접 개발하는 것의 몇 배는 생산성이 높아졌어요.

조금 아쉬웠던 것은 카드 컴포넌트 내에 들어가는 여러 요소들의 위치를 하드코딩으로 구현한 것이었어요. 정말 껍데기만 잘 만들고 확장성이나 유지보수를 전혀 생각하지 않은 느낌이었어요.

이번 기능 개발은 딱 하루를 위한 기능이었기 때문에 확장성과 유지보수를 크게 고려하지 않아도 되기에 다시 수정하지는 않았습니다. 하지만 이후에도 간단한 컴포넌트는 Figma MCP로 개발해 볼 생각이에요. 확장성과 유지보수성을 프롬프트에 추가한다면 결과물이 또 어떻게 달라질지 궁금해지네요.

이번에는 Virtual 슬라이드의 개념과 쓰임에 대해 알아보려 한다.

Virtural 슬라이드의 내부동작

Virtual 슬라이드의 메소드 인터페이스는 virtual.d.ts에서 볼 수 있다.

Virtual 슬라이드에서는 일반 슬라이드 메소드인 appendSlide, prependSlide, removeSlide, removeAllSlides외에도 from, to, cache, slides, update를 가진다.

이 메소드들은 왜 더 필요할까? 그것은 DOM을 다루는 방식에 있다.

1. 일반 vs Virtual의 상태를 가지는 주인

일반 슬라이드

• 상태의 근원 = DOM
• 슬라이드 추가/삭제 = DOM에 append/prepend/remove
• Swiper는 DOM을 읽어 (recalcSlides, update) 내부 상태를 재조정

Virtual 슬라이드

• 상태의 근원 = virtual.slides배열
• DOM은 "화면에 필요한 만큼" 부분적으로 존재
• Swiper는 아래의 값들을 계산한다

    - 지금 화면에 어떤 인덱스를 보여줘야 할지 (from/to)
    - 지금 렌더링된 DOM을 어디에 놓아야 하는지 (offset)
    - 이미 만들어 둔 DOM을 재사용해야 하는지 (cache)

Virtual은 렌더링 엔진이 하나 더 붙은 구조라서, 인터페이스가 "상태+렌더 제어"까지 포함한다.

2. Virtual에 cache/from/to/update가 있는 이유

from, to

Virtual은 전체 슬라이드가 DOM에 없다. 그래서 "현재 렌더링된 구간"을 반드시 기억해야 한다.

• from = 현재 DOM에 존재하는 첫 슬라이드 인덱스
• to = 현재 DOM에 존재하는 마지막 슬라이드 인덱스

offset

Virtual은 일부만 DOM에 렌더링하기 때문에, 실제로는 "100번째 슬라이드부터 렌더링"해도 DOM상으로는 첫 번째처럼 보일 수 있다.

그래서 원래 위치처럼 보이도록 밀어주는 값이 필요하다.

가로면 left/right, 세로면 top을 사용한다. 실제로 React호환성 코드에서도 이 값을 style로 사용한다. react/virual.mjs

cache

Virtual은 계속 DOM을 만들었다가 지웠다를 반복한다. 매번 새로 만드는 비용을 줄이기 위해 한 번 만든 SlideEl을 저장해두고 재사용하는 방식으로 비용을 줄인다.

일반 슬라이드는 DOM에 계속 존재하기에 cache가 필요없다.

update

일반 슬라이드는 DOM을 추가하면 되지만, Virtual은 데이터만 바뀌면 DOM을 다시 맞춰 렌더링해야 한다.

그래서 virtual.update()는 아래와 같은 역할을 수행한다.

• activeIndex 기준 from, to 재계산
• DOM에 있어야 할 슬라이드만 남기고 교체
• offset 재적용

3. addSlide의 부재

• 일반 슬라이드: append / prepend / add / remove / removeAll
• Virtual: append / prepend / remove / removeAll / update

Virtual에 addSlide가 없는 이유는 중간 삽입은 배열 수정으로 하고 update만 호출하면 되기 때문이다.

4. React/Vue에서 Virtual을 지양한다

Only for Core version (in React & Vue it should be done by modifying slides array/data/source)

React와 Vue는 렌더링 주도권이 자신에게 있다.

만약 Swiper가 DOM을 직접 append, prepend하면 React의 Virtual DOM과 충돌한다.

5. Virtual 최적화

virtual.css에서는 Virtual 슬라이드의 성능이나 스크롤이 깨지지 않도록 한다.

핵심부분을 살펴보자면

translateZ(0)

• 해당 요소를 CPU 레이어로 올리는 역할이다. 스와이프 중 깜빡임이나 떨림을 방지한다.

backface-visibility: hidden

• 3D 변환 중 뒷면 렌더링으로 발생할 수 있는 텍스트 깨짐을 방지한다.

Virtual에서 이 부분들이 중요한 이유는 DOM을 계속 갈아끼우는 데에 있다. 그렇게 갈아끼운 DOM의 위치를 transform으로 재조정한다.

만약 GPU 레이어로 올리지 않으면 페인트 비용과 시각적으로 깨짐이 발생한다. 이것은 브라우저 렌더링 순서와 관련이 있다.

브라우저 렌더링 순서

1. style 계산
2. Layout (reflow) - 위치/크기 계산
3. Paint - 픽셀 비트맵으로 그림
4. Composite - 레이어 합성해서 화면에 출력

여기서 깨짐(flicker, jitter, tearing)은 대부분 Paint 단계에서 발생한다.

Virtual에서 일어나는 일

Virtual은 스와이프할 때마다 기존 슬라이드 DOM 제거 -> 새로운 슬라이드 DOM 삽입 -> 위치 재조정이 일어난다. 즉, 한 프레임 안에서 DOM 트리 변경, 위치 변경, 스타일 변경이 한꺼번에 일어나는 것이다.

CPU 레이어만 쓴다면

DOM 제거/추가는 reflow, 위치 변경은 repaint라 하면 브라우더 렌더링 순서 중 Layout -> Paint가 자주 발생하게 된다. 프레임 안에 다 못 끝낸다면 중간 상태가 화면에 노출된다.

Paint는 이전 비트맵 위에 변경된 영역만 다시 그리는 누적 비트맵이라 Virtual에서 Layout -> Paint 가 원자적으로 처리되지 않으면 앞에서 말한 "깨짐"이 발생한다.

GPU 레이어를 쓰면 달라지는 것

GPU 레이어의 특징은 이렇다.

• Layouy / Paint를 다시 안 함
• 이미 그려진 비트맵을 CPU에서 위치만 이동
• Composite 단계에서만 처리

그렇기에 요소를 별도의 합성 레이어로 분리함으로써 repaint가 아니라 composite단계에서 처리하는 것이다.

깨짐이 사라지는 이유도 프레임 단위로 레이어가 교체되기 때문에 중간 상태가 화면에 노출될 일이 없기 때문이다.

virtual에서 특히 중요한 이유

일반 슬라이드에선 DOM이 거의 고정되어 있고 위치 변화가 적다. 그렇기에 repaint 빈도가 낮은 반면, Virtual에서는 DOM을 자주 교체하여 offset이 계속 변경되므로 repaint 빈도가 높다.

CPU 레이어는 Virtual 슬라이드에서 일어나는 Paint를 감당할 수 없기에 GPU 레이어로 올린 것이다.

다음 챕터

Virtual 슬라이드를 알아보니 브라우저 내부 동작과 관련있다는 것이 신기했다. 다음은 React에서 Swiper가 어떻게 돌아가는지 알아볼 예정이다.

내부 동작이 궁금해 swipe 깃허브에서 코드를 보고 간단하게 정리해보았다.

Swipe 슬라이드 구분

Swipe 라이브러리에는 슬라이드 관리 방식이 크게 2가지가 있다.

1. 일반 슬라이드 (DOM 기반 슬라이드)

모든 슬라이드를 실제 DOM으로 다 만들어서 관리

• 슬라이드가 전부 .swipe-slide DOM으로 존재한다.
• appendSlide, removeSlide는 DOM을 직접 추가/삭제

언제 쓸까?

• 슬라이드 수가 적을 때
• 단순한 캐러셀, 배너
• 구현이나 디버깅이 쉬운 것을 원할 때

2. Virtual 슬라이드

슬라이드 데이터만 들고 있고 화면에 필요한 일부만 DOM으로 렌더링

• 전체 슬라이드는 JS배열로 관리한다.
• DOM에는 항상 현재 화면 주변 슬라이드만 존재한다.
• 스크롤/스와이프 시 DOM을 교체한다.

언제 쓸까?

• 슬라이드가 매우 많을 때
• 무한 스크롤
• React/Vue와 같이 Virtual DOM을 쓰는 환경

일반 슬라이드 내부 동작

일반 슬라이드의 메소드 인터페이스는 manipulation.ts에서 볼 수 있다.

이제 코드를 살펴보자.

1. addSlide

동작흐름

1. loop면 구조 해체
2. index 뒤 슬라이드 전부 잠시 제거
3. 새 슬라이드 삽입
4. 제거했던 슬라이드 다시 붙임
5. 전체 재계산 + loop 복구 + slideTo로 화면유지

핵심로직

// 1. index 이후 슬라이드들을 DOM에서 제거해서 임시 저장
const slidesBuffer = [];
for (let i = baseLength - 1; i >= index; i -= 1) {
  const currentSlide = swiper.slides[i];
  currentSlide.remove();
  slidesBuffer.unshift(currentSlide);
}

// 2. 새 슬라이드를 원하는 위치에 append
slidesEl.append(slides);

// 3. 제거했던 슬라이드들을 다시 뒤에 붙임
for (let i = 0; i < slidesBuffer.length; i += 1) {
  slidesEl.append(slidesBuffer[i]);
}

DOM에는 insertBefore 같은 고수준 API를 쓰지 않고 있다.

"뒤쪽 슬라이드 전부 빼고 -> 새 슬라이드 붙이고 -> 다시 붙인다" 전략을 쓰기 때문이다.

why

Swipe는 내부적으로 슬라이드 순서를 단순하게 slidesEl.children 순서로 관리하기 때문에 중간 삽입을 직접 지원하지 않는다. 그래서 물리적으로 DOM을 재배치하는 방식을 사용하고 있다.

2. removeSlide

동작흐름

1. loop 모드면 복제 슬라이드 때문에 loop 제거
2. 지정한 인덱스의 슬라이드 DOM 제거
3. activeIndex 보정
4. 슬라이드 목록 재계산
5. loop 복구
6. 화면 유지 (보던 슬라이드로 이동)

loop 모드에서는 앞/뒤에 복제 슬라이드가 붙어서 인덱스가 어긋나기에 loop를 제거한다.

핵심로직

// 1. 슬라이드 DOM 제거
swiper.slides[indexToRemove].remove();

// 2. 삭제로 인해 activeIndex 보정
if (indexToRemove < activeIndex) {
  activeIndex -= 1;
}

// 3. 슬라이드 목록 재수집
swiper.recalcSlides();

슬라이드 DOM을 제거하고, 그로 인해 밀린 activeIndex를 보정한 뒤 Swiper가 다시 계산하게 하는 것이다.

이외에도 모든 슬라이드를 제거하는 removeAllSlides가 있다.

3. appendSlide

동작흐름

1. loop 모드면 기존 loop 구조 제거
2. 슬라이드 DOM 추가 
    2-1. 문자열 -> 임시 DOM 생성 후 append
    2-2. HTMLElement -> 그대로 append
3. 슬라이드 목록 재계산
4. loop 복구 
5. 레이아웃과 상태 업데이트

핵심로직

// 1. 슬라이드 DOM에 추가
slidesEl.append(slideEl);

// 2. Swiper 내부 슬라이드 목록 재수집
swiper.recalcSlides();

복잡한 로직은 없었고 슬라이드 DOM 추가 -> Swipe가 변화를 인식하는 것이 다였다.

4. prependSlide

동작흐름

1. loop 모드면 기존 loop 구조 제거
2. 슬라이드 DOM을 맨 앞에 추가
    2-1. 문자열 → 임시 DOM → prepend
    2-2. HTMLElement → 그대로 prepend
3. activeIndex 보정 (앞의 슬라이드가 추가되었으므로)
4. 슬라이드 목록 재계산
5. loop 복구
6. 레이아웃과 상태 업데이트
7. 보던 슬라이드로 유지 

핵심로직

// 1. 슬라이드를 맨 앞에 DOM으로 추가
slidesEl.prepend(slideEl);

// 2. 앞에 추가됐으므로 activeIndex 보정
newActiveIndex = activeIndex + addedSlidesCount;

// 3. Swiper 내부 상태 재계산
swiper.recalcSlides();

슬라이드를 DOM 앞에 붙이고, activeIndex를 밀어준 뒤 Swipe가 다시 계산하게 한다.

간단정리

appendSlide → DOM 뒤에 추가

prependSlide → DOM 앞에 추가 + index 밀기

addSlide → DOM 재배치

removeSlide → DOM 제거 + index 당기기

다음 챕터

다음글에서는 Virtual 슬라이드 동작과 특징, 그리고 일반 슬라이드와 Virtural 슬라이드의 차이점과 쓰임에 대해 작성해보려 한다.

TDD, BDD, DDD 뒤에 붙은 DD(Driven Development) 에서 따온 단어인데요.

개발뿐만 아니라 협업에서도 주도하는 역할이 중요하다고 생각합니다. 저는 프론트엔드 개발자로서 여러 프로젝트에서 다양한 분들과 협업을 해 왔는데요. 프론트엔드 개발자가 할 수 있는 주도 개발에는 어떤 것이 있을 지 고민해 봤습니다.

프론트엔드가 하는 일

프로젝트에서 프론트엔드가 하는 작업은 UI/UX를 고려한 컴포넌트 설계 및 제작, api 요청응답 관리, 라우팅 설계, 최적화 작업 등 여러 가지가 있습니다.

이 중에서 저는 오늘 UI/UX와 api에 관련하여 프론트엔드가 주도할 수 있는 작업을 얘기하려고 합니다.

늦어지는 작업 속도

"디자인이 아직 없어서 컴포넌트를 제작할 수 없어."

"백엔드 api 구현이 안 되어서 api 연동을 못 하네. 일단 mock data로 대신해서 보여줘야 하나..?"

다들 프로젝트를 하면서 이런 경험을 한 번쯤 해 보셨을 것 같아요. 개발을 처음 시작했을 때는 이 간극을 어떻게 메워야 할 지, 팀원에게 어떤 식으로 얘기할 지 고민이 많았던 것 같습니다.

여러 프로젝트를 진행해 오면서 이 고민은 점점 커졌습니다. 어떻게 하면 디자이너-프론트, 프론트-백엔드 간의 작업 병목을 해소할 수 있을까 하고요.

Storybook으로 디자이너와 협업하기

Storybook은 React, Vue 등에서 사용되는 UI 컴포넌트를 효율적으로 관리할 수 있는 개발 도구입니다. 그 외에 Storybook에 대해 조금 더 알고 싶으시다면 React + Storybook 적용을 참고해주세요!

개발을 하다 보면 UI 컴포넌트가 많아져 폴더를 일일이 찾아봐야 하는 번거로움이 생길 때가 있습니다.

이때 Storybook을 사용하면, 현재 추가한 UI 컴포넌트들만 모아 볼 수 있어요. 버튼을 예로 들면 Button.stories.ts로 버튼 스토리를 추가할 수 있어요.

UI 컴포넌트가 많아질수록 추가해야 할 스토리 파일도 많아질 거에요. 저는 stories 라는 폴더에 스토리 파일들을 배치했어요. 컴포넌트 파일과 같이 두는 경우도 있지만 확장성을 고려한다면 저처럼 다른 폴더로 분리하는 것을 추천합니다.

Storybook 본 컴포넌트

스토리북을 설치하셨다면 npm run storybook으로 스토리북을 실행할 수 있어요.

왼쪽 파일들이 모두 stories.ts 파일입니다. 오른쪽엔 이름, 설명, 타입, 제어 등 다양한 속성이 존재해요.

import { Button } from '@/components/Button/Button';
import type { Meta, StoryObj } from '@storybook/nextjs';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
};

export default meta;
type Story = StoryObj<typeof Button>;

해당 코드는 Button 스토리 파일에서 기본으로 설정해야 하는 코드입니다. tags: ['autodocs'] 부분이 문서 페이지를 자동으로 생성해주는 부분이고요.

meta 객체는 스토리북 사이드바에 표시될 경로, 그리고 문서를 만들 대상 컴포넌트를 지정하는 핵심적인 설정이에요. 그 외 StoryObj 타입이나 export default meta 구문은 타입스크립트의 타입 안정성을 등록하기 위한 표준 보일러플레이트입니다.

Chromatic으로 배포

아직은 로컬에서만 보이는 스토리북을 배포할 수 있는 방법이 따로 있습니다. 바로 Chromatic이라는 도구입니다. netlify,vercel 같은 배포 도구가 있지만 chromatic은 배포 전에 컴포넌트를 미리 볼 수 있고, 무엇보다 스토리북에 최적화되어 있다는 것이 장점이기에 사용했습니다.

npm install --save-dev chromatic // 의존성 설치

npx chromatic --project-token <your-project-token> // 스토리북을 chromatic에 배포

명령어를 수행하면 추가한 스토리북 파일들이 chromatic에 배포됩니다. 실제로 제가 배포한 스토리북 배포링크 입니다.

디자이너에게 공유하기

위 링크는 서비스가 배포되기 전에 미리 디자이너에게 공유할 수 있습니다. 이것의 가장 큰 장점은 디자이너가 보는 UI와 개발자가 제작한 UI 간극을 최대한 줄일 수 있다는 것입니다.

이미 머지가 된 PR인데 갑자기 수정 요청이 오면 당황스럽겠죠. 또 자주 그런 일이 발생한다면 개발자나 디자이너 모두에게 부담이 될 것입니다.

💁🏻 개발 주도하기

일반적으로는 디자이너가 먼저 Figma 같은 디자인툴을 이용해 컴포넌트를 디자인하고, 개발자가 이를 코드로 구현하는 "디자인 주도 개발" 방식을 따릅니다.

하지만 개발자가 먼저 공통 컴포넌트를 만들고 디자이너에게 공유하는 개발을 주도할 수 있지 않을까요?

장점

심미적인 부분이나 UX적인 흐름보다 기능 구현에 초점을 맞춰 공유한다면, 디자이너는 기능적인 측면의 고민들보다 UX와 그 외 스타일 부분들에 집중할 수 있어요. 또한 빠른 프로토타입을 만들어야 할 때 유용합니다.

단점

물론 단점도 존재합니다. 디자이너가 나중에 컴포넌트를 보고 마음에 들지 않는다고 하면, 개발자는 다시 코드를 대폭 수정해야 하겠죠.

그럼에도 추천해요

프로젝트의 성격에 따라 개발을 주도할 수 있는 방법이 달라질 것 같은데요, 이런 방법도 가능할 것 같다~ 라는 하나의 예시로 봐 주시면 될 것 같아요. 그럼에도 불구하고 Storybook과 Chromatic을 사용하는 것은 프론트엔드와 디자인 간의 의사소통을 더 적극적으로 가능하게 하고, 작업 병목을 해소할 수 있는 아주 좋은 방법이라고 생각합니다.

백엔드와 협업하기

그 다음은 프론트엔드-백엔드 사이의 작업 병목을 해결하기 위해서 어떤 방법을 사용할 수 있을까에 대한 고민을 해 봤어요.

API 연동 프로세스

개발자는 API 개발을 하기 위해 해야 하는 여러 가지 단계가 있습니다.

➡️ API 명세서 작성 -> 프론트 UI 개발 -> 백엔드 API 개발 (기다려야 함) -> API 연동

여기서 백엔드 개발자가 API를 개발하기 전까지 프론트엔드는 기다려야 합니다.

추가적으로 생기는 귀찮음도 존재해요.

• 백엔드는 매번 mock api를 생성해주고 삭제해야 함
• mock api를 적용할 때와 아닐 때 api 주소를 변경해야 함

이때 MSW를 활용하여 프론트에서 미리 API 요청/응답을 모의 테스트할 수 있습니다.

msw

Mock Server Worker(msw)는 프론트엔드 개발에서 백엔드 개발이 완료되기 전에 API 요청을 가로채서 모의(mock)응답을 보내주는 라이브러리입니다.

msw 사용 방법

이제 msw 기본 설정에 필요한 핵심 코드들을 설명해보겠습니다.

API 핸들러 정의

📂 src/mocks/handlers.js

http는 어떤 HTTP 요청을 가로챌지 정의하는 메서드들의 모음입니다. 흔히 아는 HTTP 메서드명과 이름이 같아요. 실제 api 코드처럼 작성하면 됩니다.

단지 실제 api 요청을 보내는 것이 아니라, 요청을 백엔드 서버에 도착하기전에 가로챈다는 것이 차이점이에요.

HttpResponse는 http가 가로챈 요청에 대해 실제 브라우저에게 돌려줄 mock 응답을 쉽게 만들어줍니다. 가장 많이 사용되는 게 바로 HttpResponse.json() 메서드에요.

브라우저 환경 설정

📂 src/mocks/browser.js

이제 서비스 워커를 등록하여 mock 폴더에서 발생하는 모든 네트워크 요청을 서비스 워커가 감시하고 가로채도록 합니다.

과거 모킹 라이브러리에서는 fetch나 axios 함수 자체를 덮어쓰는 방식을 사용했다고 해요. MSW는 그보다 더 낮은 네트워크 레벨에서 서비스 워커를 통해 요청을 가로채기 때문에, 코드를 더 깔끔하게 유지할 수 있어요.

어플리케이션에 적용

MSW는 개발 환경에서만 실행되어야 하기 때문에 앱 진입점에 설정해야 할 부분이 있어요.

이제 development 환경에서만 msw가 실행되도록 변경했습니다. bypass 옵션은 핸들러애 정의되지 않은 요청을 실제 네트워크로 전달하도록 합니다.

💁🏻 개발 주도하기

➡️ API 명세서 작성 -> 프론트 UI 개발 -> 백엔드 API 개발 (기다려야 함) -> API 연동

다시 API 개발 프로세스를 가져오면, 이제 프론트엔드는 백엔드 API 개발이 완료되기 전에 기다림없이 API 요청과 응답을 테스트할 수 있어요.

실제 api 로직이 들어갈 부분에 mock api 코드를 추가하여 개발할 수 있고, 추후 백엔드에서 API 개발이 완료되면 mock api 부분을 실제 api 요청 코드로 변경만 하면 바로 연동이 가능합니다.

마무리

프론트엔드 개발자 입장에서 작업을 주도하는 방법에 대해 알아봤습니다.

글을 쓰면서 프론트 뿐만 아니라 백엔드, 디자이너 등 각 분야의 팀원이 주도할 수 있는 방법은 무엇일지 고민해봐도 좋을 것 같다는 생각이 들었습니다.

제 포스트가 팀프로젝트에 도움이 되었길 바라며 이것으로 마칩니다.

AI시대에 맞는 개발자를 교육하는 네이버 커넥트재단에서 운영하는 프로그램이다. 과정은 베이직, 챌린지, 멤버쉽로 총 3개로 구성되어 있다. 참고

모집 분야는 웹 풀스택, 모바일(ios, android)로 나누어져 있다. 프론트엔드 개발만 해 오다가 최근 백엔드에도 관심이 생겼었고, 마침 부스트캠프에 웹 풀스택 과정이 있는 것을 보고 지원하게 되었다.

베이직

2주동안 진행되는 챌린지 맛보기(?) 과정이다. 금요일을 제외하고 월목요일 동안 매일 나오는 미션을 풀고, 다른 사람의 코드를 리뷰한다. 리뷰가 필수는 아니지만, 다양한 방식의 풀이가 궁금해서 미션마다 23개 정도 리뷰를 했다.

챌린지에 입과하려면 베이직 과정과 문제 해결력 테스트까지 해야 한다. 문제 해결력 테스트를 보려면 베이직에 있는 모든 문제를 풀어야 해서 정말 열심히 했다.

문제 해결력 테스트

베이직이 목요일에 끝나고, 준비할 시간이 금요일밖에 없었다. 풀었던 미션을 보면서 부족했던 JS메소드를 숙지하고 갔다. 다행히 시험 환경에서 MDN 을 제공해줘서 생각 안 나는 메소드를 바로바로 찾아볼 수 있었다.

제한시간은 3시간이었고 코테 3개, 나머지는 CS 문제였다. (CS 문제가 좀 많았던 걸로 기억한다.) 1,2번을 풀고 나머지 시간은 CS 문제에 투자했다. 베이직에서 학습했던 내용이 생각보다 많았다. 제대로 학습하지 않았다면 힘들 수도 있기 때문에 베이직 과정을 착실히 해 낸 사람이 유리해보였다.

엄청 잘 본 것도, 그렇다고 못 본 것도 아닌 애매한 느낌이었다. 다행히 챌린지가 되어서 더더 열심히 해야겠다는 생각이 들었다.

챌린지

주말을 제외하고 한 달 동안 매일매일 미션을 풀어야 한다.

이 과정이 가장 힘들었다. 매일 1019는 코어 타임, 1012는 동료들과 실시간 피드백 및 피드백 작성으로 구성되어 있다. 지금와서 보면 코어 타임은 의미가 없었던 것 같다. 하루종일 해야 하기 때문이다. 매일 새벽에 잤는데, 매일매일 문제를 풀어야 하고 멤버쉽에 떨어지면 어떡하지 하는 불안감 때문에 더 열심히 했다.

🏃챌린지 전의 나

나는 프로젝트를 위한 공부만 해 왔기에, 필요할 때마다 찾아보고 적용하는 방식으로 학습했다. 단점은 빠르게 휘발되어서 시간이 지나면 잘 기억이 안 났다.

전공에서 배운 CS지식은 하나도 기억이 안 나고, 진정 내가 전공생인가 의구심이 들 정도였다.

🥕얻은 것

챌린지에서는 학습 내용과 리드미를 추가로 작성해야 한다. 하루에 하나의 미션을 풀어야 하기에 학습과 구현의 밸런스를 잘 찾아야 한다.

주차가 지나면서 시간 분배가 정말 중요하다는 것을 느꼈다. 또한 너무 깊은 학습은 오히려 야크털을 깎는 행위라는 것이다. (멘토분께서 이렇게 표현하셨다.)

처음에는 야크털을 많이 깎으면서 시행착오를 많이 겪었고, 점점 학습과 구현의 밸런스를 찾아갔다. 학습을 많이 한다고 미션이 잘 해결되는 것이 아니고, 구현에만 집중해도 기억에 잘 남지 않았다. 그래서 각 미션마다 내가 얻어가고 싶은 것에 집중했다.

챌린지의 끝

미션이 어려워 스스로 타협하는 순간도 있었고, 잠을 줄이면서 열심히 했던 순간도 있었다. 그러다보니 모르는 것 자체에 면역이 생겼다. 모르면 또 학습하면 되지 하는 마인드가 자연스럽게 생겼고 나에게 맞는 구현-학습 사이클이 생긴 것을 체감했다.

가장 큰 수확은 CS 지식이 모든 문제 해결의 근간이라는 것을 깨닫게 된 것이다. 학교에서 배울 때는 정말 먼 얘기처럼 들렸는데, 부스트캠프에서는 실제로 CS지식이 어떻게 활용되는지 이해할 수 있었다.

결과는 합격이었다.. 마음속으로는 안 되면 어떡하지 하는 생각이 정말 많이 들었다. 챌린지를 잘 끝낸 나에게 정말 고생했다고 말해주고 싶고, 부족한 만큼 더 열심히, 잘 하고 싶다.

이전 포스팅에서는 깃허브 이슈와 지라 이슈 자동화에 대한 워크플로우를 만들어봤습니다. 하지만 지라 이슈의 담당자를 직접 설정해줘야 하는 문제가 있었습니다. 이 부분을 자동화하지 않으면 워크플로우의 의미가 없다고 생각했어요. 그래서 이번엔 이슈 담당자 자동화를 해 보았습니다.

이슈 템플릿에 Assignee추가

먼저 이슈 템플릿에서 Assignee를 드롭박스에서 선택할 수 있도록 만들었어요. 이슈 템플릿 링크

터미널에서 accountId 찾기

깃허브 Assignee에 나오는 이름은 깃허브 닉네임이에요. 이것은 Jira에서 호환이 안 되겠죠. Jira에서 담당자를 설정하려면 각 담당자의 accountId를 알아야 합니다. 터미널에서 아래 명령어를 입력하면 기본적으로 50명의 사용자의 정보를 반환합니다.

curl -u <email>:<api_token> "https://<your-domain>.atlassian.net/rest/api/3/user/search"

원래는 제일 뒤에 /query=사용자이름으로 찾으려 했지만 잘 안 되었어요. 한글 문제인가 싶어서 영어를 입력했는데도 404가 뜨더군요. 그래서 위 명령어를 입력해서 손수 노가다로 accountId를 찾았습니다.

깃허브 지라 간의 매핑 테이블 만들기

위에서 찾은 accountId와 깃허브 Assignee를 매핑한 테이블을 만들 차례입니다. 이것은 지라 워크플로우에 들어갈 필수적인 요소에요.

{
  "seongwon030": "accountId1",
  "oesnuj": "accountId2",
  "Zepelown": "accountId3",
  "Due-IT": "accountId4",
  "PororoAndFriends": "accountId5",
  "lepitaaar": "accountId6",
}

이렇게 json형식으로 만들어줍니다. accountId부분은 임의로 넣었어요.

accountId 보안 위험

accountId를 깃허브에 노출하면 해당 accountId로 api요청 시 displayName이 노출될 우려가 있습니다. 사용자 실명 유추가 가능한 것이죠. 또한, 조직 내 특정 유저가 존재한다는 사실이 노출되어 피싱 공격이 가능합니다.

repository secret으로 설정

repository -> setting -> Secrets -> Secrets and variables -> Actions 으로 이동한 다음, New repository secret 를 클릭합니다.

기존 워크플로우 수정

common-jira-create.yml

      - name: Map GitHub username to Jira accountId
        id: assignee
        run: |
          echo '${{ secrets.JIRA_USER_MAP }}' > user_map.json
          FORM_ASSIGNEE="${{ steps.issue-parser.outputs.issueparser_assignee }}"
          ACCOUNT_ID=$(jq -r --arg user "$FORM_ASSIGNEE" '.[$user]' user_map.json)

          echo "Resolved accountId for $FORM_ASSIGNEE → $ACCOUNT_ID"
          echo "accountId=$ACCOUNT_ID" >> $GITHUB_OUTPUT

1. secrets.JIRA_USER_MAP이라는 JSON 문자열을 user_map.json으로 저장합니다.
2. GitHub 이슈 템플릿에서 추출한 assignee 값을 $FORM_ASSIGNEE에 저장합니다.
3. jq를 사용해서 해당 사용자명의 Jira accountId를 추출합니다.
4. GITHUB_OUTPUT에 accountId를 저장해서 다음 step에서 사용 가능하게 만듭니다.

중요한 것은 Login 워크플로우 후에 해당 작업이 수행되어야 한다는 것입니다. 로그인을 하지 않는다면 accountId를 식별하지 못 할 것입니다.

워크플로우 테스트

먼저 이슈를 생성합니다.

이제 지라에 이슈가 생성되었는지 확인합니다. 아래처럼 이슈가 잘 생성된 것을 확인할 수 있습니다.

마지막으로 담당자도 잘 할당되는 것을 볼 수 있습니다.

Atlassian에서 개발한 프로젝트 관리 및 이슈 추적 도구로, 주로 소프트웨어 개발팀에서 사용됩니다. 애자일 방식에 유용하며, 칸반, 스크럼 등 다양한 방법론을 지원합니다.

처음엔 그냥 ..

프로젝트를 도중에 '깃허브 프로젝트 기능보다 더 나은 도구가 없을까?'하는 생각이 들었습니다. 깃허브 프로젝트는 TODO, INPROGRESS, DONE 세 가지로 프로젝트 진행 상황을 관리하며, 추가로 Milestone으로 스프린트 또한 관리할 수 있습니다.

깃허브 프로젝트를 도입하려던 찰나에 Jira라는 협업 도구가 제 눈에 띄었습니다. 애자일 프로세스에 유용하다는 것을 알게 되었고, 먼저 프론트엔드 이슈에 도입하였습니다.

사실 큰 이유는 없었어요. 저희 팀이 프론트엔드, 백엔드, 디자이너로 구성된 팀이었고 회의 때마다 각자의 진행상황을 공유했습니다. 하지만 실시간으로 각자의 진행상황을 파악하기 힘들었어요. 카카오톡으로 일일이 묻기 번거롭고, 계속 묻는 것도 서로에게 부담일 거니까요. 개발자들은 디스코드 웹훅으로 어떤 이슈가 올라갔는지 실시간으로 알 수 있었지만, 작업들을 모아보기도 힘들었어요.

FE만 워크플로우 만들기

저는 여러 자료를 찾아보면서 깃허브 이슈와 지라 이슈를 연동하는 방법을 알게 되었습니다. 해당 워크플로우는 다음과 같습니다.

1. 깃허브에서 이슈를 생성한다.
2. Title과 Description을 작성한다.
3. FE-번호 형식에 맞게 티켓 넘버를 작성한다.
4. 브랜치명을 적는다.
5. create를 한다.

이렇게 하면 자동으로 브랜치명에 이슈 넘버와 티켓넘버가 붙도록 만들었어요. 예를 들면, FE-11 티켓넘버에 브랜치명은 feature/add-login-ui라고 가정했을 때 최종 브랜치명은 feature/#깃허브이슈번호-add-login-ui가 됩니다. 깃허브 이슈번호는 생성한 이슈에서 바로 가져오는 방식이에요. 해당 코드는 여기서 보실 수 있어요. create-jira-issue.yml

초반에는 백로그 없이 보드로만 작업을 했어요.

장점

브랜치를 생성할 때 이슈넘버를 확인하지 않아도 되어 정말 편해졌습니다. 보드로 작업 진행도를 파악하기도 쉬워졌어요.

단점

하지만 깃허브 프로젝트와 다를 게 없다는 생각이 들었습니다. 보드 그 이상의 기능을 활용할 수 없었어요. 모든 팀원이 사용해야 스프린트, 백로그의 의미가 생기고 모든 작업의 진행도를 파악할 수 있으니까요.

드디어 이유가 생겼다

저번주에 갑자기 팀장님이 Jira를 사용하는 게 어떠냐고 모든 팀원들에게 물어보셨습니다. 부트캠프에서 여러 현직자분들을 만나셨는데, 거의 다 Jira를 사용한다는 얘기를 들었다고 하셨어요. 그래서 팀원 모두의 찬성으로 저희 팀 모두가 Jira를 사용하기로 했어요.

저희가 쓰던 FE프로젝트는 놔두고, 새로운 프로젝트를 만들었습니다. 새로운 프로젝트에도 이슈가 생성되도록 워크플로우를 추가했습니다.

깃허브 jira 연동하기

기존의 워크플로우는 무조건 develop-fe 브랜치에서 분기되었었는데, 이제는 모든 브랜치에서 분기가 가능하도록 해야 합니다. 프론트엔드, 백엔드 모두가 써야하기 때문입니다.

이슈템플릿 변경하기

이슈 템플릿 링크

분기할 브랜치 선택 항목을 추가하여, 어떤 브랜치든 분기할 수 있도록 만들었어요.

워크플로우 변경하기

common-jira-create.yml 입력한 브랜치에 대해 브랜치를 분기하도록 변경하였습니다. 추가로 기존에 없는 브랜치라면 워크플로우를 미리 중단하도록 했어요.

결과 확인하기

깃허브 이슈를 생성하니 지라에도 이슈가 잘 생성되네요!

close-jira-issue.yml 이것은 깃허브 이슈 닫기 시 지라 이슈를 완료상태로 변경해주는 코드입니다.

마치며

팀원 모두가 Jira를 사용하게 되어 기쁩니다. 스프린트, 백로그, 회고까지 애자일 프로세스를 적극 경험해보고 싶네요. 사용자를 만나면서 백로그를 작업하는 경험이 제일 기다려지네요. 피드백 환영합니다~!

Sentry는 어플리케이션에서 발생하는 에러를 자동으로 감지하고 추적합니다. 에러는 매일 감지되며 ip, 브라우저 정보, os정보 등 세부적인 정보를 제공합니다.

Sentry공식문서에서 볼 수 있듯이 여러 언어, 프레임워크를 지원합니다.

왜 사용할까?

지금 진행 중인 moadong 프로젝트가 얼마 전 사용자에게 배포되었습니다. 배포하고 나서 문득 그런 생각이 들었습니다. "사용자에게 보이는 에러는 어떻게 방지하지?"

로컬에서 발생한 에러는 개발자 눈에 보이기 때문에 바로 고칠 수 있습니다. 반면 사용자에게 에러가 났을 때 언제 에러가 발생했는지, 무슨 에러인지 파악할 수 없습니다. Sentry는 로컬 환경이 아니어도 배포 주소만 설정하면 사용자에게 뜨는 모든 에러를 추적할 수 있습니다. 더 세세한 에러에 대처하고, 사용자에게 최대한 편한 UI/UX를 제공하기 위해 저희 프론트엔드 팀은 Sentry를 적용하기로 하였습니다.

적용하기

시작하기

Sentry에 먼저 접속해줍니다.

여기서 GET STARTED 를 눌러줍니다.

로그인

여기서 저는 깃허브 계정으로 로그인하였습니다.

Organization 만들기

Sentry내에서 쓸 Organization을 만듭니다. 이름은 자유롭게 지어주시면 됩니다. Data Storage Location은 US로 설정해주었습니다.

플랫폼 설정

React를 클릭해줍니다.

아래 설정은 자유롭게 해주세요. 그 다음 Create Project를 합니다.

라이브러리 설치

위 사진처럼 자신의 프로젝트 폴더에서 npm install --save @sentry/react를 합니다.

SDK 설정

주의 : dsn에 나와있는 key는 자신의 sentry 프로젝트에 부여된 고유한 key이기 때문에 노출하면 안 됩니다. 해당 키를 .env파일에 설정해 주세요.

추가로 제 프로젝트에서는 여러 sdk를 사용하고 있었기에 initSDK.ts 파일을 따로 생성한 다음 각각 함수로 묶어주었습니다.

// initSDK.ts
export function initializeSentry() {
  if (process.env.NODE_ENV === 'development') {
    return;
  }

  Sentry.init({
    dsn: process.env.SENTRY_DSN,
    sendDefaultPii: false,
    release: process.env.SENTRY_RELEASE,
    tracesSampleRate: 0.1,
  });
}

// index.tsx
import {
  initializeSentry,
} from './utils/initSDK';

initializeSentry();

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement,
);
root.render(<App />);

error 테스트

로컬에서 에러를 테스트하기 위해 먼저 if (process.env.NODE_ENV === 'development') 를 주석처리 해 둡니다.

그리고 나서 임시로 error 코드를 작성합니다.

import React from 'react';
import * as Styled from './Footer.styles';

const Footer = () => {
  return (
    <>
      <Styled.FooterContainer>
        <Styled.Divider />
        <Styled.FooterContent>
          <Styled.PolicyText>개인정보 처리방침</Styled.PolicyText>
          <Styled.CopyRightText>
            Copyright © moodong. All Rights Reserved
          </Styled.CopyRightText>
          <Styled.EmailText>
            e-mail:{' '}
            <a href='mailto:pknu.moadong@gmail.com'>pknu.moadong@gmail.com</a>
            <button
              onClick={() => {
                throw new Error('test');
              }}
            >
              test
            </button>
          </Styled.EmailText>
        </Styled.FooterContent>
      </Styled.FooterContainer>
    </>
  );
};

export default Footer;

당연하게도 로컬에서는 에러가 발생할 것입니다.

예상대로 에러가 잘 나옵니다. 그럼 이제 Sentry에 해당 에러가 추적되었는지 확인해봅시다.

Sentry 이벤트 화면

이벤트 목록에서 에러가 잘 뜨는 것을 확인할 수 있습니다.

이벤트 수, 유저 수를 보여줍니다. 브라우저 정보, 릴리즈(개발 및 배포 환경), URL, environment(어떤 환경에서 발생했는지) 등을 볼 수 있습니다.

여기선 어떤 동작이 에러를 발생시켰는지 볼 수 있습니다. 문자가 이상하게 나오는 것은 소스맵 문제입니다. 해당 내용도 추후에 추가할 예정입니다.

배포 서버 설정

저는 netlify에서 배포하고 있었기 때문에 deploy settings의 environment에 새로운 variables로 dsn을 설정해주었습니다. 환경변수를 추가하지 않으면 배포 사이트 에러를 추적할 수 없기에 꼭 해주셔야 합니다.

디스코드 웹 훅 연동

저희 팀은 디스코드와 깃허브를 연동하여 작업 시 활발하게 사용 중이었습니다. sentry에도 웹 훅 연동 기능이 있어서 겸사겸사 연동을 해 보았습니다.

organization settings -> Integrations -> Discord 순입니다.

Add Installation을 누르면 아래와 같은 창이 나옵니다.

여기서 프로젝트 Discord를 선택하고 승인을 눌러줍니다.

승인이 완료되면 알람 세팅을 할 수 있습니다. 어차피 개발 서버에서 실행되지 않기에 All Environments로 설정해 줍니다. 저는 간단하게 이슈 생성 시(에러 발생)에 알람을 주도록 하였습니다.

두번째 설정은 자유롭게 해 주시면 됩니다. 중요한 것은 세 번째 설정인데, 여기서 알림을 받을 디스코드 채널 Id를 입력해야 합니다.

나머지 설정도 완료한 다음 Save Rule을 합니다. 이제 디스코드 알림이 오는지 확인하겠습니다.

잘 오는 것을 볼 수 있습니다. Assign은 해당 에러를 팀원에게 할당하는 기능입니다. 에러를 해결했다면 Resolve를 합니다.

마치며

이상으로 Sentry 설정과 디스코드 연동까지 해 보았습니다. 지금까지 에러는 개발자에게만 일어나는 것이라 생각했습니다. 사용자에게 배포하고 나서 에러에 대한 시각이 더 넓어진 느낌이 들었습니다. 이제부터 사용자에게 불편함 없이 서비스를 제공하기 위해 한 층 더 나아가 보려고 합니다.

객체를 선언하고 그 key를 타입으로 쓰고 싶다면 무조건 as const를 붙이고 keyof typeof를 쓴다.

1. 버튼 타입 제한

const BUTTON_TYPES = {
  primary: 'Primary Button',
  secondary: 'Secondary Button',
  danger: 'Danger Button',
} as const;

type ButtonType = keyof typeof BUTTON_TYPES;
// ButtonType = 'primary' | 'secondary' | 'danger'

interface ButtonProps {
  type: ButtonType;
}

const Button = ({ type }: ButtonProps) => {
  return <button>{BUTTON_TYPES[type]}</button>;

• 버튼 타입 prop은 'primary' | 'secondary' | 'danger'만 가능하다.
• 실수로 'Third' 를 넣으면 컴파일 에러가 난다.

2. API 요청 타입 강제

const API_ENDPOINTS = {
  getUser: '/api/user',
  getPosts: '/api/posts',
  getComments: '/api/comments',
} as const;

type ApiType = keyof typeof API_ENDPOINTS;
// 'getUser' | 'getPosts' | 'getComments'

function fetchApi(api: ApiType) {
  return fetch(API_ENDPOINTS[api]);
}

• fetchApi('getPosts') 처럼 사용한다.
• 없는 API 이름 쓰면 에러 발생.

3. 테마 설정

const THEMES = {
  light: 'Light Mode',
  dark: 'Dark Mode',
  system: 'System Default',
} as const;

type ThemeType = keyof typeof THEMES;
// 'light' | 'dark' | 'system'

function setTheme(theme: ThemeType) {
  console.log(`Setting theme to ${THEMES[theme]}`);
}

• setTheme('light') or setTheme('dark')

4. key 매핑해서 타입 변환하기

키를 이용해 새로운 타입 만들기

const THEMES = {
  light: 'Light Mode',
  dark: 'Dark Mode',
  system: 'System Default',
} as const;

type ThemeValue = {
  [K in keyof typeof THEMES]: string;

{
  light: string;
  dark: string;
  system: string;
}

➡️ ThemeValues 타입의 모습입니다. 객체의 키들을 순회하며 새로운 타입을 만들 수 있으며, 이것을 Mapped Type 이라 합니다.

5. 키 값(value)에 따라 타입 달리하기

const API_ENDPOINTS = {
  getUser: '/api/user',
  getPosts: '/api/posts',
  deletePost: null,
} as const;

// value가 null이면 optional, 아니면 required로
type ApiFunctions = {
  [K in keyof typeof API_ENDPOINTS]: type of API_ENDPOINTS[K] extends string
      ? () => Promise<void>
    : never;
};

• extends는 타입 상속과 타입 검사에 둘 다 사용됩니다. 여기서는 string인지 검사합니다.
• 'getUser', 'getPosts'는 () => Promise 타입으로 매핑
• 'deletePost'는 never로 매핑

언제 사용할까?

• 정해진 키들만 쓰도록 할 때
• props 안전하게 하고 싶을 때
• 객체의 키들을 타입으로 안전하게 뽑아내고 싶을 때

string 리터럴 사용하면 안 되나?

type ColorKey = 'red' | 'blue' | 'green';

-> 리터럴로 직접 쓰기.

  const COLORS = {
  red: '#ff0000',
  blue: '#0000ff',
  green: '#00ff00',
  yellow: '#ffff00',  // 새로운 색 추가
} as const;

여기서 만약 새로운 프로퍼티를 추가해야 하는 상황이라면?

// 기존
type ColorKey = 'red' | 'blue' | 'green';

// yellow 추가했으니까 여기도 수정해야 함
type ColorKey = 'red' | 'blue' | 'green' | 'yellow';

객체를 바꿀 때마다 타입도 수동으로 수정해야 합니다. 이것은 매우 비효율적입니다.

keyof typeof 쓰기

type ColorKey = keyof typeof COLORS;  

객체가 바뀌면 타입도 자동으로 따라갑니다.

프로젝트에 적용해보기

1. 믹스패널 track 이벤트를 클릭함수 내에 적용해야 한다.
2. 데스크탑 home 버튼과 모바일 home버튼에 각각 다른 이벤트를 적용해야 한다.

trackEvent 타입

 const trackEventNames = {
  desktop: 'Home Button Clicked',
  mobile: 'Mobile Home Button Clicked',
} as const; 

Click 함수에 매개변수로 전달하기

const handleHomeClick = (device: keyof typeof trackEventNames) => {
    navigate('/');
    setKeyword('');
    setInputValue('');
    trackEvent(trackEventNames[device]);
};

마치며

프로젝트를 하면서 타입스크립트를 그때그때 배우고 있지만 항상 새롭습니다. 그래도 그때그때 배우는게 기억에 제일 잘 남는 것 같아요. 피드백은 언제나 환영입니다!

즉, 현재 보이는 카드 부분만 사용자에게 보여주면 된다는 것입니다. 만약 모든 카드를 렌더링마다 불러오게 된다면, 사용자에게 보이지 않는 카드들 모두 가져오게 됩니다. 이는 불필요한 이미지 렌더링이 일어나게 되고 성능에도 문제가 발생합니다.

그래서 현재 카드 부분이 보일 때만 카드를 렌더링 하도록 하고 싶었습니다. 자바스크립트에서는IntersectionObserver라는 API를 제공합니다. MDN

해당 API로 이미지가 뷰포트에 들어왔을 시에만 이미지를 지연로딩하는 컴포넌트를 제작하였습니다. 참고로 리액트 + 타입스크립트 조합입니다.

이미지 Props

interface LazyImageProps {
  src: string;        // 로드할 이미지 주소
  alt: string;        // 이미지 설명 (접근성용)
  onError?: () => void; // 이미지 로드 실패 시 콜백
  index?: number;     // 리스트일 경우 지연 순서 지정
  delayMs?: number;   // 각 이미지 로딩 간의 지연 시간
}

상태 정의

const [shouldLoad, setShouldLoad] = useState(false);
const [isVisible, setIsVisible] = useState(false);

• shouldLoad : 이미지 로드를 시작할지 여부
• isVisible : 이미지 렌더링 여부

ref

const imgRef = useRef<HTMLImageElement | null>(null);

• dom 요소 추적으로 IntersectionObserver가 관찰할 수 있도록 함

뷰포트 감지

useEffect(() => {
  const observer = new IntersectionObserver(([entry]) => {
    if (entry.isIntersecting) {
      const delay = index * delayMs;
      const timeout = setTimeout(() => {
        setShouldLoad(true);
      }, delay);
      observer.disconnect();

      return () => clearTimeout(timeout);
    }
  }, { threshold: 0.1 });

  if (imgRef.current) {
    observer.observe(imgRef.current);
  }

  return () => observer.disconnect();
}, [index, delayMs]);

• 이미지가 뷰포트에 10% 이상 들어오면 -> threshold: 0.1
• index * delayMs만큼 기다렸다가 setShouldLoad(true)
• 이는 로딩이 시작되었다는 뜻입니다. 그렇다면 요소를 더 이상 관찰할 필요가 없기에 observer.disconnect()로 중지합니다. (disconnect는 모든 요소, unobserve()는 특정요소입니다.)

이미지 로딩

useEffect(() => {
  if (shouldLoad) {
    setIsVisible(true);
  }
}, [shouldLoad]);

렌더링

return isVisible ? (
  <img ref={imgRef} src={src} alt={alt} onError={onError} />
) : (
  <div ref={imgRef} ... /> // placeholder
);

이미지가 아직 안 보이면 placeholder를 렌더링합니다. 로드가 시작되면 진짜 이미지로 교체합니다.

마치며

제가 만든 컴포넌트는 뷰포트에 하나의 카드 + 두 번째 카드의 10분의 1의 정도 보이는 구조였습니다. 만약 뷰포트에 거의 하나의 요소만 들어간다면 index * delayMs를 추가하는 것은 필수는 아니라는 생각이 드네요.

결과적으로 카드 인덱스가 낮은 순으로 순차적 렌더링이 됨을 확인할 수 있었습니다. 원한다면 onError 함수에 fallback 이미지로 대체하여 에러 방지도 할 수 있습니다.

Keep

• 깃허브와 디스코드, jira 연동으로 변경사항 추적이 쉽고 간편해졌다.
• 사용한 기술에 대해 기록하는 습관을 들였다.
• 더 좋은 리뷰에 대해 고민하는 시간이 많다.
• 디자인 시스템인 스토리북을 도입하고 사용했다.
• jest를 도입하고 단위테스트를 학습했다.
• 요구사항 개발에 대한 날짜를 정한 뒤 마감일을 지켰다.
• 연락을 자주 봄으로써 매끄럽게 개발을 진행했다.

Problem

• 명확한 이유없이 jira를 도입했다.
• 디자인시스템 도입 후 제대로 활용하지 못했다.
• pr에 리뷰요청을 한 뒤 개인적으로 연락을 한 적이 많았다. (컨벤션에 있던 1일을 기다리지 않고)
• 세 개의 프로젝트를 진행하면서 한 가지 일에 제대로 집중하지 못 했다.
• 회고없이 기능 개발과 회의만 진행했다.
• 새벽에 개발을 하면서 아침 시간을 잘 활용하지 못 했다.
• 급하게 merge해야 하는 상황에서 양질의 리뷰를 하지 못했다.
• 여러 가지 일을 하면서 스트레스 관리가 어려웠다.

Try

• jira를 도입한 이유를 명확히 하고, 우리 팀에 필요한 것인지 조금 더 고민해본다.
• 리뷰 시간은 컨벤션대로 기다린다.
• 디자인 시스템을 활용해 디자이너와 협업한다.
• 늦어도 새벽 2시에는 잔다.
• 아침 9시 데일리 미팅에 늦지 않기.
• 사용한 기술에 대해 조금 더 깊은 공부를 해 본다. ex) tanstack-query
• jest로 단위 테스트를 한다.
• 팀 역량을 끌어올리는 팀원이 되도록 노력한다.

여기서 Get a free trial을 클릭합니다.

저는 github와 바로 연동하기 위해 Sign up with Github를 클릭해 주었습니다.

깃허브 내에서 코드래빗을 적용하고 싶은 레포지토리를 연결해줍니다.

연결이 완료되면 왼쪽 메뉴에 대시보드와 여러 세팅이 보입니다.

여기서 Organization Settings -> Configuration 으로 갑니다. 여기서 Review Language를 Korean으로 설정한 다음 오른쪽 위 Apply Changes를 눌러주면 설정 완료입니다.

이제 PR에 코멘트를 달아주는지 확인해 봅시다.

리뷰가 스킵되었네요. Review -> Auto Review 설정을 해 준다면 자동을 리뷰를 해 줄 겁니다.

하지만 제 리뷰는 이미 스킵되었기 때문에 강제로 리뷰를 시켜야겠습니다. 위에 코멘트를 보시면 @coderabbitai review로 강제 리뷰를 할 수 있다고 합니다.

Quote reply로 해당 명령을 치고 comment를 눌러줍니다.

그러면 코드래빗이 pr에 올라간 커밋들을 모두 검사하여 리뷰를 달아줍니다.

코멘트에 대한 답도 해 주는군요.

시퀸스 다이어그램까지 만들어주네요.

변경사항

pr 자동 리뷰가 되지 않은 건 설정을 빼 먹었기 때문입니다.. 먼저 organization settings로 다시 갑니다.

가장 아래 Base Branches 부분에 .* 를 입력하고 엔터를 누른 뒤 apply changes 하면 전체 브랜치에 대한 pr에 자동으로 리뷰하겠다는 뜻입니다.

만약 특정 브랜치에만 리뷰하도록 하려면 feature/* 같이 설정해주시면 됩니다.

또한, coderabbit.yaml로 설정하는 방법도 있습니다. 자신의 프로젝트 루트 폴더에 해당 파일을 추가하면 가능합니다.

language: 'ko-KR'
early_access: false
reviews:
  profile: 'chill'
  request_changes_workflow: false
  high_level_summary: true
  poem: false
  review_status: true
  collapse_walkthrough: false
  auto_review:
    enabled: true
    drafts: false
    base_branches:
      - "/*"
chat:
  auto_reply: true

여기서 원하는대로 수정하여 사용하시면 됩니다!

마치며

자동 코드리뷰를 해 주는 것은 너무 편리한 기능인 것 같습니다. 하지만 ai가 언제나 정답일 수는 없기에 저희 팀에서는 팀원 간 리뷰 후 명령어를 사용하여 코드래빗으로 추가적인 리뷰를 받는 방식을 선택했습니다!

moadong

이번에 메인페이지에 들어갈 캐러셀을 제작하게 되었습니다.
Typescript와 styled-component를 사용하였고 반응형과 무한 캐러셀 동작에 집중하였습니다.

기능 요구사항

• 좌우 버튼을 눌러 배너를 슬라이드할 수 있어야 한다.
• 자동으로 3초마다 배너가 이동한다.
• 첫 번째 배너에서 이전 버튼을 누르면 마지막 배너로 이동해야 한다.
• 마지막 배너에서 다음 버튼을 누르면 첫 번째 배너로 이동해야 한다.
• 창 크기가 변경되면 슬라이드 크기가 자동 조정되어야 한다.

구현 과정

1. 무한 루프를 위한 슬라이드 배열 확장

const extendedBanners = [banners[banners.length - 1], ...banners, banners[0]];

2. 슬라이드 크기 동적 업데이트

  const [currentSlideIndex, setCurrentSlideIndex] = useState(1); 

const updateSlideWidth = useCallback(() => {
  if (slideRef.current) {
    setSlideWidth(slideRef.current.offsetWidth);
    slideRef.current.style.transform = `translateX(-${currentSlideIndex * slideRef.current.offsetWidth}px)`;
  }
}, [currentSlideIndex]);

currentSlideIndex는 현재 슬라이드 인덱스를 저장하고, updateSlideWidth 함수는 currentSlideIndex가 변경될 때마다 실행됩니다.

현재 슬라이드가 있다면 현재 슬라이드 width 값을 가져와 슬라이드 너비를 업데이트합니다.

3. 슬라이드 이동 로직

const [isAnimating, setIsAnimating] = useState(true);
const [isTransitioning, setIsTransitioning] = useState(false);

const moveToNextSlide = useCallback(() => {
  if (isTransitioning) return;
  setIsTransitioning(true);
  setIsAnimating(true);
  setCurrentSlideIndex((prev) => prev + 1);
}, [isTransitioning]);

const moveToPrevSlide = useCallback(() => {
  if (isTransitioning) return;
  setIsTransitioning(true);
  setIsAnimating(true);
  setCurrentSlideIndex((prev) => prev - 1);
}, [isTransitioning]);

isAnimating는 애니메이션 상태를 관리합니다. isTransitioning는 슬라이드가 애니메이션 중인지 여부를 나타내는 상태입니다.

isTransitioning 상태가 true라면 애니메이션 중이므로 중복 호출을 방지합니다. 그렇지 않다면 슬라이드 전환이 시작되었기 때문에 상태를 true로 바꿉니다. 슬라이드 인덱스 또한 업데이트 해 줍니다.

4. 무한 슬라이드 구현

useEffect(() => {
  if (!slideRef.current) return;

  if (isAnimating) {
    slideRef.current.style.transform = `translateX(-${currentSlideIndex * slideWidth}px)`;
  } else {
    if (currentSlideIndex === 1) {
      slideRef.current.style.transform = `translateX(-${slideWidth}px)`;
    } else if (currentSlideIndex === banners.length) {
      slideRef.current.style.transform = `translateX(-${banners.length * slideWidth}px)`;
    }
  }

  const transitionEndHandler = () => {
    if (currentSlideIndex === banners.length + 1) {
      setIsAnimating(false);
      setCurrentSlideIndex(1);
    } else if (currentSlideIndex === 0) {
      setIsAnimating(false);
      setCurrentSlideIndex(banners.length);
    }
    setIsTransitioning(false);
  };

  slideRef.current.addEventListener('transitionend', transitionEndHandler);
  return () => slideRef.current?.removeEventListener('transitionend', transitionEndHandler);
}, [currentSlideIndex, slideWidth, banners.length, isAnimating]);

📌 1. 기본적인 슬라이드 이동

currentSlideIndex가 변경되면 useEffect가 실행됩니다. isAnimating이 true이면 translateX(-currentSlideIndex * slideWidth)를 적용하여 슬라이드를 이동시킵니다. transitionend 이벤트가 발생하면 transitionEndHandler를 실행합니다.

📌 2. 무한 루프 효과

마지막 배너(banners.length)에서 다음 슬라이드로 이동하면? currentSlideIndex === banners.length + 1 → 첫 번째 배너(1번)로 이동합니다.

첫 번째 배너(1번)에서 이전 슬라이드로 이동하면? currentSlideIndex === 0 → 마지막 배너(banners.length)로 이동하여 이를 통해 슬라이드가 처음과 끝을 무한히 반복하는 것처럼 보이게 만듭니다.

5. 자동 슬라이드 기능

useEffect(() => {
  const interval = setInterval(() => {
    moveToNextSlide();
  }, 3000);

  return () => clearInterval(interval);
}, [moveToNextSlide]);

3초마다 자동으로 배너가 이동하도록 설정합니다. 컴포넌트가 언마운트될 때 clearInterval을 호출하여 메모리 누수를 방지합니다.

전체 코드

import React, { useRef, useState, useEffect, useCallback } from 'react';
import * as Styled from './Banner.styles';
import { SlideButton } from '@/utils/banners';

export interface BannerProps {
  backgroundImage?: string;
}

interface BannerComponentProps {
  banners: BannerProps[];
}

const Banner = ({ banners }: BannerComponentProps) => {
  const slideRef = useRef<HTMLDivElement>(null);
  const [currentSlideIndex, setCurrentSlideIndex] = useState(1);
  const [slideWidth, setSlideWidth] = useState(0);
  const [isAnimating, setIsAnimating] = useState(true);
  const [isTransitioning, setIsTransitioning] = useState(false);

  const extendedBanners = [banners[banners.length - 1], ...banners, banners[0]];

  const updateSlideWidth = useCallback(() => {
    if (slideRef.current) {
      setSlideWidth(slideRef.current.offsetWidth);
      slideRef.current.style.transform = `translateX(-${currentSlideIndex * slideRef.current.offsetWidth}px)`;
    }
  }, [currentSlideIndex]);

  useEffect(() => {
    updateSlideWidth();
    window.addEventListener('resize', updateSlideWidth);

    return () => {
      window.removeEventListener('resize', updateSlideWidth);
    };
  }, [updateSlideWidth]);

  useEffect(() => {
    if (!slideRef.current) return;

    if (isAnimating) {
      slideRef.current.style.transform = `translateX(-${currentSlideIndex * slideWidth}px)`;
    } else {
      // 애니메이션 없이 즉시 이동
      if (currentSlideIndex === 1) {
        slideRef.current.style.transform = `translateX(-${slideWidth}px)`;
      } else if (currentSlideIndex === banners.length) {
        slideRef.current.style.transform = `translateX(-${banners.length * slideWidth}px)`;
      }
    }

    const transitionEndHandler = () => {
      if (currentSlideIndex === banners.length + 1) {
        setIsAnimating(false);
        setCurrentSlideIndex(1);
      } else if (currentSlideIndex === 0) {
        setIsAnimating(false);
        setCurrentSlideIndex(banners.length);
      }
      setIsTransitioning(false);
    };

    slideRef.current.addEventListener('transitionend', transitionEndHandler);
    return () => {
      slideRef.current?.removeEventListener(
        'transitionend',
        transitionEndHandler,
      );
    };
  }, [currentSlideIndex, slideWidth, banners.length, isAnimating]);

  const moveToNextSlide = useCallback(() => {
    if (isTransitioning) return;
    setIsTransitioning(true);
    setIsAnimating(true);
    setCurrentSlideIndex((prev) => prev + 1);
  }, [isTransitioning]);

  const moveToPrevSlide = useCallback(() => {
    if (isTransitioning) return;
    setIsTransitioning(true);
    setIsAnimating(true);
    setCurrentSlideIndex((prev) => prev - 1);
  }, [isTransitioning]);

  useEffect(() => {
    const interval = setInterval(() => {
      moveToNextSlide();
    }, 3000);

    return () => clearInterval(interval);
  }, [moveToNextSlide]);

  return (
    <Styled.BannerContainer>
      <Styled.BannerWrapper>
        <Styled.ButtonContainer>
          <Styled.SlideButton onClick={moveToPrevSlide}>
            <img src={SlideButton[0]} alt='Previous Slide' />
          </Styled.SlideButton>
          <Styled.SlideButton onClick={moveToNextSlide}>
            <img src={SlideButton[1]} alt='Next Slide' />
          </Styled.SlideButton>
        </Styled.ButtonContainer>
        <Styled.SlideWrapper ref={slideRef} isAnimating={isAnimating}>
          {extendedBanners.map((banner, index) => (
            <Styled.BannerItem key={index}>
              <img
                src={banner.backgroundImage}
                alt={`banner-${index}`}
                style={{
                  width: '100%',
                  height: '100%',
                  objectFit: 'cover',
                }}
              />
            </Styled.BannerItem>
          ))}
        </Styled.SlideWrapper>
      </Styled.BannerWrapper>
    </Styled.BannerContainer>
  );
};

export default Banner;

스타일링

import styled from 'styled-components';
import { BannerProps } from './Banner';

export const BannerContainer = styled.div`
  padding: 0 40px;
  max-width: 1180px;
  margin: 0 auto;
  width: 100%;

  display: flex;
  justify-content: center;
  align-items: center;
  margin-top: 90px;
  position: relative;

  @media (max-width: 500px) {
    margin-top: 42px;
    padding: 0;
  }
`;

export const BannerWrapper = styled.div<BannerProps>`
  position: relative;
  width: 100%;
  max-width: 1180px;
  height: auto;
  aspect-ratio: 1180 / 316;
  border-radius: 26px;
  overflow: hidden;
  background-color: transparent;
  ${({ backgroundImage }) =>
    backgroundImage &&
    `
    background-image: url(${backgroundImage});
    background-size: cover;
    background-position: center;
    `}

  @media (max-width: 500px) {
    width: 100vw;
    border-radius: 0;
  }
`;

export const SlideWrapper = styled.div<{ isAnimating: boolean }>`
  display: flex;
  width: 100%;
  height: 100%;
  ${({ isAnimating }) =>
    isAnimating
      ? 'transition: transform 0.5s ease-in-out;'
      : 'transition: none;'}
`;

export const BannerItem = styled.div`
  flex: none;
  width: 100%;
  height: 100%;
  img {
    width: 100%;
    height: 100%;
    object-fit: cover;
  }
`;
export const ButtonContainer = styled.div`
  position: absolute;
  width: 100%;
  top: 50%;
  display: flex;
  align-items: center;
  justify-content: space-between;
  transform: translateY(-50%);
  z-index: 1;
`;

export const SlideButton = styled.button`
  width: 60px;
  height: auto;
  padding: 10px 20px;
  border: none;
  background-color: transparent;
  cursor: pointer;

  img {
    width: 100%;
    height: auto;
    object-fit: cover;
  }

  @media (max-width: 698px) {
    width: 35px;
    padding: 6px 12px;
  }


  @media (max-width: 375px) {
    width: 30px;
    padding: 4px 8px;
  }
`;

구현 영상

Library가 아닌 Framework 이기 때문입니다.

참고로 next는 React.js 전용 웹 개발 프레임워크이고, React는 라이브러리입니다.

프레임워크 vs 라이브러리

기능 구현의 주도권이 누구에게 있는가?

주도권이 개발자에게 있다 -> Library 주도권이 개발자에게 없다 → Framework

• Library
  • 어떤 기능을 구현할 때 제약없이 사용합니다.
  • Ex) React page routing에서 React router또는 tanstack을 사용합니다.
• Framework
  • 기능 구현 시 프레임워크가 자체적으로 제공하는 범위 내에서 사용 가능합니다.

    자유도

Next < React

자유도가 낮다고 하는 Next를 사용하는게 괜찮을까요? 너무 높아도 좋지 않습니다. 왜냐하면 주요 기능을 제외한 그 외의 모든 기능을 만들거나, 비슷한 기능을 하는 라이브러리를 직접 찾아야하기 때문입니다. Next는 웹개발에 필요한 모든 기능이 제공됩니다. 추가로 React 확장판이라서 빠르게 배울 수 있습니다.

사전렌더링

브라우저 요청에 사전에 렌더링이 완료된 HTML을 응답하는 렌더링 방식입니다. 이것은 CSR의 단점을 효율적으로 해결합니다.

CSR

Client Side Rendering의 약자는 CSR은 React에 기본적인 렌더링 방식입니다. 클라이언트에서 직접 화면을 렌더링합니다.

장점

• 페이지 이동이 매우 빠르고 쾌적합니다.

  • 서버에서 브라우저로 JS Bundle 과정이 일어납니다. 여기엔 서비스에서 접근 가능한 모든 컴포넌트 코드가 존재합니다.
  • 초기 접속 이후 페이지 이동하게 되더라도 서버에 새로운 페이지를 요청할 필요가 없어집니다.

단점

• 초기 접속 속도가 느립니다.
  • 초기 접속에서 실제로 화면 렌더링까지 오래 걸립니다.
  • 컨텐츠 렌더링 전까지 index.html도 받아오고 js 번들 파일도 받아온 다음 js 실행까지 해야 합니다.

FCP(First Contentful Paint)

"요청 시작" 시점으로부터 컨텐츠가 화면에 처음 나타나는데 걸리는 시간

Next의 렌더링

여기서 렌더링은 두 가지 종류가 있습니다.

• JS실행(렌더링): JS코드를 HTML로 변환합니다.
• 화면에 렌더링: HTML코드를 브라우저가 화면에 그립니다.

상호작용이란 html이 아닌 js가 처리하는 영역이기 때문에 FCP 시점에서는 상호작용이 불가능합니다.

JS 번들링이 끝나고 브라우저에서 html을 연결하면, 상호작용이 가능한 페이지가 됩니다.

수화(Hydration)

브라우저가 js번들링 후 html과 연결할 때, html에 js를 뿌리는 형태같다고 하여 수화(Hydration)이라 불립니다. 참고로 TTI는 Time To Interactive의 약자로 초기 요청에서 hydration까지의 시간을 말합니다.

페이지 이동 요청

CSR과 같은 방식

앞선 초기접속 요청과정에서 hydration을 위해 서버가 브라우저에 js 번들파일(React app)을 전달했기 때문에 사실상 리액트 컴포넌트를 미리 받아온 것입니다.

사전렌더링

서버측에서 js코드를 html로 미리 렌더링하는 사전렌더링을 통해 기존 CSR의 단점인 FCP를 개선하고, 페이지 이동은 CSR과 똑같이 동작합니다.

참고

한 입 크기로 잘라먹는 Next.js

지금 만들고 있는 동아리 지원 플랫폼에서 디자이너분이 주신 피그마 영상입니다. 이 페이지는 동아리 상세보기 페이지입니다. 개발하려고 하는 것은 모집정보, 동아리정보, 소개글, 활동사진이 있는 탭과 자동 스크롤입니다.

1. 탭 클릭 시 클릭된 메뉴의 아래 테두리가 검게 칠해진다.

2. 탭을 클릭할 시 해당 컨텐츠로 자동 스크롤된다.

이것이 구현할 때 필요한 기능입니다.

메뉴Tab

모바일 화면이기 때문에 500px보다 클 때는 탭이 보이지 않도록 설정합니다. 총 4개의 버튼이 필요하기 때문에 width는 25%로 해 두었습니다.

InfoTab.styles.ts

import styled from 'styled-components';

export const InfoTabWrapper = styled.div`
  display: none;
  position: fixed;
  margin-top: -40px;

  @media (max-width: 500px) {
    display: flex;
    flex-direction: row;
    width: 100%;
    height: 45px;
    background-color: white;
  }
`;

export const InfoTabButton = styled.button`
  width: 25%;
  border: none;
  border-bottom: 2px solid #cdcdcd;
  background-color: transparent;
  cursor: pointer;
  font-size: 14px;
  transition: border-bottom 0.3s ease;

  &.active {
    border-bottom: 2px solid black;
  }
`;

active로 클릭할 시에만 border-bottom을 black으로 설정할 겁니다.

active 클래스를 사용하려면 현재 선택된 탭이 무엇인지 알아야 합니다. 그러기 위해선 Tab의 상태를 관리하는 로직이 필요합니다.

InfoTab.tsx

import React, { useState } from 'react';
import * as Styled from './InfoTabs.styles';

const tabLabels = ['모집정보', '동아리정보', '소개글', '활동사진'];

const InfoTabs = ({ onTabClick }: { onTabClick: (index: number) => void }) => {
  const [activeTab, setActiveTab] = useState(0);

  const handleTabClick = (index: number) => {
    setActiveTab(index);
    onTabClick(index);
  };

  return (
    <Styled.InfoTabWrapper>
      {tabLabels.map((label, index) => (
        <Styled.InfoTabButton
          key={label}
          className={activeTab === index ? 'active' : ''}
          onClick={() => handleTabClick(index)}>
          {label}
        </Styled.InfoTabButton>
      ))}
    </Styled.InfoTabWrapper>
  );
};

export default InfoTabs;

useState로 클릭한 버튼만 active상태가 되고, 다른 버튼은 비활성화되도록 하였습니다.

자동 스크롤

useAutoScroll.ts

import { useRef } from 'react';

const useAutoScroll = () => {
  const sectionRefs = useRef<(HTMLDivElement | null)[]>(
    new Array(4).fill(null),
  );

  const scrollToSection = (index: number) => {
    if (sectionRefs.current[index]) {
      const element = sectionRefs.current[index];
      const yOffset = -100;

      window.scrollTo({
        top: element.getBoundingClientRect().top + window.scrollY + yOffset,
        behavior: 'smooth',
      });
    }
  };

  return { sectionRefs, scrollToSection };
};

export default useAutoScroll;

📌 useAutoScroll 훅 설명

• useRef로 스크롤할 섹션들을 참조할 배열을 만듭니다. 배열 요소는 위에 만들어 두었던 탭의 메뉴들에 해당합니다.
• scrollToSection는 index를 받아서 해당 인덱스 섹션으로 스크롤되도록 합니다.
• yOffset은 스크롤 위치를 조정하기 위해 추가했습니다.
• element.getBoundingClientRect().top는 현재 뷰포트 내에서 해당 요소의 상대적인 위치를 가져오는데,여기에 window.scrollY와 yOffset을 더하면 절대적인 화면 위치로 스크롤됩니다.

InfoBox.tsx

import React from 'react';
import * as Styled from './InfoBox.styles';
import { InfoList } from '@/types/Info';

const infoData: InfoList[] = [
  {
    title: '모집정보',
    descriptions: [
      { label: '모집기간', value: '2025.02.28' },
      { label: '모집대상', value: '재학생' },
    ],
  },
  {
    title: '동아리정보',
    descriptions: [
      { label: '회장이름', value: 'xxx' },
      { label: '전화번호', value: '010-1234-5678' },
    ],
  },
];

const InfoBox = ({
  sectionRefs,
}: {
  sectionRefs: React.RefObject<(HTMLDivElement | null)[]>;
}) => {
  return (
    <Styled.InfoBoxWrapper>
      {infoData.map((info, index) => (
        <Styled.InfoBox
          key={index}
          ref={(el) => {
            sectionRefs.current[index] = el;
          }}>
          <Styled.Title>{info.title}</Styled.Title>
          <Styled.DescriptionContainer>
            {info.descriptions.map((desc, idx) => (
              <Styled.DescriptionWrapper key={idx}>
                <Styled.LeftText>{desc.label}</Styled.LeftText>
                <Styled.RightText>{desc.value}</Styled.RightText>
              </Styled.DescriptionWrapper>
            ))}
          </Styled.DescriptionContainer>
        </Styled.InfoBox>
      ))}
    </Styled.InfoBoxWrapper>
  );
};

export default InfoBox;

• 반환값 타입을 React.RefObject로 하면 DOM요소에 접근할 수 있습니다. 특징은 current가 readonly라 직접 변경할 수 없다는 점입니다.
  • 배열에 ref를 동적으로 할당하면 클릭 시 해당 div로 이동합니다.

ClubDetailPage.tsx

const ClubDetailPage = () => {
  const { sectionRefs, scrollToSection } = useAutoScroll();

  return (
    <>
      <Header />
      <InfoTabs onTabClick={scrollToSection} />
      <Styled.PageContainer>
        <InfoBox sectionRefs={sectionRefs} />
        <IntroduceBox sectionRefs={sectionRefs} />
      </Styled.PageContainer>
      <Footer />
    </>
  );
};
export default ClubDetailPage;

이제 상세페이지로 돌아가서 useAutoScroll훅에서 sectionRefs를 가져옵니다. 스크롤되어야 하는 컴포넌트에 sectionRefs를 전달하면 완성입니다.

최종화면

type Dog = {
  name: string;
  isBark: boolean;
};

type Cat = {
  name: string;
  isScratch: boolean;
};

type Animal = Dog | Cat;

function warning(animal: Animal) {
  if ("isBark" in animal) {
    console.log(animal.isBark ? "짖습니다" : "안짖어요");
  } else if ("isScratch" in animal) {
    console.log(animal.isScratch ? "할큅니다" : "안할퀴어요");
  }
}

2개의 타입 Dog와 Cat의 유니온 타입인 Animal 타입까지 정의했습니다.

매개변수로 Animal 타입의 값을 받아 동물에 따라 각각 다른 경고를 콘솔에 출력하는 함수를 만들었습니다. 이때, Dog또는 Cat타입인지 알기 위해 in 연산자를 이용해 타입을 좁힙니다.

하지만 Dog타입이나 Cat타입의 프로퍼티가 중간에 수정되거나 추가 또는 삭제될 때 타입가드는 제대로 동작하지 않습니다.

커스텀 타입 가드

function isDog(animal: Animal): animal is Dog {
  return (animal as Dog).isBark !== undefined;
}

function isCat(animal: Animal): animal is Cat {
  return (animal as Cat).isScratch !== undefined;
}

function warning(animal: Animal) {
  if (isDog(animal)) {
    console.log(animal.isBark ? "짖습니다" : "안짖어요");
  } else {
    console.log(animal.isScratch ? "할큅니다" : "안할퀴어요");
  }

isDog함수의 매개변수로 받은 값이 Dog 타입이라면 true 아니라면 false를 반환합니다. 이때 반환값의 타입으로 animal is Dog 를 정의해 줍니다.

이렇게 하면 함수가 true를 반환하면 조건문 내부에서는 이 값이 Dog타입임을 보장한다는 의미가 됩니다.

타입 가드를 사용하는 경우

1. API 응답 데이터 검증

type User = {
  id: number;
  name: string;
  email: string;
};

function isUser(data: any): data is User {
  return (
    typeof data.id === 'number' &&
    typeof data.name === 'string' &&
    typeof data.email === 'string'
  );
}

여기서 isUser는 매개변수로 전달된 data가 User타입인지 검사합니다. 조건이 모두 참이어야 true를 반환하고, 아니면 false를 반환합니다.

반환 타입에서 data is User는 타입스크립트에게 이 값이 User타입이다라고 알리는 역할을 합니다.

const response = { id: 1, name: 'John Doe', email: 'john@example.com' };

if (isUser(response)) {
  console.log(response.name);
} else {
  console.error('Invalid user data'); // 타입이 User가 아님
}

조건문 안에서 typescript는 response를 자동으로 User타입으로 간주합니다. 타입 가드가 없을 때보다 코드의 안전성이랑 가독성이 올라갑니다.

2. 선택적 프로퍼티를 가진 객체 판별

type Admin = {
  id: number;
  role: 'admin';
  permissions?: string[];
};

function isAdmin(data: any): data is Admin {
  return (
    typeof data.id === 'number' &&
    data.role === 'admin' &&
    (data.permissions === undefined || Array.isArray(data.permissions))
  );
}

const person = { id: 1, role: 'admin', permissions: ['read', 'write'] };

if (isAdmin(person)) {
  console.log(person.permissions); 
}

isAdmin함수에서 permissions는 선택적 속성이므로 두 가지를 검사해야 합니다.

1. permissions가 undefined인 경우
2. permission가 존재한다면 배열이어야 함

자바스크립트에서 배열은 객체로 취급되기 때문에 typeof로 배열을 정확히 판별할 수 없습니다. Array.isArray()는 값이 배열인지 정확하게 검사합니다.

3. 폼 데이터 검증

1️⃣ 동적 데이터 타입

타입 스크립트는 정적 타입검사(컴파일 타임)를 통해 오류를 방지하려고 하지만, 동적 데이터에서는 타입 보장이 어렵습니다.

function processFormData(data: FormData) {
  console.log(data.username.toUpperCase());
}

const formData = { username: 'JohnDoe', age: '30' }; // 잘못된 타입 (age가 문자열)

processFormData(formData);  // 컴파일 시 오류 없음 -> 런타임에 문제 발생 가능

2️⃣ 명시적으로 타입을 검사

타입스크립트는 타입을 명시적으로 검사하는 코드가 없으면 자동으로 타입을 추론할 수 없습니다.

const formData = { username: 'JohnDoe', age: '30' };

if (typeof formData.age === 'number') {
  console.log(formData.age.toFixed(2));  // 타입이 맞는 경우에만 안전하게 동작
} else {
  console.log('Invalid data');
}

3️⃣ 불필요하게 타입 검사 반복

타입 가드를 사용하지 않으면 타입 검사를 반복적으로 수행해야 합니다.

const formData = { username: 'JohnDoe', age: '30' };

// 여러 곳에서 타입을 수동으로 검사
if (typeof formData.username === 'string' && typeof formData.age === 'number') {
  console.log(formData.username.toUpperCase());
}

if (typeof formData.age === 'number') {
  console.log(formData.age.toFixed(2));
}

타입 가드 함수로 동적 데이터 검증

타입 가드를 사용하면 한 번의 타입 검사를 통해 타입을 안전하게 사용할 수 있습니다. 또한, 여러 곳에서 타입 검사를 하지 않고 타입 가드 함수를 재사용할 수 있습니다.

type FormData = {
  username: string;
  age: number;
};

function isValidFormData(data: any): data is FormData {
  return typeof data.username === 'string' && typeof data.age === 'number';
}

const formData = { username: 'JohnDoe', age: 30 }; 

if (isValidFormData(formData)) {
  console.log('Valid form data:', formData);
} else {
  console.error('Invalid form data');
}

참고

한 입 크기로 잘라먹는 타입스크립트

저는 React로 웹을 개발해오던 사람입니다. 최근 간단하게 앱을 만들 일이 있어서 알아보다가, 제가 쓰던 React와 가장 비슷한 React Native를 알게 되었습니다. 저는 이 두 개가 어떻게 다르며, 왜 나누었을까 하는 궁금증이 생겼습니다.

React

자바스크립트 컴포넌트 라이브러리인 React.js는 웹 사이트의 프론트엔드 제작을 위해 사용됩니다. 다른 프레임워크보다 더 각광받는 이유는 재사용 가능한 컴포넌트를 활용할 수 있기 때문이라고 생각합니다.

React는 React github를 보시면 알 수 있듯이 232000개의 star를 가지고 있고 현재도 계속 pr이 올라오는 것을 보실 수 있습니다.

React는 이때 사용한다

1️⃣SPA 를 개발할 때

SPA는 웹 서버에서 전체 HTML 화면을 받아오는 방식이 아니라, 로컬 PC에서 화면을 렌더링하는 방식입니다. 화면 전환 속도가 빠르고, 네이티브 앱처럼 보일 수 있는 장점이 있습니다. React의 가장 큰 특징인 컴포넌트와 Virtual Dom 구조는 SPA 동작에 적합하다고 볼 수 있습니다.

2️⃣소셜 미디어 사이트를 만들 때

소셜 미디어 사이트는 사용자의 동작이 매우 빠르게 처리됩니다. 리액트의 상태 관리를 통해 특정 컴포넌트를 업데이트 할 수 있어 리액트를 쓰기 좋습니다.

리액트의 장점에 대해서는 제가 이전에 썼던 내가 리액트를 사용하는 이유를 참고해주세요☺️

React Native

React Native는 크로스 플랫폼 앱으로 하나의 소스코드로 android, ios에서 똑같이 동작하는 앱을 말합니다. React를 기반으로 구축되었지만, 별도의 라이브러리를 사용합니다. 가장 큰 차이점은 React는 DOM을 조작하는 방식으로 UI을 업데이트하고, React Native는 js와 네이티브 모듈을 사용해 UI를 조작한다는 것입니다.

React Native github또한 12만개 star가 가지고 있으며 24년 10월 드디어 새로운 버전을 내며 지속적인 업데이트를 하고 있습니다.

React Native의 장점

1️⃣JS를 사용한다

JS를 사용하던 사람들에게 익숙하다는 장점이 있습니다. React 또한 js를 사용하기 때문에 React를 사용하던 개발자들은 비교적 수월할 수 있습니다.

2️⃣크로스 플랫폼이다

Window와 macOS 둘 다 호환되어 개발에 부담이 줄어듭니다. 이것은 언어가 아닌 서비스 환경을 얘기하는 것입니다.

어떻게 다른가

React와 React Native는 같은 라이브러리를 사용하지만 동작 과정은 다릅니다. React는 Virtual Dom을 사용하는 반면, RN은 Native 모듈로 동작합니다.

React의 Virtual DOM

React 컴포넌트는 Virtual DOM이라는 가상돔을 사용해 UI을 업데이트 합니다. 이전의 가상돔과 리렌더링된 후의 가상돔을 비교하여 바뀐 부분만 업데이트하는 방식인데요. 변경된 모든 Element를 집단화시켜 이를 한 번에 실제 DOM에 적용하는 Batch Update는 기존에 브라우저에 바로 화면을 그려주는 방법에 비해 매우 효율적으로 DOM을 조작하게 된 것입니다.

React Native의 Bridge

React Native에서는 Bridge로 Native 모듈이 호출됩니다. 다른 네이티브 앱과 다르게 자바스크립트 엔진에서 작동하기 때문에, Bridge를 통해 네이티브와의 통신에서 발생하는 성능 저하를 줄이기 위해 JS 스레드와 네이티브 스레드 간의 통신을 비동기 처리하는 최적화 방법을 사용합니다.

마치며

React와 React Native이 무엇인지와 언제 사용되는지에 대해 간단하게 정리해봤습니다. RN의 자세한 동작과정은 추후 강의를 들은 후에 한 번 더 정리해보고자 합니다.

참고

React.js 대 React Native: 주요 차이점 Virtual DOM (React) 핵심정리

프론트엔드 개발자라면 공통으로 사용되는 컴포넌트 관리를 위해 많은 신경을 쓴 경험이 있을 것입니다. 저는 이번에 동아리 지원 플랫폼 개발을 시작했는데요, 여기서 Storybook을 도입하고자 합니다.

처음에는 Storybook을 왜 사용하는지 설명하고, 그 후에 적용 방법을 작성하고자 합니다. 추가로 chromatic에 대해서도 다뤄볼 에정입니다.

Storybook

Storybook은 UI 구성 요소와 페이지를 분리하여 빌드하기 위한 프론트엔드 워크숍입니다. Storybook 공식문서 수천 개의 팀이 UI 개발, 테스트 및 문서화에 사용하고 있다고 하네요. 오픈 소스이고 무료입니다.

Storybook의 장점

1️⃣컴포넌트 중심

다양한 stories 파일로 컴포넌트의 props 을 직접 조작할 수 있습니다. 어떤 경우에 컴포넌트를 나누어야 하는지도 테스트할 수 있다는 얘기입니다.

2️⃣독립적인 개발 환경

어플리케이션 전체와 분리된 상태에서 개별 컴포넌트를 개발하고 테스트할 수 있도록 설계되었습니다. 어플리케이션의 상태나 의존성에서 벗어날 수 있다는 게 장점이에요.

3️⃣가상 개발 환경

Storybook은 실제 애플리케이션이 아닌 가상의 개발 환경에서 실행됩니다. 브라우저 기반 인터페이스로 UI를 미리 볼 수 있습니다.

4️⃣빠른 피드백 루프

독립적인 환경 덕분에 컴포넌트 수정 시 실시간으로 변경 사항을 확인할 수 있어요.

Storybook 설치

npx storybook@latest init

프로젝트 루트 폴더에서 해당 명령어를 실행합니다. 번들러는 webpack과 vite 중 프로젝트와 맞는 번들러를 선택해주시면 됩니다.

.storybook폴더와 stories폴더가 보이면 정상적으로 완료된 것입니다.

package.json에는 스토리북을 실행하고 빌드하는 명령어가 생깁니다.

.storybook 폴더

main.ts

stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],

src 디렉토리 아래의 모든 .mdx 파일을 스토리로 사용한다는 뜻입니다. stories로 끝나는 파일은 스토리북에서 쓸 수 있게 한다는 얘기입니다.

  addons: [
    '@storybook/addon-webpack5-compiler-swc',
    '@storybook/addon-onboarding',
    '@storybook/addon-essentials',
    '@chromatic-com/storybook',
    '@storybook/addon-interactions',
  ],

Storybook Addons(플러그인) 목록입니다. 프로젝트에서 Storybook 기능을 확장 및 강화하는데 사용됩니다.

framework: {
    name: '@storybook/react-webpack5',
    options: {},
  },

name은 React 기반의 storybook을 Webpack5와 함께 사용할 것을 정의합니다. options 추가적인 프레임워크 옵션을 정의하는데 사용됩니다.

이제 preview.ts입니다.

preview.ts

✔️controls

• props 이름 패턴 기반으로 색상 및 날짜 props를 자동 감지하고 적절한 UI를 컨트롤합니다.

✔️전역으로 적용

• 모든 스토리에 같은 parameters 설정을 제공합니다.

Story 작성하기

src 폴더 내에 components/Button에 버튼 컴포넌트를 작성합니다.

import React from 'react';

export const MyButton = (props: {
  children: React.ReactNode;
  backgroundColor?: string;
}) => {
  return (
    <button style={{ backgroundColor: props.backgroundColor }}>
      {props.children}
    </button>
  );
};

버튼 컴포넌트의 스토리 파일 또한 작성합니다.

import { MyButton } from './MyButton';

const meta = {
  title: 'MyComponent/MyButton',
  component: MyButton,
  argTypes: {
    backgroundColor: { control: 'color' },
  },
};

export default meta;

export const Primary = {
  args: {
    children: 'Button',
    backgroundColor: '#fff',
  },
};

이제 npm run storybook을 하면 브라우저로 스토리북이 실행됩니다.

보시면 만들어 둔 Button 컴포넌트가 보입니다. Controls에는 정의해 둔 args를 확인할 수 있습니다.

버튼을 추가로 생성해보겠습니다.

export const Secondary = {
  args: {
    children: 'Button',
    backgroundColor: 'white',
  },
  argTypes: {
    backgroundColor: { control: 'color' },
  },
};

argTypes은 backgroundColor 속성을 제어하기 위해 명시하였습니다. 이제 스토리북에서 backgroundColor를 패널에서 조절할 수 있습니다.

Chromatic으로 배포하기

로컬에서만 컴포넌트를 만들면 팀원 간 공유가 어려울 것입니다. chromatic은 스토리북을 무료로 배포할 수 있는 도구입니다.

먼저 chromatic으로 가서 get started for free로 시작해봅시다. 저는 깃허브 계정을 연동하여 하나의 레포지토리를 선택하였습니다.

터미널에서 두 가지 명령어를 실행하면 됩니다. 특히, 두 번째 명령어를 실행하면 package.json에 token이 추가되기 때문에 git에 올릴 때 env에 꼭 추가해주세요.

scripts 명령어에도 chromatic 이 추가됩니다.

이제 npm run chromatic으로 실행해봅시다.

터미널에 스토리북이 배포되었다는 메세지가 나옵니다. 추가로 사이트를 들어가보면 아래 사진처럼 Build 내용도 볼 수 있습니다.

여기엔 몇 개의 스토리 파일을 테스트했는지, 빌드된 시간, 브라우저를 보여주고 있습니다.

마치며

이번 프로젝트에 스토리북을 도입하게 된 것은 디자이너와의 협업을 좀 매끄럽게 진행해보고 싶었고, 개발할 때도 공통 컴포넌트를 관리하고 싶어서였습니다. 실제로 사용해보니 막 간단하지는 않았습니다. 코드를 추가로 작성해야 하는 점이 지금 당장에는 부담으로 다가오네요. 어쩌면 프로젝트 첫 배포 날짜가 임박해서 그런 것일 수도... 시작만 하지 말고 꾸준히 써 봐야겠습니다.

참고

Storybook Chromatic 으로 배포하기 Storybook + React, 장점부터 설치와 문서 작성법 가이드