From lisa-expo
This skill should be used when writing or modifying GraphQL operations, hooks, or mutations using Apollo Client 3.10. It enforces best practices for optimistic responses, cache updates, and TypeScript type generation. Use this skill when creating new queries/mutations, reviewing Apollo code, or troubleshooting cache issues.
npx claudepluginhub codyswanngt/lisa --plugin lisa-expoThis skill uses the workspace's default tool permissions.
This skill provides best practices for Apollo Client 3.10 in this codebase, ensuring consistent patterns for GraphQL operations, optimistic UI updates, cache management, and TypeScript type safety.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
This skill provides best practices for Apollo Client 3.10 in this codebase, ensuring consistent patterns for GraphQL operations, optimistic UI updates, cache management, and TypeScript type safety.
After modifying any operations.graphql file, run the appropriate generator:
bun run generate:types:dev # Development environment
bun run generate:types:staging # Staging environment
bun run generate:types:production # Production environment
Note: Replace
bunwith your project's package manager (npm,yarn,pnpm) as needed.
All GraphQL types, hooks, and documents must come from generated types:
import {
useGetPlayerQuery,
useUpdatePlayerMutation,
GetPlayerQuery,
PlayerFragment,
ListPlayersDocument,
} from "@/generated/graphql";
Import all GraphQL-related types from @/generated/graphql. Never define manual TypeScript types for GraphQL entities.
// CORRECT
import { PlayerFragment, useUpdatePlayerMutation } from "@/generated/graphql";
// INCORRECT - Never do this
type Player = { id: string; name: string };
The generated/graphql.ts file is auto-generated by codegen. To change types:
operations.graphql file in the feature directorybun run generate:types:devAfter modifying any operations.graphql file, immediately run the generator before committing. Verify changes compile with bun run typecheck.
Every mutation must include an optimisticResponse for instant UI feedback:
const [updatePlayer] = useUpdatePlayerMutation({
optimisticResponse: variables => ({
__typename: "Mutation",
updatePlayer: {
__typename: "Player",
id: variables.id,
name: variables.input.name,
updatedAt: new Date().toISOString(),
},
}),
});
Key requirements:
__typename for every object in the responseid for cache normalizationcrypto.randomUUID())Every mutation must handle cache updates using one of these strategies:
Automatic Updates - When mutation returns the full entity with id and __typename, Apollo updates automatically. No extra code needed.
cache.modify - For adding/removing items from lists:
const [addPlayer] = useAddPlayerMutation({
optimisticResponse: {
/* ... */
},
update(cache, { data }) {
cache.modify({
fields: {
players(existingPlayers = [], { readField }) {
const newRef = cache.writeFragment({
data: data.addPlayer,
fragment: PlayerFragmentDoc,
});
return [...existingPlayers, newRef];
},
},
});
},
});
refetchQueries - Fallback for complex scenarios:
const [complexMutation] = useComplexMutation({
refetchQueries: ["ListPlayers"],
awaitRefetchQueries: true,
});
Define fragments before queries/mutations that use them:
# 1. Fragments first
fragment PlayerFragment on Player {
id
knownName
firstName
lastName
team {
id
name
}
}
# 2. Queries second
query GetPlayer($id: ID!) {
player(id: $id) {
...PlayerFragment
}
}
# 3. Mutations last
mutation UpdatePlayer($id: ID!, $input: UpdatePlayerInput!) {
updatePlayer(id: $id, input: $input) {
...PlayerFragment
}
}
Mutations must return all fields needed for cache updates:
mutation AddPlayerToKanban($input: AddPlayerToKanbanInput!) {
addPlayerToKanban(input: $input) {
id # Required for cache normalization
position
notes
kanbanPhaseId
kanbanPhase {
# Include related objects
id
name
}
createdAt
updatedAt
}
}
// Frequently changing data - balance speed and freshness
fetchPolicy: "cache-and-network";
// Stable reference data - prioritize cache
fetchPolicy: "cache-first";
// Always-fresh data - skip cache
fetchPolicy: "network-only";
const { data } = useGetPlayerQuery({
variables: { id: playerId! },
skip: !playerId,
});
Use onError callback instead of try/catch with console.log:
const [mutation] = useMutation(MUTATION, {
onError: error => {
setErrorState("Failed to update. Please try again.");
},
});
Reference references/mutation-patterns.md for comprehensive examples of the complete mutation pattern including optimistic responses, cache updates, and error handling.
When writing or reviewing Apollo code, verify:
@/generated/graphqloptimisticResponse__typename included in all optimistic response objectsid included in all optimistic response objectsfetchPolicyskip when variables may be undefinedonError callback