@woographql/session-utils

Managing session state in headless WooCommerce applications involves juggling multiple tokens with different purposes and expiration times. @woographql/session-utils simplifies this complexity by providing a unified interface for token lifecycle management.

WooGraphQL applications need to manage several tokens:

Each token has different:

• Storage requirements (some persistent, some session-only)
• Renewal mechanisms
• Validation rules

WPGraphQL for WooCommerce supports two different session token systems:

Which should you use?

• Use the Store-API Cart Token (cartToken) - recommended for all projects, especially if using NextPress to render WordPress/Gutenberg content containing WooCommerce Blocks. The legacy token is not fully supported by WooCommerce Blocks.
• Use the Legacy Session Token (sessionToken) only if you already have an existing application using it without NextPress, and you don't have the time or resources to migrate.

See Understanding Session Tokens for detailed information about each token type.

The TokenManager class handles all of this automatically:

import { TokenManager, SessionBehavior } from '@woographql/session-utils';

const tokenManager = new TokenManager({
  ID: 'my-store',
  behavior: [SessionBehavior.withAuth, SessionBehavior.withClientSession],
  startSession: async () => { /* fetch initial session */ },
  updateSession: async () => { /* update session */ },
  refreshAuthToken: async () => { /* refresh auth token */ },
});

• Automatic Token Renewal: Auth tokens are refreshed before expiration
• Lazy Initialization: Session starts only when needed
• Flexible Storage: Uses localStorage and sessionStorage with customization options
• Multiple Behaviors: Support for guest-only, authenticated-only, or both
• Session Handoff: Generate URLs for WordPress session pass-off

Configure how your application handles different user types:

@woographql/session-utils is designed to work with:

• @woographql/react-hooks - Provides the session context for React applications
• @woographql/next - Pre-configured token managers for Next.js

Get started by following the Getting Started guide.