useAuth Hook

Relevant source files

The following files were used as context for generating this wiki page:

• src/hooks.ts
• src/types.ts
• src/index.ts
• src/middleware.ts
• README.md

The useAuth hook is a core client-side utility within the @pcstyle/auth SDK designed to provide a unified interface for accessing authentication states across PCSTYLE services. It abstracts the underlying integration with WorkOS AuthKit, offering a simplified data structure that includes the current user object, loading status, and authentication confirmation.

This hook is intended for use within React Client Components and requires the application to be wrapped in the AuthKitProvider from @workos-inc/authkit-nextjs. It works in conjunction with middleware.ts to ensure secure access to protected routes.
Sources: src/hooks.ts:1-24, README.md:46-60

Core Functionality

The useAuth hook serves as the primary entry point for components to consume authentication data. It internally utilizes the useAuth hook from @workos-inc/authkit-nextjs/components and transforms the result into a standardized AuthState object.

Data Transformation

The hook maps the internal AuthKit state to a clean interface:

• user: Returns the WorkOS User object or null.
• isLoading: A boolean indicating if the authentication check is in progress.
• isAuthenticated: A derived boolean that is true if a valid user object exists.

The diagram above illustrates how internal WorkOS state variables are processed into the unified AuthState structure.
Sources: src/hooks.ts:18-24, src/types.ts:17-21

Related Authentication Hooks

In addition to the base useAuth hook, the SDK provides specialized helpers for common authentication patterns.

useUser Hook

The useUser hook is a convenience wrapper for scenarios where a component requires an authenticated user to function. Unlike useAuth, it will throw an error if the user is not authenticated, acting as an implicit assertion.

Hook	Behavior	Throw Condition
useAuth	Returns state (User | null)	Never
useUser	Returns User	If !isAuthenticated or !user

Sources: src/hooks.ts:33-43, README.md:83-84

URL Helpers

The SDK provides utility functions to generate redirect URLs for authentication flows:

• getSignInUrl(returnTo?): Generates the URL for the PCSTYLE auth portal. If a returnTo path is provided, it is base64 encoded into a state parameter.
• getSignOutUrl(): Returns the standard sign-out endpoint for the auth domain.

Sources: src/hooks.ts:48-63, README.md:85-86

Technical Specifications

Data Structures

The hook relies on the following TypeScript interfaces defined in the core library:

export interface User {
    id: string;
    email: string;
    firstName: string | null;
    lastName: string | null;
    profilePictureUrl: string | null;
    createdAt: string;
    updatedAt: string;
}

export interface AuthState {
    user: User | null;
    isLoading: boolean;
    isAuthenticated: boolean;
}

Sources: src/types.ts:4-21

Interaction Flow

The following sequence diagram shows how the useAuth hook interacts with the WorkOS provider and the UI components.

Usage Example

The hook is designed for simple conditional rendering in React components.

'use client';
import { useAuth } from '@pcstyle/auth';

export function ProfileButton() {
  const { user, isLoading, isAuthenticated } = useAuth();

  if (isLoading) return <span>Loading...</span>;
  if (!isAuthenticated) return <a href="https://auth.pcstyle.dev">Sign In</a>;
  
  return <span>{user.email}</span>;
}

Sources: README.md:52-60, src/hooks.ts:6-16

Summary

The useAuth hook provides a standardized, type-safe way to manage user sessions within the PCSTYLE ecosystem. By abstracting the complexities of WorkOS AuthKit and providing companion utilities like useUser and URL generators, it ensures consistent authentication behavior across different microservices and frontend applications.