diff --git a/wallet/how-to/connect/set-up-sdk/javascript/electron.md b/wallet/how-to/connect/set-up-sdk/javascript/electron.md index a36deefa948..6286aa7caef 100644 --- a/wallet/how-to/connect/set-up-sdk/javascript/electron.md +++ b/wallet/how-to/connect/set-up-sdk/javascript/electron.md @@ -8,5 +8,5 @@ sidebar_position: 6 You can import [MetaMask SDK](../../../../concepts/sdk.md) into your Electron dapp to enable your users to easily connect to the MetaMask browser extension and MetaMask Mobile. -On the frontend, see the instructions to [use the SDK with React](react.md). +On the frontend, see the instructions to [use the SDK with React](react/index.md). On the backend, see the instructions to [use the SDK with Node.js](nodejs.md). \ No newline at end of file diff --git a/wallet/how-to/connect/set-up-sdk/javascript/index.md b/wallet/how-to/connect/set-up-sdk/javascript/index.md index 9f063a23009..8e150dfdfda 100644 --- a/wallet/how-to/connect/set-up-sdk/javascript/index.md +++ b/wallet/how-to/connect/set-up-sdk/javascript/index.md @@ -10,7 +10,8 @@ users to easily connect to the MetaMask browser extension and MetaMask Mobile. The following instructions work for web dapps based on standard JavaScript. You can also see instructions for the following JavaScript-based platforms: -- [React](react.md) +- [React](react/index.md) + - [React UI](react/react-ui.md) - [Pure JavaScript](pure-js.md) - [Other web frameworks](other-web-frameworks.md) - [React Native](react-native.md) diff --git a/wallet/how-to/connect/set-up-sdk/javascript/react.md b/wallet/how-to/connect/set-up-sdk/javascript/react.md deleted file mode 100644 index 23927ee0c6a..00000000000 --- a/wallet/how-to/connect/set-up-sdk/javascript/react.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_label: React -sidebar_position: 1 ---- - -# Use MetaMask SDK with React - -You can import [MetaMask SDK](../../../../concepts/sdk.md) into your React dapp to enable your users to -easily connect to the MetaMask browser extension and MetaMask Mobile. -The SDK for React has the [same prerequisites](index.md#prerequisites) as for standard JavaScript. - -## Steps - -### 1. Install the SDK - -In your project directory, install the SDK using Yarn or npm: - -```bash -yarn add @metamask/sdk -``` - -or - -```bash -npm i @metamask/sdk -``` - -### 2. Import the SDK - -In your project script, add the following to import the SDK: - -```javascript -import { MetaMaskSDK } from '@metamask/sdk'; -``` - -### 3. Instantiate the SDK - -Instantiate the SDK using any [options](../../../../reference/sdk-js-options.md): - -```javascript -const MMSDK = new MetaMaskSDK(options); - -const ethereum = MMSDK.getProvider(); // You can also access via window.ethereum -``` - -### 4. Use the SDK - -Use the SDK by calling any [provider API methods](../../../../reference/provider-api.md). -Always call [`eth_requestAccounts`](../../../../reference/rpc-api.md#eth_requestaccounts) using -[`ethereum.request()`](../../../../reference/provider-api.md#ethereumrequestargs) first, since it -prompts the installation or connection popup to appear. - -```javascript -ethereum.request({ method: 'eth_requestAccounts', params: [] }); -``` diff --git a/wallet/how-to/connect/set-up-sdk/javascript/react/index.md b/wallet/how-to/connect/set-up-sdk/javascript/react/index.md new file mode 100644 index 00000000000..884294abaf1 --- /dev/null +++ b/wallet/how-to/connect/set-up-sdk/javascript/react/index.md @@ -0,0 +1,153 @@ +--- +sidebar_label: React +sidebar_position: 1 +--- + +# Use MetaMask SDK with React + +You can import [MetaMask SDK](../../../../../concepts/sdk.md) into your React dapp to enable your users to +easily connect to the MetaMask browser extension and MetaMask Mobile. +The SDK for React has the [same prerequisites](../index.md#prerequisites) as for standard JavaScript. + +:::info React UI +This page provides instructions for using the standard `@metamask/sdk-react` package. +Alternatively, you can use the [`@metamask/sdk-react-ui`](react-ui.md) package to easily use +[wagmi](https://wagmi.sh/) hooks and a pre-styled UI button component for connecting to MetaMask. +::: + +:::tip Examples +Refer to the [MetaMask JavaScript SDK examples](https://github.com/MetaMask/metamask-sdk/tree/main/packages/examples) +for advanced use cases. +::: + +## Steps + +### 1. Install the SDK + +In your project directory, install the SDK using Yarn or npm: + +```bash +yarn add @metamask/sdk-react +``` + +or + +```bash +npm i @metamask/sdk-react +``` + +### 2. Import the SDK + +In your project script, add the following to import the SDK: + +```javascript +import { MetaMaskProvider } from '@metamask/sdk-react'; +``` + +### 3. Wrap your project with MetaMaskProvider + +Wrap your root component in a `MetaMaskProvider`. +For example: + +```js +import React from 'react'; +import ReactDOM from 'react-dom/client'; +import App from './App'; +import { MetaMaskProvider } from '@metamask/sdk-react'; + +const root = ReactDOM.createRoot( + document.getElementById('root') as HTMLElement +); + +root.render( + + + + + +); +``` + +When initializing `MetaMaskProvider`, setting `debug` to `true` activates debug mode. +For the full list of options you can set for `sdkOptions`, see the +[JavaScript SDK options reference](../../../../../reference/sdk-js-options.md). + +### 4. Use the SDK + +Use the SDK by using the `useSDK` hook in your React components. +For example: + +```js +import { useSDK } from '@metamask/sdk-react'; +import React, { useState } from 'react'; + +export const App = () => { + const [account, setAccount] = useState(); + const { sdk, connected, connecting, provider, chainId } = useSDK(); + + const connect = async () => { + try { + const accounts = await sdk?.connect(); + setAccount(accounts?.[0]); + } catch(err) { + console.warn(`failed to connect..`, err); + } + }; + + return ( +
+ + {connected && ( +
+ <> + {chainId && `Connected chain: ${chainId}`} +

+ {account && `Connected account: ${account}`} + +
+ )} +
+ ); +}; +``` + +
+useSDK return values +

+ +- `sdk`: Main SDK object that facilitates connection and actions related to MetaMask. +- `connected`: Boolean value indicating if the dapp is connected to MetaMask. +- `connecting`: Boolean value indicating if a connection is in process. +- `provider`: The provider object which can be used for lower-level interactions with the Ethereum blockchain. +- `chainId`: Currently connected blockchain's chain ID. + +

+
+ +The `sdk.connect()` method initiates a connection to MetaMask and returns an array of connected accounts: + +```javascript +const connect = async () => { + try { + const accounts = await sdk?.connect(); + setAccount(accounts?.[0]); + } catch(err) { + console.warn(`failed to connect..`, err); + } +}; +``` + +Refer to the [MetaMask JavaScript SDK examples](https://github.com/MetaMask/metamask-sdk/tree/main/packages/examples) +for advanced use cases. diff --git a/wallet/how-to/connect/set-up-sdk/javascript/react/react-ui.md b/wallet/how-to/connect/set-up-sdk/javascript/react/react-ui.md new file mode 100644 index 00000000000..174b588f460 --- /dev/null +++ b/wallet/how-to/connect/set-up-sdk/javascript/react/react-ui.md @@ -0,0 +1,115 @@ +--- +sidebar_label: React UI +sidebar_position: 1 +--- + +# Use MetaMask SDK with React UI + +You can import [MetaMask SDK](../../../../../concepts/sdk.md) into your React dapp to enable your +users to easily connect to the MetaMask browser extension and MetaMask Mobile. +The `@metamask/sdk-react-ui` package not only exports hooks from [`@metamask/sdk-react`](index.md), +but also provides wrappers around [wagmi](https://wagmi.sh/) hooks and a basic UI button component +for connecting to MetaMask. + +By combining the functions of `@metamask/sdk-react` and `@metamask/sdk-react-ui`, you can use both +the core functionality and the pre-styled UI components to streamline the integration of MetaMask +into your React dapp. + +The SDK for React has the [same prerequisites](../index.md#prerequisites) as for standard JavaScript. + +:::tip Examples +Refer to the [MetaMask JavaScript SDK examples](https://github.com/MetaMask/metamask-sdk/tree/main/packages/examples) +for advanced use cases. +::: + +## Steps + +### 1. Install the SDK + +In your project directory, install the SDK using Yarn or npm: + +```bash +yarn add @metamask/sdk-react-ui +``` + +or + +```bash +npm i @metamask/sdk-react-ui +``` + +### 2. Import the SDK + +In your project script, add the following to import the SDK: + +```javascript +import { MetaMaskUIProvider } from '@metamask/sdk-react-ui'; +``` + +### 3. Wrap your project with MetaMaskUIProvider + +Wrap your root component in a `MetaMaskUIProvider`. +For example: + +```js +import React from 'react'; +import ReactDOM from 'react-dom/client'; +import App from './App'; +import { MetaMaskUIProvider } from '@metamask/sdk-react-ui'; + +const root = ReactDOM.createRoot( + document.getElementById('root') as HTMLElement +); + +root.render( + + + + + +); +``` + +For the full list of options you can set for `sdkOptions`, see the +[JavaScript SDK options reference](../../../../../reference/sdk-js-options.md). + +### 4. Use the SDK + +Use the SDK by using the `useSDK` hook in your React components. +See the [instructions for `@metamask/sdk-react`](index.md#4-use-the-sdk). + +### 5. Use the MetaMaskButton component + +The `@metamask/sdk-react-ui` package provides a pre-styled button, `MetaMaskButton`, to initiate a +connection to MetaMask. +You can use it as follows: + +```js +import { MetaMaskButton } from "@metamask/sdk-react-ui"; +import React, { useState } from "react"; + +export const App = () => { + return ( +
+ +
+ ); +}; +``` + +
+MetaMaskButton properties +

+ +- `theme`: Set to `light` or `dark` to adapt to your dapp's theme. +- `color`: The color of the button. Accepts any valid CSS color string. + +

+
+ +Refer to the [MetaMask JavaScript SDK examples](https://github.com/MetaMask/metamask-sdk/tree/main/packages/examples) +for advanced use cases. diff --git a/wallet/reference/sdk-js-options.md b/wallet/reference/sdk-js-options.md index 1f5d23b7dab..8efd477af0a 100644 --- a/wallet/reference/sdk-js-options.md +++ b/wallet/reference/sdk-js-options.md @@ -5,19 +5,8 @@ sidebar_position: 1 # JavaScript SDK options -The JavaScript version of [MetaMask SDK](../concepts/sdk.md) takes several options. -For example, you can specify options as follows: - -```javascript -const options = { - injectProvider: false, - communicationLayerPreference: 'webrtc', -}; - -const MMSDK = new MetaMaskSDK(options); -``` - -The following table shows the full list of options: +The [JavaScript version of MetaMask SDK](../how-to/connect/set-up-sdk/javascript/index.md) takes the +following options: | Option name | Type | Default value | Description | |--------------------------------|:----------------------------------------------:|:-------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -32,12 +21,14 @@ The following table shows the full list of options: | `openDeeplink` | `(deeplinkUrl: string) => void` | `undefined` | Platforms open deeplinks differently. For example, web: `window.open` versus React Native: `Linking.open`. This function retrieves the deeplink URL and allows developers to customize how it opens. | | `getUniversalLink` | `() => string` | `undefined` | Get the universal link that is presented on the QR Code (web) and deeplinks (mobile). This makes it easier to enable users to connect with backend code. | | `communicationLayerPreference` | `"socket" or "webrtc"` | `socket` | Defines the communication library that the dapp and MetaMask wallet use to communicate with each other. Waku or another similar decentralized communication layer solution coming soon. | +| `communicationServerUrl` | `string` | `undefined` | URL for the communication server, generally managed in your environment variables. | | `webRTCLib` | `WebRTC Lib` | `undefined` | Not installed on the SDK by default. | | `WalletConnectInstance` | `WalletConnect Lib` | `undefined` | Connect a dapp to MetaMask using [WalletConnect](https://docs.walletconnect.com/). Not installed by default. | | `forceRestartWalletConnect` | `boolean` | `false` | Set `forceRestartWalletConnect` to `true` to kill the previous WalletConnect session and start another one. | | `transports` | `['websocket', 'polling']` | `undefined` | Used to set the preference on [socket.io](https://socket.io/docs/v4/) transports to `use`. | | `timer` | `BackgroundTimer` | `undefined` | Used by React Native dapps to keep the dapp alive while using `react-native-background-timer` in the background | | `enableDebug` | `boolean` | `true` | Enables/disables the sending of debugging information to the socket.io server. The default is `true` for the beta version of the SDK. The default is `false` in production versions. | +| `logging` | `{developerMode: boolean}` | `undefined` | Log-related configurations. `developerMode` enables/disables developer logs. | :::tip If your project is a web dapp and `injectProvider` is `true`, then the `ethereum` object should be