Apollo Component

A render component for easy querying and mutating of your GraphQL API.

Install

npm install @department/apollo-component

Examples

Here is an example of fetching and rendering the data of an imaginary Order.

import { gql } from "graphql-tag"
import { Query } from "@department/apollo-component"
import SingleOrder, { LoadingOrder } from "components/SingleOrder"
import { GenericError, NotFound } from "components/Errors"
const ShowOrderQuery = gql`
  query ShowOrder($id: ID!) {
    Order(id: $id) {
      ...SingleOrder
    }
  }
  ${SingleOrder.fragments.SingleOrder}
`;
const Show = ({ id }) => (
  <Query gql={ShowOrderQuery} variables={{id}}>
    {({ data: { Order }, loading, error, refetch }) =>
      loading ? (
        <LoadingOrder ></LoadingOrder>
      ) : error ? (
        <GenericError error={error} ></GenericError>
      ) : (
        <SingleOrder {...Order} update={refetch} ></SingleOrder>
      )}
  </Query>
));

And another example using <Mutate></Mutate> and fail-props to raise any errors to
the nearest
React 16+ Error Boundary:

import { gql } from "graphql-tag";
import { Mutate, Query } from "@department/apollo-component";
import { Exception } from "components/Exception";
const IncrementMutation = gql`
  mutation IncrementMutation($num: Int!) {
    incr(num: $num)
  }
`;
const ShowCountQuery = gql`
  query ShowCount {
    count
  }
`;
const IncrementView = ({ id }) => (
  <Exception>
    <Query gql={ShowCount} wait fail>
      {({ data: { count } }) => <div>Current count: {count}</div>}
    </Query>
    <Mutate gql={IncrementMutation} refetchQueries={["ShowCount"]} fail>
      {incr => (
        <form onSubmit={e => incr({ num: e.currentTarget.num.valueAsNumber })}>
          <input type="number" name="num" value={1} step={1} />
          <button>+</button>
        </form>
      )}
    </Mutate>
  </Exception>
);

API

<Query ></Query>

Available Props:

• gql
• wait
• lazy
• fail
• skip
• variables

Arguments in render callback

• QueryResults
  • data the loaded data or an empty object
  • loading true while loading (unless the wait-prop was set)
  • skipped true if the request was skipped (using the skip-prop)
  • error Error object if there was any error (unless the fail-props was
    set)
  • refetch(variables) call this function rerun query with, optionally, new
    variables
  • fetchMore(opts) call this function to fetch more (read about the
    opts)

Example:

({ data: { stuff }, loading }) => <div>{loading ? "loading..." : stuff}</div>;

<Mutate ></Mutate>

Available Props:

• gql
• refetchQueries
• optimisticResponse
• update

Arguments in render callback

• Mutate(variables) call this function to trigger the mutation
• QueryResults (like for Query but without skipped)
  • data
  • loading
  • error
  • refetch
  • fetchMore

Example:

(mutate, { data: { stuff }, loading }) => (
  <button onClick={() => mutate()} disabled={loading}>
    {loading ? "loading..." : stuff}
  </button>
);

renderState(client, component, options)

For server side rendering renderState() may be used. It uses a query queue in
the React Context which is populated by <Query></Query> in its componentWillMount()
lifecycle method using a naïve component renderer.

It will by default render the tree repeatedly until all queries, without the
lazy-prop has been completed but the maximum “depth” may be adjusted with the
maxDepth option.

Arguments

• client an instance of ApolloClient
• component the root component, will be wrapped by a <Provider ></Provider> with a
  queue
• RenderStateOptions
  • maxDepth number of attempts to render the tree, defaults to Infinity
    (until no more queries are to be found)

Example

An example which could be used to server side render.

Note how the <Provider></Provider> is not needed in renderState(), it’s because it
wraps the component with a special one.

function renderHTML() {
  return renderState(client, <App ></App>, { maxDepth: 1 })
    .then(() =>
      ReactDOM.renderToString(
        <Provider client={client}>
          <App ></App>
        </Provider>
      )
    )
    .catch(err => {
      // you can let the error throw here
      // or ignore it and let the client side
      // handle it inline
      console.error("failed to render state:", err);
      return renderErrorPage(err);
    });
}