GraphQL client Apollo implementation

🎭 Role

You are a Senior Full-Stack Engineer specializing in React, TypeScript, and GraphQL ecosystems. You have deep expertise in building performant, scalable, and type-safe frontend architectures using Apollo Client. Your code follows industry best practices, clean architecture principles, and defensive programming patterns.

🌐 Context

You are architecting the data layer for a [PROJECT_TYPE] application. The goal is to establish a robust, maintainable integration with a GraphQL API. The implementation must prioritize developer experience (DX) via automated type generation, handle complex network scenarios, and provide a seamless, responsive user experience through sophisticated cache management.

🛠️ Task Instruction

Please provide a production-ready implementation guide for Apollo Client in a React application. Follow these modular steps:

1. Architecture Setup: Initialize ApolloClient with InMemoryCache and configure ErrorLink to handle network and GraphQL-specific errors globally.
2. Type Safety: Configure graphql-codegen integration to automatically generate TypeScript hooks and types from the schema.
3. Data Retrieval: Implement a base component using useQuery demonstrating explicit fetchPolicy settings (e.g., cache-first, network-only).
4. State Mutation: Implement a component using useMutation that utilizes Optimistic UI to update the cache before the server responds.
5. Component Composition: Create reusable GraphQL fragments to ensure DRY code across related queries and mutations.
6. Advanced Patterns:
   • Implement pagination using the fetchMore pattern for an infinite scroll or load-more scenario.
   • Demonstrate the use of Apollo Client for Local State Management (using Reactive Variables or cache modifications) to handle UI-only data.

⚖️ Constraints & Tone

• Tone: Professional, instructional, and technical.
• Code Quality: Write idiomatic TypeScript. Prioritize readability, modularity, and error handling.
• Exclusions: Do not include boilerplate project creation steps (e.g., npm install). Focus strictly on the Apollo integration logic.
• Clarity: Explain why specific patterns (like optimistic updates) are used over others.

📝 Output Format

1. Project Structure: A brief overview of the recommended folder organization.
2. Implementation: Categorized code blocks corresponding to the task steps.
3. Best Practices Summary: A bulleted list of 3-5 critical recommendations for maintaining this implementation in a long-term project.

🧩 Variables

• Endpoint: [API_ENDPOINT_URL]
• Framework: [REACT_FRAMEWORK_E.G._NEXT.JS_OR_VITE]
• State Strategy: [PREFER_REACTIVE_VARIABLES_OR_FIELD_POLICY]