@walletconnect/wagmi-connector


Official WalletConnect connector for wagmi.

Installation

``bash


Using pnpm

pnpm add @walletconnect/wagmi-connector

Using npm

npm install @walletconnect/wagmi-connector

Using yarn

yarn add @walletconnect/wagmi-connector

Using bun

bun add @walletconnect/wagmi-connector
`

Usage

$3

`typescript
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'
import { injected } from 'wagmi/connectors'
import { walletConnect } from '@walletconnect/wagmi-connector'

export const config = createConfig({
chains: [mainnet, sepolia],
connectors: [
injected(),
walletConnect({
projectId: 'YOUR_WALLETCONNECT_PROJECT_ID' // dashboard.reown.com
}),
],
transports: {
[mainnet.id]: http(),
},
})
`

$3

`typescript
walletConnect({
projectId: string // Required: Your WalletConnect project ID
showQrModal?: boolean // Optional: Show QR modal (default: true)
isNewChainsStale?: boolean // Optional: Treat new chains as stale (default: true)
metadata?: { // Optional: App metadata
name: string
description: string
url: string
icons: string[]
}
qrModalOptions?: { // Optional: QR modal configuration
enableMobileFullScreen?: boolean
}
})
`

$3

If you're migrating from the built-in wagmi connector:

Before:
`typescript
import { walletConnect } from 'wagmi/connectors'
`

After:
`typescript
import { walletConnect } from '@walletconnect/wagmi-connector'
`

That's it! The API is exactly the same.

Local Development & Testing

$3

`bash


Install dependencies

pnpm install

Build the package

pnpm build

Clean build artifacts

pnpm clean
`

$3

1. In the connector package directory (~/Code/wagmi-connector):
`bash
# Build the package
pnpm build

# Link it globally
pnpm link --global
`

2. In your test application:
`bash
# Link the connector
pnpm link --global @walletconnect/wagmi-connector
`

3. Update your imports:
`typescript
// Replace wagmi/connectors import
import { walletConnect } from '@walletconnect/wagmi-connector'
`

4. Test the functionality:
- Run your dev server
- Test WalletConnect connection
- Verify all features work correctly

$3

`bash


In your test app

pnpm unlink @walletconnect/wagmi-connector

In the connector package

pnpm unlink --global
`

Requirements

- wagmi: ^2.0.0
- viem: ^2.0.0
- @wagmi/core: ^2.22.0
- TypeScript: >=5.0.4 (optional)

TypeScript

This package is built with TypeScript and includes type definitions. All types are exported from the main entry point:

`typescript
import { walletConnect, type WalletConnectParameters } from '@walletconnect/wagmi-connector'
`

API Reference

$3

Creates a WalletConnect connector instance.

#### Parameters

- projectId (required): Your WalletConnect Cloud project ID. Get one at cloud.walletconnect.com
- showQrModal (optional): Whether to show the QR modal for connection. Default: true
- isNewChainsStale (optional): How to handle newly added chains. Default: true
- true: Disconnect and require reconnection when new chains are added
- false: Attempt to continue connection (may error if wallet doesn't support dynamic chains)
- metadata (optional): Application metadata shown in wallet during connection
- qrModalOptions (optional): Configuration options for the QR modal
- enableMobileFullScreen: Enable full-screen mode on mobile devices

#### Returns

A wagmi connector instance that can be used in createConfig.

Examples

$3

`typescript
walletConnect({
projectId: 'YOUR_PROJECT_ID',
metadata: {
name: 'My DApp',
description: 'My awesome decentralized app',
url: 'https://myapp.com',
icons: ['https://myapp.com/icon.png']
}
})
`

$3

`typescript
walletConnect({
projectId: 'YOUR_PROJECT_ID',
showQrModal: false
})
`

$3

`typescript
walletConnect({
projectId: 'YOUR_PROJECT_ID',
isNewChainsStale: false // Allow dynamic chain additions
})
`

$3

`typescript
walletConnect({
projectId: 'YOUR_PROJECT_ID',
qrModalOptions: {
enableMobileFullScreen: true // Enable full-screen on mobile
}
})
`

Troubleshooting

$3

Make sure you've installed @walletconnect/ethereum-provider:
`bash
pnpm add @walletconnect/ethereum-provider
`

$3

Ensure you have the correct peer dependencies installed:
`bash
pnpm add wagmi viem @wagmi/core
`

$3

1. Verify your WalletConnect project ID is correct
2. Check that your chains are properly configured in wagmi
3. Ensure your RPC endpoints are accessible

License

See LICENSE.md for details. This project is licensed under the WalletConnect Community License Agreement.

$3

Portions © 2025 Reown, Inc. All Rights Reserved

This project includes code derived from wagmi, which is licensed under the MIT License. See NOTICE for full attribution details.

Links

- WalletConnect Documentation
- wagmi Documentation
- Get a Project ID

Contributing

This package is maintained by WalletConnect. We welcome contributions! Please follow these guidelines:

$3

1. Clone the repository:
`bash
git clone https://github.com/walletconnect/wagmi-connector.git
cd wagmi-connector
`

2. Install dependencies:
`bash
pnpm install
`

3. Build the package:
`bash
pnpm build
`

$3

`bash


Run tests once

pnpm test

Run tests in watch mode

pnpm test:watch

Run tests with coverage

pnpm test:coverage
`

$3

Before submitting a PR, ensure your code passes all checks:

`bash


Type checking

pnpm typecheck

Linting

pnpm lint

Format code

pnpm format

Check formatting

pnpm prettier:check
`

$3

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run all tests and linting checks
5. Commit your changes using Conventional Commits
6. Push to your fork and submit a Pull Request

$3

This project uses Changesets for version management.

1. Make your changes
2. Add a changeset:
`bash
pnpm changeset
``
3. Commit the changeset file
4. When merged to main, a PR will be automatically created to bump versions and update the changelog
5. Merging the version PR will automatically publish to npm

$3

The repository uses GitHub Actions for continuous integration:

- PR Checks: Runs on all pull requests, testing build, linting, type checking, and tests on Node.js 18.x and 20.x
- Publish: Automatically publishes to npm when version PRs are merged to main
- Canary Releases: Manual workflow for publishing canary versions

$3

Please open an issue in the repository to report bugs or request features.