Skip to content

Commit 55aaff4

Browse files
cxalemalexandratran
cxalem
and
alexandratran
authored
feat: add MetaMask and Dynamic SDK integration guide (#1972)
* feat: add MetaMask and Dynamic SDK integration guide Introduces a new documentation file for integrating MetaMask SDK with Dynamic SDK in a Next.js application. The guide covers project setup, configuration, and usage examples, including wallet connection and status checks. It also outlines project structure and troubleshooting tips. * Adds a new item for 'quickstart/javascript-dynamic' under the Quickstart category. * Refactor JavaScript Dynamic SDK integration guide Consolidates the introduction paragraph for clarity and removes redundant installation instructions for the MetaMask SDK. Updates the Providers component to utilize React Query and simplifies the setup process. Adjusts the documentation structure by renaming sections and enhancing troubleshooting tips. * Refines the Providers component by integrating MetaMask SDK for improved wallet connection handling. Updates the use of React Query and adjusts the component structure for better clarity and functionality. Ensures compatibility with the latest SDK features. * edits --------- Co-authored-by: Alexandra Tran <[email protected]>
1 parent 4023643 commit 55aaff4

File tree

4 files changed

+219
-11
lines changed

4 files changed

+219
-11
lines changed

‎docs/whats-new.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ of the [MetaMask developer page](https://metamask.io/developer/).
1111

1212
## April 2025
1313

14+
- Documented [MetaMask SDK + Dynamic SDK integration](/sdk/quickstart/javascript-dynamic).
15+
([#1972](https://github.com/MetaMask/metamask-docs/pull/1972))
1416
- Documented [Snaps bundle analyzer option](/snaps/reference/cli/subcommands/#analyze).
1517
([#1955](https://github.com/MetaMask/metamask-docs/pull/1955))
1618

‎sdk-sidebar.js‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ const sidebar = {
66
{
77
type: 'category',
88
label: 'Introduction',
9-
collapsible: false,
9+
collapsible: false,
1010
collapsed: false,
1111
items: [
1212
'introduction/welcome',
@@ -23,18 +23,19 @@ const sidebar = {
2323
{
2424
type: 'category',
2525
label: 'Quickstart',
26-
collapsible: false,
26+
collapsible: false,
2727
collapsed: false,
2828
items: [
2929
'quickstart/javascript-wagmi',
3030
'quickstart/javascript',
31+
'quickstart/javascript-dynamic',
3132
'quickstart/react-native',
3233
],
3334
},
3435
{
3536
type: 'category',
3637
label: 'Guides',
37-
collapsible: false,
38+
collapsible: false,
3839
collapsed: false,
3940
items: [
4041
'guides/authenticate-users',
@@ -44,7 +45,7 @@ const sidebar = {
4445
{
4546
type: 'category',
4647
label: 'Advanced',
47-
collapsible: true,
48+
collapsible: true,
4849
collapsed: true,
4950
items: [
5051
'guides/advanced/connect-and-sign',
@@ -57,13 +58,11 @@ const sidebar = {
5758
{
5859
type: 'category',
5960
label: 'Reference',
60-
collapsible: false,
61+
collapsible: false,
6162
collapsed: false,
62-
items: [
63-
'reference/sdk-options'
64-
],
65-
}
63+
items: ['reference/sdk-options'],
64+
},
6665
],
67-
};
66+
}
6867

69-
module.exports = sidebar;
68+
module.exports = sidebar

‎sdk/introduction/welcome.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,4 +32,5 @@ You can get started quickly with the following dapp platforms:
3232

3333
- [JavaScript + Wagmi (recommended)](quickstart/javascript-wagmi.md)
3434
- [JavaScript](quickstart/javascript.md)
35+
- [Dynamic SDK integration](quickstart/javascript-dynamic.md)
3536
- [React Native](quickstart/react-native.md)

‎sdk/quickstart/javascript-dynamic.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
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

Comments
 (0)