Overview
Migration Guide
Migrating RainbowKit
The Wagmi peer dependency has been updated to 2.x.x.
Follow the steps below to migrate.
1. Upgrade RainbowKit, wagmi, and viem to their latest version
npm i @rainbow-me/rainbowkit@beta wagmi@2 viem@2
2. Install @tanstack/react-query peer dependency
With Wagmi v2, TanStack Query is now a required peer dependency.
Install it with the following command:
npm i @tanstack/react-query
3. Adjust your Wagmi configuration
+ import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
- import { configureChains, createConfig, WagmiConfig } from 'wagmi'
- import { publicProvider } from 'wagmi/providers/public'
+ import { http, createConfig, WagmiProvider } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'
- const { chains, publicClient } = configureChains(
- [mainnet, sepolia],
- [publicProvider()],
- )
const config = createConfig({
- autoConnect: true,
- publicClient
connectors,
+ chains: [mainnet, sepolia],
+ transports: {
+ [mainnet.id]: http(),
+ [sepolia.id]: http(),
+ },
})
+ const queryClient = new QueryClient()
const App = () => {
return (
- <WagmiConfig config={config}>
+ <WagmiProvider config={config}>
+ <QueryClientProvider client={queryClient}>
<RainbowKitProvider chains={chains}>
{/* Your App */}
</RainbowKitProvider>
+ </QueryClientProvider>
+ </WagmiProvider>
- </WagmiConfig>
);
};
4. Check for breaking changes in wagmi and viem
If you use wagmi hooks and viem actions in your dApp, you will need to follow the migration guides for v2:
1. Remove chains property
If you use getDefaultWallets make sure to remove chains property.
import { getDefaultWallets } from '@rainbow-me/rainbowkit';
const { wallets } = getDefaultWallets({
appName: 'RainbowKit demo',
- chains,
projectId,
});
If you use a wallet that requires chains property makes sure to remove that as well:
import { connectorsForWallets } from '@rainbow-me/rainbowkit/wallets';
import {
injectedWallet,
rainbowWallet,
metaMaskWallet,
coinbaseWallet,
walletConnectWallet,
} from '@rainbow-me/rainbowkit/wallets';
const connectors = connectorsForWallets([
...wallets,
{
groupName: 'Other',
wallets: [
- injectedWallet({ chains }),
- rainbowWallet({ projectId, chains }),
- metaMaskWallet({ projectId, chains }),
- coinbaseWallet({ chains, appName: 'My App' }),
- walletConnectWallet({ projectId, chains }),
+ injectedWallet(),
+ rainbowWallet({ projectId }),
+ metaMaskWallet({ projectId }),
+ coinbaseWallet({ appName: 'My App' }),
+ walletConnectWallet({ projectId }),
],
},
]);
2. WalletConnect legacy deprecation
RainbowKit no longer supports WalletConnect legacy option.
walletConnectWallet example usage.
walletConnectWallet(options: {
projectId: string;
- walletConnectVersion: '1';
options?: {
- qrcodeModalOptions?: {
- desktopLinks?: string[];
- mobileLinks?: string[];
- };
+ qrModalOptions?: {
+ desktopWallets?: DesktopWallet[];
+ mobileWallets?: MobileWallet[];
+ };
}
});
metaMaskWallet and rainbowWallet example usage.
// Rainbow wallet
rainbowWallet(options: {
projectId: string;
- walletConnectVersion: '1';
- walletConnectOptions?: {
+ walletConnectParameters?: {
- qrcodeModalOptions?: {
- desktopLinks?: string[];
- mobileLinks?: string[];
- };
+ qrModalOptions?: {
+ desktopWallets?: DesktopWallet[];
+ mobileWallets?: MobileWallet[];
+ };
}
});
// MetaMask wallet
metaMaskWallet(options: {
projectId: string;
- walletConnectVersion: '1';
- walletConnectOptions?: {
+ walletConnectParameters?: {
- qrcodeModalOptions?: {
- desktopLinks?: string[];
- mobileLinks?: string[];
- };
+ qrModalOptions?: {
+ desktopWallets?: DesktopWallet[];
+ mobileWallets?: MobileWallet[];
+ };
}
});
3. Custom wallet
If you've previously created your own wallet would need to update a few things.
Here is example of a custom injected wallet.
+ import { createConnector as wagmiCreateConnector } from 'wagmi';
+ import { injected } from 'wagmi/connectors';
const injectedWallet = (): Wallet => ({
id: 'injected',
name: 'Injected Wallet',
iconUrl: async () => (await import('./injectedWallet.svg')).default,
iconBackground: '#fff',
+ mobile?: { ... };
+ desktop?: { ... };
+ qrCode?: { ... };
+ extension?: { ... };
- createConnector: () => ({
- connector: new InjectedConnector({
- chains,
- options,
- }),
- mobile?: { ... };
- desktop?: { ... };
- qrCode?: { ... };
- extension?: { ... };
- }),
+ createConnector: (walletDetails: WalletDetailsParams) => {
+ return wagmiCreateConnector((config) => ({
+ ...injected({
+ target: () => ({
+ id: "windowProvider",
+ name: "Window Provider",
+ provider: window.ethereum,
+ }),
+ })(config),
+ ...walletDetails,
+ }));
+ },
});
Here is another example of a custom WalletConnect wallet.
+ import { createConnector as wagmiCreateConnector } from 'wagmi';
+ import { walletConnect } from 'wagmi/connectors';
const customWallet = (): Wallet => ({
id: 'custom',
name: 'Custom Wallet',
iconUrl: async () => (await import('./customWallet.svg')).default,
iconBackground: '#fff',
+ mobile?: { ... };
+ desktop?: { ... };
+ qrCode?: { ... };
+ extension?: { ... };
- createConnector: () => ({
- connector: new WalletConnectConnector({
- projectId: "...",
- }),
- mobile?: { ... };
- desktop?: { ... };
- qrCode?: { ... };
- extension?: { ... };
- }),
+ createConnector: (walletDetails: WalletDetailsParams) => {
+ return wagmiCreateConnector((config) => ({
+ ...walletConnect({
+ projectId: "...",
+ })(config),
+ ...walletDetails,
+ }));
+ },
});
The wagmi peer dependency has been updated to 1.x.x.
Follow the steps below to migrate.
1. Upgrade RainbowKit and wagmi to their latest version
npm i @rainbow-me/rainbowkit@^1 wagmi@^1
2. Install viem peer dependency
wagmi v1 requires the viem peer dependency. Install it with the following command:
Note: wagmi no longer uses the ethers package internally. But if you rely on the Authentication API, siwe will still require ethers as a peer dependency.
3. Ensure bundler and polyfill compatibility
In previous versions of wagmi that relied on ethers, the fs, net, and tls modules required by WalletConnect were automatically polyfilled. This is no longer the case with RainbowKit v1 + wagmi v1, which are built on viem.
Reference our Next.js Webpack Config and Create React App polyfills samples for configuration guidance for your project.
Additional framework guides for Vite and Remix are available here.
4. Check for breaking changes in wagmi
If you use wagmi hooks in your application, you will need to follow wagmi's migration guide to v1.
You can see their migration guide here.
The wagmi peer dependency has been updated to 0.12.x.
RainbowKit has adopted the WalletConnectLegacyConnector connector in wagmi for continued WalletConnect v1 support. Support for WalletConnect v2 and WalletConnectConnector will soon be available as a patch release, without breaking changes.
Wallets will be transitioned automatically in future releases.
Every dApp must now provide a WalletConnect Cloud projectId to enable WalletConnect v2. This must be completed before WalletConnect v1 bridge servers are shutdown on June 28, 2023. RainbowKit will quietly prefer v1 for all wallets if projectId is unspecified.
Follow the steps below to migrate.
npm i @rainbow-me/rainbowkit@^0.12.0 wagmi@^0.12.0
Every dApp that relies on WalletConnect now needs to obtain a projectId from WalletConnect Cloud. This is absolutely free and only takes a few minutes.
Provide the projectId to getDefaultWallets and individual RainbowKit wallet connectors like the following:
const projectId = 'YOUR_PROJECT_ID';
const { wallets } = getDefaultWallets({
appName: 'My RainbowKit App',
projectId,
chains,
});
const connectors = connectorsForWallets([
...wallets,
{
groupName: 'Other',
wallets: [
argentWallet({ projectId, chains }),
trustWallet({ projectId, chains }),
ledgerWallet({ projectId, chains }),
],
},
]);
The wagmi peer dependency has been updated to 0.11.x.
Follow the steps below to migrate.
npm i @rainbow-me/rainbowkit@^0.11.0 wagmi@^0.11.0
If you use wagmi hooks in your application, you will need to check if your application has been affected by the breaking changes in wagmi.
You can see their migration guide here.
The wagmi peer dependency has been updated to 0.10.x.
Follow the steps below to migrate.
npm i @rainbow-me/rainbowkit@^0.10.0 wagmi@^0.10.0
If you use wagmi hooks in your application, you will need to check if your application has been affected by the breaking changes in wagmi.
You can see their migration guide here.
The wagmi peer dependency has been updated to 0.9.x.
Follow the steps below to migrate.
npm i @rainbow-me/rainbowkit@^0.9.0 wagmi@^0.9.0
If you use wagmi hooks in your application, you will need to check if your application has been affected by the breaking changes in wagmi.
You can see their migration guide here.
The wagmi peer dependency has been updated to 0.8.x.
Follow the steps below to migrate.
npm i @rainbow-me/rainbowkit@^0.8.0 wagmi@^0.8.0
If you use wagmi hooks in your application, you will need to check if your application has been affected by the breaking changes in wagmi.
You can see their migration guide here.
If you're creating a custom wallet list, you must now import each wallet individually in order to reduce bundle size. Note that since wallets are no longer namespaced via the wallet object, all wallets now have a Wallet suffix.
-import { connectorsForWallets, wallet } from '@rainbow-me/rainbowkit';
+import { connectorsForWallets } from '@rainbow-me/rainbowkit';
+import {
+ injectedWallet,
+ rainbowWallet,
+ metaMaskWallet,
+ coinbaseWallet,
+ walletConnectWallet,
+} from '@rainbow-me/rainbowkit/wallets';
const wallets = [
- wallet.injected({ chains }),
- wallet.rainbow({ chains }),
- wallet.metaMask({ chains }),
- wallet.coinbase({ chains, appName: 'My App' }),
- wallet.walletConnect({ chains }),
+ injectedWallet({ chains }),
+ rainbowWallet({ chains }),
+ metaMaskWallet({ chains }),
+ coinbaseWallet({ chains, appName: 'My App' }),
+ walletConnectWallet({ chains }),
];
Also note that the Steakwallet backwards compatibility layer has been removed. Omni should be used instead.
-import { wallet } from '@rainbow-me/rainbowkit';
+import { omniWallet } from '@rainbow-me/rainbowkit/wallets';
const wallets = [
- wallet.steak({ chains }),
+ omniWallet({ chains }),
];
RainbowKit has updated the wagmi peer dependency to 0.5.x.
Follow the steps below to migrate.
Upgrade RainbowKit and wagmi to their latest version
npm i @rainbow-me/rainbowkit@^0.4.0 wagmi@^0.5.0
If you use wagmi hooks in your application, you will need to check if your application has been affected by the breaking changes in wagmi.
You can see their migration guide here.
Removed the chainId parameter from createConnector on the Wallet type.
Note that all built-in wallets are using the new API. Most consumers will be unaffected. This change only affects consumers that have created/consumed custom wallets.
If you previously derived RPC URLs from the chainId on createConnector, you can now remove that logic as wagmi now handles RPC URLs internally when used with configureChains.
import { connectorsForWallets, wallet, Chain, Wallet } from '@rainbow-me/rainbowkit';
import { chain, configureChains } from 'wagmi';
import { alchemyProvider } from 'wagmi/providers/alchemy';
import { publicProvider } from 'wagmi/providers/public';
import { WalletConnectConnector } from 'wagmi/connectors/walletConnect';
export interface MyWalletOptions {
chains: Chain[];
}
-const chains = [chain.mainnet]
+const { chains } = configureChains(
+ [chain.mainnet],
+ [
+ alchemyProvider({ alchemyId: process.env.ALCHEMY_ID }),
+ publicProvider(),
+ ]
+);
export const rainbow = ({ chains }: MyWalletOptions): Wallet => ({
...
- createConnector: ({ chainId }) => {
+ createConnector: () => {
- const rpc = chains.reduce(
- (rpcUrlMap, chain) => ({
- ...rpcUrlMap,
- [chainId]: chain.rpcUrls.default,
- }),
- {}
- );
const connector = new WalletConnectConnector({
chains,
options: {
qrcode: false,
- rpc,
},
});
}
...
}
const connectors = connectorsForWallets([
{
groupName: 'Recommended',
wallets: [
rainbow({ chains }),
],
},
]);
RainbowKit has updated the wagmi peer dependency to ^0.4.
Follow the steps below to migrate.
Upgrade RainbowKit and wagmi to their latest version
npm i @rainbow-me/rainbowkit@^0.2.0 wagmi@^0.4.2
Import configureChains from wagmi instead of RainbowKit:
- import { configureChains } from '@rainbow-me/rainbowkit';
+ import { configureChains } from 'wagmi';
RainbowKit no longer exports an apiProvider API. Replace it with your desired provider from wagmi.
- import { apiProvider } from '@rainbow-me/rainbowkit';
Import alchemyProvider from wagmi/providers/alchemy.
+ import { alchemyProvider } from 'wagmi/providers/alchemy';
const { chains, provider } = configureChains(
[chain.mainnet, chain.polygon, chain.optimism, chain.arbitrum],
- [apiProvider.alchemy(process.env.ALCHEMY_ID)]
+ [alchemyProvider({ alchemyId: process.env.ALCHEMY_ID })]
);
Import infuraProvider from wagmi/providers/infura.
+import { infuraProvider } from 'wagmi/providers/infura';
const { chains, provider } = configureChains(
[chain.mainnet, chain.polygon, chain.optimism, chain.arbitrum],
- [apiProvider.infura(process.env.INFURA_ID)]
+ [infuraProvider({ infuraId: process.env.INFURA_ID })]
);
Import jsonRpcProvider from wagmi/providers/jsonRpc.
+ import { jsonRpcProvider } from 'wagmi/providers/jsonRpc';
const { chains, provider } = configureChains(
[chain.mainnet, chain.polygon],
[
- apiProvider.jsonRpc(chain => ({
- rpcUrl: `https://${chain.id}.example.com`,
- })),
+ jsonRpcProvider({
+ rpc: chain => ({
+ http: `https://${chain.id}.example.com`,
+ }),
+ }),
]
);
Import publicProvider from wagmi/providers/public.
+ import { publicProvider } from 'wagmi/providers/public';
const { chains, provider } = configureChains(
[chain.mainnet, chain.polygon],
- [apiProvider.fallback()]
+ [publicProvider()]
);
Rename WagmiProvider to WagmiConfig.
import {
- WagmiProvider
+ WagmiConfig
} from 'wagmi'
const App = () => {
return (
- <WagmiProvider client={wagmiClient}>...</WagmiProvider>
+ <WagmiConfig client={wagmiClient}>...</WagmiConfig>
);
};
And you're done! 🌈
