Skip to main content

Frontend GraphQL Layer

This page explains how the frontend talks to the GraphQL API: operation docs in apps/portal/src/gql/, generated hooks in apps/portal/src/gql/hooks.ts, and Apollo’s InMemoryCache.

How it works

Here’s the pipeline I use when I add or change frontend GraphQL operations.

1) Operation documents live next to the code

Frontend GraphQL operation docs live under:
For example, apps/portal/src/gql/queries/fetchMe.gql.ts exports a typed query document via gql.

2) Codegen generates the React hooks

The generated hooks file is always:
It’s generated from the schema (/shared/template.schema.graphql) plus the operation docs via:

3) Apollo caching keeps server-state reads consistent

In apps/portal/src/main.tsx, the Apollo client is created with:
That InMemoryCache is the reason components can rely on generated hooks without rebuilding “server-state” in Redux.
📖 See also: GraphQL for the backend/resolver + schema side of the same workflow.

Extending this system

When you add a new operation, use this recipe so codegen and generated hooks stay in sync.
  1. Add (or update) an operation doc under apps/portal/src/gql/queries/ or apps/portal/src/gql/mutations/.
Example: add apps/portal/src/gql/queries/fetchMyWidget.gql.ts:
  1. Regenerate hooks:
  1. Use the generated hook in your component:
  1. Verify:

What not to do

These boundaries keep the frontend/GraphQL contract predictable. ❌ Never manually edit apps/portal/src/gql/hooks.ts. ❌ Never duplicate server-state into Redux when Apollo cache already drives the hook results. ❌ Never add backend-only SDK usage (Stripe, Redis, etc.) in React; the frontend talks via GraphQL.

File conventions

This section keeps operation docs and generated hooks predictable. Prefer:
  • *.gql.ts for operation documents (example: fetchMe.gql.ts)
  • If you see it used, follow the existing repo naming style for *.gq.ts (example: revokeMembers.gq.ts)

What’s next?

If you’re about to add a new screen that consumes these hooks, follow the routing and state docs next.