> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# @appsignal/urql

[`urql`](https://urql.dev/) is a GraphQL client for JavaScript applications. The `@appsignal/urql` package provides a [custom exchange](https://urql.dev/docs/architecture/#the-exchanges), which, once added to your `urql` client, automatically intercepts all GraphQL errors and reports them to AppSignal.

## Installation

### `npm` or `yarn`

Add the `@appsignal/urql` and `@appsignal/javascript` packages to your `package.json`. Then, run `npm install`/`yarn install`.

You can also add these packages to your `package.json` on the command line:

<CodeGroup>
  ```sh Shell theme={null}
  yarn add @appsignal/javascript @appsignal/urql
  npm install @appsignal/javascript @appsignal/urql
  ```
</CodeGroup>

### JSPM.io import maps

Using the [JSPM.io import map generator](https://generator.jspm.io/), you can generate an import map for your application's dependencies.

Add `@appsignal/javascript` and `@appsignal/urql` to the dependencies list in the generator, then add the generated import map and ES module shims to your application's code.

### `rails-importmap`

Use the following command to add these packages to your Rails application's import maps:

<CodeGroup>
  ```sh Shell theme={null}
  ./bin/importmap pin @appsignal/javascript @appsignal/urql
  ```
</CodeGroup>

## Usage

### Adding exchange to the client

The `@appsignal/urql` package provides a custom urql exchange that automatically reports GraphQL errors to AppSignal. This exchange intercepts all query and mutation results and reports any errors without requiring changes to individual `useQuery` calls.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { createClient, fetchExchange } from "urql";
  import Appsignal from "@appsignal/javascript";
  import { createAppsignalExchange } from "@appsignal/urql";

  const appsignal = new Appsignal({
    key: "YOUR FRONTEND API KEY",
  });

  const client = createClient({
    url: "https://api.example.com/graphql",
    exchanges: [createAppsignalExchange(appsignal), fetchExchange],
  });
  ```
</CodeGroup>

The exchange will automatically:

* Report all GraphQL errors to AppSignal
* Include the GraphQL query body as a parameter (visible in AppSignal's error details)
* Include the endpoint URL as a tag
* Include operation name and type as tags (when available)

## Error Details

When a GraphQL error occurs, AppSignal will receive:

* **Error message**: A concatenation of all GraphQL error messages
* **Tags**:
  * `endpoint`: The GraphQL endpoint URL
  * `operationName`: The name of the GraphQL operation (if specified)
  * `operationType`: The type of operation (query, mutation, subscription)
* **Parameters**:
  * `query`: The full GraphQL query body

This provides complete context for debugging GraphQL errors in your application.