godgpt-web-auth

A React authentication package with built-in support for Google, Apple, and Email sign-in.

Features

• 🔐 AuthProvider - Context provider for managing auth state
• 🎨 LoginPage - Pre-built, customizable login UI
• 🪝 useAuth - Hook for accessing auth state and actions
• 🔄 Token Management - Automatic token storage and refresh
• 📦 Zero Config - Works out of the box with sensible defaults
• 🔌 Pluggable Storage - Use localStorage, sessionStorage, or custom adapters

Installation

npm install godgpt-web-auth
# or
yarn add godgpt-web-auth
# or
pnpm add godgpt-web-auth

Quick Start

1. Wrap your app with AuthProvider

import { AuthProvider, LoginPage, useAuth } from "godgpt-web-auth";
import type { AuthConfig } from "godgpt-web-auth";

const authConfig: AuthConfig = {
  backendUrl: process.env.NEXT_PUBLIC_AUTH_BACKEND_URL,
  appId: "your-app-id",
  google: {
    clientId: process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID,
  },
  apple: {
    clientId: process.env.NEXT_PUBLIC_APPLE_CLIENT_ID, // Service ID for web
    redirectUri: "https://your-domain.com",
  },
  email: {
    enabled: true,
  },
};

function App() {
  return (
    <AuthProvider
      config={authConfig}
      onLogout={() => {
        // Handle logout (e.g., redirect to home)
        window.location.href = "/";
      }}
    >
      <AppContent />
    </AuthProvider>
  );
}

2. Use the LoginPage component

function AppContent() {
  const { tokens, logout, isLoading, isAuthLoaded } = useAuth();

  // Show loading while checking stored tokens
  if (!isAuthLoaded) {
    return <div>Loading...</div>;
  }

  // Show login page if not authenticated
  if (!tokens) {
    return <LoginPage />;
  }

  // User is authenticated
  return (
    <div>
      <h1>Welcome!</h1>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

Exports

Main Exports

| Export | Type | Description | | -------------- | --------- | ------------------------------------------------------------------ | | AuthProvider | Component | Context provider - wrap your app with this | | LoginPage | Component | Pre-built login UI with all providers | | useAuth | Hook | Access auth state: tokens, logout, isLoading, isAuthLoaded |

Types

| Type | Description | | ------------------ | ------------------------------------- | | AuthConfig | Configuration object for AuthProvider | | AuthContextValue | Return type of useAuth hook | | JWTData | Token data structure | | AuthResult | Result from sign-in attempts | | AuthProviderType | "google" \| "apple" \| "password" |

Advanced Exports

For custom implementations:

// Individual sign-in strategies
import {
  signInWithEmail,
  signInWithGoogle,
  signInWithApple,
} from "godgpt-web-auth";

// Storage adapters
import {
  storageService,
  createStorageService,
  localStorageAdapter,
  memoryStorageAdapter,
} from "godgpt-web-auth";

// Token services
import { exchangeToken, refreshToken } from "godgpt-web-auth";

Configuration

AuthConfig

interface AuthConfig {
  /** Backend URL for token exchange */
  backendUrl: string;

  /** App identifier sent with token requests */
  appId?: string;

  /** Google OAuth configuration */
  google?: {
    clientId: string;
  };

  /** Apple Sign In configuration */
  apple?: {
    clientId: string; // Service ID (not App ID) for web
    redirectUri?: string; // Required for production (HTTPS)
  };

  /** Email/password configuration */
  email?: {
    enabled: boolean;
  };
}

useAuth Hook

const {
  tokens, // JWTData | null - Current tokens
  logout, // () => Promise<void> - Clear tokens and call onLogout
  isLoading, // boolean - Sign-in in progress
  isAuthLoaded, // boolean - Initial token check complete
} = useAuth();

OAuth Provider Setup

Google

1. Go to Google Cloud Console
2. Create OAuth 2.0 Client ID (Web application)
3. Add your domain to Authorized JavaScript origins
4. Add your domain to Authorized redirect URIs

Apple

1. Go to Apple Developer Portal
2. Create a Service ID (not App ID) for web
3. Enable "Sign In with Apple"
4. Configure domains and return URLs
5. Note: Apple requires HTTPS for redirect URIs

Token Storage

By default, tokens are stored in localStorage. For custom storage:

import { createStorageService, memoryStorageAdapter } from "godgpt-web-auth";

// Use memory storage (for SSR or testing)
const customStorage = createStorageService(memoryStorageAdapter);

License

MIT