> ## Documentation Index > Fetch the complete documentation index at: https://docs.dynamic.xyz/docs/llms.txt > Use this file to discover all available pages before exploring further. # React Quickstart > [card] Recommended: JavaScript SDK with React Hooks > > For new React apps, we recommend the JavaScript SDK with React Hooks (`@dynamic-labs-sdk/react-hooks`) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the [React quickstart (JavaScript SDK)](https://docs.dynamic.xyz/docs/javascript/reference/react-quickstart.md) to get started. Get started with Dynamic's React SDK to add embedded wallets, multi-chain support, and flexible authentication (email, social login, passkeys) to your app in just a few lines. > [!NOTE] > > Before you start: You’ll need Node.js 18+ and a Dynamic environment ID from the [Dynamic Console](https://console.dynamic.xyz/dashboard/developer). > [tab] Agent-friendly > > > [!TIP] > > > > Add the Dynamic docs MCP to your AI editor first — your agent can then query the docs directly. > > > [tab] Cursor > > > > [Click here to add the MCP to Cursor.](https://cursor.com/en/install-mcp?name=dynamic\&config=eyJ1cmwiOiJodHRwczovL3d3dy5keW5hbWljLnh5ei9kb2NzL21jcCJ9) > > > [tab] Claude Code > > > > ```bash theme={"system"} > > claude mcp add --transport http dynamic https://www.dynamic.xyz/docs/mcp > > ``` > > > [tab] Codex > > > > ```bash theme={"system"} > > codex mcp add dynamic --url https://www.dynamic.xyz/docs/mcp > > ``` > > > [tab] Other > > > > If your editor or agent supports remote HTTP MCP, add a server that points at `https://www.dynamic.xyz/docs/mcp`. The exact steps depend on the product; use its MCP documentation for URL-based or HTTP transport setup. > > > [!WARNING] > > > > **New React app?** Use the agent prompt on the [React quickstart (JavaScript SDK)](https://docs.dynamic.xyz/docs/javascript/reference/react-quickstart.md) instead. Dynamic recommends the JavaScript SDK with React Hooks (`@dynamic-labs-sdk/react-hooks`) over the React SDK on this page. > > Copy this prompt into your LLM only if the project already uses or explicitly requires the React SDK (`@dynamic-labs/sdk-react-core`). > > ````markdown theme={"system"} > # React SDK Quickstart > > ## Default for React apps — use the JavaScript SDK instead > > **Stop and read this first.** If the user wants to add Dynamic to a **React** app, the default is **not** this document. > > **Preferred path for React:** Use the **JavaScript SDK with React Hooks** (`@dynamic-labs-sdk/react-hooks`). Follow the agent prompt in the [React quickstart (JavaScript SDK)](https://www.dynamic.xyz/docs/javascript/reference/react-quickstart) (agent prompt id: `javascript-react`). > > **Use this React SDK quickstart only when:** > - The codebase already uses `@dynamic-labs/sdk-react-core` > - The user explicitly requests the React SDK, `DynamicContextProvider`, `DynamicWidget`, or React SDK + Wagmi integration > > If neither applies, tell the user you are using the JavaScript SDK path and switch to the JavaScript SDK React quickstart before writing any code. > > --- > > ## Purpose and Usage > > This document provides structured quickstart information for the Dynamic React SDK (`@dynamic-labs/sdk-react-core`). It is designed to be consumed by LLMs to generate accurate installation commands and code examples based on user requirements. > > **Do not use this document for new React integrations** unless the user meets the criteria in **Default for React apps** above. > > **How to use this document:** > > Start by asking the user which path they want: > > > "Would you like a **Quick start** (EVM + DynamicWidget UI, zero configuration — recommended if you're just getting started) or a **Custom setup** (choose your chains, Wagmi integration, and EVM client library)?" > > - If the user chooses **Quick start**: follow the Quick Start Path section exactly. Do not ask any configuration questions — execute the happy path as written. > - If the user chooses **Custom setup**: follow the Custom Setup Path section and ask all configuration questions before proceeding. > > --- > > ## Quick Start Path > > > Use this path when the user chooses Quick start. Execute every step in order. Do not skip steps. Do not ask configuration questions. > > **Stack:** Vite 5 + npm + EVM only + DynamicWidget (no Wagmi) > > ### Step 1 — Prerequisites > > Tell the user: > - Node.js 18+ is required > - A Dynamic environment ID is required — get one at https://console.dynamic.xyz/dashboard/developer/api > > Ask the user for their environment ID before proceeding. > > ### Step 2 — Scaffold the project > > Use Vite 5 explicitly. Do not use `npm create vite@latest` — it installs Vite 8 which is incompatible with the Dynamic SDK due to a missing native binary. > > ```bash > npm create vite@5 my-app -- --template react-ts > cd my-app > ``` > > ### Step 3 — Install the SDK > > ```bash > npm i @dynamic-labs/sdk-react-core @dynamic-labs/ethereum viem > ``` > > ### Step 4 — Fix Vite polyfills > > The Dynamic SDK requires Node globals (`process`, `Buffer`) that Vite does not provide by default. Add the following `define` block to `vite.config.ts`. Do not use `@esbuild-plugins/node-globals-polyfill` — it is incompatible with Vite 5. > > ```typescript > // vite.config.ts > import { defineConfig } from 'vite'; > import react from '@vitejs/plugin-react'; > > export default defineConfig({ > plugins: [react()], > define: { > 'process.env': {}, > global: 'globalThis', > }, > }); > ``` > > ### Step 5 — Set up the provider > > Wrap your app in `DynamicContextProvider` at the root with `EthereumWalletConnectors`: > > ```typescript > // src/main.tsx > import { StrictMode } from 'react'; > import { createRoot } from 'react-dom/client'; > import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core'; > import { EthereumWalletConnectors } from '@dynamic-labs/ethereum'; > import App from './App'; > > createRoot(document.getElementById('root')!).render( > > settings={{ > environmentId: 'YOUR_ENVIRONMENT_ID', > walletConnectors: [EthereumWalletConnectors], > }} > > > > > > ); > ``` > > ### Step 6 — Add the widget > > Drop `DynamicWidget` into your app component. This provides the complete auth and wallet connection UI out of the box: > > ```typescript > // src/App.tsx > import { DynamicWidget } from '@dynamic-labs/sdk-react-core'; > > export default function App() { > return ( >
> >
> ); > } > ``` > > ### Step 7 — Post-login patterns > > After the user authenticates, use these hooks to access wallet and user state: > > ```typescript > import { useDynamicContext } from '@dynamic-labs/sdk-react-core'; > > export default function WalletInfo() { > const { primaryWallet, user, handleLogOut } = useDynamicContext(); > > if (!primaryWallet) return

Not connected

; > > return ( >
>

Address: {primaryWallet.address}

>

Chain: {primaryWallet.chain}

>

Email: {user?.email}

> >
> ); > } > ``` > > > Note: `primaryWallet.chain` returns the chain family as a string (`'EVM'`, `'SOL'`, `'BTC'`), not a numeric chain ID. Use `await primaryWallet.getNetwork()` to get the numeric network ID. > > --- > > ## Custom Setup Path > > > Use this path when the user chooses Custom setup. Ask ALL questions below before generating any code. > > **Questions to ask the user:** > > 1. Which package manager do you prefer? (npm, yarn, pnpm, bun) > 2. Which chains do you want to support? (EVM, SVM, Bitcoin, Algorand, Flow Cadence, Starknet, Cosmos, Sui, Midnight, Spark, Tron, TON, Aptos, Aleo, Stellar: one or more) > 3. If EVM: do you want Wagmi integration for React hooks? > 4. If EVM: which EVM client library do you prefer? (viem or ethers) > > **Only after receiving answers**, use the sections below to generate the correct setup. > > ### Scaffolding note > Always scaffold with a pinned Vite version. Do not use `vite@latest` — use `vite@5`: > ```bash > npm create vite@5 my-app -- --template react-ts > ``` > > ### Vite polyfill (required for all Vite setups) > Add to `vite.config.ts` — do not use `@esbuild-plugins/node-globals-polyfill`, it is incompatible with Vite 5: > ```typescript > define: { > 'process.env': {}, > global: 'globalThis', > }, > ``` > > ### Package Manager Commands > - `npm`: `npm i` > - `yarn`: `yarn add` > - `pnpm`: `pnpm add` > - `bun`: `bun add` > > ### Package Mapping > - Core (always required): `@dynamic-labs/sdk-react-core` > - EVM: `@dynamic-labs/ethereum viem` (`viem` is a peer dependency of `@dynamic-labs/ethereum`) > - SVM: `@dynamic-labs/solana` > - Bitcoin: `@dynamic-labs/bitcoin` > - Algorand: `@dynamic-labs/algorand` > - Flow Cadence: `@dynamic-labs/flow` > - Starknet: `@dynamic-labs/starknet` > - Cosmos: `@dynamic-labs/cosmos` > - Sui: `@dynamic-labs/sui` > - Midnight: `@dynamic-labs/midnight` > - Spark: `@dynamic-labs/spark` > - Tron: `@dynamic-labs/tron` > - TON: `@dynamic-labs/ton` > - Aptos: `@dynamic-labs/aptos` > - Aleo: `@dynamic-labs/aleo` > - Stellar: `@dynamic-labs/stellar` > - Wagmi (EVM only, optional): `@dynamic-labs/wagmi-connector wagmi @tanstack/react-query` > - Ethers (only when the EVM client is `ethers`): `@dynamic-labs/ethers-v6 ethers` > > > **Wagmi version:** The latest compatible version is Wagmi v3 (v3.1.0+). You may see some dependency warnings related to `DynamicWagmiConnector` because the package still uses some Wagmi v2 packages internally — these are safe to ignore and will be updated in a future release. > > ### Chain Connector Mapping > - `EVM` → `EthereumWalletConnectors` from `@dynamic-labs/ethereum` > - `SVM` → `SolanaWalletConnectors` from `@dynamic-labs/solana` > - `Bitcoin` → `BitcoinWalletConnectors` from `@dynamic-labs/bitcoin` > - `Algorand` → `AlgorandWalletConnectors` from `@dynamic-labs/algorand` > - `Flow Cadence` → `FlowWalletConnectors` from `@dynamic-labs/flow` > - `Starknet` → `StarknetWalletConnectors` from `@dynamic-labs/starknet` > - `Cosmos` → `CosmosWalletConnectors` from `@dynamic-labs/cosmos` > - `Sui` → `SuiWalletConnectors` from `@dynamic-labs/sui` > - `Midnight` → `MidnightWalletConnectors` from `@dynamic-labs/midnight` > - `Spark` → `SparkWalletConnectors` from `@dynamic-labs/spark` > - `Tron` → `TronWalletConnectors` from `@dynamic-labs/tron` > - `TON` → `TonWalletConnectors` from `@dynamic-labs/ton` > - `Aptos` → `AptosWalletConnectors` from `@dynamic-labs/aptos` > - `Aleo` → `AleoWalletConnectors` from `@dynamic-labs/aleo` > - `Stellar` → `StellarWalletConnectors` from `@dynamic-labs/stellar` > > ### Component Structure > > **Without Wagmi**: > ```typescript > export default function App() { > return ( > settings={{ > environmentId: 'YOUR_ENVIRONMENT_ID', > walletConnectors: [EthereumWalletConnectors], > }} > > > > > ); > } > ``` > > **With Wagmi**: > ```typescript > const config = createConfig({ > chains: [mainnet], > multiInjectedProviderDiscovery: false, > transports: { [mainnet.id]: http() }, > }); > > const queryClient = new QueryClient(); > > export default function App() { > return ( > settings={{ > environmentId: 'YOUR_ENVIRONMENT_ID', > walletConnectors: [EthereumWalletConnectors], > }} > > > > > > > > > > > ); > } > ``` > > ### Post-login patterns (apply to all setups) > > ```typescript > import { useDynamicContext } from '@dynamic-labs/sdk-react-core'; > > const { primaryWallet, user, handleLogOut } = useDynamicContext(); > > // Wallet address > primaryWallet?.address > > // Chain family as a string ('EVM', 'SOL', 'BTC') > primaryWallet?.chain > > // Numeric network ID > await primaryWallet?.getNetwork() > > // Authenticated user > user?.email > > // Logout > handleLogOut() > ``` > > ### Valid Combinations > - Any combination of chains is valid > - Wagmi only applies when EVM is selected > - Ethers connector only applies when EVM client is set to `ethers` > > ### Documentation > All docs for this SDK: https://docs.dynamic.xyz (paths starting with `/react/`) > Environment ID: https://console.dynamic.xyz/dashboard/developer/api > > --- > > ## Building a headless integration? > > If you're building without the Dynamic Widget, see the [Authentication screens](/react/authentication-methods/headless-authentication) for a full list of screens your app needs to handle. > > --- > > ## Step-Up Authentication > > **Required before accepting the `2026_04_01` API version** — verify your > minimum API version in [Console > Developers > API & SDK Keys](https://console.dynamic.xyz/dashboard/developer/api). > > If using `DynamicWidget` or Dynamic's built-in UI, step-up prompts are > handled automatically. **If building a headless/custom UI, you must handle > step-up authentication manually** using the `useStepUpAuthentication` hook > — check requirements, trigger verification, and wait for the elevated token > before proceeding with the sensitive operation. > > See [Step-up authentication](/react/authentication-methods/step-up-auth/overview) for the full implementation guide. > > --- > > ## Device Registration > > **Required before accepting the `2026_04_01` API version** — verify your > minimum API version in [Console > Developers > API & SDK Keys](https://console.dynamic.xyz/dashboard/developer/api). > > If using Dynamic's built-in UI (default), device registration is handled > automatically — no code required. **If building a headless/custom UI** > (`deviceRegistrationModal: { enabled: false }`), **you must manually check > whether the current device needs registration and handle the completion > event yourself.** > > Full guide: https://docs.dynamic.xyz/react/authentication-methods/device-registration > > --- > > ## Troubleshooting — Console Configuration > > If the app builds successfully but login fails, the widget doesn't open, wallets don't appear, or you see network/auth errors, the most common causes are Dynamic Console settings that haven't been configured. Ask the user to verify each of the following in their Dynamic Console at https://console.dynamic.xyz: > > ### 1 — Chains not enabled > The EVM chain (or any other chain used in the quickstart) must be enabled under **Chains & Networks** in the console. If the chain isn't toggled on, wallet connection and signing will silently fail or return empty results. > > ### 2 — Login method not enabled > The login method the app uses (e.g. email OTP, social login, external wallets) must be toggled on under **Sign-in Methods**. If it isn't enabled, the auth flow will not appear or will fail silently inside the widget. > > ### 3 — Embedded wallets not enabled > If the app uses embedded (WaaS) wallets, the **Embedded Wallets** feature must be enabled under **Wallets** in the console. Without it, no embedded wallet will be created after login. > > ### 4 — CORS origin not allowlisted > The URL the app is running on (e.g. `http://localhost:5173`) must be added to the **Allowed Origins** list in the console under **Security**. Without it, all SDK requests will be blocked by CORS. Add the exact origin including port. > > If all four are configured and the app is still not working, check the browser console for error codes and refer to https://docs.dynamic.xyz/overview/troubleshooting/general. > ```` > [tab] Manual > > ## Install and initialize the SDK > > [https://documentation-quickstarts.vercel.app/react?color-scheme=dark](https://documentation-quickstarts.vercel.app/react?color-scheme=dark) > > [https://documentation-quickstarts.vercel.app/react?color-scheme=light](https://documentation-quickstarts.vercel.app/react?color-scheme=light) > > > [!TIP] > > > > EthereumWalletConnectors also includes all EVM compatible chains including > > layer 2's i.e. Base as well as [Dynamic Embedded > > Wallets](https://docs.dynamic.xyz/docs/react/wallets/embedded-wallets/mpc/setup.md). Learn more about WalletConnectors [here](https://docs.dynamic.xyz/docs/react/reference/providers/dynamiccontextprovider.md#walletconnectors). > > ## Configure your UI and signup > > The quickstart embed above includes the DynamicWidget, which provides out of the box UI. If you prefer to use your own UI, remove `DynamicWidget` from the code, and refer to the "Using Your UI" section of any guide to see how to add it in a custom UI. Below we've listed some of the common signup options for you to configure in your own Dynamic environment. > > > [card] > > > > Add email signup > > > > [Open](https://docs.dynamic.xyz/docs/react/authentication-methods/email.md) > > > [card] > > > > Add sms signup > > > > [Open](https://docs.dynamic.xyz/docs/react/authentication-methods/sms.md) > > > [card] > > > > Add social signup > > > > [Open](https://docs.dynamic.xyz/docs/react/authentication-methods/social.md) > > > [card] > > > > Add passkey signup > > > > [Open](https://docs.dynamic.xyz/docs/react/authentication-methods/passkey.md) > > > [card] > > > > Add external wallet signup > > > > [Open](https://docs.dynamic.xyz/docs/react/authentication-methods/external-wallets.md) > > > [!NOTE] > > > > If you are using Wagmi, make sure to read our [full Wagmi > > guide](https://docs.dynamic.xyz/docs/react/reference/using-wagmi.md) for more setup instructions. > > > [!TIP] > > > > If you're using Vite, you'll need to check out [the polyfills guide](https://docs.dynamic.xyz/docs/get-started/troubleshooting/react/vitejs-polyfills-necessary-for-dynamic-sdk.md). > > > > If you see any other errors, check [Dynamic Doctor](https://docs.dynamic.xyz/docs/get-started/troubleshooting/dynamic-doctor.md) for quick debugging tips! > > > [!TIP] > > > > To quickly test the login flow, you can enable [Test > > Accounts](https://docs.dynamic.xyz/docs/platform/console/test-accounts.md) in Sandbox mode. > > ## Next Steps > > > [!WARNING] > > > > **Step-up authentication** and **device registration** are required > > before accepting the `2026_04_01` API version. If you have a headless > > integration, you must implement both manually. > > See the [upgrade guide](https://docs.dynamic.xyz/docs/get-started/migrations/api/2026_04_01.md). > > * [Step-up authentication](https://docs.dynamic.xyz/docs/react/authentication-methods/step-up-auth/overview.md) > > * [Device registration](https://docs.dynamic.xyz/docs/react/authentication-methods/device-registration.md) > > > [!NOTE] > > > > Building without the Dynamic Widget? See the [Authentication screens](https://docs.dynamic.xyz/docs/react/authentication-methods/headless-authentication.md) for a full list of screens your app needs to handle. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.