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';