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>
  );
};

To install magiql with all its features to your project, run the following commands based on if you use yarn or npm. The single dependency includes multiple entry points to code-split features and not require user to install more dependencies.

yarn add magiql graphql

# or
npm install magiql graphql --save

This is required to use fragments and normalized caching

To use the relay-compiler, add magiql/babel to your Babel config as a plugin, eg. in babel.config.js. The magiql Babel plugin is just a wrapper around babel-plugin-relay to include everything in one dependency. It also runs the relay-compiler in watch mode by default.

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

Or, you can run the compiler from cli using the magiql command (use magiql --watch for watch mode, recommended for development). This is also just a wrapper around the relay-compiler. You still need to add the Babel plugin, but can disable running the compiler with Babel, but setting runWithBabel to false in magiql.config.js.

magiql.config.js

If need to customize the Relay compiler away from the defaults (specified below), add a magiql.config.js file in the root directory. It is very similar to relay.config.js, but tailored a little for magiql.

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/**`,
    ];
 }

With GraphQL, the biggest game changer when used with React are fragments. The useFragment hook introduced by relay makes it delightful to declare the data needs of your components. These are some of the advantages:

• Date requirements completely localized and encapsulated in your component
• Declarative, modular and composable
• Fragments can include nest more fragments and fits naturally with the React component model
• Don't need to add everything to the top level query
• Easy to ensure type safety (using relay-compiler generated files)
• Data available independent of how the data is fetched by some parent component
• Components only subscribe to the precise part of the data store that it cares about (down to the field level).

Usage (with fragments)

// 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>
  );
};

These features and accompanying restrictions provide an excellent authoring experience that almost seems magical when it works.

Using the Relay compiler, magiql can generate types for all your operations since it has access to your schema as well. These types are generated and updated by the compiler, so ensure that it's running in watch mode (either through Babel or the cli) when you are developing.

If the name of query is HomeQuery, then import type as such:

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

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

• Types are imported from the folder specified as artifactDirectory in magiql.config.js (Default: generated).
• Typescript support is enabled by default. To disable it, set language to javascript in magiql.config.js.
• If not using the compiler, you can provide type parameters to each operation with the following sample signature

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

Coming soon

Coming soon

To fully unlock fragments, including optimistic responses and cache manipulation of entities, we needed a normalized cache of our data. We call this cache, the store in magiql.

• Each entity is identified and stored once.
• Component that access entities subscribe to changes to that entity
• Implementation can be customized when creating a GraphQLClient via the useStore option, we provide three implementations of our own (using recoil and react-query's QueryCache)
• Provide your own getDataID to these stores to control how id's are determined and then let magiql handle the rest for managing access.

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),
  }),
});

Store Implementations

• Recoil createRecoilStore
  • Recommended if already working with the compiler and the Babel plugin
  • Each field of an entity is stored as atom, entities and fragments are both selectors on the atoms
  • Components subscribe to fields on entities (very granular and precise)
  • Customize how to determine id for each entity
• React Query's QueryCache as store createNormalizedQueryCacheStore
  • Each entity is a query with the entity's id as the key
  • Components subscribe to entities (not field-level subscriptions)
  • Same API as createRecoilStore
• React Query's QueryCache (unnormalized) createQueryCacheStore
  • Client's QueryCache stores data attached to queries, and doesnt identify entities
  • Doesn't allow cache manipulation with entities
  • No options required since doesn't actually normally, but will still work with Fragments

Relay allows us to use fragments in queries and mutations without importing them as modules. For this to work, the names must be globally unique. It is also good habit to name the fragments and queries based on the components and props that use them. Thus, relay enforces a few conventions when it comes to naming your operations. These conventions are quite helpful and make your lives easier:

• Queries must be named query ${ModuleName}Query { ... }, eg, a query in file Home.tsx can be named HomeQuery or HomeRoomsQuery
• Mutations must be named mutation ${ModuleName}Mutation { ... }, eg, a mutation in file Home.tsx can be named HomeMutation or HomeDestroyMutation
• Fragments must be named fragment ${ModuleName}_${propName} on type { ... }, eg, a fragment in file HomeDetails.tsx where the prop for the fragment ref is home can be named HomeDetails_home

You can use the magiql Devtools which are inspired by react-query-devtools as follows:

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>
  );
}

You can use the magiql Devtools which are inspired by react-query-devtools as follows:

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>
  );
}