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

​
Before you start

Make sure you have:
Working with multiple environments or domains? You can create separate MoonKey apps for test (development) and production to isolate configurations and user data.

​
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
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.
  • Ethereum
  • Solana
'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>
  );
}

​
Provider configuration

The MoonKeyProvider component accepts the following props:
​
appId
string
required
Your MoonKey App ID from the dashboard. This identifies your application and determines which configuration settings to use.
​
config
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 for all available options.

​
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. 
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>;
}
The ready state ensures you don’t show incorrect UI (like a login button for an already-authenticated user) during the brief initialization period.

​
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:
providers.tsx
'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:
app/layout.tsx
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:
pages/_app.tsx
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): 
import { MoonKeyProvider } from '@moon-key/react-auth';

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

​
Email-only authentication

For applications that only need email authentication: 
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: 
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: 
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

Add authentication

Learn how to implement login and logout functionality

Create wallets

Generate embedded wallets for your users

Customize appearance

Match MoonKey’s UI to your brand

Handle user data

Access and manage user profiles