|
| 1 | +# @turnkey/react-wallet-kit |
| 2 | + |
| 3 | +The `@turnkey/react-wallet-kit` is a powerful SDK that allows you to integrate Turnkey's Embedded Wallets into your React applications. It provides a set of UI components and easy-to-use functions, all exported from a hook, enabling you to quickly build secure embedded wallet experiences. |
| 4 | + |
| 5 | + |
| 6 | +## Installation |
| 7 | + |
| 8 | +You can use `@turnkey/react-wallet-kit` in any React based web application. |
| 9 | + |
| 10 | +For this guide, let's create a new `Next.js` app. If you already have an existing app, you don't need to do this. |
| 11 | + |
| 12 | +```bash npx |
| 13 | +npx create-next-app@latest |
| 14 | +``` |
| 15 | + |
| 16 | +Now, install the Turnkey React Wallet Kit package: |
| 17 | + |
| 18 | +<CodeGroup> |
| 19 | + |
| 20 | +```bash npm |
| 21 | +npm install @turnkey/react-wallet-kit |
| 22 | +``` |
| 23 | + |
| 24 | +```bash pnpm |
| 25 | +pnpm add @turnkey/react-wallet-kit |
| 26 | +``` |
| 27 | + |
| 28 | +```bash yarn |
| 29 | +yarn add @turnkey/react-wallet-kit |
| 30 | +``` |
| 31 | + |
| 32 | +</CodeGroup> |
| 33 | + |
| 34 | +## Provider |
| 35 | + |
| 36 | +Wrap your app with the `TurnkeyProvider` component, and import `"@turnkey/react-wallet-kit/dist/styles.css"` to include styles for the UI components. |
| 37 | + |
| 38 | +With Next.js App Router, keep `app/layout.tsx` as a server component and create a separate `app/providers.tsx` client wrapper. This is necessary if you want to pass callbacks (e.g., onError), which must be defined in a client component. |
| 39 | + |
| 40 | +```tsx app/providers.tsx |
| 41 | +"use client"; |
| 42 | + |
| 43 | +import { |
| 44 | + TurnkeyProvider, |
| 45 | + TurnkeyProviderConfig, |
| 46 | +} from "@turnkey/react-wallet-kit"; |
| 47 | + |
| 48 | +const turnkeyConfig: TurnkeyProviderConfig = { |
| 49 | + organizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID!, |
| 50 | + authProxyConfigId: process.env.NEXT_PUBLIC_AUTH_PROXY_CONFIG_ID!, |
| 51 | +}; |
| 52 | + |
| 53 | +export function Providers({ children }: { children: React.ReactNode }) { |
| 54 | + return <TurnkeyProvider config={turnkeyConfig}>{children}</TurnkeyProvider>; |
| 55 | +} |
| 56 | +``` |
| 57 | + |
| 58 | +In case anything goes wrong, let's add an `onError` callback to the `TurnkeyProvider` to catch any errors that may occur. |
| 59 | + |
| 60 | +```tsx app/providers.tsx |
| 61 | +<TurnkeyProvider |
| 62 | + config={turnkeyConfig} |
| 63 | + callbacks={{ |
| 64 | + onError: (error) => console.error("Turnkey error:", error), |
| 65 | + }} |
| 66 | +> |
| 67 | +``` |
| 68 | + |
| 69 | +Then, use the `Providers` component to wrap your app in `app/layout.tsx`. |
| 70 | + |
| 71 | +```tsx app/layout.tsx |
| 72 | +import "./globals.css"; |
| 73 | +import Providers from "./providers"; |
| 74 | + |
| 75 | +export default function RootLayout({ |
| 76 | + children, |
| 77 | +}: { |
| 78 | + children: React.ReactNode; |
| 79 | +}) { |
| 80 | + return ( |
| 81 | + <html lang="en"> |
| 82 | + <body> |
| 83 | + <Providers>{children}</Providers> |
| 84 | + </body> |
| 85 | + </html> |
| 86 | + ); |
| 87 | +} |
| 88 | +``` |
| 89 | + |
| 90 | +> **Why this pattern?** |
| 91 | +> |
| 92 | +> - Callbacks (and other interactive bits) must be declared in a client component. |
| 93 | +> - Keeping layout.tsx as a server component maintains optimal rendering and avoids making your entire app client-side unnecessarily. |
| 94 | +> - Centralizing Turnkey setup in app/providers.tsx keeps configuration, styles, and callbacks in one place. |
| 95 | + |
| 96 | + |
| 97 | +## Quick Authentication |
| 98 | + |
| 99 | +The easiest way to handle authentication is using the `handleLogin` function from the `useTurnkey` hook. This will automatically show a modal with all the authentication methods you've enabled in your dashboard. |
| 100 | + |
| 101 | +```tsx |
| 102 | +import { useTurnkey } from "@turnkey/react-wallet-kit"; |
| 103 | + |
| 104 | +function LoginButton() { |
| 105 | + const { handleLogin } = useTurnkey(); |
| 106 | + |
| 107 | + return <button onClick={handleLogin}>Login / Sign Up</button>; |
| 108 | +} |
| 109 | +``` |
| 110 | + |
| 111 | + |
| 112 | +For more information, check out [our docs!](https://docs.turnkey.com) |
0 commit comments