Wagmi v2

[tmm]

Very excited to announce the next major version of Wagmi!

Wagmi v2 redesigns the core APIs to mesh better with Viem and TanStack Query. This major version transforms Wagmi into a light wrapper around these libraries, sprinkling in multichain support and account management. As such, there are some breaking changes and deprecations. Check out the migration guide for more info.

There are also some incredible features included in this release, like:

• Full TanStack Query support + queryKey exports
• Connect multiple connectors at a time
• Switch chains while disconnected
• EIP-6963 enabled
• Strongly typed chainId and chain properties
• Smaller bundle size and improved tree-shaking
• Updated docs at https://rc.wagmi.sh and NPM provenance

We recommend trying it out in your projects, but there may be breaking changes before the final release. If you find bugs or have feedback, please open an issue or reply to this discussion. All development is happening on the rc branch.

In general, since major versions don't happen that often, feel free to give feedback on anything. We appreciate the support!

[DannyDelott]

Excellent work on the release. Migration has been pretty smooth.

One issue: We get our connectors from RainbowKit. Is there a workaround to convert a v1 wagmi connector to a v2 one? I suspect Rainbowkit isn't far behind, but perhaps there's a simple solution in the meantime.

Example snippet:

import { createConfig, http } from "wagmi";
import { mainnet } from "wagmi/chains";
import { getDefaultWallets } from "@rainbow-me/rainbowkit";

const { connectors } = getDefaultWallets({
  appName: "my app",
  projectId: 'project-id'
  chains: [mainnet],
});

export const wagmiConfig = createConfig({
  chains: [mainnet]
  connectors, // <-- incompatable type
  transports: {
    [mainnet.id]: http('alchemy-url'),
  },
});

https://www.rainbowkit.com/docs/installation#configure

[jasperverbeet]

Looks like RainbowKit is working on it: rainbow-me/rainbowkit#1601.

We ended up building their PR and patching the dist folder locally (using pnpm patch). Works like a charm.

[mhpaler]

We're interested in doing something similar. Can you expand a bit more on how you performed this?

[oxSaturn]

Is react plugin from @wagmi/cli/plugins removed? Couldn't find it in source code, and it's not mentioned in the migration guide:

[tmm]

It's still a work-in-progress!

[tmm]

It's live.

https://beta.wagmi.sh/cli/api/plugins/react

[0xartcro]

What is the estimated release date?

[tmm]

Depends on how much feedback folks give, etc. Alpha will probably be for next month, then beta for a month, then major version release. This could change, but it's how the core team is thinking about it right now.

[MartinPucan]

@tmm please, is there more accurate estimate of when the release could be? Thank you!

[tmm]

Release candidate this week. Stable release first week of January.

[oxSaturn]

Wondering if anyone run into this issue with pnpm wagmi init:

/node_modules/@wagmi/cli/dist/esm/commands/generate.js:5
import { ensureDir, writeFile } from 'fs-extra';
                    ^^^^^^^^^
SyntaxError: Named export 'writeFile' not found. The requested module 'fs-extra' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export, for example using:

import pkg from 'fs-extra';
const { ensureDir, writeFile } = pkg;

    at ModuleJob._instantiate (node:internal/modules/esm/module_job:124:21)
    at async ModuleJob.run (node:internal/modules/esm/module_job:190:5)

Node.js v18.17.1

[script-money]

Wondering if anyone run into this issue with pnpm wagmi init:

/node_modules/@wagmi/cli/dist/esm/commands/generate.js:5
import { ensureDir, writeFile } from 'fs-extra';
                    ^^^^^^^^^
SyntaxError: Named export 'writeFile' not found. The requested module 'fs-extra' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export, for example using:

import pkg from 'fs-extra';
const { ensureDir, writeFile } = pkg;

    at ModuleJob._instantiate (node:internal/modules/esm/module_job:124:21)
    at async ModuleJob.run (node:internal/modules/esm/module_job:190:5)

Node.js v18.17.1

I has some issue, have to change code in node_modules

[iceanddust]

Same here. Applying the suggestion in the error message in the node_modules code fixes the bug. Although a better, tree-shakable approach I think would be to upgrade fs-extra to v11 and change the import source to fs-extra/esm

[generatorpoint]

Any updates on the wagmi-cli react plugin? Will we have a chance to test it out soon?

[tmm]

Working on it shortly. Will reply to this thread (and this one) once it's complete. Once it is out, there will be plenty of time for feedback in beta before heading to stable release.

[tmm]

It's released.

https://beta.wagmi.sh/cli/api/plugins/react

[unicape]

Are the config parameters in useConfig really useful?

Will anyone initialize the parameters externally and then pass them to useConfig to obtain them?
I don't think it makes any sense

[tmm]

It's probably not useful for most users, but for library authors (e.g. us building Wagmi) or folks that don't want to wrap their app in the Wagmi React Context Provider, it's useful. It streamlines the internal hook typing and bypasses the missing React Context Provider error.

[samuveth]

Will v2 support async loading of connectors? #2402

[tmm]

createConfig's connectors option is synchronous. If you don't want to configure connectors globally via createConfig, most hooks allow you to pass in a connector property.

[samuveth]

@tmm does this also work with v1?

[unicape]

Can the v2 version add more examples of hooks? I think there are only a small part now.

[tmm]

Any specific examples you think would be helpful? Planning to port over all of these (except the SIWE example).

[unicape]

Thank you, that's enough

[firnprotocol]

great work.

i am completely unable to switchChains or switchChainsAsync in wagmi2. on all connectors (injected MetaMask, WalletConnect, etc.), i get the error:

SwitchChainError: An error occurred when attempting to switch chain.

Details: Chain not configured.

Version: @wagmi/core@2.0.0-rc.0
Version: viem@2.0.0-rc.0
    at Object.switchChain (injected.js:274:1)
    at async switchChain (switchChain.js:14:1)

with error.code === 4902. thanks in advance

[firnprotocol]

k, was able to trivially reproduce just by adding the walletconnect connector to that sandbox: https://stackblitz.com/edit/vitejs-vite-ty17d7

steps to reproduce: connect using walletconnect (any wallet), then try switching chains

[tmm]

Can you create an issue so we can track it?

[firnprotocol]

k, see #3347

[kristiegiles]

I ran into this, too. The chainId --> { chainId } change isn't mentioned in the migration guide.

[tmm]

PR welcome!

[jasperverbeet]

It looks like V2 removed the suspense: true option, is this feature coming back in the future?

In v4 we could pass down the suspense: true property to useQuery, but now it looks like React Query has added a useSuspenseQuery hook in v5 (https://tanstack.com/query/latest/docs/react/reference/useSuspenseQuery).

[jasperverbeet]

One potential solution would be to update this function:

https://github.com/wevm/wagmi/blob/11936387bdd7db2a672ddcf9dee332828352f213/packages/react/src/utils/query.ts#L73C1-L85C1

To do something like:

// This line is new
const tanstack_useQueryFn = parameters.suspense
    ? tanstack_useSuspenseQuery
    : tanstack_useQuery;

  const result = tanstack_useQueryFn({
    ...(parameters as any),
    queryKeyHashFn: hashFn // for bigint support
  }) as UseQueryReturnType<data, error>;
  result.queryKey = parameters.queryKey;
  return result;

The following params are not available for useSuspenseQuery (see docs above), so these would have to be removed from the types:

• suspense
• throwOnError
• enabled
• placeholderData

[tmm]

TanStack Query v4 suspense support was experimental. Since the option was dropped from useQuery, it was also removed from Wagmi. Instead, you can use useSuspenseQuery along with TanStack Query-related exports from the 'wagmi/query' entrypoint.

import { useSuspenseQuery } from '@tanstack/react-query'
import { useConfig } from 'wagmi'
import { getBalanceQueryOptions } from 'wagmi/query'

const config = useConfig()
const result = useSuspenseQuery(
  getBalanceQueryOptions(config, { address: '0x…' })
)

In the future, we might add separate suspense hooks (e.g. useSuspenseBalance, useSuspenseReadContract. useSuspenseEnsName), but no immediate plans at this time as it's more to manage and we haven't heard from folks that it is an important feature.

[jasperverbeet]

Thank you for your reply :).

Initially, we ended up reimplementing those hooks as you described, but having that overhead in our app became a big point of frustration.

We later decided to patch it out since we use the new Suspense API everywhere.

pnpm patch wagmi@2.0.0-rc.0 

diff --git a/dist/esm/utils/query.js b/dist/esm/utils/query.js
index 4a08d4dc6796060752c48199a53f9798077e3079..74b5d19dfe73dc7c8980912e8c29840f8c8dddfb 100644
--- a/dist/esm/utils/query.js
+++ b/dist/esm/utils/query.js
@@ -1,4 +1,4 @@
-import { replaceEqualDeep, useInfiniteQuery as tanstack_useInfiniteQuery, useQuery as tanstack_useQuery, } from '@tanstack/react-query';
+import { replaceEqualDeep, useInfiniteQuery as tanstack_useInfiniteQuery, useSuspenseQuery as tanstack_useQuery, } from '@tanstack/react-query';
 import { deepEqual, } from '@wagmi/core/internal';
 import { hashFn } from '@wagmi/core/query';
 // Adding some basic customization.
diff --git a/src/utils/query.ts b/src/utils/query.ts
index 79dcb580a846610c8e059ce6adec2370396df996..90662e74a2284c0ec5be5f4866f5a40f03d62fce 100644
--- a/src/utils/query.ts
+++ b/src/utils/query.ts
@@ -9,7 +9,7 @@ import {
   type UseQueryResult,
   replaceEqualDeep,
   useInfiniteQuery as tanstack_useInfiniteQuery,
-  useQuery as tanstack_useQuery,
+  useSuspenseQuery as tanstack_useQuery,
 } from '@tanstack/react-query'
 import {
   type Evaluate,

I hope we get this feature natively in the future, but other than that, thank you for the hard work on this project. It's helped us massively over the last 1.5y or so.

[nicosampler]

@tmm could it be possible to add a wagmi config to indicate using useSuspenseQuery instead of useQuery as @jasperverbeet is suggesting?

[kristiegiles]

https://stackblitz.com/edit/vitejs-vite-9e1qqk?file=src%2Fcomponents%2FConnect.tsx
Why are there two separate MetaMask connectors now? It seems one has an id of "metaMaskSDK" and one is "io.metamask."

[glitch-txs]

Seems like MM SDK is already using EIP-6963, should we change its ID to io.metamask? would this filter the provider to avoid duplicates?

[tmm]

Could be up for this depending out the behavior. If someone wants to sketch out a PR, can take a look.

[glitch-txs]

my bad, the filter lives inside the mipd but not globaly for all connectors, so changing the ID doesn't work, I guess the best approach is to filter them manually outside Wagmi?

[androidsixteen]

I'm running into the same issue that @kristiegiles screenshotted above:
SDK state invalid -- undefined mobile provider

I've setmultiInjectedProviderDiscovery to false and have explicitly added MetaMask as a connector, so would prefer to get rid of this issue using those settings. The downside of relying on the injected connector is that you can't always assume that the user will have MetaMask installed

Was there any resolution for this, or any workaround we can use to suppress the error?

[jxom]

This is a MetaMask SDK issue unfortunately. Will ping them.

[kristiegiles]

I have a Next.js app that uses the pages directory. I had previously disabled SSR with dynamic imports on the wagmi config and any components using wagmi. For example:

const WagmiConfig = dynamic(
  import('wagmi').then((mod) => mod.WagmiConfig),
  { ssr: false }
);

I tried changing those to normal imports and adding ssr: true to the config. For example:

import { WagmiProvider } from 'wagmi';

const config = createConfig({
  ssr: true,
}

But the hydration errors came back...is this expected?

[tmm]

Can you provide a minimal reproduction? Hard to tell if this is related to Wagmi or something else without it.

[kristiegiles]

Here is a minimal reproduction: https://github.com/kristiegiles/nextjs-wagmi-qur2tj

The hydration mismatch error does not show in StackBlitz but should show if you run it locally.

Changing the import to

import dynamic from 'next/dynamic'
const WagmiProvider = dynamic(
  import("wagmi").then((mod) => mod.WagmiProvider),
  { ssr: false }
);

makes the hydration error go away.

[kristiegiles]

After upgrading to the latest version, I no longer get this error in my minimal reproduction.

[iceanddust]

Are you planning to add back to the actions and react plugins of the CLI package the ability to select which hooks and functions we want to be generated? I have a project where we make use of this functionality in v1 like so:

...
plugins: [
    react({
        useContractEvent: false,
        useContractRead: true,
        useContractFunctionRead: false,
        ...
    }),
    ...
],
... 

[tmm]

Not at the moment as any unused code is tree-shakable away and it's not work the extra flags IMO.

[iceanddust]

Fair enough.
I'm trying to generate the new file, but I'm running into some errors with the watch contract event generated hooks. It's claiming that functionName is not a property of createUseWatchContractEvent. I think it's because this line in the react CLI plugin should use eventName instead of functionName

[tmm]

Nice spot! PR welcome or create an issue and I can fix shortly.

[iceanddust]

Cool, I just opened a PR for that :)

[tmm]

Thank you! Will release soon.

[kristiegiles]

The migration guide shows data?.gas but in my version (2.0.0-rc.2), data from useEstimateGas is a bigint and data?.gas is undefined.

[kristiegiles]

Updated migration guide

[hiromaily]

Hi Wagmi team. This v2 is awesome!
I'm still using v1 and am curious about when wagmi v1 maintenance is end.

[tmm]

V1 will receive critical security fixes until the majority of users move over to v2.

[bjfresh]

Curious as to whether useReadContract/useWriteContract/useWaitForTransactionReceipt might eventually (re)gain support for onError/onSuccess callbacks from v1? These were especially useful eg. for Sentry error logging on failures. There are alternate ways of accomplishing this using isError/error, of course, but the previous interface was really nicely encapsulated.

[tmm]

useWriteContract still has these callbacks. They were removed from query hooks, not mutation hooks. Unlikely they come back for query hooks unless TanStack Query adds them back (which seems extremely unlikely).

[0xMySt1c]

is there a reason you cannot pass the data.request directly to the useWriteContract hook.

I wanted to bundle the entire useSimulateContract -> useWriteContract lifecycle into a custom hook (made the error handling much cleaner on the component side), but because useWriteContract no longer returns the write functions not sure it is possible?

[tmm]

It's not how TanStack Query does mutations. Wagmi has used TanStack Query internally since v0.2. Wagmi v2 aligns closer to how TanStack Query works so runtime and type-level behavior is more robust and stable.