From f93d3dab496c7a9d8b0be6510873744b6c715d41 Mon Sep 17 00:00:00 2001 From: Alejandro Date: Fri, 11 Apr 2025 13:29:40 +0200 Subject: [PATCH 1/5] 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. --- sdk/quickstart/javascript-dynamic.md | 221 +++++++++++++++++++++++++++ 1 file changed, 221 insertions(+) create mode 100644 sdk/quickstart/javascript-dynamic.md diff --git a/sdk/quickstart/javascript-dynamic.md b/sdk/quickstart/javascript-dynamic.md new file mode 100644 index 00000000000..d2fe7a82b54 --- /dev/null +++ b/sdk/quickstart/javascript-dynamic.md @@ -0,0 +1,221 @@ +--- +description: MetaMask + Dynamic SDK Integration +toc_max_heading_level: 2 +--- + +# MetaMask + Dynamic SDK Integration + +Get started with MetaMask SDK and Dynamic SDK integration in a Next.js dapp. +This project demonstrates how to combine both SDKs to create a seamless wallet connection experience +for both desktop and mobile users. + +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 + +## Project 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 +``` + +## Set up the project + +You can either clone the repository or set up the project manually: + +### Option 1: Clone the repository + +```bash +git clone https://github.com/MetaMask/metamask-dynamic +cd metamask-dynamic +pnpm install +``` + +### Option 2: Manual setup + +### 1. Install dependencies + +Install the required dependencies: + +```bash +pnpm i @metamask/sdk @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`: + +```typescript +import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core"; +import { EthereumWalletConnectors } from "@dynamic-labs/ethereum"; +import { DynamicWagmiConnector } from "@dynamic-labs/wagmi-connector"; +import { MetaMaskSDK } from "@metamask/sdk"; + +export function Providers({ children }) { + const [mounted, setMounted] = useState(false); + const [sdkInitialized, setSdkInitialized] = useState(false); + + useEffect(() => { + if (typeof window === 'undefined') return; + + const MMSDK = new MetaMaskSDK({ + dappMetadata: { + name: "MetaMask Dynamic Integration", + url: window.location.host, + }, + injectProvider: true, + communicationServerUrl: "https://metamask-sdk-socket.metamask.io", + }); + + const ethereum = MMSDK.getProvider(); + if (ethereum) { + window.ethereum = ethereum; + setSdkInitialized(true); + } + + setMounted(true); + }, []); + + return ( + + + + {children} + + + + ); +} +``` + +### 3. Configure Next.js + +Update your `next.config.ts`: + +```typescript +const nextConfig = { + allowedDevOrigins: [ + "http://localhost:3000", + "http://192.168.1.152:3000/", + "192.168.1.152:3000", + "192.168.1.152", + ], +}; +``` + +### 4. Set up environment variables + +Create a `.env.local` file: + +``` +NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID=your_dynamic_environment_id +``` + +## Usage + +### Connect Wallet + +Use the Dynamic Widget in your components: + +```typescript +"use client"; + +import { DynamicWidget } from "@dynamic-labs/sdk-react-core"; + +export const Navbar = () => { + return ( + + ); +}; +``` + +### Check Wallet Status + +Use the `useAccount` hook from Wagmi: + +```typescript +"use client"; + +import { useAccount } from "wagmi"; + +export const Hero = () => { + const { address, isConnected } = useAccount(); + + return ( +
+ {isConnected ? ( +

Connected: {address}

+ ) : ( +

Not connected

+ )} +
+ ); +}; +``` + +## Production Deployment + +For production deployments: + +1. Update your `next.config.ts` with production domains +2. Set up proper environment variables +3. Configure your Dynamic SDK environment ID +4. Ensure MetaMask SDK is properly initialized + +## Troubleshooting + +Common issues and solutions: + +1. **SDK Initialization Error** + - Ensure MetaMask is installed + - Check environment variables + - Verify network connectivity + +2. **TypeScript Errors** + - Update type definitions + - Check SDK versions compatibility + +3. **Mobile Experience Issues** + - Test on actual mobile devices + - Verify redirect URLs + - Check MetaMask Mobile installation + +## Additional Resources + +- [MetaMask SDK Documentation](https://docs.metamask.io/guide/sdk.html) +- [Dynamic SDK Documentation](https://docs.dynamic.xyz/) +- [Wagmi Documentation](https://wagmi.sh/) +- [Next.js Documentation](https://nextjs.org/docs) + +## Contributing + +1. Fork the repository +2. Create your feature branch +3. Commit your changes +4. Push to the branch +5. Create a Pull Request + +## License + +This project is licensed under the MIT License. \ No newline at end of file From 4cad01bad0a16c8fd69d4afb32bf51bc17b3aa95 Mon Sep 17 00:00:00 2001 From: Alejandro Date: Fri, 11 Apr 2025 13:36:23 +0200 Subject: [PATCH 2/5] Adds a new item for 'quickstart/javascript-dynamic' under the Quickstart category. --- sdk-sidebar.js | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/sdk-sidebar.js b/sdk-sidebar.js index ec9c5b148dd..f3028976433 100644 --- a/sdk-sidebar.js +++ b/sdk-sidebar.js @@ -6,7 +6,7 @@ const sidebar = { { type: 'category', label: 'Introduction', - collapsible: false, + collapsible: false, collapsed: false, items: [ 'introduction/welcome', @@ -23,18 +23,19 @@ const sidebar = { { type: 'category', label: 'Quickstart', - collapsible: false, + collapsible: false, collapsed: false, items: [ 'quickstart/javascript-wagmi', 'quickstart/javascript', + 'quickstart/javascript-dynamic', 'quickstart/react-native', ], }, { type: 'category', label: 'Guides', - collapsible: false, + collapsible: false, collapsed: false, items: [ 'guides/authenticate-users', @@ -44,7 +45,7 @@ const sidebar = { { type: 'category', label: 'Advanced', - collapsible: true, + collapsible: true, collapsed: true, items: [ 'guides/advanced/connect-and-sign', @@ -57,13 +58,11 @@ const sidebar = { { type: 'category', label: 'Reference', - collapsible: false, + collapsible: false, collapsed: false, - items: [ - 'reference/sdk-options' - ], - } + items: ['reference/sdk-options'], + }, ], -}; +} -module.exports = sidebar; +module.exports = sidebar From f08af672060e495db54a46b245957b0a248af7d2 Mon Sep 17 00:00:00 2001 From: Alejandro Date: Fri, 11 Apr 2025 13:44:09 +0200 Subject: [PATCH 3/5] 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. --- sdk/quickstart/javascript-dynamic.md | 64 ++++++++-------------------- 1 file changed, 18 insertions(+), 46 deletions(-) diff --git a/sdk/quickstart/javascript-dynamic.md b/sdk/quickstart/javascript-dynamic.md index d2fe7a82b54..873b8163d2c 100644 --- a/sdk/quickstart/javascript-dynamic.md +++ b/sdk/quickstart/javascript-dynamic.md @@ -5,9 +5,7 @@ toc_max_heading_level: 2 # MetaMask + Dynamic SDK Integration -Get started with MetaMask SDK and Dynamic SDK integration in a Next.js dapp. -This project demonstrates how to combine both SDKs to create a seamless wallet connection experience -for both desktop and mobile users. +Get started with MetaMask SDK and Dynamic SDK integration in a Next.js dapp. This project demonstrates how to combine both SDKs to create a seamless wallet connection experience for both desktop and mobile users. Features include: @@ -50,7 +48,7 @@ pnpm install Install the required dependencies: ```bash -pnpm i @metamask/sdk @dynamic-labs/sdk-react-core @dynamic-labs/ethereum @dynamic-labs/wagmi-connector wagmi viem @tanstack/react-query +pnpm i @dynamic-labs/sdk-react-core @dynamic-labs/ethereum @dynamic-labs/wagmi-connector wagmi viem @tanstack/react-query ``` ### 2. Configure providers @@ -58,35 +56,22 @@ pnpm i @metamask/sdk @dynamic-labs/sdk-react-core @dynamic-labs/ethereum @dynami Set up your providers in `app/providers.tsx`: ```typescript -import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core"; +"use client"; + +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { type ReactNode, useState } from "react"; +import { WagmiProvider } from "wagmi"; import { EthereumWalletConnectors } from "@dynamic-labs/ethereum"; import { DynamicWagmiConnector } from "@dynamic-labs/wagmi-connector"; -import { MetaMaskSDK } from "@metamask/sdk"; - -export function Providers({ children }) { - const [mounted, setMounted] = useState(false); - const [sdkInitialized, setSdkInitialized] = useState(false); - - useEffect(() => { - if (typeof window === 'undefined') return; - - const MMSDK = new MetaMaskSDK({ - dappMetadata: { - name: "MetaMask Dynamic Integration", - url: window.location.host, - }, - injectProvider: true, - communicationServerUrl: "https://metamask-sdk-socket.metamask.io", - }); +import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core"; +import { config } from "@/wagmi.config"; - const ethereum = MMSDK.getProvider(); - if (ethereum) { - window.ethereum = ethereum; - setSdkInitialized(true); - } +type Props = { + children: ReactNode; +}; - setMounted(true); - }, []); +export function Providers({ children }: Props) { + const [queryClient] = useState(() => new QueryClient()); return ( Date: Fri, 11 Apr 2025 14:15:41 +0200 Subject: [PATCH 4/5] 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. --- sdk/quickstart/javascript-dynamic.md | 34 ++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/sdk/quickstart/javascript-dynamic.md b/sdk/quickstart/javascript-dynamic.md index 873b8163d2c..f3df21b30b6 100644 --- a/sdk/quickstart/javascript-dynamic.md +++ b/sdk/quickstart/javascript-dynamic.md @@ -58,20 +58,34 @@ Set up your providers in `app/providers.tsx`: ```typescript "use client"; -import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; -import { type ReactNode, useState } from "react"; -import { WagmiProvider } from "wagmi"; -import { EthereumWalletConnectors } from "@dynamic-labs/ethereum"; -import { DynamicWagmiConnector } from "@dynamic-labs/wagmi-connector"; 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"; -type Props = { - children: ReactNode; -}; +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, + }, + }); -export function Providers({ children }: Props) { - const [queryClient] = useState(() => new QueryClient()); + const ethereum = MMSDK.getProvider(); + if (ethereum) { + window.ethereum = ethereum as unknown as IEthereum; + } + }, []); return ( Date: Fri, 11 Apr 2025 10:28:46 -0700 Subject: [PATCH 5/5] edits --- docs/whats-new.md | 2 + sdk/introduction/welcome.md | 1 + sdk/quickstart/javascript-dynamic.md | 141 +++++++++++++-------------- 3 files changed, 73 insertions(+), 71 deletions(-) diff --git a/docs/whats-new.md b/docs/whats-new.md index 4bff3255d1a..3cd5790192d 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -11,6 +11,8 @@ of the [MetaMask developer page](https://metamask.io/developer/). ## April 2025 +- Documented [MetaMask SDK + Dynamic SDK integration](/sdk/quickstart/javascript-dynamic). + ([#1972](https://github.com/MetaMask/metamask-docs/pull/1972)) - Documented [Snaps bundle analyzer option](/snaps/reference/cli/subcommands/#analyze). ([#1955](https://github.com/MetaMask/metamask-docs/pull/1955)) diff --git a/sdk/introduction/welcome.md b/sdk/introduction/welcome.md index 1416aaddc11..acffc3bff38 100644 --- a/sdk/introduction/welcome.md +++ b/sdk/introduction/welcome.md @@ -32,4 +32,5 @@ You can get started quickly with the following dapp platforms: - [JavaScript + Wagmi (recommended)](quickstart/javascript-wagmi.md) - [JavaScript](quickstart/javascript.md) +- [Dynamic SDK integration](quickstart/javascript-dynamic.md) - [React Native](quickstart/react-native.md) diff --git a/sdk/quickstart/javascript-dynamic.md b/sdk/quickstart/javascript-dynamic.md index f3df21b30b6..e1f9018ffa9 100644 --- a/sdk/quickstart/javascript-dynamic.md +++ b/sdk/quickstart/javascript-dynamic.md @@ -1,51 +1,73 @@ --- +sidebar_label: Dynamic SDK integration description: MetaMask + Dynamic SDK Integration toc_max_heading_level: 2 --- -# MetaMask + Dynamic SDK Integration +# MetaMask SDK + Dynamic SDK integration -Get started with MetaMask SDK and Dynamic SDK integration in a Next.js dapp. This project demonstrates how to combine both SDKs to create a seamless wallet connection experience for both desktop and mobile users. +Get started with MetaMask SDK and [Dynamic SDK](https://docs.dynamic.xyz/introduction/welcome). +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. +You can also [manually set up the SDK](#set-up-manually) 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 +- **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. -## Project Structure +## Project structure + +The project you will set up has the following structure: ``` ├── app/ -│ ├── providers.tsx # Main providers configuration -│ └── layout.tsx # Root layout with providers +│ ├── 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 +│ ├── 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 ``` -## Set up the project +## Set up using a template -You can either clone the repository or set up the project manually: +1. Download the [MetaMask SDK + Dynamic SDK template](https://github.com/MetaMask/metamask-dynamic): -### Option 1: Clone the repository + ```bash + git clone https://github.com/MetaMask/metamask-dynamic + ``` -```bash -git clone https://github.com/MetaMask/metamask-dynamic -cd metamask-dynamic -pnpm install -``` +2. Navigate into the repository: + + ```bash + cd metamask-dynamic + ``` + +3. Install dependencies: + + ```bash + pnpm install + ``` -### Option 2: Manual setup +4. Run the project: + + ```bash + pnpm dev + ``` + +You've successfully set up MetaMask SDK and Dynamic SDK. +See how to [use the combined SDKs](#usage). + +## Set up manually ### 1. Install dependencies -Install the required dependencies: +Install the SDK and the required dependencies to an existing project: ```bash pnpm i @dynamic-labs/sdk-react-core @dynamic-labs/ethereum @dynamic-labs/wagmi-connector wagmi viem @tanstack/react-query @@ -55,7 +77,7 @@ pnpm i @dynamic-labs/sdk-react-core @dynamic-labs/ethereum @dynamic-labs/wagmi-c Set up your providers in `app/providers.tsx`: -```typescript +```typescript title="providers.tsx" "use client"; import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core"; @@ -110,13 +132,13 @@ export function Providers({ children }: { children: React.ReactNode }) { Create a `.env.local` file: -``` +```text title=".env.local" NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID=your_dynamic_environment_id ``` ## Usage -### Connect Wallet +### Connect wallet Use the Dynamic Widget in your components: @@ -134,7 +156,7 @@ export const Navbar = () => { }; ``` -### Check Wallet Status +### Check wallet status Use the `useAccount` hook from Wagmi: @@ -158,50 +180,27 @@ export const Hero = () => { }; ``` -## Production Deployment - -For production deployments: - -1. Update your `next.config.ts` with production domains -2. Set up proper environment variables -3. Configure your Dynamic SDK environment ID -4. Ensure MetaMask SDK is properly initialized - -## Troubleshooting - -Common issues and solutions: - -1. **SDK Initialization Error** - - - Ensure MetaMask is installed - - Check environment variables - - Verify network connectivity - -2. **TypeScript Errors** - - - Update type definitions - - Check SDK versions compatibility - -3. **Mobile Experience Issues** - - Test on actual mobile devices - - Verify redirect URLs - - Check MetaMask Mobile installation - -## Additional Resources +## Production readiness -- [MetaMask SDK Documentation](https://docs.metamask.io/guide/sdk.html) -- [Dynamic SDK Documentation](https://docs.dynamic.xyz/) -- [Wagmi Documentation](https://wagmi.sh/) -- [Next.js Documentation](https://nextjs.org/docs) +Before deploying your project to production: -## Contributing +1. Update your `next.config.ts` with production domains. +2. Set up proper environment variables. +3. Configure your Dynamic SDK environment ID. +4. Ensure MetaMask SDK is properly initialized. -1. Fork the repository -2. Create your feature branch -3. Commit your changes -4. Push to the branch -5. Create a Pull Request +## Troubleshoot -## License +Common issues and solutions include: -This project is licensed under the MIT License. +- **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.