kitten.sh
Mirror: The highly customizable and versatile GraphQL client with which you add on features like normalized caching as you grow.
(docs) - Debugging Documentation (#749)
* Initial write up
* Tweak order
* Remove unnecessary caption
* Change wording
* Remove unused heading
* "queries"
* Update docs/advanced/debugging.md
Co-Authored-By: Jovi De Croock <jovi.decroock@formidable.com>
* Update docs/advanced/debugging.md
Co-Authored-By: Jovi De Croock <jovi.decroock@formidable.com>
* Update debugging.md
* Update docs/advanced/debugging.md
Co-Authored-By: Jovi De Croock <jovi.decroock@formidable.com>
* Update urql term
Co-authored-by: Jovi De Croock <jovi.decroock@formidable.com>
authored by
Andy Richardson
Jovi De Croock
and committed by
GitHub
46d8b3b9
f1997acb
+126
+126
docs/advanced/debugging.md
+126
docs/advanced/debugging.md
···
1
+
---
2
+
title: Debugging
3
+
order: 6
4
+
---
5
+
6
+
# Debugging
7
+
8
+
We've tried to make debugging in `urql` as seamless as possible by creating tools for users of `urql` and those creating their own exchanges.
9
+
10
+
## Debug events
11
+
12
+
Debug events are a means for seeing what's going on inside of `urql` exchanges. Before getting started, here are a few things to be aware of.
13
+
14
+
### Anyone with client access can listen
15
+
16
+
This includes the creator of an `urql` client and any of it's exchanges (although the latter is not advised).
17
+
18
+
### Debug events are disabled in production
19
+
20
+
Debug events are a fire-and-forget mechanism and should not be used as a means for messaging in your app.
21
+
22
+
## Consuming debug events
23
+
24
+
Debugging events can be inspected either graphically using our [devtools](https://github.com/FormidableLabs/urql-devtools) or manually by subscribing to events on the client.
25
+
26
+
### Devtools
27
+
28
+
The quickest way is going to be using our [devtools extension](https://github.com/FormidableLabs/urql-devtools/) which visualizes events on a timeline and provides tools to filter events, inspect the cache, and trigger custom queries via the running client.
29
+
30
+
31
+
32
+
Visit [the repo](https://github.com/FormidableLabs/urql-devtools/) for instructions on getting started.
33
+
34
+
> Note: Devtools is unfortunately not currently supported for React Native but we're looking into it!
35
+
36
+
### Manual consumption of events
37
+
38
+
For those not looking to use a GUI to view events, the client has a `subscribeToDebugTarget` function.
39
+
40
+
As demonstrated below, the `subscribeToDebugTarget` function takes a callback which is called with every debug event that is dispatched.
41
+
42
+
```ts
43
+
const { unsubscribe } = client.subscribeToDebugTarget(event => {
44
+
if (event.source === 'dedupExchange') {
45
+
return;
46
+
}
47
+
48
+
console.log(event);
49
+
});
50
+
51
+
// ...
52
+
// Unsubscribe from events
53
+
unsubscribe();
54
+
```
55
+
56
+
## Dispatching debug events
57
+
58
+
Debug events are a means of sharing implementation details to consumers of an exchange.
59
+
60
+
#### Identify key events
61
+
62
+
The first step is to identify key events of the exchange in question.
63
+
64
+
For example, a [_fetchExchange_](https://github.com/FormidableLabs/urql/blob/master/packages/core/src/exchanges/fetch.ts) which triggers fetch requests may have an event of type `fetchRequest`.
65
+
66
+
#### Create an event type (optional)
67
+
68
+
For type safe events, and to prevent conflicts with other exchanges, [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) can be used.
69
+
70
+
```ts
71
+
// urql.d.ts
72
+
import '@urql/core';
73
+
74
+
declare module '@urql/core' {
75
+
interface DebugEventTypes {
76
+
fetchRequest: { targetUrl: string };
77
+
}
78
+
}
79
+
```
80
+
81
+
#### Dispatch the event
82
+
83
+
A `dispatchDebug` function is now passed to every exchange and is used to dispatch debug events.
84
+
85
+
It is called with an object containing the following properties:
86
+
87
+
- `type` - a unique identifier for the event type.
88
+
- `message` - a human readable description of the event.
89
+
- `operation` - the operation in scope when the event occured.
90
+
- `data` _(optional)_ - any additional data useful for debugging
91
+
92
+
Here, we call `dispatchDebug` with our `fetchRequest` event we declared earlier.
93
+
94
+
```ts
95
+
export const fetchExchange: Exchange = ({ forward, dispatchDebug }) => {
96
+
// ...
97
+
dispatchDebug({
98
+
type: 'fetchRequest',
99
+
message: 'A network request has been triggered',
100
+
operation,
101
+
data: { targetUrl },
102
+
});
103
+
};
104
+
```
105
+
106
+
> Note: for a real world example, see the [_fetchExchange_](https://github.com/FormidableLabs/urql/blob/master/packages/core/src/exchanges/fetch.ts).
107
+
108
+
### Tips
109
+
110
+
In summary, here are a few do's and don'ts.
111
+
112
+
#### ✅ Do share internal details
113
+
114
+
Frequent debug messages on key events inside your exchange is very useful for consumers.
115
+
116
+
#### ✅ Do create unique event types
117
+
118
+
Key events should be easy to identify and differentiate, so have a unique name and data format for each unique event and use that format consistently.
119
+
120
+
#### ❌ Don't listen to debug events inside your exchange
121
+
122
+
While it is possible, there isn't any value in doing this. Use the exchange pipeline to communicate with other exchanges.
123
+
124
+
#### ❌ Don't send warnings in debug events
125
+
126
+
Debug **events** are intended to document **events** inside an exchange, not as a way to send messages to the user. Use `console.warn` to send alerts to the user.
docs/assets/devtools-timeline.png
docs/assets/devtools-timeline.png
This is a binary file and will not be displayed.