magiql

A bunch of simple but magical React hooks to work with GraphQL.
powered by react-query, inspired by relay and urql

A set of React hooks to work with GraphQL data. magiql stands on the shoulders of massive giants in the data-synchronization and state-management space, both conceputally and some as actual dependencies. It uses the amazing react-query library as its data-fetching and synchronization layer which forms the foundation of this library. Seriously, without react-query, this won't be any good. The API is also very similar to react-query and will be familiar to the users. It's just slightly tweaked to make it easier to work with GraphQL. On top of the these great synchronization primitives, we add normalized caching which allows us to enable the amazing developer experience that relay provides without any of the restrictions and buy-in required.

magiql is designed to be easy to adopt (moving from vanilla react-query or other GraphQL clients). Most features (like normalized caching, recoil-based store implementation, relay-compiler and build-time optimizations) are completely optional and configurable. But everything is included under one installed dependency so that you don't have to install things again and again (don't worry, the different entry-points are code-split and you will only include things that you actually use). You can start using magiql as a GraphQL Client immediately and it grows to cater to your needs as they arise by allowing extensive customization and incrementally adoption of more speciliazed features.

Features

Most of the features that we are providing are thanks to react-query. Using inspiration from relay and urql, we are able to provide a bunch of additional awesome GraphQL-specific features that you can find below

• Auto Caching + Refetching (stale-while-revalidate, Window Refocus, Polling/Realtime)
• Parallel + Dependent Queries
• "Lazy" Queries
• Request Deduplication
• Paginated + Cursor-based Queries
• Load-More + Infinite Scroll Queries w/ Scroll Recovery
• Normalized caching + Entity Manipulation (multiple store implementations (recoil, react-query)
• Fragment-first GraphQL approach (relay-style useFragment hook)
• Request Cancellation
• Mutations + Reactive Query Refetching
• Optimistic Updates
• Exchanges API to customize execution (logging, persisted queries, authentication, JWT token refresh)
• React Suspense Support (must be enabled with React Concurrent Mode)
• Dedicated Devtools

Using the relay-compiler (via magiql/babel or magiql cli) is required to unlock some more awesome features,

• Schema-aware Normalized caching
• Typescript Support + Code generation
• Build-time GraphQL optimizations
• Skip parsing at runtime

Note: You don't need a Relay-compliant server to get all these features in magiql. It will work with any GraphQL server. It also doesn't require you to commit to React Concurrent Mode which the new relay hooks require.

There is an example for this: https://magiql.vercel.app. You can see the components and pages folder for example code.

Warning: This is still in alpha stage and docs and examples are in the works

Documentation

import {
  GraphQLClientProvider,
  GraphQLClient,
  useQuery,
  graphql,
} from "magiql";

const client = new GraphQLClient({
  endpoint: "https://swapi-graphql.netlify.app/.netlify/functions/index",
});

const People = () => {
  const { data, status, error } = useQuery(
    graphql`
      query PeopleQuery($limit: Int) {
        allPeople(first: $limit) {
          edges {
            node {
              id
              name
              homeworld {
                name
              }
            }
          }
        }
      }
    `,
    {
      variables: {
        limit: 10,
      },
    }
  );

  if (status === "loading") {
    return <div>Loading...</div>;
  }

  if (error) {
    return <div>{error.message}</div>;
  }

  return (
    <div>
      {data
        ? data.allPeople?.edges?.map((edge) => (
            <div key={edge.node.id}>
              <b>{edge.node.name}</b> ({edge.node.homeworld?.name})
            </div>
          ))
        : null}
    </div>
  );
};

const App = () => {
  return (
    <GraphQLClientProvider client={client}>
      <People />
    </GraphQLClientProvider>
  );
};

yarn add magiql graphql

# or
npm install magiql graphql --save

module.exports {
  presets: [ ... ],
  plugins: ["magiql/babel", ... ]
}

module.exports = {
  schema: "./schema.graphql",
  src: "./",
  artifactDirectory: "generated",
  extensions: ["ts", "tsx", "js", "jsx", "graphql"],
  quiet: false,
  watch: boolean,
  runWithBabel: true,
  language: "typescript",
  include: ["**"],
  exclude: [
      "**/node_modules/**",
      "**/__mocks__/**",
      `**/generated/**`,
    ];
 }

// Person.tsx
import React from "react";
import { useFragment, graphql } from "magiql";
import { Person_person } from "generated/Person_person.graphql";

export function Person({ person }: { person: Person_person }) {
  const data = useFragment(
    graphql`
      fragment Person_person on Person {
        name
        homeworld {
          name
        }
      }
    `,
    person
  );

  return (
    <div>
      <b>{data.name}</b> ({data.homeworld?.name})
    </div>
  );
}

// People.tsx
import React from "react";
import { useQuery, graphql } from "magiql";
import { PeopleQuery } from "generated/PeopleQuery.graphql";
import { Person } from "./Person";

export const People = () => {
  const { data, status, error } = useQuery<PeopleQuery>(
    graphql`
      query PeopleQuery($limit: Int) {
        allPeople(first: $limit) {
          edges {
            node {
              id
              ...Person_person
            }
          }
        }
      }
    `,
    {
      variables: {
        limit: 10,
      },
    }
  );

  return (
    <div>
      {data
        ? data.allPeople?.edges?.map((edge) => <Person person={edge.node} />)
        : null}
    </div>
  );
};

import { GraphQLClientProvider, GraphQLClient } from "magiql";
import { createRecoilStore } from "magiql/recoil-store";
import { People } from "./People";

const client = new GraphQLClient({
  endpoint: "https://swapi-graphql.netlify.app/.netlify/functions/index",
  useStore: createRecoilStore(),
});

const App = () => {
  return (
    <GraphQLClientProvider client={client}>
      <People />
    </GraphQLClientProvider>
  );
};

import { HomeQuery } from "generated/HomeQuery.graphql";
import { useQuery } from "magiql";

const { data, error } = useQuery<HomeQuery>(graphql`
  query HomeQuery {
    currentHome {
      name
    }
  }
`);

type HomeQuery = {
  response: {
    currentHome: {
      name: string;
    };
  };
  variables: {};
};

import { GraphQLClient } from "magiql";
import { createRecoilStore } from "magiql/recoil-store";

const client = new GraphQLClient({
  endpoint: "...",
  useStore: createRecoilStore({
    // optional, by default it uses the `id` field if available otherwise falls back to an unnormalized id
    // this is the default function
    getDataID: (record, type) => (record.id ? `${type}:${record.id}` : null),
  }),
});

import React from "react";
import { GraphQLClient, GraphQLClientProvider } from "magiql";
import GraphQLDevtools from "magiql/devtools";

export default function App({ children }) {
  return (
    <GraphQLClientProvider client={client}>
      {children}
      <GraphQLDevtools defaultIsOpen defaultTab="store" />
    </GraphQLClientProvider>
  );
}

API

The following is the core API for magiql. With the help of amazing libraries like react-query, relay-compiler and recoil, we are able to provide the following features as a GraphQL client. The runtime is your familiar react-query api. There is also an optional build time setup that unlocks fragments and normalized store.

import React from "react";
import { GraphQLClient, GraphQLClientProvider } from "magiql";
import GraphQLDevtools from "magiql/devtools";

export default function App({ children }) {
  return (
    <GraphQLClientProvider client={client}>
      {children}
      <GraphQLDevtools defaultIsOpen defaultTab="store" />
    </GraphQLClientProvider>
  );
}

Runtime

• useQuery(query, { variables, ...options }), usePaginatedQuery and useInfiniteQuery: Data fetching patterns for GraphQL queries with numerous ways to customize them for refetching on different events
  • All options from react-query are valid in the second argument
  • No fetch function or query key required
  • Stale-while-revalidate caching strategy
  • Request deduplication
  • Infinite queries
  • Paginated queries
  • Parallel and dependent queries
  • Lazy queries
  • Window Focus refetching
  • Network Status refetching
  • Polling/interval refetching
  • Normalized caching (uses relay-compiler)
• useMutation: a hook that provides a way to run GraphQL mutations (updates) on the server state conviniently with optmistic updates from your React app
  • Optimistic updates
  • Cache manipulation for entities in store
• useFragment: a hook that allows you to properly encapsulate the date requirements of a component within it by subscribing to a GraphQL Fragment which resolves when provided a ref from the parent component via props
  • Field-level subscription for fragments, only rerenders when that changes
  • Allows nesting of fragments, great deal of composability and reusability
  • Doesn't need to be responsible for fetching data (gets reference from parent component)
  • Requires that you run the relay-compiler with either the Babel plugin or the cli command.
• useGraphQLClient: Access the underlying GraphQLClient
  • Create new client using GraphQLClient class
  • Add the GraphQLClientProvider with an instance of a GraphQLClient
  • Can customize react-query config by using `new GraphQLClient({ endpoint: "...", queryConfig: {...} })
• Exchanges based API for customizing query execution behaviour, allows for,
  • logging, authentication, refreshing tokens, normalization, error handling
• React Suspense support
  • prowered by react-query (must be enabled)
• React Native support
  • Should work out of the box in expo or wherever the react-native package.json property is resolved

Foundation and inspirations

Here are some of the big dependencies and inspirations for magiql:

• react-query

  • Data-fetching (network) layer
  • Stale-while-revalidate caching strategy
  • Request deduplication
  • Window Focus refetching
  • Network Status refetching
  • Infinite queries
  • Paginated queries
  • Parallel and dependent queries
  • Lazy queries
  • Polling/interval refetching
  • React Suspense support
  • Normalized caching (with the help of the relay compiler)
  • Differences:
    • No query key required (GraphQL document name + variables form the key)
    • No query fetch function required (provided by the client with customization options)
    • Pass GraphQL document as first argument

• relay-compiler

  • Build time optimizations (flatten fragments, add id fields, etc.)
  • Code-generation for types (for full typescript support)
  • Using fragments effectively with optimizations
  • Concept: useFragment hook (game changer!) to declaratively define data needs for components independent of the fetching of the data
  • Implementation: relay-runtime inspiration for (de)normalizating data
  • magiql allows us to use the relay hooks API without jumping to React Suspense (can't use the new relay hooks without that)
  • Do not need relay compliant server (will work with any GraphQL server)

• recoil (opt-in)

  • Alternative implementation for normalized cache for data
  • Granular subscription (field-level) to data for fragments and queries based on exactly what they ask
  • similar implementation for jotai is also being worked on

• urql (inspiration)

  • Concept: exchange API to customize execution of graphql request
  • Allowed easy ways to add logging, persisted queries, auth (with token refresh support)