Merge branch 'main' into release-4.0

Author: jerelmiller

README.md

@@ -1,57 +1,106 @@
-<div align="center">
+<header>
+  <div align="center">
+    <a href="https://www.apollographql.com?utm_medium=github&utm_source=apollographql_apollo-client&utm_campaign=readme"><img src="https://raw.githubusercontent.com/apollographql/apollo-client-devtools/main/assets/apollo-wordmark.svg" height="100" alt="Apollo Logo"></a>
+  </div>
+  <h1 align="center">Apollo Client</h1>
+ 
+**The industry-leading GraphQL client for TypeScript, JavaScript, React, Vue, Angular, and more.** Apollo Client delivers powerful caching, intuitive APIs, and comprehensive developer tools to accelerate your app development.
 
-<p>
-	<a href="https://www.apollographql.com/"><img src="https://raw.githubusercontent.com/apollographql/apollo-client-devtools/main/assets/apollo-wordmark.svg" height="100" alt="Apollo Client"></a>
-</p>
-<h1>Apollo Client</h1>
+➡️ [**Get Started with Apollo Client →**](https://www.apollographql.com/docs/react/get-started?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme)
+
+  <div align="center">
 
 [![npm version](https://badge.fury.io/js/%40apollo%2Fclient.svg)](https://badge.fury.io/js/%40apollo%2Fclient) [![Build Status](https://circleci.com/gh/apollographql/apollo-client.svg?style=svg)](https://circleci.com/gh/apollographql/apollo-client) [![Join the community](https://img.shields.io/discourse/status?label=Join%20the%20community&server=https%3A%2F%2Fcommunity.apollographql.com)](https://community.apollographql.com)
 
-</div>
+  </div>
+</header>
 
----
+## ❓ Why Choose Apollo Client?
 
-**Announcement:**
-Join 1000+ engineers at GraphQL Summit 2025 by Apollo for talks, workshops, and office hours. Oct 6-8, 2025 in San Francisco. [Get your pass here ->](https://www.apollographql.com/graphql-summit-2025?utm_campaign=2025-03-04_graphql-summit-github-announcement&utm_medium=github&utm_source=apollo-server)
+ ✅ Zero-config caching - Intelligent caching out of the box<br>
+ ✅ Framework agnostic - Works with React, Vue, Angular, Svelte, and vanilla JavaScript<br>
+ ✅ TypeScript-first - Full type safety and IntelliSense support<br>
+ ✅ React 19 ready - Supports Suspense, RSC, Compiler, and more<br>
+ ✅ Production-tested - Powers countless apps worldwide that serve millions of end users<br>
+ 
+ ## 🚀 Quick Start
+ 
+```sh
+npm install @apollo/client graphql
+```
 
----
+## 💡 Resources
 
-Apollo Client is a fully-featured caching GraphQL client with integrations for React, Angular, and more. It allows you to easily build UI components that fetch data via GraphQL.
+| Resource | Description | Link |
+| ----- | ----- | ----- |
+| **Getting Started Guide** | Complete setup and first query | [Start Here →](https://www.apollographql.com/docs/react/get-started?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) |
+| **Full Documentation** | Comprehensive guides and examples | [Read Docs →](https://www.apollographql.com/docs/react?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) |
+| **API Reference** | Complete API documentation | [Browse API →](https://www.apollographql.com/docs/react/api/apollo-client?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) |
+| **VS Code Extension** | Enhanced development experience | [Install Extension →](https://marketplace.visualstudio.com/items?itemName=apollographql.vscode-apollo) |
+| **DevTools** | Debug your GraphQL apps | [Chrome](https://chrome.google.com/webstore/detail/apollo-client-devtools/jdkknkkbebbapilgoeccciglkfbmbnfm) \| [Firefox](https://addons.mozilla.org/en-US/firefox/addon/apollo-developer-tools/) |
+| **Free Course** | Learn GraphQL and Apollo Client | [Take Course →](https://odyssey.apollographql.com?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) |
 
-Apollo Client aims to comply with the [Working Draft of the GraphQL specification](https://spec.graphql.org/draft/).
+## 💬 Get Support
 
-| ☑️  Apollo Client User Survey |
-| :----- |
-| What do you like best about Apollo Client? What needs to be improved? Please tell us by taking a [one-minute survey](https://docs.google.com/forms/d/e/1FAIpQLSczNDXfJne3ZUOXjk9Ursm9JYvhTh1_nFTDfdq3XBAFWCzplQ/viewform?usp=pp_url&entry.1170701325=Apollo+Client&entry.204965213=Readme). Your responses will help us understand Apollo Client usage and allow us to serve you better. |
+**Need help?** We're here for you:
+
+* [**Community Forum**](https://community.apollographql.com?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) \- Q\&A and discussions  
+* [**GraphQL Discord**](https://discord.graphql.org) \- Real-time chat with the community
 
-## Documentation
+## 🧑‍🚀 About Apollo 
 
-All Apollo Client documentation, including React integration articles and helpful recipes, can be found at: <br/>
-[https://www.apollographql.com/docs/react/](https://www.apollographql.com/docs/react/)
+Deliver tomorrow's roadmap today with our comprehensive suite of API orchestration tools:
 
-The Apollo Client API reference can be found at: <br/>
-[https://www.apollographql.com/docs/react/api/apollo-client/](https://www.apollographql.com/docs/react/api/apollo-client/)
+* [**Apollo Client**](https://www.apollographql.com/docs/react?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) \- Type-safe apps with GraphQL-powered on-device caching ([React](https://www.apollographql.com/docs/react?utm_medium=github&utm_source=apollographql_apollo-client&utm_campaign=readme), [iOS](https://www.apollographql.com/docs/ios?utm_medium=github&utm_source=apollographql_apollo-client&utm_campaign=readme), [Kotlin](https://www.apollographql.com/docs/kotlin?utm_medium=github&utm_source=apollographql_apollo-client&utm_campaign=readme))  
+* [**Apollo Connectors**](https://www.apollographql.com/connectors?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) \- Compose all your GraphQL and REST APIs into one GraphQL endpoint  
+* [**Apollo MCP Server**](https://www.apollographql.com/ai?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) \- AI needs APIs. The fastest way to ship reliable AI experiences  
+* [**Apollo Router**](https://www.apollographql.com/docs/router?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) \- Scale your APIs seamlessly with GraphQL Federation, Security, Auth, and more  
+* [**GraphOS**](https://www.apollographql.com/graphos?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) \- Deploy, manage, govern, and explore your APIs ([start for free, no credit card needed](https://www.apollographql.com/pricing?utm_medium=github&utm_source=apollographql_apollo-client&utm_campaign=readme))
 
-Learn how to use Apollo Client with self-paced hands-on training on Odyssey, Apollo's official learning platform: <br/>
-[https://odyssey.apollographql.com/](https://odyssey.apollographql.com/)
+[**Explore the Complete Apollo Platform →**](https://www.apollographql.com/?utm_source=github&utm_medium=apollographql-_apollo-client&utm_campaign=readme)
 
-## Maintainers
+## 🛠️ Maintained by
 
 |Name|Username|
 |---|---|
 |Jeff Auriemma|[@bignimbus](https://github.com/bignimbus)|
 |Jerel Miller|[@jerelmiller](https://github.com/jerelmiller)|
 |Lenz Weber-Tronic|[@phryneas](https://github.com/phryneas)|
 
-## Who is Apollo?
+## 🗺️ Roadmap
+
+We regularly update our [public roadmap](https://github.com/apollographql/apollo-client/blob/main/ROADMAP.md) with the status of our work-in-progress and upcoming features.
+
+## 📣 Tell us what you think
+
+| ☑️  Apollo Client User Survey |
+| :----- |
+| What do you like best about Apollo Client? What needs to be improved? Please tell us by taking a [one-minute survey](https://docs.google.com/forms/d/e/1FAIpQLSczNDXfJne3ZUOXjk9Ursm9JYvhTh1_nFTDfdq3XBAFWCzplQ/viewform?usp=pp_url&entry.1170701325=Apollo+Client&entry.204965213=Readme). Your responses will help us understand Apollo Client usage and allow us to serve you better. |
+
+## 🗓️ Events
+
+Join these live events to meet other GraphQL users and learn more: 
+
+🎪 [**GraphQL Summit 2025**](https://summit.graphql.com?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme)  
+ Oct 6-8, 2025 • San Francisco  
+ *1000+ engineers, talks, workshops, and office hours*
+
+🌟 [**GraphQLConf 2025**](https://graphql.org/conf/2025)
+ Sep 8-10, 2025 • Amsterdam  
+ *Celebrating 10 Years of GraphQL*
+
+[**View All Events →**](https://www.apollographql.com/events?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme)
+
+## 🏆 Contributing
+
+Thank you for your interest in submitting a Pull Request to Apollo Client!  Read our [guidelines](https://github.com/apollographql/apollo-client/blob/main/CONTRIBUTING.md) first, and don't hesitate to get in touch.
+
+**New to open source?** Check out our [**Good First Issues**](https://github.com/apollographql/apollo-client/issues?q=is%3Aopen%20label%3A%22%3Abooks%3A%20good-first-issue%22) to get started.
 
-[Apollo](https://apollographql.com/) builds open-source tools and commercial services to make application development easier, better, and accessible to more people. We help you ship faster with:
+## 🤝 Code of Conduct
 
-- [GraphOS](https://www.apollographql.com/graphos) - The platform for building, managing, and scaling a supergraph: a unified network of your organization's microservices and their data sources—all composed into a single distributed API.
-- [Apollo Federation](https://www.apollographql.com/federation) – The industry-standard open architecture for building a distributed graph. Use Apollo’s gateway to compose a unified graph from multiple subgraphs, determine a query plan, and route requests across your services.
-- [Apollo Client](https://github.com/apollographql/apollo-client) – The most popular GraphQL client for the web. Apollo also builds and maintains [Apollo iOS](https://github.com/apollographql/apollo-ios) and [Apollo Kotlin](https://github.com/apollographql/apollo-kotlin).
-- [Apollo Server](https://github.com/apollographql/apollo-server) – A production-ready JavaScript GraphQL server that connects to any microservice, API, or database. Compatible with all popular JavaScript frameworks and deployable in serverless environments.
+Please read our [Code of Conduct](https://community.apollographql.com/faq). This applies to any space run by Apollo, including our GitHub repositories, the Apollo GraphOS Discord, the Apollo GraphQL Forum. The Code of Conduct reflects our commitment to making the Apollo Community a welcoming and safe space in which individuals can interact.
 
-## Learn how to build with Apollo
+## 🪪 License
 
-Check out the [Odyssey](https://odyssey.apollographql.com/) learning platform, the perfect place to start your GraphQL journey with videos and interactive code challenges. Join the [Apollo Community](https://community.apollographql.com/) to interact with and get technical help from the GraphQL community.
+Source code in this repository is available under the terms of the MIT License.  Read the full text [here](https://github.com/apollographql/apollo-client/blob/main/LICENSE).

ROADMAP.md

@@ -1,6 +1,6 @@
 # 🔮 Apollo Client Ecosystem Roadmap
 
-**Last updated: 2025-05-07**
+**Last updated: 2025-06-11**
 
 For up to date release notes, refer to the project's [Changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md).
 
@@ -17,13 +17,13 @@ For up to date release notes, refer to the project's [Changelog](https://github.
 
 ### Apollo Client
 
-#### 3.14.0 - June 5th, 2025
-_Release candidate - May 29th, 2025
+#### 3.14.0 - July 3rd, 2025
+_Release candidate - June 27th, 2025_
 
 - 4.0 compatibility release/deprecations
 
-#### [4.0.0](https://github.com/apollographql/apollo-client/milestone/31) - June 10th, 2025
-_Release candidate - May 29th 2025_
+#### [4.0.0](https://github.com/apollographql/apollo-client/milestone/31) - July 31st, 2025
+_Release candidate - June 18th 2025_
 
 ### GraphQL Testing Library
 

docs/source/api/link/persisted-queries.mdx

@@ -81,6 +81,10 @@ You can optionally create a configuration file in the root of your project to ov
 
 To automatically update the manifest for each new app release, include the `generate-persisted-query-manifest` command in your CI/CD pipeline.
 
+<Tip>
+If you see a difference in the `id` generated in the manifest and the one your client is sending at runtime, read the options available in the [`@apollo/generate-persisted-query-manifest`](https://www.npmjs.com/package/@apollo/generate-persisted-query-manifest) package to ensure the configuration matches your usage of Apollo Client.
+</Tip>
+
 ## 2. Publish manifests to a PQL
 
 <PublishPQMs />