상태 관리 점진적 마이그레이션 (Recoil → Jotai)

세 가지 동기가 있었어요. 첫째, Recoil의 메인테이너 지원이 위축되고 있다는 시그널이 명확했습니다. 메인 메인테이너(Meta) 분의 활동이 줄었고 이슈 응답이 느려졌어요. 라이브 서비스의 핵심 인프라를 그런 라이브러리에 두는 건 리스크였어요. 둘째, 번들 사이즈 부담. Recoil은 트리쉐이킹이 잘 안 돼서 번들에 통째로 들어가곤 했어요. 셋째, atom key가 전역 문자열이라 매크로 단위 모듈 분리가 늘어날수록 충돌 위험이 누적됐습니다.

대안을 셋 비교했어요. Zustand는 가볍지만 사고 모델이 store 단위라 atom 단위로 잘게 쪼갠 코드를 옮기는 비용이 컸고, Redux Toolkit은 보일러플레이트 + immer 사고가 따라와서 전환이 너무 큰 충격이었어요. Jotai는 atom 모델 자체가 Recoil과 거의 동일하고, atom이 객체 참조라서 key 문자열 자체가 사라지는 등 Recoil의 약점만 깔끔하게 보완하는 선택지였습니다. 결국 마이그레이션 비용이 가장 작고 효과가 가장 큰 선택지여서 Jotai로 결정했어요.

Recoil은 atom을 만들 때 key: 'userAtom' 같은 문자열을 강제로 받아요. 이 key는 전역 namespace에 등록돼서, 다른 파일에서 같은 key로 atom을 또 만들면 개발 모드에서는 경고가 뜨고 프로덕션에서는 silent하게 한쪽이 덮어써집니다. 모노레포라 패키지가 여러 개고, atomFamily처럼 동적으로 생성되는 atom도 있다 보니 시간이 흐를수록 충돌 가능성이 누적됐어요.

Jotai에서는 atom이 그냥 자바스크립트 객체 참조로 식별돼요. const userAtom = atom(initial) 했으면 그 변수 자체가 atom의 정체성이고, 같은 이름의 변수를 두 모듈에서 만들면 그냥 다른 atom입니다. key 충돌이라는 개념 자체가 존재하지 않아요. 이게 Recoil 코드를 옮기면서 자연스럽게 사라진 부채여서, 마이그레이션의 부수 효과로 가장 컸던 부분이에요.

한 번에 다 갈아엎으면 라이브 서비스가 며칠 멈출 위험이 있어서, 둘을 공존시키는 전략을 짰어요. 앱 루트에 RecoilRoot가 있는 상태에서 그 내부에 Jotai의 Provider를 중첩으로 두고, 둘이 서로 간섭하지 않는다는 걸 먼저 검증했습니다.

그 다음 룰을 정했어요. 신규 기능은 무조건 Jotai로, 기존 Recoil 코드는 유지보수 시점에 자연스럽게 전환. 이건 Strangler Fig 패턴이에요. 새 기능을 늘리면서 점진적으로 옛 시스템을 잠식하는 거죠. PR 한 개당 대략 atom 하나씩 옮겼고, 그 atom을 쓰던 컴포넌트를 같이 옮기되 외부에서 그 atom을 쓰는 다른 컴포넌트가 있다면 양쪽 데이터를 잠시 동기화하는 어댑터 atom을 두기도 했습니다.

이 전략 덕에 마이그레이션 진행 중에도 매주 정상적으로 배포가 나갔고, 롤백이 필요한 상황이 한 번도 없었어요. 약 6개월에 걸쳐 자연스럽게 100% Jotai로 수렴했습니다. (※ 기간은 본인 기억에 맞게 보정)

처음엔 그냥 atom 옆에 useEffect 로 localStorage에 쓰는 코드를 넣었는데, 같은 패턴이 10군데 넘게 반복되면서 미묘하게 다 달랐어요. 어디는 try/catch가 있고 어디는 없고, JSON 파싱 실패 시 동작도 제각각이었습니다.

usePersistedState라는 훅으로 통합했어요. 시그니처는 usePersistedState(atom, key) 같은 단순한 형태고, 내부에서 마운트 시 localStorage에서 읽어오기·atom 변경 시 throttle된 쓰기·읽기 실패 시 기본값 fallback·SSR에서는 noop·storage 이벤트로 다른 탭 변경 동기화 — 이 다섯 가지 엣지케이스를 한 번에 처리합니다. Provider 패턴으로 묶어서 같은 atom을 여러 컴포넌트가 구독해도 storage 이벤트 리스너는 한 번만 붙도록 했고요.

결과적으로 관련 코드가 20% 정도 줄었고, "localStorage를 어떻게 다뤄야 안전하지?"라는 질문이 더 이상 PR 리뷰에 안 올라왔어요. 라이브러리 교체를 단순 작업으로 끝내지 않고, 코드 품질 개선의 기회로 활용한 사례였습니다.

atom이 작아지면 자유도는 올라가지만 그래프는 복잡해져요. 세 가지로 관리했습니다.

첫째, 작명 규칙. domain_role 형태로 통일했어요. material_color, editor_selection 같은 식이라 IDE에서 검색이 쉬웠습니다. 둘째, derived atom의 의존성을 JSDoc 으로 명시. @dependsOn material_color 같은 태그를 남겨서 코드 리딩 시 그래프를 따라가기 쉽게 했어요. 셋째, 순환 의존이 생기면 ESLint로 빌드를 막았어요. eslint-plugin-import의 no-cycle 룰로 강제했고, 순환이 잡히면 도메인을 잘못 잘랐다는 신호로 받아들여서 atom 분리 자체를 다시 봤습니다.

이렇게 해도 그래프 복잡도는 한계가 있어서, 다음 단계로 atom 그룹을 모듈 단위로 묶고 모듈 간 인터페이스를 selector atom 으로만 노출하는 패턴을 도입할 계획이었습니다.