@hypership/auth-react v1.1.3

@hypership/auth-react

A powerful and flexible authentication SDK for React applications, part of the Hypership platform.

Contents

• Installation
• Features
• Quick Start
• Using the Hook
• Available Components
• Theme Support
• Styling
• Using Current User Data
• Server-Side Authentication
• API Reference
  • HypershipAuthProvider Props
  • AuthFlow Props
  • AuthFlowPage Props
  • useHypershipAuth Hook

Installation

npm install @hypership/auth-react

Features

• 🔐 Complete authentication flow (Sign In, Sign Up, Password Reset)
• 📧 Email verification and account confirmation
• 🔄 Password reset and change functionality
• 🌓 Built-in light/dark theme support with Tailwind CSS
• 🚀 GitHub OAuth integration
• 🎨 Customizable UI components
• 🔒 Secure token management
• 🌐 Automatic token refresh
• 📱 Responsive design

Quick Start

1. Wrap your app with the HypershipAuthProvider:

import { HypershipAuthProvider } from "@hypership/auth-react";

function App() {
  return (
    <HypershipAuthProvider apiKey="your-hypership-api-key">
      <YourApp />
    </HypershipAuthProvider>
  );
}

2. Use the authentication flow component:

import { AuthFlow } from "@hypership/auth-react";

function LoginPage() {
  const handleAuthSuccess = () => {
    // Handle successful authentication
  };

  return <AuthFlow onAuthSuccess={handleAuthSuccess} />;
}

// Or start with the sign up form:
function SignUpPage() {
  const handleAuthSuccess = () => {
    // Handle successful authentication
  };

  return <AuthFlow onAuthSuccess={handleAuthSuccess} initialView="signUp" />;
}

Theme Support

The SDK now uses Tailwind CSS for styling and includes first-class support for dark mode:

<HypershipAuthProvider apiKey="your-hypership-public-key">
  <YourApp />
</HypershipAuthProvider>

Automatic Theme Detection

Our components will automatically detect and adapt to your app's theme:

1. Tailwind Dark Mode: If your app uses Tailwind's dark mode class on the HTML element
2. next-themes: If your app uses the popular next-themes package
3. System Preference: Falls back to the user's system preference

ThemeToggle Component

Add a theme toggle button to your app with our built-in component:

import { ThemeToggle } from "@hypership/auth-react";

function YourComponent() {
  return (
    <div>
      <h1>Your App</h1>
      <ThemeToggle />
    </div>
  );
}

Theme Context

Access and control the theme directly:

import { useTheme } from "@hypership/auth-react";

function YourComponent() {
  const { theme, setTheme, resolvedTheme } = useTheme();

  return (
    <div>
      <p>Current theme: {theme}</p>
      <p>Resolved theme: {resolvedTheme}</p>
      <button onClick={() => setTheme("dark")}>Dark Mode</button>
      <button onClick={() => setTheme("light")}>Light Mode</button>
      <button onClick={() => setTheme("system")}>System</button>
    </div>
  );
}

Dark Mode Helpers

Work with dark mode easily:

import { useDarkMode } from "@hypership/auth-react";

function YourComponent() {
  const isDarkMode = useDarkMode();

  return (
    <div>{isDarkMode ? "Dark mode is active" : "Light mode is active"}</div>
  );
}

Styling

Our components use Tailwind CSS for styling. If your project doesn't use Tailwind, don't worry - we bundle all the necessary styles.

Importing Styles

To use our components with their styles, you only need to:

// In your main entry file (e.g., _app.js, App.js, main.jsx)
import "@hypership/auth-react/style.css";

That's it! The necessary wrapper class is automatically included in the HypershipAuthProvider, so you don't need to add any additional wrappers.

// This is all you need - no extra wrapper required!
<HypershipAuthProvider apiKey="your-hypership-api-key">
  <AuthFlow onAuthSuccess={handleSuccess} />
</HypershipAuthProvider>

Using the AuthFlowPage Component

The AuthFlowPage component provides a complete, styled authentication page:

import { AuthFlowPage } from "@hypership/auth-react";

function LoginPage() {
  return (
    <AuthFlowPage
      title="Welcome to My App"
      onAuthSuccess={handleSuccess}
      backgroundImage="/path/to/image.jpg" // Optional
    />
  );
}

Dark Mode Support

Dark mode is handled automatically through the ThemeProvider:

import { ThemeToggle } from "@hypership/auth-react";

function App() {
  return (
    <HypershipAuthProvider apiKey="your-hypership-api-key">
      <div>
        <ThemeToggle />
        <AuthFlow onAuthSuccess={handleSuccess} />
      </div>
    </HypershipAuthProvider>
  );
}

If your project already uses Tailwind CSS, our component styles will integrate seamlessly with your existing design system.

To ensure proper theming, make sure your app's HTML element has the dark class when dark mode is active. Our ThemeProvider handles this automatically.

Using the Hook

Access authentication state and methods using the useHypershipAuth hook:

import { useHypershipAuth } from "@hypership/auth-react";

function YourComponent() {
  const {
    currentUser,
    isAuthenticated,
    signIn,
    signUp,
    signOut,
    error,
    theme,
    toggleTheme,
  } = useHypershipAuth();

  // Use the authentication state and methods
}

Available Components

• AuthFlow: Complete authentication flow UI with configurable initial view (sign in or sign up)
• AuthFlowPage: Complete authentication flow UI with a page and configurable initial view
• SignIn: Standalone sign-in component
• SignUp: Standalone sign-up component
• PasswordReset: Password reset flow
• ConfirmUserAccount: Account confirmation component
• Private: Protected route wrapper

Using AuthFlow with initialView

You can choose which authentication view to show initially:

import { AuthFlow } from "@hypership/auth-react";

// Start with sign in (default)
function LoginPage() {
  return <AuthFlow onAuthSuccess={handleSuccess} />;
}

// Start with sign up
function RegisterPage() {
  return <AuthFlow onAuthSuccess={handleSuccess} initialView="signUp" />;
}

// Start with password reset
function ResetPasswordPage() {
  // Optionally pre-populate the email
  return (
    <AuthFlow
      onAuthSuccess={handleSuccess}
      initialView="passwordReset"
      initialEmail="user@example.com" // Optional
    />
  );
}

// Start with account confirmation
function ConfirmAccountPage() {
  // You can pre-populate the email for a smoother experience
  return (
    <AuthFlow
      onAuthSuccess={handleSuccess}
      initialView="confirmAccount"
      initialEmail="user@example.com" // Optional
    />
  );
}

Using AuthFlowPage with initialView

import { AuthFlowPage } from "@hypership/auth-react";

// Sign in page
function SignInPage() {
  return (
    <AuthFlowPage
      title="Welcome Back"
      onAuthSuccess={handleSuccess}
      backgroundImage="/path/to/image.jpg" // Optional
    />
  );
}

// Registration page
function RegisterPage() {
  return (
    <AuthFlowPage
      title="Create an Account"
      onAuthSuccess={handleSuccess}
      initialView="signUp"
      backgroundImage="/path/to/image.jpg" // Optional
    />
  );
}

// Password reset page
function ResetPasswordPage() {
  return (
    <AuthFlowPage
      title="Reset Your Password"
      onAuthSuccess={handleSuccess}
      initialView="passwordReset"
      initialEmail="user@example.com" // Optional pre-filled email
      backgroundImage="/path/to/image.jpg" // Optional
    />
  );
}

// Account confirmation page
function ConfirmAccountPage() {
  // For verification after signup
  return (
    <AuthFlowPage
      title="Verify Your Account"
      onAuthSuccess={handleSuccess}
      initialView="confirmAccount"
      initialEmail="user@example.com" // Pre-fill the email for better UX
      backgroundImage="/path/to/image.jpg" // Optional
    />
  );
}

Using Current User Data

You can access the current user's information using the useHypershipAuth hook:

import { useHypershipAuth } from "@hypership/auth-react";

function Component() {
  const { currentUser } = useHypershipAuth();

  return (
    <>
      <div>ID: {currentUser?.id}</div>
      <div>Username: {currentUser?.username}</div>
      <div>First Name: {currentUser?.firstName}</div>
      <div>Last Name: {currentUser?.lastName}</div>
      <div>Enabled: {currentUser?.enabled}</div>
      <div>Metadata: {currentUser?.metadata}</div>
    </>
  );
}

export default Component;

Server-Side Authentication

For server-side components and server actions in Next.js, you can use the currentUser function to verify authentication and get the current user's information:

import { currentUser } from "@hypership/auth-react/server";

// Example of a Next.js Server Action
("use server");

interface Website {
  id: string;
  name: string;
  url: string;
  websiteUserId: string;
  createdAt: Date;
}

export async function getWebsites(): Promise<Website[]> {
  try {
    const user = await currentUser();

    if (!user?.userId) {
      return [];
    }

    const websites = await prisma.website.findMany({
      where: {
        websiteUserId: user.userId,
      },
      orderBy: {
        createdAt: "desc",
      },
    });
    return websites;
  } catch {
    return [];
  }
}

// Example of using server-side auth in a Route Handler
export async function GET() {
  const user = await currentUser();

  if (!user?.userId) {
    return new Response("Unauthorized", { status: 401 });
  }

  // Perform authenticated operations
  const data = await fetchUserData(user.userId);
  return Response.json(data);
}

The currentUser function automatically handles token verification and returns an object containing:

• userId: The authenticated user's ID
• tokenData: Additional token information including expiration
• error: Any authentication errors that occurred

This makes it easy to protect server-side routes and actions while maintaining type safety and security.

API Reference

HypershipAuthProvider Props

AuthFlow Props

AuthFlowPage Props

useHypershipAuth Hook

Returns an object with:

• Authentication State:

  • currentUser: Current user object or null
  • isAuthenticated: Boolean indicating auth status
  • error: Error message or null
  • theme: Current theme ('light' or 'dark')

• Loading States:

  • signingIn: Loading state for sign-in
  • signingUp: Loading state for sign-up
  • authenticating: Loading state for initial auth
  • passwordResetting: Loading state for password reset
  • confirmingAccount: Loading state for account confirmation

• Methods:

  • signIn(email: string, password: string): Promise<void>
  • signUp(email: string, password: string): Promise<void>
  • signOut(): Promise<void>