Skip to main content
This guide will help you integrate WellPlayed into your React application and authenticate your first user.

​
Prerequisites

Before you begin, make sure you have:
  • A React application (v19+ recommended)
  • Node.js 18 or higher
  • An account on WellPlayed Console

​
Get Your Credentials

1

Create an Organization

Sign in to the WellPlayed Console and create an organization if you haven’t already. Note your Organization ID from the dashboard.
2

Create an Application

Navigate to the Apps section and create a new application. Configure:
  • Application Name: Your app’s name
  • Redirect URIs: Add http://localhost:3000/login for development
  • Allowed Origins: Add http://localhost:3000 for CORS
Save your Client ID - you’ll need it for the SDK configuration.
Keep your Organization ID and Client ID secure. Never commit them directly to version control. Use environment variables instead.

​
Installation

1

Install the React SDK

Install the WellPlayed React SDK package:
npm install @well-played.gg/react-sdk
The React SDK automatically includes the TypeScript SDK as a dependency.
2

Install Peer Dependencies

Ensure you have React 19+ installed:
npm install react@^19.0.0 react-dom@^19.0.0

​
Setup the Provider

1

Wrap Your App with WellPlayedProvider

Import the WellPlayedProvider and wrap your application. This component handles authentication, Apollo Client setup, and provides the WellPlayed context.
src/main.tsx
import { WellPlayedProvider } from "@well-played.gg/react-sdk";
import React from "react";
import { createRoot } from "react-dom/client";
import { RouterProvider, createBrowserRouter } from "react-router-dom";
import { App } from "./App";

const router = createBrowserRouter([
  {
    path: "",
    element: <App />,
  },
]);

const Root = () => (
  <WellPlayedProvider
    organizationId="vHFLeYcHvCJS4fmZW4uDrN" // Replace with your organizationId
    wpAppConfig={{
      scope: "offline_access",
      client_id: "9e53e218-d77d-48fd-8bd3-2c4f597b94ef", // Replace with your client_id
      redirect_uri: `${window.location.origin}/login`,
    }}
  >
    <RouterProvider router={router} />
  </WellPlayedProvider>
);

const root = createRoot(document.getElementById("root")!);
root.render(<Root />);
2

Understanding the Configuration

The WellPlayedProvider accepts several props:
  • organizationId (required): Your organization ID from the WellPlayed Console
  • wpAppConfig (required): Application configuration object:
    • client_id: Your application’s client ID
    • redirect_uri: Where users return after authentication (must match console config)
    • scope: OAuth scopes - use "offline_access" to enable token refresh
  • apiBaseUrl (optional): API environment - defaults to "well-played.gg", use "stg.well-played.gg" for staging
  • clientConfig (optional): Advanced Apollo Client configuration
  • oidcConfig (optional): Additional OIDC provider settings
The redirect_uri must include a path segment (e.g., /login). Using just the origin will cause an error. This path doesn’t need to exist as a route - the OIDC library handles the callback automatically.

​
Authenticate a User

Now let’s add authentication to your app using the useConnectedPlayer hook.
1

Create Your App Component

Use the useConnectedPlayer hook to access authentication state and user data:
src/App.tsx
import { useConnectedPlayer } from "@well-played.gg/react-sdk";
import React from "react";

export const App = () => {
  const { authenticated, login, logout, data, loading } = useConnectedPlayer();

  if (loading) {
    return <div>Loading...</div>;
  }

  if (!authenticated) {
    return (
      <div>
        <h1>Welcome to WellPlayed</h1>
        <button onClick={() => login()}>Sign In</button>
      </div>
    );
  }

  return (
    <div>
      <h1>Welcome, {data?.getMyAccount?.profiles[0]?.username}!</h1>
      <button onClick={() => logout()}>Sign Out</button>
      
      <div>
        <h2>Your Profile</h2>
        <pre>{JSON.stringify(data?.getMyAccount, null, 2)}</pre>
      </div>
    </div>
  );
};
2

Test Authentication

Run your application and click the “Sign In” button:
npm run dev
You’ll be redirected to the WellPlayed authentication page. After signing in, you’ll return to your app with the user’s profile data.

​
Fetch Player Data

Let’s extend the example to fetch multiple player profiles using the usePlayers hook.
src/PlayerList.tsx
import { usePlayers } from "@well-played.gg/react-sdk";
import React from "react";

export const PlayerList = () => {
  const { results, loading, refetch } = usePlayers({
    playerIds: ["player-id-1", "player-id-2", "player-id-3"],
  });

  if (loading) {
    return <div>Loading players...</div>;
  }

  return (
    <div>
      <h2>Players</h2>
      <ul>
        {results.map((player) => (
          <li key={player.id}>
            <strong>{player.username}</strong>
            {player.identities.map((identity) => (
              <div key={identity.providerId}>
                {identity.providerId}:
                {identity.properties.map((prop) => (
                  <span key={prop.property}>
                    {prop.property} = {prop.value}
                  </span>
                ))}
              </div>
            ))}
          </li>
        ))}
      </ul>
      <button onClick={() => refetch(["player-id-1", "player-id-2"])}>Refresh</button>
    </div>
  );
};
The usePlayers hook automatically handles pagination and batching. It fetches up to 100 players per request and combines the results.

​
Access the GraphQL Client

For advanced use cases, you can access the underlying Apollo Client or typed client:
src/CustomQuery.tsx
import { useWellPlayed, graphql } from "@well-played.gg/react-sdk";
import { useQuery } from "@apollo/client";
import React from "react";

const GET_TOURNAMENT_QUERY = graphql(`
  query getTournament($id: ID!) {
    tournament(id: $id) {
      id
      name
      status
    }
  }
`);

export const TournamentDetails = ({ tournamentId }: { tournamentId: string }) => {
  const { apiClient } = useWellPlayed();
  const { data, loading } = useQuery(GET_TOURNAMENT_QUERY, {
    client: apiClient,
    variables: { id: tournamentId },
  });

  if (loading) return <div>Loading tournament...</div>;

  return (
    <div>
      <h2>{data?.tournament?.name}</h2>
      <p>Status: {data?.tournament?.status}</p>
    </div>
  );
};

​
What’s Available in the Context

The useWellPlayed hook provides access to: 
const {
  organizationId,    // Your organization ID
  apiClient,         // Apollo Client instance
  typedClient,       // Typed GraphQL client
  accessToken,       // Current OAuth access token
} = useWellPlayed();
Source: wp.provider.tsx:86-94

​
Next Steps

Explore React Hooks

Learn about all available hooks for tournaments, teams, and players

Tournament Guide

Build a complete tournament bracket system

TypeScript SDK

Use the typed client for server-side or non-React applications

API Reference

Browse the complete API documentation

​
Common Issues

Make sure your redirect_uri includes a path segment:
// ❌ Wrong
redirect_uri: window.location.origin

// ✅ Correct
redirect_uri: `${window.location.origin}/login`
Ensure your component is rendered inside the WellPlayedProvider:
// ✅ Correct structure
<WellPlayedProvider ...>
  <App /> {/* Can use useWellPlayed here */}
</WellPlayedProvider>
Verify that you’ve added your application’s origin to the Allowed Origins list in the WellPlayed Console app configuration.
Make sure you include offline_access in the scope:
wpAppConfig={{
  scope: "offline_access",  // Required for token refresh
  // ...
}}
For more examples and advanced usage patterns, check out the demo application in the SDK repository.

Build docs developers (and LLMs) love

Get started for freeTalk to us