reactive/data-client / .agents/skills/data-client-graphql-setup
data-client-graphql-setup
VerifiedSet up @data-client/graphql for GraphQL APIs. Configures GQLEndpoint with auth and custom options. Use after data-client-setup detects GraphQL patterns.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.9 KB |
| references.json | config | 104 B |
| references/auth.md | markdown | 1.9 KB |
SKILL.md
View on GitHub---
name: data-client-graphql-setup
description: Set up @data-client/graphql for GraphQL APIs. Configures GQLEndpoint with auth and custom options. Use after data-client-setup detects GraphQL patterns.
disable-model-invocation: true
---
# 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:
```bash
# 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):
```ts
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:
```ts
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:
```ts
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
```ts
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
```ts
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
```ts
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
```tsx
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
- [GQLEndpoint](https://dataclient.io/graphql/api/GQLEndpoint) - Full GQLEndpoint API
- [GraphQL Guide](https://dataclient.io/graphql) - GraphQL usage guide
- [Authentication Guide](references/auth.md) - Cookies and tokens on GraphQL requests
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |