Project File Structure

Relevant source files

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

• package.json
• README.md
• tsup.config.ts
• src/index.ts
• src/middleware.ts
• src/hooks.ts
• src/types.ts
• src/convex.ts
• tsconfig.json

The @pcstyle/auth repository is a unified authentication SDK designed for PCSTYLE services, leveraging WorkOS AuthKit as the underlying provider. The project is structured as a TypeScript-based library that exports multiple entry points for different environments, including Next.js middleware, React hooks for client-side authentication, and configuration utilities for Convex integration.

The repository follows a modern JavaScript/TypeScript project layout, utilizing tsup for bundling and providing high-level abstractions over WorkOS to ensure consistent authentication across various subdomains (e.g., .pcstyle.dev).

Sources: package.json:1-5, README.md:1-5, tsup.config.ts:4-8

Core Architectural Components

The project is divided into specialized modules that handle specific aspects of the authentication lifecycle. This modularity is enforced through the build configuration, which defines three primary entry points.

This diagram illustrates the high-level organization of the repository's source code and configuration files.
Sources: tsup.config.ts:4-8, src/index.ts:1-10, tsconfig.json:1-24

Library Entry Points

The package exports multiple sub-paths to allow consumers to import only the necessary logic for their specific environment.

Entry Point	Source File	Description
. (Main)	src/index.ts	Exports core types and React hooks for general app use.
./middleware	src/middleware.ts	Contains Next.js middleware factories for route protection.
./convex	src/convex.ts	Provides JWT provider configuration for Convex backends.

Sources: package.json:9-25, tsup.config.ts:4-8

Detailed File Analysis

1. Build and Configuration Logic

The project uses tsup to generate both CommonJS (.js) and ESM (.mjs) formats, along with TypeScript declaration files (.d.ts).

• package.json: Defines peer dependencies on @workos-inc/authkit-nextjs, next, and react. It also maps the conditional exports for the different entry points mentioned above.
• tsup.config.ts: Configures the bundler to treat react, next, and @workos-inc/authkit-nextjs as external dependencies to avoid bundling them into the SDK.
• tsconfig.json: Sets the target to ES2020 and ensures compatibility with React JSX.

Sources: package.json:28-32, tsup.config.ts:9-15, tsconfig.json:4-16

2. Source Code (src/)

React Hooks (src/hooks.ts)

This file implements client-side authentication state management by wrapping the WorkOS useAuth hook.

• useAuth(): Returns an AuthState object containing user, isLoading, and isAuthenticated.
• useUser(): A convenience hook that returns the current user or throws an error if the user is not authenticated.
• getSignInUrl(returnTo?): Generates a URL for the PCSTYLE auth portal, optionally encoding a return path in the state parameter using Base64.

Sources: src/hooks.ts:16-56

Middleware (src/middleware.ts)

Handles server-side route protection within Next.js applications.

• createAuthMiddleware(options?): Wraps authkitMiddleware from WorkOS. It allows developers to specify publicPaths which bypass authentication.
• matcherConfig: A recommended Next.js matcher configuration that excludes static assets and internal Next.js paths.

Sources: src/middleware.ts:19-41

Convex Integration (src/convex.ts)

Facilitates authentication between the frontend and the Convex database.

• createConvexAuthConfig(clientId): Generates a configuration object for Convex's auth.config.ts. It sets up two customJwt providers: one for the standard WorkOS issuer and one for the User Management specific issuer.

Sources: src/convex.ts:12-36

Data Models and Types

The src/types.ts file defines the standard data structures used across the SDK.

This class diagram represents the core interfaces used for representing user identity and authentication state.
Sources: src/types.ts:4-58

Configuration Defaults

The SDK assumes a standard environment within the PCSTYLE ecosystem, defined by the following defaults:

Property	Default Value	Context
authDomain	https://auth.pcstyle.dev	Global auth portal
cookieDomain	.pcstyle.dev	For cross-subdomain sessions
issuer	https://api.workos.com/	JWT Verification

Sources: src/types.ts:60-75, src/convex.ts:20-22

Authentication Flow

The following sequence diagram illustrates how a protected route is handled via the middleware and hooks defined in the file structure.

The flow shows the interaction between the middleware logic and the React hooks logic.
Sources: src/middleware.ts:19-30, src/hooks.ts:16-30, README.md:31-65

Summary

The @pcstyle/auth project structure is designed to provide a unified interface for authentication across the PCSTYLE platform. By separating the logic into specific entry points (index, middleware, and convex), the project ensures that developers can easily integrate authentication into various parts of their stack while maintaining a single source of truth for types and configuration.