kitten.sh
1# @urql/exchange-populate
2
3`populate` is an exchange for auto-populating fields in your mutations.
4
5[Read more about the `populateExchange` on our docs!](https://formidable.com/open-source/urql/docs/advanced/auto-populate-mutations)
6
7## Quick Start Guide
8
9First install `@urql/exchange-populate` alongside `urql`:
10
11```sh
12yarn add @urql/exchange-populate
13# or
14npm install --save @urql/exchange-populate
15```
16
17You'll then need to add the `populateExchange`, that this package exposes.
18
19```js
20import { createClient, cacheExchange, fetchExchange } from 'urql';
21import { populateExchange } from '@urql/exchange-populate';
22
23const client = createClient({
24 url: 'http://localhost:1234/graphql',
25 exchanges: [populateExchange({ schema }), cacheExchange, fetchExchange],
26});
27```
28
29The `schema` option is the introspection result for your backend graphql schema, more information
30about how to get your schema can be found [in the "Schema Awareness" Page of the Graphcache documentation.](https://formidable.com/open-source/urql/docs/graphcache/schema-awareness/#getting-your-schema).
31
32## Example usage
33
34Consider the following queries which have been requested in other parts of your application:
35
36```graphql
37# Query 1
38{
39 todos {
40 id
41 name
42 }
43}
44
45# Query 2
46{
47 todos {
48 id
49 createdAt
50 }
51}
52```
53
54Without the `populateExchange` you may write a mutation like the following which returns a newly created todo item:
55
56```graphql
57# Without populate
58mutation addTodo(id: ID!) {
59 addTodo(id: $id) {
60 id # To update Query 1 & 2
61 name # To update Query 1
62 createdAt # To update Query 2
63 }
64}
65```
66
67By using `populateExchange`, you no longer need to manually specify the selection set required to update your other queries. Instead you can just add the `@populate` directive.
68
69```graphql
70# With populate
71mutation addTodo(id: ID!) {
72 addTodo(id: $id) @populate
73}
74```
75
76> Note: The above two mutations produce an identical GraphQL request.