GraphQL Protocol Setup

This skill configures @data-client/graphql for a project. It should be applied after data-client-setup detects GraphQL patterns.

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:

• GraphQL endpoint URL: Look for /graphql or custom paths

• Authentication: Check for auth headers in existing GraphQL client setup

• Custom headers: API keys, tenant IDs, etc.

• Error handling: GraphQL error parsing patterns

With Authentication

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

export const gql = new GQLEndpoint('/graphql', { getHeaders() { const token = localStorage.getItem('authToken'); return { 'Content-Type': 'application/json', ...(token && { Authorization: Bearer ${token} }), }; }, });

Async Authentication (token refresh)

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

export const gql = new GQLEndpoint('/graphql', { async getHeaders() { const token = await getValidToken(); return { 'Content-Type': 'application/json', Authorization: Bearer ${token}, }; }, });

Custom Error Handling

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

class CustomGQLEndpoint extends GQLEndpoint { async fetchResponse(input: RequestInfo, init: RequestInit): Promise<any> { const response = await super.fetchResponse(input, init);

// Handle GraphQL errors
if (response.errors?.length) {
  const authError = response.errors.find(
    e => e.extensions?.code === 'UNAUTHENTICATED'
  );
  if (authError) {
    window.dispatchEvent(new CustomEvent('auth:expired'));
  }
}

return response;

} }

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

Defining Queries and Mutations

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 } } , { schema: 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 } } , { schema: User }, );

With Collection

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

export const listUsers = gql.query( () => query ListUsers { users { id name email } } , { schema: 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 } } , { schema: 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-schema" to define Entity classes

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

References

• GQLEndpoint - Full GQLEndpoint API

• GraphQL Guide - GraphQL usage guide

• Authentication Guide - Auth patterns for GraphQL