GraphQL & Apollo Client Best Practices

This skill outlines the mandatory patterns for implementing GraphQL features in this project to avoid "Invalid hook call" errors and import issues.

1. Wrapping Components with ApolloProvider

Context: In Astro's island architecture, React components (.tsx) running on the client (hydrated islands) do not share a specific global context unless explicitly provided. This rule does not apply to .astro files where data fetching happens server-side using the client instance directly.

Rule: When a React component uses Apollo hooks (e.g., useQuery, useMutation), you MUST serve it wrapped in an ApolloProvider specifically for that island.

Implementation Pattern:

Separation of specific logic (Content) and the Provider wrapper.

import React, { useState } from 'react';
import { ApolloProvider } from '@apollo/client';
import { clientGql } from '@graphql-astro/apolloClient';
import { useSomeQuery } from '@graphql-astro/generated/graphql';

// 1. Inner component with the logic/hooks
function MyComponentContent() {
    const { data, loading } = useSomeQuery();
    
    if (loading) return <div>Loading...</div>;
    return <div>{data?.someField}</div>;
}

// 2. Exported component wrapped with provider
function MyComponent() {
    return (
        <ApolloProvider client={clientGql}>
            <MyComponentContent />
        </ApolloProvider>
    );
}

export default MyComponent;

2. Imports in graphql.ts

Rule: If you need to use gql tag manually or in graphql.ts (or similar utility files), you MUST import it from @apollo/client/core.

Correct:

import { gql } from '@apollo/client/core';

Incorrect:

import { gql } from '@apollo/client';
import { gql } from 'graphql-tag';