Migrate from v2 to v3

Overview

Wagmi v3 gives you total control over connector dependencies. Since Wagmi's initial release, Wagmi included required connector dependencies as part of its package to eliminate the need to manage multiple third-party dependencies.

This worked worked well in the early years as a "batteries-included" approach, but didn't allow for more fine-grained control over your dependency tree. By giving you control over connector dependencies, you can decide to only install what you need, manage version bumps at your own pace, and have total control over what third-party code and licenses you bring into your project

To get started, install the latest version of Wagmi.

pnpm

pnpm add @wagmi/core@3

npm

npm install @wagmi/core@3

yarn

yarn add @wagmi/core@3

bun

bun add @wagmi/core@3

Not ready to migrate yet?

The Wagmi v2 docs are still available at 2.x.wagmi.sh/core.

Install Connector Dependencies

All connector dependencies are now optional peer dependencies. This means that if you want to use a specific connector, you need to install its required dependencies.

For example, if you are using the porto connector, you also need to install the porto npm package. Required connector dependencies are listed below (along with links to npm, GitHub, Socket, and licenses) and on docs pages under the "Install" section.

Secure your supply-chain

Since you are now responsible for managing connector dependencies, take a look at Wagmi's Security Getting Started section to brush up on some best practices.

Building a developer tool on top of Wagmi?

If you are developing a library with Wagmi, you should decide if you want to install connector dependencies as part of your library ("batteries-included" approach) or pass the responsibility onto your users (more flexibility and control).

baseAccount

baseAccount requires @base-org/account

npmGitHubSocketOSI Compliant License

pnpm

pnpm add @base-org/account@~2.4.0

npm

npm install @base-org/account@~2.4.0

yarn

yarn add @base-org/account@~2.4.0

bun

bun add @base-org/account@~2.4.0

coinbaseWallet

coinbaseWallet requires @coinbase/wallet-sdk

npmGitHubSocketOSI Compliant License

pnpm

pnpm add @coinbase/wallet-sdk@~4.3.6

npm

npm install @coinbase/wallet-sdk@~4.3.6

yarn

yarn add @coinbase/wallet-sdk@~4.3.6

bun

bun add @coinbase/wallet-sdk@~4.3.6

gemini

gemini requires @gemini-wallet/core

npmGitHubSocketOSI Compliant License

pnpm

pnpm add @gemini-wallet/core@~0.3.1

npm

npm install @gemini-wallet/core@~0.3.1

yarn

yarn add @gemini-wallet/core@~0.3.1

bun

bun add @gemini-wallet/core@~0.3.1

metaMask

metaMask requires @metamask/sdk

npmGitHubSocketNon-OSI Compliant License

pnpm

pnpm add @metamask/sdk@~0.33.1

npm

npm install @metamask/sdk@~0.33.1

yarn

yarn add @metamask/sdk@~0.33.1

bun

bun add @metamask/sdk@~0.33.1

porto

porto requires porto

npmGitHubSocketOSI Compliant License

pnpm

pnpm add porto@~0.2.35

npm

npm install porto@~0.2.35

yarn

yarn add porto@~0.2.35

bun

bun add porto@~0.2.35

safe

safe requires @safe-global/safe-apps-provider and @safe-global/safe-apps-sdk

@safe-global/safe-apps-provider

npmGitHubSocketOSI Compliant License

@safe-global/safe-apps-sdk

npmGitHubSocketOSI Compliant License

pnpm

pnpm add @safe-global/safe-apps-provider@~0.18.6 @safe-global/safe-apps-sdk@~9.1.0

npm

npm install @safe-global/safe-apps-provider@~0.18.6 @safe-global/safe-apps-sdk@~9.1.0

yarn

yarn add @safe-global/safe-apps-provider@~0.18.6 @safe-global/safe-apps-sdk@~9.1.0

bun

bun add @safe-global/safe-apps-provider@~0.18.6 @safe-global/safe-apps-sdk@~9.1.0

walletConnect

walletConnect requires @walletconnect/ethereum-provider

npmGitHubSocketNon-OSI Compliant License

pnpm

pnpm add @walletconnect/ethereum-provider@~2.21.1

npm

npm install @walletconnect/ethereum-provider@~2.21.1

yarn

yarn add @walletconnect/ethereum-provider@~2.21.1

bun

bun add @walletconnect/ethereum-provider@~2.21.1

Bumped Minimum TypeScript Version

The minimum supported TypeScript version is now 5.7.3 instead of 5.0.4. Older versions of TypeScript should continue to work, but since TypeScript doesn't follow semver we recommend you update to at least 5.7.3. This should be relatively simple as there haven't been any breaking changes since 5.0.4.

Migrate v2 Deprecations

v2 deprecations Review the v2 migration guide for more information.

Deprecations

Renamed Account Actions

At the core of Wagmi are connections between apps and Ethereum providers (e.g. EIP-1193), getAccount, switchAccount, and watchAccount are renamed to getConnection, switchConnection, and watchConnection to more accurately represent to how Wagmi works.

import {
  getAccount,
  getConnection,
  switchAccount,
  switchConnection,
  watchAccount,
  watchConnection,
} from '@wagmi/core'

switchAccountMutationOptions is also updated to switchConnectionMutationOptions.

import {
  switchAccountMutationOptions,
  switchConnectionMutationOptions,
} from '@wagmi/core/query'