Skip to main content

​
Overview

The createWellPlayedClient function creates a fully configured Apollo Client instance for the WellPlayed GraphQL API. It supports queries, mutations, subscriptions (via WebSockets), SSR, application authentication, and advanced caching. This client is ideal for React applications using Apollo hooks or any JavaScript environment requiring advanced GraphQL features.

​
Function Signature

export const createWellPlayedClient = ({
  token,
  organizationId,
  invalidationPolicies,
  handlers,
  fetchPolicy,
  websocket,
  apiBaseUrl,
  ssr,
  application,
}: ClientProps) => ApolloClient
Defined in packages/typescript-sdk/src/apollo.ts:80

​
Parameters

​
organizationId
string
required
The organization ID to use for all requests. This header is sent with every GraphQL operation.
​
token
string
The authentication token to use for the client. When provided, sent as Bearer <token> in the Authorization header.Mutually exclusive with application - use either user token OR application credentials, not both.
​
application
object
Application credentials for server-side authentication. The client will automatically obtain and refresh access tokens using OAuth client credentials flow.
​
apiBaseUrl
ApiBaseUrl
The base URL environment to connect to.Type: "well-played.gg" | "stg.well-played.gg"Default: "well-played.gg"
​
ssr
boolean
Whether the client is running in Server-Side Rendering mode. When true:
  • Disables local storage cache persistence
  • Sets Apollo’s ssrMode option
  • Default: false
​
fetchPolicy
FetchPolicy
The default fetch policy for queries and watch queries.Type: Apollo’s FetchPolicy ("cache-first" | "cache-and-network" | "network-only" | "cache-only" | "no-cache" | "standby")Default: "network-only"
​
invalidationPolicies
InvalidationPolicies
Custom cache invalidation policies using @nerdwallet/apollo-cache-policies.
​
websocket
object
WebSocket configuration for GraphQL subscriptions.
​
handlers
object
Event handlers for errors and WebSocket lifecycle events.

​
Return Value

​
client
ApolloClient
A configured Apollo Client instance ready to execute GraphQL operations. The client includes:
  • HTTP link for queries and mutations
  • WebSocket link for subscriptions (automatically selected based on operation type)
  • Cache with invalidation policies
  • Default error policies and fetch policies

​
Examples

​
Basic Client (Browser)

import { createWellPlayedClient } from '@well-played.gg/typescript-sdk';

const client = createWellPlayedClient({
  organizationId: 'org_123456',
  token: 'user-jwt-token',
});

​
SSR Configuration (Next.js)

import { createWellPlayedClient } from '@well-played.gg/typescript-sdk';

const client = createWellPlayedClient({
  organizationId: 'org_123456',
  token: userToken, // from session/cookie
  ssr: true, // Disables localStorage persistence
  fetchPolicy: 'network-only',
});

​
Application Authentication (Server)

import { createWellPlayedClient } from '@well-played.gg/typescript-sdk';

const client = createWellPlayedClient({
  organizationId: 'org_123456',
  application: {
    clientId: process.env.WELLPLAYED_CLIENT_ID,
    clientSecret: process.env.WELLPLAYED_CLIENT_SECRET,
  },
  ssr: true,
});

​
With WebSocket Subscriptions

import { createWellPlayedClient } from '@well-played.gg/typescript-sdk';

const client = createWellPlayedClient({
  organizationId: 'org_123456',
  token: 'user-jwt-token',
  websocket: {
    lazy: true, // Connect only when subscription starts
  },
  handlers: {
    webSocket: {
      onConnected: (socket) => {
        console.log('WebSocket connected');
      },
      onClosed: (event) => {
        console.log('WebSocket closed:', event.code);
      },
      onError: (error) => {
        console.error('WebSocket error:', error);
      },
    },
  },
});

​
With Error Handling and Cache Configuration

import { createWellPlayedClient } from '@well-played.gg/typescript-sdk';
import { RenewalPolicy } from '@nerdwallet/apollo-cache-policies';

const client = createWellPlayedClient({
  organizationId: 'org_123456',
  token: 'user-jwt-token',
  fetchPolicy: 'cache-and-network',
  invalidationPolicies: {
    timeToLive: 300000, // 5 minutes
    renewalPolicy: RenewalPolicy.WriteOnly,
  },
  handlers: {
    onError: ({ graphQLErrors, networkError }) => {
      if (graphQLErrors) {
        graphQLErrors.forEach(({ message, locations, path }) =>
          console.error(
            `[GraphQL error]: Message: ${message}, Location: ${locations}, Path: ${path}`
          )
        );
      }
      if (networkError) {
        console.error(`[Network error]: ${networkError}`);
      }
    },
  },
});

​
Staging Environment

import { createWellPlayedClient } from '@well-played.gg/typescript-sdk';

const client = createWellPlayedClient({
  organizationId: 'org_123456',
  token: 'user-jwt-token',
  apiBaseUrl: 'stg.well-played.gg',
});

​
Implementation Details

​
API Endpoints

The client constructs the following URLs based on apiBaseUrl:
  • GraphQL HTTP: https://api.warrior.{apiBaseUrl}/graphql
  • GraphQL WebSocket: wss://api.warrior.{apiBaseUrl}/graphql
  • OAuth: https://oauth.warrior.{apiBaseUrl}

​
Cache Persistence

When ssr: false (default), the client uses apollo3-cache-persist to synchronously persist the cache to localStorage. This provides offline-first capabilities and faster subsequent page loads.

​
Operation Routing

The client uses Apollo’s split to route operations:
  • Subscriptions → WebSocket link
  • Queries & Mutations → HTTP link
Routing is determined automatically based on the operation type in your GraphQL document.

Build docs developers (and LLMs) love

Get started for freeTalk to us