Wagmi v3 커넥터 피어 의존성 전환: UI 라이브러리 병목을 우회하는 커스텀 UI 구현

Wagmi v3는 지갑 커넥터를 선택적 피어 의존성 구조로 전환하며 프론트엔드 번들 크기를 최적화했습니다. 이 급격한 변화로 인해 기존 UI 라이브러리들은 빌드 경고를 내거나 호환성 문제를 겪고 있습니다. 써드파티 라이브러리의 업데이트를 수동적으로 기다리기보다, Wagmi v3의 새로운 API를 사용해 가볍고 제어력이 높은 커스텀 연결 UI를 직접 구축하는 방법을 살펴보겠습니다.

커넥터 피어 의존성 전환이 가져온 UI 킷 병목 현상

Wagmi v3는 지갑 커넥터를 코어에서 분리해 선택적 피어 의존성 구조로 전환했습니다. 기존 버전은 사용하지 않는 지갑의 SDK까지 전부 내장하는 구조였기에 프론트엔드 번들 용량이 불필요하게 늘어나는 한계가 있었습니다. v3는 이러한 번들 비대화 문제를 해결하기 위해 개발자가 실제로 사용할 지갑 라이브러리만 명시적으로 선택해 설치하는 구조를 채택했습니다.

이제 MetaMask 연결 기능을 사용하려면 @metamask/connect-evm 패키지를, Coinbase Wallet을 사용하려면 @coinbase/wallet-sdk 패키지를 프로젝트에 반드시 직접 설치해야 합니다. 외부 의존성 제어권을 프론트엔드 환경에 온전히 넘김으로써 실질적인 번들 크기 경량화를 달성할 수 있게 되었습니다.

하지만 이 급격한 아키텍처 개편은 생태계의 UI 라이브러리 병목이라는 부작용을 낳았습니다. RainbowKit이나 ConnectKit 같은 기성 지갑 연결 UI 라이브러리들이 Wagmi v3의 피어 의존성 변경 사항을 완벽히 반영하지 못해 빌드 경고와 의존성 충돌 문제를 야기하고 있기 때문입니다. 프로덕션 환경의 안정성을 지키고 번들 크기를 최적으로 유지하려면 외부 라이브러리 업데이트를 기다리기보다 직접 커스텀 UI를 구축하는 것이 고도화된 기술적 해법입니다.

핵심 API 변경점: useAccount에서 useConnection으로

Wagmi v3는 Web3 연결 세션의 정체성을 명확히 정의하기 위해 핵심 API의 명칭을 개편했습니다. 기존에 사용자 계정 상태를 조회하던 useAccount 훅이 EIP-1193 표준과의 일관성을 위해 useConnection으로 변경되었습니다. 이에 발맞춰 관련 생명주기를 추적하는 useAccountEffect는 useConnectionEffect로, 활성화된 연결을 전환하는 useSwitchAccount는 useSwitchConnection으로 각각 이름이 바뀌었습니다.

새로워진 useConnection 훅은 단순히 연결된 상태를 확인하는 것을 넘어 단일 지갑 주소인 address, 다중 계정 연결을 지원하는 배열 형태의 addresses, 현재 활성화된 체인을 나타내는 chainId, 사용 중인 지갑 객체인 connector 정보를 모두 포함하는 정밀한 세션 객체를 반환합니다. 특히 연결 수립 과정을 'connecting', 'reconnecting', 'connected', 'disconnected' 네 가지 세부 상태로 분류하는 status 문자열을 함께 반환하므로 복잡한 분기 처리 코드도 훨씬 간결하게 작성할 수 있습니다.

실제 커스텀 연결 상태 컴포넌트를 설계할 때도 이 반환 구조를 활용해 선언적인 UI를 쉽게 구현할 수 있습니다.

import { useConnection } from 'wagmi';

export function ConnectionProfile() {
  const { address, chainId, status } = useConnection();

  if (status === 'connecting' || status === 'reconnecting') {
    return <div>지갑 연결 상태를 확인하는 중입니다...</div>;
  }

  if (status === 'disconnected') {
    return <div>지갑을 연결해 주세요.</div>;
  }

  return (
    <div>
      <p>연결된 주소: {address}</p>
      <p>네트워크 ID: {chainId}</p>
    </div>
  );
}

Wagmi v3로 마이그레이션할 때 기존의 계정 중심 컴포넌트들을 이처럼 공급자 연결 중심으로 변경하면, 복잡한 써드파티 UI 라이브러리 없이도 반응성이 뛰어난 경량 커스텀 UI를 간결하게 완성할 수 있습니다.

TanStack Query v5 규칙과의 완전한 결합

Wagmi v3는 트랜잭션 전송이나 서명처럼 체인 상태를 변경하는 비동기 작업을 TanStack Query v5 규격의 Mutation 패턴으로 전면 표준화했습니다. 이전 버전들과 달리 useConnect, useWriteContract, useSignMessage 등의 핵심 훅들은 단순한 일회성 호출 함수 대신 완벽한 상태 수명 주기를 갖춘 Mutation 객체를 반환합니다. 개발자는 명시적으로 제공되는 실행 함수(.mutate()에 대응) 및 비동기 흐름 제어가 용이한 비동기 메서드(.mutateAsync()에 대응)를 사용해 실행 경로를 직접 제어해야 합니다.

이 아키텍처 통합의 장점은 로딩, 성공, 실패 등 트랜잭션 상태 관리가 극도로 단순해진다는 점입니다. 별도의 상태 관리 라이브러리나 복잡한 복제 코드 없이 Mutation 객체가 실시간으로 제공하는 상태 변수들을 UI에 직관적으로 매핑할 수 있습니다.

아래는 useWriteContract 훅을 활용해 계약을 호출할 때 비동기 에러를 캐치하는 구현 패턴입니다.

import { useWriteContract } from 'wagmi';

function MintButton() {
  const { writeContractAsync, isPending } = useWriteContract();

  const handleMint = async () => {
    try {
      // mutateAsync 패턴을 활용해 트랜잭션 수명 주기를 비동기로 직접 제어
      await writeContractAsync({
        address: '0x...', 
        abi: contractAbi,
        functionName: 'mint',
      });
      alert('민팅 성공!');
    } catch (error) {
      console.error('트랜잭션 오류:', error);
    }
  };

  return (
    <button onClick={handleMint} disabled={isPending}>
      {isPending ? '트랜잭션 처리 중...' : '민팅하기'}
    </button>
  );
}

이처럼 프로미스 체인을 직접 반환하는 비동기 메서드를 활용하면, 여러 트랜잭션을 연쇄적으로 실행하거나 사용자 거부 에러 처리를 프론트엔드 단에서 일관되게 구조화할 수 있습니다.

EIP-6963 기반 커스텀 멀티 인젝션 UI 구현

EIP-6963 규격은 브라우저에 여러 확장 지갑이 설치되어 있을 때 window.ethereum 전역 객체를 두고 서로 경쟁하던 충돌 문제를 근본적으로 해결합니다. Wagmi v3에서는 injected 커넥터를 설정하면 EIP-6963을 지원하는 여러 확장 지갑을 자동으로 발견하여 각각 독립된 공급자로 인식합니다. 개발자는 복잡한 감지 코드를 직접 구현할 필요 없이, 브라우저가 공급하는 지갑 이름과 아이콘 메타데이터를 활용해 세련된 멀티 인젝션 UI를 간결하게 렌더링할 수 있습니다.

또한, 메타마스크 커넥터에 새롭게 추가된 connectAndSign 옵션을 사용하면 지갑 연결 수락과 SIWE 인증 메시지 서명을 단 한 번의 사용자 승인 팝업으로 합칠 수 있습니다.

Wagmi v3에서 EIP-6963과 메타마스크 원스텝 연결을 구성하는 기본 설정 예시는 다음과 같습니다.

import { createConfig, http } from 'wagmi'
import { mainnet } from 'wagmi/chains'
import { injected, metaMask } from 'wagmi/connectors'

export const config = createConfig({
  chains: [mainnet],
  connectors: [
    injected(),
    metaMask({
      connectAndSign: true,
    }),
  ],
  transports: {
    [mainnet.id]: http(),
  },
})

이 조합을 활용하면 불필요한 이중 지갑 팝업을 차단하고 멀티 디바이스 환경에서 확장 지갑들 사이의 간섭 현상을 완전히 제거하는 고도화된 온체인 로그인 경험을 제공할 수 있습니다.

실무 마이그레이션 체크포인트

Wagmi v3로의 전환은 불필요한 의존성을 걷어내고 런타임 번들 크기를 최적화할 수 있는 좋은 기회입니다. 만약 Next.js나 Turbopack 환경에서 미설치 커넥터로 인해 빌드 경고가 발생한다면, next.config.ts 설정 파일에 간단한 경로 별칭 설정을 추가해 빌드 병목을 손쉽게 해결할 수 있습니다. 무거운 써드파티 UI 라이브러리의 업데이트를 수동적으로 기다리기보다, 완전히 새로워진 API를 활용해 프로젝트 요구사항에 딱 맞는 가볍고 독립적인 커스텀 연결 UI를 직접 구축해 볼 때입니다.