Skip to content

reactive/data-client / .agents/skills/data-client-graphql-setup

data-client-graphql-setup

Verified

Set up @data-client/graphql for GraphQL APIs. Configures GQLEndpoint with auth and custom options. Use after data-client-setup detects GraphQL patterns.

GraphQL Protocol Setup

This guide configures @data-client/graphql for a project. Use it once the Data Client provider is set up and the project calls GraphQL APIs.

Installation

Install the GraphQL package alongside the core package:

# npm
npm install @data-client/graphql

# yarn
yarn add @data-client/graphql

# pnpm
pnpm add @data-client/graphql

GQLEndpoint Setup

Basic Configuration

Create a file at src/api/gql.ts (or similar):

import { GQLEndpoint } from '@data-client/graphql';

export const gql = new GQLEndpoint('/graphql');

Detection Checklist

Scan the existing codebase for GraphQL patterns:

  1. GraphQL endpoint URL: Look for /graphql or custom paths
  2. Authentication: Check for auth headers in existing GraphQL client setup
  3. Custom headers: API keys, tenant IDs, etc.
  4. Error handling: GraphQL error parsing patterns

With Authentication

getHeaders() runs synchronously, so it can add a token that is already in memory:

import { GQLEndpoint } from '@data-client/graphql';

export const gql = new GQLEndpoint('/graphql', {
  getHeaders(headers: HeadersInit): HeadersInit {
    const token = localStorage.getItem('authToken');
    return token ? { ...headers, Authorization: `Bearer ${token}` } : headers;
  },
});

Async Authentication and Error Handling

If the token must be awaited (for example, refreshed), override fetchResponse() in a subclass. GraphQL errors in a response reject with GQLNetworkError, whose errors holds the response's errors array:

import { GQLEndpoint, GQLNetworkError } from '@data-client/graphql';

class AuthGQLEndpoint extends GQLEndpoint<any> {
  async fetchResponse(input: RequestInfo, init: RequestInit) {
    const headers = new Headers(init.headers);
    headers.set('Authorization', `Bearer ${await getValidToken()}`);
    try {
      return await super.fetchResponse(input, { ...init, headers });
    } catch (error) {
      if (
        error instanceof GQLNetworkError &&
        error.errors.some((e: any) => e.extensions?.code === 'UNAUTHENTICATED')
      ) {
        window.dispatchEvent(new CustomEvent('auth:expired'));
      }
      throw error;
    }
  }
}

export const gql = new AuthGQLEndpoint('/graphql');

Defining Queries and Mutations

The second argument of gql.query() and gql.mutation() is the schema, shaped like the response's data: a query for user { ... } takes { user: User }, and the component reads .user. The schema normalizes each response into the shared cache, and the examples below import Entity classes that must already exist. Apply the skill "data-client-schema" to define them before writing endpoints.

Query Example

import { gql } from './gql';
import { User } from '../schemas/User';

export const getUser = gql.query(
  (v: { id: string }) => `
    query GetUser($id: ID!) {
      user(id: $id) {
        id
        name
        email
      }
    }
  `,
  { user: User },
);

Mutation Example

import { gql } from './gql';
import { User } from '../schemas/User';

export const updateUser = gql.mutation(
  (v: { id: string; name: string }) => `
    mutation UpdateUser($id: ID!, $name: String!) {
      updateUser(id: $id, name: $name) {
        id
        name
      }
    }
  `,
  { updateUser: User },
);

With Collection

import { gql } from './gql';
import { UserCollection } from '../schemas/User';

export const listUsers = gql.query(
  `
    query ListUsers {
      users {
        id
        name
        email
      }
    }
  `,
  { users: UserCollection },
);

export const createUser = gql.mutation(
  (v: { name: string; email: string }) => `
    mutation CreateUser($name: String!, $email: String!) {
      createUser(name: $name, email: $email) {
        id
        name
        email
      }
    }
  `,
  { createUser: UserCollection.push },
);

Usage in Components

import { useSuspense, useController } from '@data-client/react';
import { getUser, updateUser } from './api/users';

function UserProfile({ id }: { id: string }) {
  const { user } = useSuspense(getUser, { id });
  const ctrl = useController();

  const handleUpdate = async (name: string) => {
    await ctrl.fetch(updateUser, { id, name });
  };

  return (
    <div>
      <h1>{user.name}</h1>
      <button onClick={() => handleUpdate('New Name')}>Update</button>
    </div>
  );
}

Next Steps

Apply skill "data-client-react" or "data-client-vue" for usage.

References

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall