useUser Hook

Relevant source files

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

• src/hooks.ts
• src/types.ts
• README.md
• src/index.ts
• package.json

The useUser hook is a specialized React hook provided by the @pcstyle/auth SDK designed to retrieve the currently authenticated user's profile information. It serves as a strict alternative to the broader useAuth hook, specifically tailored for application contexts where a user's presence is mandatory.

Within the architecture of the PCSTYLE auth system, this hook acts as a consumer of the session state managed by WorkOS AuthKit. By abstracting the validation logic, it ensures that developers can access user data without manual null-checks, provided the component is rendered within an authenticated boundary.

Sources: src/hooks.ts:38-42, README.md:1-5

Core Logic and Implementation

The useUser hook is built on top of the useAuth hook. It executes a validation check on the isAuthenticated status and the existence of the user object. If either check fails, the hook triggers a runtime error, enforcing a strict "authenticated context" requirement.

Logic Flow

The following diagram illustrates the internal logic of the hook when called within a component:

The hook ensures that components do not attempt to render user-specific data when the session is invalid or loading.
Sources: src/hooks.ts:43-53

Data Structure

The hook returns a User object, which is strictly typed to match the WorkOS AuthKit user schema.

User Object Schema

Field	Type	Description
id	string	Unique identifier for the user
email	string	Primary email address
firstName	string | null	User's first name
lastName	string | null	User's last name
profilePictureUrl	string | null	URL to the user's avatar
createdAt	string	ISO timestamp of account creation
updatedAt	string	ISO timestamp of last update

Sources: src/types.ts:4-12

Relationship with Auth Architecture

The useUser hook is part of a larger ecosystem of hooks and utilities exported by the main entry point of the package.

The relationship between hooks ensures that useUser benefits from the shared state management of the underlying WorkOS provider.
Sources: src/hooks.ts:18-53, src/index.ts:1-3

Usage Requirements

For the useUser hook to function correctly, the application must meet the following architectural requirements:

1. Client-Side Environment: The hook is marked with the 'use client' directive and must be used within React Client Components.
2. Provider Wrapping: The application must be wrapped in the AuthKitProvider from @workos-inc/authkit-nextjs.
3. Authentication Guard: It should ideally be used in routes protected by the createAuthMiddleware or within logic that has already verified the session.

Example Implementation

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

export function DashboardHeader() {
  const user = useUser(); // Throws if not signed in
  return <h1>Welcome, {user.firstName}</h1>;
}

Sources: src/hooks.ts:1, README.md:46-54, package.json:23-27

Summary

The useUser hook provides a type-safe and assertion-guaranteed method for accessing user data in PCSTYLE services. By leveraging the @workos-inc/authkit-nextjs peer dependency and internal state validation, it simplifies the development of protected UI components by removing the need for repetitive conditional checks against null user states.