[add your ideas] Recipes for ReasonRelay

[zth]

We're going to add a "Recipes" section to the ReasonRelay docs. These recipes will detail how to do common things that you'll find yourself wanting to do when building an app. The idea is that the recipe will demonstrate both the actual code, as well as describe what concepts are at play (and where you can read more about them), and why you do what you do.

There's a ton to cover - post your ideas for things you'd like to see covered here in this issue. Actual contributions of recipes will be much welcome here too, I just need to set up a structure for all of this first I think.

[zth]

Using fragments outside of React's render method

Fragments are a great way to declare data dependencies for anything in your app relying on data from GraphQL. Something that's a bit hidden is the fact that you can use fragments outside of React's render method via adding @inline to your fragment, and then using Fragment.readInline(fragmentRef). This should be detailed with an example.

[zth]

Inserting added items from a mutation into connections - simple cases

Show how to insert an added item from a mutation into an existing connection in the simplest possible way.

[zth]

Inserting added items from a mutation into connections - advanced cases

Show how to insert an added item from a mutation into an existing connection in more advanced scenarios (multiple connections, can't use __id, etc)

[zth]

Using client side state

Show how to extend existing types and add totally new types client side, and then how to leverage that data.
Show how to piggy-back on the Node interface to write helpers that can update any node in the store in a type safe way.

[ajf-ajf]

'Normal' Pagination (i.e., not 'infinite scrolling')

Show how to extend Relay's default cursor pagination conventions to allow for more typical pagination patterns. e.g., cursors for first and last page, and x number of pages adjacent to the current page.

[zth]

Invalidating things in the store after a mutation

This is an advanced tactic to handle "updating" the store after mutations. Relay allow you to invalidate parts of the store, meaning that the next time the invalidated part is evaluated through a query/fragment/yadayada, Relay will treat it as missing and refetch the whole thing that depends on that. However, this does not happen automatically on invalidating (rather at the next evaluation/render). So Relay also allow you to listen to things being invalidated (and take appropriate actions) by passing the thing's dataId to useSubscribeToInvalidationState.

This is very powerful, but needs to be explained.

[zth]

Handling login/logout

Invalidating the entire store and re-rendering the app after logging out, etc.

[cometkim]

Preloading with router

Show how to interact with preloaded data before and after navigate to a route.

This is one of the important concepts in original Relay examples and gives the user an idea of how to integrate UI with Concurrent mode.

[zth]

Manual store updates after mutations

Cover updating the store imperatively after mutations in general. Most people will hopefully not need to do this at all, but some will, so it's important to cover.

[zth]

Handling uploads

Handling uploads through GraphQL via Relay.

[zth]

Partial rendering

Leveraging suspense and Relay's partial rendering mode to partially render views with existing cached data while waiting for queries.

[marco2216]

Maybe this is what you mean by partial rendering, but I had this issue with rendering data from the store while refetching data in a paginated list. Upon calling the refetch function, the list always suspends, and on the initial refetch, there would be no data in the store (that Relay can identify, in fact we have some list data that we are already displaying). What I ended up doing was creating this refetch 'dummy' component, that would refetch the data, so the main component wouldn't suspend:

// We are using a dummy component to refresh the client list data, so that we avoid suspending when refetching.
// The dummy component will suspend, and the store updates are rendered in the main component.
// StoreAndNetwork doesn't work for refreshing paginated data, because we are changing the "first" variable
// - Relay doesn't know that we already have cached data.
module RefetchDummy = {
  [@react.component]
  let make =
      (
        ~coach,
        ~refreshClientListRef: React.ref(unit => unit),
        ~variables,
        ~onComplete,
      ) => {
    let ReasonRelay.{refetch} = Fragment.usePagination(coach);

    refreshClientListRef.current = (
      () =>
        refetch(
          ~variables,
          ~fetchPolicy=StoreAndNetwork,
          ~onComplete=_ => onComplete(),
          (),
        )
    );

    React.null;
  };
};

It would be great to know how to keep rendering exactly the same thing as before, i.e. a way to prevent suspending, just refetching and letting the cache update the component after receiving new data.

[zth]

@marco2216 Please open a separate issue with that and we can discuss that there :)

[cometkim]

Data-driven code-splitting

Not sure if ReasonRelay supports JSModule, @match, and @module, but I think it is an eye-catching feature of the Relay.

https://mrtnzlml.com/docs/relay/match-module

This could be a topic similar to the preloading section because we have to deal with dynamic imports.

(Maybe my concern is only focused on the CM support 😂)

[cometkim]

This comment is created from issue tracker demo XD