Environment Variables

Relevant source files

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

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

Environment variables serve as the core configuration mechanism for the @pcstyle/auth SDK. They enable secure communication with WorkOS services and ensure consistent session management across the PCSTYLE ecosystem, particularly for cross-subdomain authentication.

These variables are required to initialize the underlying @workos-inc/authkit-nextjs library and to configure third-party integrations like Convex. Sources: README.md:12-21, src/convex.ts:1-25

Required Variables

The following variables must be defined in the application's environment (e.g., .env.local) to ensure the authentication flow operates correctly.

Variable	Description	Constraints
WORKOS_API_KEY	Private API key for WorkOS communication	Must be kept secret (sk_...)
WORKOS_CLIENT_ID	Public identifier for the WorkOS application	Required for Convex and Web flows
WORKOS_COOKIE_PASSWORD	Secret used to encrypt the session cookie	Must be 32+ characters
WORKOS_COOKIE_DOMAIN	The shared domain for session cookies	Typically .pcstyle.dev

Sources: README.md:14-21

Cross-Subdomain Configuration

A critical requirement for the PCSTYLE architecture is that WORKOS_COOKIE_PASSWORD must be identical across all services sharing the WORKOS_COOKIE_DOMAIN. This allows a session established on one subdomain (e.g., auth.pcstyle.dev) to be valid across other subdomains using the same SDK configuration. Sources: README.md:23-23, src/types.ts:74-78

Usage in System Components

Environment variables are consumed at different stages of the application lifecycle, from server-side middleware to backend database configurations.

1. Convex Backend Authentication

The WORKOS_CLIENT_ID is used to construct the JWT validation configuration for Convex. This ensures that the backend can verify tokens issued by WorkOS.

The createConvexAuthConfig function explicitly checks for the presence of this variable and throws an error if it is missing, preventing unauthenticated access due to misconfiguration. Sources: src/convex.ts:14-38

2. Middleware and Routing

While the middleware utilizes internal defaults from AuthMiddlewareOptions, the underlying authkitMiddleware consumes environment variables to handle redirects and session decryption. Sources: src/middleware.ts:1-35, src/types.ts:31-50

3. Client-Side Navigation

Client-side hooks use hardcoded defaults or configuration objects that mirror the environment setup to generate URLs for the authentication service.

Configuration Data Structures

The SDK defines internal interfaces that map to these environment configurations to ensure type safety.

export interface AuthConfig {
    /** The auth domain, default: 'https://auth.pcstyle.dev' */
    authDomain?: string;

    /** Cookie domain for cross-subdomain auth, default: '.pcstyle.dev' */
    cookieDomain?: string;
}

Sources: src/types.ts:71-82

Summary

The @pcstyle/auth system relies on a specific set of WorkOS environment variables to maintain a unified session across the .pcstyle.dev ecosystem. Proper synchronization of the WORKOS_COOKIE_PASSWORD across different deployments is the most critical step for ensuring seamless cross-subdomain authentication.