[토스 오픈소스 기여 vol.0] 오픈소스 기여 가이드

 

많은 개발자들이 조직에서 반복적인 프로젝트를 하다 보면, 기술적으로 정체되어 있다는 느낌을 받곤 합니다.
저 역시 최근 들어 그런 느낌을 자주 받았고, 큰 성장을 체감하지 못하고 있어 스스로 성장이 필요하다고 느꼈습니다.

 

 

그러던 중 오픈소스 관련 포스팅을 작성하면서, 오픈소스가 주는 이점을 크게 느끼게 되었고, 자연스럽게 오픈소스 기여를 해보고 싶다는 생각이 들었습니다. 하지만 처음이라 어디서부터 시작해야 할지 감이 오지 않아, 하나씩 차근차근 해보기로 마음먹었습니다.

 

먼저, 토스의 경우 코드를 이렇게 작성하고, 이슈나 PR을 이렇게 커뮤니케이션하는구나 라는 점을 느끼며, 초기에는 문서(docs) 수정부터 시작하고 점차 코드 영역으로 확장했다고 합니다. 저 역시 간단한 타입 정의나 테스트 코드부터 시작해서, 나중에는 CI 관련 코드 등으로 참여 범위를 넓혀보려고 합니다.

 

 

이번 글에서는 제가 이 과정을 직접 경험하며 공유하려고 합니다.
오늘은 프로젝트를 다운받고, 코드를 어떤 식으로 작성하고 있는지 확인하는 것부터 시작해보겠습니다.

 

 

토스에는 Slash라는 내부 라이브러리 컬렉션이 있습니다.
Slash는 토스 내부에서 사용되는 여러 TypeScript/JavaScript 유틸리티와 React 도구를 한데 모아놓은 컬렉션으로, “Slash libraries”라는 이름으로 문서가 정리되어 있습니다.

 

 

이 라이브러리들은 미리 정의된 문제들을 해결하기 위해 만들어졌습니다.
예를 들어, 한글 처리, React Suspense 관리, 복잡한 사용자 흐름 관리 등 다양한 개발 과정에서 반복적으로 발생하는 문제들을 효율적으로 처리할 수 있도록 돕습니다.

 

https://www.slash.page/ko/

Slash 라이브러리

 

토스 오픈소스 라이브러리 목록

• es-toolkit
  토스에서 만든 유틸리티 라이브러리 모음
• es-hangul
  한글 관련 유틸리티 및 텍스트 처리 라이브러리
• suspensive
  React Suspense를 활용한 비동기 상태 관리 라이브러리
• overlay-kit
  모달, 팝업 등 UI 오버레이 컴포넌트 라이브러리
• use-funnel
  퍼널 분석 및 이벤트 추적을 위한 React 훅 라이브러리

 

📚 각 라이브러리 설명

라이브러리 이름	기능 / 문제 해결	주요 특징 / 활용 예
es-toolkit	일반적인 자바스크립트 유틸리티 함수 모음 (lodash 같은 역할)	작고 빠름, 번들 사이즈 작고 타입 안정성 있음. 예: debounce, sum, delay, throttle 같은 함수들이 있음.
es-hangul	한글 문자열 처리를 편하게 조사 붙이기 / 초성 추출 / 분해 및 조합 등	예: getChoseong, josa 함수 등이 있어 “사과가/사과를 먹었습니다” 같은 표현을 자동 처리 가능. ECMAScript Modules 방식이며 브라우저에서도 최소 코드 다운로드 하도록 설계됨.
suspensive	React의 Suspense / ErrorBoundary 등을 간편하게 사용하려는 도구 집합	SSR 환경에서 Suspense를 점진적으로 적용 가능하게 해주는 clientOnly 같은 기능도 제공됨. <Suspense>, <ErrorBoundary>, <ErrorBoundaryGroup> 등의 선언적 API 제공.
overlay-kit	React에서 모달, 팝업, 다이얼로그 등 “오버레이” UI를 선언적으로 관리	상태 관리(useState 등)과 이벤트 핸들링 복잡성 줄임. overlay.open, overlay.openAsync 같은 API가 있음. 오버레이 안에서 어떤 UI를 렌더링할지 쉽게 조정 가능.
use-funnel	단계(step)가 있는 사용자 흐름(funnel)이나 wizard 형태의 UI 흐름 관리	예: 여러 입력 단계(이메일 → 비밀번호 → 정보 입력 등)를 타입 안정성 있게 관리. 히스토리(back/forward) 지원됨. 다양한 라우터 환경(Next.js, react-router, react navigation) 대응.

 

 

처음 오픈소스 기여를 시작할 때는

프로젝트의 규모, 코드 난이도, 문서화 상태, 이슈 난이도를 보고 선택하는 게 좋을것 같아서 비교를 해보았습니다.

 

토스 오픈소스 5개 라이브러리(es-toolkit, es-hangul, suspensive, overlay-kit, use-funnel)를 내부 구조와 API 관점에서 비교해보면, 접근 난이도나 활용 목적을 한눈에 볼 수 있을 것같아서 GPT의 도움을 받아 비교해서 선별해보았습니다.

 

🔹 정리

1. 초보 기여자: es-toolkit / es-hangul → 함수 중심, 테스트/문서 개선으로 시작하기 좋음
2. 중급 개발자: overlay-kit, use-funnel → Hook/컴포넌트 구조 이해 필요
3. 상급 개발자: suspensive → React Suspense + SSR, 에러 경계 관리 이해 필요

 

📦 라이브러리의 내부 구조와 대표 API

1️⃣ es-toolkit (범용 JS 유틸)

es-toolkit/
├─ src/
│   ├─ debounce.ts       # 함수 지연 호출
│   ├─ throttle.ts       # 함수 제한 호출
│   ├─ sum.ts            # 배열 합계
│   └─ delay.ts          # Promise 지연
└─ tests/
    ├─ debounce.spec.ts
    ├─ throttle.spec.ts
    └─ sum.spec.ts

 

• 대표 API: debounce(), throttle(), sum(), delay()
• 특징: 순수 JS 함수, 타입스크립트 지원, 테스트(Vitest) 포함

es-toolkit은 단순한 JS 함수들의 모음이에요. src 폴더 안에는 debounce, throttle, sum, delay 같은 개별 함수 파일이 있고, 각각에 대응하는 테스트 파일이 tests 폴더에 있어요.
대표 API는 debounce()나 throttle() 같은 함수로, 브라우저나 Node 환경에서 그대로 쓸 수 있습니다. 타입스크립트를 지원하고 Vitest로 테스트를 돌릴 수 있어 초보자가 기여하기 가장 쉬운 구조입니다.

 

 

2️⃣ es-hangul (한글 처리)

es-hangul/
├─ src/
│   ├─ josa.ts           # 조사 붙이기
│   ├─ getChoseong.ts    # 초성 추출
│   ├─ hangulCompose.ts  # 글자 조합
│   └─ hangulDecompose.ts# 글자 분해
└─ tests/
    ├─ josa.spec.ts
    ├─ getChoseong.spec.ts
    └─ hangulCompose.spec.ts

 

 

• 대표 API: josa('사과', '을'), getChoseong('가나다')
• 특징: 작은 범위, 직관적, 타입 안전, Vitest

es-hangul은 한글 문자열 처리에 특화된 유틸 모음이에요. src 안에는 josa.ts(조사 붙이기), getChoseong.ts(초성 추출), hangulCompose.ts(글자 조합), hangulDecompose.ts(글자 분해) 같은 파일들이 있어요. 테스트도 Vitest로 작성되어 있습니다.
대표 API는 josa('사과', '을')나 getChoseong('가나다')이고, 한글 처리 도메인이 직관적이라 입문용으로 적합합니다.

 

 

3️⃣ suspensive (React Suspense & ErrorBoundary)

suspensive/
├─ src/
│   ├─ components/
│   │   ├─ Suspense.tsx
│   │   └─ ErrorBoundary.tsx
│   ├─ hooks/
│   │   └─ clientOnly.ts
└─ tests/
    ├─ Suspense.spec.tsx
    └─ ErrorBoundary.spec.tsx

 

 

• 대표 API: <Suspense>, <ErrorBoundary>, clientOnly()
• 특징: React 전용, SSR 대응, 중급 난이도

suspensive는 React 환경에서 Suspense와 ErrorBoundary를 관리하기 위한 라이브러리입니다. src/components에는 와 컴포넌트가 있고, src/hooks에는 clientOnly 같은 Hook이 있습니다.
대표 API는 와 를 JSX에서 직접 쓰거나, clientOnly()로 SSR 환경에서 특정 컴포넌트를 클라이언트 전용으로 렌더링하는 방식입니다. React와 SSR 지식이 필요해 난이도가 중급 수준이에요.

 

 

4️⃣ overlay-kit (모달/팝업 관리)

overlay-kit/
├─ src/
│   ├─ overlay.tsx       # 오버레이 컨트롤
│   ├─ hooks/
│   │   └─ useOverlay.ts
└─ tests/
    ├─ overlay.spec.tsx
    └─ useOverlay.spec.ts

 

 

• 대표 API: overlay.open(<Modal />), overlay.close()
• 특징: Hook + API 조합, React UI 관리, 중급 난이도

overlay-kit은 React에서 모달, 팝업, 다이얼로그 등 오버레이 UI를 선언적으로 관리할 수 있게 도와주는 라이브러리입니다. src/overlay.tsx가 핵심이고, src/hooks/useOverlay.ts로 상태를 제어할 수 있습니다.
대표 API는 overlay.open()와 overlay.close()로, 오버레이를 열고 닫는 동작을 간단히 제어할 수 있습니다. React Hook과 컴포넌트 구조를 이해해야 해서 난이도는 중급이에요.

 

 

5️⃣ use-funnel (단계별 UI 흐름)

use-funnel/
├─ src/
│   └─ hooks/
│       └─ useFunnel.ts   # step 관리, next/back
└─ tests/
    └─ useFunnel.spec.ts

• 대표 API: const { step, next, back } = useFunnel(...)
• 특징: Wizard/Flow 관리, 타입 안전, 중급~상급

use-funnel은 단계별 UI 흐름이나 Wizard를 타입 안전하게 관리하는 Hook입니다. src/hooks/useFunnel.ts 안에서 step, next, back 등을 관리하며, 히스토리(back/forward)도 지원합니다.
대표 API는 const { step, next, back } = useFunnel(...)이고, 복잡한 단계형 UI를 만들 때 유용합니다. 타입 안정성을 이해해야 해서 난이도는 중급~상급이에요.

 

 

정리를 해보자면,

🔎 난이도별 접근성

1. es-hangul (가장 쉬움 ✅)
   • 한글 관련 문자열 처리라 문제 도메인이 직관적임.
   • 비교적 작은 범위(문자열 유틸 함수)라 이해하기 쉬움.
   • “오타 수정”, “문서 보강”, “테스트 케이스 추가” 같은 기여 포인트 많음.
2. es-toolkit
   • lodash 같은 유틸 모음.
   • 코드가 단순한 함수 단위로 나뉘어 있어서 특정 함수 하나만 분석해도 됨.
   • 작은 개선(PR) 시도하기 좋아요.
3. overlay-kit
   • React에서 모달/팝업 UI를 다루는 라이브러리.
   • 컴포넌트/Hook 기반이라, 프론트엔드 개발자로서 실사용 경험을 살려 기여하기 좋음.
   • 다만 내부 구조(상태관리/Portal 등) 이해가 조금 필요.
4. use-funnel
   • "단계별 UI 흐름" 관리 라이브러리.
   • 타입 안정성이 핵심이라 TypeScript 타입 설계 경험 있으면 기여하기 괜찮음.
   • 초반에는 난이도가 조금 높을 수 있음.
5. suspensive (가장 어려움 ⚠️)
   • React Suspense/ErrorBoundary 다루는 고급 패턴.
   • React 동작 원리에 대한 깊은 이해 필요.
   • 초보자 입장에서는 난이도가 꽤 있음.

 

 

 

그리고 어떤 부분 먼저해야할지 감이 오지않아서 기여 포인트도 정해달라고 해보았다.

 

🎯 es-toolkit

• 기여 포인트
  • 테스트 케이스 추가: debounce, throttle, sum 같은 함수의 경계값 테스트
  • 문서 개선: 각 함수의 예제 코드 추가, 사용법 명확화
  • 버그 수정: 작은 함수 동작 오류, 타입 정의 오류
• 난이도: 낮음
• 추천 이유: 순수 JS 함수라 코드 이해가 쉽고, 테스트/문서 기여가 곧바로 의미 있음

 

🎯 es-hangul

• 기여 포인트
  • 테스트 케이스 확장: 조사 처리, 초성 추출 등 예외 케이스 추가
  • 문서 보강: 함수 사용 예제, 한국어 맞춤법 관련 설명 추가
  • 작은 버그/오타 수정
• 난이도: 낮음
• 추천 이유: 한글 처리라는 도메인이 직관적이고, 초보자도 테스트/문서 개선으로 기여 가능

 

🎯 overlay-kit

• 기여 포인트
  • 테스트 케이스 추가: overlay.open() / overlay.close() 동작 검증
  • 문서 개선: 오버레이 사용 예제, Hook 사용법 추가
  • UI 컴포넌트 개선: 기본 Modal 컴포넌트 스타일 수정이나 Props 설명 추가
• 난이도: 중급
• 추천 이유: React Hook과 UI 관리 경험을 살릴 수 있음, 테스트/문서 기여로 시작 가능

 

🎯 use-funnel

• 기여 포인트
  • 테스트 케이스 추가: step 이동, back/forward, 예외 케이스
  • 문서 개선: 단계별 UI 구성 예제, 타입 설명 추가
  • 예제 시나리오 추가: Wizard나 회원가입 같은 흐름 샘플 작성
• 난이도: 중급~상급
• 추천 이유: 단계별 UI 흐름 이해가 필요하지만, 테스트/문서로 접근하면 시작 가능

 

🎯 suspensive

• 기여 포인트
  • 문서 개선: <Suspense> / <ErrorBoundary> 사용법, SSR 관련 주의 사항 추가
  • 테스트 케이스 확장: Suspense fallback, 에러 처리 시나리오
  • 작은 버그/타입 오류 수정
• 난이도: 상급
• 추천 이유: React Suspense와 SSR 이해가 필요하지만, 문서/테스트 기여로 접근 가능

 

🔹 추천 순서 (첫 PR 기준)

1. es-hangul → 직관적, 테스트/문서 개선
2. es-toolkit → 함수 단위, 테스트/문서 개선
3. overlay-kit → React Hook 이해 후 테스트/문서 기여
4. use-funnel → 단계형 UI 이해 후 테스트/예제 작성
5. suspensive → SSR + Suspense 이해 후 문서/테스트 기여

 

 

이번 글에서는 토스 오픈소스 라이브러리들의 구조와 난이도, 그리고 초보자가 접근하기 좋은 기여 포인트를 정리해보았습니다.✨ ✨ 

 

다음 포스팅에서는 es-hangul을 실제로 다운로드하고, 코드를 분석하며 작은 PR을 만들어보는 과정부터 시작할 예정이에요.
테스트를 작성하고 문서를 개선하는 실습 과정을 함께 공유할 테니, 오픈소스 기여에 관심 있는 분들은 같이 따라오시면 좋습니다.

 

 

 

🎥 참고 자료로, 최근 토스 개발자 컨퍼런스 공식 홈페이지를 소개합니다.
해당 사이트에는 컨퍼런스 영상이 순차적으로 올라오고 있어, 토스 개발 문화와 기술 스택을 직접 확인할 수 있습니다.
오픈소스 기여와 관련된 내부 사례나 코드 리뷰 문화도 영상에서 접할 수 있으니, 관심 있는 분들은 참고하시면 좋습니다.

 

https://toss.im/slash-24

토스 개발자 컨퍼런스 SLASH24