npm - @apollo/client - Versions diffs - 4.1.6 → 4.1.8 - Mend

@apollo/client 4.1.6 → 4.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/CHANGELOG.md +13 -0
package/__cjs/link/ws/index.cjs +9 -1
package/__cjs/link/ws/index.cjs.map +1 -1
package/__cjs/link/ws/index.d.cts +1 -1
package/__cjs/react/hooks/useSubscription.cjs +1 -1
package/__cjs/react/hooks/useSubscription.cjs.map +1 -1
package/__cjs/react/hooks/useSubscription.d.cts +2 -2
package/__cjs/version.cjs +1 -1
package/link/ws/index.d.ts +1 -1
package/link/ws/index.js +9 -1
package/link/ws/index.js.map +1 -1
package/package.json +3 -2
package/react/hooks/useSubscription.d.ts +2 -2
package/react/hooks/useSubscription.js +1 -1
package/react/hooks/useSubscription.js.map +1 -1
package/react/hooks-compiled/useSubscription.d.ts +2 -2
package/react/hooks-compiled/useSubscription.js +1 -1
package/react/hooks-compiled/useSubscription.js.map +1 -1
package/skills/apollo-client/SKILL.md +168 -0
package/skills/apollo-client/references/caching.md +560 -0
package/skills/apollo-client/references/error-handling.md +344 -0
package/skills/apollo-client/references/fragments.md +804 -0
package/skills/apollo-client/references/integration-client.md +340 -0
package/skills/apollo-client/references/integration-nextjs.md +325 -0
package/skills/apollo-client/references/integration-react-router.md +256 -0
package/skills/apollo-client/references/integration-tanstack-start.md +378 -0
package/skills/apollo-client/references/mutations.md +549 -0
package/skills/apollo-client/references/queries.md +416 -0
package/skills/apollo-client/references/state-management.md +428 -0
package/skills/apollo-client/references/suspense-hooks.md +773 -0
package/skills/apollo-client/references/troubleshooting.md +487 -0
package/skills/apollo-client/references/typescript-codegen.md +133 -0
package/version.js +1 -1

package/skills/apollo-client/references/integration-react-router.md ADDED Viewed

@@ -0,0 +1,256 @@
+# Apollo Client Integration with React Router Framework Mode
+This guide covers integrating Apollo Client in a React Router 7 application with support for modern streaming SSR.
+## Installation
+Install Apollo Client and the React Router integration package:
+```bash
+npm install @apollo/client-integration-react-router @apollo/client graphql rxjs
+```
+> **TypeScript users:** For type-safe GraphQL operations, see the [TypeScript Code Generation guide](typescript-codegen.md).
+## Setup
+### Step 1: Create Apollo Configuration
+Create an `app/apollo.ts` file that exports a `makeClient` function and an `apolloLoader`:
+```typescript
+import { HttpLink, InMemoryCache } from "@apollo/client";
+import {
+  createApolloLoaderHandler,
+  ApolloClient,
+} from "@apollo/client-integration-react-router";
+// `request` will be available on the server during SSR or in loaders, but not in the browser
+export const makeClient = (request?: Request) => {
+  return new ApolloClient({
+    cache: new InMemoryCache(),
+    link: new HttpLink({ uri: "https://your-graphql-endpoint.com/graphql" }),
+  });
+};
+export const apolloLoader = createApolloLoaderHandler(makeClient);
+```
+> **Important:** `ApolloClient` must be imported from `@apollo/client-integration-react-router`, not from `@apollo/client`.
+### Step 2: Reveal Entry Files
+Run the following command to create the entry files if they don't exist:
+```bash
+npx react-router reveal
+```
+This will create `app/entry.client.tsx` and `app/entry.server.tsx`.
+### Step 3: Configure Client Entry
+Adjust `app/entry.client.tsx` to wrap your app in `ApolloProvider`:
+```typescript
+import { makeClient } from "./apollo";
+import { ApolloProvider } from "@apollo/client";
+import { StrictMode, startTransition } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { HydratedRouter } from "react-router/dom";
+startTransition(() => {
+  const client = makeClient();
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <ApolloProvider client={client}>
+        <HydratedRouter />
+      </ApolloProvider>
+    </StrictMode>
+  );
+});
+```
+### Step 4: Configure Server Entry
+Adjust `app/entry.server.tsx` to wrap your app in `ApolloProvider` during SSR:
+```typescript
+import { makeClient } from "./apollo";
+import { ApolloProvider } from "@apollo/client";
+// ... other imports
+export default function handleRequest(
+  request: Request,
+  responseStatusCode: number,
+  responseHeaders: Headers,
+  routerContext: EntryContext
+) {
+  return new Promise((resolve, reject) => {
+    // ... existing code
+    const client = makeClient(request);
+    const { pipe, abort } = renderToPipeableStream(
+      <ApolloProvider client={client}>
+        <ServerRouter
+          context={routerContext}
+          url={request.url}
+          abortDelay={ABORT_DELAY}
+        />
+      </ApolloProvider>,
+      {
+        [readyOption]() {
+          shellRendered = true;
+          // ... rest of the handler
+        },
+        // ... other options
+      }
+    );
+  });
+}
+```
+### Step 5: Add Hydration Helper
+Add `<ApolloHydrationHelper>` to `app/root.tsx`:
+```typescript
+import { ApolloHydrationHelper } from "@apollo/client-integration-react-router";
+import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        <ApolloHydrationHelper>{children}</ApolloHydrationHelper>
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+export default function App() {
+  return <Outlet />;
+}
+```
+## Usage
+### Using apolloLoader with useReadQuery
+You can now use the `apolloLoader` function to create Apollo-enabled loaders for your routes:
+```typescript
+import { gql } from "@apollo/client";
+import { useReadQuery } from "@apollo/client/react";
+import { useLoaderData } from "react-router";
+import type { Route } from "./+types/my-route";
+import type { TypedDocumentNode } from "@apollo/client";
+import { apolloLoader } from "./apollo";
+// TypedDocumentNode definition with types
+const GET_USER: TypedDocumentNode<
+  { user: { id: string; name: string; email: string } },
+  { id: string }
+> = gql`
+  query GetUser($id: ID!) {
+    user(id: $id) {
+      id
+      name
+      email
+    }
+  }
+`;
+export const loader = apolloLoader<Route.LoaderArgs>()(({ preloadQuery }) => {
+  const userQueryRef = preloadQuery(GET_USER, {
+    variables: { id: "1" },
+  });
+  return {
+    userQueryRef,
+  };
+});
+export default function UserPage() {
+  const { userQueryRef } = useLoaderData<typeof loader>();
+  const { data } = useReadQuery(userQueryRef);
+  return (
+    <div>
+      <h1>{data.user.name}</h1>
+      <p>{data.user.email}</p>
+    </div>
+  );
+}
+```
+> **Important:** To provide better TypeScript support, `apolloLoader` is a method that you need to call twice: `apolloLoader<LoaderArgs>()(loader)`
+### Multiple Queries in a Loader
+You can preload multiple queries in a single loader:
+```typescript
+import { gql } from "@apollo/client";
+import { useReadQuery } from "@apollo/client/react";
+import { useLoaderData } from "react-router";
+import type { Route } from "./+types/my-route";
+import { apolloLoader } from "./apollo";
+// TypedDocumentNode definitions omitted for brevity
+export const loader = apolloLoader<Route.LoaderArgs>()(({ preloadQuery }) => {
+  const userQueryRef = preloadQuery(GET_USER, {
+    variables: { id: "1" },
+  });
+  const postsQueryRef = preloadQuery(GET_POSTS, {
+    variables: { userId: "1" },
+  });
+  return {
+    userQueryRef,
+    postsQueryRef,
+  };
+});
+export default function UserPage() {
+  const { userQueryRef, postsQueryRef } = useLoaderData<typeof loader>();
+  const { data: userData } = useReadQuery(userQueryRef);
+  const { data: postsData } = useReadQuery(postsQueryRef);
+  return (
+    <div>
+      <h1>{userData.user.name}</h1>
+      <h2>Posts</h2>
+      <ul>
+        {postsData.posts.map((post) => (
+          <li key={post.id}>{post.title}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+## Important Considerations
+1. **Import ApolloClient from Integration Package:** Always import `ApolloClient` from `@apollo/client-integration-react-router`, not from `@apollo/client`, to ensure proper SSR hydration.
+2. **TypeScript Support:** The `apolloLoader` function requires double invocation for proper TypeScript type inference: `apolloLoader<LoaderArgs>()(loader)`.
+3. **Request Context:** The `makeClient` function receives the `Request` object during SSR and in loaders, but not in the browser. Use this to set up auth headers or other request-specific configuration.
+4. **Streaming SSR:** The integration fully supports React's streaming SSR capabilities. Place `Suspense` boundaries strategically for optimal user experience.
+5. **Cache Hydration:** The `ApolloHydrationHelper` component ensures that data loaded on the server is properly hydrated on the client, preventing unnecessary refetches.

package/skills/apollo-client/references/integration-tanstack-start.md ADDED Viewed

@@ -0,0 +1,378 @@
+# Apollo Client Integration with TanStack Start
+This guide covers integrating Apollo Client in a TanStack Start application with support for modern streaming SSR.
+> **Note:** When using `npx create-tsrouter-app` to create a new TanStack Start application, you can choose Apollo Client in the setup wizard to have all of this configuration automatically set up for you.
+## Installation
+Install Apollo Client and the TanStack Start integration package:
+```bash
+npm install @apollo/client-integration-tanstack-start @apollo/client graphql rxjs
+```
+> **TypeScript users:** For type-safe GraphQL operations, see the [TypeScript Code Generation guide](typescript-codegen.md).
+## Setup
+### Step 1: Configure Root Route with Context
+In your `routes/__root.tsx`, change from `createRootRoute` to `createRootRouteWithContext` to provide the right context type:
+```typescript
+import type { ApolloClientIntegration } from "@apollo/client-integration-tanstack-start";
+import {
+  createRootRouteWithContext,
+  Outlet,
+} from "@tanstack/react-router";
+export const Route = createRootRouteWithContext<ApolloClientIntegration.RouterContext>()({
+  component: RootComponent,
+});
+function RootComponent() {
+  return (
+    <html>
+      <head>
+        <meta charSet="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>My App</title>
+      </head>
+      <body>
+        <Outlet />
+      </body>
+    </html>
+  );
+}
+```
+### Step 2: Set Up Apollo Client in Router
+In your `router.tsx`, set up your Apollo Client instance and run `routerWithApolloClient`:
+```typescript
+import {
+  routerWithApolloClient,
+  ApolloClient,
+  InMemoryCache,
+} from "@apollo/client-integration-tanstack-start";
+import { HttpLink } from "@apollo/client";
+import { createRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+export function getRouter() {
+  const apolloClient = new ApolloClient({
+    cache: new InMemoryCache(),
+    link: new HttpLink({ uri: "https://your-graphql-endpoint.com/graphql" }),
+  });
+  const router = createRouter({
+    routeTree,
+    context: {
+      ...routerWithApolloClient.defaultContext,
+    },
+  });
+  return routerWithApolloClient(router, apolloClient);
+}
+```
+> **Important:** `ApolloClient` and `InMemoryCache` must be imported from `@apollo/client-integration-tanstack-start`, not from `@apollo/client`.
+## Usage
+### Option 1: Loader with preloadQuery and useReadQuery
+Use the `preloadQuery` function in your route loader to preload data during navigation:
+```typescript
+import { gql } from "@apollo/client";
+import { useReadQuery } from "@apollo/client/react";
+import { createFileRoute } from "@tanstack/react-router";
+import type { TypedDocumentNode } from "@apollo/client";
+// TypedDocumentNode definition with types
+const GET_USER: TypedDocumentNode<
+  { user: { id: string; name: string; email: string } },
+  { id: string }
+> = gql`
+  query GetUser($id: ID!) {
+    user(id: $id) {
+      id
+      name
+      email
+    }
+  }
+`;
+export const Route = createFileRoute("/user/$userId")({
+  component: RouteComponent,
+  loader: ({ context: { preloadQuery }, params }) => {
+    const queryRef = preloadQuery(GET_USER, {
+      variables: { id: params.userId },
+    });
+    return {
+      queryRef,
+    };
+  },
+});
+function RouteComponent() {
+  const { queryRef } = Route.useLoaderData();
+  const { data } = useReadQuery(queryRef);
+  return (
+    <div>
+      <h1>{data.user.name}</h1>
+      <p>{data.user.email}</p>
+    </div>
+  );
+}
+```
+### Option 2: Direct useSuspenseQuery in Component
+You can also use Apollo Client's suspenseful hooks directly in your component without a loader:
+```typescript
+import { gql } from "@apollo/client";
+import { useSuspenseQuery } from "@apollo/client/react";
+import { createFileRoute } from "@tanstack/react-router";
+import type { TypedDocumentNode } from "@apollo/client";
+// TypedDocumentNode definition with types
+const GET_POSTS: TypedDocumentNode<{
+  posts: Array<{ id: string; title: string; content: string }>;
+}> = gql`
+  query GetPosts {
+    posts {
+      id
+      title
+      content
+    }
+  }
+`;
+export const Route = createFileRoute("/posts")({
+  component: RouteComponent,
+});
+function RouteComponent() {
+  const { data } = useSuspenseQuery(GET_POSTS);
+  return (
+    <div>
+      <h1>Posts</h1>
+      <ul>
+        {data.posts.map((post) => (
+          <li key={post.id}>
+            <h2>{post.title}</h2>
+            <p>{post.content}</p>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+### Multiple Queries in a Loader
+You can preload multiple queries in a single loader:
+```typescript
+import { gql } from "@apollo/client";
+import { useReadQuery } from "@apollo/client/react";
+import { createFileRoute } from "@tanstack/react-router";
+// TypedDocumentNode definitions omitted for brevity
+export const Route = createFileRoute("/dashboard")({
+  component: RouteComponent,
+  loader: ({ context: { preloadQuery } }) => {
+    const userQueryRef = preloadQuery(GET_USER, {
+      variables: { id: "current" },
+    });
+    const statsQueryRef = preloadQuery(GET_STATS, {
+      variables: { period: "month" },
+    });
+    return {
+      userQueryRef,
+      statsQueryRef,
+    };
+  },
+});
+function RouteComponent() {
+  const { userQueryRef, statsQueryRef } = Route.useLoaderData();
+  const { data: userData } = useReadQuery(userQueryRef);
+  const { data: statsData } = useReadQuery(statsQueryRef);
+  return (
+    <div>
+      <h1>Welcome, {userData.user.name}</h1>
+      <div>
+        <h2>Monthly Stats</h2>
+        <p>Views: {statsData.stats.views}</p>
+        <p>Clicks: {statsData.stats.clicks}</p>
+      </div>
+    </div>
+  );
+}
+```
+### Using useQueryRefHandlers for Refetching
+When using `useReadQuery`, you can get refetch functionality from `useQueryRefHandlers`:
+> **Important:** Always call `useQueryRefHandlers` before `useReadQuery`. These two hooks interact with the same `queryRef`, and calling them in the wrong order could cause subtle bugs.
+```typescript
+import { useReadQuery, useQueryRefHandlers, QueryRef } from "@apollo/client/react";
+function UserComponent({ queryRef }: { queryRef: QueryRef<GetUserQuery> }) {
+  const { refetch } = useQueryRefHandlers(queryRef);
+  const { data } = useReadQuery(queryRef);
+  return (
+    <div>
+      <h1>{data.user.name}</h1>
+      <button onClick={() => refetch()}>Refresh</button>
+    </div>
+  );
+}
+```
+## Important Considerations
+1. **Import from Integration Package:** Always import `ApolloClient` and `InMemoryCache` from `@apollo/client-integration-tanstack-start`, not from `@apollo/client`, to ensure proper SSR hydration.
+2. **Context Type:** Use `createRootRouteWithContext<ApolloClientIntegration.RouterContext>()` to provide proper TypeScript types for the `preloadQuery` function in loaders.
+3. **Loader vs Component Queries:**
+   - Use `preloadQuery` in loaders when you want to start fetching data before the component renders
+   - Use `useSuspenseQuery` directly in components for simpler cases or when data fetching can wait until render
+4. **Streaming SSR:** The integration fully supports React's streaming SSR capabilities. Place `Suspense` boundaries strategically for optimal user experience.
+5. **Cache Management:** The Apollo Client instance is shared across all routes, so cache updates from one route will be reflected in all routes that use the same data.
+6. **Authentication:** Use Apollo Client's `SetContextLink` for dynamic auth tokens.
+## Advanced Configuration
+### Adding Authentication
+For authentication in TanStack Start with SSR support, you need to handle both server and client environments differently. Use `createIsomorphicFn` to provide environment-specific implementations:
+```typescript
+import {
+  ApolloClient,
+  InMemoryCache,
+  routerWithApolloClient,
+} from "@apollo/client-integration-tanstack-start";
+import { ApolloLink, HttpLink } from "@apollo/client";
+import { SetContextLink } from "@apollo/client/link/context";
+import { createIsomorphicFn } from "@tanstack/react-start";
+import { createRouter } from "@tanstack/react-router";
+import { getSession, getCookie } from "@tanstack/react-start/server";
+import { routeTree } from "./routeTree.gen";
+// Create isomorphic link that uses different implementations per environment
+const createAuthLink = createIsomorphicFn()
+  .server(() => {
+    // Server-only: Can access server-side functions like `getCookies`, `getCookie`, `getSession`, etc. exported from `"@tanstack/react-start/server"`
+    return new SetContextLink(async (prevContext) => {
+      return {
+        headers: {
+          ...prevContext.headers,
+          authorization: getCookie("Authorization"),
+        },
+      };
+    });
+  })
+  .client(() => {
+    // Client-only: Can access `localStorage` or other browser APIs
+    return new SetContextLink((prevContext) => {
+      return {
+        headers: {
+          ...prevContext.headers,
+          authorization: localStorage.getItem("authToken") ?? "",
+        },
+      };
+    });
+  });
+export function getRouter() {
+  const httpLink = new HttpLink({
+    uri: "https://your-graphql-endpoint.com/graphql",
+  });
+  const apolloClient = new ApolloClient({
+    cache: new InMemoryCache(),
+    link: ApolloLink.from([createAuthLink(), httpLink]),
+  });
+  const router = createRouter({
+    routeTree,
+    context: {
+      ...routerWithApolloClient.defaultContext,
+    },
+  });
+  return routerWithApolloClient(router, apolloClient);
+}
+```
+> **Important:** The `getRouter` function is called both on the server and client, so it must not contain environment-specific code. Use `createIsomorphicFn` to provide different implementations:
+>
+> - **Server:** Can access server-only functions like `getSession`, `getCookies`, `getCookie` from `@tanstack/react-start/server` to access authentication information in request or session data
+> - **Client:** Can use `localStorage` or other browser APIs to access auth tokens (if setting `credentials: "include"` is sufficient, try to prefer that over manually setting auth headers client-side)
+>
+> This ensures your authentication works correctly in both SSR and browser contexts.
+### Custom Cache Configuration
+```typescript
+import {
+  ApolloClient,
+  InMemoryCache,
+} from "@apollo/client-integration-tanstack-start";
+import { HttpLink } from "@apollo/client";
+import { createRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+import { routerWithApolloClient } from "@apollo/client-integration-tanstack-start";
+export function getRouter() {
+  const apolloClient = new ApolloClient({
+    cache: new InMemoryCache({
+      typePolicies: {
+        Query: {
+          fields: {
+            posts: {
+              merge(existing = [], incoming) {
+                return [...existing, ...incoming];
+              },
+            },
+          },
+        },
+      },
+    }),
+    link: new HttpLink({ uri: "https://your-graphql-endpoint.com/graphql" }),
+  });
+  const router = createRouter({
+    routeTree,
+    context: {
+      ...routerWithApolloClient.defaultContext,
+    },
+  });
+  return routerWithApolloClient(router, apolloClient);
+}
+```