Getting Started

Overview

@wagmi/solid is a collection of Solid primitives for Ethereum. You can learn more about the rationale behind the project in the Why Wagmi section.

Manual Installation

To manually add @wagmi/solid to your project, install the required packages.

pnpm

pnpm add @wagmi/solid viem@2.x @tanstack/solid-query

npm

npm install @wagmi/solid viem@2.x @tanstack/solid-query

yarn

yarn add @wagmi/solid viem@2.x @tanstack/solid-query

bun

bun add @wagmi/solid viem@2.x @tanstack/solid-query

• Viem is a TypeScript interface for Ethereum that performs blockchain operations.
• TanStack Query is an async state manager that handles requests, caching, and more.
• TypeScript is optional, but highly recommended. Learn more about TypeScript support.

Create Config

Create and export a new Wagmi config using createConfig.

config.ts

import { http, createConfig } from '@wagmi/solid'
import { mainnet, sepolia } from '@wagmi/solid/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

In this example, Wagmi is configured to use the Mainnet and Sepolia chains, and injected connector. Check out the createConfig docs for more configuration options.

TypeScript Tip

If you are using TypeScript, you can "register" the Wagmi config or use the hook config property to get strong type-safety across Solid Context in places that wouldn't normally have type info.

register config

import {  } from '@wagmi/solid'

(() => ({ chainId: 123 }))
Argument of type '() => { chainId: 123; }' is not assignable to parameter of type 'Parameters<Config<readonly [{ blockExplorers: { readonly default: { readonly name: "Etherscan"; readonly url: "https://etherscan.io"; readonly apiUrl: "https://api.etherscan.io/api"; }; }; blockTime: 12000; ... 15 more ...; verifyHash?: ((client: Client<...>, parameters: VerifyHashParameters) => Promise<...>) | unde...'.
  Call signature return types '{ chainId: 123; }' and '{ cacheTime?: number | undefined; chainId?: 1 | 11155111 | undefined; scopeKey?: string | undefined; query?: LooseOmit<QueryOptions<bigint, GetBlockNumberErrorType, bigint, readonly [...]>, "queryKey" | "queryFn"> | undefined; config?: Config<...> | ... 1 more ... | undefined; watch?: boolean | ... 2 more ... | unde...' are incompatible.
    The types of 'chainId' are incompatible between these types.
      Type '123' is not assignable to type '1 | 11155111 | undefined'.

declare module '@wagmi/solid' {
  interface Register {
    : typeof 
  }
}

hook config property

import {  } from '@wagmi/solid'

(() => ({ chainId: 123, config }))
Argument of type '() => { chainId: 123; config: Config<readonly [{ blockExplorers: { readonly default: { readonly name: "Etherscan"; readonly url: "https://etherscan.io"; readonly apiUrl: "https://api.etherscan.io/api"; }; }; ... 16 more ...; verifyHash?: ((client: Client<...>, parameters: VerifyHashParameters) => Promise<boolean>) |...' is not assignable to parameter of type 'Parameters<Config<readonly [{ blockExplorers: { readonly default: { readonly name: "Etherscan"; readonly url: "https://etherscan.io"; readonly apiUrl: "https://api.etherscan.io/api"; }; }; blockTime: 12000; ... 15 more ...; verifyHash?: ((client: Client<...>, parameters: VerifyHashParameters) => Promise<...>) | unde...'.
  Call signature return types '{ chainId: 123; config: Config<readonly [{ blockExplorers: { readonly default: { readonly name: "Etherscan"; readonly url: "https://etherscan.io"; readonly apiUrl: "https://api.etherscan.io/api"; }; }; ... 16 more ...; verifyHash?: ((client: Client<...>, parameters: VerifyHashParameters) => Promise<...>) | undefined...' and '{ cacheTime?: number | undefined; chainId?: 1 | 11155111 | undefined; scopeKey?: string | undefined; query?: LooseOmit<QueryOptions<bigint, GetBlockNumberErrorType, bigint, readonly [...]>, "queryKey" | "queryFn"> | undefined; config?: Config<...> | ... 1 more ... | undefined; watch?: boolean | ... 2 more ... | unde...' are incompatible.
    The types of 'chainId' are incompatible between these types.
      Type '123' is not assignable to type '1 | 11155111 | undefined'.

By registering or using the hook config property, useBlockNumber's chainId is strongly typed to only allow Mainnet and Sepolia IDs. Learn more by reading the TypeScript docs.

Wrap App in Context Provider

Wrap your app in the WagmiProvider Solid Context Provider and pass the config you created earlier to the config property.

App.tsx

import { WagmiProvider } from '@wagmi/solid'
import { config } from './config'

function App() {
  return (
    <WagmiProvider config={config}>
      {/** ... */}
    </WagmiProvider>
  )
}

config.ts

import { http, createConfig } from '@wagmi/solid'
import { mainnet, sepolia } from '@wagmi/solid/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

Check out the WagmiProvider docs to learn more about Solid Context in Wagmi.

Setup TanStack Query

Inside the WagmiProvider, wrap your app in a TanStack Query Solid Context Provider, e.g. QueryClientProvider, and pass a new QueryClient instance to the client property.

App.tsx

import { QueryClient, QueryClientProvider } from '@tanstack/solid-query'
import { WagmiProvider } from '@wagmi/solid'
import { config } from './config'

const queryClient = new QueryClient()

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        {/** ... */}
      </QueryClientProvider>
    </WagmiProvider>
  )
}

config.ts

import { http, createConfig } from '@wagmi/solid'
import { mainnet, sepolia } from '@wagmi/solid/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

Check out the TanStack Query docs to learn about the library, APIs, and more.

Use Wagmi

Now that everything is set up, every component inside the Wagmi and TanStack Query Providers can use Wagmi Solid Primitives.

Profile.tsx

import { useConnection } from '@wagmi/solid'

export function Profile() {
  const connection = useConnection()

  return (
    <div>
      <p>Address: {connection.address}</p>
      <p>Status: {connection.status}</p>
    </div>
  )
}

App.tsx

import { QueryClient, QueryClientProvider } from '@tanstack/solid-query'
import { WagmiProvider } from '@wagmi/solid'
import { config } from './config'
import { Profile } from './Profile'

const queryClient = new QueryClient()

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <Profile />
      </QueryClientProvider>
    </WagmiProvider>
  )
}

config.ts

import { http, createConfig } from '@wagmi/solid'
import { mainnet, sepolia } from '@wagmi/solid/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

Next Steps

For more information on what to do next, check out the following topics.

• TypeScript Learn how to get the most out of Wagmi's type-safety and inference for an enlightened developer experience.
• Connect Wallet Learn how to enable wallets to connect to and disconnect from your apps and display information about connected accounts.
• Solid Primitives Browse the collection of Solid Primitives and learn how to use them.
• Viem Learn about Viem and how it works with Wagmi.