프로젝트에 React Native를 도입할 때 크게 두 가지 방식이 있습니다.
프로젝트를 처음부터 React Native 로 개발한다.
현재 프로젝트에 부분적으로 React Native 를 도입한다.
베트남의 토스앱을 개발하던 때는 운영되는 서비스를 잠시 멈추고 React Native로 새로 개발했었습니다. 그 시점에 앱의 기능이 그렇게 많지 않았기 때문에 가능했었습니다. 하지만 한국에서 서비스 하고 있는 토스앱은 그렇지 않았습니다.
토스의 React Native 도입 배경
토스앱은 사실 크로스 플랫폼을 활용하기 위해 React Native를 도입했던 것은 아니었습니다. 2021년 코로나가 극심할 때 식당이나 카페등 가게에 출입하기 위해  QR인증을 했던 것을 기억하실것입니다. 그 때 QR인증을 위해 나라에서 지정한 업체의 SDK 를 사용해야 했습니다. 그런데 그 업체가 React Native로 된 SDK를 전달해주었고, 그렇게 토스앱에 React Native가 포함되었습니다. 
이후 토스 내부에서도 웹서비스의 화면들을 더 빠르게 로드해야 한다는 요구사항과 겹쳐서 React를 다루는 Frontend 개발자들이 앱에 포함되어 있는 React Native를 살려 크로스 플랫폼 도구로 사용하게 되었습니다.
토스와 비슷하게 많은 회사들이 각자 다른 이유로 운영 중인 서비스를 크로스 플랫폼으로 확장하고자 React Native를 도입하려고 할 것입니다. 이런 경우에 CocoaPods를 사용하지 않고 React Native를 도입하는 방법을 알려드리겠습니다. 
React Native와 의존성 관리 도구
운영되는 앱에 React Native를 도입하기로 결정했을 때 iOS 개발자의 입장을 생각해봅시다. React Native는 기본적으로 CocoaPods로 설치되도록 되어 있어요. 현재 운영하고 있는 서비스가 CocoaPods를  의존성 관리 도구로 사용하고 있다면, 큰 어려움 없이 React Native를 도입할 수 있습니다.
하지만 iOS 개발 환경에는 CocoaPods 외에도 여러 가지의 의존성 관리 도구가 있습니다. 애플의 First Party인 Swift Package Manager 나, Carthage, Rome, 등등이 있습니다. 의존성 관리 도구는 아니지만 프로젝트 설정 관리 도구인 Tuist도 있습니다.
그럼 CocoaPods 외에 다른 의존성 관리 도구를 사용하고 있다면 어떻게 React Native를 도입할 수 있을까요?  사용 중인 의존성 관리 도구와 CocoaPods를 함께 사용해야 합니다. CocoaPods를 사용하고 있지 않다면 CocoaPods를 추가하면 되고, CocoaPods를 이미 병행으로 사용하고 있다면 해당 Podfile에 React Native 관련 의존성을 추가하면 됩니다. 
하지만 이렇게 의존성 관리 도구를 병행하는 것은 좋은 방법이 아닙니다.
왜 의존성 관리 도구를 하나만 써야 할까?
두 가지 이상의 의존성 관리 도구를 사용한다면 각각의 의존성 관리 도구는 각자가 관리하는 의존성들만 Resolve할 뿐, 서로가 관리하고 있는 의존성을 알 수 없습니다. 즉 CocoaPods에서 A라는 라이브러리를 추가하고, Swift Package Manager 에서 A라는 라이브러리를 추가하면 라이브러리 A가 중복됩니다. 

라이브러리 B가 라이브러리 A에 의존하고, 라이브러리 C가 라이브러리 A에 의존한다고 생각해볼게요. 

이때 라이브러리 B를 CocoaPods에, 그리고 라이브러리 C를 Swift Package Manager에 추가하여 관리한다면 다음 그림처럼 됩니다. 

이처럼 라이브러리 A가 중복되고 빌드나 아카이브에 실패합니다. 
이 문제를 해결하기 위해 강제로 B가 A에 의존하지 않도록 해야 합니다. 그러기 위해 해야 하는 작업은 다음과 같습니다.
라이브러리 B 의 레포를 찾아 Fork 한다.
Fork 한 레포에서 podspec 파일을 찾는다.
podspec 파일에서 라이브러리 A에 대한 의존성 항목을 찾아서 삭제한다. 
Podfile에서 라이브러리  B의 레포 경로를 내가 수정한 레포지토리로 지정한다.
이러한 작업을 울며 겨자먹기로 할 수밖에 없습니다. 

하지만 이런 경우엔 의존성 커스텀 히스토리를 잘 관리해야 합니다. 그렇지 않으면 지뢰가 되어 추후에 문제가 생길 수 있기 때문이에요. 
Swift Package Manager에서 라이브러리 C가 더 이상 필요하지 않아 제거하게 되면 라이브러리 A도 함께 사라지기 때문에 라이브러리 B가 바라보던 라이브러리 A도 사라져 빌드에 실패하게 됩니다. 
나중에 이 히스토리를 모르는 다른 사람이 fork한 레포를 사용하지 않고 원본 레포를 사용한다면 A 라이브러리 중복 문제가 다시 나타나고, 원인을 알기 어려워 시간을 허비하게 됩니다.
이처럼 히스토리를 모르면 해결하기 어려운 문제들이 일어납니다. 그렇기 때문에 히스토리를 잘 관리하거나,  의존성 관리 도구는 하나만 사용하는 것이 좋습니다. 

CocoaPods 없이 React Native 라이브러리 포함하기
지금까지 의존성 관리 도구를 하나만 사용해야 되는 이유를 설명해드렸습니다. 그렇다면 이미 운영 중인 서비스의 의존성 관리 도구로 반드시 CocoaPods를 사용해야 될까요? 이제부터는 CocoaPods를 사용하지 않고 하나의 의존성 관리 도구로 React Native를 도입할 수 있는 방법을 알려드리겠습니다. 
React Native 라이브러리들을 미리 XCFramework로 빌드한 다음에 내 프로젝트에 포함하면 됩니다. 미리 빌드 하는 과정에서 사실은  CocoaPods를 여전히 사용하게 됩니다. 이 방법을 Prebuild 라 부르겠습니다. 
따라해보기
그렇다면 이제 ReactNative를 XCFramework로 빌드 하는 방법을 단계별로 알아보겠습니다.

스크립트를 이용해 프로젝트를 만듭니다.
react_native_prebuild 디렉토리를 생성 후 진입합니다.
mkdir react_native_prebuild
cd react_native_prebuild
프로젝트 생성 스크립트를 만듭니다. 
gem install xcodeproj
echo "require 'xcodeproj'

# 새로운 프로젝트 생성
project = Xcodeproj::Project.new('ReactNativePrebuild.xcodeproj')

# 타겟 추가
project.new_target(:application, 'ReactNativePrebuild', :ios)

# 프로젝트 저장
project.save" > create_project.rb
프로젝트 생성 스크립트를 실행해 프로젝트를 생성합니다.
ruby create_project.rb
react-native를 설치할 package.json을 만듭니다.
{
  "name": "react-native-prebuild",
  "version": "0.0.1",
  "private": true,
  "dependencies": {
    "react": "18.3.1",
    "react-native": "0.76.0", 
    "yarn": "^1.22.2"
  }
}
yarn 등으로 설치합니다. 
yarn 이 없는 경우 
npm install --global yarn.
yarn 으로 빌드
yarn
pod init을 수행합니다.
pod init
podfile을 다음과 같이 수정합니다. 
source 'https://cdn.cocoapods.org/'
platform :ios, '18.0'

# prepare_react_native_project 를 호출하기 위함.
require_relative './node_modules/react-native/scripts/react_native_pods'

inhibit_all_warnings!
prepare_react_native_project!

target 'ReactNativePrebuild' do
  use_frameworks! :linkage => :static

  use_react_native!(
    :path => './node_modules/react-native',
    :app_path => "#{Pod::Config.instance.installation_root}/"
  )

end

post_install do |installer|
  # For ReactNative
  react_native_post_install(
      installer,
      './node_modules/react-native',
      :mac_catalyst_enabled => false
    )

end
pod install로 pod을 설치합니다. 
pod install
React Native 라이브러리들을  XCFramework 로 빌드 하는 스크립트를 작성합니다. 
touch build_xcframeworks.sh
chmod +x build_xcframeworks.sh
빌드 스크립트의 내용은 다음과 같습니다. 
라이브러리를 simulator 용으로 archive 합니다.
라이브러리를 device 용으로 archive 합니다.
라이브러리들의 framework들을 뽑아 XCFramework로 만듭니다.
#!/bin/bash

set -euo pipefail

export SRCROOT=$(pwd)
export WORKSPACE=ReactNativePrebuild
export PROJECT="Pods-$WORKSPACE"

function archive() {
  xcodebuild archive \
    -workspace $WORKSPACE.xcworkspace \
    -scheme $PROJECT \
    -archivePath $SRCROOT/$PROJECT-iphonesimulator.xcarchive \
    -configuration $1 \
    -sdk iphonesimulator \
    -quiet \
    SKIP_INSTALL=NO
  xcodebuild archive \
    -workspace $WORKSPACE.xcworkspace \
    -scheme $PROJECT \
    -archivePath $SRCROOT/$PROJECT-iphoneos.xcarchive \
    -configuration $1 \
    -sdk iphoneos \
    -quiet \
    SKIP_INSTALL=NO
}

function create_xcframework() {
    for framework in $(find $SRCROOT/$PROJECT-iphonesimulator.xcarchive/Products/Library/Frameworks -type d -name "*.framework");
    do
        basename=$(basename $framework)
        framework_name=$(basename $framework .framework)

        xcodebuild -create-xcframework \
            -framework "$SRCROOT/$PROJECT-iphonesimulator.xcarchive/Products/Library/Frameworks/$basename" \
            -framework "$SRCROOT/$PROJECT-iphoneos.xcarchive/Products/Library/Frameworks/$basename" \
            -output "$SRCROOT/Frameworks/$framework_name.xcframework"
    done

    copyCommonFramworks
}

function copyCommonFramworks() {
  cp -R $SRCROOT/Pods/hermes-engine/destroot/Library/Frameworks/universal/hermes.xcframework $SRCROOT/Frameworks/hermes.xcframework
}

function clean() {
    rm -rf $SRCROOT/$PROJECT-iphoneos.xcarchive
    rm -rf $SRCROOT/$PROJECT-iphonesimulator.xcarchive
    rm -rf Pods
    rm -rf node_modules
}

function build_and_create_frameworks() {
    local configuration="Release"
    rm -rf build
    yarn
    pod install
    archive $configuration
    create_xcframework
    clean
}

function initDirectory() {
    rm -rf $SRCROOT/Frameworks
    rm -rf $SRCROOT/Sources
    mkdir $SRCROOT/Frameworks
    mkdir Sources
    touch Sources/dummy.swift
}

initDirectory
build_and_create_frameworks 
ruby ./generate_package_swift.rb
package.swift 를 생성하는 스크립트 파일 generate_package_swift.rb 를 만듭니다.
touch generate_package_swift.rb
frameworks_dir = 'Frameworks'

frameworks = Dir.entries(frameworks_dir).select { |entry| entry.end_with?('.xcframework') }

framework_names = frameworks.map { |f| File.basename(f, '.xcframework') }

package_swift_content = <<~SWIFT
  // swift-tools-version:5.6
  import PackageDescription

  let package = Package(
      name: "PrebuiltReactNativeFrameworks",
      platforms: [
          .iOS(.v11)
      ],
      products: [
          .library(
              name: "PrebuiltReactNativeFrameworks",
              targets: ["PrebuiltReactNativeFrameworks"]
          )
      ],
      targets: [
          // 메인 타겟: 모든 프레임워크를 포함
          .target(
              name: "PrebuiltReactNativeFrameworks",
              dependencies: [
SWIFT

framework_names.each_with_index do |name, index|
  comma = index < framework_names.size - 1 ? ',' : ''
  package_swift_content << "                  \"#{name}\"#{comma}\n"
end

package_swift_content << <<~SWIFT
              ],
              path: "Sources/",
              sources: ["dummy.swift"],
              linkerSettings: [
                  .linkedLibrary("objc"),
                  .linkedLibrary("c++"),
                  .linkedLibrary("c++abi"),
                  .linkedFramework("JavaScriptCore", .when(platforms: [.iOS])),
              ]
          ),
SWIFT

framework_names.each_with_index do |name, index|
  comma = index < framework_names.size - 1 ? ',' : ''
  package_swift_content << <<~SWIFT
          .binaryTarget(
              name: "#{name}",
              path: "Frameworks/#{name}.xcframework"
          )#{comma}
  SWIFT
end

package_swift_content << <<~SWIFT
      ]
  )
SWIFT

File.open('Package.swift', 'w') do |file|
  file.write(package_swift_content)
end

puts "Package.swift 파일이 성공적으로 생성되었습니다."

build_xcframeworks.sh 스크립트를 를 수행하여 XCFramework들과 package.swift를 생성합니다.swift build 명령어로 완성된 package.swift가 잘 생성되었는지 확인해보면 좋습니다. 
완성된 Swift Package를 운영중인 프로젝트에 추가합니다.

React 가 import 되는것을 확인합니다. 


Prebuild의 장점
iOS 개발자에게 가장 큰 적은 빌드 시간입니다. 프로젝트의 복잡성이 증가할수록 빌드 시간도 기하급수적으로 증가합니다. 그래서 iOS 개발자에게 좋은 코드란 읽고 이해하기 좋거나 기능의 추가, 수정이 용이하는 등 아키텍처 측면에서 아름다운 것 외에도 빠르게 빌드 되는 코드라는 중요한 요소가 있습니다. 
CocoaPods를 이용해 React Native를 추가한다면 라이브러리들의 버전을 Resolve하는 시간, Fetch하는 시간이 걸리게 되고 첫 빌드 시 React Native 코드도 함께 빌드되어야 실행을 해볼 수 있습니다. 이론상 CocoaPods로 추가된 코드들은 처음 한 번만 빌드 되고 증분 빌드 시엔 다시 빌드 되지 않지만, 알 수 없는 원인으로 다시 빌드 시간이 소요되는 경우도 있습니다. 또한 Clean Build를 할 경우 명백하게 다시 빌드 시간이 소요됩니다.
만약 이 빌드 시간이 사라질 수 있다면 어떨까요? 예를 들어 1분의 시간이 절약되면, 하루 평균 checkout 횟수 * 개발자 수 의 시간이 매일 절약됩니다. 평균 checkout 횟수가 5회이고 개발자가 10명일 경우 하루에 50분의 시간이 절약되고, 한 달이면 1000분으로 16시간이 절약됩니다. 하지만 1분에서 멈추지 않고, 2분이 줄어들고 개발자가 20명이면 한 달에 4000분, 즉 66시간이 절약되게 됩니다. 

맺음말
이상 의존성 관리 도구를 하나만 사용해야 하는 이유, CocoaPods를 사용하지 않고 React Native를 iOS 환경에서 이용하는 방법, Prebuild를 사용하였을 때의 장점에 대해서 알아보았습니다. 이 방법을 사용하여 여러분도 의존성 관리 도구를 여러 개 사용하지 않고, 더 빠르게 빌드할 수 있길 바랍니다. 


프로젝트에 React Native를 도입할 때 크게 두 가지 방식이 있습니다.
프로젝트를 처음부터 React Native 로 개발한다.
현재 프로젝트에 부분적으로 React Native 를 도입한다.
베트남의 토스앱을 개발하던 때는 운영되는 서비스를 잠시 멈추고 React Native로 새로 개발했었습니다. 그 시점에 앱

토스와 비슷하게 많은 회사들이 각자 다른 이유로 운영 중인 서비스를 크로스 플랫폼으로 확장하고자 React Native를 도입하려고 할 거예요. 이런 경우에 CocoaPods를 사용하지 않고 React Native를 도입하는 방법을 알려드릴게요.

CocoaPods 없이 React Native 개발하기

웹과 유사한 개발 경험을 제공하는 React Native, 디버깅 경험은 과연 어떨까요? 토스에서 자체 디버깅 도구를 만들어 생산성을 끌어올리게 된 과정을 소개합니다.

잃어버린 생산성을 찾아서, React Native로 알아보는 디버깅


프론트엔드 개발자라면 한 번쯤 고민해봤을 성능 최적화!
토스 개발자들이 전하는 최적화의 본질과 실무 노하우를 공개합니다.
“서비스 최적화 언제, 어떻게 시작해야 할까요?”
”초기 로딩 속도를 개선하려면 무엇을 줄이고 바꿔야하는 걸까요?”
”사용자가 느끼는 반응성과 실제 성능, 둘 다 잡는 방법은?”
초기 로딩부터 런타임 최적화까지
토스의 박서진, 박건영, 조유성 님이 전하는 최적화 사례와 비법을 만나보세요!

타임스탬프
00:00 인트로
01:25 성능 최적화, 지금 시작해도 될까요?
04:30 초기 로딩 속도를 좌우하는 3대 요인
09:44 런타임 성능을 높이는 데 필요한 도구와 전략
16:07 React 리렌더링 최적화 꿀팁

출연진
박서진, 토스 Head of Frontend
박건영, 토스증권 Frontend Developer
조유성, 토스 UX Engineering Team Leader

다른 모닥불 회차 보러가기
EP.6 프론트엔드 개발에서 Next.js, 꼭 써야 할까?
EP.7 개발자 리더로서 성장당한 썰
EP.8 Next.js 그만 쓰세요! 면접관이 진짜 원하는 것!?




프론트엔드 개발자라면 한 번쯤 고민해봤을 성능 최적화!
토스 개발자들이 전하는 최적화의 본질과 실무 노하우를 공개합니다.
“서비스 최적화 언제, 어떻게 시작해야 할까요?”
”초기 로딩 속도를 개선하려면 무엇을 줄이고 바꿔야하는 걸까요?”
”사용자가 느끼는 반응성과 실제 성능, 둘 다 잡는 방법은?”
초기 로딩부터 런타임

프론트엔드 개발자라면 한 번쯤 고민해봤을 성능 최적화! 토스 개발자들이 전하는 최적화의 본질과 실무 노하우를 공개합니다.

초기 로딩부터 런타임 최적화까지, 토스의 박서진, 박건영, 조유성 님이 전하는 최적화 사례와 비법을 만나보세요!

프론트엔드 서비스 최적화? 토스에서는 '이렇게' 합니다! 모닥불 | EP.9

안녕하세요. 토스 Frontend Developer 강민우입니다.
토스팀 프론트엔드 챕터는 이전부터 퍼널에 관해 SLASH23 발표도 했었고, Slash Library에 use-funnel를 오픈소스로 배포하는 등 퍼널 라이브러리를 꾸준히 대내외적으로 사용하고 있었습니다. 그런데 기존에 사용하던 퍼널 라이브러리에는 다음과 같은 문제점들이 발견되기 시작했어요. 문제의식에 대한 더 자세한 내용은 이전의 선영님의 아티클을 읽어보세요.
Next.js에 의존성이 있기 때문에, react-router-dom을 사용하는 곳에서 쓰기 어려웠어요. 혹은 라우터를 사용하지 않는 곳에서 퍼널 상태를 관리하고 싶은 니즈도 있었고요.

각각의 단계별로 상태 관리를 지원하지 않기 때문에 이전 단계에서 입력한 상태를 현재 단계에서 있다는 것을 따로 증명해야 됐어요.
뒤로가기를 했을 때 현재 페이지에 있던 상태를 사용하고 싶지 않았어요. 기존 라이브러리에서는 상태를 히스토리에 연동하지 않기 때문입니다.
다양한 추가 기능을 넣고 싶은데 그러한 인터페이스가 마련되어 있지 않았어요. 예를 들어, 약관동의를 BottomSheet로 띄운 컴포넌트를 하나의 단계로 사용하기 어려웠어요.
이런 문제로 사내에서 워킹그룹으로 새롭게 @use-funnel 오픈소스 라이브러리를 개발하기 시작했어요. 이전 아티클에서는 문제의식과 워킹그룹의 타임라인을 공유드렸다면 이번 아티클에서는 라이브러리의 구현에 대해서 더 자세히 살펴볼게요.
Next.js 의존성 제거
먼저 Next.js 뿐만 아니라 다른 라우터를 지원하기 위해서 모노레포 형태의 콘셉트을 잡았습니다. @use-funnel/core 라는 패키지를 통해 핵심 기능을 만들어 둔 후, createUseFunnel 이라는 훅을 만드는 함수를 패키지에서 반환하도록 했습니다.
// @use-funnel/core
export function createUseFunnel(useRouter) {
	return function useFunnel(options) {
		const router = useRouter(options);
		// ... 퍼널 관련 코드들
	}
}
그리고 라우터를 구현하는 @use-funnel/next , @use-funnel/react-router-dom 패키지에서 실제 퍼널 상태를 만드는데 필요한 것들을 구현하도록 했습니다.
import { createUseFunnel } from '@use-funnel/core';
import { useMemo, useState } from 'react';

export const useFunnel = createUseFunnel(({ id, initialState }) => {
  const [history, setHistory] = useState([initialState]);
  const [currentIndex, setCurrentIndex] = useState(0);
  return useMemo(
    () => ({
      history,
      currentIndex,
      currentState: history[currentIndex],
      push(state) {
        setHistory((prev) => [...prev.slice(0, currentIndex + 1), state]);
        setCurrentIndex((prev) => prev + 1);
      },
      replace(state) {
        setHistory((prev) => {
          const newHistory = prev.slice(0, currentIndex + 1);
          newHistory[currentIndex] = state;
          return newHistory;
        });
      },
      go: (index) => setCurrentIndex((prev) => prev + index),
    }),
    [history, currentIndex],
  );
});
이를 통해 react-router-dom, @react-navigation/native 등 다양한 라우터 등을 대응할 수 있게 되었고, 커스텀한 상태를 구현할 경우를 위한 케이스를 위해 직접 @use-funnel/core 패키지를 가져와서 구현할 수 있게 되었습니다.
단계별로 상태 관리 안전하게 할 수 있게 하기
이렇게 만들어지는 useFunnel() 훅에 단계로 별로 상태 관리를 어떻게 정의할까요? 
// 기존의 useFunnel()
const [Funnel, setFunnel] = useFunnel(['AStep', 'BStep', 'CStep'] as const);

// 새로운 useFunnel()
const funnel = useFunnel<{
  AStep: { foo?: string; bar?: string };
  BStep: { foo: string; bar?: string };
  CStep: { foo: string; bar: string };
}>({
  initial: {
    step: 'AStep',
    context: {}
  }
});
기존에는 단순히 단계 배열을 요구하는 것이었지만, 새로운 useFunnel()을 사용할 때 각각의 단계별로 상태를 타입스크립트 제네릭으로 정의할 수 있게 했습니다. 
// 기존 렌더링
<Funnel>
  <Funnel.Step name="AStep"><AStep /></Funnel.Step>
  <Funnel.Step name="BStep"><BStep /></Funnel.Step>
  <Funnel.Step name="CStep"><CStep /></Funnel.Step>
</Funnel>

// 새로운 방식
switch (funnel.step) {
  case 'AStep': return <AStep />;
  case 'BStep': return <BStep foo={funnel.context.foo} />;
  case 'CStep': return <CStep foo={funnel.context.foo} bar={funnel.context.bar} />;
}
또한, 단계별로 상태를 추론하기 위해서 기존의 컴포넌트만 반환해주던 결과에서 구별된 유니온(Discriminated unions)을 반환해서 각 단계와 상태를 타입 안전하게 사용할 수 있도록 했어요.
switch (funnel.step) {
  case 'AStep': {
	  return (
		  <AStep
			  // BStep으로 이동하기 위해서는 `foo` 가 반드시 필요!
			  onNext={foo => funnel.history.push('BStep', { foo })}
		  />
	  );
  }
  case 'BStep': {
	  return (
		  <BStep
			  foo={funnel.context.foo}
			  onNext={bar => funnel.history.push('CStep', { bar })}
			  // AStep으로 이동하기 위해서는 아무런 조건이 없어도 되므로 상태를 안 넘겨줘도 됨.
			  onReplace={() => funnel.history.replace('AStep')}
		  />
	  );
  }
  case 'CStep': return <CStep foo={funnel.context.foo} bar={funnel.context.bar} />;
}
그리고 안전하게 다음 단계로 넘어가기 위해서, 단계를 변경할 때 해당 단계에 필요한 상태가 있는지 비교해서 꼭 필요한 상태가 누락되면 타입 오류가 나도록 했습니다.
예를 들어, 위 예제에서 “AStep” 의 경우 “BStep” 으로 이동하기 위해서 foo 프로퍼티가 필수로 요구되며, “BStep” 에서 “AStep” 으로 이동하기 위해서는 필수로 요구하지 않습니다.
이를 구현하기 위해서 타입스크립트에서 현재 단계의 상태 타입과 이동 단계의 상태 타입을 비교해서 달라진 상태가 있는지 확인했어요. 상태가 다르면 단계 이동 함수에서 반드시 상태를 기입하도록 했어요.
type CurrentStep = { foo: string; bar?: string };
type TargetStep = { foo: string; bar: string };

// { foo?: string; bar: string }
// CurrentStep에서 이미 foo가 존재하기 때문에 foo를 optional하게 요구합니다.
type Input = CompareMergeContext<CurrentStep, TargetStep>;
CompareMergeContext 타입의 자세한 구현체가 궁금하시면 이걸 열어주세요! 
// TBase에서 TResult로 변환할 때 필수적인 키를 가져옵니다.
export type RequiredCompareKeys<TBase, TResult> = keyof TResult | keyof TBase extends infer K
  ? K extends keyof TResult
    ? K extends keyof TBase
      ? TBase[K] extends TResult[K]
        ? never
        : K
      : undefined extends TResult[K]
        ? never
        : K
    : never
  : never;

// TBase에서 TResult로 변환할 때 필수적이지 않은 키를 가져옵니다.
export type OptionalCompareKeys<TBase, TResult> = keyof TBase | keyof TResult extends infer K
  ? K extends keyof TResult
    ? K extends keyof TBase
      ? TBase[K] extends TResult[K]
        ? K
        : never
      : undefined extends TResult[K]
        ? K
        : never
    : K extends keyof TBase
      ? K
      : never
  : never;
 
// RequiredCompareKeys와 OptionalCompareKeys를 합쳐서 새로운 객체 타입을 만든다.
export type CompareMergeContext<TBase, TResult> = Prettify<
  {
    [K in RequiredCompareKeys<TBase, TResult>]: K extends keyof TResult
      ? TResult[K]
      : K extends keyof TBase
        ? TBase[K]
        : never;
  } & {
    [K in OptionalCompareKeys<TBase, TResult>]?: K extends keyof TBase
      ? TBase[K]
      : K extends keyof TResult
        ? TResult[K]
        : never;
  }
>;
또한 런타임 밸리데이션을 통해 상태 검증을 구현해야 하는 경우, 제네릭 선언 없이 단계를 정의해서 사용할 수 있도록 했습니다.
import { z } from 'zod';

const AStepZod = z.object({ foo: z.string().optional(), bar: z.string().optional() });
const BStepZod = AStepZod.required({ foo: true });
const CStepZod = BStepZod.required({ bar: true });

const funnel = useFunnel({
  steps: {
    AStep: { parse: AStepZod.parse },
    BStep: { parse: BStepZod.parse },
    CStep: { parse: CStepZod.parse },
  },
  initial: {
    step: 'AStep',
    context: {},
  }
});
다양한 추가 기능을 구현하기 위한 인터페이스

토스에서는 유저에게 이용약관 및 개인정보 처리 동의를 받기 위해 같은 바텀시트를 활용한 UI를 자주 사용하는데요, 이러한 UI를 하나의 단계로 표현하고 싶은 니즈가 있었습니다.
기존의 useFunnel() 에서는 별도로 이전의 단계의 상태를 저장하고 있지 않기 때문에 이러한 구현이 조금 어려웠습니다.
새로운 버전의 useFunnel()에서는 이러한 다양한 문제를 해결하기 이전 단계들의 상태를 저장하고, 이를 쉽게 사용하기 위해 훅에서 반환되는 Render 컴포넌트를 만들었습니다.
const funnel = useFunnel(...);

<funnel.Render
	AStep={({ history }) => (
		<AStep
		  // BStep으로 이동하기 위해서는 `foo` 가 반드시 필요!
		  onNext={foo => history.push('BStep', { foo })}
	  />
  )}
  BStep={({ context, history }) => (
	  <BStep
		  foo={context.foo}
		  onNext={bar => history.push('CStep', { bar })}
		  // AStep으로 이동하기 위해서는 아무런 조건이 없어도 되므로 상태를 안 넘겨줘도 됨.
		  onReplace={() => history.replace('AStep')}
	  />
  )}
  CStep={({ context }) => <CStep foo={context.foo} bar={context.bar} />}
/>
이 컴포넌트 따로 switch-case 없이 모든 단계의 렌더링을 쉽게 사용할 수 있는 용도로도 사용할 수 있습니다.
여기에서 AStep에서 BStep으로 이동할 때, AStep의 렌더링을 그대로 유지한 채 BStep의 렌더링을 보여주고 싶었습니다. 이를 위해 funnel.Render.overlay 라는 구현체로 렌더 함수를 감싸서, 내부에서 처리하도록 했습니다.
<funnel.Render
	AStep={({ history }) => (
		<AStep
		  // BStep으로 이동하기 위해서는 `foo` 가 반드시 필요!
		  onNext={foo => history.push('BStep', { foo })}
	  />
  )}
  BStep={funnel.Render.overlay(({ context, history }) => (
	  <BStep
		  foo={context.foo}
		  onNext={bar => history.push('CStep', { bar })}
		  // AStep으로 이동하기 위해서는 아무런 조건이 없어도 되므로 상태를 안 넘겨줘도 됨.
		  onReplace={() => history.replace('AStep')}
	  />
	)}
  CStep={({ context }) => (
	  <CStep foo={context.foo} bar={context.bar} />
  )}
/>
내부 구현은 간단하게 다음과 같습니다.
const renderEntires: Array<{ step: string; element: React.ReactNode }> = [];

// Overlay를 렌더링할 때, renderBeforeOverlay에 먼저 렌더링할 단계의 컴포넌트들을 배열(renderEntires)에 추가합니다.
if (render.type === 'overlay') {
  declare const renderBeforeOverlay: Array<{ step: string; element: React.ReactNode }>;
  renderEntries.push(...renderBeforeOverlay);
}

renderEntires.push(render(funnelRenderStep));

return (
  <Fragment>
    {renderEntires.map((entry) => (
      <Fragment key={entry.step}>{entry.element}</Fragment>
    ))}
  </Fragment>
);
Render 컴포넌트는 항상 배열을 통해 현재 퍼널 단계를 렌더링하고 있습니다. 현재 퍼널 단계가 Overlay이라면 이전 단계를 배열에 담아서 렌더링을 하도록 했습니다.
추가로 Render 컴포넌트를 통해 한 가지 편의 기능을 추가한 것이 있습니다. 바로 현재 단계에서 조건에 따라 여러 단계의 퍼널로 갈 때 사용하기 좋은 funnel.Render.with 입니다.
<funnel.Render
	AStep={funnel.Render.with({
	  events: {
	    GoBStepWithFoo(foo: string, { history }) {
	      history.push('BStep', { foo })
	    },
	    GoBStepWithBar(bar: number, { history }) {
	      history.push('BStep', { bar })
	    },
	    GoCStep(_, { history }) {
	      history.push('CStep')
	    }
	  },
	  render({ dispatch }) {
		  return (
			  <AStep
			    onFoo={foo => dispatch('GoBStepWithFoo', foo)}
			    onBar={bar => dispatch('GoBStepWithBar', bar)}
			    onC={() => dispatch('GoCStep')}
			  />
		  );
	  }
	})}
/>
복잡한 퍼널에서 이동 규칙과 렌더링 규칙을 나눠줌으로써 응집성 있는 퍼널을 기대할 수 있게되었습니다.
마치며
토스에서는 이러한 공통된 관심사를 가진 사람들을 모아 워킹그룹을 운영할 수 있어요. 저에게는 이것이 첫 워킹그룹이었는데요, 단순히 사내 라이브러리 개선에서 시작해 오픈소스까지 발전해서 업무와 병행하느라 힘들었지만 그만큼 보람이 매우 깊었습니다. 
앞으로도 많은 기능과 개선을 꾸준히 진행할 예정입니다. @use-funnel 많이 사용해주시고 문제 있으면 언제든지 이슈를 남겨주세요. 
토스 프론트엔드 챕터는 @use-funnel 외에도 여러 오픈소스를 운영하고 있습니다. 토스에서 운영중인 오픈소스는 여기서 확인하실 수 있어요.



안녕하세요. 토스 Frontend Developer 강민우입니다.
토스팀 프론트엔드 챕터는 이전부터 퍼널에 관해 SLASH23 발표도 했었고, Slash Library에 use-funnel를 오픈소스로 배포하는 등 퍼널 라이브러리를 꾸준히 대내외적으로 사용하고 있었습니다. 그런데 기존에 사용하던 퍼널 라이브러리에는 다음과

이번 아티클에서는 @use-funnel 라이브러리의 구현 과정과 방법에 대해서 더 자세히 살펴볼게요.

@use-funnel 개발기 #2: 기존 라이브러리를 어떻게 뜯어 고칠 것인가?

새로운 기능을 개발하다 보면 이런 순간이 찾아와요. 모니터에는 수십 개의 탭이 열려있고, 팀 내부 도구 사용법을 찾아보려는데 문서가 어디 있는지조차 기억나지 않죠. 결국 동료에게 메시지를 보내고 답장을 기다리면서 개발 흐름이 끊기고 맙니다. 익숙한 상황이죠?
토스 프론트엔드 챕터도 비슷한 문제를 경험하고 있었는데요. 이 문제를 조금 다르게 풀어 봤습니다. 문서를 더 잘 써서 방문하게 하는 대신, 문서가 직접 찾아가는 방식으로요.
문서의 경로의존성 깨기
문서의 경로의존성은 사용자가 원하는 정보를 찾기 위해 정해진 경로를 따라가야 하는 제약을 뜻해요. 기존의 기술 문서는 생산자 입장에서 구조화되어 있어서 사용자 입장에서 원하는 정보를 찾으려면 여러 번의 탐색, 혹은 검색이 필요하죠. 이런 문서의 경로의존성을 깨기 위해 먼저 개발자들이 어떻게 일하는지 관찰하고, 인터뷰했어요. 
개발자들이 지식을 얻기 위해 주로 사용하는 방식은 “질문하기”였어요. 옆에 있는 동료에게 물어보거나, 사내 메신저 채널에 질문을 던지는 거죠. 자연스럽고 공감되는 행동이었어요. 그래서 이런 개발자의 행동을 존중하는 방식으로 문서의 형태를 바꿔보기로 했습니다.
질문하기의 가장 큰 장점은 원하는 정보를 즉각적으로 얻을 수 있다는 거예요. 방대한 문서를 검색하고 읽는 것보다 동료에게 직접 물어보는 것이 시간과 노력 면에서 훨씬 효율적이에요. 개발자들이 문서를 더 적극적으로 활용하게 하려면, 이러한 즉각성이 문서에도 필요하다고 생각했어요. 마치 대화하듯이 문서에 질문을 던졌을 때 맥락에 맞는 답변을 바로 받을 수 있다면, 문서는 더욱 강력한 도구가 될 거예요.
그렇게 탄생한 도구가 바로 ‘박씨’에요.
박씨: 질문하면서 문서 읽기
특징: 질문하면 문서 내용을 기반으로 답변해줘요. 일의 흐름이 끊기지 않고 바로바로 정보를 얻을 수 있어요.
위치: IDE(VSCode, Cursor)와 사내 메신저에 있어요.
효과: "문서 찾기"가 아닌 "대화하듯 물어보기”로 지식을 얻을 수 있어요.
재밌는 점: 박씨는 프론트엔드 챕터 헤드 서진님의 페르소나를 따서 만들어 졌어요.


박씨는 LLM이 더 정확하고 신뢰할 수 있는 답변을 만들어내기 위해 개발된 RAG(Retrieval-Augmented Generation) 기반 챗봇이에요. 기존 문서들을 바탕으로 믿을 수 있는 정보를 답변하고, 그 출처를 함께 제공해요. 박씨를 사용하면 문서를 탐색하거나 키워드로 검색할 필요 없이, 궁금한 점을 자연스럽게 물어보면서 필요한 정보를 얻을 수 있어요. 동료에게 물어보는 것보다 더 정확하고, 누구에게나 일관된 답변을 제공한다는 장점이 있죠.
박씨가 좋은 품질의 답변을 하려면 탄탄한 기반 지식이 필요해요. 그래서 저희는 문서의 양과 질을 모두 높이는 것에도 많은 공을 들이고 있어요. 하지만 테크니컬 라이터와 소수의 개발자들만으로는 충분한 문서를 만들기 어려웠어요. 이 시스템이 확장성을 가지려면 누구나 자신의 지식을 쉽게 문서화할 수 있어야 했죠. 그래서 실록봇이라는 문서 자동화 도구를 만들었답니다.
실록봇: 대화를 바로 문서화하기
역할: 사내 메신저 대화 속 중요 정보를 쉽게 문서화해요.
작동방식: 대화 스레드에 실록봇 이모지를 붙이거나 봇을 호출하면 AI가 대화를 분석하고 요약해서  PR을 올려요.
효과: 사람이 시간을 내서 문서를 따로 작성하는 것이 아니라, 실제 문제 해결 과정에서 자연스럽게 그리고 자동으로 기록할 수 있어요.

실록봇은 팀 내에서 오가는 중요한 대화를 요약해서 자동으로 문서화 해줘요. 사실 개발자들은 사내 메신저에서 질문에 답하거나 대화하며 항상 지식을 교류하고 있더라구요. 그런 대화가 메신저에서 일어나기 때문에 빠르게 휘발되고, 반복적으로 같은 질문이 올라오는 게 아쉬웠어요. 실록봇은 메신저에서 일어나는 대화를 요약해서 문서 리포지토리에 PR을 만들어요. 메신저에 남긴 유용한 메시지나 논의 스레드를 최소한의 노력으로 기록할 수 있게 된 것이죠.
예를 들어, 어떤 버그를 해결하기 위해 나눈 대화가 도움이 됐다고 생각한 팀원이 실록봇을 호출해요. 그러면 그 대화는 바로 문서가 되고, 이렇게 만들어진 정보는 박씨가 학습해요. 덕분에 팀원들은 같은 질문을 반복할 필요 없이 실록봇이 모은 정보와 박씨를 사용해 쉽게 해결책을 찾을 수 있어요. 문서를 위한 문서 작성이 아니라, 지식이 공유되는 순간에 자연스럽게 문서가 만들어지는 거예요.
지식이 흐르는 팀
박씨와 실록봇 덕분에 이제 토스 프론트엔드 챕터는 특정 팀원에게 지식이 몰려있거나, 같은 질문이 반복되는 문제가 줄었어요. 필요한 순간에 필요한 정보가 제공되면서 팀 내 지식이 자연스럽게 흐르는 환경이 되었답니다. 그리고 이런 환경이 팀의 생산성과 효율성을 높이고 있어요. 개발자의 행동을 관찰하고, ‘기술 문서’를 정적인 정보 모음이 아니라 개발자의 학습과 문제 해결을 도와주는 시스템으로 접근했던 것이 유효했어요.
테크니컬 라이팅도 함께 진화하고 있는데요. 이전에는 공급자 관점에서 정보를 구조화하고 특정 기능을 효과적으로 설명하는 것에 초점을 맞췄다면, 지금은 개발자가 문서를 잘 사용할 수 있는 시스템을 만드는 데 집중하고 있어요. 결국 테크니컬 라이팅의 본질은 ‘어떻게 문서로 개발자의 문제 해결을 도와줄 수 있을까’이기 때문이에요.
토스 프론트엔드 플랫폼 팀은 지식을 공유하고, 접근하기 좋은 학습 인프라를 만드는 여정에 함께하실 분을 기다리고 있어요. AI 기반 문서화 시스템을 더욱 발전시키고, 코드와 자연스럽게 연결되는 문서 자동화 시스템을 만들고, 사내 메신저를 비롯한 여러 플랫폼과 잘 어우러지는 문서 생태계를 구축하는 일들이 기다리고 있어요.
개발자들이 더 효율적으로 일할 수 있는 환경을 만들어서 개발자 경험을 한 단계 높이는 일에 관심 있으신가요? 그렇다면 Frontend Platform Engineer에 지원해 주세요! 함께 더 나은 개발 문화를 만들어가요.



새로운 기능을 개발하다 보면 이런 순간이 찾아와요. 모니터에는 수십 개의 탭이 열려있고, 팀 내부 도구 사용법을 찾아보려는데 문서가 어디 있는지조차 기억나지 않죠. 결국 동료에게 메시지를 보내고 답장을 기다리면서 개발 흐름이 끊기고 맙니다. 익숙한 상황이죠?
토스 프론트엔드 챕터도 비슷한 문제를 경험하고 있었는데요. 이 