vorld-auth-react

React SDK for Vorld Auth — passwordless authentication with Email OTP, OAuth, and Solana wallet support.

Installation

npm install vorld-auth-react

For wallet authentication (optional):

npm install @solana/web3.js

Quick Start

1. Wrap your app with the provider

"use client";

import { VorldAuthProvider } from "vorld-auth-react";
import { useMemo } from "react";

function useDeviceId() {
  return useMemo(() => {
    if (typeof window === "undefined") return undefined;
    const key = "vorld_device_id";
    let id = localStorage.getItem(key);
    if (!id) {
      id = crypto.randomUUID();
      localStorage.setItem(key, id);
    }
    return id;
  }, []);
}

export function Providers({ children }: { children: React.ReactNode }) {
  const deviceId = useDeviceId();

  return (
    <VorldAuthProvider
      appId="your-app-id"
      authUrl="https://auth.thevorld.com"
      deviceId={deviceId}
      onSessionExpired={() => {
        // Handle session expiry
      }}
    >
      {children}
    </VorldAuthProvider>
  );
}

2. Use the auth hook

"use client";

import { useState } from "react";
import { useVorldAuth } from "vorld-auth-react";

export function LoginPage() {
  const {
    user,
    isAuthenticated,
    isLoading,
    sendOTP,
    verifyOTP,
    signInWithGoogle,
    logout,
  } = useVorldAuth();

  const [email, setEmail] = useState("");
  const [otp, setOtp] = useState("");
  const [otpSent, setOtpSent] = useState(false);

  if (isLoading) return <div>Loading...</div>;

  if (isAuthenticated) {
    return (
      <div>
        <p>Welcome, {user?.email}!</p>
        <button onClick={logout}>Logout</button>
      </div>
    );
  }

  return (
    <div>
      {!otpSent ? (
        <>
          <input
            type="email"
            value={email}
            onChange={(e) => setEmail(e.target.value)}
            placeholder="Enter your email"
          />
          <button onClick={() => { sendOTP(email); setOtpSent(true); }}>
            Send OTP
          </button>
          <button onClick={() => signInWithGoogle()}>
            Sign in with Google
          </button>
        </>
      ) : (
        <>
          <input
            type="text"
            value={otp}
            onChange={(e) => setOtp(e.target.value)}
            placeholder="Enter OTP"
          />
          <button onClick={() => verifyOTP(email, otp)}>Verify</button>
        </>
      )}
    </div>
  );
}

Provider Props

| Prop | Type | Required | Description | |--------------------|--------------------------------|----------|--------------------------------------------------| | appId | string | Yes | Your Vorld App ID | | authUrl | string | No | Auth server URL (default: https://auth.thevorld.com) | | deviceId | string | No | Device ID for token binding (recommended) | | platform | string | No | Platform identifier (default: "web") | | debug | boolean | No | Enable debug logging | | onAuthStateChange| (user: User \| null) => void | No | Called when auth state changes | | onSessionExpired | () => void | No | Called when session expires |

Hooks

useVorldAuth

const {
  user,              // User | null
  isAuthenticated,   // boolean
  isLoading,         // boolean
  error,             // string | null
  
  // Email OTP
  sendOTP,           // (email: string) => Promise<void>
  verifyOTP,         // (email: string, otp: string) => Promise<void>
  
  // OAuth
  signInWithGoogle,  // (returnTo?: string) => Promise<void>
  signInWithDiscord, // (returnTo?: string) => Promise<void>
  signInWithTwitter, // (returnTo?: string) => Promise<void>
  
  // Wallet
  signInWithWallet,  // () => Promise<void>
  
  // Session
  logout,            // () => Promise<void>
  refreshSession,    // () => Promise<void>
} = useVorldAuth();

useWallet

const {
  wallets,           // Wallet[]
  defaultWallet,     // Wallet | null
  isConnecting,      // boolean
  connectWallet,     // (nickname?: string) => Promise<void>
  disconnectWallet,  // (walletId: string) => Promise<void>
  signMessage,       // (message: string) => Promise<string>
  setDefaultWallet,  // (walletId: string) => Promise<void>
} = useWallet();

useSession

Lightweight hook for read-only session state:

const { user, isAuthenticated, isLoading, error } = useSession();

Components

import { OTPInput, GoogleButton, WalletButton } from "vorld-auth-react/components";

// OTP input with auto-submit
<OTPInput length={6} onComplete={(otp) => verifyOTP(email, otp)} />

// OAuth buttons
<GoogleButton onSuccess={() => router.push("/dashboard")} />

// Wallet button
<WalletButton onSuccess={() => router.push("/dashboard")} />

Supported Wallets

Phantom, Solflare, Backpack, Glow, Coin98

Requirements

• React 18+ or 19
• Node.js 18+

Links

• Documentation
• Developer Console