0
# Client Management
1

2
The Client is the central hub for GraphQL operations in @urql/core, managing active operations, state, and the exchange pipeline that processes requests and responses.
3

4
## Capabilities
5

6
### Client Creation
7

8
Create a new GraphQL client with configuration options.
9

10
```typescript { .api }
11
/**
12
 * Creates a new GraphQL client instance
13
 * @param options - Configuration options for the client
14
 * @returns Configured Client instance
15
 */
16
function createClient(options: ClientOptions): Client;
17

18
interface ClientOptions {
19
  /** Target URL for GraphQL API requests */
20
  url: string;
21
  /** Array of exchanges that form the processing pipeline */
22
  exchanges: Exchange[];
23
  /** Additional options for fetch requests */
24
  fetchOptions?: RequestInit | (() => RequestInit);
25
  /** Custom fetch function polyfill */
26
  fetch?: typeof fetch;
27
  /** Allow subscriptions via fetch instead of separate transport */
28
  fetchSubscriptions?: boolean;
29
  /** Enable React/Preact Suspense support */
30
  suspense?: boolean;
31
  /** Default request policy for operations */
32
  requestPolicy?: RequestPolicy;
33
  /** Use GET requests for queries */
34
  preferGetMethod?: boolean | 'force' | 'within-url-limit';
35
}
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import { createClient, cacheExchange, fetchExchange } from "@urql/core";
42

43
// Basic client setup
44
const client = createClient({
45
  url: "https://api.example.com/graphql",
46
  exchanges: [cacheExchange, fetchExchange],
47
});
48

49
// Client with custom fetch options
50
const authenticatedClient = createClient({
51
  url: "https://api.example.com/graphql",
52
  exchanges: [cacheExchange, fetchExchange],
53
  fetchOptions: () => ({
54
    headers: {
55
      authorization: `Bearer ${getAuthToken()}`,
56
    },
57
  }),
58
});
59

60
// Client with GET requests for queries
61
const cacheFriendlyClient = createClient({
62
  url: "https://api.example.com/graphql",
63
  exchanges: [cacheExchange, fetchExchange],
64
  preferGetMethod: 'within-url-limit',
65
});
66
```
67

68
### Client Class
69

70
The main Client class provides methods for executing GraphQL operations.
71

72
```typescript { .api }
73
class Client {
74
  /** Flag indicating if Suspense support is enabled */
75
  readonly suspense: boolean;
76

77
  /** Create an operation from a request and context */
78
  createRequestOperation<Data = any, Variables extends AnyVariables = AnyVariables>(
79
    kind: OperationType,
80
    request: GraphQLRequest<Data, Variables>,
81
    opts?: Partial<OperationContext> | undefined
82
  ): Operation<Data, Variables>;
83

84
  /** Execute an operation and return a result source */
85
  executeRequestOperation<Data = any, Variables extends AnyVariables = AnyVariables>(
86
    operation: Operation<Data, Variables>
87
  ): OperationResultSource<OperationResult<Data, Variables>>;
88

89
  /** Redispatch an operation if it has active consumers */
90
  reexecuteOperation(operation: Operation): void;
91
}
92
```
93

94
### Request Policies
95

96
Control how the client handles caching behavior for operations.
97

98
```typescript { .api }
99
type RequestPolicy = 
100
  | 'cache-first'      // Use cache if available, fallback to network
101
  | 'cache-and-network' // Return cache immediately, then network result
102
  | 'network-only'      // Always make network request, bypass cache
103
  | 'cache-only';       // Only return cached results, never network
104

105
interface OperationContext {
106
  requestPolicy: RequestPolicy;
107
  // ... other context properties
108
}
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
// Override request policy per operation
115
const result = await client.query(
116
  GetUserQuery, 
117
  { id: "123" },
118
  { requestPolicy: 'network-only' }
119
).toPromise();
120

121
// Cache-and-network for immediate response with fresh data
122
const source = client.query(
123
  GetPostsQuery,
124
  {},
125
  { requestPolicy: 'cache-and-network' }
126
);
127
```
128

129
### Operation Context
130

131
Configure per-operation behavior and metadata.
132

133
```typescript { .api }
134
interface OperationContext {
135
  /** GraphQL API endpoint URL */
136
  url: string;
137
  /** Fetch options for HTTP requests */
138
  fetchOptions?: RequestInit | (() => RequestInit);
139
  /** Custom fetch implementation */
140
  fetch?: typeof fetch;
141
  /** Enable subscription over fetch */
142
  fetchSubscriptions?: boolean;
143
  /** Caching and network strategy */
144
  requestPolicy: RequestPolicy;
145
  /** Use GET method for queries */
146
  preferGetMethod?: boolean | 'force' | 'within-url-limit';
147
  /** Enable Suspense mode */
148
  suspense?: boolean;
149
  /** Additional cache invalidation typenames */
150
  additionalTypenames?: string[];
151
  /** Debug metadata for development */
152
  meta?: OperationDebugMeta;
153
  /** Allow arbitrary additional properties */
154
  [key: string]: any;
155
}
156
```
157

158
**Usage Examples:**
159

160
```typescript
161
// Override URL for specific operation
162
const result = await client.query(
163
  GetExternalDataQuery,
164
  { id: "123" },
165
  { url: "https://external-api.com/graphql" }
166
).toPromise();
167

168
// Add cache invalidation hints
169
await client.mutation(
170
  UpdateUserMutation,
171
  { id: "123", name: "New Name" },
172
  { additionalTypenames: ['User'] }
173
).toPromise();
174

175
// Force GET request for a specific query
176
const cached = await client.query(
177
  GetPublicDataQuery,
178
  {},
179
  { preferGetMethod: 'force' }
180
).toPromise();
181
```
182

183
### Client Constructor (Advanced)
184

185
Direct Client class instantiation for advanced use cases.
186

187
```typescript { .api }
188
interface Client {
189
  new (options: ClientOptions): Client;
190
}
191

192
const Client: new (opts: ClientOptions) => Client;
193
```
194

195
**Usage Examples:**
196

197
```typescript
198
// Direct instantiation (equivalent to createClient)
199
const client = new Client({
200
  url: "https://api.example.com/graphql",
201
  exchanges: [cacheExchange, fetchExchange],
202
});
203
```
204

205
## Types
206

207
### Debug Metadata
208

209
Development-time metadata for operation tracking.
210

211
```typescript { .api }
212
interface OperationDebugMeta {
213
  /** Human-readable source of the operation */
214
  source?: string;
215
  /** Cache outcome for the operation */
216
  cacheOutcome?: CacheOutcome;
217
  /** Network request latency in milliseconds */
218
  networkLatency?: number;
219
  /** Request start timestamp */
220
  startTime?: number;
221
}
222

223
type CacheOutcome = 'miss' | 'partial' | 'hit';
224
```