charlesstover / fetch-suspense

A React hook compatible with React 16.6's Suspense component.

useFetch

useFetch is a React hook that supports the React 16.6 Suspense component implementation.

The design decisions and development process for this package are outlined in the Medium article React Suspense with the Fetch API.

Install

• npm install fetch-suspense or
• yarn add fetch-suspense

Examples

Basic Example

import useFetch from 'fetch-suspense';
import React, { Suspense } from 'react';

// This fetching component will be delayed by Suspense until the fetch request
//   resolves. The return value of useFetch will be the response of the server.
const MyFetchingComponent = () => {
  const response = useFetch('/path/to/api', { method: 'POST' });
  return 'The server responded with: ' + response;
};

// The App component wraps the asynchronous fetching component in Suspense.
// The fallback component (loading text) is displayed until the fetch request
//   resolves.
const App = () => {
  return (
    <Suspense fallback="Loading...">
      <MyFetchingComponent />
    </Suspense>
  );
};

Using a Custom Fetch API

If you don't want to rely on the global fetch API, you can create your own useFetch hook by importing the createUseFetch helper function.

import { createUseFetch } from 'fetch-suspense';
import myFetchApi from 'my-fetch-package';
import React, { Suspense } from 'react';

// Create a useFetch hook using one's own Fetch API.
// NOTE: useFetch hereafter refers to this constant, not the default export of
//   the fetch-suspense package.
const useFetch = createUseFetch(myFetchApi);

// This fetching component will be delayed by Suspense until the fetch request
//   resolves. The return value of useFetch will be the response of the server.
const MyFetchingComponent = () => {
  const response = useFetch('/path/to/api', { method: 'POST' });
  return 'The server responded with: ' + response;
};

// The App component wraps the asynchronous fetching component in Suspense.
// The fallback component (loading text) is displayed until the fetch request
//   resolves.
const App = () => {
  return (
    <Suspense fallback="Loading...">
      <MyFetchingComponent />
    </Suspense>
  );
};

Including Fetch Metadata

To include fetch metadata with your response, include an options parameter with metadata: true.

import useFetch from 'fetch-suspense';
import React, { Suspense } from 'react';

// This fetching component will be delayed by Suspense until the fetch request
//   resolves. The return value of useFetch will be the response of the server
//   AS WELL AS metadata for the request.
const MyFetchingComponent = () => {
  const { contentType, response } = useFetch(
    '/path/to/api',
    { method: 'POST' },
    { metadata: true }, // <--
  );
  return `The server responded with ${contentType}: ${response}`;
};

// The App component wraps the asynchronous fetching component in Suspense.
// The fallback component (loading text) is displayed until the fetch request
//   resolves.
const App = () => {
  return (
    <Suspense fallback="Loading...">
      <MyFetchingComponent />
    </Suspense>
  );
};

Options

The supported options for the third, options parameter are:

lifespan?: number

Default: 0

The number of milliseconds to cache the result of the request. Each time the component mounts before this many milliseconds have passed, it will return the response from the last time this same request was made.

If 0, the cache will be last the remainder of the browser session.

metadata?: boolean

Default: false

If true, the useFetch hook will return metadata in addition to the response from the fetch request. Instead of returning just the response, an interface as follows will be returned:

interface UseFetchResponse {
  bodyUsed: boolean;
  contentType: null | string;
  headers: Headers;
  ok: boolean;
  redirected: boolean;
  // The same response from the server that would be returned if metadata were
  //   false. It is an Object is the server responded with JSON, and it is a
  //   string if the server responded with plain text.
  response: Object | string;
  status: number;
  statusText: string;
  url: string;
}

You can access these properties easily through destructuring. See Including Fetch Metadata.

Sponsor 💗

If you are a fan of this project, you may become a sponsor via GitHub's Sponsors Program.

fetch-suspense's Issues

Add useTransition example to README

fetch-suspense is designed to work with React concurrent mode's Suspense. The fetch-suspense README contains an excellent example of usage with Suspense.

The other main new API in concurrent mode is useTransition. It would be helpful to have a README example showing to use fetch-suspense within a startTransition created by useTransition.

Alternative to 'import * as' module syntax

This will soon no longer be considered valid JavaScript:

import * as useFetch from 'fetch-suspense'

useFetch(/*...*/)

https://stackoverflow.com/questions/39415661/what-does-resolves-to-a-non-module-entity-and-cannot-be-imported-using-this/39415662#39415662

An ES6 module namespace object cannot be invoked as a function or with new.
The thing you import using * as X from a module is defined to only have properties.

As a backwards-compatible change, this module should have something like this added to the bottom of fetch-suspense.ts:

module.exports.useFetch = module.exports

That way we'll be able to do this:

import { useFetch } from 'fetch-suspense'

useFetch(/*...*/)

Metadata is always undefined

Hi, great library! I am testing the metadata parameter, because I expected the hook to throw when receiving a non-200 status code. However, I always get this metadata:

Object {
  "bodyUsed": undefined,
  "contentType": "text/html; charset=utf-8",
  "headers": undefined,
  "ok": undefined,
  "redirected": undefined,
  "response": "...",
  "status": undefined,
  "statusText": undefined,
  "url": undefined,
}

The same request in Postman gives the following status:

Is this a bug, or am I doing something wrong and is it working as designed?

TypeScript complaint: 'fetch-suspense.d.ts' is not a module

More specifically, this is a complaint that happens:

import useFetch from 'fetch-suspense';
//                    ~~~~~~~~~~~~~~~~
// File '/Users/user/repos/Project/node_modules/fetch-suspense/fetch-suspense.d.ts' is not a module.ts(2306)

fetch-suspense.d.ts should export useFetch to indicate that it's exported. Right now, it's implying there's a global const useFetch variable.

Handle fetch error (network timeout/non-2xx responses)

Hello,

I can't figure out how to handle fetch errors with fetch-suspense.
I'd like to show an error message to the user if something fails.
Could you provide an example, possibly with some comments on it?

Thank you!

Support fetching an array of requests.

First of all I'd like to thank your for this awesome package.

But now for a feature request / question.

What if I have a component that needs to do multiple fetch requests before rendering? How would you extend this hook to be able to handle multiple fetch requests?

UMD/standalone version for inclusion via e.g. unpkg.com

Please consider also building a UMD/standalone version.

Cancel the fetch if it has not been completed and props changed

You can read about the AbortController here: https://developer.mozilla.org/en-US/docs/Web/API/AbortController

UseFetch factory for creating the hook with a custom fetch implementation.

export const createUseFetch = fetch => {/*...*/};
export default createUseFetch(global.fetch);

TypeScript 3.6.2 removed GlobalFetch

Similar issue: apollographql/apollo-link#1131

Wamp wump. I can fix this too. 😅

How to handle no internet connection exceptions.

If I go offline, fetch throws and the whole application goes to hell. fetch-suspense should catch the error and return it so it can be handled properly.

maxDuration not being respected

Hi @CharlesStover! First off thanks for writing this package.

The only thing that I noticed was that maxDuration seems to not be respected and the loading spinner seems to show right away. Have you experienced this at all?

Ability to manually clear a cache

Hello!

Thanks for this great library. It's been super helpful and works well.

I'm wondering if its going to be possible ever to trigger a manual cache clear. Say we are loading a user profile on page load. That data doesn't change often, and can be cached. If a user updates their profile though, we will need the ability to clear the cached response in order to trigger a refetch.

Hope this makes sense as a use case, and thanks again!