|
| 1 | +--- |
| 2 | +sidebar_label: Dynamic SDK integration |
| 3 | +description: MetaMask + Dynamic SDK Integration |
| 4 | +toc_max_heading_level: 2 |
| 5 | +--- |
| 6 | + |
| 7 | +# MetaMask SDK + Dynamic SDK integration |
| 8 | + |
| 9 | +Get started with MetaMask SDK and [Dynamic SDK](https://docs.dynamic.xyz/introduction/welcome). |
| 10 | +You can [use the quickstart template](#set-up-using-a-template), which automatically sets up both SDKs with a [Next.js](https://nextjs.org/docs) and [Wagmi](https://wagmi.sh/) dapp. |
| 11 | +You can also [manually set up the SDK](#set-up-manually) in an existing dapp. |
| 12 | + |
| 13 | +Features include: |
| 14 | + |
| 15 | +- **Dual SDK integration** - Seamlessly combine MetaMask and Dynamic SDKs. |
| 16 | +- **Wallet connection** - Connect to MetaMask wallet with enhanced features. |
| 17 | +- **Mobile experience** - Optimized for both desktop and mobile users. |
| 18 | +- **TypeScript support** - Full type safety and modern development experience. |
| 19 | +- **Next.js integration** - Built with Next.js 14 and App Router. |
| 20 | + |
| 21 | +## Project structure |
| 22 | + |
| 23 | +The project you will set up has the following structure: |
| 24 | + |
| 25 | +``` |
| 26 | +├── app/ |
| 27 | +│ ├── providers.tsx # Main providers configuration |
| 28 | +│ └── layout.tsx # Root layout with providers |
| 29 | +├── components/ |
| 30 | +│ ├── Navbar.tsx # Navigation with wallet connection |
| 31 | +│ └── Hero.tsx # Hero section with wallet status |
| 32 | +├── wagmi.config.ts # Wagmi configuration |
| 33 | +├── next.config.ts # Next.js configuration |
| 34 | +└── package.json # Project dependencies |
| 35 | +``` |
| 36 | + |
| 37 | +## Set up using a template |
| 38 | + |
| 39 | +1. Download the [MetaMask SDK + Dynamic SDK template](https://github.com/MetaMask/metamask-dynamic): |
| 40 | + |
| 41 | + ```bash |
| 42 | + git clone https://github.com/MetaMask/metamask-dynamic |
| 43 | + ``` |
| 44 | + |
| 45 | +2. Navigate into the repository: |
| 46 | + |
| 47 | + ```bash |
| 48 | + cd metamask-dynamic |
| 49 | + ``` |
| 50 | + |
| 51 | +3. Install dependencies: |
| 52 | + |
| 53 | + ```bash |
| 54 | + pnpm install |
| 55 | + ``` |
| 56 | + |
| 57 | +4. Run the project: |
| 58 | + |
| 59 | + ```bash |
| 60 | + pnpm dev |
| 61 | + ``` |
| 62 | + |
| 63 | +You've successfully set up MetaMask SDK and Dynamic SDK. |
| 64 | +See how to [use the combined SDKs](#usage). |
| 65 | +
|
| 66 | +## Set up manually |
| 67 | +
|
| 68 | +### 1. Install dependencies |
| 69 | +
|
| 70 | +Install the SDK and the required dependencies to an existing project: |
| 71 | +
|
| 72 | +```bash |
| 73 | +pnpm i @dynamic-labs/sdk-react-core @dynamic-labs/ethereum @dynamic-labs/wagmi-connector wagmi viem @tanstack/react-query |
| 74 | +``` |
| 75 | +
|
| 76 | +### 2. Configure providers |
| 77 | +
|
| 78 | +Set up your providers in `app/providers.tsx`: |
| 79 | +
|
| 80 | +```typescript title="providers.tsx" |
| 81 | +"use client"; |
| 82 | +
|
| 83 | +import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core"; |
| 84 | +import { EthereumWalletConnectors, IEthereum } from "@dynamic-labs/ethereum"; |
| 85 | +import { DynamicWagmiConnector } from "@dynamic-labs/wagmi-connector"; |
| 86 | +import { MetaMaskSDK } from "@metamask/sdk"; |
| 87 | +import { WagmiProvider } from "wagmi"; |
| 88 | +import { config } from "@/wagmi.config"; |
| 89 | +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; |
| 90 | +import { useEffect } from "react"; |
| 91 | +
|
| 92 | +export function Providers({ children }: { children: React.ReactNode }) { |
| 93 | +
|
| 94 | + const queryClient = new QueryClient(); |
| 95 | +
|
| 96 | + useEffect(() => { |
| 97 | + if (typeof window === "undefined") return; |
| 98 | +
|
| 99 | + const MMSDK = new MetaMaskSDK({ |
| 100 | + dappMetadata: { |
| 101 | + name: "MetaMask Dynamic Integration", |
| 102 | + url: window.location.href, |
| 103 | + }, |
| 104 | + }); |
| 105 | +
|
| 106 | + const ethereum = MMSDK.getProvider(); |
| 107 | + if (ethereum) { |
| 108 | + window.ethereum = ethereum as unknown as IEthereum; |
| 109 | + } |
| 110 | + }, []); |
| 111 | +
|
| 112 | + return ( |
| 113 | + <DynamicContextProvider |
| 114 | + settings={{ |
| 115 | + mobileExperience: "redirect", |
| 116 | + environmentId: process.env.NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID!, |
| 117 | + walletConnectors: [EthereumWalletConnectors], |
| 118 | + appName: "MetaMask Dynamic Integration", |
| 119 | + }} |
| 120 | + > |
| 121 | + <WagmiProvider config={config}> |
| 122 | + <QueryClientProvider client={queryClient}> |
| 123 | + <DynamicWagmiConnector>{children}</DynamicWagmiConnector> |
| 124 | + </QueryClientProvider> |
| 125 | + </WagmiProvider> |
| 126 | + </DynamicContextProvider> |
| 127 | + ); |
| 128 | +} |
| 129 | +``` |
| 130 | +
|
| 131 | +### 3. Set up environment variables |
| 132 | +
|
| 133 | +Create a `.env.local` file: |
| 134 | +
|
| 135 | +```text title=".env.local" |
| 136 | +NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID=your_dynamic_environment_id |
| 137 | +``` |
| 138 | +
|
| 139 | +## Usage |
| 140 | +
|
| 141 | +### Connect wallet |
| 142 | +
|
| 143 | +Use the Dynamic Widget in your components: |
| 144 | +
|
| 145 | +```typescript |
| 146 | +"use client"; |
| 147 | +
|
| 148 | +import { DynamicWidget } from "@dynamic-labs/sdk-react-core"; |
| 149 | +
|
| 150 | +export const Navbar = () => { |
| 151 | + return ( |
| 152 | + <nav> |
| 153 | + <DynamicWidget /> |
| 154 | + </nav> |
| 155 | + ); |
| 156 | +}; |
| 157 | +``` |
| 158 | +
|
| 159 | +### Check wallet status |
| 160 | +
|
| 161 | +Use the `useAccount` hook from Wagmi: |
| 162 | +
|
| 163 | +```typescript |
| 164 | +"use client"; |
| 165 | +
|
| 166 | +import { useAccount } from "wagmi"; |
| 167 | +
|
| 168 | +export const Hero = () => { |
| 169 | + const { address, isConnected } = useAccount(); |
| 170 | +
|
| 171 | + return ( |
| 172 | + <div> |
| 173 | + {isConnected ? ( |
| 174 | + <p>Connected: {address}</p> |
| 175 | + ) : ( |
| 176 | + <p>Not connected</p> |
| 177 | + )} |
| 178 | + </div> |
| 179 | + ); |
| 180 | +}; |
| 181 | +``` |
| 182 | +
|
| 183 | +## Production readiness |
| 184 | +
|
| 185 | +Before deploying your project to production: |
| 186 | +
|
| 187 | +1. Update your `next.config.ts` with production domains. |
| 188 | +2. Set up proper environment variables. |
| 189 | +3. Configure your Dynamic SDK environment ID. |
| 190 | +4. Ensure MetaMask SDK is properly initialized. |
| 191 | +
|
| 192 | +## Troubleshoot |
| 193 | +
|
| 194 | +Common issues and solutions include: |
| 195 | +
|
| 196 | +- **SDK initialization error:** |
| 197 | + - Ensure MetaMask is installed. |
| 198 | + - Check environment variables. |
| 199 | + - Verify network connectivity. |
| 200 | +- **TypeScript errors:** |
| 201 | + - Update type definitions. |
| 202 | + - Check SDK versions compatibility. |
| 203 | +- **Mobile experience issues:** |
| 204 | + - Test on actual mobile devices. |
| 205 | + - Verify redirect URLs. |
| 206 | + - Check MetaMask Mobile installation. |
0 commit comments