AuthKitProvider

Relevant source files

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

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

AuthKitProvider is a foundational React component provided by @workos-inc/authkit-nextjs and utilized by the @pcstyle/auth SDK to enable authentication state management across PCSTYLE applications. It acts as the context provider that wraps the application's component tree, allowing both server-side and client-side components to access session data, user profiles, and authentication status.

The provider integrates directly with WorkOS AuthKit to handle session persistence and synchronization across subdomains, specifically supporting the .pcstyle.dev ecosystem. By wrapping the root layout with this provider, developers can leverage custom hooks like useAuth() to consume authentication state throughout their application.

Sources: README.md:42-53, src/types.ts:60-65, package.json:34

Architecture and Integration

The AuthKitProvider serves as the entry point for authentication context. It is typically implemented in the root layout of a Next.js application to ensure that the entire component tree has access to the authentication state.

Component Hierarchy

The following diagram illustrates how AuthKitProvider wraps the application structure and enables hooks to access the shared state:

The provider maintains the connection to the WorkOS session, which is then accessed by consumption hooks.
Sources: README.md:45-53, src/hooks.ts:16-29

Environment Dependency

The behavior of the provider and the underlying authentication system is governed by specific environment variables that must be configured at the project level.

Variable	Description	Requirement
WORKOS_API_KEY	Secret key for WorkOS API access.	Required
WORKOS_CLIENT_ID	The Client ID for the AuthKit project.	Required
WORKOS_COOKIE_PASSWORD	Encryption key for session cookies (min 32 chars).	Required
WORKOS_COOKIE_DOMAIN	The domain scope for auth cookies (e.g., .pcstyle.dev).	Required

Sources: README.md:12-20, src/types.ts:60-65

Usage and Implementation

Implementation in Root Layout

To initialize authentication, the AuthKitProvider must be imported from the peer dependency @workos-inc/authkit-nextjs/components and wrapped around the body content in the main layout file.

// Example from README.md
import { AuthKitProvider } from '@workos-inc/authkit-nextjs/components';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <AuthKitProvider>{children}</AuthKitProvider>
      </body>
    </html>
  );
}

Sources: README.md:42-53, package.json:34

Consuming the Provider State

The @pcstyle/auth library provides simplified hooks to interact with the context established by the AuthKitProvider.

• useAuth(): Returns an AuthState object containing user, isLoading, and isAuthenticated.
• useUser(): A convenience hook that returns the current User object or throws an error if the user is not authenticated.

This flow shows how client components retrieve state from the provider initialized at the root.
Sources: src/hooks.ts:16-52, src/types.ts:17-21

Data Structures

The provider manages and exposes data adhering to specific TypeScript interfaces defined within the SDK.

User Object

The User type represents the profile information synchronized through the provider.

Field	Type	Description
id	string	Unique identifier from WorkOS.
email	string	User's 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 user creation.

Sources: src/types.ts:4-12

Auth State

The internal state tracked by the provider and exposed to the application.

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

Sources: src/types.ts:17-21, src/hooks.ts:24-28

Relationship with Middleware

While AuthKitProvider manages client-side and component-level state, it works in tandem with the createAuthMiddleware. The middleware handles server-side session validation and redirects before the provider is even rendered on the client.

The middleware ensures the session exists before the AuthKitProvider initializes the local state.
Sources: src/middleware.ts:24-30, README.md:25-39

Summary

AuthKitProvider is the essential context layer for the PCSTYLE authentication ecosystem. By integrating WorkOS AuthKit into the Next.js component tree, it provides a unified way to manage user sessions and profile data. It relies on a properly configured environment and works alongside server-side middleware to ensure a secure and seamless authentication experience across all .pcstyle.dev subdomains.