breaking: Change the error broadcasting behavior in mutations and add throwOnError option

[shuding]

Errors from mutations should be separated from direct fetches. Currently, the returned and shared error state from useSWR will be mutated by mutate calls:

const { error } = useSWR('/api')

mutate('/api', mutator) → this might update `error` if it fails

The main use case for that is to have a global and declarative error indicator for mutations, but then it conflicts with fetching errors (e.g. resource fails to load). With the new useSWRMutation hook, that is no longer needed because we can have a cleaner representation for both:

const { error: loadError } = useSWR('/api')
const { error: actionError } = useSWRMutation('/api')

And they will be separated and scoped to different places:

For example (1) and (2) will always share the same data and error. So if the user fails to load initially, error indicators can be shown in both places (or you can throw to trigger an upper-level error boundary). In (3) and (4) you can trigger remote mutations to update the user resource. If the mutation succeeded, (1) and (2) will be updated and rerendered with the new data. If a mutation from (3) failed, only (3) will get the error state so you can show the error indicator there, without affecting (1) (2) and (4).

throwOnError

Since there is already onError supported in useSWRMutation, here we are adding a new option throwOnError to mutations (both useSWRMutation and mutate) to define if an error should be thrown inline or not. It defaults to true.

// This call will not throw an error if it fails. It will fail silently.
mutate(key, fetcher, {
  throwOnError: false
})

const { trigger, error } = useSWRMutation('/api', mutator, {
  throwOnError: false,
  onError: (err) => { ... }
})

// This call will not throw inline
trigger()

// Override the option:
try {
  await trigger(null, { throwOnError: true })
} catch (err) {
  // ...
}

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 8209d03:

Sandbox	Source
SWR-Basic	Configuration
SWR-States	Configuration
SWR-Infinite	Configuration
SWR-SSR	Configuration

[utg1-tdawg]

@shuding Is there a way to set throwOnError globally? Seems like SWRConfig doesn't accept it as an argument.

[silcro-123]

@shuding Is there a way to set throwOnError globally? Seems like SWRConfig doesn't accept it as an argument.

i have same issue.