wagmi-development

name	wagmi-development
description	Creates Wagmi features across all layers - core actions, query options, framework bindings. Use when adding new actions, hooks, or working across packages/core, packages/react, packages/vue.

Wagmi Development

Full-stack patterns for adding Wagmi features. This skill covers Viem-based actions only (not Wagmi config actions).

Layer Overview

1. Core Action (packages/core/src/actions/) - Base functionality wrapping Viem
2. Query Options (packages/core/src/query/) - TanStack Query integration
3. Framework Bindings - React (packages/react/src/hooks/), Vue (packages/vue/src/composables/)

---

1. Core Action

Structure

import {
  type MyActionErrorType as viem_MyActionErrorType,
  type MyActionParameters as viem_MyActionParameters,
  type MyActionReturnType as viem_MyActionReturnType,
  myAction as viem_myAction,
} from 'viem/actions'

import type { Config } from '../createConfig.js'
import type { ChainIdParameter, ConnectorParameter } from '../types/properties.js'
import type { Compute } from '../types/utils.js'
import { getAction } from '../utils/getAction.js'

export type MyActionParameters<config extends Config = Config> = Compute<
  ChainIdParameter<config> & viem_MyActionParameters
>

export type MyActionReturnType = viem_MyActionReturnType

export type MyActionErrorType = viem_MyActionErrorType

/** https://wagmi.sh/core/api/actions/myAction */
export async function myAction<config extends Config>(
  config: config,
  parameters: MyActionParameters<config>,
): Promise<MyActionReturnType> {
  const { chainId, ...rest } = parameters
  const client = config.getClient({ chainId })
  const action = getAction(client, viem_myAction, 'myAction')
  return action(rest)
}

Key Rules

• Viem imports: Prefix with viem_ (e.g., viem_getBalance)
• Client access:
  • Read-only: config.getClient({ chainId })
  • Wallet: await getConnectorClient(config, { chainId, connector, account })
  • Mixed: Use getConnectorClient for account, getClient for action (see estimateGas.ts)
• Parameters: Add ChainIdParameter<config> always. Add ConnectorParameter for wallet actions.
• Type params: Mirror Viem's type params for inference. Use const modifier for literal inference (abi, args).
• Spread: Omit wagmi-specific props (chainId, connector) when calling Viem action.

Testing

Runtime tests (action.test.ts):

import { abi, address, config } from '@wagmi/test'
import { expect, test } from 'vitest'
import { myAction } from './myAction.js'

test('default', async () => {
  await expect(myAction(config, { /* required params */ })).resolves.toMatchInlineSnapshot(`...`)
})

test('parameters: chainId', async () => { /* test chainId param */ })

test('behavior: error case', async () => { /* test error handling */ })

Type tests (action.test-d.ts) - only if action has type inference:

import { config } from '@wagmi/test'
import { expectTypeOf, test } from 'vitest'
import { myAction } from './myAction.js'

test('default', async () => {
  const result = await myAction(config, { /* params */ })
  expectTypeOf(result).toEqualTypeOf<ExpectedType>()
})

Type benchmarks (action.bench-d.ts) - only if action has type inference:

import { attest } from '@ark/attest'
import { test } from 'vitest'
import type { MyActionParameters } from './myAction.js'

test('default', () => {
  type Result = MyActionParameters<typeof abi.erc20, 'balanceOf'>
  const res = {} as Result
  attest.instantiations([12345, 'instantiations'])
  attest(res.args).type.toString.snap(`readonly [account: \`0x\${string}\`]`)
})

Wallet action tests: Connect before, disconnect after:

test('default', async () => {
  await connect(config, { connector })
  await expect(myAction(config, { /* params */ })).resolves.toMatchInlineSnapshot(`...`)
  await disconnect(config, { connector })
})

---

2. Query Options

Query (read-only) or Mutation (wallet) options for TanStack Query.

Query Structure

import {
  type MyActionErrorType,
  type MyActionParameters,
  type MyActionReturnType,
  myAction,
} from '../actions/myAction.js'
import type { Config } from '../createConfig.js'
import type { ScopeKeyParameter } from '../types/properties.js'
import type { QueryOptions, QueryParameter } from '../types/query.js'
import type { Compute, ExactPartial } from '../types/utils.js'
import { filterQueryOptions, structuralSharing } from './utils.js'

export type MyActionOptions<
  config extends Config,
  selectData = MyActionData,
> = Compute<ExactPartial<MyActionParameters<config>> & ScopeKeyParameter> &
  QueryParameter<MyActionQueryFnData, MyActionErrorType, selectData, MyActionQueryKey<config>>

export  myActionQueryOptions<
  config  ,
  selectData = ,
>(
  : config,
  : <config, selectData> = {},
): <config, selectData> {
   {
    ...options.,
    : (options. && (options.?. ?? )),
    :  (context) => {
       [, { : _, ...parameters }] = context.
       (!parameters.)   ()
       result =  (config, {
        ...(parameters  ),
        : parameters.,
      })
       result ?? 
    },
    : (options),
    structuralSharing, 
  }
}

   = <>
   = 

  myActionQueryKey<config  >(
  : <<<config>> & > = {},
) {
   [, (options)]  
}

  <config  > = < myActionQueryKey<config>>

  <
  config  ,
  selectData = ,
> = <, , selectData, <config>>

Mutation Structure

import type { MutationOptions, MutationParameter } from '../types/query.js'

export type MyActionOptions<config extends Config, context = unknown> = MutationParameter<
  MyActionData,
  MyActionErrorType,
  MyActionVariables<config>,
  context
>

export function myActionMutationOptions<config extends Config, context>(
  config: config,
  options: MyActionOptions<config, context> = {},
): MyActionMutationOptions<config> {
  return {
    ...options.mutation,
    mutationFn: async (variables) => {
      return myAction(config, variables)
    },
    mutationKey: ['myAction'],
  }
}

export type MyActionMutationOptions<config extends Config> = MutationOptions<
  MyActionData,
  MyActionErrorType,
  MyActionVariables<config>
>

Key Rules

• ExactPartial vs UnionExactPartial: Use ExactPartial for simple types, UnionExactPartial for complex unions (contract actions)
• enabled: Based on required params being truthy
• structuralSharing: Include when action returns objects/arrays
• filterQueryOptions: Filters common non-serializable props. Skip props like onReplaced manually in query key.
• Query key: Always ['actionName', filterQueryOptions(options)]

Testing

import { config } from '@wagmi/test'
import { expect, test } from 'vitest'
import { myActionQueryOptions } from './myAction.js'

test('default', () => {
  expect(myActionQueryOptions(config, {})).toMatchInlineSnapshot(`
    {
      "enabled": false,
      "queryFn": [Function],
      "queryKey": ["myAction", {}],
    }
  `)
})

test('enabled', () => {
  expect(myActionQueryOptions(config, { requiredParam: 'value' }).enabled).toBe(true)
})

test('queryFn: calls query fn', async () => {
  const options = myActionQueryOptions(config, { requiredParam: 'value' })
  const result = await options.queryFn({ queryKey: options.queryKey } as any)
  expect(result).toMatchInlineSnapshot(`...`)
})

---

3. Framework Bindings

React Query Hook

'use client'
import type { Config, MyActionErrorType, ResolvedRegister } from '@wagmi/core'
import type { Compute } from '@wagmi/core/internal'
import {
  type MyActionData,
  type MyActionOptions,
  myActionQueryOptions,
} from '@wagmi/core/query'
import type { ConfigParameter } from '../types/properties.js'
import { type UseQueryReturnType, useQuery } from '../utils/query.js'
import { useChainId } from './useChainId.js'
import { useConfig } from './useConfig.js'

export type UseMyActionParameters<
  config extends Config = Config,
  selectData = MyActionData,
> = Compute<MyActionOptions<config, selectData> & ConfigParameter<config>>

export type UseMyActionReturnType<selectData = MyActionData> =
  <selectData, >


  useMyAction<
  config   = [],
  selectData = ,
>(
  : <config, selectData> = {},
): <selectData> {
   config = (parameters)
   chainId = ({ config })
   options = (config, {
    ...parameters,
    : parameters. ?? chainId,
    : parameters.,
  })
   (options)
}

React Mutation Hook

'use client'
import { useMutation } from '@tanstack/react-query'
import type { Config, ResolvedRegister, MyActionErrorType } from '@wagmi/core'
import {
  type MyActionData,
  type MyActionMutate,
  type MyActionMutateAsync,
  type MyActionOptions,
  type MyActionVariables,
  myActionMutationOptions,
} from '@wagmi/core/query'
import type { ConfigParameter } from '../types/properties.js'
import type { UseMutationReturnType } from '../utils/query.js'
import { useConfig } from './useConfig.js'

export type UseMyActionParameters<config extends Config = Config, context = unknown> =
  MyActionOptions<config, context> & ConfigParameter<config>

export type UseMyActionReturnType<config extends  = , context = > =
  <
    ,
    ,
    <config>,
    context,
    <config, context>,
    <config, context>
  >


  useMyAction<
  config   = [],
  context = ,
>(
  : <config, context> = {},
): <config, context> {
   config = (parameters)
   options = (config, parameters)
   mutation = (options)
    = <config, context>
   {
    ...mutation,
    : mutation.  [],
    : mutation.  [],
  }
}

Vue Composable (Query)

import type { Config, MyActionErrorType, ResolvedRegister } from '@wagmi/core'
import type { Compute } from '@wagmi/core/internal'
import {
  type MyActionData,
  type MyActionOptions,
  myActionQueryOptions,
} from '@wagmi/core/query'
import { computed } from 'vue'
import type { ConfigParameter } from '../types/properties.js'
import type { DeepMaybeRef } from '../types/ref.js'
import { deepUnref } from '../utils/cloneDeep.js'
import { type UseQueryReturnType, useQuery } from '../utils/query.js'
import { useChainId } from './useChainId.js'
import { useConfig } from './useConfig.js'

export type UseMyActionParameters<
  config extends Config = Config,
  selectData = ,
> = <<<config, selectData> & <config>>>

  <selectData = > =
  <selectData, >


  useMyAction<
  config   = [],
  selectData = ,
>(
  : <config, selectData> = {},
): <selectData> {
   params = ( (parameters))
   config = (params)
   chainId = ({ config })
   options = (
    (config  , {
      ...params.,
      : params.. ?? chainId.,
      : params..,
    }),
  )
   (options  )  
}

Framework Rules

Rule	React	Vue
Top directive	'use client'	None
Parameters wrapper	Compute<...>	Compute<DeepMaybeRef<...>>
Reactivity	Direct	computed() + deepUnref()
Doc URL	wagmi.sh/react/api/hooks/	wagmi.sh/vue/api/composables/

Shared rules:

• ResolvedRegister['config']: Use in function signature only, not type defs
• No enabled/structuralSharing in hooks: Handled by queryOptions

Testing

Query hook test-d.ts:

import { abi } from '@wagmi/test'
import { expectTypeOf, test } from 'vitest'
import { useMyAction } from './useMyAction.js'

test('select data', () => {
  const result = useMyAction({
    /* params */
    query: {
      select(data) {
        expectTypeOf(data).toEqualTypeOf<ExpectedDataType>()
        return data
      },
    },
  })
  expectTypeOf(result.data).toEqualTypeOf<ExpectedDataType>()
})

Mutation hook test-d.ts:

import { expectTypeOf, test } from 'vitest'
import { useMyAction } from './useMyAction.js'

test('context', () => {
  const { mutate } = useMyAction({
    mutation: {
      onMutate(variables) {
        expectTypeOf(variables).toMatchTypeOf<{ /* expected shape */ }>()
        return { foo: 'bar' }
      },
      onError(error, variables, context) { /* test types */ },
      onSuccess(data, variables, context) { /* test types */ },
      onSettled(data, error, variables, context) { /* test types */ },
    },
  })

  mutate({ /* params */ }, {
    onSuccess(data, variables, context) { /* test inference */ },
  })
})

---

Exports

Add to exports/index.ts in respective package:

// packages/core/src/exports/index.ts
export {
  type MyActionParameters,
  type MyActionReturnType,
  type MyActionErrorType,
  myAction,
} from '../actions/myAction.js'

// packages/core/src/exports/query.ts
export {
  type MyActionData,
  type MyActionOptions,
  type MyActionQueryFnData,
  type MyActionQueryKey,
  type MyActionQueryOptions,
  myActionQueryKey,
  myActionQueryOptions,
} from '../query/myAction.js'

// packages/react/src/exports/index.ts
export {
  type UseMyActionParameters,
  type UseMyActionReturnType,
  useMyAction,
} from '../hooks/useMyAction.js'

---

Verification

# Format
pnpm format

# Type check (all or filtered)
pnpm check:types
pnpm --filter @wagmi/core check:types
pnpm --filter wagmi check:types

# Test (all or filtered)
pnpm test
pnpm test --project core
pnpm test --project react

# Update test snapshots
pnpm vitest -u

# Type benchmarks
pnpm bench:types

# Viem version mismatch in test snapshots
pnpm version:update:viem

# Build (all or filtered)
pnpm run clean && pnpm build
pnpm --filter @wagmi/core build