commit c2b9eb5afc9088bda6668f80fff74677d4dbf95b · kitten.sh/urql

docs/basics/README.md

···

       20
       20
        
       - [**Document Caching**](./document-caching.md) explains the default cache mechanism of `urql`, as opposed to the opt-in

     

       21
       21
        
         [Normalized Cache](../graphcache/normalized-caching.md).

     

       22
       22
        
       - [**Errors**](../basics/errors.md) contains information on error handling in `urql`.

     

       23
       23
       +
       - [**UI-Patterns**](../basics/ui-patterns.md) presents some common UI-patterns with `urql`.

+201

docs/basics/ui-patterns.md

···

       1
       1
       +
       ---

     

       2
       2
       +
       title: UI-Patterns

     

       3
       3
       +
       order: 6

     

       4
       4
       +
       ---

     

       5
       5
       +
       

     

       6
       6
       +
       # UI Patterns

     

       7
       7
       +
       

     

       8
       8
       +
       > This page is incomplete. You can help us expanding it by suggesting more patterns or asking us about common problems you're facing on [GitHub Discussions](https://github.com/FormidableLabs/urql/discussions).

     

       9
       9
       +
       

     

       10
       10
       +
       Generally, `urql`'s API surface is small and compact. Some common problems that we're facing when building apps may look like they're not a built-in feature, however, there are several patterns that even a lean UI can support.

     

       11
       11
       +
       This page is a collection of common UI patterns and problems we may face with GraphQL and how we can tackle them in

     

       12
       12
       +
       `urql`. These examples will be written in React but apply to any other framework.

     

       13
       13
       +
       

     

       14
       14
       +
       ## Infinite scrolling

     

       15
       15
       +
       

     

       16
       16
       +
       "Infinite Scrolling" is the approach of loading more data into a page's list without splitting that list up across multiple pages.

     

       17
       17
       +
       

     

       18
       18
       +
       There are a few ways of going about this. In our [normalized caching chapter on the topic](../graphcache/local-resolvers.md#pagination)

     

       19
       19
       +
       we see an approach with `urql`'s normalized cache, which is suitable to get started quickly. However, this approach also requires some UI code as well to keep track of pages.

     

       20
       20
       +
       Let's have a look at how we can create a UI implementation that makes use of this normalized caching feature.

     

       21
       21
       +
       

     

       22
       22
       +
       ```js

     

       23
       23
       +
       import React from 'react';

     

       24
       24
       +
       import { useQuery, gql } from 'urql';

     

       25
       25
       +
       

     

       26
       26
       +
       const PageQuery = gql`

     

       27
       27
       +
         query Page($first: Int!, $after: String) {

     

       28
       28
       +
           todos(first: $first, after: $after) {

     

       29
       29
       +
             nodes {

     

       30
       30
       +
               id

     

       31
       31
       +
               name

     

       32
       32
       +
             }

     

       33
       33
       +
             pageInfo {

     

       34
       34
       +
               hasNextPage

     

       35
       35
       +
               endCursor

     

       36
       36
       +
             }

     

       37
       37
       +
           }

     

       38
       38
       +
         }

     

       39
       39
       +
       `;

     

       40
       40
       +
       

     

       41
       41
       +
       const ListPage = ({ variables, isLastPage }) => {

     

       42
       42
       +
         const [{ data, fetching, error }] = useQuery({ query: PageQuery, variables });

     

       43
       43
       +
         const todos = data?.todos;

     

       44
       44
       +
       

     

       45
       45
       +
         return (

     

       46
       46
       +
           <div>

     

       47
       47
       +
             {error && <p>Oh no... {error.message}</p>}

     

       48
       48
       +
             {fetching && <p>Loading...</p>}

     

       49
       49
       +
             {todos && (

     

       50
       50
       +
               <>

     

       51
       51
       +
                 {todos.nodes.map(todo => (

     

       52
       52
       +
                   <div key={todo.id}>

     

       53
       53
       +
                     {todo.id}: {todo.name}

     

       54
       54
       +
                   </div>

     

       55
       55
       +
                 ))}

     

       56
       56
       +
                 {isLastPage && todos.pageInfo.hasNextPage && (

     

       57
       57
       +
                   <button

     

       58
       58
       +
                     onClick={() => onLoadMore(todos.pageInfo.endCursor)}

     

       59
       59
       +
                   >

     

       60
       60
       +
                     load more

     

       61
       61
       +
                   </button>

     

       62
       62
       +
                 )}

     

       63
       63
       +
               </>

     

       64
       64
       +
             )}

     

       65
       65
       +
           </div>

     

       66
       66
       +
         );

     

       67
       67
       +
       }

     

       68
       68
       +
       

     

       69
       69
       +
       const Search = () => {

     

       70
       70
       +
         const [pageVariables, setPageVariables] = useState([

     

       71
       71
       +
           {

     

       72
       72
       +
             first: 10,

     

       73
       73
       +
             after: '',

     

       74
       74
       +
           },

     

       75
       75
       +
         ]);

     

       76
       76
       +
       

     

       77
       77
       +
         return (

     

       78
       78
       +
           <div>

     

       79
       79
       +
             {pageVariables.map((variables, i) => (

     

       80
       80
       +
               <SearchResultPage

     

       81
       81
       +
                 key={'' + variables.after}

     

       82
       82
       +
                 variables={variables}

     

       83
       83
       +
                 isLastPage={i === pageVariables.length - 1}

     

       84
       84
       +
                 onLoadMore={after =>

     

       85
       85
       +
                   setPageVariables([...pageVariables, { after, first: 10 }])

     

       86
       86
       +
                 }

     

       87
       87
       +
               />

     

       88
       88
       +
             ))}

     

       89
       89
       +
           </div>

     

       90
       90
       +
         );

     

       91
       91
       +
       }

     

       92
       92
       +
       ```

     

       93
       93
       +
       

     

       94
       94
       +
       Here we keep an array of all `variables` we've encountered and use them to render their

     

       95
       95
       +
       respective `result` page. This only rerenders the additional page rather than having a long

     

       96
       96
       +
       list that constantly changes. [You can find a full code example of this pattern in our example folder on the topic of Graphcache pagination.](https://github.com/FormidableLabs/urql/tree/main/examples/with-graphcache-pagination)

     

       97
       97
       +
       

     

       98
       98
       +
       We also do not need to use our normalized cache to achieve this. As long as we're able to split individual lists up into chunks across components, we can also solve this problem entirely in UI code. [Read our example code on how to achieve this.](https://github.com/FormidableLabs/urql/tree/main/examples/with-pagination)

     

       99
       99
       +
       

     

       100
       100
       +
       ## Prefetching data

     

       101
       101
       +
       

     

       102
       102
       +
       We sometimes find it necessary to load data for a new page before that page is opened, for instance while a JS bundle is still loading. We may

     

       103
       103
       +
       do this with help of the `Client`, by calling methods without using the React bindings directly.

     

       104
       104
       +
       

     

       105
       105
       +
       ```js

     

       106
       106
       +
       import React from 'react';

     

       107
       107
       +
       import { useClient, gql } from 'urql';

     

       108
       108
       +
       

     

       109
       109
       +
       const TodoQuery = gql`

     

       110
       110
       +
         query Todo($id: ID!) {

     

       111
       111
       +
           todo(id: $id) {

     

       112
       112
       +
             id

     

       113
       113
       +
             name

     

       114
       114
       +
           }

     

       115
       115
       +
         }

     

       116
       116
       +
       `;

     

       117
       117
       +
       

     

       118
       118
       +
       const Component = () => {

     

       119
       119
       +
         const client = useClient();

     

       120
       120
       +
         const router = useRouter();

     

       121
       121
       +
       

     

       122
       122
       +
         const transitionPage = React.useCallback(async (id) => {

     

       123
       123
       +
           const loadJSBundle = import('./page.js');

     

       124
       124
       +
           const loadData = client.query(TodoQuery, { id }).toPromise();

     

       125
       125
       +
           await Promise.all([loadJSBundle, loadData]);

     

       126
       126
       +
           router.push(`/todo/${id}`);

     

       127
       127
       +
         }, []);

     

       128
       128
       +
       

     

       129
       129
       +
         return (

     

       130
       130
       +
           <button onClick={() => transitionPage('1')}>

     

       131
       131
       +
             Go to todo 1

     

       132
       132
       +
           </button>

     

       133
       133
       +
         )

     

       134
       134
       +
       }

     

       135
       135
       +
       ```

     

       136
       136
       +
       

     

       137
       137
       +
       Here we're calling `client.query` to prepare a query when the transition begins.

     

       138
       138
       +
       We then call `toPromise()` on this query which activates it. Our `Client` and its cache share results, which means that we've already kicked off or even completed the query before we're on the new page.

     

       139
       139
       +
       

     

       140
       140
       +
       ## Lazy query

     

       141
       141
       +
       

     

       142
       142
       +
       It's often required to "lazily" start a query, either at a later point or imperatively. This means that we don't start a query when a new component is mounted immediately.

     

       143
       143
       +
       

     

       144
       144
       +
       Parts of `urql` that automatically start, like the `useQuery` hook, have a concept of a [`pause` option.](./react-preact.md#pausing-usequery) This option is used to prevent the hook from automatically starting a new query.

     

       145
       145
       +
       

     

       146
       146
       +
       ```js

     

       147
       147
       +
       import React from 'react';

     

       148
       148
       +
       import { useQuery, gql } from 'urql';

     

       149
       149
       +
       

     

       150
       150
       +
       const TodoQuery = gql`

     

       151
       151
       +
         query Todos {

     

       152
       152
       +
           todos {

     

       153
       153
       +
             id

     

       154
       154
       +
             name

     

       155
       155
       +
           }

     

       156
       156
       +
         }

     

       157
       157
       +
       `;

     

       158
       158
       +
       

     

       159
       159
       +
       const Component = () => {

     

       160
       160
       +
         const [result, fetch] = useQuery({ query: TodoQuery });

     

       161
       161
       +
         const router = useRouter();

     

       162
       162
       +
       

     

       163
       163
       +
         return (

     

       164
       164
       +
           <button onClick={fetch}>

     

       165
       165
       +
             Load todos

     

       166
       166
       +
           </button>

     

       167
       167
       +
         )

     

       168
       168
       +
       }

     

       169
       169
       +
       ```

     

       170
       170
       +
       

     

       171
       171
       +
       We can unpause the hook to start fetching, or, like in this example, call its returned function to manually kick off the query.

     

       172
       172
       +
       

     

       173
       173
       +
       ## Reacting to focus and stale time

     

       174
       174
       +
       

     

       175
       175
       +
       In urql we leverage our extensibility pattern named "Exchanges" to manipulate the way

     

       176
       176
       +
       data comes in and goes out of our client.

     

       177
       177
       +
       

     

       178
       178
       +
       - [Stale time](https://github.com/FormidableLabs/urql/tree/main/exchanges/request-policy)

     

       179
       179
       +
       - [Focus](https://github.com/FormidableLabs/urql/tree/main/exchanges/refocus)

     

       180
       180
       +
       

     

       181
       181
       +
       When we want to introduce one of these patterns we add the package and add it to the `exchanges`

     

       182
       182
       +
       property of our `Client`. In the case of these two we'll have to add it before the cache

     

       183
       183
       +
       else our requests will never get upgraded.

     

       184
       184
       +
       

     

       185
       185
       +
       ```js

     

       186
       186
       +
       import { createClient, dedupExchange, cacheExchange, fetchExchange } from 'urql';

     

       187
       187
       +
       import { refocusExchange } from '@urql/exchange-refocus';

     

       188
       188
       +
       

     

       189
       189
       +
       const client = createClient({

     

       190
       190
       +
         url: 'some-url',

     

       191
       191
       +
         exchanges: [

     

       192
       192
       +
           dedupExchange,

     

       193
       193
       +
           refocusExchange(),

     

       194
       194
       +
           cacheExchange,

     

       195
       195
       +
           fetchExchange,

     

       196
       196
       +
         ]

     

       197
       197
       +
       })

     

       198
       198
       +
       ```

     

       199
       199
       +
       

     

       200
       200
       +
       That's all we need to do to react to these patterns.

     

       201
       201
       +