Apollo Client Ecosystem: Legacy Modular vs. Modern Consolidated

For years, building GraphQL apps in React meant installing multiple packages: apollo-client for logic, react-apollo for UI bindings, and graphql-tag for query parsing. This modular approach gave developers control but added complexity. Today, the ecosystem has shifted toward consolidation. Let's break down what each package did, why they changed, and what you should use now.

🏗️ Architecture: Separate Packages vs. Unified Bundle

apollo-client was the core engine.

• It managed the cache, network links, and state.
• It was framework-agnostic (worked with Vue, Angular, or vanilla JS).
• You had to manually wire it up to React using a separate library.

// apollo-client: Legacy setup
import ApolloClient from 'apollo-client';
import { HttpLink } from 'apollo-link-http';
import { InMemoryCache } from 'apollo-cache-inmemory';

const client = new ApolloClient({
  link: new HttpLink({ uri: '/graphql' }),
  cache: new InMemoryCache()
});

react-apollo was the bridge to React.

• It provided Higher-Order Components (HOCs) like graphql() and later Hooks like useQuery.
• It depended on apollo-client to work.
• Installing it meant managing two major version numbers simultaneously.

// react-apollo: Legacy React binding
import { ApolloProvider } from 'react-apollo';
import { useQuery } from 'react-apollo';

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

@apollo/client (The Modern Standard) combines both.

• It includes the client logic and React bindings in one package.
• It simplifies imports and version management.
• It is the only recommended path for new development.

// @apollo/client: Modern unified setup
import { ApolloClient, InMemoryCache, ApolloProvider, useQuery } from '@apollo/client';

const client = new ApolloClient({
  uri: '/graphql',
  cache: new InMemoryCache()
});

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

📝 Query Parsing: External Utility vs. Built-In

graphql-tag is a standalone parser.

• It turns template literals into GraphQL AST (Abstract Syntax Tree) objects.
• It was required to tag queries so the client could read them.
• It is still maintained but often unnecessary now.

// graphql-tag: Standalone usage
import gql from 'graphql-tag';

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) { name }
  }
`;

@apollo/client includes gql by default.

• You can import gql directly from the main package.
• This reduces the number of dependencies in your package.json.
• Functionally identical to the standalone package for most users.

// @apollo/client: Built-in gql tag
import { gql } from '@apollo/client';

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) { name }
  }
`;

⚠️ Deprecation Status: What's Safe to Use?

This is the most critical part of the comparison. The maintainers have made clear decisions about the future of these libraries.

Why the Change?

Maintaining separate packages caused version mismatches.

• Developers often struggled to find compatible versions of apollo-client and react-apollo.
• Bug fixes had to be coordinated across multiple repositories.
• The unified package ensures that the React bindings always match the core client logic.

🔄 Migration: From Legacy to Modern

If you are currently using the legacy stack, here is how the code changes.

1. Update Imports

Old Way (apollo-client + react-apollo)

import ApolloClient from 'apollo-client';
import { ApolloProvider, useQuery } from 'react-apollo';
import gql from 'graphql-tag';

New Way (@apollo/client)

import { ApolloClient, ApolloProvider, useQuery, gql } from '@apollo/client';

2. Update Client Configuration

Old Way

// Required separate link and cache packages
import { createHttpLink } from 'apollo-link-http';
import { InMemoryCache } from 'apollo-cache-inmemory';

const client = new ApolloClient({
  link: createHttpLink({ uri: '/graphql' }),
  cache: new InMemoryCache()
});

New Way

// Links and cache are built-in
import { HttpLink, InMemoryCache } from '@apollo/client';

const client = new ApolloClient({
  link: new HttpLink({ uri: '/graphql' }),
  cache: new InMemoryCache()
});

🛠️ When to Keep graphql-tag?

There are rare cases where you might still install graphql-tag separately:

1. Non-Apollo Projects: If you are using a different GraphQL client (like urql or graphql-request) but still want the gql tag utility.
2. Build Tooling: Some older webpack or babel configurations expect the specific graphql-tag loader for query extraction.
3. Server-Side Parsing: If you need to parse GraphQL strings in a Node.js backend that does not use the Apollo Client.

// Example: Using graphql-tag with a different client
import gql from 'graphql-tag';
import { request } from 'graphql-request';

const query = gql`{ posts { title } }`;
request('/api/graphql', query);

💡 Summary: The Path Forward

apollo-client and react-apollo are history.
They served the community well during the early days of GraphQL in React. However, they are no longer the standard. Continuing to use them introduces technical debt and security risks due to lack of updates.

@apollo/client is the present and future.
It offers the same features with less setup. It is actively maintained, better documented, and designed for modern React patterns like Hooks.

graphql-tag is a utility.
Keep it in your toolkit for non-Apollo tasks, but don't install it unnecessarily if you are already using @apollo/client.

📊 Quick Reference

🏁 Final Recommendation

For any new project, start with @apollo/client.
It removes the guesswork of compatibility and gives you a single source of truth for your GraphQL layer.
If you are maintaining an old app, plan a migration to the unified package as soon as possible to ensure long-term stability.