Skip to content

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

data-client-setup

Verified

Install and set up @data-client/react or @data-client/vue in a project. Detects project type (NextJS, Expo, React Native, Vue, plain React) and protocol (REST, GraphQL, custom), then follows the bundled protocol-specific setup guide.

FileKindSize
SKILL.mdskill md13.9 KB
evals/evals.jsonconfig12.6 KB
references.jsonconfig523 B
references/DataClientPlugin.mdmarkdown6.6 KB
references/DataProvider.mdmarkdown6.6 KB
references/data-client-endpoint-setup.mdmarkdown8.5 KB
references/data-client-endpoint-setup/references/Endpoint.mdmarkdown20.9 KB
references/data-client-endpoint-setup/references/Endpoint.vue.mdmarkdown20.5 KB
references/data-client-graphql-setup.mdmarkdown4.8 KB
references/data-client-graphql-setup/references/auth.mdmarkdown1.9 KB
references/data-client-rest-setup.mdmarkdown7.6 KB
references/data-client-rest-setup/references/RestEndpoint.mdmarkdown45.2 KB
references/data-client-rest-setup/references/RestEndpoint.vue.mdmarkdown46.1 KB
references/data-client-rest-setup/references/auth.mdmarkdown9.4 KB
references/data-client-rest-setup/references/auth.vue.mdmarkdown9.7 KB
references/data-client-rest-setup/references/axios-migration.mdmarkdown25.4 KB
references/data-client-rest-setup/references/axios-migration.vue.mdmarkdown25.5 KB
references/data-client-rest-setup/references/django.mdmarkdown2.3 KB
references/data-client-rest-setup/references/fetch-migration.mdmarkdown4.0 KB
references/data-client-rest-setup/references/got-migration.mdmarkdown4.5 KB
references/data-client-rest-setup/references/hookifyResource.mdmarkdown6.0 KB
references/data-client-rest-setup/references/hookifyResource.vue.mdmarkdown6.3 KB
references/data-client-rest-setup/references/ky-migration.mdmarkdown3.9 KB
references/data-client-rest-setup/references/resource.mdmarkdown27.0 KB
references/data-client-rest-setup/references/resource.vue.mdmarkdown27.1 KB
references/data-client-rest-setup/references/superagent-migration.mdmarkdown4.1 KB
references/getDefaultManagers.mdmarkdown6.1 KB
references/getDefaultManagers.vue.mdmarkdown3.8 KB
references/installation.mdmarkdown4.0 KB
references/installation.vue.mdmarkdown2.7 KB
references/tanstack-query-migration.mdmarkdown31.1 KB

references/data-client-graphql-setup.md

View on GitHub
<!-- Generated by `yarn build:skills` from .agents/skills/data-client-graphql-setup/SKILL.md. Edit the source, not this file. -->

# 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](./data-client-graphql-setup/references/auth.md) - Cookies and tokens on GraphQL requests
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall