This comprehensive guide will help you migrate from the legacy @initia/react-wallet-widget to the new and improved @initia/interwovenkit-react. InterwovenKit v2 offers better performance, improved TypeScript support, and a more intuitive API.
Migration Benefits
  • No more SSR configuration required
  • Better TypeScript support
  • Improved performance and bundle size
  • Simplified API with consistent naming
  • Enhanced error handling

​
Step-by-Step Migration

1

Update Package Installation

Replace the legacy wallet widget package with InterwovenKit.
# Remove old package
npm uninstall @initia/react-wallet-widget

# Install new package
npm install @initia/interwovenkit-react
Update all imports from @initia/react-wallet-widget to @initia/interwovenkit-react throughout your codebase.
2

Clean Up Legacy Configuration

Remove SSR-related imports and configuration that are no longer needed.
3

Install Required Peer Dependencies

InterwovenKit requires specific peer dependencies for proper functionality.
npm install wagmi viem @tanstack/react-query
These dependencies enable advanced wallet functionality and improved chain interaction capabilities.
4

Update Provider Configuration

Replace the legacy provider setup with the new InterwovenKit configuration.
providers.tsx
"use client"

import { PropsWithChildren, useEffect } from "react"
import { createConfig, http, WagmiProvider } from "wagmi"
import { mainnet } from "wagmi/chains"
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
import {
  initiaPrivyWalletConnector,
  injectStyles,
  InterwovenKitProvider
} from "@initia/interwovenkit-react"
import InterwovenKitStyles from "@initia/interwovenkit-react/styles.js"

// Configure Wagmi for wallet connections
const wagmiConfig = createConfig({
  connectors: [initiaPrivyWalletConnector],
  chains: [mainnet],
  transports: { [mainnet.id]: http() },
})

const queryClient = new QueryClient()

export default function Providers({ children }: PropsWithChildren) {
  useEffect(() => {
    // Inject styles into the shadow DOM used by Initia Wallet
    injectStyles(InterwovenKitStyles)
  }, [])

  return (
    <QueryClientProvider client={queryClient}>
      <WagmiProvider config={wagmiConfig}>
        <InterwovenKitProvider defaultChainId="YOUR_CHAIN_ID">
          {children}
        </InterwovenKitProvider>
      </WagmiProvider>
    </QueryClientProvider>
  )
}
The new provider structure separates concerns better and provides more flexibility for wallet configuration.

​
API Migration Guide

​
Provider Configuration Changes

<WalletWidgetProvider chainId="YOUR_CHAIN_ID" />

<WalletWidgetProvider customLayer={YOUR_CHAIN} />

​
Bridge Configuration Migration

export default function Providers() {
  return (
    <WalletWidgetProvider
      bridgeOptions={{
        defaultDstChainId: "YOUR_CHAIN_ID",
        defaultDstAssetDenom: "YOUR_DENOM"
      }}
    />
  )
}
Bridge configuration has moved from the provider level to individual method calls, providing more flexibility and better user experience.

​
Removed Provider Props

The following props are no longer supported: 
- <WalletWidgetProvider additionalWallets={...} />
- <WalletWidgetProvider filterWallet={...} />
To customize wallet options, use wagmi connectors in your wagmi configuration instead.

​
Hook and Method Changes

​
Wallet Connection Interface

import { truncate } from "@initia/utils"
import { useWallet } from "@initia/react-wallet-widget"

export default function WalletButton() {
  const { address, onboard, view, bridge, isLoading } = useWallet()

  if (!address) {
    return (
      <button onClick={onboard} disabled={isLoading}>
        {isLoading ? "Loading..." : "Connect Wallet"}
      </button>
    )
  }

  return (
    <div>
      <button onClick={bridge}>Open Bridge</button>
      <button onClick={view}>{truncate(address)}</button>
    </div>
  )
}
Ensure your entire application is wrapped with <InterwovenKitProvider> at the root level for the hooks to function properly.

​
Transaction Handling

import { useWallet } from "@initia/react-wallet-widget"

export default function TransactionComponent() {
  const { requestTx } = useWallet()

  const handleSubmit = async () => {
    try {
      const transactionHash = await requestTx(
        { messages: [] },
        { chainId: "YOUR_CHAIN_ID" }
      )
      console.log("Transaction submitted:", transactionHash)
    } catch (error) {
      console.error("Transaction failed:", error)
    }
  }

  return <button onClick={handleSubmit}>Submit Transaction</button>
}
For more granular control over transaction states, use requestTxSync() to get the transaction hash immediately, then waitForTxConfirmation() to wait for blockchain confirmation. See the useInterwovenKit reference for details.

​
Advanced Integration

​
Working with @initia/initia.js

For complex transaction building, InterwovenKit seamlessly integrates with @initia/initia.js:
example-usage.tsx
import { MsgSend, Msg } from "@initia/initia.js"
import { useInterwovenKit } from "@initia/interwovenkit-react"

// Helper function to convert Initia.js messages to InterwovenKit format
function toEncodeObject(msg: Msg) {
  const data = msg.toData()
  return {
    typeUrl: data["@type"],
    value: msg.toProto()
  }
}

export default function SendTransaction() {
  const { initiaAddress, requestTxBlock } = useInterwovenKit()

  const handleSend = async () => {
    // Build messages using initia.js
    const msgs = [
      MsgSend.fromPartial({
        fromAddress: initiaAddress,
        toAddress: "recipient_address_here",
        amount: [{ amount: "1000000", denom: "uinit" }],
      }),
    ]

    // Convert to InterwovenKit format
    const messages = msgs.map(toEncodeObject)

    try {
      const { transactionHash } = await requestTxBlock({
        messages,
        chainId: "YOUR_CHAIN_ID"
      })
      console.log("Transfer successful:", transactionHash)
    } catch (error) {
      console.error("Transfer failed:", error)
    }
  }

  return (
    <button onClick={handleSend} disabled={!initiaAddress}>
      Send INIT
    </button>
  )
}

​
Migration Checklist

Need help with migration? Check out the Getting Started guide for complete implementation examples, or refer to the API Reference for detailed method documentation.