apollo-client
Guide for building React applications with Apollo Client 4.x. Use this skill when: (1) setting up Apollo Client in a React project, (2) writing GraphQL queries or mutations with hooks, (3) configuring caching or cache policies, (4) managing local state with reactive variables, (5) troubleshooting Apollo Client errors or performance issues.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 12
- Forks
- 5
01 前言 Front Matter
- name
- apollo-client
- license
- MIT
- metadata
- { "author": "apollographql", "version": "1.0.0" }
- description
- Guide for building React applications with Apollo Client 4.x. Use this skill when: (1) setting up Apollo Client in a React project, (2) writing GraphQL queries or mutations with hooks, (3) configuring caching or cache policies, (4) managing local state with reactive variables, (5) troubleshooting Apollo Client errors or performance issues.
- allowed-tools
- Bash(npm:*) Bash(npx:*) Bash(node:*) Read Write Edit Glob Grep
- compatibility
- React 18+, React 19 (Suspense/RSC). Works with Next.js, Vite, CRA, and other React frameworks.
02 资源文件 14
- 参考文档agents/openai.yaml162 B
- 参考文档references/caching.md10.6 KB
- 参考文档references/error-handling.md10.8 KB
- 参考文档references/fragments.md22.1 KB
- 参考文档references/integration-client.md8.7 KB
- 参考文档references/integration-nextjs.md8.5 KB
- 参考文档references/integration-react-router.md7.0 KB
- 参考文档references/integration-tanstack-start.md10.9 KB
- 参考文档references/mutations.md11.8 KB
- 参考文档references/queries.md10.0 KB
- 参考文档references/state-management.md10.3 KB
- 参考文档references/suspense-hooks.md22.0 KB
- 参考文档references/troubleshooting.md10.5 KB
- 参考文档references/typescript-codegen.md4.0 KB
03 SKILL.md 正文
Apollo Client 4.x Guide
Apollo Client is a comprehensive state management library for JavaScript that enables you to manage both local and remote data with GraphQL. Version 4.x brings improved caching, better TypeScript support, and React 19 compatibility.
Integration Guides
Choose the integration guide that matches your application setup:
- Client-Side Apps - For client-side React applications without SSR (Vite, Create React App, etc.)
- Next.js App Router - For Next.js applications using the App Router with React Server Components
- React Router Framework Mode - For React Router 7 applications with streaming SSR
- TanStack Start - For TanStack Start applications with modern routing
Each guide includes installation steps, configuration, and framework-specific patterns optimized for that environment.
Quick Reference
Basic Query
import { gql } from "@apollo/client";
import { useQuery } from "@apollo/client/react";
const GET_USER = gql`
query GetUser($id: ID!) {
user(id: $id) {
id
name
}
}
`;
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>;
}
Basic Mutation
import { gql } from "@apollo/client";
import { useMutation } from "@apollo/client/react";
const CREATE_USER = gql`
mutation CreateUser($input: CreateUserInput!) {
createUser(input: $input) {
id
name
}
}
`;
function CreateUserForm() {
const [createUser, { loading, error }] = useMutation(CREATE_USER);
const handleSubmit = async (name: string) => {
await createUser({ variables: { input: { name } } });
};
return <button onClick={() => handleSubmit("John")}>Create User</button>;
}
Suspense Query
import { Suspense } from "react";
import { useSuspenseQuery } from "@apollo/client/react";
function UserProfile({ userId }: { userId: string }) {
const { data } = useSuspenseQuery(GET_USER, {
variables: { id: userId },
});
return <div>{data.user.name}</div>;
}
function App() {
return (
<Suspense fallback={<p>Loading user...</p>}>
<UserProfile userId="1" />
</Suspense>
);
}
Reference Files
Detailed documentation for specific topics:
- TypeScript Code Generation - GraphQL Code Generator setup for type-safe operations
- Queries - useQuery, useLazyQuery, polling, refetching
- Suspense Hooks - useSuspenseQuery, useBackgroundQuery, useReadQuery, useLoadableQuery
- Mutations - useMutation, optimistic UI, cache updates
- Fragments - Fragment colocation, useFragment, useSuspenseFragment, data masking
- Caching - InMemoryCache, typePolicies, cache manipulation
- State Management - Reactive variables, local state
- Error Handling - Error policies, error links, retries
- Troubleshooting - Common issues and solutions
Key Rules
Query Best Practices
- Each page should generally only have one query, composed from colocated fragments. Use
useFragmentoruseSuspenseFragmentin all non-page-components. Use@deferto allow slow fields below the fold to stream in later and avoid blocking the page load. - Fragments are for colocation, not reuse. Each fragment should describe exactly the data needs of a specific component, not be shared across components for common fields. See Fragments reference for details on fragment colocation and data masking.
- Always handle
loadinganderrorstates in UI when using non-suspenseful hooks (useQuery,useLazyQuery). When using Suspense hooks (useSuspenseQuery,useBackgroundQuery), React handles this through<Suspense>boundaries and error boundaries. - Use
fetchPolicyto control cache behavior per query - Use the TypeScript type server to look up documentation for functions and options (Apollo Client has extensive docblocks)
Mutation Best Practices
- If the schema permits, mutation return values should return everything necessary to update the cache. Neither manual updates nor refetching should be necessary.
- If the mutation response is insufficient, carefully weigh manual cache manipulation vs refetching. Manual updates risk missing server logic. Consider optimistic updates with a granular refetch if needed.
- Handle errors gracefully in the UI
- Use
refetchQueriessparingly (prefer letting the cache update automatically)
Caching Best Practices
- Configure
keyFieldsfor types withoutidfield - Disable normalization by setting
keyFields: falsefor types that don't include an identifier and are meant to group related fields under the parent - Use
typePoliciesfor pagination and computed fields - Understand cache normalization to debug issues
- Enable data masking for all new applications - it prevents components from accessing fragment data they don't own, enforcing proper data boundaries and preventing over-rendering
Performance
- Avoid over-fetching with proper field selection
- Configure appropriate
fetchPolicyper use case - Use
@deferfor incremental delivery of deferred query parts, and@streamfor streaming list fields (@streamavailable in Apollo Client 4.1+) - Prefer Suspense hooks (
useSuspenseQuery,useBackgroundQuery) in modern applications for better loading state handling and code simplicity
Ground Rules
- ALWAYS use Apollo Client 4.x patterns (not v3 or earlier)
- ALWAYS wrap your app with
ApolloProvider - ALWAYS handle loading and error states when using non-suspenseful hooks
- PREFER Suspense hooks (
useSuspenseQuery,useBackgroundQuery) in modern applications for better DX - NEVER store Apollo Client in React state (use module-level or context)
- PREFER
cache-firstfor read-heavy data,network-onlyfor real-time data - USE TypeScript for better type safety with GraphQL
- IMPLEMENT proper cache updates instead of refetching entire queries
- ADVISE the human steering you to look into Apollo DevTools when collaboratively debugging Apollo Client issues
04 同仓库更多 Skills
zarr-python
Stores and queries chunked N-D scientific arrays with Zarr-Python 3, including codecs, sharding, S3/GCS storage, and NumPy/Dask/Xarray integration. Use for array layout, bounded I/O, format migration, or scientific metadata preservation.
yeet
Publish local changes to GitHub by confirming scope, committing intentionally, pushing the branch, and opening a draft PR through the GitHub app from this plugin, with `gh` used only as a fallback where connector coverage is insufficient.
xarray
N-dimensional labeled arrays and datasets in Python. Built on top of NumPy and Dask. It introduces labels in the form of dimensions, coordinates, and attributes on top of raw NumPy-like arrays, making data analysis in physical sciences more intuitive and less error-prone. Use for working with multi-dimensional scientific data, NetCDF/GRIB/Zarr files, climate/weather/oceanographic datasets, remote sensing, geospatial imaging, large out-of-memory datasets with Dask, and labeled array operations.
writing-mstest-tests
Use when asked to fix, rewrite, update, improve, modernize, show corrected code for, or explain existing MSTest tests or MSTest-specific configuration. Use for "review" when corrected code or edits are wanted, even for one pasted assertion or passing tests with bad failure output. Covers expected/actual labels; generic Boolean, collection, string, numeric, null, identity, exception, hard-cast, and object[] checks; TestContext/lifecycle; timeout/cancellation; OS/CI conditions, retry, cleanup, parallelization, MSTest.Sdk project setup, and MSTESTxxxx. Honor the installed MSTest version. DO NOT USE to design new test cases (code-testing), perform report-only audits, create project files rather than explain MSTest setup, run tests, migrate frameworks, or handle non-MSTest/non-.NET code.
wgs-prs
End-to-end WGS to polygenic risk score pipeline. Takes paired-end FASTQ files (or a pre-existing VCF) through nf-core/sarek for variant calling, applies VCF QC (normalisation, hard filtering, Ti/Tv and Het/Hom checks), then computes polygenic risk scores via the PGS Catalog. Fills the FASTQ to VCF gap upstream of the gwas-prs skill.
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.