Navigation Helpers

Relevant source files

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

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

Navigation Helpers in the @pcstyle/auth SDK provide a standardized way to manage user redirects and URL generation for authentication flows. These utilities ensure that users are directed to the centralized authentication domain (auth.pcstyle.dev) for signing in and out, while maintaining state for seamless redirection back to the originating application.

The helpers primarily consist of functional utilities that generate URLs for authentication transitions and middleware configurations that control access to specific application paths based on the user's authentication status.

Sources: src/hooks.ts:47-66, README.md:1-10

Authentication URL Generation

The SDK provides specialized functions to generate URLs for sign-in and sign-out operations. These functions target the centralized PCSTYLE authentication service.

Sign-In URL and State Management

The getSignInUrl function generates a link to the authentication portal. It supports an optional returnTo parameter, which is encoded into a Base64 string and passed as a state query parameter. This allows the authentication server to redirect the user back to their original location after a successful login.

The diagram shows the logic for generating a sign-in URL with state persistence.
Sources: src/hooks.ts:54-66

Sign-Out URL

The getSignOutUrl function provides a static endpoint for terminating the user session across the PCSTYLE domain.

Function	Return Type	Target URL	Description
getSignInUrl(returnTo?)	string	https://auth.pcstyle.dev	Generates URL with optional Base64 encoded return path.
getSignOutUrl()	string	https://auth.pcstyle.dev/signout	Generates the standard sign-out endpoint URL.

Sources: src/hooks.ts:47-66, README.md:73-80

Middleware Navigation Control

Navigation is also managed at the infrastructure level via Next.js middleware. This component intercepts requests and determines if a user should be allowed to proceed or be redirected to a login flow.

Public vs. Protected Paths

The createAuthMiddleware function allows developers to define publicPaths. Requests to these paths bypass the mandatory authentication check, while all other matched paths trigger the WorkOS AuthKit navigation logic.

The flow of request handling within the auth middleware.
Sources: src/middleware.ts:18-30, src/types.ts:25-30

Configuration Options

The middleware behavior is influenced by the AuthMiddlewareOptions structure:

Option	Type	Default	Description
publicPaths	string[]	[]	List of routes that do not require an active session.
signInUrl	string	https://auth.pcstyle.dev	The destination for unauthenticated users.
redirectUri	string	https://auth.pcstyle.dev/callback	The OAuth callback target.

Sources: src/types.ts:25-45, src/middleware.ts:18-30

Implementation Examples

Client-Side Redirection

In client components, these helpers are used to create navigation links or triggers.

'use client';
import { getSignInUrl, getSignOutUrl } from '@pcstyle/auth';

export function AuthLinks() {
  return (
    <div>
      <a href={getSignInUrl('/dashboard')}>Log In to Dashboard</a>
      <a href={getSignOutUrl()}>Log Out</a>
    </div>
  );
}

Sources: src/hooks.ts:47-66, src/index.ts:1-3

Middleware Setup

Configuring the middleware to handle automatic navigation for protected routes.

import { createAuthMiddleware } from '@pcstyle/auth/middleware';

export default createAuthMiddleware({
  publicPaths: ['/api/health', '/about'],
});

Sources: src/middleware.ts:7-25, README.md:25-35

Summary

Navigation Helpers in @pcstyle/auth facilitate a unified login experience across subdomains by centralizing URL generation and request interception. By utilizing Base64 state encoding for returns and configurable middleware for path protection, the SDK ensures consistent user movement between application features and the authentication service.