Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
The @pcstyle/auth SDK provides a unified authentication solution for PCSTYLE services, built on top of WorkOS AuthKit. It facilitates seamless session management, protected routing via middleware, and integration with third-party services like Convex.
This guide covers the installation, environment configuration, and implementation of authentication hooks and middleware within a Next.js environment.
Sources: README.md:1-5, package.json:1-10
Installation and Configuration
Package Installation
To begin, install the SDK alongside its peer dependency, @workos-inc/authkit-nextjs. The project uses bun as the preferred package manager.
Sources: README.md:9-11, package.json:23-27
Environment Variables
Authentication requires specific WorkOS credentials. The WORKOS_COOKIE_PASSWORD must be at least 32 characters and remain consistent across all subdomains to ensure cross-subdomain authentication works correctly.
| Variable | Description | Default/Value |
|---|---|---|
WORKOS_API_KEY | WorkOS Secret API Key | sk_... |
WORKOS_CLIENT_ID | WorkOS Client Identifier | client_... |
WORKOS_COOKIE_PASSWORD | Password for cookie encryption | <32+ chars> |
WORKOS_COOKIE_DOMAIN | Domain for shared cookies | .pcstyle.dev |
Sources: README.md:15-21, src/types.ts:69-78
Core Implementation
Middleware Configuration
The SDK provides createAuthMiddleware to handle route protection. It allows developers to define publicPaths that bypass authentication requirements.
The middleware logic determines access based on path matching and authentication status.
Sources: src/middleware.ts:20-28, src/types.ts:34-40
Application Setup
The application must be wrapped in the AuthKitProvider within the root layout to provide authentication context to client components.
Sources: README.md:39-50
Client-Side Authentication
Auth Hooks
The SDK exposes two primary React hooks for managing authentication state in the browser:
useAuth(): Returns the current state, including the user object, loading status, and authentication flag.useUser(): A convenience hook that returns the user object directly or throws an error if the user is not authenticated.
Sequence of data retrieval for client-side authentication states.
Sources: src/hooks.ts:18-32, src/hooks.ts:42-51
Navigation Helpers
Helpers are provided to generate standardized URLs for authentication flows across the PCSTYLE ecosystem.
| Function | Return Value / Behavior |
|---|---|
getSignInUrl(returnTo?) | Returns https://auth.pcstyle.dev with optional encoded state for redirection. |
getSignOutUrl() | Returns https://auth.pcstyle.dev/signout. |
Sources: src/hooks.ts:56-72
External Integrations
Convex Auth Configuration
For services using Convex as a backend, the SDK provides a utility to generate the necessary JWT provider configuration. This validates WorkOS tokens using RS256 algorithms.
The configuration includes providers for both standard WorkOS API and User Management endpoints.
Sources: src/convex.ts:12-34
Data Models
User Types
The SDK defines structured types for both the raw WorkOS user and the internal Convex user representation.
| Interface | Fields | Source |
|---|---|---|
User | id, email, firstName, lastName, profilePictureUrl, createdAt, updatedAt | src/types.ts:4-12 |
ConvexUser | _id, authId, email, name, avatarUrl, role, createdAt, updatedAt | src/types.ts:46-55 |
Summary
The @pcstyle/auth SDK streamlines the integration of WorkOS into Next.js applications by providing pre-configured middleware, typed hooks, and specialized configurations for Convex. By centralizing the authentication domain at auth.pcstyle.dev and sharing cookies across .pcstyle.dev, it enables a unified login experience across the entire service platform.
Sources: README.md:1-5, src/types.ts:74-78