ai-qakit 1.0.0

package/templates/.claude/skills/frontend-development/references/graphql-apollo.md

@@ -0,0 +1,731 @@
+# GraphQL with Apollo Client
+
+Apollo Client 3.8+ patterns for type-safe GraphQL in React applications.
+
+---
+
+## Installation
+
+```bash
+npm install @apollo/client graphql
+npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-react-apollo
+```
+
+---
+
+## Apollo Client Setup
+
+```tsx
+// shared/api/apollo-client.ts
+import {
+  ApolloClient,
+  InMemoryCache,
+  createHttpLink,
+  from,
+} from '@apollo/client';
+import { setContext } from '@apollo/client/link/context';
+import { onError } from '@apollo/client/link/error';
+
+const httpLink = createHttpLink({
+  uri: import.meta.env.VITE_GRAPHQL_URL || '/graphql',
+});
+
+const authLink = setContext((_, { headers }) => {
+  const token = localStorage.getItem('token');
+  return {
+    headers: {
+      ...headers,
+      authorization: token ? `Bearer ${token}` : '',
+    },
+  };
+});
+
+const errorLink = onError(({ graphQLErrors, networkError }) => {
+  if (graphQLErrors) {
+    graphQLErrors.forEach(({ message, locations, path, extensions }) => {
+      console.error(`[GraphQL error]: Message: ${message}, Path: ${path}`);
+      
+      // Handle authentication errors
+      if (extensions?.code === 'UNAUTHENTICATED') {
+        localStorage.removeItem('token');
+        window.location.href = '/login';
+      }
+    });
+  }
+  if (networkError) {
+    console.error(`[Network error]: ${networkError}`);
+  }
+});
+
+export const apolloClient = new ApolloClient({
+  link: from([errorLink, authLink, httpLink]),
+  cache: new InMemoryCache({
+    typePolicies: {
+      Query: {
+        fields: {
+          // Merge paginated lists
+          posts: {
+            keyArgs: ['filter', 'sortBy'],
+            merge(existing = [], incoming, { args }) {
+              if (args?.offset === 0) return incoming;
+              return [...existing, ...incoming];
+            },
+          },
+        },
+      },
+      // Normalize by id
+      User: {
+        keyFields: ['id'],
+      },
+      Post: {
+        keyFields: ['id'],
+      },
+    },
+  }),
+  defaultOptions: {
+    watchQuery: {
+      fetchPolicy: 'cache-and-network',
+      errorPolicy: 'all',
+    },
+    query: {
+      fetchPolicy: 'cache-first',
+      errorPolicy: 'all',
+    },
+    mutate: {
+      errorPolicy: 'all',
+    },
+  },
+});
+```
+
+---
+
+## Provider Setup
+
+```tsx
+// app/providers/apollo-provider.tsx
+import { ApolloProvider } from '@apollo/client';
+import { apolloClient } from '@/shared/api/apollo-client';
+
+export const ApolloAppProvider: React.FC<{ children: React.ReactNode }> = ({
+  children,
+}) => (
+  <ApolloProvider client={apolloClient}>
+    {children}
+  </ApolloProvider>
+);
+```
+
+---
+
+## GraphQL Codegen Setup
+
+```yaml
+# codegen.yml
+schema: 'http://localhost:4000/graphql'
+documents: 'src/**/*.graphql'
+generates:
+  src/shared/api/graphql/generated.ts:
+    plugins:
+      - typescript
+      - typescript-operations
+      - typescript-react-apollo
+    config:
+      withHooks: true
+      withHOC: false
+      withComponent: false
+      skipTypename: false
+      enumsAsTypes: true
+      scalars:
+        DateTime: string
+        JSON: Record<string, unknown>
+```
+
+```json
+// package.json scripts
+{
+  "scripts": {
+    "codegen": "graphql-codegen --config codegen.yml",
+    "codegen:watch": "graphql-codegen --config codegen.yml --watch"
+  }
+}
+```
+
+---
+
+## useSuspenseQuery (PRIMARY PATTERN)
+
+Apollo Client 3.8+ supports React Suspense:
+
+```tsx
+// entities/user/model/useUser.ts
+import { useSuspenseQuery } from '@apollo/client';
+import { GET_USER } from '../api/userQueries';
+import type { GetUserQuery, GetUserQueryVariables } from '@/shared/api/graphql/generated';
+
+export function useUser(userId: string) {
+  const { data, error, refetch } = useSuspenseQuery<
+    GetUserQuery,
+    GetUserQueryVariables
+  >(GET_USER, {
+    variables: { id: userId },
+  });
+
+  return {
+    user: data.user,
+    error,
+    refetch,
+  };
+}
+
+// Usage in component
+export const UserProfile: React.FC<{ userId: string }> = ({ userId }) => {
+  const { user } = useUser(userId);
+
+  return (
+    <div className="p-4">
+      <h1 className="text-2xl font-bold">{user.name}</h1>
+      <p className="text-muted-foreground">{user.email}</p>
+    </div>
+  );
+};
+
+// Parent wraps with Suspense
+<SuspenseLoader>
+  <UserProfile userId="123" />
+</SuspenseLoader>
+```
+
+---
+
+## useBackgroundQuery + useReadQuery
+
+Prefetch data without blocking render:
+
+```tsx
+import { useBackgroundQuery, useReadQuery } from '@apollo/client';
+
+// Parent initiates background query
+export const PostsPage: React.FC = () => {
+  const [queryRef] = useBackgroundQuery(GET_POSTS, {
+    variables: { limit: 20 },
+  });
+
+  return (
+    <div>
+      <h1>Posts</h1>
+      <SuspenseLoader>
+        <PostsList queryRef={queryRef} />
+      </SuspenseLoader>
+    </div>
+  );
+};
+
+// Child reads the data
+const PostsList: React.FC<{ queryRef: QueryReference<GetPostsQuery> }> = ({
+  queryRef,
+}) => {
+  const { data } = useReadQuery(queryRef);
+
+  return (
+    <div className="space-y-4">
+      {data.posts.map((post) => (
+        <PostCard key={post.id} post={post} />
+      ))}
+    </div>
+  );
+};
+```
+
+---
+
+## Fragment Colocation
+
+Keep data requirements close to components:
+
+```graphql
+# entities/user/api/userFragments.graphql
+fragment UserCard on User {
+  id
+  name
+  email
+  avatar
+}
+
+fragment UserProfile on User {
+  ...UserCard
+  bio
+  createdAt
+  posts {
+    id
+    title
+  }
+}
+```
+
+```tsx
+// entities/user/ui/UserCard.tsx
+import { FragmentType, useFragment } from '@/shared/api/graphql/generated';
+import { UserCardFragmentDoc } from '../api/userFragments';
+
+interface UserCardProps {
+  user: FragmentType<typeof UserCardFragmentDoc>;
+  className?: string;
+}
+
+export const UserCard: React.FC<UserCardProps> = ({ user: userProp, className }) => {
+  const user = useFragment(UserCardFragmentDoc, userProp);
+
+  return (
+    <Card className={cn('p-4', className)}>
+      <Avatar src={user.avatar} alt={user.name} />
+      <div>
+        <p className="font-medium">{user.name}</p>
+        <p className="text-sm text-muted-foreground">{user.email}</p>
+      </div>
+    </Card>
+  );
+};
+```
+
+---
+
+## Queries in FSD Structure
+
+```graphql
+# entities/post/api/postQueries.graphql
+query GetPosts($limit: Int, $offset: Int, $filter: PostFilter) {
+  posts(limit: $limit, offset: $offset, filter: $filter) {
+    id
+    title
+    content
+    createdAt
+    author {
+      ...UserCard
+    }
+  }
+}
+
+query GetPost($id: ID!) {
+  post(id: $id) {
+    id
+    title
+    content
+    createdAt
+    author {
+      ...UserProfile
+    }
+    comments {
+      id
+      content
+      author {
+        ...UserCard
+      }
+    }
+  }
+}
+```
+
+```tsx
+// entities/post/api/index.ts
+import { gql } from '@apollo/client';
+
+export const GET_POSTS = gql`
+  query GetPosts($limit: Int, $offset: Int, $filter: PostFilter) {
+    posts(limit: $limit, offset: $offset, filter: $filter) {
+      id
+      title
+      content
+      createdAt
+      author {
+        id
+        name
+        avatar
+      }
+    }
+  }
+`;
+
+export const GET_POST = gql`
+  query GetPost($id: ID!) {
+    post(id: $id) {
+      id
+      title
+      content
+      createdAt
+      author {
+        id
+        name
+        email
+        avatar
+      }
+    }
+  }
+`;
+```
+
+---
+
+## Mutations
+
+```tsx
+// features/posts/create-post/model/useCreatePost.ts
+import { useMutation } from '@apollo/client';
+import { toast } from 'sonner';
+import { CREATE_POST, GET_POSTS } from '@/entities/post/api';
+import type {
+  CreatePostMutation,
+  CreatePostMutationVariables,
+} from '@/shared/api/graphql/generated';
+
+export function useCreatePost() {
+  const [createPost, { loading, error }] = useMutation<
+    CreatePostMutation,
+    CreatePostMutationVariables
+  >(CREATE_POST, {
+    // Update cache after mutation
+    update(cache, { data }) {
+      if (!data?.createPost) return;
+
+      cache.modify({
+        fields: {
+          posts(existingPosts = []) {
+            const newPostRef = cache.writeFragment({
+              data: data.createPost,
+              fragment: gql`
+                fragment NewPost on Post {
+                  id
+                  title
+                  content
+                  createdAt
+                }
+              `,
+            });
+            return [newPostRef, ...existingPosts];
+          },
+        },
+      });
+    },
+    // Or refetch queries
+    refetchQueries: [{ query: GET_POSTS }],
+    onCompleted: () => {
+      toast.success('Post created successfully');
+    },
+    onError: (error) => {
+      toast.error(error.message || 'Failed to create post');
+    },
+  });
+
+  return {
+    createPost: (input: CreatePostMutationVariables['input']) =>
+      createPost({ variables: { input } }),
+    loading,
+    error,
+  };
+}
+```
+
+---
+
+## Optimistic Updates
+
+```tsx
+// features/posts/like-post/model/useLikePost.ts
+import { useMutation } from '@apollo/client';
+
+export function useLikePost() {
+  const [likePost] = useMutation(LIKE_POST, {
+    optimisticResponse: ({ postId }) => ({
+      __typename: 'Mutation',
+      likePost: {
+        __typename: 'Post',
+        id: postId,
+        likesCount: 'OPTIMISTIC', // Will be replaced
+        isLikedByMe: true,
+      },
+    }),
+    update(cache, { data }, { variables }) {
+      cache.modify({
+        id: cache.identify({ __typename: 'Post', id: variables?.postId }),
+        fields: {
+          likesCount(existing) {
+            return existing + 1;
+          },
+          isLikedByMe() {
+            return true;
+          },
+        },
+      });
+    },
+  });
+
+  return { likePost };
+}
+```
+
+---
+
+## Pagination
+
+### Offset-Based
+
+```tsx
+// features/posts/model/usePostsPaginated.ts
+import { useSuspenseQuery } from '@apollo/client';
+import { GET_POSTS } from '@/entities/post/api';
+
+export function usePostsPaginated(limit = 20) {
+  const { data, fetchMore } = useSuspenseQuery(GET_POSTS, {
+    variables: { limit, offset: 0 },
+  });
+
+  const loadMore = () => {
+    fetchMore({
+      variables: {
+        offset: data.posts.length,
+      },
+    });
+  };
+
+  return {
+    posts: data.posts,
+    loadMore,
+    hasMore: data.posts.length % limit === 0,
+  };
+}
+```
+
+### Cursor-Based (Relay Style)
+
+```tsx
+// features/posts/model/usePostsInfinite.ts
+import { useSuspenseQuery } from '@apollo/client';
+
+export function usePostsInfinite(first = 20) {
+  const { data, fetchMore } = useSuspenseQuery(GET_POSTS_CONNECTION, {
+    variables: { first },
+  });
+
+  const loadMore = () => {
+    if (!data.postsConnection.pageInfo.hasNextPage) return;
+
+    fetchMore({
+      variables: {
+        first,
+        after: data.postsConnection.pageInfo.endCursor,
+      },
+      updateQuery(prev, { fetchMoreResult }) {
+        if (!fetchMoreResult) return prev;
+        return {
+          postsConnection: {
+            ...fetchMoreResult.postsConnection,
+            edges: [
+              ...prev.postsConnection.edges,
+              ...fetchMoreResult.postsConnection.edges,
+            ],
+          },
+        };
+      },
+    });
+  };
+
+  return {
+    posts: data.postsConnection.edges.map((e) => e.node),
+    pageInfo: data.postsConnection.pageInfo,
+    loadMore,
+  };
+}
+```
+
+---
+
+## Subscriptions (Real-time)
+
+```tsx
+// features/notifications/model/useNotifications.ts
+import { useSubscription } from '@apollo/client';
+
+const NOTIFICATION_SUBSCRIPTION = gql`
+  subscription OnNotification($userId: ID!) {
+    notificationReceived(userId: $userId) {
+      id
+      type
+      message
+      createdAt
+    }
+  }
+`;
+
+export function useNotifications(userId: string) {
+  const { data, loading } = useSubscription(NOTIFICATION_SUBSCRIPTION, {
+    variables: { userId },
+    onData: ({ data }) => {
+      if (data?.notificationReceived) {
+        toast.info(data.notificationReceived.message);
+      }
+    },
+  });
+
+  return { notification: data?.notificationReceived, loading };
+}
+```
+
+---
+
+## Error Handling
+
+```tsx
+// shared/ui/graphql-error-boundary.tsx
+import { useFragment } from '@apollo/client';
+
+interface GraphQLErrorBoundaryProps {
+  children: React.ReactNode;
+  fallback?: React.ReactNode;
+}
+
+export const GraphQLErrorBoundary: React.FC<GraphQLErrorBoundaryProps> = ({
+  children,
+  fallback,
+}) => {
+  return (
+    <ErrorBoundary
+      fallback={
+        fallback ?? (
+          <div className="p-8 text-center">
+            <p className="text-destructive">Something went wrong</p>
+          </div>
+        )
+      }
+    >
+      {children}
+    </ErrorBoundary>
+  );
+};
+```
+
+---
+
+## Cache Management
+
+```tsx
+// Manual cache updates
+const cache = apolloClient.cache;
+
+// Read from cache
+const user = cache.readFragment({
+  id: 'User:123',
+  fragment: USER_FRAGMENT,
+});
+
+// Write to cache
+cache.writeFragment({
+  id: 'User:123',
+  fragment: USER_FRAGMENT,
+  data: { ...user, name: 'Updated Name' },
+});
+
+// Evict from cache
+cache.evict({ id: 'User:123' });
+cache.gc(); // Garbage collect
+
+// Reset entire cache
+await apolloClient.resetStore();
+```
+
+---
+
+## Query Key Patterns
+
+```tsx
+// Consistent variable patterns
+const queryVariables = {
+  // Lists
+  posts: { limit: 20, offset: 0 },
+  postsByUser: (userId: string) => ({ userId, limit: 20 }),
+  postsByCategory: (category: string) => ({ category }),
+
+  // Details
+  post: (id: string) => ({ id }),
+  user: (id: string) => ({ id }),
+};
+
+// Use in queries
+const { data } = useSuspenseQuery(GET_POSTS, {
+  variables: queryVariables.posts,
+});
+```
+
+---
+
+## FSD Organization
+
+```
+src/
+├── shared/
+│   └── api/
+│       ├── apollo-client.ts       # Client setup
+│       └── graphql/
+│           ├── generated.ts       # Codegen output
+│           └── fragments.graphql  # Shared fragments
+├── entities/
+│   ├── user/
+│   │   ├── api/
+│   │   │   ├── userQueries.graphql
+│   │   │   ├── userFragments.graphql
+│   │   │   └── index.ts
+│   │   └── model/
+│   │       └── useUser.ts
+│   └── post/
+│       ├── api/
+│       │   ├── postQueries.graphql
+│       │   └── postMutations.graphql
+│       └── model/
+│           └── usePost.ts
+└── features/
+    └── posts/
+        └── create-post/
+            ├── api/
+            │   └── createPost.graphql
+            └── model/
+                └── useCreatePost.ts
+```
+
+---
+
+## Apollo Client vs TanStack Query
+
+| Feature | Apollo Client | TanStack Query |
+|---------|--------------|----------------|
+| Best for | GraphQL | REST APIs |
+| Cache | Normalized | Query-based |
+| Devtools | Apollo DevTools | TanStack DevTools |
+| Suspense | ✅ useSuspenseQuery | ✅ useSuspenseQuery |
+| Optimistic | Built-in | Manual |
+| Subscriptions | ✅ Built-in | ❌ Requires custom |
+
+**Use Apollo Client when:**
+- Backend uses GraphQL
+- Need normalized caching
+- Real-time subscriptions needed
+- Complex cache relationships
+
+**Use TanStack Query when:**
+- REST API backend
+- Simple caching needs
+- Query-based cache is sufficient
+
+---
+
+## GraphQL Checklist
+
+- [ ] Set up Apollo Client with auth link
+- [ ] Configure error handling link
+- [ ] Set up GraphQL Codegen
+- [ ] Use useSuspenseQuery (not useQuery)
+- [ ] Colocate fragments with components
+- [ ] Configure cache type policies
+- [ ] Implement optimistic updates for mutations
+- [ ] Set up proper error boundaries
+- [ ] Use generated types everywhere
+
+