Powered by

A design system from Family

Migration Guide

If you are coming from an earlier version of ConnectKit, you will need to make sure to update the following APIs listed below.

1.7.0 Breaking Changes

Update Packages

  1. Peer dependency wagmi updated to 2.x.

  2. Peer dependency viem updated to 2.x.

  3. Install the new peer dependency @tanstack/react-query at a minimum version of ^5.

npm i wagmi@2.x viem@2.x @tanstack/react-query@^5

Update Files

Read the wagmi migration guide for migrating from v1 to v2 to make sure your application is compatible.

  1. Rename wagmi's provider, and TanStack Query moved from wagmi into peer dependencies.

Replace <WagmiConfig> with <WagmiProvider>, and include TanStack Query's <QueryClientProvider>.

,
_app.tsx
import {
- WagmiConfig,
+ WagmiProvider,
  createConfig,
} from 'wagmi';
import { mainnet, polygon, optimism, arbitrum } from 'wagmi/chains';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ConnectKitProvider, getDefaultConfig } from 'connectkit';


const config = createConfig(
  getDefaultConfig({
    ... // your config
   })
);


+const queryClient = new QueryClient();


export const Web3Provider = ({ children }) => {
  return (
-   <WagmiConfig config={config}>
+    <WagmiProvider config={config}>
+      <QueryClientProvider client={queryClient}>
        <ConnectKitProvider>{children}</ConnectKitProvider>
+      </QueryClientProvider>
+    </WagmiProvider>
-   </WagmiConfig>
  );
};

  1. Remove alchemyId and infuraId in favor for wagmi transports.

These provider IDs no longer handled via the ConnectKit getDefaultConfig function, as they are now replaced with wagmi transports.

It is recommended to add in transports for each chain you want to support. You can read more about how to set up transports over at our RPC Providers documentation.

Learn more about this change in the wagmi migration guide.

,
_app.tsx
import { createConfig, http, fallback } from "wagmi";
import { mainnet } from 'wagmi/chains';


const config = createConfig(
  getDefaultConfig({
    chains: [mainnet],
-   alchemyId: process.env.ALCHEMY_ID,
-   infuraId: process.env.INFURA_ID,
+   transports: [
+       [mainnet.id]: fallback([
+         http(`https://mainnet.infura.io/v3/${process.env.INFURA_ID}`),
+         http(`https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_ID}`),
+         http(), // public fallback
+       ]),
+   ]
   })
);

1.4.0 Breaking Changes

Update Packages

  1. Peer dependency wagmi updated to 1.0.0.

  2. Removed ethers peer dependency in favour of viem.

npm uninstall ethers
npm i wagmi@1.x viem@1.x

Update Files

Read the wagmi migration guide for 1.x.x to make sure your application is compatible.

  1. Replace getDefaultClient with getDefaultConfig.

This change is to make the API more consistent with the rest of the wagmi ecosystem.

,
pages/_app.tsx
-import { createClient } from "wagmi";
+import { createConfig } from "wagmi";


-import { getDefaultClient } from "connectkit";
+import { getDefaultConfig } from "connectkit";

1.3.0 Breaking Changes

WalletConnect v1 has been sunset and ConnectKit now uses WalletConnect v2 by default.

To learn more about this change, please read the WalletConnect v2 announcement.

ConnectKit will continue to support WalletConnect v1 via the legacyWalletConnect connector up until June 28. However, it is recommended to migrate to WalletConnect v2 as soon as possible.

  1. Upgrade dependencies

Upgrade connectkit and wagmi:

npm install connectkit@^1.3.0 wagmi@^0.12.0

  1. Include a projectId in your client configuration

WalletConnect v2 requires a projectId to be included in the client configuration. You can get a projectId by signing up for a free account at WalletConnect Cloud.

,
App.tsx
...


const client = createConfig(
  getDefaultConfig({
    ...
+    walletConnectProjectId: process.env.WALLETCONNECT_PROJECT_ID,
    ...
  }),
);


...

If you are using a more advanced custom configuration, you will need to include the projectId within your WalletConnectConnector object.

1.2.0 Breaking Changes

If you are using the connectkit-siwe-next package, you will need to update your application to be compatible with the latest version.

connectkit-siwe-next has been updated to 0.1.0. Follow the steps below to make sure your application is compatible with this update.

Update Packages

For an in-depth guide on how to set up your application, please read the Sign In With Ethereum Documentation.

Update Files

  1. First you will need to split your siwe helper into two separate helpers, siweServer and siweClient.

,
siwe.ts (removed)
- import { siwe } from '../siwe';
,
siweServer.ts (new)
import { configureServerSideSIWE } from 'connectkit-next-siwe';


export const siweServer = configureServerSideSIWE(
  session: {
    cookieName: string, // defaults to "connectkit-next-siwe"
    password: string, // defaults to `process.env.SESSION_SECRET`
    cookieOptions: {
      secure: boolean, // defaults to true if `process.env.NODE_ENV === 'production'`
      // see https://www.npmjs.com/package/cookie for other options
    },
  },
);
,
siweClient.ts (new)
import { configureClientSIWE } from "connectkit-next-siwe";


export const siweClient = configureClientSIWE({
  apiRoutePrefix: string,
  statement: string, // defaults to "Sign In With Ethereum"
});

  1. Replace the siwe import in your pages/api/[...routes].ts file with the siweServer helper.

,
pages/api/[...routes].ts
- import { siwe } from '../../../siwe';
+ import { siweServer } from '../../../siweServer';


export default siweServer.apiRouteHandler;

  1. Replace the siwe import in your _app.tsx file with the siweClient helper.

,
pages/_app.tsx
- import { siwe } from '../siwe';
- <siwe.Provider>
...
- </siwe.Provider>


+ import { siweClient } from '../siweClient';
+ <siweClient.Provider>
...
+ </siweClient.Provider>

  1. Replace the siwe import in your getServerSideProps functions with the siweServer helper.

,
pages/index.tsx
- import { siwe } from '../../siwe';
+ import { siweServer } from '../../siweServer';


export const getServerSideProps: GetServerSideProps<Props> = async ({ req, res, }) => {
-   const { address } = await siwe.getSession(req, res);
+   const { address } = await siweServer.getSession(req, res);
  ...
});

For further reading please see the Sign In With Ethereum Documentation.

1.1.1 Breaking Changes

ConnectKit has updated the wagmi peer dependency to 0.9.x.

Read the wagmi migration guide for 0.9.x to make sure your application is compatible.

1.1.0 Breaking Changes

  1. ConnectKit is now a pure ES module, removing CommonJS support. If you are using modern tooling, like Next.js, Vite, or Vitest, you likely don't need to do anything. Remix and Jest require some additional configuration. Check out this guide for more info on ESM support and Frequently Asked Questions across various tools and setups.

  2. ConnectKit has updated the wagmi peer dependency to 0.8.x. Read more below to learn how to make sure your application is compatible.

Dependency Updates

The peer dependency wagmi has been updated to 0.8.x. Follow the steps below to make sure your application is compatible with this update.

  1. Upgrade dependencies

Upgrade ConnectKit and wagmi to their latest versions:

npm install connectkit@^1.1.0 wagmi@^0.8.0

  1. Check for breaking changes in wagmi

You will need to review if your application has been affected by breaking changes in wagmi.

Check out the wagmi migration guide for 0.8.x. Since this update skips version 0.7.x of wagmi, you will also need to review the wagmi migration guide for 0.7.x as well.

On this page