GraphQL Subscriptions with Apollo

# GraphQL Subscriptions with Apollo

Implement powerful real-time data synchronization using GraphQL subscriptions in your Google Antigravity projects. This guide covers Apollo Client setup, subscription patterns, and Supabase integration for live updates.

## Apollo Client Configuration

Set up Apollo Client with WebSocket support for subscriptions:

```typescript
// lib/apollo-client.ts
import { ApolloClient, InMemoryCache, split, HttpLink } from "@apollo/client";
import { GraphQLWsLink } from "@apollo/client/link/subscriptions";
import { createClient } from "graphql-ws";
import { getMainDefinition } from "@apollo/client/utilities";

const httpLink = new HttpLink({
  uri: process.env.NEXT_PUBLIC_GRAPHQL_HTTP_URL,
  headers: {
    "apikey": process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
  },
});

const wsLink = typeof window !== "undefined" ? new GraphQLWsLink(
  createClient({
    url: process.env.NEXT_PUBLIC_GRAPHQL_WS_URL!,
    connectionParams: {
      headers: {
        apikey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
      },
    },
    retryAttempts: 5,
    shouldRetry: () => true,
  })
) : null;

const splitLink = typeof window !== "undefined" && wsLink
  ? split(
      ({ query }) => {
        const definition = getMainDefinition(query);
        return (
          definition.kind === "OperationDefinition" &&
          definition.operation === "subscription"
        );
      },
      wsLink,
      httpLink
    )
  : httpLink;

export const apolloClient = new ApolloClient({
  link: splitLink,
  cache: new InMemoryCache({
    typePolicies: {
      Query: {
        fields: {
          messages: {
            merge(existing = [], incoming) {
              return [...existing, ...incoming];
            },
          },
        },
      },
    },
  }),
});
```

## Subscription Hook Implementation

Create reusable subscription hooks for common patterns:

```typescript
// hooks/useMessageSubscription.ts
import { useSubscription, gql } from "@apollo/client";
import { useCallback, useEffect, useState } from "react";

const MESSAGE_SUBSCRIPTION = gql`
  subscription OnNewMessage($channelId: UUID!) {
    messagesCollection(
      filter: { channel_id: { eq: $channelId } }
    ) {
      edges {
        node {
          id
          content
          created_at
          user {
            id
            username
            avatar_url
          }
        }
      }
    }
  }
`;

export function useMessageSubscription(channelId: string) {
  const [messages, setMessages] = useState<Message[]>([]);
  const [connectionStatus, setConnectionStatus] = useState<
    "connecting" | "connected" | "disconnected" | "error"
  >("connecting");

  const { data, loading, error } = useSubscription(MESSAGE_SUBSCRIPTION, {
    variables: { channelId },
    onData: ({ data }) => {
      if (data?.data?.messagesCollection?.edges) {
        const newMessages = data.data.messagesCollection.edges.map(
          (edge: { node: Message }) => edge.node
        );
        setMessages((prev) => {
          const messageIds = new Set(prev.map((m) => m.id));
          const uniqueNew = newMessages.filter(
            (m: Message) => !messageIds.has(m.id)
          );
          return [...prev, ...uniqueNew];
        });
      }
    },
    onError: (error) => {
      console.error("Subscription error:", error);
      setConnectionStatus("error");
    },
  });

  useEffect(() => {
    if (loading) setConnectionStatus("connecting");
    else if (error) setConnectionStatus("error");
    else setConnectionStatus("connected");
  }, [loading, error]);

  return { messages, connectionStatus, error };
}
```

## Real-time Chat Component

Build a complete chat interface with subscriptions:

```typescript
// components/ChatRoom.tsx
"use client";

import { useState, useRef, useEffect } from "react";
import { useMutation, gql } from "@apollo/client";
import { useMessageSubscription } from "@/hooks/useMessageSubscription";

const SEND_MESSAGE = gql`
  mutation SendMessage($channelId: UUID!, $content: String!) {
    insertIntoMessagesCollection(
      objects: [{ channel_id: $channelId, content: $content }]
    ) {
      records {
        id
        content
        created_at
      }
    }
  }
`;

export function ChatRoom({ channelId }: { channelId: string }) {
  const [newMessage, setNewMessage] = useState("");
  const messagesEndRef = useRef<HTMLDivElement>(null);
  const { messages, connectionStatus } = useMessageSubscription(channelId);
  const [sendMessage, { loading: sending }] = useMutation(SEND_MESSAGE);

  useEffect(() => {
    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
  }, [messages]);

  const handleSend = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!newMessage.trim() || sending) return;

    await sendMessage({
      variables: { channelId, content: newMessage },
      optimisticResponse: {
        insertIntoMessagesCollection: {
          records: [{
            id: `temp-${Date.now()}`,
            content: newMessage,
            created_at: new Date().toISOString(),
            __typename: "Message",
          }],
          __typename: "MessagesInsertResponse",
        },
      },
    });
    setNewMessage("");
  };

  return (
    <div className="flex flex-col h-full">
      <ConnectionIndicator status={connectionStatus} />
      <div className="flex-1 overflow-y-auto p-4 space-y-4">
        {messages.map((message) => (
          <MessageBubble key={message.id} message={message} />
        ))}
        <div ref={messagesEndRef} />
      </div>
      <form onSubmit={handleSend} className="p-4 border-t">
        <input
          value={newMessage}
          onChange={(e) => setNewMessage(e.target.value)}
          placeholder="Type a message..."
          disabled={connectionStatus !== "connected"}
        />
        <button type="submit" disabled={sending}>Send</button>
      </form>
    </div>
  );
}
```

## Best Practices

1. **Connection Management**: Implement reconnection logic with exponential backoff
2. **Optimistic Updates**: Show messages immediately while server confirms
3. **Deduplication**: Prevent duplicate messages using ID-based filtering
4. **Error Boundaries**: Wrap subscription components with error handling
5. **Memory Management**: Clean up subscriptions on component unmount
6. **Type Safety**: Generate TypeScript types from GraphQL schema