We made some changes to how mutations work in the new version of Relay in order to makes them more straight forward to use and more customizable. Mutations are currently not covered by an automatic conversion and require a manual upgrade. However, limited number of changes is needed to make your existing mutations work with both the old and new environment.
FatQueries in Relay Classic mutations was a concept that was confusing for a number of people. It required Relay to keep track of a significant amount of metadata regarding each record and automatically figure out the query to send to the server for the mutation. The logic to deduce the queries to send to the server was both complicated to maintain and slow to run. On top of that, we often had questions about why a particular field is included or skipped. We decided to allow people to have more control by allowing them write out exactly what data they want to update as the result of a mutation. Both individual fields and fragments can be included in these queries. Similar to container fragments, this is subjected to masking. That means only fields listed out directly will be accessible in the callbacks and the updater functions. The data fetched by in referenced fragments will still be updated in the store.
Example of existing fat query:
Example of converted mutation query:
This is no longer needed in Compatibility Mode for neither environments. Relay will normalized the data using the mutation query and id to update the store automatically. You can remove it completely.
RANGE_ADD needs one additional property in the config named
connectionInfo to work with the new environment. Learn more about
RANGE_DELETE needs one additional property in the config named
connectionKeys to work with the new environment. Learn more about
NODE_DELETE config will work as-is with the new environment. No change is needed.
Take this example of a simple mutation in Relay Classic:
We combine these two into a regular GraphQL mutation, which list out specific fields that needs to be updated.
As specified above,
FIELDS_CHANGE configs can be omitted.
getVariables(), we take the return value from the original function and wrap it in an object that contains a property that matches the variable name for the mutation. In this case, the mutation has a
input variable that is of type
As you can see, our resulting mutation is a lot simpler and more like regular GraphQL than the Relay Classic version we started out with.
See Mutation for additional options on
commitMutation for more complex mutations.