dantrain · dantrain · Feb 15, 2026 · Jan 31, 2026 · Jan 31, 2026 · Jan 31, 2026
diff --git a/.changeset/new-response-format.md b/.changeset/new-response-format.md
@@ -0,0 +1,57 @@
+---
+"@remix-relay/react": major
+"@remix-relay/server": major
+---
+
+Update to GraphQL incremental delivery format (incrementalSpec v0.2)
+
+### Breaking changes
+
+- **`graphql` peer dependency updated from `17.0.0-alpha.2` to `17.0.0-alpha.9`** - Adopts the newer incremental delivery response format with `pending`/`incremental`/`completed` fields.
+
+- **Client fetch function must use `processMultipartResponse`** - The client-side relay environment fetch function must be updated to use the new `processMultipartResponse` utility exported from `@remix-relay/react`, which handles the new response format. The `Accept` header must also change from `deferSpec=20220824` to `incrementalSpec=v0.2`.
+
+### Migration
+
+Update the `graphql` dependency:
+
+```shell
+pnpm add graphql@17.0.0-alpha.9
+```
+
+Update the client relay environment fetch function to use `processMultipartResponse`:
+
+```typescript
+import {
+  getCachedResponse,
+  processMultipartResponse,
+} from "@remix-relay/react";
+
+const fetchFn: FetchFunction = (params, variables, cacheConfig) => {
+  return (
+    getCachedResponse(params, variables, cacheConfig) ??
+    Observable.create((sink) => {
+      (async () => {
+        try {
+          const response = await fetch("/graphql", {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Accept: "multipart/mixed; incrementalSpec=v0.2, application/json",
+            },
+            body: JSON.stringify({ query: params.text, variables }),
+          });
+
+          const parts = await meros(response);
+
+          for await (const payload of processMultipartResponse(parts)) {
+            sink.next(payload);
+          }
+        } finally {
+          sink.complete();
+        }
+      })();
+    })
+  );
+};
+```
diff --git a/apps/counter-app/app/lib/relay-environment.ts b/apps/counter-app/app/lib/relay-environment.ts
@@ -19,7 +19,10 @@ import {
 import { PayloadExtensions } from "relay-runtime/lib/network/RelayNetworkTypes";
 import { toast } from "sonner";
 import invariant from "tiny-invariant";
-import { getCachedResponse } from "@remix-relay/react";
+import {
+  getCachedResponse,
+  processMultipartResponse,
+} from "@remix-relay/react";
 import { trackPromise } from "~/components/Progress";
 
 const isServer = typeof document === "undefined";
@@ -39,7 +42,7 @@ const fetchFn: FetchFunction = (
             method: "POST",
             headers: {
               "Content-Type": "application/json",
-              Accept: "multipart/mixed; deferSpec=20220824, application/json",
+              Accept: "multipart/mixed; incrementalSpec=v0.2, application/json",
             },
             body: JSON.stringify({
               query: params.text,
@@ -55,24 +58,8 @@ const fetchFn: FetchFunction = (
 
           const parts = await meros(response);
 
-          if (parts instanceof Response) {
-            const result = await parts.json();
-            if (result.errors) {
-              throw new Error(result.errors?.[0]?.message);
-            }
-
-            sink.next(result);
-          } else {
-            for await (const part of parts) {
-              if (part.body.errors) {
-                throw new Error(part.body.errors?.[0]?.message);
-              }
-
-              sink.next({
-                ...part.body,
-                ...part.body?.incremental?.[0],
-              });
-            }
+          for await (const payload of processMultipartResponse(parts)) {
+            sink.next(payload);
           }
         } catch (err) {
           if (!isServer) {

diff --git a/apps/counter-app/package.json b/apps/counter-app/package.json
@@ -16,7 +16,7 @@
     "write-graphql-schema": "tsx ./scripts/write-graphql-schema.ts"
   },
   "dependencies": {
-    "@apollo/server": "5.0.0",
+    "@apollo/server": "^5.1.0",
     "@as-integrations/express5": "^1.1.2",
     "@paralleldrive/cuid2": "^3.3.0",
     "@pothos/core": "^4.12.0",
@@ -34,7 +34,7 @@
     "cookie-parser": "^1.4.7",
     "cors": "^2.8.6",
     "express": "^5.2.1",
-    "graphql": "17.0.0-alpha.2",
+    "graphql": "17.0.0-alpha.9",
     "graphql-relay": "^0.10.2",
     "graphql-subscriptions": "^3.0.0",
     "graphql-ws": "^6.0.7",

diff --git a/apps/counter-app/schema.graphql b/apps/counter-app/schema.graphql
@@ -17,7 +17,7 @@ directive @stream(
   if: Boolean! = true
 
   """Number of items to return immediately"""
-  initialCount: Int = 0
+  initialCount: Int! = 0
 
   """Unique name"""
   label: String

diff --git a/apps/movie-app/app/lib/relay-environment.ts b/apps/movie-app/app/lib/relay-environment.ts
@@ -12,7 +12,10 @@ import {
   RecordSource,
   Store,
 } from "relay-runtime";
-import { getCachedResponse } from "@remix-relay/react";
+import {
+  getCachedResponse,
+  processMultipartResponse,
+} from "@remix-relay/react";
 
 const isServer = typeof document === "undefined";
 
@@ -30,7 +33,7 @@ const fetchFn: FetchFunction = (
             method: "POST",
             headers: {
               "Content-Type": "application/json",
-              Accept: "multipart/mixed; deferSpec=20220824, application/json",
+              Accept: "multipart/mixed; incrementalSpec=v0.2, application/json",
             },
             body: JSON.stringify({
               doc_id: params.id,
@@ -40,23 +43,8 @@ const fetchFn: FetchFunction = (
 
           const parts = await meros(response);
 
-          // Check if it's a Response-like object (has .json method)
-          if (parts && typeof (parts as Response).json === "function") {
-            sink.next(await (parts as Response).json());
-          } else {
-            for await (const part of parts as AsyncIterable<{
-              json: boolean;
-              body: unknown;
-            }>) {
-              const data = part.json
-                ? {
-                    ...(part.body as object),
-                    ...((part.body as { incremental?: object[] })
-                      ?.incremental?.[0] ?? {}),
-                  }
-                : JSON.parse(part.body as string);
-              sink.next(data);
-            }
+          for await (const payload of processMultipartResponse(parts)) {
+            sink.next(payload);
           }
         } catch (err) {
           if (!isServer) {

diff --git a/apps/movie-app/package.json b/apps/movie-app/package.json
@@ -19,7 +19,6 @@
     "write-graphql-schema": "tsx ./scripts/write-graphql-schema.ts"
   },
   "dependencies": {
-    "@graphql-tools/executor": "^1.5.1",
     "@graphql-yoga/plugin-defer-stream": "^3.18.0",
     "@graphql-yoga/plugin-persisted-operations": "^3.18.0",
     "@pothos/core": "^4.12.0",
@@ -30,7 +29,7 @@
     "@remix-relay/ui": "workspace:*",
     "class-variance-authority": "^0.7.1",
     "drizzle-orm": "^0.45.1",
-    "graphql": "17.0.0-alpha.2",
+    "graphql": "17.0.0-alpha.9",
     "graphql-yoga": "^5.18.0",
     "isbot": "^5.1.34",
     "lodash-es": "^4.17.23",

diff --git a/apps/movie-app/schema.graphql b/apps/movie-app/schema.graphql
@@ -17,7 +17,7 @@ directive @stream(
   if: Boolean! = true
 
   """Number of items to return immediately"""
-  initialCount: Int = 0
+  initialCount: Int! = 0
 
   """Unique name"""
   label: String

diff --git a/apps/trellix-relay/app/lib/relay-environment.tsx b/apps/trellix-relay/app/lib/relay-environment.tsx
@@ -20,7 +20,10 @@ import {
 import { PayloadExtensions } from "relay-runtime/lib/network/RelayNetworkTypes";
 import { toast } from "sonner";
 import invariant from "tiny-invariant";
-import { getCachedResponse } from "@remix-relay/react";
+import {
+  getCachedResponse,
+  processMultipartResponse,
+} from "@remix-relay/react";
 import { trackPromise } from "~/components/Progress";
 
 const isServer = typeof document === "undefined";
@@ -40,7 +43,7 @@ const fetchFn: FetchFunction = (
             method: "POST",
             headers: {
               "Content-Type": "application/json",
-              Accept: "multipart/mixed; deferSpec=20220824, application/json",
+              Accept: "multipart/mixed; incrementalSpec=v0.2, application/json",
             },
             body: JSON.stringify({
               query: params.text,
@@ -56,24 +59,8 @@ const fetchFn: FetchFunction = (
 
           const parts = await meros(response);
 
-          if (parts instanceof Response) {
-            const result = await parts.json();
-            if (result.errors) {
-              throw new Error(result.errors?.[0]?.message);
-            }
-
-            sink.next(result);
-          } else {
-            for await (const part of parts) {
-              if (part.body.errors) {
-                throw new Error(part.body.errors?.[0]?.message);
-              }
-
-              sink.next({
-                ...part.body,
-                ...part.body?.incremental?.[0],
-              });
-            }
+          for await (const payload of processMultipartResponse(parts)) {
+            sink.next(payload);
           }
         } catch (err) {
           if (!isServer) {

diff --git a/apps/trellix-relay/package.json b/apps/trellix-relay/package.json
@@ -19,7 +19,7 @@
     "write-graphql-schema": "tsx ./scripts/write-graphql-schema.ts"
   },
   "dependencies": {
-    "@apollo/server": "5.0.0",
+    "@apollo/server": "^5.1.0",
     "@as-integrations/express5": "^1.1.2",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
@@ -46,7 +46,7 @@
     "cors": "^2.8.6",
     "drizzle-orm": "^0.45.1",
     "express": "^5.2.1",
-    "graphql": "17.0.0-alpha.2",
+    "graphql": "17.0.0-alpha.9",
     "graphql-relay": "^0.10.2",
     "graphql-subscriptions": "^3.0.0",
     "graphql-ws": "^6.0.7",

diff --git a/apps/trellix-relay/schema.graphql b/apps/trellix-relay/schema.graphql
@@ -17,7 +17,7 @@ directive @stream(
   if: Boolean! = true
 
   """Number of items to return immediately"""
-  initialCount: Int = 0
+  initialCount: Int! = 0
 
   """Unique name"""
   label: String

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -27,7 +27,7 @@ pnpm create react-router@latest --template remix-run/react-router-templates/node
 For this guide we'll use [Pothos](https://pothos-graphql.dev/) to create the GraphQL schema.
 
 ```shell
-pnpm add @pothos/core graphql@17.0.0-alpha.2
+pnpm add @pothos/core graphql@17.0.0-alpha.9
 ```
 
 > [!NOTE]
@@ -191,24 +191,20 @@ Add an `app/lib/relay-environment.ts` file.
 
 ```typescript
 import { meros } from "meros/browser";
+import type { FetchFunction } from "relay-runtime";
 import {
-  type CacheConfig,
-  type FetchFunction,
-  type RequestParameters,
-  type Variables,
   Environment,
   Network,
   Observable,
   RecordSource,
   Store,
 } from "relay-runtime";
-import { getCachedResponse } from "@remix-relay/react";
+import {
+  getCachedResponse,
+  processMultipartResponse,
+} from "@remix-relay/react";
 
-const fetchFn: FetchFunction = (
-  params: RequestParameters,
-  variables: Variables,
-  cacheConfig: CacheConfig,
-) => {
+const fetchFn: FetchFunction = (params, variables, cacheConfig) => {
   return (
     getCachedResponse(params, variables, cacheConfig) ??
     Observable.create((sink) => {
@@ -218,25 +214,15 @@ const fetchFn: FetchFunction = (
             method: "POST",
             headers: {
               "Content-Type": "application/json",
-              Accept: "multipart/mixed; deferSpec=20220824, application/json",
+              Accept: "multipart/mixed; incrementalSpec=v0.2, application/json",
             },
-            body: JSON.stringify({
-              query: params.text,
-              variables,
-            }),
+            body: JSON.stringify({ query: params.text, variables }),
           });
 
           const parts = await meros(response);
 
-          if (parts instanceof Response) {
-            sink.next(await parts.json());
-          } else {
-            for await (const part of parts) {
-              sink.next({
-                ...part.body,
-                ...part.body?.incremental?.[0],
-              });
-            }
+          for await (const payload of processMultipartResponse(parts)) {
+            sink.next(payload);
           }
         } finally {
           sink.complete();
@@ -265,7 +251,7 @@ export function getCurrentEnvironment() {
 }
 ```
 
-Note the use of `fetch` to request data, and the [meros](https://github.com/maraisr/meros) library to read the multipart response. This enables streaming of client requests.
+Note the use of `fetch` to request data, and the [meros](https://github.com/maraisr/meros) library to read the multipart response. The `processMultipartResponse` utility from `@remix-relay/react` handles the incremental delivery format used by `@defer`.
 
 Add providers and a Suspense boundary to `app/root.tsx`.
 

diff --git a/package.json b/package.json
@@ -33,7 +33,7 @@
   "pnpm": {
     "peerDependencyRules": {
       "allowedVersions": {
-        "graphql": "17.0.0-alpha.2"
+        "graphql": "17.0.0-alpha.9"
       }
     }
   }

diff --git a/packages/react/package.json b/packages/react/package.json
@@ -45,9 +45,6 @@
     "lint": "eslint . --max-warnings 0",
     "typecheck": "tsc -b --noEmit"
   },
-  "dependencies": {
-    "tiny-invariant": "^1.3.3"
-  },
   "devDependencies": {
     "@remix-relay/eslint-config": "workspace:*",
     "@remix-relay/typescript-config": "workspace:*",
@@ -58,7 +55,7 @@
     "@types/react-relay": "^18.2.1",
     "@types/relay-runtime": "^20.1.1",
     "eslint": "^9.39.0",
-    "graphql": "17.0.0-alpha.2",
+    "graphql": "17.0.0-alpha.9",
     "jiti": "^2.6.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",