@apollo/client 4.1.6 → 4.1.8

package/skills/apollo-client/references/troubleshooting.md

@@ -0,0 +1,487 @@
+# Troubleshooting Reference
+
+## Table of Contents
+
+- [Setup Issues](#setup-issues)
+- [Cache Issues](#cache-issues)
+- [TypeScript Issues](#typescript-issues)
+- [Performance Issues](#performance-issues)
+- [DevTools Usage](#devtools-usage)
+- [Common Error Messages](#common-error-messages)
+
+## Setup Issues
+
+### Provider Not Found
+
+**Error:** `Could not find "client" in the context or passed in as an option`
+
+**Cause:** Component is not wrapped with `ApolloProvider`.
+
+**Solution:**
+
+```tsx
+// Ensure ApolloProvider wraps your app
+import { ApolloProvider } from "@apollo/client";
+
+function App() {
+  return (
+    <ApolloProvider client={client}>
+      <YourApp />
+    </ApolloProvider>
+  );
+}
+```
+
+### Multiple Apollo Clients
+
+**Problem:** Unintended cache isolation or conflicting states.
+
+**Solution:** Use a single client instance or explicitly manage multiple clients:
+
+```tsx
+// Single client (recommended)
+const client = new ApolloClient({
+  /* ... */
+});
+
+export function App() {
+  return (
+    <ApolloProvider client={client}>
+      <Router />
+    </ApolloProvider>
+  );
+}
+
+// Multiple clients (rare use case)
+const publicClient = new ApolloClient({
+  uri: "/public/graphql",
+  cache: new InMemoryCache(),
+});
+const adminClient = new ApolloClient({
+  uri: "/admin/graphql",
+  cache: new InMemoryCache(),
+});
+
+function AdminSection() {
+  return (
+    <ApolloProvider client={adminClient}>
+      <AdminDashboard />
+    </ApolloProvider>
+  );
+}
+```
+
+### Client Created in Component
+
+**Problem:** New client on every render causes cache loss.
+
+**Solution:** Create client outside component or use a ref pattern:
+
+```tsx
+// Bad - new client on every render
+function App() {
+  const client = new ApolloClient({
+    /* ... */
+  }); // Don't do this!
+  return <ApolloProvider client={client}>...</ApolloProvider>;
+}
+
+// Module-level client definition
+// Okay if there is a 100% guarantee this application will never use SSR
+const client = new ApolloClient({
+  /* ... */
+});
+function App() {
+  return <ApolloProvider client={client}>...</ApolloProvider>;
+}
+
+// Good - store Apollo Client in a ref that is initialized once
+function useApolloClient(makeApolloClient: () => ApolloClient): ApolloClient {
+  const storeRef = useRef<ApolloClient | null>(null);
+  if (!storeRef.current) {
+    storeRef.current = makeApolloClient();
+  }
+  return storeRef.current;
+}
+
+// Better - singleton global in non-SSR environments to survive unmounts
+const singleton = Symbol.for("ApolloClientSingleton");
+declare global {
+  interface Window {
+    [singleton]?: ApolloClient;
+  }
+}
+
+function useApolloClient(makeApolloClient: () => ApolloClient): ApolloClient {
+  const storeRef = useRef<ApolloClient | null>(null);
+  if (!storeRef.current) {
+    if (typeof window === "undefined") {
+      storeRef.current = makeApolloClient();
+    } else {
+      window[singleton] ??= makeApolloClient();
+      storeRef.current = window[singleton];
+    }
+  }
+  return storeRef.current;
+}
+// Note: this second option might need manual removal between tests
+```
+
+## Cache Issues
+
+### Stale Data Not Updating
+
+**Problem:** UI doesn't reflect mutations or other updates.
+
+**Solution 1:** Verify cache key identification:
+
+```typescript
+const cache = new InMemoryCache({
+  typePolicies: {
+    // Ensure proper identification
+    Product: {
+      keyFields: ["id"], // or ['sku'] if no id field
+    },
+  },
+});
+```
+
+**Solution 2:** Update cache after mutations:
+
+```tsx
+const [deleteProduct] = useMutation(DELETE_PRODUCT, {
+  update: (cache, { data }) => {
+    cache.evict({ id: cache.identify(data.deleteProduct) });
+    cache.gc();
+  },
+});
+```
+
+**Solution 3:** Use appropriate fetch policy:
+
+```tsx
+const { data } = useQuery(GET_PRODUCTS, {
+  fetchPolicy: "cache-and-network", // Always fetch fresh data
+});
+```
+
+### Missing Cache Updates After Mutation
+
+**Problem:** New items don't appear in lists after creation.
+
+**Solution:** Manually update the cache:
+
+```tsx
+const [createProduct] = useMutation(CREATE_PRODUCT, {
+  update: (cache, { data }) => {
+    const existing = cache.readQuery<{ products: Product[] }>({
+      query: GET_PRODUCTS,
+    });
+
+    cache.writeQuery({
+      query: GET_PRODUCTS,
+      data: {
+        products: [...(existing?.products ?? []), data.createProduct],
+      },
+    });
+  },
+});
+```
+
+### Pagination Cache Issues
+
+**Problem:** Paginated data not merging correctly.
+
+**Solution:** Configure proper type policies:
+
+```typescript
+const cache = new InMemoryCache({
+  typePolicies: {
+    Query: {
+      fields: {
+        products: {
+          keyArgs: ["category"], // Only category creates new cache entries
+          merge(existing = [], incoming) {
+            return [...existing, ...incoming];
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+### Cache Normalization Problems
+
+**Problem:** Objects with same ID showing different data in different queries.
+
+**Debug:** Check cache contents:
+
+```typescript
+// In DevTools console or component
+console.log(client.cache.extract());
+```
+
+**Solution:** Ensure consistent `__typename` and `id` fields:
+
+```graphql
+query GetUsers {
+  users {
+    id # Always include id
+    name
+  }
+}
+```
+
+## TypeScript Issues
+
+### Type Generation Setup
+
+**Problem:** No type safety for GraphQL operations.
+
+**Solution:** Set up GraphQL Code Generator with the [recommended starter configuration](https://www.apollographql.com/docs/react/development-testing/graphql-codegen#recommended-starter-configuration), as described in the [Skill](../SKILL.md).
+
+### Using Generated Types
+
+```tsx
+import { useQuery } from "@apollo/client/react";
+import { GetUsersDocument, GetUsersQuery } from "./generated/graphql";
+
+function UserList() {
+  // Fully typed without manual type annotations
+  const { data, loading, error } = useQuery(GetUsersDocument);
+
+  // data.users is automatically typed as GetUsersQuery['users']
+  return (
+    <ul>{data?.users.map((user) => <li key={user.id}>{user.name}</li>)}</ul>
+  );
+}
+```
+
+## Performance Issues
+
+### Over-Fetching
+
+**Problem:** Fetching more data than needed.
+
+**Solution:** Select only required fields:
+
+```graphql
+# Bad - fetching everything
+query GetUsers {
+  users {
+    id
+    name
+    email
+    profile { ... }
+    posts { ... }
+    friends { ... }
+  }
+}
+
+# Good - fetch what's needed
+query GetUserNames {
+  users {
+    id
+    name
+  }
+}
+```
+
+### N+1 Queries
+
+**Problem:** Multiple network requests for related data.
+
+**Solution:** Structure queries to batch requests. Best practice: use query colocation and compose queries from fragments defined on child components.
+
+```graphql
+# Bad - separate queries
+query GetUser($id: ID!) {
+  user(id: $id) {
+    id
+    name
+  }
+}
+query GetUserPosts($userId: ID!) {
+  posts(userId: $userId) {
+    id
+    title
+  }
+}
+
+# Good - single query
+query GetUserWithPosts($id: ID!) {
+  user(id: $id) {
+    id
+    name
+    posts {
+      id
+      title
+    }
+  }
+}
+```
+
+### Unnecessary Re-Renders
+
+**Problem:** Components re-render when unrelated cache data changes.
+
+**Solution:** Use `useFragment` and data masking for selective field reading. If that is not possible, `useQuery` with `@nonreactive` directives might be an alternative.
+
+```tsx
+// Prefer useFragment with data masking
+const { data } = useFragment({
+  fragment: USER_FRAGMENT,
+  from: { __typename: "User", id },
+});
+
+// Alternative: use @nonreactive directive
+const GET_USER = gql`
+  query GetUser($id: ID!) {
+    user(id: $id) {
+      id
+      name
+      # This field won't trigger re-renders when it changes
+      metadata @nonreactive {
+        lastSeen
+        preferences
+      }
+    }
+  }
+`;
+
+const { data } = useQuery(GET_USER, {
+  variables: { id },
+});
+```
+
+### Cache Misses
+
+**Debug:** Use Apollo DevTools to inspect cache.
+
+```typescript
+const client = new ApolloClient({
+  cache: new InMemoryCache(),
+  // DevTools are enabled by default in development
+  // Only configure this when you need to enable them in production
+  devtools: {
+    enabled: true,
+  },
+});
+```
+
+## DevTools Usage
+
+### Installing Apollo DevTools
+
+Install the browser extension:
+
+- [Chrome](https://chrome.google.com/webstore/detail/apollo-client-devtools/jdkknkkbebbapilgoeccciglkfbmbnfm)
+- [Firefox](https://addons.mozilla.org/en-US/firefox/addon/apollo-developer-tools/)
+
+### Enabling DevTools
+
+DevTools are enabled by default in development. Only configure this setting if you need to enable them in production:
+
+```typescript
+const client = new ApolloClient({
+  cache: new InMemoryCache(),
+  devtools: {
+    enabled: true, // Set to true to enable in production
+  },
+});
+```
+
+### DevTools Features
+
+1. **Cache Inspector**: View normalized cache contents
+2. **Queries**: See active queries and their states
+3. **Mutations**: Track mutation history
+4. **Explorer**: Build and test queries against your schema
+5. **Memoization Limits**: Monitor and track cache memoization
+6. **Cache Writes**: Track all writes to the cache
+
+### Debugging Cache
+
+```typescript
+// Log cache contents
+console.log(JSON.stringify(client.cache.extract(), null, 2));
+
+// Check specific object using cache.identify
+console.log(
+  client.cache.readFragment({
+    id: cache.identify({ __typename: "User", id: 1 }),
+    fragment: gql`
+      fragment _ on User {
+        id
+        name
+        email
+      }
+    `,
+  })
+);
+```
+
+## Common Error Messages
+
+### "Missing field 'X' in {...}"
+
+**Cause:** Query doesn't include required field for cache normalization.
+
+**Solution:** Include `id` and `__typename`:
+
+```graphql
+query GetUsers {
+  users {
+    id # Required for caching
+    __typename # Usually added automatically
+    name
+  }
+}
+```
+
+**Additional advice**: Read the full error message thoroughly.
+
+### "Store reset while query was in flight"
+
+**Cause:** `client.resetStore()` called during active queries.
+
+**Solution:** Wait for queries to complete or use `clearStore()`:
+
+```typescript
+// Option 1: Clear without refetching
+await client.clearStore();
+
+// Option 2: Reset and refetch active queries
+await client.resetStore();
+```
+
+### "Invariant Violation: X"
+
+**Cause:** Various configuration or usage errors.
+
+**Common fixes:**
+
+- Ensure `ApolloProvider` wraps the component tree
+- Check that `gql` tagged templates are valid GraphQL
+- Verify cache configuration matches your schema
+
+### "Cannot read property 'X' of undefined"
+
+**Cause:** Accessing data before query completes.
+
+**Solution:** Check `dataState` for proper type narrowing:
+
+```tsx
+const { data, dataState } = useQuery(GET_USER);
+
+// dataState can be "complete", "partial", "streaming", or "empty"
+// It describes the completeness of the data, not a loading state
+if (dataState === "empty") return <Spinner />;
+
+// Now data is guaranteed to exist
+return <div>{data.user.name}</div>;
+
+// Or use optional chaining
+return <div>{data?.user?.name}</div>;
+```

package/skills/apollo-client/references/typescript-codegen.md

@@ -0,0 +1,133 @@
+# TypeScript Code Generation
+
+This guide covers setting up GraphQL Code Generator for type-safe Apollo Client usage with TypeScript.
+
+## Installation
+
+```bash
+npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typed-document-node
+```
+
+## Configuration
+
+Create a `codegen.ts` file in your project root:
+
+```typescript
+// codegen.ts
+import { CodegenConfig } from "@graphql-codegen/cli";
+
+const config: CodegenConfig = {
+  overwrite: true,
+  schema: "<URL_OF_YOUR_GRAPHQL_API>",
+  // This assumes that all your source files are in a top-level `src/` directory - you might need to adjust this to your file structure
+  documents: ["src/**/*.{ts,tsx}"],
+  // Don't exit with non-zero status when there are no documents
+  ignoreNoDocuments: true,
+  generates: {
+    // Use a path that works the best for the structure of your application
+    "./src/types/__generated__/graphql.ts": {
+      plugins: ["typescript", "typescript-operations", "typed-document-node"],
+      config: {
+        avoidOptionals: {
+          // Use `null` for nullable fields instead of optionals
+          field: true,
+          // Allow nullable input fields to remain unspecified
+          inputValue: false,
+        },
+        // Use `unknown` instead of `any` for unconfigured scalars
+        defaultScalarType: "unknown",
+        // Apollo Client always includes `__typename` fields
+        nonOptionalTypename: true,
+        // Apollo Client doesn't add the `__typename` field to root types so
+        // don't generate a type for the `__typename` for root operation types.
+        skipTypeNameForRoot: true,
+      },
+    },
+  },
+};
+
+export default config;
+```
+
+## Enable Data Masking
+
+To enable data masking with GraphQL Code Generator, create a type declaration file to inform Apollo Client about the generated types:
+
+```typescript
+// apollo-client.d.ts
+import { GraphQLCodegenDataMasking } from "@apollo/client/masking";
+
+declare module "@apollo/client" {
+  export interface TypeOverrides
+    extends GraphQLCodegenDataMasking.TypeOverrides {}
+}
+```
+
+## Running Code Generation
+
+Add a script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "codegen": "graphql-codegen"
+  }
+}
+```
+
+Run code generation:
+
+```bash
+npm run codegen
+```
+
+## Usage with Apollo Client
+
+The typed-document-node plugin generates `TypedDocumentNode` types that Apollo Client hooks automatically infer.
+
+### Defining Operations
+
+Define your operations inline with the `if (false)` pattern. This allows GraphQL Code Generator to detect and extract operations without executing the code at runtime (bundlers omit this dead code during minification):
+
+```typescript
+import { gql } from "@apollo/client";
+
+// This query will never be consumed in runtime code, so it is wrapped in `if (false)` so the bundler can omit it when bundling.
+if (false) {
+  gql`
+    query GetUser($id: ID!) {
+      user(id: $id) {
+        id
+        name
+        email
+      }
+    }
+  `;
+}
+```
+
+### Using Generated Types
+
+After running `npm run codegen`, import the generated `TypedDocumentNode`:
+
+```typescript
+import { useQuery } from "@apollo/client/react";
+import { GetUserDocument } from "./queries.generated";
+
+function UserProfile({ userId }: { userId: string }) {
+  // Types are automatically inferred from GetUserDocument
+  const { data } = useQuery(GetUserDocument, {
+    variables: { id: userId },
+  });
+
+  // ... other logic ...
+
+  return <div>{data?.user.name}</div>;
+}
+```
+
+## Important Notes
+
+- The typed-document-node plugin might have a bundle size tradeoff but can prevent inconsistencies and is best suited for usage with LLMs, so it is recommended for most applications.
+- See the [GraphQL Code Generator documentation](https://www.apollographql.com/docs/react/development-testing/graphql-codegen#recommended-starter-configuration) for other recommended configuration patterns if required.
+- Apollo Client hooks automatically infer types from `TypedDocumentNode` - never use manual generics like `useQuery<QueryType, VariablesType>()`.

package/version.js

@@ -1,3 +1,3 @@
-export const version = "4.1.6";
+export const version = "4.1.8";
 export const build = "esm";
 //# sourceMappingURL=version.js.map