urql

https://nearform.com/open-source/urql/docs
Admin
urql is a highly customizable and versatile GraphQL client for React, Svelte, and other JavaScript...
Tokens:53,803
Snippets:700
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install @urql/exchange-execute

Source: https://nearform.com/open-source/urql/docs/api/execute-exchange

Install the package using yarn or npm.

```bash
yarn add @urql/exchange-execute
# or
npm install --save @urql/exchange-execute
```

--------------------------------

### Install @urql/exchange-auth

Source: https://nearform.com/open-source/urql/docs/api/auth-exchange

Install the package using yarn or npm.

```bash
yarn add @urql/exchange-auth
# or
npm install --save @urql/exchange-auth
```

--------------------------------

### Install next-urql dependencies

Source: https://nearform.com/open-source/urql/docs/advanced/server-side-rendering

Install the required packages for next-urql integration.

```bash
yarn add next-urql react-is urql graphql
# or
npm install --save next-urql react-is urql graphql
```

--------------------------------

### Install populateExchange

Source: https://nearform.com/open-source/urql/docs/advanced/auto-populate-mutations

Install the required package via npm or yarn.

```bash
yarn add @urql/exchange-populate
# or
npm install --save @urql/exchange-populate
```

--------------------------------

### Install @urql/core

Source: https://nearform.com/open-source/urql/docs/basics/core

Use these commands to add the core package to your project dependencies.

```bash
yarn add @urql/core
# or
npm install --save @urql/core
```

--------------------------------

### Install retryExchange

Source: https://nearform.com/open-source/urql/docs/advanced/retry-operations

Install the package using yarn or npm.

```bash
yarn add @urql/exchange-retry
# or
npm install --save @urql/exchange-retry
```

--------------------------------

### Using useClientHandle in Vue setup

Source: https://nearform.com/open-source/urql/docs/basics/vue

Demonstrates how to use useClientHandle to perform queries after an await call in an async setup function.

```javascript
import { gql, useClientHandle } from '@urql/vue';


export default {
  async setup() {
    const handle = useClientHandle();


    await Promise.resolve(); // NOTE: This could be any await call


    const result = await handle.useQuery({
      query: gql`
        {
          todos {
            id
            title
          }
        }
      `,
    });


    return { data: result.data };
  },
};
```

--------------------------------

### Install @urql/next dependencies

Source: https://nearform.com/open-source/urql/docs/advanced/server-side-rendering

Install the required packages to enable urql support in Next.js.

```bash
yarn add @urql/next urql graphql
# or
npm install --save @urql/next urql graphql
```

--------------------------------

### Install urql dependencies

Source: https://nearform.com/open-source/urql/docs/basics/react-preact

Commands to install the urql package using yarn or npm.

```bash
yarn add urql
# or
npm install --save urql
```

--------------------------------

### Install @urql/vue dependencies

Source: https://nearform.com/open-source/urql/docs/basics/vue

Install the required packages using yarn or npm.

```bash
yarn add @urql/vue graphql
# or
npm install --save @urql/vue graphql
```

--------------------------------

### Install @urql/introspection

Source: https://nearform.com/open-source/urql/docs/graphcache/schema-awareness

Install the package required to minify introspection data.

```bash
yarn add @urql/introspection
# or
npm install --save @urql/introspection
```

--------------------------------

### Example Queries

Source: https://nearform.com/open-source/urql/docs/advanced/auto-populate-mutations

Sample queries used to demonstrate the need for automatic population.

```graphql
# Query 1
{
  todos {
    id
    name
  }
}


# Query 2
{
  todos {
    id
    createdAt
  }
}
```

--------------------------------

### Install urql Svelte dependencies

Source: https://nearform.com/open-source/urql/docs/basics/svelte

Install the required packages using yarn or npm.

```bash
yarn add @urql/svelte
# or
npm install --save @urql/svelte
```

--------------------------------

### Install Request Policy Exchange

Source: https://nearform.com/open-source/urql/docs/api/request-policy-exchange

Install the package using yarn or npm.

```bash
yarn add @urql/exchange-request-policy
# or
npm install --save @urql/exchange-request-policy
```

--------------------------------

### Install preact-ssr-prepass dependencies

Source: https://nearform.com/open-source/urql/docs/advanced/server-side-rendering

Install the necessary packages to enable the two-pass SSR approach for Preact.

```bash
yarn add preact-ssr-prepass preact
# or
npm install --save preact-ssr-prepass preact
```

--------------------------------

### Install react-ssr-prepass dependencies

Source: https://nearform.com/open-source/urql/docs/advanced/server-side-rendering

Install the necessary packages to enable the two-pass SSR approach for React.

```bash
yarn add react-ssr-prepass react-is react-dom
# or
npm install --save react-ssr-prepass react-is react-dom
```

--------------------------------

### Setup graphql-ws for subscriptions

Source: https://nearform.com/open-source/urql/docs/advanced/subscriptions

Implementation using the graphql-ws library to handle WebSocket-based subscriptions.

```typescript
import { Client, cacheExchange, fetchExchange, subscriptionExchange } from 'urql';
import { createClient as createWSClient } from 'graphql-ws';


const wsClient = createWSClient({
  url: 'ws://localhost/graphql',
});


const client = new Client({
  url: '/graphql',
  exchanges: [
    cacheExchange,
    fetchExchange,
    subscriptionExchange({
      forwardSubscription(request) {
        const input = { ...request, query: request.query || '' };
        return {
          subscribe(sink) {
            const unsubscribe = wsClient.subscribe(input, sink);
            return { unsubscribe };
          },
        };
      },
    }),
  ],
});
```

--------------------------------

### Install persisted exchange package

Source: https://nearform.com/open-source/urql/docs/advanced/persistence-and-uploads

Install the required package using yarn or npm.

```bash
yarn add @urql/exchange-persisted
# or
npm install --save @urql/exchange-persisted
```

--------------------------------

### Setup subscriptions-transport-ws for subscriptions

Source: https://nearform.com/open-source/urql/docs/advanced/subscriptions

Implementation using the legacy subscriptions-transport-ws library. Note that this package is no longer actively maintained.

```typescript
import { Client, cacheExchange, fetchExchange, subscriptionExchange } from 'urql';
import { SubscriptionClient } from 'subscriptions-transport-ws';


const subscriptionClient = new SubscriptionClient('ws://localhost/graphql', { reconnect: true });


const client = new Client({
  url: '/graphql',
  exchanges: [
    cacheExchange,
    fetchExchange,
    subscriptionExchange({
      forwardSubscription: request => subscriptionClient.request(request),
    }),
  ],
});
```

--------------------------------

### Install Refocus Exchange

Source: https://nearform.com/open-source/urql/docs/api/refocus-exchange

Use a package manager to add the exchange to your project dependencies.

```bash
yarn add @urql/exchange-refocus
# or
npm install --save @urql/exchange-refocus
```

--------------------------------

### Setup UrqlProvider in a Client Layout

Source: https://nearform.com/open-source/urql/docs/advanced/server-side-rendering

Wrap the application in UrqlProvider within a client layout to enable SSR and hydration.

```typescript
// app/client/layout.tsx
'use client';


import { useMemo } from 'react';
import { UrqlProvider, ssrExchange, cacheExchange, fetchExchange, createClient } from '@urql/next';


export default function Layout({ children }: React.PropsWithChildren) {
  const [client, ssr] = useMemo(() => {
    const ssr = ssrExchange({
      isClient: typeof window !== 'undefined',
    });
    const client = createClient({
      url: 'https://trygql.formidable.dev/graphql/web-collections',
      exchanges: [cacheExchange, ssr, fetchExchange],
      suspense: true,
    });


    return [client, ssr];
  }, []);


  return (
    <UrqlProvider client={client} ssr={ssr}>
      {children}
    </UrqlProvider>
  );
}
```

--------------------------------

### Install React Native storage package

Source: https://nearform.com/open-source/urql/docs/graphcache/offline

Commands to install the @urql/storage-rn package for React Native offline support.

```bash
yarn add @urql/storage-rn
# or
npm install --save @urql/storage-rn
```

--------------------------------

### Deduplicate dependencies

Source: https://nearform.com/open-source/urql/docs/basics/core

Run these commands to resolve issues caused by multiple versions of @urql/core being installed.

```bash
# npm
npm dedupe
# pnpm
pnpm dedupe
# yarn
npx yarn-deduplicate && yarn
```

--------------------------------

### Initialize Graphcache Client

Source: https://nearform.com/open-source/urql/docs/graphcache

Basic setup for the urql client using the Graphcache exchange instead of the default cache exchange.

```javascript
import { Client, fetchExchange } from 'urql';
import { cacheExchange } from '@urql/exchange-graphcache';


const client = new Client({
  url: 'http://localhost:3000/graphql',
  exchanges: [cacheExchange({}), fetchExchange],
});
```

--------------------------------

### Initialize authExchange in Client

Source: https://nearform.com/open-source/urql/docs/advanced/authentication

Setup the authExchange within the urql Client configuration, ensuring it is placed correctly relative to other exchanges.

```javascript
import { Client, cacheExchange, fetchExchange } from 'urql';
import { authExchange } from '@urql/exchange-auth';


const client = new Client({
  url: 'http://localhost:3000/graphql',
  exchanges: [
    cacheExchange,
    authExchange(async utils => {
      return {
        /* config... */
      };
    }),
    fetchExchange,
  ],
});
```

--------------------------------

### Install GraphQL Code Generator dependencies

Source: https://nearform.com/open-source/urql/docs/basics/typescript-integration

Install the required packages for TypeScript support and code generation.

```bash
yarn add -D graphql typescript @graphql-codegen/cli @graphql-codegen/client-preset
# or
npm install -D graphql typescript @graphql-codegen/cli @graphql-codegen/client-preset
```

--------------------------------

### GraphQL Query Document Example

Source: https://nearform.com/open-source/urql/docs/graphcache/normalized-caching

A sample GraphQL query document used to fetch todo and author information.

```graphql
{
  __typename
  todo(id: 1) {
    __typename
    id
    title
    author {
      __typename
      id
      name
    }
  }
}
```

--------------------------------

### Default Exchange Configuration

Source: https://nearform.com/open-source/urql/docs/advanced/authoring-exchanges

Standard client setup showing the ordering of synchronous and asynchronous exchanges.

```javascript
import { Client, cacheExchange, fetchExchange } from 'urql';


new Client({
  // ...
  exchanges: [cacheExchange, fetchExchange];
});
```

--------------------------------

### Implement a Resolver

Source: https://nearform.com/open-source/urql/docs/api/graphcache

Example of a resolver that transforms a field value into a Date instance.

```javascript
{
  Todo: {
    createdAt(parent, args, cache) {
      // Read `createdAt` on the parent but return a Date instance
      const date = cache.resolve(parent, 'createdAt');
      return new Date(date);
    }
  }
}
```

--------------------------------

### Demonstrate Relay Pagination Request Series

Source: https://nearform.com/open-source/urql/docs/graphcache/local-resolvers

Example sequence of Relay-style requests showing cursor-based pagination.

```javascript
first: 1 => node 1, endCursor: a
first: 1, after: a => node 2, endCursor: b
...
last: 1 => node 99, startCursor: c
last: 1, before: c => node 89, startCursor: d
```

--------------------------------

### Implement Vue Suspense with useQuery

Source: https://nearform.com/open-source/urql/docs/basics/vue

Use async setup with await on useQuery to suspend component rendering until data is fetched.

```vue
<template>
  <ul>
    <li v-for="todo in data.todos" :key="todo.id">{{ todo.title }}</li>
  </ul>
</template>


<script>
import { gql, useQuery } from '@urql/vue';


export default {
  async setup() {
    const { data, error } = await useQuery({
      query: gql`
        {
          todos {
            id
            title
          }
        }
      `
    });


    return { data };
  }
};
</script>
```

--------------------------------

### Provide Client using provideClient

Source: https://nearform.com/open-source/urql/docs/basics/vue

Use the provideClient function within a parent component's setup to share the client instance.

```javascript
<script>
  import { Client, provideClient, cacheExchange, fetchExchange } from '@urql/vue';


  const client = new Client({
    url: 'http://localhost:3000/graphql',
    exchanges: [cacheExchange, fetchExchange],
  });


  provideClient(client);
</script>
```

--------------------------------

### Install Graphcache package

Source: https://nearform.com/open-source/urql/docs/graphcache

Commands to add the Graphcache dependency to your project using yarn or npm.

```bash
yarn add @urql/exchange-graphcache
# or
npm install --save @urql/exchange-graphcache
```

--------------------------------

### Configure Auth State Initialization

Source: https://nearform.com/open-source/urql/docs/advanced/authentication

Examples of retrieving authentication tokens from storage during the authExchange initialization phase for web and React Native environments.

```javascript
async function initializeAuthState() {
  const token = localStorage.getItem('token');
  const refreshToken = localStorage.getItem('refreshToken');
  return { token, refreshToken };
}


authExchange(async utils => {
  let { token, refreshToken } = initializeAuthState();
  return {
    /* config... */
  };
});
```

```javascript
async function initializeAuthState() {
  const token = await AsyncStorage.getItem(TOKEN_KEY);
  const refreshToken = await AsyncStorage.getItem(REFRESH_KEY);
  return { token, refreshToken };
}


authExchange(async utils => {
  let { token, refreshToken } = initializeAuthState();
  return {
    /* config... */
  };
});
```

--------------------------------

### Configure subscriptionExchange in urql Client

Source: https://nearform.com/open-source/urql/docs/advanced/subscriptions

Basic setup for adding the subscriptionExchange to the urql Client, requiring a forwardSubscription function.

```typescript
import { Client, cacheExchange, fetchExchange, subscriptionExchange } from 'urql';


const client = new Client({
  url: 'http://localhost:3000/graphql',
  exchanges: [
    cacheExchange,
    fetchExchange,
    subscriptionExchange({
      forwardSubscription,
    }),
  ],
});
```

--------------------------------

### Example GraphQL Query for Todo

Source: https://nearform.com/open-source/urql/docs/graphcache/normalized-caching

A standard GraphQL query used to illustrate how data is stored and retrieved from the cache.

```graphql
{
  todo(id: 1) {
    id
  }
}
```

--------------------------------

### GraphQL JSON Response Example

Source: https://nearform.com/open-source/urql/docs/graphcache/normalized-caching

The JSON response corresponding to the provided GraphQL query document.

```json
{
  "__typename": "Query",
  "todo": {
    "__typename": "Todo",
    "id": 1,
    "title": "implement graphcache",
    "author": {
      "__typename": "Author",
      "id": 1,
      "name": "urql-team"
    }
  }
}
```

--------------------------------

### Define GraphQL query and mutation

Source: https://nearform.com/open-source/urql/docs/graphcache/normalized-caching

Example GraphQL definitions for a todo list query and an add todo mutation.

```graphql

query TodosList {
  todos {
    id
    title
  }
}


mutation AddTodo($title: String!) {
  addTodo(title: $title) {
    id
    title
  }
}


```

--------------------------------

### Define query and result for empty list scenario

Source: https://nearform.com/open-source/urql/docs/basics/document-caching

Example of a query and result structure where the cache cannot infer typenames due to an empty list.

```javascript
const query = `query { todos { id name } }`;
const result = { todos: [] };
```

--------------------------------

### Initialize the urql Client

Source: https://nearform.com/open-source/urql/docs/basics/svelte

Create a new Client instance with the required URL and exchanges.

```javascript
import { Client, cacheExchange, fetchExchange } from '@urql/svelte';


const client = new Client({
  url: 'http://localhost:3000/graphql',
  exchanges: [cacheExchange, fetchExchange],
});
```

--------------------------------

### Initialize the GraphQL Client

Source: https://nearform.com/open-source/urql/docs/basics/vue

Create a new Client instance with the required URL and exchanges.

```javascript
import { Client, cacheExchange, fetchExchange } from '@urql/vue';


const client = new Client({
  url: 'http://localhost:3000/graphql',
  exchanges: [cacheExchange, fetchExchange],
});
```

--------------------------------

### Run a first query with queryStore

Source: https://nearform.com/open-source/urql/docs/basics/svelte

Initializes a data container using queryStore and handles loading, error, and data states using Svelte's auto-subscription.

```svelte
<script>
  import { queryStore, gql, getContextClient } from '@urql/svelte';


  const todos = queryStore({
    client: getContextClient(),
    query: gql`
      query {
        todos {
          id
          title
        }
      }
    `,
  });
</script>


{#if $todos.fetching}
<p>Loading...</p>
{:else if $todos.error}
<p>Oh no... {$todos.error.message}</p>
{:else}
<ul>
  {#each $todos.data.todos as todo}
  <li>{todo.title}</li>
  {/each}
</ul>
{/if}
```

--------------------------------

### Define a GraphQL mutation

Source: https://nearform.com/open-source/urql/docs/graphcache/cache-updates

Example mutation definition for updating a todo item.

```graphql
mutation UpdateTodo($id: ID!, $text: ID!) {
  updateTodo(id: $id, text: $text) {
    id
    text
  }
}
```

--------------------------------

### Initialize the urql Client

Source: https://nearform.com/open-source/urql/docs/architecture

Configure the urql Client with a URL and necessary exchanges for caching and fetching.

```typescript
import { Client, cacheExchange, fetchExchange } from '@urql/core';


const client = new Client({
  url: 'http://localhost:3000/graphql',
  exchanges: [cacheExchange, fetchExchange],
});
```

--------------------------------

### Mutation returning a scalar

Source: https://nearform.com/open-source/urql/docs/graphcache/cache-updates

Example of a mutation that returns a scalar, preventing automatic cache updates.

```graphql
mutation UpdateTodo($todoId: ID!, $date: String!) {
  updateTodoDate(id: $todoId, date: $date)
}
```

--------------------------------

### Configure standard exchanges

Source: https://nearform.com/open-source/urql/docs/advanced/authoring-exchanges

Initialize the urql Client with the default cache and fetch exchanges.

```javascript
import { Client, fetchExchange, cacheExchange } from 'urql';


const client = new Client({
  url: 'http://localhost:3000/graphql',
  exchanges: [cacheExchange, fetchExchange],
});
```

--------------------------------

### Invalid usage without aliases

Source: https://nearform.com/open-source/urql/docs/advanced/auto-populate-mutations

Example of queries that may conflict without using aliases.

```graphql
# Query 1
{
  todos(first: 10) {
    id
    name
  }
}


# Query 2
{
  todos(last: 20) {
    id
    createdAt
  }
}
```

--------------------------------

### Define an optimistic mutation

Source: https://nearform.com/open-source/urql/docs/graphcache/cache-updates

Example GraphQL mutation for toggling a todo item's favorite status.

```graphql
mutation FavoriteTodo(id: $id) {
  favoriteTodo(id: $id) {
    id
    favorite
    updatedAt
  }
}
```

--------------------------------

### Prefetching data with urql Client

Source: https://nearform.com/open-source/urql/docs/basics/ui-patterns

Use the client.query method to initiate a query before a page transition completes. This allows data to be fetched in parallel with other assets like JS bundles.

```javascript
import React from 'react';
import { useClient, gql } from 'urql';


const TodoQuery = gql`
  query Todo($id: ID!) {
    todo(id: $id) {
      id
      name
    }
  }
`;


const Component = () => {
  const client = useClient();
  const router = useRouter();


  const transitionPage = React.useCallback(async id => {
    const loadJSBundle = import('./page.js');
    const loadData = client.query(TodoQuery, { id }).toPromise();
    await Promise.all([loadJSBundle, loadData]);
    router.push(`/todo/${id}`);
  }, []);


  return <button onClick={() => transitionPage('1')}>Go to todo 1</button>;
};
```

--------------------------------

### provideClient(clientOrOptions)

Source: https://nearform.com/open-source/urql/docs/api/vue

Provides the urql Client to the component subtree.

```APIDOC
## provideClient(clientOrOptions)

### Description
Provides the Client to a component subtree. Accepts either a Client instance or the same options as createClient.
```

--------------------------------

### Reinitialize Client on Auth State Change

Source: https://nearform.com/open-source/urql/docs/advanced/authentication

Use useMemo to recreate the urql Client when authentication state changes, ensuring the cache is invalidated.

```javascript
import { createClient, Provider } from 'urql';


const App = ({ isLoggedIn }: { isLoggedIn: boolean | null }) => {
  const client = useMemo(() => {
    if (isLoggedIn === null) {
      return null;
    }


    return createClient({ /* config */ });
  }, [isLoggedIn]);


  if (!client) {
    return null;
  }


  return {
    <Provider value={client}>
      {/* app content  */}
    <Provider>
  }
}
```

--------------------------------

### Define GraphQL Error Structure

Source: https://nearform.com/open-source/urql/docs/advanced/authentication

Example of a GraphQL error response structure using extensions for error codes.

```json
{
  data: null,
  errors: [
    {
      message: 'Unauthorized: Token has expired',
      extensions: {
        code: 'FORBIDDEN'
      },
    }
  ]
}
```

--------------------------------

### Configure Client with fetchOptions

Source: https://nearform.com/open-source/urql/docs/basics/core

Customize fetch requests by providing a function that returns headers or other fetch options.

```javascript
const client = new Client({
  url: 'http://localhost:3000/graphql',
  exchanges: [cacheExchange, fetchExchange],
  fetchOptions: () => {
    const token = getToken();
    return {
      headers: { authorization: token ? `Bearer ${token}` : '' },
    };
  },
});
```

--------------------------------

### Provide the Client via Context

Source: https://nearform.com/open-source/urql/docs/basics/react-preact

Wrapping the application with the Provider component to make the client available to all child components.

```javascript
import { Client, Provider, cacheExchange, fetchExchange } from 'urql';


const client = new Client({
  url: 'http://localhost:3000/graphql',
  exchanges: [cacheExchange, fetchExchange],
});


const App = () => (
  <Provider value={client}>
    <YourRoutes />
  </Provider>
);
```

--------------------------------

### Implementing useClient hook

Source: https://nearform.com/open-source/urql/docs/api/urql

A convenience wrapper for accessing the urql client context, which includes a warning mechanism for default client usage.

```javascript
import React from 'react';
import { Context } from 'urql';


const useClient = () => React.useContext(Context);
```

--------------------------------

### Query with embedded entity

Source: https://nearform.com/open-source/urql/docs/graphcache/normalized-caching

Example query involving an entity type that lacks a primary key and is considered embedded data.

```graphql
{
  __typename
  todo(id: 1) {
    id
    image {
      url
      width
      height
    }
  }
}
```

--------------------------------

### Fetch data with useQuery

Source: https://nearform.com/open-source/urql/docs/basics/react-preact

Demonstrates a basic GraphQL query implementation using the useQuery hook to handle loading, error, and data states.

```javascript
import { gql, useQuery } from 'urql';


const TodosQuery = gql`
  query {
    todos {
      id
      title
    }
  }
`;


const Todos = () => {
  const [result, reexecuteQuery] = useQuery({
    query: TodosQuery,
  });


  const { data, fetching, error } = result;


  if (fetching) return <p>Loading...</p>;
  if (error) return <p>Oh no... {error.message}</p>;


  return (
    <ul>
      {data.todos.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  );
};
```

--------------------------------

### Query with custom identifier field

Source: https://nearform.com/open-source/urql/docs/graphcache/normalized-caching

Example GraphQL query where the entity uses 'uuid' instead of the default 'id' field.

```graphql
{
  item {
    uuid
  }
}
```

--------------------------------

### Optimistic mutation with arguments

Source: https://nearform.com/open-source/urql/docs/graphcache/cache-updates

Example of a mutation where the field includes arguments, requiring careful handling of the optimistic return value.

```graphql
mutation FavoriteTodo(id: $id) {
  favoriteTodo(id: $id) {
    id
    favorite(since: ONE_MONTH_AGO)
    updatedAt
  }
}
```

--------------------------------

### Provide Client as a Vue Plugin

Source: https://nearform.com/open-source/urql/docs/basics/vue

Register the client globally by using the urql plugin with the Vue application instance.

```javascript
import { createApp } from 'vue';
import Root from './App.vue';
import urql, { cacheExchange, fetchExchange } from '@urql/vue';


const app = createApp(Root);


app.use(urql, {
  url: 'http://localhost:3000/graphql',
  exchanges: [cacheExchange, fetchExchange],
});


app.mount('#app');
```

--------------------------------

### Server-Side Rendering with Vue and urql

Source: https://nearform.com/open-source/urql/docs/advanced/server-side-rendering

Demonstrates how to configure the SSR exchange and render a Vue application to a string on the server, including data extraction for client-side rehydration.

```javascript
import { createSSRApp } = from 'vue'
import { renderToString } from '@vue/server-renderer';


import urql, {
  createClient,
  cacheExchange,
  fetchExchange,
  ssrExchange
} from '@urql/vue';


const handleRequest = async (req, res) => {
  // This is where we'll put our root component
  const app = createSSRApp(Root)


  // NOTE: All we care about here is that the SSR Exchange is included
  const ssr = ssrExchange({ isClient: false });
  app.use(urql, {
    exchanges: [cacheExchange, ssr, fetchExchange]
  });


  const markup = await renderToString(app);


  const data = JSON.stringify(ssr.extractData());


  res.status(200).send(`
    <html>
      <body>
        <div id="root">${markup}</div>
        <script>
          window.__URQL_DATA__ = JSON.parse(${data});
        </script>
      </body>
    </html>
  `);
};
```

--------------------------------

### queryStore

Source: https://nearform.com/open-source/urql/docs/api/svelte

Creates a Svelte pausable, readable store for executing GraphQL queries.

```APIDOC
## queryStore(args)

### Description
The `queryStore` factory accepts properties as inputs and returns a Svelte pausable, readable store of results.

### Arguments
- **client** (Client) - Required - The Client to use for the operation.
- **query** (string | DocumentNode) - Required - The query to be executed.
- **variables** (object) - Optional - The variables to be used with the GraphQL request.
- **requestPolicy** (RequestPolicy) - Optional - The cache strategy to be used.
- **pause** (boolean) - Optional - A flag to pause execution.
- **context** (object) - Optional - Contextual information for the query.
```

--------------------------------

### Mutation returning a full entity

Source: https://nearform.com/open-source/urql/docs/graphcache/cache-updates

Example of a mutation updated to return the full Todo entity to enable automatic cache updates.

```graphql
mutation UpdateTodo($todoId: ID!, $date: String!) {
  updateTodoDate(id: $todoId, date: $date) {
    ...Todo_date
  }
}


fragment Todo_date on Todo {
  id
  updatedAt
}
```

--------------------------------

### Automatic Cache Update Example

Source: https://nearform.com/open-source/urql/docs/graphcache/cache-updates

A mutation that returns the updated entity allows Graphcache to automatically update the cache without manual intervention.

```graphql
query User($id: ID!) {
  user(id: $id) {
    __typename # "User"
    id
    username
  }
}


mutation UpdateUsername($id: ID!, $username: String!) {
  updateUser(id: $id, username: $username) {
    __typename # "User"
    id
    username
  }
}
```

--------------------------------

### Typed GraphQL Queries in React

Source: https://nearform.com/open-source/urql/docs/basics/typescript-integration

Example of using the generated graphql() function with the urql useQuery hook to provide typed data and variables.

```typescript
import React from 'react';
import { useQuery } from 'urql';


import './App.css';
import Film from './Film';
import { graphql } from '../src/gql';


const allFilmsWithVariablesQueryDocument = graphql(/* GraphQL */ `
  query allFilmsWithVariablesQuery($first: Int!) {
    allFilms(first: $first) {
      edges {
        node {
          ...FilmItem
        }
      }
    }
  }
`);


function App() {
  // `data` is typed!
  const [{ data }] = useQuery({
    query: allFilmsWithVariablesQueryDocument,
    variables: { first: 10 },
  });
  return (
    <div className="App">
      {data && (
        <ul>
          {data.allFilms?.edges?.map(
            (e, i) => e?.node && <Film film={e?.node} key={`film-${i}`} />
          )}
        </ul>
      )}
    </div>
  );
}


export default App;
```

--------------------------------

### Use reactive variables

Source: https://nearform.com/open-source/urql/docs/basics/vue

Demonstrates how useQuery reacts to changes in reactive variables, enabling dynamic updates to the query results.

```vue
<template>
  <ul v-if="data">
    <li v-for="todo in data.todos" :key="todo.id">{{ todo.title }}</li>
  </ul>
  <button @click="from += 10">Next Page</button>
</template>


<script>
import { gql, useQuery } from '@urql/vue';


export default {
  setup() {
    const from = ref(0);


    const result = useQuery({
      query: gql`
        query ($from: Int!, $limit: Int!) {
          todos(from: $from, limit: $limit) {
            id
            title
          }
        }
      `,
      variables: { from, limit: 10 }
    });


    return {
      from,
      data: result.data,
    };
  }
};
</script>
```

--------------------------------

### useClientHandle()

Source: https://nearform.com/open-source/urql/docs/api/vue

Returns a client handle that provides direct access to the Client instance and bound versions of useQuery, useMutation, and useSubscription.

```APIDOC
## useClientHandle()

### Description
Returns a client handle that allows access to the raw Client reference and provides bound versions of composition functions.

### Methods
- **client**: Returns the raw Client reference.
- **useQuery(...)**: Executes a query using the Client from the handle's context.
- **useMutation(...)**: Executes a mutation using the Client from the handle's context.
- **useSubscription(...)**: Executes a subscription using the Client from the handle's context.
```

--------------------------------

### Enable fetch for subscriptions

Source: https://nearform.com/open-source/urql/docs/advanced/subscriptions

Configuration for backends that support executing subscriptions via standard HTTP fetch calls.

```typescript
import { Client, cacheExchange, fetchExchange, subscriptionExchange } from 'urql';


const client = new Client({
  url: '/graphql',
  fetchSubscriptions: true,
  exchanges: [cacheExchange, fetchExchange],
});
```

--------------------------------

### Configure Vite for urql

Source: https://nearform.com/open-source/urql/docs/basics/svelte

Exclude @urql/svelte from Vite's dependency optimization to avoid initialization errors.

```javascript
{
  optimizeDeps: {
    exclude: ['@urql/svelte'],
  }
  // other properties
}
```

--------------------------------

### Implementing SSR with getStaticProps

Source: https://nearform.com/open-source/urql/docs/advanced/server-side-rendering

Configures urql with ssrExchange to populate the cache during static generation, ensuring the urqlState prop is returned for the client.

```javascript
import { withUrqlClient, initUrqlClient } from 'next-urql';
import { ssrExchange, cacheExchange, fetchExchange, useQuery } from 'urql';


const TODOS_QUERY = `
  query { todos { id text } }
`;


function Todos() {
  const [res] = useQuery({ query: TODOS_QUERY });
  return (
    <div>
      {res.data.todos.map(todo => (
        <div key={todo.id}>
          {todo.id} - {todo.text}
        </div>
      ))}
    </div>
  );
}


export async function getStaticProps(ctx) {
  const ssrCache = ssrExchange({ isClient: false });
  const client = initUrqlClient(
    {
      url: 'your-url',
      exchanges: [cacheExchange, ssrCache, fetchExchange],
    },
    false
  );


  // This query is used to populate the cache for the query
  // used on this page.
  await client.query(TODOS_QUERY).toPromise();


  return {
    props: {
      // urqlState is a keyword here so withUrqlClient can pick it up.
      urqlState: ssrCache.extractData(),
    },
    revalidate: 600,
  };
}


export default withUrqlClient(
  ssr => ({
    url: 'your-url',
  })
  // Cannot specify { ssr: true } here so we don't wrap our component in getInitialProps
)(Todos);
```

--------------------------------

### Initialize offlineExchange

Source: https://nearform.com/open-source/urql/docs/graphcache/offline

Replace the standard cacheExchange with offlineExchange to enable offline capabilities in the urql client.

```javascript
import { Client, fetchExchange } from 'urql';
import { offlineExchange } from '@urql/exchange-graphcache';


const cache = offlineExchange({
  schema,
  updates: {
    /* ... */
  },
  optimistic: {
    /* ... */
  },
});


const client = new Client({
  url: 'http://localhost:3000/graphql',
  exchanges: [cache, fetchExchange],
});
```

--------------------------------

### authExchange(config)

Source: https://nearform.com/open-source/urql/docs/api/auth-exchange

Initializes the authExchange with a configuration function that returns authentication logic options.

```APIDOC
## authExchange(config)

### Description
Initializes the authentication exchange for the urql client. It accepts an asynchronous function that returns configuration options to manage authentication state.

### Parameters
- **config** (function) - Required - An async function that receives `utils` and returns an object containing authentication configuration.

### Configuration Options
- **addAuthToOperation** (function) - Required - Defines how to add authentication information (e.g., headers) to an operation.
- **willAuthError** (function) - Optional - Used to detect if an operation will likely fail due to an authentication error.
- **didAuthError** (function) - Optional - Used to detect authentication errors from API results.
- **refreshAuth** (function) - Optional - Called when an authentication error occurs to update authentication state and retry the operation.
```

--------------------------------

### subscriptionStore

Source: https://nearform.com/open-source/urql/docs/api/svelte

Creates a Svelte pausable, readable store for GraphQL subscriptions with an optional reducer.

```APIDOC
## subscriptionStore(args, handler)

### Description
The `subscriptionStore` utility function accepts the same inputs as `queryStore` and an optional handler function to reduce incoming data.

### Arguments
- **args** (object) - Required - Same arguments as `queryStore`.
- **handler** (function) - Optional - A function with signature `(previousData: R | undefined, data: T) => R` to reduce data over time.
```

--------------------------------

### Run GraphQL Codegen

Source: https://nearform.com/open-source/urql/docs/basics/typescript-integration

Commands to initiate the GraphQL code generator in watch mode.

```bash
yarn codegen
# or
npm run codegen
```

--------------------------------

### Subscribe to GraphQL query results using the Client

Source: https://nearform.com/open-source/urql/docs/architecture

Demonstrates executing a query and subscribing to the resulting stream of data using the urql Client.

```javascript
import { gql } from '@urql/core';


const QUERY = gql`
  query Test($id: ID!) {
    getUser(id: $id) {
      id
      name
    }
  }
`;


client.query(QUERY, { id: 'test' }).subscribe(result => {
  console.log(result); // { data: ... }
});
```

--------------------------------

### Enable SSR with ssr: true

Source: https://nearform.com/open-source/urql/docs/advanced/server-side-rendering

Explicitly enable server-side rendering by passing the ssr option to withUrqlClient.

```javascript
import { cacheExchange, fetchExchange } from '@urql/core';


import { withUrqlClient } from 'next-urql';


export default withUrqlClient(
  ssrExchange => ({
    url: 'http://localhost:3000/graphql',
    exchanges: [cacheExchange, ssrExchange, fetchExchange],
  }),
  { ssr: true } // Enables server-side rendering using `getInitialProps`
)(Index);
```

--------------------------------

### Configure populateExchange in Client

Source: https://nearform.com/open-source/urql/docs/advanced/auto-populate-mutations

Add the populateExchange to the exchanges array before the cacheExchange.

```javascript
import { Client, fetchExchange } from '@urql/core';
import { populateExchange } from '@urql/exchange-populate';


const client = new Client({
  // ...
  exchanges: [populateExchange({ schema }), cacheExchange, fetchExchange],
});
```

--------------------------------

### Wrap pages with withUrqlClient

Source: https://nearform.com/open-source/urql/docs/advanced/server-side-rendering

Use the withUrqlClient higher-order component to provide the urql client to your Next.js pages.

```javascript
// pages/index.js
import React from 'react';
import { useQuery } from 'urql';
import { withUrqlClient } from 'next-urql';


const Index = () => {
  const [result] = useQuery({
    query: '{ test }',
  });


  // ...
};


export default withUrqlClient((_ssrExchange, ctx) => ({
  // ...add your Client options here
  url: 'http://localhost:3000/graphql',
}))(Index);
```

--------------------------------

### Demonstrate Merge Modes for Simple Pagination

Source: https://nearform.com/open-source/urql/docs/graphcache/local-resolvers

Visualizing how mergeMode affects the order of concatenated pages in offset/limit pagination.

```javascript
// An example where mergeMode: after works better
skip: 0, limit: 3 => 1, 2, 3
skip: 3, limit: 3 => 4, 5, 6


mergeMode: after => 1, 2, 3, 4, 5, 6 ✔️
mergeMode: before => 4, 5, 6, 1, 2, 3


// An example where mergeMode: before works better
skip: 0, limit: 3 => 4, 5, 6
skip: 3, limit: 3 => 1, 2, 3


mergeMode: after => 4, 5, 6, 1, 2, 3
mergeMode: before => 1, 2, 3, 4, 5, 6 ✔️
```

--------------------------------

### Configure urql in a Server Component

Source: https://nearform.com/open-source/urql/docs/advanced/server-side-rendering

Use registerUrql from @urql/next/rsc to create a client and execute queries within a Next.js Server Component.

```typescript
// app/page.tsx
import React from 'react';
import { cacheExchange, createClient, fetchExchange, gql } from '@urql/core';
import { registerUrql } from '@urql/next/rsc';


const makeClient = () => {
  return createClient({
    url: 'https://trygql.formidable.dev/graphql/basic-pokedex',
    exchanges: [cacheExchange, fetchExchange],
  });
};


const { getClient } = registerUrql(makeClient);


export default async function Home() {
  const result = await getClient().query(PokemonsQuery, {});
  return (
    <main>
      <h1>This is rendered as part of an RSC</h1>
      <ul>
        {result.data.pokemons.map((x: any) => (
          <li key={x.id}>{x.name}</li>
        ))}
      </ul>
    </main>
  );
}
```

--------------------------------

### Exchange Composition Context

Source: https://nearform.com/open-source/urql/docs/advanced/authoring-exchanges

Demonstrates how an exchange fits into the client pipeline between cache and fetch exchanges.

```javascript
import { Client, cacheExchange, fetchExchange } from 'urql';


const noopExchange = ({ client, forward }) => {
  return operations$ => {
    // <-- The ExchangeIO function
    // We receive a stream of Operations from `cacheExchange` which
    // we can modify before...
    const forwardOperations$ = operations$;


    // ...calling `forward` with the modified stream. The `forward`
    // function is the next exchange's `ExchangeIO` function, in this
    // case `fetchExchange`.
    const operationResult$ = forward(operations$);


    // We get back `fetchExchange`'s stream of results, which we can
    // also change before returning, which is what `cacheExchange`
    // will receive when calling `forward`.
    return operationResult$;
  };
};


const client = new Client({
  exchanges: [cacheExchange, noopExchange, fetchExchange],
});
```

--------------------------------

### Provide the Client via Context

Source: https://nearform.com/open-source/urql/docs/basics/svelte

Use setContextClient in a parent component to share the client instance with child components.

```html
<script>
  import { Client, setContextClient, cacheExchange, fetchExchange } from '@urql/svelte';


  const client = new Client({
    url: 'http://localhost:3000/graphql',
    exchanges: [cacheExchange, fetchExchange],
  });


  setContextClient(client);
</script>
```

--------------------------------

### Create a DocumentNode with gql

Source: https://nearform.com/open-source/urql/docs/basics/core

Use the gql tag to create a DocumentNode directly, which is compatible with urql's query requirements.

```javascript

import { gql } from '@urql/core';


const TodosQuery = gql`
  query {
    todos {
      id
      title
    }
  }
`;

```

--------------------------------

### client.subscription

Source: https://nearform.com/open-source/urql/docs/api/core

A shorthand method for executing GraphQL subscriptions.

```APIDOC
## client.subscription

### Description
Similar to client.query, but does not provide a toPromise() helper method on the returned stream.
```
Tokens:
Raw