MetaMask SDK + Dynamic SDK integration
Get started with MetaMask SDK and Dynamic SDK. You can set up the SDKs in the following ways:
- SDK CLI - Use the CLI to scaffold a Next.js and Wagmi dapp with both SDKs.
- Quickstart template - Clone the template to set up a Next.js and Wagmi dapp with both SDKs.
- Manual setup - Set up both SDKs in an existing dapp.
Features include:
- Dual SDK integration - Seamlessly combine MetaMask and Dynamic SDKs.
- Wallet connection - Connect to MetaMask wallet with enhanced features.
- Mobile experience - Optimized for both desktop and mobile users.
- TypeScript support - Full type safety and modern development experience.
- Next.js integration - Built with Next.js 14 and App Router.
The project you will set up has the following structure:
├── app/
│ ├── providers.tsx # Main providers configuration
│ └── layout.tsx # Root layout with providers
├── components/
│ ├── Navbar.tsx # Navigation with wallet connection
│ └── Hero.tsx # Hero section with wallet status
├── wagmi.config.ts # Wagmi configuration
├── next.config.ts # Next.js configuration
└── package.json # Project dependencies
Prerequisites
- Node.js version 19 or later
- pnpm
- MetaMask installed in your browser or on mobile
- A Dynamic Environment ID
Set up using the CLI
-
Run the CLI command, replacing
<project-name>
with your project name:npx @consensys/create-web3-app <project-name>
-
Select the Dynamic Quickstart template:
? Please select the template you want to use:
Next.js Quickstart (MetaMask SDK Example) (Recommended)
❯ MetaMask <-> Dynamic Quickstart -
Select your preferred blockchain tooling if your project requires it:
? Would you like to include blockchain tooling? (Use arrow keys)
❯ HardHat
Foundry
None -
Select your preferred package manager. We recommend pnpm for speed and efficiency:
? Please select the package manager you want to use:
Yarn
NPM
❯ pnpm -
Select to enter your Dynamic Environment ID in the command prompt:
? The selected template uses Dynamic.xyz. You'll need a Dynamic Environment ID
added to a .env file. Would you like to add it now? You can get one from
https://app.dynamic.xyz/dashboard/developer/api Yes
? Please paste your Dynamic Environment ID: -
The CLI will take a few minutes to set up your project. Once complete, you can run the project using the following command in
<project-name>/packages/site
:pnpm run dev
You've successfully set up MetaMask SDK and Dynamic SDK. See how to use the combined SDKs.
Set up using a template
-
Download the MetaMask SDK + Dynamic SDK template:
git clone https://github.com/MetaMask/metamask-dynamic
-
Navigate into the repository:
cd metamask-dynamic
-
Install dependencies:
pnpm install
-
Create a
.env.local
file:touch .env.local
-
In
.env.local
, add aNEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID
environment variable, replacing<YOUR-ENVIRONMENT-ID>
with your Dynamic Environment ID:.env.localNEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID=<YOUR-ENVIRONMENT-ID>
-
Run the project:
pnpm dev
You've successfully set up MetaMask SDK and Dynamic SDK. See how to use the combined SDKs.
Set up manually
1. Install dependencies
Install the SDK and the required dependencies to an existing project:
pnpm i @dynamic-labs/sdk-react-core @dynamic-labs/ethereum @dynamic-labs/wagmi-connector wagmi viem @tanstack/react-query
2. Configure providers
Set up your providers in app/providers.tsx
:
"use client";
import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core";
import { EthereumWalletConnectors, IEthereum } from "@dynamic-labs/ethereum";
import { DynamicWagmiConnector } from "@dynamic-labs/wagmi-connector";
import { MetaMaskSDK } from "@metamask/sdk";
import { WagmiProvider } from "wagmi";
import { config } from "@/wagmi.config";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useEffect } from "react";
export function Providers({ children }: { children: React.ReactNode }) {
const queryClient = new QueryClient();
useEffect(() => {
if (typeof window === "undefined") return;
const MMSDK = new MetaMaskSDK({
dappMetadata: {
name: "MetaMask Dynamic Integration",
url: window.location.href,
},
});
const ethereum = MMSDK.getProvider();
if (ethereum) {
window.ethereum = ethereum as unknown as IEthereum;
}
}, []);
return (
<DynamicContextProvider
settings={{
mobileExperience: "redirect",
environmentId: process.env.NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID!,
walletConnectors: [EthereumWalletConnectors],
appName: "MetaMask Dynamic Integration",
}}
>
<WagmiProvider config={config}>
<QueryClientProvider client={queryClient}>
<DynamicWagmiConnector>{children}</DynamicWagmiConnector>
</QueryClientProvider>
</WagmiProvider>
</DynamicContextProvider>
);
}
3. Set up environment variables
Create a .env.local
file.
In .env.local
, add a NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID
environment variable, replacing <YOUR-ENVIRONMENT-ID>
with your Dynamic Environment ID:
NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID=<YOUR-ENVIRONMENT-ID>
You can now test your dapp by running pnpm run dev
.
Usage
Connect wallet
Use the Dynamic Widget in your components:
"use client";
import { DynamicWidget } from "@dynamic-labs/sdk-react-core";
export const Navbar = () => {
return (
<nav>
<DynamicWidget />
</nav>
);
};
Check wallet status
Use the useAccount
hook from Wagmi:
"use client";
import { useAccount } from "wagmi";
export const Hero = () => {
const { address, isConnected } = useAccount();
return (
<div>
{isConnected ? (
<p>Connected: {address}</p>
) : (
<p>Not connected</p>
)}
</div>
);
};
Production readiness
Before deploying your project to production:
- Update your
next.config.ts
with production domains. - Set up proper environment variables.
- Configure your Dynamic SDK environment ID.
- Ensure MetaMask SDK is properly initialized.
Troubleshoot
Common issues and solutions include:
- SDK initialization error:
- Ensure MetaMask is installed.
- Check environment variables.
- Verify network connectivity.
- TypeScript errors:
- Update type definitions.
- Check SDK versions compatibility.
- Mobile experience issues:
- Test on actual mobile devices.
- Verify redirect URLs.
- Check MetaMask Mobile installation.