velog-mcp란

Velog는 공개 API가 없습니다. 그래서 내부 GraphQL API(v2.velog.io/graphql)를 리버스 엔지니어링해서 Claude가 직접 포스트를 작성·발행·수정할 수 있는 MCP 서버를 만들었어요.

GitHub 블로그 이전 기능(velog_import_from_github)은 그 중 하나로, GitHub 레포의 마크다운 파일을 읽어 Velog 초안으로 변환해주는 기능이에요.

개발 과정은 Velog MCP 개발기에 기록해뒀습니다 !

1. 파일 다운로드 순차 처리

for (const file of mdFiles) {
  const raw = await fetchRaw(file.download_url, ...); // 순차 실행
}

포스트가 50개면 GitHub 요청 50번을 직렬로 날려요. 각 요청이 12초면 전체 import가 **12분 소요**됩니다. MCP 툴이라 Claude가 응답을 기다리는 동안 대화가 그냥 멈춰 보이죠.

개선하기: Promise.all + concurrency limit으로 병렬 처리해서 개선했어요. 토큰이 있으면 동시 10개, 없으면 5개로 제한하는 mapConcurrent worker-pool을 붙여 10배 이상 단축했어요.

2. GitHub API Rate Limit 미방어

GitHub API의 rate limit은 이렇습니다.

fetchGitHubContents 1번 + 파일 수 N번 = 1 + N 요청. 50개 포스트면 51번 요청이라 토큰 없이는 한도에 거의 닿게 됩니다. 더 큰 문제는 기존 코드가 403이 뜨면 import 중간에 폭발하고, 이미 만들어진 velog draft는 메모리에 고아로 남아요.

개선하기: fetch와 draft 생성을 2단계로 분리

Phase 1 (병렬): 모든 파일 fetch + 파싱 → 메모리에만 보관 (draft 없음)
              ↓ rate limit 감지 시 즉시 throw — draft 0개 생성된 상태
Phase 2 (순차): fetch 전부 성공 시에만 draft 일괄 생성

403은 "rate limit 한도 초과" 에러로 명확히 구분했어요. 네트워크 에러 파일은 failed[]에 경로 + 원인을 기록해서 skipped와 구분했어요.

all-or-nothing 전략으로 중간에 에러가 나면 초안을 모두 지워버리는 방식으로, 고아 draft를 원천 차단했어요.

3. 단일 디렉토리만 스캔

const files = await fetchGitHubContents(repo, filePath, branch, ...);
// 재귀 없음

Jekyll 블로그는 보통 _posts/2024/01/post.md 같은 연도/월 하위 폴더 구조를 씁니다. 재귀 스캔이 없으면 루트 _posts/ 아래 .md 파일만 읽히고 하위 폴더는 통째로 누락되는 구조였어요.

개선하기: fetchGitHubContents를 재귀 호출로 바꿔서 하위 디렉토리까지 전부 스캔하도록 개선했어요.

4. Draft 메모리 누수

const drafts = new Map<string, Draft>();

MCP는 장시간 실행될 수 있어요. importFromGitHub가 draft를 N개 생성하는데, publishPost를 호출해야만 deleteDraft가 되는데, 사용자가 publish 안 하면 대용량 마크다운이 계속 메모리에 쌓여요.

개선하기: draft에 24시간 TTL을 붙였어요. 생성 시 타임스탬프를 기록하고, 조회·발행 시 만료 여부를 체크해서 오래된 draft는 자동 삭제하도록 했습니다.

5. loadConfig 매 요청마다 파일 읽기

return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8"));

graphql()과 uploadImage() 호출 시마다 디스크에서 JSON을 읽어요. 포스트 50개 publish하면 50번 disk I/O가 발생하게 됩니다.

개선하기: 의도적으로 캐시하지 않는다.

Velog access token은 TTL이 1~2시간이고, 만료되면 GraphQL 응답의 Set-Cookie로 자동 갱신되는 구조에요. saveConfig()가 파일을 갱신하는데, 인메모리 캐시를 쓰면 토큰 리프레시 직후 요청이 구버전 토큰을 쓰게 되겠죠. 디스크 I/O가 느리긴 해도 SSD 기준 < 1ms라 사용자 경험에 큰 영향은 없다고 판단했어요.

6. 재시도/이어쓰기 없음

import 도중 네트워크 에러가 나면 전체가 실패해요. 이미 생성된 draft는 고아가 되고 어디까지 됐는지 알 수 없어요.

개선하기: 올-오어-낫씽 롤백으로 대체.

2번 수정(2단계 분리)으로 Phase 1 실패 시 draft 0개를 보장해요. 재시도가 필요하면 처음부터 다시 하면 됩니다. 완벽하진 않지만 고아 draft 없는 예측 가능한 실패가 더 낫다고 판단했어요.

마치며

MCP 서버처럼 장시간 실행되는 프로세스에서는 고아 상태(orphan state) 방지가 가장 중요했어요. 기능이 완벽하지 않아도 실패했을 때 상태가 예측 가능하면 복구가 쉽다는 걸 알게 되었어요.

올-오어-낫씽 전략이 완벽한 해답은 아니지만, 지금 단계에서는 "고아 draft 없는 명확한 실패"가 "중간 성공 + 고아 draft"보다 훨씬 낫다고 판단했어요.

"Claude가 내 벨로그에 직접 글을 올릴 수 있으면 얼마나 편할까?"

이 생각 하나에서 시작됐어요. 찾아보니 Velog에는 공식 API가 없었습니다.

MCP란

MCP(Model Context Protocol)는 Claude가 외부 도구를 직접 호출할 수 있게 해주는 Anthropic의 프로토콜이에요. 즉, MCP 서버만 만들면 Claude가 Velog를 직접 다룰 수 있다는 뜻이었습니다.

그래서 MCP를 직접 만들기로 했습니다.

리버스 엔지니어링

브라우저 개발자 도구를 열고, Network 탭을 켜고, Velog에서 글을 쓰고 댓글을 달면서 어떤 GraphQL 요청이 오가는지 하나씩 확인했어요. URL 복붙하고, 요청 바디 분석하고, 응답 구조를 파악하는 원시적인 방법이었어요.

설계는 gstack에게

https://github.com/garrytan/gstack

설계 단계에서는 gstack의 힘을 빌렸습니다. API 구조, MCP 툴 인터페이스, 에러 처리 방식 등 전반적인 아키텍처 설계에 사용했습니다.

이틀만에 완성한 것들

• 포스트 CRUD — 글 작성, 조회, 수정, 삭제, 임시저장
• 댓글 CRUD — 댓글 작성, 수정, 삭제
• 트렌드 분석 — 트렌딩 포스트 조회 및 분석

Claude로 벨로그를 실제로 운영할 수 있는 수준이 되었습니다.

npm publish, 그리고 뜻밖의 걱정

구현을 마치고 npm publish로 패키지를 배포했습니다. 그런데 마음 한켠이 찜찜했습니다. 공식 API도 아니고, 리버스 엔지니어링으로 만든 건데 이게 서비스 이용약관에 문제가 될 수 있지 않을까?

벨로그 개발자분에게 메일 보내기

그래서 Velog 개발자분에게 직접 이메일을 보냈습니다. "이런 MCP 서버를 만들었는데, 계속 운영해도 괜찮을까요?"

당일 바로 답변을 주셨습니다. 허용한다는 답변이었습니다. 덕분에 마음 편하게 계속 개발할 수 있게 됐습니다. 물론 깃허브에도 오픈소스로 올려두었습니다.

추가 기능

바로 어제, GitHub 블로그에 올린 글을 Velog로 자동으로 옮겨주는 tool을 추가했습니다. 마크다운 파일을 읽어서 frontmatter를 파싱하고, 이미지를 업로드한 뒤 Velog에 그대로 발행하는 흐름입니다.

GitHub Pages에 블로그를 운영하다가 Velog로 이사 오고 싶은 분들에게 유용할 것 같습니다.

API가 언제 바뀔지 모른다

공식 API가 아니다 보니 한 가지 걱정이 생겼습니다. Velog 서버 측에서 GraphQL 스키마를 바꿔버리면 MCP 서버가 동작하지 않게 되겠죠.

그래서 매일 오전 9시마다 실제 Velog API를 호출해서 연결이 살아있는지 자동으로 확인하는 Github actions를 추가했습니다.

진짜 토큰으로 인증하고 API를 요청하는 흐름입니다. 성공하면 갱신된 토큰을 GitHub Secrets에 자동으로 업데이트하고, 실패하면 알림(slack)이 오도록 했습니다.

마무리

사실 저 혼자 쓰려고 개발한 건데 어쩌다보니 벨로그 개발자분에게 메일도 보내고, 재밌는 기능들이 계속 생각나서 열심히 하고 있는 중입니다.

추가되었으면 하는 기능 있으시면 편하게 댓글 달아주세요!!

깃허브: https://github.com/seongwon030/velog_mcp

제품 분석(Product Analytics)도구로서, 사용자의 이벤트를 트래킹할 수 있는 서비스에요.

쉽게 말하면 “우리 서비스에서 사용자들이 뭘 하는지, 어디서 이탈하는지 숫자로 보여주는 도구”에요.

저희 팀은 Mixpanel에서 직접 퍼널과 인사이트를 만들어서 데이터를 보고 있었어요. 쿼리를 짜는 게 아니라, Mixpanel UI 안에서 이벤트를 고르고, 필터를 붙이고, breakdown을 설정하는 방식이에요.

하지만 불편함이 있었어요.

1. UI 적응 비용이 크다.

Insights / Funnels / Retention 각각 인터페이스가 달라요. 내가 머릿속에 그린 지표를 Mixpanel이 요구하는 방식으로 옮기는 과정 자체가 피로해요. 특히 처음 보는 breakdown 옵션을 찾아다니거나, 집계 방식(unique / total / median)을 바꾸는 것처럼 사소한 설정이 생각보다 많은 클릭을 요구해요.

Insights

Retention

Funnels

2. 리포트는 최대 5개까지만 저장된다

Mixpanel 무료 플랜 기준으로 개인이 저장할 수 있는 리포트(퍼널, 인사이트 등)는 최대 5개에요.

분석을 하면 할수록 기존 리포트를 지워야 하는 상황이 생겼어요. 물론 팀원 한 명 당 하나의 리포트를 만들 수 있었지만, 사실 제가 거의 모든 리포트를 다 만드는 상황이었기에 여전히 어려움이 있었어요.

Mixpanel MCP를 Claude Code에 연결하면 이 두 가지를 모두 해결할 수 있어요.

UI 대신 자연어로 묻고, 결과마다 고유한 Mixpanel URL을 받기 때문에 개수 제한이 없었어요.

MCP란?

MCP(Model Context Protocol)는 Claude 같은 AI가 외부 툴을 직접 호출할 수 있게 해주는 프로토콜이에요. Mixpanel MCP는 Mixpanel의 쿼리 API를 Claude가 직접 호출할 수 있도록 래핑한 서버에요.

쉽게 말하면 아래와 같은 플로우가 가능해져요.

나 → Claude에게 자연어로 질문
Claude → Mixpanel MCP 서버 호출
Mixpanel MCP → Mixpanel API로 쿼리 실행
결과 → Claude가 해석해서 나에게 전달

설정 방법

Claude웹에서 추가하기

1. MCP Server URLs 얻기

MCP Server - Mixpanel Docs

https://mcp.mixpanel.com/mcp 이 URL을 복사

2. Claude 설정 → 커넥터 → 커스텀 커넥터 추가

이름은 아무거나 설정하면 되고, 원격 MCP 서버 URL에 이전에 복사해둔 주소를 붙여넣고 추가.

이제 웹에서 MCP를 사용할 수 있고, 터미널에서 또한 가능.

mcp.json으로 추가하기

1. Claude Code에서 MCP 서버 등록

Claude Code 설정에서 Mixpanel MCP 서버를 추가한다. ~/.claude/settings.json 또는 Claude Desktop 설정에서:

{
  "mcpServers": {
    "mixpanel": {
      "command": "npx",
      "args": ["-y", "@mixpanel/mcp"],
      "env": {
        "MIXPANEL_SERVICE_ACCOUNT_USERNAME": "your-service-account",
        "MIXPANEL_SERVICE_ACCOUNT_SECRET": "your-secret"
      }
    }
  }
}

2. Mixpanel 서비스 계정 발급

Mixpanel → Organization Settings → Service Accounts에서 생성.

• 권한: Analyst 이상 (읽기 전용으로 충분)
• username / secret 두 값을 복사해서 위 설정에 넣으면 끝

3. 연결 확인

Claude Code 세션을 시작하면 MCP 서버가 자동으로 뜸. 아래와 같이 물어보기.

"우리 Mixpanel 프로젝트 목록 보여줘"

실제 사용 예시

연결 이후부터는 “mixpanel mcp로 ~~해줘”라고 물어보면 되는데, 그냥 물어보는 것보단 규칙을 정해서 일관성있게 답을 얻고 싶었어요. 그래서 mixpanel용 클로드 command 를 만들었어요.

단계는 6단계로 아래와 같이 설정

[step1] 분석 유형 확인 
[step2] 필요한 데이터 확인
[step3] 쿼리 스키마 확인
[step4] 분석 실행
[step5] 결과 분석 및 해석
[step6] 문서화

이 단계 안에서 주의할 점들이나 더 신경써야 할 점들은 프로젝트 성격에 맞게 커스텀했어요.

클로드 커맨드

아래는 클로드 mixpanel 커맨드에 작성했던 “분석 유형”인데, 프로젝트마다 다르기 때문에 그냥 넘어가도 좋아요. (참고로 저는 현재 대학교의 동아리를 보여주고 지원할 수 있는 웹서비스를 운영 중이에요😊)

패턴 1. 퍼널 분석

자연어 질문:

"메인페이지 방문 → 상세페이지 방문 → 지원하기 버튼 클릭 퍼널을
 최근 30일 기준으로 유니크 유저로 보여줘"

Claude가 하는 일:

• Funnels 쿼리 스키마를 확인
• 이벤트명(MainPage Visited, ClubDetailPage Visited, Club Apply Button Clicked)을 매핑
• API 호출 → 단계별 전환율 반환

결과 예시:

핵심은 이벤트명을 정확히 몰라도 된다는 점이에요. "지원하기 클릭"이라고 하면 Claude가 알아서 Club Apply Button Clicked로 매핑해요.

패턴 2. TOP N 랭킹

자연어 질문:

"동아리별로 상세페이지 체류시간 중간값을 내림차순으로 보여줘 (최근 30일)"

Claude가 하는 일:

• ClubDetailPage Duration 이벤트에서 duration_seconds 프로퍼티를 median으로 집계
• clubName 기준으로 breakdown
• 결과를 정렬해서 테이블로 반환

이걸 Mixpanel UI에서 직접 하려면: Insights → 이벤트 선택 → Aggregate Property → breakdown 추가 → 정렬 순서 변경… 꽤 많은 클릭이 필요해요.

패턴 3. 트렌드 분석

자연어 질문:

"지난 5주간 메인 방문, 상세 방문, 지원 클릭 유저 수 주간 추이 보여줘"

결과: 주차별 꺾은선 데이터 + Mixpanel 리포트 링크

Claude가 리포트 URL도 함께 반환하기 때문에, 더 자세히 보고 싶으면 링크 타고 Mixpanel 대시보드에서 바로 확인할 수 있어요.

패턴 4. 코호트 비교

자연어 질문:

"지원하기 버튼을 클릭한 유저와 안 한 유저의 상세페이지 체류시간을 비교해줘"

이런 코호트성 비교는 Mixpanel UI에서 설정이 까다롭다. MCP는 Claude가 내부적으로 frequency-per-user breakdown을 써서 자동으로 처리해줘요.

Mixpanel UI 대비 달라지는 점

Tip

이벤트명을 몰라도 된다

Claude가 Get-Events 툴로 먼저 이벤트 목록을 검색한 뒤 쿼리를 짜요.

"지원 완료" 같은 표현으로도 찾아줘서 편해요.

프로젝트 ID를 알려주면 빠르다

매번 프로젝트를 물어보는 걸 피하려면 대화 초반에 한 번 알려줘요. 그럼 헷갈리는 일 없이 잘 대답해줍니다.

"우리 프로젝트 ID는 3611536이야, 앞으로 이걸로 써줘"

주의사항

외부 사이트 추적불가

예를 들어, 결제 버튼이 외부회사(토스,카카오 등)의 페이지로 이동하는 경우, 버튼 클릭까지만 추적 가능하고 실제 결제 완료 여부는 알 수 없어요.

너무 긴 기간 + 세분화된 breakdown은 타임아웃

90일 범위 + 사용자별 일별 breakdown처럼 데이터 양이 많은 조합은 쿼리가 타임아웃될 수 있어요.

실제로 저도 90일 넘는 기간을 설정하니 데이터가 너무 많아 조회할 수 없었어요.

이 경우 기간을 30일 이내로 줄이거나, 잡히는 이벤트 수를 줄이거나(이벤트 목록 자체를 줄이기), breakdown 기준을 완화해야 해요.

직접 적용해보기

1-3월 데이터를 MCP로 분석하면서 흥미로운 사실을 발견했어요.

처음 가설은 단순했어요. "상세페이지를 오래 볼수록 관심이 높고, 지원하기를 더 많이 누를 것이다."

하지만 데이터는 반대였어요.

┌────────────────────┬─────────────────┬───────────────┐
│ 지원하기 클릭 횟수 │ 체류시간 중간값 │ 체류시간 평균             │
├────────────────────┼─────────────────┼───────────────┤
│ 0~4번               │ 8초             │ 22~32초        │
├────────────────────┼─────────────────┼───────────────┤
│ 4~12번              │ 8초             │ 13~20초        │
├────────────────────┼─────────────────┼───────────────┤
│ 14번 이상            │ 6초             │ 12.6초         │
└────────────────────┴─────────────────┴───────────────┘

• 클릭을 가장 많이 한 유저일수록 오히려 체류시간이 짧았어요.
• 반대로 거의 안 누른 유저들이 페이지를 더 오래 봤어요.

해석: 클릭을 많이 한 유저는 이미 플랫폼에 익숙해서 빠르게 스캔하고 결정한다. 오래 머문 유저는 아직 확신이 없어 고민중이거나, 정보가 충분하지 않다고 느끼는 상태일 가능성이 있다.

즉 체류시간 = 관심도라는 단순한 등식은 성립하지 않았어요. 이 인사이트를 얻기까지 UI에서 직접 코호트를 설정했다면 훨씬 오래 걸렸을 것 같아요.

얻은 개선포인트

이 데이터 하나로 방향이 명확해졌습니다. 상세페이지를 오래 보는 유저는 아직 확신을 못 잡은 상태일 가능성이 높아요. 즉 페이지 체류시간을 늘리는 것보다, 오래 머문 유저가 결국 지원 버튼을 누르게 만드는 것이 진짜 개선 포인트인거죠.

아직 어떤 UI 개선을 할 지 정확하게 정하지는 않았지만, 방향성을 잘 잡을 수 있었어요.

마무리

Mixpanel MCP를 쓰면서 좋은점은 두 가지였어요.

UI 적응 비용 제거

• Mixpanel 인터페이스를 익히지 않아도 됩니다. 머릿속에 있는 지표를 그대로 말하면 Claude가 알아서 쿼리로 만들어줘요.

리포트 개수 제한 해소

• 쿼리를 실행할 때마다 고유한 Mixpanel URL이 발급해줘요. 저장해두지 않아도 링크만 있으면 언제든 다시 볼 수 있고, 5개 제한에 걸릴 일이 없어요. 특히 주간 리포트처럼 반복적인 분석이나, 갑자기 생긴 수치 이상을 빠르게 파악할 때 효과적입니다.

작년 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를 전달하면 완성입니다.

최종화면