Menu

@appsignal/urql

urql is a GraphQL client for JavaScript applications. The @appsignal/urql package provides a custom exchange, 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:

Shell
yarn add @appsignal/javascript @appsignal/urql
npm install @appsignal/javascript @appsignal/urql

JSPM.io import maps

Using the JSPM.io import map generator, 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:

Shell
./bin/importmap pin @appsignal/javascript @appsignal/urql

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.

typescript
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],
});

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.