Setup Guide

This guide provides a comprehensive setup of Reclaim Auth in your React application.

Prerequisites

React application
Node.js environment
Basic understanding of TypeScript
Access to Reclaim Protocol credentials

Configuration Setup

First, create a configuration file to manage your authentication settings:

Create src/config/auth.config.ts:

interface AuthConfig {
  clientId: string;
  redirectUri: string;
  environment?: 'development' | 'production';
}
 
export const authConfig: AuthConfig = {
  clientId: process.env.REACT_APP_RECLAIM_CLIENT_ID!,
  clientSecret: process.env.REACT_APP_RECLAIM_CLIENT_SECRET!,
  redirectUri: process.env.REACT_APP_RECLAIM_REDIRECT_URI!,
  environment: process.env.NODE_ENV as 'development' | 'production'
};

Authentication Provider Implementation

The Authentication Provider manages the authentication state throughout your application using React's Context API:

// src/providers/AuthProvider.tsx
import React, { createContext, useContext, useEffect, useState } from 'react';
import getReclaimAuth, { type ReclaimUser } from 'identity-react';
import { authConfig } from '../config/auth.config';
 
interface AuthContextType {
  user: ReclaimUser | null;
  loading: boolean;
  error: Error | null;
  signIn: () => Promise<void>;
  signOut: () => Promise<void>;
}
 
const AuthContext = createContext<AuthContextType | null>(null);
 
export function AuthProvider({ children }: { children: React.ReactNode }) {
  const [user, setUser] = useState<ReclaimUser | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);
 
  const auth = getReclaimAuth(authConfig.clientId, authConfig.clientSecret, authConfig.redirectUri);
 
  useEffect(() => {
    const unsubscribe = auth.onAuthStateChanged((newUser) => {
      setUser(newUser);
      setLoading(false);
    });
 
    return () => unsubscribe();
  }, []);
 
  const signIn = async () => {
    try {
      setError(null);
      await auth.signIn();
    } catch (err) {
      setError(err instanceof Error ? err : new Error('Authentication failed'));
      throw err;
    }
  };
 
  const signOut = async () => {
    try {
      setError(null);
      await auth.signOut();
    } catch (err) {
      setError(err instanceof Error ? err : new Error('Sign out failed'));
      throw err;
    }
  };
 
  return (
    <AuthContext.Provider 
      value={{ 
        user, 
        loading, 
        error,
        signIn, 
        signOut 
      }}
    >
      {children}
    </AuthContext.Provider>
  );
}
 
// Custom hook to use auth context
export function useAuth() {
  const context = useContext(AuthContext);
  if (!context) {
    throw new Error('useAuth must be used within an AuthProvider');
  }
  return context;
}

Application Integration

To enable authentication across your application:

Wrap your root component with the AuthProvider:

// src/App.tsx
import { AuthProvider } from './providers/AuthProvider';
 
function App() {
  return (
    <AuthProvider>
      <Router>
        <YourAppComponents />
      </Router>
    </AuthProvider>
  );
}

Implementation Example

Here's a practical example of implementing authentication in a Profile component:

// src/components/Profile.tsx
import { useAuth } from '../providers/AuthProvider';
 
function Profile() {
  const { user, loading, error, signIn, signOut } = useAuth();
 
  if (loading) {
    return <div>Loading...</div>;
  }
 
  if (error) {
    return <div>Error: {error.message}</div>;
  }
 
  if (!user) {
    return (
      <div>
        <p>Please sign in to view your profile</p>
        <button onClick={signIn}>Sign In</button>
      </div>
    );
  }
 
  return (
    <div>
      <h1>Profile</h1>
      <p>ID: {user.id}</p>
      <pre>{JSON.stringify(user.userData, null, 2)}</pre>
      <pre>{JSON.stringify(user.additionalData, null, 2)}</pre>
      <button onClick={signOut}>Sign Out</button>
    </div>
  );
}

Type Definitions

The SDK provides TypeScript interfaces for type safety:

[Previous TypeScript interfaces remain unchanged]

Security Best Practices

To ensure secure authentication:

Environment Variable Management Create a .env file in your project root:

REACT_APP_RECLAIM_CLIENT_ID=your_client_id
REACT_APP_RECLAIM_CLIENT_SECRET=your_client_secret,
REACT_APP_RECLAIM_REDIRECT_URI=http://localhost:3000

Security Headers Configuration Add security headers to your HTML file:

<!-- public/index.html -->
<meta http-equiv="Content-Security-Policy" content="default-src 'self' https://identity.reclaimprotocol.org; frame-src 'self' https://identity.reclaimprotocol.org">

Robust Error Handling Implement comprehensive error handling:

try {
  await auth.signIn();
} catch (error) {
  if (error.message.includes('popup')) {
    // Handle popup blocked
  } else if (error.message.includes('unauthorized')) {
    // Handle unauthorized client
  } else {
    // Handle other errors
  }
}

Additional Resources

For more information about authentication hooks, visit Authentication Hooks
Review the Security Guidelines for best practices
Check the API Documentation for detailed reference

Troubleshooting Tips

Ensure all environment variables are properly set before running the application
Check browser console for authentication-related errors
Verify CORS settings if experiencing cross-origin issues
Confirm proper setup of redirect URIs in your Reclaim Protocol dashboard

Setup Guide

On this page