Skip to main content
Version: 4.5

Installation

Rest Hooks is a library for fetching structured data in a performant way with no boilerplate.

Its interface is declarative and minimal. A small structure declaration is all that is needed for Rest Hooks to perform numerous fetching and caching optimizations while providing predictable, precisely-typed data to consume.

Structured data means data composed of Objects (maps) and Arrays (lists), as opposed media like images and videos. This makes it great for API calls regardless of form (REST-like, GraphQL, gRPC), serialization (JSON, YAML), or transport (HTTP, WebSockets, local).

Install rest-hooks​

Install the rest-hooks package into your project using yarn

yarn add rest-hooks
npm install rest-hooks

Legacy browser (IE) support​

Rest Hooks includes multiple bundles including a commonjs bundle that is compiled with maximum compatibility as well as an ES6 module bundle that is compiled to target modern browsers or react native. Tools like webpack or rollup will use the ES6 modules to enable optimizations like tree-shaking. However, the Javascript included will not support legacy browsers like Internet Explorer. If your browser target includes such browsers (you'll likely see something like Uncaught TypeError: Class constructor Resource cannot be invoked without 'new') you will need to follow the steps below.

Transpile Rest Hooks package​

Note: Many out-of-the-box solutions like create react app will already perform this step and no additional work is needed.

Add preset to run only legacy transformations.

yarn add --dev babel-preset-react-app
npm install babel-preset-react-app

Add this section to your webpack.config.js under the 'rules' section.

This will only run legacy transpilation, and skip all other steps as they are unneeded.

rules: [
  // put other js rules here
  {
    test: /\.(js|mjs)$/,
    use: ['babel-loader'],
    include: [/node_modules/],
    exclude: /@babel(?:\/|\\{1,2})runtime/,
    options: {
      babelrc: false,
      configFile: false,
      compact: false,
      presets: [
        [
          require.resolve('babel-preset-react-app/dependencies'),
          { helpers: true },
        ],
      ],
      cacheDirectory: true,
    },
  },
]

Polyfills​

Use CRA polyfill or follow instructions below.

yarn add core-js whatwg-fetch
npm install core-js whatwg-fetch

index.tsx​

import 'core-js/stable';
import 'whatwg-fetch';
// place the above line at top

Add provider at top-level component​

index.tsx​

import { CacheProvider } from 'rest-hooks';
import ReactDOM from 'react-dom';

ReactDOM.render(
  <CacheProvider>
    <App />
  </CacheProvider>,
  document.body
);

Alternatively integrate state with redux

Add Suspense and ErrorBoundary​

Suspense will show a fallback while content is loading.

Put the <Suspense/> component around the point where you want the fallback to be shown. Any usage of the hooks will need to be below this point in the tree.

Feel free to hook up multiple <Suspense/> points if you want to show loaders at different points in your application.

<NetworkErrorBoundary/> will handle fallbacks upon any network errors.

App.tsx​

import { Suspense } from 'react';
import { NetworkErrorBoundary } from 'rest-hooks';

const App = () => (
  <div>
    <h1>Main Title</h1>
    <Nav />
    <Suspense fallback={<Spinner />}>
      <NetworkErrorBoundary>
        <Routes />
      </NetworkErrorBoundary>
    </Suspense>
  </div>
);

More about loading state