Home

Awesome

relay-hooks

npm npm downloads

Use Relay as React hooks

Installation

Install react-relay and relay-hooks using yarn or npm:

yarn add react-relay relay-hooks

Contributing

relay-hooks

The initial purpose of the library was to provide the ability to use all react-relay HOCs as react hooks and to implement the store-or-network and store-only policies used by the react-relay-offline library to manage offline relay applications

After Relay's core team shared information about the the initial differences in the issue https://github.com/relay-tools/relay-hooks/issues/5, all the necessary changes were made in order to make relay-hooks as close as possible to their specifications.

It is a stable library and none of its dependencies are experimental and it allows you to immediately use react hooks with relay-runtime and it is designed for easy migration to react-relay hooks.

It is a light library and compatible with react-relay

RelayEnvironmentProvider

Since queries with useQuery no longer set context, we will expose a new RelayEnvironmentProvider component that takes an environment and sets it in context; variables will no longer be part of context. A RelayEnvironmentProvider should be rendered once at the root of the app, and multiple useQuery's can be rendered under this environment provider.

import { RelayEnvironmentProvider } from 'relay-hooks';

ReactDOM.render(
  <RelayEnvironmentProvider environment={modernEnvironment}>
    <AppTodo/>
  </RelayEnvironmentProvider>,
  rootElement,
);

useQuery

useQuery does not take an environment as an argument. Instead, it reads the environment set in the context; this also implies that it does not set any React context. In addition to query (first argument) and variables (second argument), useQuery accepts a third argument options.

options

fetchPolicy: determine whether it should use data cached in the Relay store and whether to send a network request. The options are:

fetchKey: [Optional] A fetchKey can be passed to force a refetch of the current query and variables when the component re-renders, even if the variables didn't change, or even if the component isn't remounted (similarly to how passing a different key to a React component will cause it to remount). If the fetchKey is different from the one used in the previous render, the current query and variables will be refetched.

networkCacheConfig: [Optional] Object containing cache config options for the network layer. Note the the network layer may contain an additional query response cache which will reuse network responses for identical queries. If you want to bypass this cache completely, pass {force: true} as the value for this option.

skip: [Optional] If skip is true, the query will be skipped entirely.

onComplete: [Optional] Function that will be called whenever the fetch request has completed

import { useQuery, graphql } from 'relay-hooks';

const query = graphql`
  query appQuery($userId: String) {
    user(id: $userId) {
      ...TodoApp_user
    }
  }
`;

const variables = {
  userId: 'me',
}; 

const options = {
  fetchPolicy: 'store-or-network', //default
  networkCacheConfig: undefined,
}

const AppTodo = function (appProps)  {
  const {data, error, retry, isLoading} = useQuery(query, variables, options);

  if (data && data.user) {
    return <TodoApp user={data.user} />;
  } else if (error) {
    return <div>{error.message}</div>;
  }
  return <div>loading</div>;
}

useLazyLoadQuery

same to useQuery

import * as React from 'react';
import { useQuery, graphql, RelayEnvironmentProvider } from 'relay-hooks';

const query = graphql`
  query appQuery($userId: String) {
    user(id: $userId) {
      ...TodoApp_user
    }
  }
`;

class ErrorBoundary extends React.Component {
  state = { error: null };
  
  componentDidCatch(error) {
    this.setState({ error });
  }

  render() {
    const { children, fallback } = this.props;
    const { error } = this.state;
    if (error) {
      return React.createElement(fallback, { error });
    }
    return children;
  }
}

const variables = {
  userId: 'me',
}; 

const options = {
  fetchPolicy: 'store-or-network', //default
  networkCacheConfig: undefined,
}


const AppTodo = function (appProps) {
  const {data} = useLazyLoadQuery(query, variables, options);
  return <TodoApp user={data.user} />;
}


const App = (
  <RelayEnvironmentProvider environment={modernEnvironment}>
    <ErrorBoundary fallback={({ error }) => `Error: ${error.message + ': ' + error.stack}`}>
      <React.Suspense fallback={<div>loading suspense</div>}>
        <AppTodo />
      </React.Suspense>
    </ErrorBoundary>
  </RelayEnvironmentProvider>
);

useFragment

See useFragment.md

useRefetchable

See useRefetchable.md

usePagination

See usePagination.md

useMutation

See useMutation.md

useSubscription

See useSubscription.md

usePreloadedQuery

See usePreloadedQuery.md