Apollo vs urql vs graphql-hooks: Architecture and Usage Compared

Building GraphQL applications in React requires a client to handle caching, network requests, and state management. While apollo-client and react-apollo defined the early standard, they are now legacy packages. urql and graphql-hooks offer modern alternatives with different philosophies. Let's compare how they handle setup, data fetching, and caching.

⚠️ Critical Note on Apollo Packages

Both apollo-client and react-apollo are deprecated. They represent Apollo version 2. The current standard is @apollo/client, which merges these two packages into one. For the sake of this comparison, we will show the legacy API to illustrate the historical context, but you should not use these packages in new work.

🛠️ Setup and Configuration

apollo-client handles the core logic like caching and networking. It requires a separate React binding package to work in UI components.

// apollo-client: Core instantiation
import ApolloClient from 'apollo-client';
import { InMemoryCache } from 'apollo-cache-inmemory';

const client = new ApolloClient({
  uri: 'https://api.example.com/graphql',
  cache: new InMemoryCache()
});

react-apollo provides the React context provider to make the client available across your app. It depends on the core client above.

// react-apollo: React Provider
import { ApolloProvider } from 'react-apollo';

function App() {
  return <ApolloProvider client={client}>{/* children */}</ApolloProvider>;
}

graphql-hooks combines client creation and React context in a similar modular way but focuses on hooks from the start.

// graphql-hooks: Client and Provider
import { GraphQLClient, GraphQLHooksProvider } from 'graphql-hooks';

const client = new GraphQLClient({ url: 'https://api.example.com/graphql' });

function App() {
  return <GraphQLHooksProvider client={client}>{/* children */}</GraphQLHooksProvider>;
}

urql uses a unified client creation function and a standard Provider component. It is known for its concise setup.

// urql: Client and Provider
import { createClient, Provider } from 'urql';

const client = createClient({ url: 'https://api.example.com/graphql' });

function App() {
  return <Provider value={client}>{/* children */}</Provider>;
}

📥 Fetching Data in Components

apollo-client does not have React hooks built-in. You must use the core API manually or rely on react-apollo for component integration.

// apollo-client: Core API usage (non-React)
client.query({
  query: GET_USER,
  variables: { id: 1 }
}).then(({ data }) => {
  console.log(data);
});

react-apollo introduces the useQuery hook to handle loading and error states within React components.

// react-apollo: React Hook
import { useQuery } from 'react-apollo';

function UserProfile() {
  const { loading, data } = useQuery(GET_USER, { variables: { id: 1 } });
  if (loading) return <p>Loading...</p>;
  return <div>{data.user.name}</div>;
}

graphql-hooks offers a very similar hook API, keeping the interface familiar for those switching from Apollo.

// graphql-hooks: React Hook
import { useQuery } from 'graphql-hooks';

function UserProfile() {
  const { loading, data } = useQuery(GET_USER, { variables: { id: 1 } });
  if (loading) return <p>Loading...</p>;
  return <div>{data.user.name}</div>;
}

urql also uses a useQuery hook but returns an array-like structure or object depending on version, focusing on simplicity.

// urql: React Hook
import { useQuery } from 'urql';

function UserProfile() {
  const [result] = useQuery({ query: GET_USER, variables: { id: 1 } });
  const { loading, data } = result;
  if (loading) return <p>Loading...</p>;
  return <div>{data.user.name}</div>;
}

🗄️ Caching Strategy

apollo-client uses a normalized cache by default. It stores objects by ID, allowing updates to reflect across different queries automatically.

// apollo-client: Normalized Cache
// Automatically updates any component showing user:1 
// if you write to the cache elsewhere
client.writeQuery({
  query: GET_USER,
  variables: { id: 1 },
  data: { user: { name: 'New Name' } }
});

react-apollo relies entirely on the core client's cache. It does not add caching logic itself but exposes tools to interact with it.

// react-apollo: Cache Interaction
import { useApolloClient } from 'react-apollo';

function UpdateButton() {
  const client = useApolloClient();
  // Interact with the same cache as apollo-client
  client.writeQuery({ ... });
}

graphql-hooks has a simpler cache implementation. It is less opinionated and does not normalize data by default, which reduces complexity but requires manual updates.

// graphql-hooks: Manual Cache
// No automatic normalization
// You must manage cache keys and updates manually
client.setQueryData({ query: GET_USER, variables: { id: 1 } }, newData);

urql uses a configurable cache exchange. It supports normalized caching via an additional package but defaults to a simpler document cache for flexibility.

// urql: Cache Exchange
import { cacheExchange } from '@urql/core';
// Enable normalized caching explicitly
const client = createClient({
  url: '...',
  exchanges: [cacheExchange, fetchExchange]
});

🔄 Handling Mutations

apollo-client handles mutations through the core client method, returning promises.

// apollo-client: Core Mutation
client.mutate({
  mutation: UPDATE_USER,
  variables: { id: 1, name: 'New' }
});

react-apollo provides a useMutation hook that returns a trigger function and state.

// react-apollo: Mutation Hook
import { useMutation } from 'react-apollo';

function EditForm() {
  const [updateUser] = useMutation(UPDATE_USER);
  return <button onClick={() => updateUser({ variables: { id: 1 } })}>Save</button>;
}

graphql-hooks mirrors the Apollo hook pattern closely for mutations.

// graphql-hooks: Mutation Hook
import { useMutation } from 'graphql-hooks';

function EditForm() {
  const [updateUser] = useMutation(UPDATE_USER);
  return <button onClick={() => updateUser({ variables: { id: 1 } })}>Save</button>;
}

urql uses a useMutation hook that returns an array with the execute function and result state.

// urql: Mutation Hook
import { useMutation } from 'urql';

function EditForm() {
  const [result, executeMutation] = useMutation(UPDATE_USER);
  return <button onClick={() => executeMutation({ variables: { id: 1 } })}>Save</button>;
}

🤝 Similarities: Shared Ground

Despite their differences, all these libraries aim to solve the same problems. Here are key overlaps:

1. ⚛️ React Hook Integration

• All modern interfaces (including legacy react-apollo) rely on hooks for data fetching.
• They manage loading, error, and data states similarly.

// Common pattern across react-apollo, urql, graphql-hooks
const { loading, data, error } = useQuery(MY_QUERY);

2. 🌐 HTTP Transport

• All packages send POST requests to a GraphQL endpoint by default.
• They support custom headers for authentication tokens.

// All support custom headers
// apollo-client: new HttpLink({ headers: { Authorization: '...' } })
// urql: createClient({ fetchOptions: { headers: { ... } } })
// graphql-hooks: new GraphQLClient({ headers: { ... } })

3. 🛠️ Developer Tools

• All support TypeScript definitions for type safety.
• They integrate with React DevTools for debugging state.

// All packages ship with .d.ts files
// import { useQuery } from 'urql'; // Fully typed

📊 Summary: Key Differences

💡 The Big Picture

apollo-client and react-apollo are legacy tools. They established the patterns we use today but are no longer maintained. If you are on these, plan a migration to @apollo/client.

graphql-hooks is like a lightweight utility belt 🎒 — perfect for small projects or teams that want to avoid the complexity of a normalized cache. It gets the job done with minimal setup.

urql is like a modular engineering kit 🧰 — ideal for teams that want a balance between performance and flexibility. Its exchange system lets you customize behavior without rewriting the core client.

Final Thought: For new projects, avoid the deprecated Apollo v2 packages. Choose urql for extensibility or graphql-hooks for simplicity. If you need the full Apollo ecosystem, use the modern @apollo/client package instead of the legacy ones.