useFetch

npm i use-http

Features

• SSR (server side rendering) support
• TypeScript support
• 2 dependencies (use-ssr, urs)
• GraphQL support (queries + mutations)
• Provider to set default url and options
• Request/response interceptors
• React Native support
• Aborts/Cancels pending http requests when a component unmounts
• Built in caching
• Persistent caching support
• Suspense^{(experimental)} support
• Retry functionality

Usage

Examples + Videos

• useFetch - managed state, request, response, etc.
• useFetch - request/response interceptors
• useFetch - retries, retryOn, retryDelay
• useFetch - abort, timeout, onAbort, onTimeout
• useFetch - persist, cache
• useFetch - cacheLife, cachePolicy
• useFetch - suspense ^{(experimental)}
• useFetch - pagination
• useQuery - GraphQL
• useFetch - Next.js
• useFetch - create-react-app

Basic Usage Managed State useFetch

If the last argument of `useFetch` is not a dependency array `[]`, then it will not fire until you call one of the http methods like `get`, `post`, etc. ```js import useFetch from 'use-http' function Todos() { const [todos, setTodos] = useState([]) const { get, post, response, loading, error } = useFetch('https://example.com') useEffect(() => { initializeTodos() }, []) // componentDidMount async function initializeTodos() { const initialTodos = await get('/todos') if (response.ok) setTodos(initialTodos) } async function addTodo() { const newTodo = await post('/todos', { title: 'my new todo' }) if (response.ok) setTodos([...todos, newTodo]) } return ( <> Add Todo {error && 'Error!'} {loading && 'Loading...'} {todos.map(todo => (

{todo.title}

))} ) } ```

Suspense Mode^{(experimental)} Auto-Managed State

Can put `suspense` in 2 places. Either `useFetch` (A) or `Provider` (B). ```js import useFetch, { Provider } from 'use-http' function Todos() { const { data: todos = [] } = useFetch('/todos', { suspense: true // A. can put `suspense: true` here }, []) // onMount return todos.map(todo =>

{todo.title}

) } function App() { const options = { suspense: true // B. can put `suspense: true` here too } return ( ) } ```

Pagination + Provider

The `onNewData` will take the current data, and the newly fetched data, and allow you to merge the two however you choose. In the example below, we are appending the new todos to the end of the current todos. ```jsx import useFetch, { Provider } from 'use-http' const Todos = () => { const [page, setPage] = useState(1) const { data = [], loading } = useFetch(`/todos?page=${page}&amountPerPage=15`, { onNewData: (currTodos, newTodos) => [...currTodos, ...newTodos], // appends newly fetched todos perPage: 15, // stops making more requests if last todos fetched < 15 }, [page]) // runs onMount AND whenever the `page` updates (onUpdate) return (

{data.map(todo =>
• {todo.title}
} {loading && 'Loading...'} {!loading && ( setPage(page + 1)}>Load More Todos )}

) } const App = () => ( ) ```

Destructured useFetch

⚠️ Do not destructure the `response` object! Details in [this video](https://youtu.be/_-GujYZFCKI?list=PLZIwrWkE9rCdUybd8t3tY-mUMvXkCdenW&t=127). Technically you can do it, but if you need to access the `response.ok` from, for example, within a component's onClick handler, it will be a stale value for `ok` where it will be correct for `response.ok`. ️️⚠️ ```js var [request, response, loading, error] = useFetch('https://example.com') // want to use object destructuring? You can do that too var { request, response, // 🚨 Do not destructure the `response` object! loading, error, data, cache, // methods: get, set, has, delete, clear (like `new Map()`) get, post, put, patch, delete // don't destructure `delete` though, it's a keyword del, // <- that's why we have this (del). or use `request.delete` head, options, connect, trace, mutate, // GraphQL query, // GraphQL abort } = useFetch('https://example.com') // 🚨 Do not destructure the `response` object! // 🚨 This just shows what fields are available in it. var { ok, status, headers, data, type, statusText, url, body, bodyUsed, redirected, // methods json, text, formData, blob, arrayBuffer, clone } = response var { loading, error, data, cache, // methods: get, set, has, delete, clear (like `new Map()`) get, post, put, patch, delete // don't destructure `delete` though, it's a keyword del, // <- that's why we have this (del). or use `request.delete` mutate, // GraphQL query, // GraphQL abort } = request ```

Relative routes useFetch

```jsx var request = useFetch('https://example.com') request.post('/todos', { no: 'way' }) ```

Abort useFetch

```jsx const { get, abort, loading, data: repos } = useFetch('https://api.github.com/search/repositories?q=') // the line below is not isomorphic, but for simplicity we're using the browsers `encodeURI` const searchGithubRepos = e => get(encodeURI(e.target.value)) <> Abort {loading ? 'Loading...' : repos.data.items.map(repo => (

{repo.name}

))} ```

{request.data}

{request.data}

Provider using the GraphQL useMutation and useQuery

##### Query for todos ```jsx import { useQuery } from 'use-http' export default function QueryComponent() { // can also do it this way: // const [data, loading, error, query] = useQuery` // or this way: // const { data, loading, error, query } = useQuery` const request = useQuery` query Todos($userID string!) { todos(userID: $userID) { id title } } ` const getTodosForUser = id => request.query({ userID: id }) return ( <> getTodosForUser('theUsersID')}>Get User's Todos {request.loading ? 'Loading...' :

{request.data}

} ) } ``` ##### Add a new todo ```jsx import { useMutation } from 'use-http' export default function MutationComponent() { const [todoTitle, setTodoTitle] = useState('') // can also do it this way: // const request = useMutation` // or this way: // const { data, loading, error, mutate } = useMutation` const [data, loading, error, mutate] = useMutation` mutation CreateTodo($todoTitle string) { todo(title: $todoTitle) { id title } } ` const createTodo = () => mutate({ todoTitle }) return ( <> setTodoTitle(e.target.value)} /> Create Todo {loading ? 'Loading...' :

{data}

} ) } ``` ##### Adding the Provider These props are defaults used in every request inside the ``. They can be overwritten individually ```jsx import { Provider } from 'use-http' import QueryComponent from './QueryComponent' import MutationComponent from './MutationComponent' function App() { const options = { headers: { Authorization: 'Bearer YOUR_TOKEN_HERE' } } return ( ) } ```

Request/Response Interceptors

This example shows how we can do authentication in the `request` interceptor and how we can camelCase the results in the `response` interceptor ```jsx import { Provider } from 'use-http' import { toCamel } from 'convert-keys' function App() { let [token, setToken] = useLocalStorage('token') const options = { interceptors: { // every time we make an http request, this will run 1st before the request is made // url, path and route are supplied to the interceptor // request options can be modified and must be returned request: async ({ options, url, path, route }) => { if (isExpired(token)) { token = await getNewToken() setToken(token) } options.headers.Authorization = `Bearer ${token}` return options }, // every time we make an http request, before getting the response back, this will run response: async ({ response, request }) => { // unfortunately, because this is a JS Response object, we have to modify it directly. // It shouldn't have any negative affect since this is getting reset on each request. const res = response if (res.data) res.data = toCamel(res.data) return res } } } return ( ) } ```

Handling Different Response Types

This example shows how we can get `.json()`, `.text()`, `.formData()`, `.blob()`, `.arrayBuffer()`, and all the other [http response methods](https://developer.mozilla.org/en-US/docs/Web/API/Response#Methods). By default, `useFetch` 1st tries to call `response.json()` under the hood, if that fails it's backup is `response.text()`. If that fails, then you need a different response type which is where this comes in. ```js import useFetch from 'use-http' const App = () => { const [name, setName] = useState('') const { get, loading, error, response } = useFetch('http://example.com') const handleClick = async () => { await get('/users/1?name=true') // will return just the user's name const text = await response.text() setName(text) } return ( <> Load Data {error && error.messge} {loading && "Loading..."} {name &&

{name}

} ) } ```

Retries retryOn & retryDelay

In this example you can see how `retryOn` will retry on a status code of `305`, or if we choose the `retryOn()` function, it returns a boolean to decide if we will retry. With `retryDelay` we can either have a fixed delay, or a dynamic one by using `retryDelay()`. Make sure `retries` is set to at minimum `1` otherwise it won't retry the request. If `retries > 0` without `retryOn` then by default we always retry if there's an error or if `!response.ok`. If `retryOn: [400]` and `retries > 0` then we only retry on a response status of `400`. ```js import useFetch from 'use-http' const TestRetry = () => { const { response, get } = useFetch('https://httpbin.org/status/305', { // make sure `retries` is set otherwise it won't retry retries: 1, retryOn: [305], // OR retryOn: async ({ attempt, error, response }) => { // returns true or false to determine whether to retry return error || response && response.status >= 300 }, retryDelay: 3000, // OR retryDelay: ({ attempt, error, response }) => { // exponential backoff return Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) // linear backoff return attempt * 1000 } }) return ( <> get()}>CLICK

{JSON.stringify(response, null, 2)}

) } ```

Overview

Hooks

Options

This is exactly what you would pass to the normal js fetch, with a little extra. All these options can be passed to the <Provider options={/* every option below */} />, or directly to useFetch. If you have both in the <Provider /> and in useFetch, the useFetch options will overwrite the ones from the <Provider />

const options = {
  // accepts all `fetch` options such as headers, method, etc.

  // The time in milliseconds that cache data remains fresh.
  cacheLife: 0,

  // Cache responses to improve speed and reduce amount of requests
  // Only one request to the same endpoint will be initiated unless cacheLife expires for 'cache-first'.
  cachePolicy: 'cache-first', // 'no-cache'

  // set's the default for the `data` field
  data: [],

  // typically, `interceptors` would be added as an option to the `<Provider />`
  interceptors: {
    request: async ({ options, url, path, route }) => { // `async` is not required
      return options // returning the `options` is important
    },
    response: async ({ response, request }) => {
      // notes:
      // - `response.data` is equivalent to `await response.json()`
      // - `request` is an object matching the standard fetch's options
      return response // returning the `response` is important
    }
  },

  // set's the default for `loading` field
  loading: false,

  // called when aborting the request
  onAbort: () => {},

  // runs when an error happens.
  onError: ({ error }) => {},

  // this will allow you to merge the `data` for pagination.
  onNewData: (currData, newData) => {
    return [...currData, ...newData] 
  },

  // called when the request times out
  onTimeout: () => {},

  // this will tell useFetch not to run the request if the list doesn't haveMore. (pagination)
  // i.e. if the last page fetched was < 15, don't run the request again
  perPage: 15,

  // Allows caching to persist after page refresh. Only supported in the Browser currently.
  persist: false,

  // this would basically call `await response.json()`
  // and set the `data` and `response.data` field to the output
  responseType: 'json',
  // OR can be an array. It's an array by default.
  // We will try to get the `data` by attempting to extract
  // it via these body interface methods, one by one in
  // this order. We skip `formData` because it's mostly used
  // for service workers.
  responseType: ['json', 'text', 'blob', 'arrayBuffer'],

  // amount of times it should retry before erroring out
  retries: 3,

  // The time between retries
  retryDelay: 10000,
  // OR
  // Can be a function which is used if we want change the time in between each retry
  retryDelay({ attempt, error, response }) {
    // exponential backoff
    return Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)
    // linear backoff
    return attempt * 1000
  },

  // make sure `retries` is set otherwise it won't retry
  // can retry on certain http status codes
  retryOn: [503],
  // OR
  async retryOn({ attempt, error, response }) {
    // retry on any network error, or 4xx or 5xx status codes
    if (error !== null || response.status >= 400) {
      console.log(`retrying, attempt number ${attempt + 1}`);
      return true;
    }
  },

  // enables experimental React Suspense mode
  suspense: true, // defaults to `false`

  // amount of time before the request get's canceled/aborted
  timeout: 10000,
}

useFetch(options)
// OR
<Provider options={options}><ResOfYourApp /></Provider>

Who's using use-http?

Does your company use use-http? Consider sponsoring the project to fund new features, bug fixes, and more.

Browser Support

If you need support for IE, you will need to add additional polyfills. The React docs suggest these polyfills, but from this issue we have found it to work fine with the react-app-polyfill. If you have any updates to this browser list, please submit a PR!

[]() Edge	[]() Firefox	[]() Chrome	[]() Safari	[]() Opera
12+	last 2 versions	last 2 versions	last 2 versions	last 2 versions

Feature Requests/Ideas

If you have feature requests, submit an issue to let us know what you would like to see!

Todos

• [ ] OSS analytics

• [ ] contributors

• [ ] prefetching

• [ ] global cache state management

• [ ] optimistic updates

• [ ] persist support for React Native

• [ ] better loading state management. When using only 1 useFetch in a component and we use Promise.all([get('/todos/1'), get('/todos/2')]) then don't have a loading true, loading false on each request. Just have loading true on 1st request, and loading false on last request.

• [ ] is making a gitpod useful here? 🤔

• [ ] suspense

  • [ ] triggering it from outside the <Suspense /> component.
  • add .read() to request
  • or make it work with just the suspense: true option
  • both of these options need to be thought out a lot more^
  • [ ] tests for this^ (triggering outside)
  • [ ] cleanup tests in general. Snapshot tests are unpredictably not working for some reason.
  • snapshot test resources: swr, react-apollo-hooks
  • basic test resources: fetch-suspense, @testing-library/react-hooks suspense PR

• [ ] maybe add translations like this one

• [ ] maybe add contributors all-contributors

• [ ] add sponsors similar to this

• [ ] Error handling

  • [ ] if calling response.json() and there is no response yet

• [ ] tests

  • [ ] tests for SSR
  • [ ] tests for react native see here
  • [ ] tests for GraphQL hooks useMutation + useQuery
  • [ ] tests for stale response see this PR
  • [ ] tests to make sure response.formData() and some of the other http response methods work properly
  • [ ] the onMount works properly with all variants of passing useEffect(fn, [request.get]) and not causing an infinite loop
  • [ ] async tests for interceptors.response
  • [ ] aborts fetch on unmount
  • [ ] does not abort fetch on every rerender
  • [ ] retryDelay and timeout are both set. It works, but is annoying to deal with timers in tests. resource
  • [ ] timeout with retries > 0. (also do retires > 1) Need to figure out how to advance timers properly to write this and the test above

• [ ] take a look at how react-apollo-hooks work. Maybe ad useSubscription and const request = useFetch(); request.subscribe() or something along those lines

• [ ] make this a github package

  • see ava packages

• [ ] Documentation:

  • [ ] show comparison with Apollo
  • [ ] figure out a good way to show side-by-side comparisons
  • [ ] show comparison with Axios

• [ ] potential option ideas

  const request = useFetch({
  graphql: {
    // all options can also be put in here
    // to overwrite those of `useFetch` for
    // `useMutation` and `useQuery`
  },
  // by default this is true, but if set to false
  // then we default to the responseType array of trying 'json' first, then 'text', etc.
  // hopefully I get some answers on here: https://bit.ly/3afPlJS
  responseTypeGuessing: true,
  
  // Allows you to pass in your own cache to useFetch
  // This is controversial though because `cache` is an option in the requestInit
  // and it's value is a string. See: https://developer.mozilla.org/en-US/docs/Web/API/Request/cache
  // One possible solution is to move the default `fetch`'s `cache` to `cachePolicy`.
  // I don't really like this solution though.
  // Another solution is to only allow the `cache` option with the `<Provider cache={new Map()} />`
  cache: new Map(),
  // these will be the exact same ones as Apollo's
  cachePolicy: 'cache-and-network', 'network-only', 'cache-only', 'no-cache' // 'cache-first'
  // potential idea to fetch on server instead of just having `loading` state. Not sure if this is a good idea though
  onServer: true,
  onSuccess: (/* idk what to put here */) => {},
  // if you would prefer to pass the query in the config
  query: `some graphql query`
  // if you would prefer to pass the mutation in the config
  mutation: `some graphql mutation`
  refreshWhenHidden: false,
  })
  
  // potential for causing a rerender after clearing cache if needed
  request.cache.clear(true)

• [ ] potential option ideas for GraphQL

  const request = useQuery({ onMount: true })`your graphql query`
  
  const request = useFetch(...)
  const userID = 'some-user-uuid'
  const res = await request.query({ userID })`
  query Todos($userID string!) {
    todos(userID: $userID) {
      id
      title
    }
  }
  `

• [ ] make code editor plugin/package/extension that adds GraphQL syntax highlighting for useQuery and useMutation 😊

• [ ] add React Native test suite