> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streambird.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

Configure the MoonKey React SDK in your application to enable authentication and wallet functionality.

## Before you start

Make sure you have:

* [Installed the MoonKey React SDK](/get-started/frontend-sdks/react/installation)
* [Created a MoonKey app](/get-started/dashboard/create-new-app) and obtained your App ID from the dashboard

<Tip>
  Working with multiple environments or domains? You can create separate MoonKey apps for test (development) and production to isolate configurations and user data.
</Tip>

## Initialize the MoonKey Provider

The `MoonKeyProvider` component wraps your application and provides authentication and wallet context to all child components. Import it from the appropriate blockchain-specific entry point and add it to your app's root level.

**Choose your import based on the blockchain you're supporting:**

* For Ethereum/EVM chains: `@moon-key/react-auth/ethereum`
* For Solana: `@moon-key/react-auth/solana`

<Tip>
  Place the `MoonKeyProvider` as high in your component tree as possible. Any component that needs to use MoonKey hooks must be wrapped by the provider.
</Tip>

<Tabs>
  <Tab title="Ethereum">
    <CodeGroup>
      ```tsx Next.js (App Router) theme={null}
      'use client';

      import { MoonKeyProvider } from '@moon-key/react-auth';

      export default function Providers({ children }: { children: React.ReactNode }) {
        return (
          <MoonKeyProvider
            publishableKey="your-moonkey-publishableKey"
            config={{
              // Automatically create embedded wallets for users
              embeddedWallets: {
                createOnLogin: 'always'
              },
              // Configure which login methods to show
              loginMethods: ['email', 'google']
            }}
          >
            {children}
          </MoonKeyProvider>
        );
      }
      ```

      ```tsx Create React App theme={null}
      import React from 'react';
      import ReactDOM from 'react-dom/client';
      import { MoonKeyProvider } from '@moon-key/react-auth';
      import App from './App';
      import './index.css';

      const root = ReactDOM.createRoot(
        document.getElementById('root') as HTMLElement
      );

      root.render(
        <React.StrictMode>
          <MoonKeyProvider
            publishableKey="your-moonkey-publishableKey"
            config={{
              // Automatically create embedded wallets for users
              embeddedWallets: {
                createOnLogin: 'always'
              },
              // Configure which login methods to show
              loginMethods: ['email', 'google']
            }}
          >
            <App />
          </MoonKeyProvider>
        </React.StrictMode>
      );
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Solana">
    <CodeGroup>
      ```tsx Next.js (App Router) theme={null}
      'use client';

      import { MoonKeyProvider } from '@moon-key/react-auth';

      export default function Providers({ children }: { children: React.ReactNode }) {
        return (
          <MoonKeyProvider
            publishableKey="your-moonkey-publishableKey"
            config={{
              // Automatically create embedded wallets for users
              embeddedWallets: {
                createOnLogin: 'always'
              },
              // Configure which login methods to show
              loginMethods: ['email', 'google']
            }}
          >
            {children}
          </MoonKeyProvider>
        );
      }
      ```

      ```tsx Create React App theme={null}
      import React from 'react';
      import ReactDOM from 'react-dom/client';
      import { MoonKeyProvider } from '@moon-key/react-auth';
      import App from './App';
      import './index.css';

      const root = ReactDOM.createRoot(
        document.getElementById('root') as HTMLElement
      );

      root.render(
        <React.StrictMode>
          <MoonKeyProvider
            publishableKey="your-moonkey-publishableKey"
            config={{
              // Automatically create embedded wallets for users
              embeddedWallets: {
                createOnLogin: 'always'
              },
              // Configure which login methods to show
              loginMethods: ['email', 'google']
            }}
          >
            <App />
          </MoonKeyProvider>
        </React.StrictMode>
      );
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Provider configuration

The `MoonKeyProvider` component accepts the following props:

<ParamField path="appId" type="string" required>
  Your MoonKey App ID from the dashboard. This identifies your application and determines which configuration settings to use.
</ParamField>

<ParamField path="config" type="Object">
  Configuration options for authentication methods, embedded wallets, appearance, and behavior.

  **Common configuration options:**

  * `loginMethods`: Array of authentication methods to enable (`'email'`, `'google'`, `'apple'`, `'wallet'`)
  * `embeddedWallets`: Settings for automatic wallet creation and supported chains
  * `appearance`: Customize the UI theme and branding

  See the [configuration guide](/get-started/frontend-sdks/react/configuration) for all available options.
</ParamField>

## Waiting for initialization

When the `MoonKeyProvider` first mounts, the SDK performs initialization tasks including:

* Checking for active user sessions
* Refreshing authentication tokens
* Loading user profile and wallet data
* Restoring previous authentication state

**Always wait for the SDK to finish initializing before accessing user state or triggering authentication flows.** Use the `ready` property from the `useMoonKey` hook to determine when initialization is complete.

```tsx theme={null}
import { useMoonKey } from '@moon-key/react-auth';

function YourComponent() {
  const { ready, isAuthenticated, user } = useMoonKey();

  // Show loading state while MoonKey initializes
  if (!ready) {
    return <div>Loading...</div>;
  }

  // Now it's safe to use authentication state
  if (isAuthenticated) {
    return <div>Welcome back, {user?.email}!</div>;
  }

  return <div>Please log in</div>;
}
```

<Info>
  The `ready` state ensures you don't show incorrect UI (like a login button for an already-authenticated user) during the brief initialization period.
</Info>

## Next.js considerations

### App Router (Next.js 13+)

When using Next.js App Router, your provider component must include the `'use client'` directive since MoonKey relies on React hooks and browser APIs:

```tsx providers.tsx theme={null}
'use client';

import { MoonKeyProvider } from '@moon-key/react-auth';

export default function Providers({ children }: { children: React.ReactNode }) {
  return (
    <MoonKeyProvider publishableKey="your_publishable_key">
      {children}
    </MoonKeyProvider>
  );
}
```

Then use this provider in your root layout:

```tsx app/layout.tsx theme={null}
import Providers from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>
          {children}
        </Providers>
      </body>
    </html>
  );
}
```

### Pages Router (Next.js 12 and earlier)

For Pages Router, wrap your app in `_app.tsx`:

```tsx pages/_app.tsx theme={null}
import type { AppProps } from 'next/app';
import { MoonKeyProvider } from '@moon-key/react-auth';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <MoonKeyProvider publishableKey="your_publishable_key">
      <Component {...pageProps} />
    </MoonKeyProvider>
  );
}
```

## Example configurations

### Minimal setup

The simplest configuration with just an App ID (Ethereum):

```tsx theme={null}
import { MoonKeyProvider } from '@moon-key/react-auth';

<MoonKeyProvider publishableKey="your-moonkey-publishableKey">
  {children}
</MoonKeyProvider>
```

### Email-only authentication

For applications that only need email authentication:

```tsx theme={null}
import { MoonKeyProvider } from '@moon-key/react-auth';

<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    loginMethods: ['email']
  }}
>
  {children}
</MoonKeyProvider>
```

### Wallet-first experience

For Web3-native applications with Solana:

```tsx theme={null}
import { MoonKeyProvider } from '@moon-key/react-auth';

<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    loginMethods: ['wallet', 'email'],
    embeddedWallets: {
      createOnLogin: 'always'
    }
  }}
>
  {children}
</MoonKeyProvider>
```

### Custom branding

Customize the appearance to match your brand:

```tsx theme={null}
import { MoonKeyProvider } from '@moon-key/react-auth';

<MoonKeyProvider
  publishableKey="your-moonkey-publishableKey"
  config={{
    appearance: {
      theme: 'dark',
      logo: 'https://your-domain.com/logo.png'
    },
    loginMethods: ['email', 'google', 'wallet']
  }}
>
  {children}
</MoonKeyProvider>
```

## Troubleshooting

### "MoonKey is not ready" errors

If you encounter errors about MoonKey not being initialized, ensure you're:

1. Checking the `ready` state before using MoonKey hooks
2. Wrapping your components with `MoonKeyProvider`
3. Not trying to use MoonKey hooks in server components (Next.js App Router)

### Hooks can only be used inside MoonKeyProvider

This error means you're trying to use a MoonKey hook outside the provider's scope. Make sure:

1. Your `MoonKeyProvider` wraps all components that use MoonKey hooks
2. You haven't accidentally placed the provider inside a component that's trying to use MoonKey
3. The provider is rendered before any child components try to use hooks

## Next steps

<CardGroup cols={2}>
  <Card title="Add authentication" icon="lock" href="/get-started/frontend-sdks/react/authentication">
    Learn how to implement login and logout functionality
  </Card>

  <Card title="Create wallets" icon="wallet" href="/get-started/frontend-sdks/react/wallets">
    Generate embedded wallets for your users
  </Card>

  <Card title="Customize appearance" icon="palette" href="/get-started/frontend-sdks/react/customization">
    Match MoonKey's UI to your brand
  </Card>

  <Card title="Handle user data" icon="user" href="/get-started/frontend-sdks/react/user-data">
    Access and manage user profiles
  </Card>
</CardGroup>