Isograph and the Missing Abstraction

When you remove a field from a component in a typical GraphQL app, you have to trace where that data flows to figure out if it’s safe to remove from the query. If you get it wrong, you break the app. If you’re too cautious, queries accumulate dead fields.

Isograph fixes this: components declare what they need, the compiler generates the queries, changes propagate automatically.

How It Works

Define a component as a client field:

export const Avatar = iso(`
  User.Avatar @component {
    avatar_url
  }
`)(function AvatarComponent({ data }) {
  return <CircleImage image={data.avatar_url} />;
});

Use it in another component:

export const UserProfile = iso(`
  User.UserProfile @component {
    name
    Avatar
  }
`)(function UserProfileComponent({ data }) {
  return (
    <div>
      <h1>{data.name}</h1>
      <data.Avatar />
    </div>
  );
});

Select Avatar, render <data.Avatar />. No imports. No props. No fragment spreading.

The compiler walks the tree of client fields and generates a query that fetches exactly what’s needed.

What This Eliminates

Manual fragment coordination. Change Avatar’s requirements? The query regenerates. No tracing through the codebase to see what breaks.

Prop drilling. UserProfile doesn’t know what Avatar needs. It just renders it. Avatar gets its data from the reader AST at runtime.

Dead fields in queries. Remove a field from Avatar? The compiler removes it from the query. No manual cleanup.

Data Masking

The reader AST reads out exactly the fields a component selected. Avatar sees avatar_url. Even if the query fetched 50 other fields, Avatar can’t access them.

This gives you two things:

Stability. Changes to other components’ selections don’t affect Avatar at runtime. The query might change, but what Avatar receives doesn’t.

Performance. Avatar subscribes only to avatar_url. When unrelated fields change, Avatar doesn’t re-render.

LSP

I contributed the LSP and VSCode extension in mid-2024. Syntax highlighting, go-to-definition, hover, formatting.

---

Isograph is Robert Balicki’s work. Relay at Meta for years, then this.

isograph.dev | github.com/isographlabs/isograph