@apollo/client 4.2.0-alpha.2 → 4.2.0-alpha.3

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

@@ -0,0 +1,336 @@
+# Apollo Client Integration for Client-Side Apps
+
+This guide covers setting up Apollo Client in client-side React applications without server-side rendering (SSR). This includes applications using Vite, Parcel, Create React App, or other bundlers that don't implement SSR.
+
+For applications with SSR, use one of the framework-specific integration guides instead:
+
+- [Next.js App Router](integration-nextjs.md)
+- [React Router Framework Mode](integration-react-router.md)
+- [TanStack Start](integration-tanstack-start.md)
+
+## Installation
+
+```bash
+npm install @apollo/client graphql rxjs
+```
+
+## TypeScript Code Generation (optional but recommended)
+
+For type-safe GraphQL operations with TypeScript, see the [TypeScript Code Generation guide](typescript-codegen.md).
+
+## Setup Steps
+
+### Step 1: Create Client
+
+```typescript
+import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client";
+
+// Recommended: Use HttpOnly cookies for authentication
+const httpLink = new HttpLink({
+  uri: "https://your-graphql-endpoint.com/graphql",
+  credentials: "include", // Sends cookies with requests (secure when using HttpOnly cookies)
+});
+
+const client = new ApolloClient({
+  link: httpLink,
+  cache: new InMemoryCache(),
+});
+```
+
+If you need manual token management (less secure, only when HttpOnly cookies aren't available):
+
+```typescript
+import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client";
+import { SetContextLink } from "@apollo/client/link/context";
+
+const httpLink = new HttpLink({
+  uri: "https://your-graphql-endpoint.com/graphql",
+});
+
+const authLink = new SetContextLink(({ headers }) => {
+  const token = localStorage.getItem("token");
+  return {
+    headers: {
+      ...headers,
+      authorization: token ? `Bearer ${token}` : "",
+    },
+  };
+});
+
+const client = new ApolloClient({
+  link: authLink.concat(httpLink),
+  cache: new InMemoryCache(),
+});
+```
+
+### Step 2: Setup Provider
+
+```tsx
+import { ApolloProvider } from "@apollo/client";
+import App from "./App";
+
+function Root() {
+  return (
+    <ApolloProvider client={client}>
+      <App />
+    </ApolloProvider>
+  );
+}
+```
+
+### Step 3: Execute Query
+
+```tsx
+import { gql } from "@apollo/client";
+import { useQuery } from "@apollo/client/react";
+
+const GET_USERS = gql`
+  query GetUsers {
+    users {
+      id
+      name
+      email
+    }
+  }
+`;
+
+function UserList() {
+  const { loading, error, data, dataState } = useQuery(GET_USERS);
+
+  if (loading) return <p>Loading...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  // TypeScript note: for stricter type narrowing, you can also check `dataState === "complete"` before accessing data
+  return (
+    <ul>{data?.users.map((user) => <li key={user.id}>{user.name}</li>)}</ul>
+  );
+}
+```
+
+## Basic Query Usage
+
+### Using Variables
+
+```tsx
+const GET_USER = gql`
+  query GetUser($id: ID!) {
+    user(id: $id) {
+      id
+      name
+      email
+    }
+  }
+`;
+
+function UserProfile({ userId }: { userId: string }) {
+  const { loading, error, data, dataState } = useQuery(GET_USER, {
+    variables: { id: userId },
+  });
+
+  if (loading) return <p>Loading...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  // TypeScript note: for stricter type narrowing, you can also check `dataState === "complete"` before accessing data
+  return <div>{data?.user.name}</div>;
+}
+```
+
+> **Note for TypeScript users**: Use [`dataState`](https://www.apollographql.com/docs/react/data/typescript#type-narrowing-data-with-datastate) for more robust type safety and better type narrowing in Apollo Client 4.x.
+
+### TypeScript Integration
+
+For complete examples with loading, error handling, and `dataState` for type narrowing, see [Basic Query Usage](#basic-query-usage) above.
+
+#### Usage with Generated Types
+
+For type-safe operations with code generation, see the [TypeScript Code Generation guide](typescript-codegen.md).
+
+Quick example:
+
+```typescript
+import { gql } from "@apollo/client";
+import { useQuery } from "@apollo/client/react";
+import { GetUserDocument } from "./queries.generated";
+
+// Define your query with the if (false) pattern for code generation
+if (false) {
+  gql`
+    query GetUser($id: ID!) {
+      user(id: $id) {
+        id
+        name
+        email
+      }
+    }
+  `;
+}
+
+function UserProfile({ userId }: { userId: string }) {
+  // Types are automatically inferred from GetUserDocument
+  const { data } = useQuery(GetUserDocument, {
+    variables: { id: userId },
+  });
+
+  return <div>{data.user.name}</div>;
+}
+```
+
+#### Usage with Manual Type Annotations
+
+If not using code generation, define types alongside your queries using `TypedDocumentNode`:
+
+```typescript
+import { gql, TypedDocumentNode } from "@apollo/client";
+import { useQuery } from "@apollo/client/react";
+
+interface GetUserData {
+  user: {
+    id: string;
+    name: string;
+    email: string;
+  };
+}
+
+interface GetUserVariables {
+  id: string;
+}
+
+// Types should always be defined via TypedDocumentNode alongside your queries/mutations, not at the useQuery/useMutation call site
+const GET_USER: TypedDocumentNode<GetUserData, GetUserVariables> = gql`
+  query GetUser($id: ID!) {
+    user(id: $id) {
+      id
+      name
+      email
+    }
+  }
+`;
+
+function UserProfile({ userId }: { userId: string }) {
+  const { data } = useQuery(GET_USER, {
+    variables: { id: userId },
+  });
+
+  // data.user is automatically typed from GET_USER
+  return <div>{data.user.name}</div>;
+}
+```
+
+## Basic Mutation Usage
+
+```tsx
+import { gql, TypedDocumentNode } from "@apollo/client";
+import { useMutation } from "@apollo/client/react";
+
+interface CreateUserMutation {
+  createUser: {
+    id: string;
+    name: string;
+    email: string;
+  };
+}
+
+interface CreateUserMutationVariables {
+  input: {
+    name: string;
+    email: string;
+  };
+}
+
+const CREATE_USER: TypedDocumentNode<
+  CreateUserMutation,
+  CreateUserMutationVariables
+> = gql`
+  mutation CreateUser($input: CreateUserInput!) {
+    createUser(input: $input) {
+      id
+      name
+      email
+    }
+  }
+`;
+
+function CreateUserForm() {
+  const [createUser, { loading, error }] = useMutation(CREATE_USER);
+
+  const handleSubmit = async (formData: FormData) => {
+    const { data } = await createUser({
+      variables: {
+        input: {
+          name: formData.get("name") as string,
+          email: formData.get("email") as string,
+        },
+      },
+    });
+    if (data) {
+      console.log("Created user:", data.createUser);
+    }
+  };
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        handleSubmit(new FormData(e.currentTarget));
+      }}
+    >
+      <input name="name" placeholder="Name" />
+      <input name="email" placeholder="Email" />
+      <button type="submit" disabled={loading}>
+        {loading ? "Creating..." : "Create User"}
+      </button>
+      {error && <p>Error: {error.message}</p>}
+    </form>
+  );
+}
+```
+
+## Client Configuration Options
+
+```typescript
+const client = new ApolloClient({
+  // Required: The cache implementation
+  cache: new InMemoryCache({
+    typePolicies: {
+      Query: {
+        fields: {
+          // Field-level cache configuration
+        },
+      },
+    },
+  }),
+
+  // Network layer
+  link: new HttpLink({ uri: "/graphql" }),
+
+  // Avoid defaultOptions if possible as they break TypeScript expectations.
+  // Configure options per-query/mutation instead for better type safety.
+  // defaultOptions: {
+  //   watchQuery: { fetchPolicy: 'cache-and-network' },
+  // },
+
+  // DevTools are enabled by default in development
+  // Only configure when enabling in production
+  devtools: {
+    enabled: true, // Only needed for production
+  },
+
+  // Custom name for this client instance
+  clientAwareness: {
+    name: "web-client",
+    version: "1.0.0",
+  },
+});
+```
+
+## Important Considerations
+
+1. **Choose Your Hook Strategy:** Decide if your application should be based on Suspense. If it is, use suspenseful hooks like `useSuspenseQuery` (see [Suspense Hooks guide](suspense-hooks.md)), otherwise use non-suspenseful hooks like `useQuery` (see [Queries guide](queries.md)).
+
+2. **Client-Side Only:** This setup is for client-side apps without SSR. The Apollo Client instance is created once and reused throughout the application lifecycle.
+
+3. **Authentication:** Prefer HttpOnly cookies with `credentials: "include"` in `HttpLink` options to avoid exposing tokens to JavaScript. If manual token management is necessary, use `SetContextLink` to dynamically add authentication headers from `localStorage` or other client-side storage.
+
+4. **Environment Variables:** Store your GraphQL endpoint URL in environment variables for different environments (development, staging, production).
+
+5. **Error Handling:** Always handle `loading` and `error` states when using `useQuery` or `useLazyQuery`. For Suspense-based hooks (`useSuspenseQuery`), React handles this through `<Suspense>` boundaries and error boundaries.

package/skills/apollo-client/references/integration-nextjs.md

@@ -0,0 +1,325 @@
+# Apollo Client Integration with Next.js App Router
+
+This guide covers integrating Apollo Client in a Next.js application using the App Router architecture with support for both React Server Components (RSC) and Client Components.
+
+## What is supported?
+
+### React Server Components
+
+Apollo Client provides a shared client instance across all server components for a single request, preventing duplicate GraphQL requests and optimizing server-side rendering.
+
+### React Client Components
+
+When using the `app` directory, client components are rendered both on the server (SSR) and in the browser. Apollo Client enables you to execute GraphQL queries on the server and use the results to hydrate your browser-side cache, delivering fully-rendered pages to users.
+
+## Installation
+
+Install Apollo Client and the Next.js integration package:
+
+```bash
+npm install @apollo/client@latest @apollo/client-integration-nextjs graphql rxjs
+```
+
+> **TypeScript users:** For type-safe GraphQL operations, see the [TypeScript Code Generation guide](typescript-codegen.md).
+
+## Setup for React Server Components (RSC)
+
+### Step 1: Create Apollo Client Configuration
+
+Create an `ApolloClient.ts` file in your app directory:
+
+```typescript
+import { HttpLink } from "@apollo/client";
+import {
+  registerApolloClient,
+  ApolloClient,
+  InMemoryCache,
+} from "@apollo/client-integration-nextjs";
+
+export const { getClient, query, PreloadQuery } = registerApolloClient(() => {
+  return new ApolloClient({
+    cache: new InMemoryCache(),
+    link: new HttpLink({
+      // Use an absolute URL for SSR (relative URLs cannot be used in SSR)
+      uri: "https://your-api.com/graphql",
+      fetchOptions: {
+        // Optional: Next.js-specific fetch options for caching and revalidation
+        // See: https://nextjs.org/docs/app/api-reference/functions/fetch
+      },
+    }),
+  });
+});
+```
+
+### Step 2: Use in Server Components
+
+You can now use the `getClient` function or the `query` shortcut in your server components:
+
+```typescript
+import { query } from "./ApolloClient";
+
+async function UserProfile({ userId }: { userId: string }) {
+  const { data } = await query({
+    query: GET_USER,
+    variables: { id: userId },
+  });
+
+  return <div>{data.user.name}</div>;
+}
+```
+
+### Override Next.js Fetch Options
+
+You can override Next.js-specific `fetch` options per query using `context.fetchOptions`:
+
+```typescript
+const { data } = await getClient().query({
+  query: GET_USER,
+  context: {
+    fetchOptions: {
+      next: { revalidate: 60 }, // Revalidate every 60 seconds
+    },
+  },
+});
+```
+
+## Setup for Client Components (SSR and Browser)
+
+### Step 1: Create Apollo Wrapper Component
+
+Create `app/ApolloWrapper.tsx`:
+
+```typescript
+"use client";
+
+import { HttpLink } from "@apollo/client";
+import {
+  ApolloNextAppProvider,
+  ApolloClient,
+  InMemoryCache,
+} from "@apollo/client-integration-nextjs";
+
+function makeClient() {
+  const httpLink = new HttpLink({
+    // Use an absolute URL for SSR
+    uri: "https://your-api.com/graphql",
+    fetchOptions: {
+      // Optional: Next.js-specific fetch options
+      // Note: This doesn't work with `export const dynamic = "force-static"`
+    },
+  });
+
+  return new ApolloClient({
+    cache: new InMemoryCache(),
+    link: httpLink,
+  });
+}
+
+export function ApolloWrapper({ children }: React.PropsWithChildren) {
+  return (
+    <ApolloNextAppProvider makeClient={makeClient}>
+      {children}
+    </ApolloNextAppProvider>
+  );
+}
+```
+
+### Step 2: Wrap Root Layout
+
+Wrap your `RootLayout` in the `ApolloWrapper` component in `app/layout.tsx`:
+
+```typescript
+import { ApolloWrapper } from "./ApolloWrapper";
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <ApolloWrapper>{children}</ApolloWrapper>
+      </body>
+    </html>
+  );
+}
+```
+
+> **Note:** This works even if your layout is a React Server Component. It ensures all Client Components share the same Apollo Client instance through `ApolloNextAppProvider`.
+
+### Step 3: Use Apollo Client Hooks in Client Components
+
+For optimal streaming SSR, use suspense-enabled hooks like `useSuspenseQuery` and `useFragment`:
+
+```typescript
+"use client";
+
+import { useSuspenseQuery } from "@apollo/client/react";
+
+export function UserProfile({ userId }: { userId: string }) {
+  const { data } = useSuspenseQuery(GET_USER, {
+    variables: { id: userId },
+  });
+
+  return <div>{data.user.name}</div>;
+}
+```
+
+## Preloading Data from RSC to Client Components
+
+You can preload data in React Server Components to populate the cache of your Client Components.
+
+### Step 1: Use PreloadQuery in Server Components
+
+```tsx
+import { PreloadQuery } from "./ApolloClient";
+import { Suspense } from "react";
+
+export default async function Page() {
+  return (
+    <PreloadQuery query={GET_USER} variables={{ id: "1" }}>
+      <Suspense fallback={<>Loading...</>}>
+        <ClientChild />
+      </Suspense>
+    </PreloadQuery>
+  );
+}
+```
+
+### Step 2: Consume with useSuspenseQuery in Client Components
+
+```tsx
+"use client";
+
+import { useSuspenseQuery } from "@apollo/client/react";
+
+export function ClientChild() {
+  const { data } = useSuspenseQuery(GET_USER, {
+    variables: { id: "1" },
+  });
+
+  return <div>{data.user.name}</div>;
+}
+```
+
+> **Important:** Data fetched this way should be considered client data and never referenced in Server Components. `PreloadQuery` prevents mixing server data and client data by creating a separate `ApolloClient` instance.
+
+### Using with useReadQuery
+
+For advanced use cases, you can use `PreloadQuery` with `useReadQuery` to avoid request waterfalls:
+
+```tsx
+<PreloadQuery query={GET_USER} variables={{ id: "1" }}>
+  {(queryRef) => (
+    <Suspense fallback={<>Loading...</>}>
+      <ClientChild queryRef={queryRef} />
+    </Suspense>
+  )}
+</PreloadQuery>
+```
+
+In your Client Component:
+
+```tsx
+"use client";
+
+import {
+  useQueryRefHandlers,
+  useReadQuery,
+  QueryRef,
+} from "@apollo/client/react";
+
+export function ClientChild({ queryRef }: { queryRef: QueryRef<TQueryData> }) {
+  const { refetch } = useQueryRefHandlers(queryRef);
+  const { data } = useReadQuery(queryRef);
+
+  return <div>{data.user.name}</div>;
+}
+```
+
+## Handling Multipart Responses (@defer) in SSR
+
+When using the `@defer` directive, `useSuspenseQuery` will only suspend until the initial response is received. To handle deferred data properly, you have three strategies:
+
+### Strategy 1: Use PreloadQuery with useReadQuery
+
+`PreloadQuery` allows deferred data to be fully transported and streamed chunk-by-chunk.
+
+### Strategy 2: Remove @defer Fragments
+
+Use `RemoveMultipartDirectivesLink` to strip `@defer` directives from queries during SSR:
+
+```typescript
+import { RemoveMultipartDirectivesLink } from "@apollo/client-integration-nextjs";
+
+new RemoveMultipartDirectivesLink({
+  stripDefer: true, // Default: true
+});
+```
+
+You can exclude specific fragments from stripping by labeling them:
+
+```graphql
+query myQuery {
+  fastField
+  ... @defer(label: "SsrDontStrip1") {
+    slowField1
+  }
+}
+```
+
+### Strategy 3: Wait for Deferred Data
+
+Use `AccumulateMultipartResponsesLink` to debounce the initial response:
+
+```typescript
+import { AccumulateMultipartResponsesLink } from "@apollo/client-integration-nextjs";
+
+new AccumulateMultipartResponsesLink({
+  cutoffDelay: 100, // Wait up to 100ms for incremental data
+});
+```
+
+### Combined Approach: SSRMultipartLink
+
+Combine both strategies with `SSRMultipartLink`:
+
+```typescript
+import { SSRMultipartLink } from "@apollo/client-integration-nextjs";
+
+new SSRMultipartLink({
+  stripDefer: true,
+  cutoffDelay: 100,
+});
+```
+
+## Testing
+
+Reset singleton instances between tests using the `resetApolloClientSingletons` helper:
+
+```typescript
+import { resetApolloClientSingletons } from "@apollo/client-integration-nextjs";
+
+afterEach(resetApolloClientSingletons);
+```
+
+## Debugging
+
+Enable verbose logging in your `app/ApolloWrapper.tsx`:
+
+```typescript
+import { setLogVerbosity } from "@apollo/client";
+
+setLogVerbosity("debug");
+```
+
+## Important Considerations
+
+1. **Separate RSC and SSR Queries:** Avoid overlapping queries between RSC and SSR. RSC queries don't update in the browser, while SSR queries can update dynamically as the cache changes.
+
+2. **Use Absolute URLs:** Always use absolute URLs in `HttpLink` for SSR, as relative URLs cannot be used in server-side rendering.
+
+3. **Streaming SSR:** For optimal performance, use `useSuspenseQuery` and `useFragment` to take advantage of React 18's streaming SSR capabilities.
+
+4. **Suspense Boundaries:** Place `Suspense` boundaries at meaningful places in your UI for the best user experience.