The Isograph team is extremely proud to announce the release of Isograph v0.5.0! This release contains amazing new runtime features, massive DevEx wins, compiler performance improvements and important internal refactors. And the team is growing! The team is growing — since the last release, five new engineers have contributed to the project!

• Optimistic updates. You can now provide an optimistic response at that time, which will be written into the store for the duration of the network request.
• Writing external data into the Isograph store. We now provide a typed interface to write arbitrary data into the Isograph store. Useful when incrementally adopting Isograph, when you don't yet have a GraphQL endpoint set up, or when you have another source of data (e.g. server-sent of events or local storage.)
• DevEx wins in the VSCode extension. Selecting a field that doesn't yet exist? There's an autofix that will create the field for you! And so much more!
• Compiler performance wins. We no longer rewrite the entire __isograph folder on every change, leading to massive speedups in watch mode!

Let's talk about each of these, and more!

Optimistic updates​

We now support providing an optimistic response for most network requests! Oftentimes, when you make a network request (for example, when making a mutation to increment a post's like count), you already know what the result will be if the request succeeds. In cases like this, you can now provide an optimisticNetworkResponse. This response will be written into the store, and later dropped when the network request completes.

The best part about this — this is completely statically typed! Entrypoints contain so-called raw response types, which are types that correspond to what the network response would be. When you provide an optimisticNetworkResponse, you must provide something of that shape. So that means that if you change what you're fetching by adding or removing fields, then the raw response type changes, and what you provide must change!

In order to implement this, we had to rewrite the store from being a single object to being a stack of objects! Writing an optimistic response is as simple as adding an object to this stack, and reverting it is simply removing it from the stack. Neat! This work also sets us up for future support for "forking" the store (i.e. a store that supports multi-version concurrency control).

Thank you @PatrykWalach for this amazing work!

Writing external data​

We now provide a typed API for writing external data into the Isograph store! You may want to do this in at least three circumstances:

• you're incrementally adopting Isograph,
• you don't have a GraphQL backend, but want to enjoy the DevEx and performance wins of Isograph, or
• you have an external source of data (e.g. some server-sent events, local storage, etc.) that you want to work with an existing Isograph app.

Like with optimistic updates, these rely on the raw response type! You create an entrypoint and provide the equivalent of the network response, and that is written into the store, as if it came from the network.

Another win here is that writing data from an external source uses the same primitives as writing network data, so you get a bunch of awesome things for free! Just the needed components are re-rendered, the data can be garbage collected when its unused, etc.

Once again, amazing work by @PatrykWalach!

VSCode extension improvements​

And this version of Isograph included some amazing DevEx wins! In my (admittedly biased) opinion, I think Isograph can lay a claim to being the framework that provides the best DevEx! Check out this video, where we holistically describe the developer experience of using Isograph:

And now, we've released not only a VSCode extension, but also an Open VSIX extension, so you can get the benefits when using other editors, like VSCodium and Eclipse Theia. Thank you @sp6370 for setting this up!

But let's also call out some specific features that shipped in v0.5.0:

• errors are now surfaced in VSCode!
• autocomplete of fields now works!
• if you select a field that doesn't exist, you will get an autofix that creates a file containing a stub of the field for you! For example, if you selected Query.Header, and it didn't exist, and used the autofix labeled Create new @component field named `Query.Header` , then it would create a file containing:

import { iso } from '@iso';

export const Query__Header2 = iso(`
  field Query.Header @component {
  }
`)(({ data }) => {
  return null;
});

What a massive speedup!

And guess what? There are even more VSCode extension improvements coming soon!

Compiler performance wins​

Another win that we shipped was an absolutely massive performance win. We previously rewrote the entire __isograph directory on every save. Now, we keep track of the previous file state and make only the minimal changes to the file system required.

Testing locally, in the pet demo, updating the graphql schema by adding a new, unused field on pet demo went from 144ms to 53ms (in a debug build on a macbook pro m1), and updating the Query.HomeRoute iso literal by adding a new field went from 125ms to 72ms. These gains are likely going to be much larger in larger projects!

Thank you @lucasmachadorj for this amazing work!

Internal refactors​

We also did an absolutely monumental amount of internal refactoring, with three big goals:

• enable us to add additional features to the extension,
• improve the performance of the compiler, and
• set us up to support other network protocols (e.g. SQL, tRPC).

Since these aren't user-facing, I'll focus on just one of these improvements by @ch1ffa. We added support for returning references from memoized functions. This is a gamechanger. Our incremental compiler is written as a series of memoized pure functions which reuse their old values if no input has changed, and therefore their return value couldn't have changed. However, one limitation was that we were restricted to returning owned object, so if a particular value went through several memoized functions, it was repeatedly cloned. Now, we support returning references, and the compiler clones objects far less!

Other improvements​

• @Cobord added tests related to the garbage collection of MemoRefs.
• @corydeppen added docs about TanStack start and StrictMode.
• @TheRealGChen added docs related to troubleshooting.
• @tbezman fixed broken useClientSideDefer types.

There is a lot more! See the commit message for more details.

Conclusion​

Getting this release out has been a monumental effort, and this blog post didn't cover even cover everything! There's never been an easier time to try out Isograph!

So go on, give the quickstart a try! Join the discord! Star the repository!

Isograph is an opinionated, compiler-driven framework for building data-driven apps that are stable and performant out of the box. In Isograph, developers write components, along with the data they require, and a compiler stitches everything up for you. See also the quickstart!

The Isograph team is extremely proud to announce the release of Isograph v0.4! This release contains an absolutely monumental amount of features! The team is growing — since the last release, five new engineers have contributed to the project!

• There's a new VSCode extension, which provides syntax highlighting, auto format, hover info and go to definition.
• We introduced client pointers, which are functions from graph data to an ID. These allow the app developer to embed follow up queries in their isograph literals. They were the largest remaining missing primitive in Isograph.
• We introduced typesafe updaters, which provide an absolute top-notch developer experience for updating locally cached data.
• We introduced persisted queries. Instead of sending the entire query text, Isograph can send just a query ID, saving bandwidth and increasing security!

Let's talk about each of these, and more!

VSCode extension​

The new VSCode extension deserves an Isograph release of its own. It completely changes the experience of working with Isograph. With syntax highlighting, go to definition and hover information, it becomes much easier to create a mental model of your app and the flow of data within it. Before this extension, Isograph literals were magic strings. With the extension, Isograph literals come alive!

And that's just a start! We spent much of the last year refactoring the Isograph compiler (more on that later) and laying the groundwork for future extension features. So stay tuned. Follow up features, like find all references, surfacing errors, autocomplete, etc. are in the works!

Client pointers​

Yet another feature that deserves its own release! Client pointers are functions from some graph data, which return a (you guessed it) pointer to another object, and they were the largest remaining missing primitive in Isograph.

This might be best explained with an example. Consider a bestFriend pointer, which selects a list of friends as well as the viewer's closeness. The pointer iterates over this list of friends, and returns a link to the friend with the highest closeness.

Now, in another isograph literal, we can select that bestFriend field, and off of it, select name (and hundreds of other fields). Great!

Now, when this is used, it will result in two queries. First, a query for all of the friends, their closenesses, and their IDs, and later, a follow up request for the best friend's name. Neat!

This allows us to avoid downloading the name and hundreds of other fields for each friend, only to throw out most of that data. That's a waste of bandwidth and an unnecessary cost on your server.

Now, there are lots of additional features that we want to ship with client pointers, but it's extremely exciting to even get version one out!

Local updates​

And a third? We really should have cut some smaller releases in the mean time!

Isograph now allows you to tag certain selections as @updatable, meaning that that client field will be passed a startUpdate function, in which you can just modify that field. Just look at that developer experience! Just use mutate data. And not to mention, it's typesafe and performant. If you make multiple changes, they all get batched, and only components that actually read that modified field will be re-rendered!

An absolutely massive thanks to Patryk Wałach for working on client pointers and optimistic updates (and 50 million other features, besides.)

Persisted queries/trusted documents​

A fourth?! Isograph now supports persisted queries. Previously, Isograph would send the full query text with every network request. This is bad — both because it requires sending the full query text twice, which is bad for bandwidth, and because this required you to expose a GraphQL endpoint.

Instead, with persisted queries, Isograph allows you to register these queries at build time, and send only an ID. This not only cuts down on bandwidth usage, but also allows you to not expose a GraphQL endpoint, drastically improving security!

See this article for more info.

Lazy loaded normalization and reader ASTs​

The Isograph compiler generates many files that actually materialize the user experience you want. And one of those files is called the normalization AST. It's primarily used to write a network response into the Isograph store, and it's not necessary to kick off the network request.

And in this version of Isograph, you can annotate an entrypoint (which is like a query root) with @lazyLoad(normalization: true) and have that entrypoint's normalization AST not be included as part of the parent bundle! Instead, Isograph will start fetching the normalization AST when it kicks off the request for data. Neat!

And if you annotate the entrypoint with @lazyLoad(normalization: true, reader: true), it will also not include the reader AST, which is to say, it will also not include the JavaScript for rendering the result of the query.

Isograph's north star is to allow you to build the app you want with the least amount of data and JavaScript. If it's extraneous, it should not be part of the initial bundle! And this is another example of how we're pulling that off.

Special thanks to Iha Shin and Edwin Santos, two developers who worked on this feature!

Experimental SWC plugin​

Now, hitherto, Isograph has required a babel plugin. We know that isn't ideal for everyone!

So today, we're extremely excited to announce that we also shipped an experimental SWC plugin! It works with NextJS v15.0.0 to v15.0.2. We'll ship SWC plugins that work for more versions of NextJS soon.

A special thanks to Pablo Crovetto and Edmondo Porcu for working on this.

Incremental compiler​

Last, and by no means least, I'd like to point out that the language server has been made possible by a massive rewrite of the Isograph compiler. It went from a batch mode compiler to an incremental one, where intermediate results are automatically reused.

Whereas in a batch compiler, any change causes the compiler to re-execute everything, in an incremental compiler, a small change (such as an update to one file), results in a small amount of work being redone (that file is reparsed, etc.) And a language server — that's sort of like a compiler where very little changes! For example, if you're hovering on one field and then on another, we should be able to reuse pretty much all of the work!

Now, one could add caching manually (for example, by file.) But that's really tough to extend and maintain, and risks opening up bugs.

So, we turned to a solution where functions can simply be annotated with a #[memo] macro, and just like that, they're smartly cached. And we found that the developer experience was great!

And this is all powered by a homegrown framework that we're calling Pico (a smaller, simpler Salsa). This merits its own blog post, but for now, it is sufficient to point out that this was an absolutely monumental effort by Vadim Evseev (who also shipped persisted queries).

The work to make the compiler incremental is ongoing, it turns out that even with a good developer experience, it's a lot of work :).

Conclusion​

Getting this release out has been a monumental effort, and this blog post didn't cover even cover everything! There is a tree sitter grammar, open telemetry integration and so many cool internal features I'd love to go on about. And since v0.3, five new contributors have helped out, including Ben Patton and Julio Teixeira. Bolt Foundry is all-in on Isograph, and having a great time using it. And now that the language server is out, there's never been an easier time to try out Isograph!

So go on, give the quickstart a try! Join the discord! Star the repository!

Interested in trying Isograph out? Check out the quickstart, join the Discord and watch the presentation at GraphQL conf.

Big picture​

These releases improve the usability of Isograph for real-world projects. They include massive internal refactors that bring Isograph closer to a cross-platform world. And they include contributions from five new developers!

Detailed release notes​

In these two releases, you'll find:

Support for Relay-style connection spec pagination​

We've added a useConnectionSpecPagination hook that makes working with Relay-style connections a breeze. Check out the GitHub demo for an example of it in action.

Fetch policies​

APIs for fetching data, such as useLazyReference and useImperativeReference, now accept a fetch policy. Using a fetch policy, you can specify that you would like to unconditionally make a network request, to make it if there isn't enough data in the store to fulfill the entire query, or to not make the network request.

Support for refining to a concrete type and unions​

GraphQL unions and interfaces are now given special fields, asConcreteType fields, which are non-null if the union/interface has that concrete type. For example, you might select asUser on an object of type Node.

onComplete and onError callbacks​

APIs for fetching data, such as useLazyReference and useImperativeReference, also accept onComplete and onError callbacks. These give you the ability to execute a callback when a network request completes or errors out.

We lifted the requirement that IDs are globally unique​

Isograph no longer requires IDs to be globally unique. Instead, they only must be unique within a given typename.

link field​

Each object type has a magic link field, which acts as a pointer to that object. So, for example, in node(id: "4") { asUser { link } }, the link field would be { __typename: "User", __link: "4" }.

Compiler watch mode performance improvements​

Our compiler watch mode is now more efficient, and reuses more intermediate results. This is just a taste of things to come — expect massive efficiency gains in the next release 😈.

Massively improved docs​

Our docs have been overhauled. This task will never be done, but there are some serious improvements there.

A demo of using Isograph with Vite​

Isograph can be used with any build framework, but so far, all of our demos have used NextJS. Now, we have a Vite demo.

Other features​

• There are numerous additional validations, such as that there are no undefined or unused variables. Variables are also typechecked.
• There are improved component prop types
• We log when an environment is created
• Additional Isograph config options:
  • You can use the generated_file_header option to specify a comment that the Isograph compiler should include in generated files. This can be used to disable auto-formatting, linting, etc.
  • The module option controls whether the Babel transform, when encountering entrypoints, will generate require calls or import statements.
  • The include_file_extensions_in_import_statements option controls whether generated files refer to other files with or without file extensions.
  • The no_babel_transform option can be set to true if you don't have the babel transform set up.
• Our demos now showcase proper error handling.
• Isograph now has a peer dependency on React 18 or 19, and is not pinned to a specific version of React.

Bug fixes​

• The component cache had a bug that involved components defined on interfaces and items of different types with identical IDs. (Remember, IDs are no longer required to be globally unique.)
• We fixed a long-standing issue in which errors during SSR caused infinite suspense, instead of showing an error fallback.

Other internal improvements​

• We cut down on re-renders by having Isograph re-use parts of the old read out value. To my knowledge, this is done in a cutting edge way: by using the reader AST, and (though we have no benchmarks) is potentially more performant than any other solution.
• We did a substantial refactor that prepares Isograph to be able to generate SQL, OpenAPI, or any other type of query!
• We added fixture tests for added stability.

Contributors​

I want to thank the many contributors that helped make this release possible:

• Patryk Wałach
• Vadim Evseev
• Edmondo Porcu
• Lane Sawyer
• Edwin Santos
• Iha Shin
• Adrtivv
• Sami Syed

And I want to thank the following folks who provided extremely valuable feedback:

• Randall Bennett
• Dennis Kinuthia

The Isograph family is growing 😊

Conclusion​

Whew! If you made it this far, congratulations! But I promise you — subsequent releases will be even more filled with features!

So why not give it a try? Check out the quickstart, join the Discord and watch the presentation at GraphQL conf.

Runtime deep dive​

In the runtime deep dive, we discussed:

• what is a data driven app? How do changes to subcomponents affect other files? 0:00
• debugging an Isograph app using React DevTools 14:03
• entrypoints and generated queries 17:20
• client fields (and how Isograph reads the just data selected by a given client field) 20:18
• what happens when a network request is made? How does Isograph render the entire page? 29:14
• adding additional logic to GraphQL queries 34:19
• how do we use the Reader AST to generate the data for a given client field 39:19
• what about @component client fields? what is the component cache? 41:49
• how does TypeScript learn about the type of the data parameter passed to client fields? 49:30
• Loadable fields 51:13

Q&A​

• do we use the same store for the client component cache and the network response cache? What else might be stored in the network response cache? 1:02:17
• what does the roadmap look like? How generic will be Isograph in the long term? 1:08:39
• can we calculate client fields on the server? Benefits in terms of privacy, performance, capabilities, etc. 1:11:50
• how does one migrate from Redux to Isograph? Modifications to the store? 1:15:17
• thoughts on a plugin architecture? Yes! 1:17:56
• other ways to modify fragments 1:21:27
• what about benchmarks? 1:24:04

Compiler deep dive​

In the compiler deep dive, we discuss:

• Big picture overview 00:00
• The future direction for the compiler: salsa architecture 10:13
• Most important things that we do 19:08
• Parsing and processing the GraphQL schema (intro) 20:15
• Parsing the GraphQL schema 22:15
• Processing the parsed GraphQL schema 36:05
• Parsing iso literals 46:50
• Adding client field literals to the schema 51:10
• Validating the Isograph schema 53:12
• Generating the content of generated files 1:01:10
• Writing artifacts to disk 1:13:09

Q&A​

• How does watch mode work? 1:14:17
• What is the future of the compiler? 1:17:20

Words cannot express how excited the Isograph team is to announce the release of Isograph 0.2.0. This release is chock full of features, including:

• fully-featured @component client fields
• automatic typing
• compiler watch mode
• @loadable fields
• pagination
• network error handling
• fragment variables
• garbage collection
• fine grained re-rendering
• support for Windows
• finer control over re-exposed fields

Let's run through each of these in turn!

@component client fields​

As of 0.1.0, Isograph @component client fields had to be interpolated. That's awkward! In 0.2.0, they can be used like regular components!

export const BlogPostDisplay = iso(`
  field BlogPost.BlogPostDisplay @component {
    BlogPostHeader
  }
`)(blogPost => <blogPost.BlogPostHeader />)

Much better!

Automatic typing​

The first parameter to client fields is fully statically typed! Consider this BlogPostHeader:

import { iso } from '@iso';

export const BlogPostHeader = iso(`
  field BlogPost.BlogPostHeader @component { 
    title
    author
  }
`)((blogPost) => (
  <>
    <h1>{blogPost.title}</h1>
    <h2>{blogPost.author}</h2>
  </>
));

The blogPost parameter will have type

type BlogPost__BlogPostHeader__param = {
  title: string | null | undefined;
  author: string | null | undefined;
};

and VSCode (or your IDE of choice) will know about it!

That's because the iso function is overloaded at its definition. It's a function that, if passed a string starting with field BlogPost.BlogPostHeader, will pass an object of type BlogPost__BlogPostHeader__param to the resolver function.

This overload is generated by the Isograph compiler, so as soon as you save, it will get updated and VSCode will learn about it!

Compiler watch mode​

Speaking of "as soon as you save", the Isograph compiler now comes with a watch mode!

Now, if run with yarn iso --watch, the Isograph compiler will re-run on every save!

Loadable fields​

If there weren't so many other huge features in this release, this would be a marquee feature on its own!

Isograph now ships with loadable fields, which are like entrypoints (i.e. separate queries) embedded in other queries!

With loadable fields, you can:

• @defer data
• paginate
• load data in response to user actions, such as clicks

Loadable fields can also be used to asynchronously load JavaScript, so they also let you do Relay entrypoints in userland.

So, this means we can load only the JavaScript for objects that we actually encounter (e.g. load a VideoPlayer component if and only if we encounter a news feed item containing a video!)

There's so much more to be said about this topic, so for now, see the loadable fields documentation.

Pagination​

As mentioned above, loadable fields can power pagination! See the documentation.

The best part about this is that this is entirely doable in userland, so if you want behavior that's appropriate for your specific use case, you can implement that!

Network error handling​

You can now throw if a network request errored out.

Fragment variables​

All variables in Isograph are local now. No more confusing global variables :)

Garbage collection​

When fragment references are disposed (e.g. if a component that calls useLazyReference unmounts), the data they protect is liable to be garbage collected. This ensures that the memory usage of the Isograph store does not grow without bound over time!

Fine-grained re-rendering​

Now, Isograph @component client fields will re-render if and only if the data read out by the first parameter has actually changed.

There should be very few unnecessary re-renders!

(There are still some unnecessary re-renders due to loadable fields appearing different from render-to-render, but this there is an open issue, and fixing this is a great first issue!)

Support for Windows​

Isograph now builds on Windows! Woohoo!

Thank you to adrtivv for fixing this!

Finer control over re-exposed fields​

As of last year's GraphQL conf, re-exposed mutation fields were not configurable. But now they are!

Conclusion​

So many of these deserve their own blog post. But the point is simply this — many patterns that were previously impossible to do in Isograph are doable now! Isograph is suitable for more projects, and the developer experience is better than ever!

So go ahead, follow the quickstart and give it a try!

This video follows the work done in this video, in which I built an app that authenticates with the GitHub OAuth API. This video isn't necessary to watch to understand the DevEx video.

The repository can be found here.

And on top of that, we're releasing this brand new documentation website!

So go on! Take it for a spin. Everything you need to give Isograph a try is in the quickstart guide.

What is Isograph, and how does it provide such a great developer experience?​

Isograph is a framework for building React apps that are powered by GraphQL data. It has ambitions to be a framework for building apps powered by data.

With Isograph, developers define components and the data they need. Isograph takes care of the rest. On every save, the Isograph compiler will generate queries containing exactly the data needed by a given view (no more and no less), and wire up your app so that all of these components receive exactly the data they asked for (no more and no less).

Because the compiler is doing so much for you, Isograph is able to offer an amazing developer experience, free of boilerplate. Engineers can just reason locally about the file that they are modifying, and trust that the compiler will wire up their app correctly.

But the benefits of that go far beyond developer experience.

The trilemma​

As an engineering team grows, communication and coordination become more and more difficult. There comes a time when your app becomes unstable, because no one can reason about it end-to-end anymore, and innocuous changes start leading to downtime.

In response, teams can add process and manual review, sacrificing developer velocity.

Or, they can structure their apps so that the parts are independent, and each component fetches its own data. But this comes at a cost — many network requests for duplicate data and a chaotic loading experience. Or, query declarations can become append only. Either way, your app grows sluggish over time.

With Isograph, there's no tradeoff between velocity, stability and performance​

The Isograph compiler allows developers to reason about just the file they're modifying, generates optimized queries on every save, and never accidentally forgets to pass data to components. So, even as your team grows, Isograph allows you to maintain iteration speed, app stability and stellar performance.

Why now?​

We're releasing an alpha version of Isograph in recognition of a milestone: the most important components of the Isograph developer experience have landed. In fact, you can check out the quickstart guide and see for yourself! You can also check out this video in which Robert Balicki builds an Isograph app.

We encourage you to try Isograph, to join the Discord and to look at the open issues on GitHub. If you want to get involved in the early stages of a project that is pushing the boundaries of what is possible in web development, we would encourage you to get involved!

If you have questions or guidance about whether Isograph is appropriate for you, we're happy to answer them!

New features​

Quite a few features have shipped since the talk at GraphQL Conf! Let's talk through the biggest ones:

Client-defined @component fields can be used as React components​

The most-requested DevEx improvement has arrived! Client-defined @component fields can be used directly as React components!

For example, if we select a User.Avatar client-defined @component field in the User.UserProfile field, it can be rendered as <props.data.Avatar />!

export const UserProfile = iso`
  field User.UserProfile @component {
    full_name,
    Avatar,
  }
`(function UserProfile(props) {
  return (
    <>
      <h1>Hello {props.data.full_name}!</h1>
      <props.data.Avatar />
    </>
  );
});

Major thanks to Alec Aivazis for explaining how this is done in Houdini, and to Christoph Nakazawa for convincing me of the importance of this feature.

Users do not have to provide types​

Another absolutely groundbreaking feature that landed is that the type of the parameter to client field functions is fully typed, without the user having to do anything about it. Consider the UserProfile example shown previously. The props field is fully typed, and TypeScript knows about this!

How this works is that the Isograph compiler generates the iso function, along with its types, and TypeScript can infer that we're passing an object with shape { full_name: string, Avatar: Component }!

Major thanks to Terence Bezman for explaining how this can be done, and to Alec Aivazis for proving this out in Houdini. And a huge shoutout to Edmondo Porcu for hitting the ground running and shipping such an incredibly impactful feature!

Installable via yarn​

Everything can be installed with yarn! Add Isograph to an existing project with:

yarn add --dev @isograph/compiler
yarn add --dev @isograph/babel-plugin
yarn add @isograph/react

Watch mode​

The compiler can now be run in watch mode with yarn iso --watch, and even provides pretty error messages:

Starting to compile.
Error when compiling.

Error when validating schema, resolvers and fetch declarations.

In the resolver `Actor.UserLink`, the field `Actor.foo` is selected, but that field does not exist on `Actor`
/Users/rbalicki/code/isograph/demos/github-demo/src/isograph-components/UserLink.tsx

  field Actor.UserLink @component {
    login,
    foo,
    ^^^
  }

Compilation took 139ms.

Babel plugin​

In a huge DevEx win, Isograph now comes with a Babel plugin that replaces calls to iso(`entrypoint Type.Field`) with require calls to the generated entrypoint artifact. (SWC support coming soon!)

Now that this and the automatically-supplied types feature have landed, there is (currently) no reason for users to import any generated artifacts or types (except iso.)

Entrypoints​

Goodbye @fetchable client-defined fields, hello entrypoints! The Isograph mental model has been substantially simplified.

When the Isograph compiler encounters an Isograph literal of the form iso(`entrypoint Query.field`), it will generate a query text for that field. This entrypoint can be passed to useLazyReference, which will make the network request during the initial render of a component.

Configurable magic mutation fields​

Magic mutation fields are fields that are added to certain types. When read out, these fields are functions that trigger mutations. For example, you might configure a User.set_name field to call the Mutation.set_name mutation.

These are now configurable in schema extensions via the @exposeField directive. See the documentation.

A brand-new isograph.dev​

You're looking at it now!

Thanks​

Isograph isn't a one-person job! I want to thank Edmondo Porcu, Sami Syed and Marais Rossouw for contributing to Isograph, and Adrtivv for a surprise, last minute PR that didn't make it into this release! I want to thank Lenny Crespo Garcia for providing incredibly valuable feedback and recording videos with me. I want to thank Matt Mahoney, Jens Neuse, Predrag Gruevski, Randall Bennett, Reed Harmeyer, Gabriel Nordeborn, Benjie Gillam, Terence Bezman, Alec Aivazis, Zack Jackson, Kerry Imai, Dennis Cahillane, Nicholas Shook and John Maguire for providing valuable feedback.

I'm sure I'm forgetting others, so I apologize in advance!

Isograph would not be as far along or as polished without you.

Client-defined @component fields can be used as React components​

The most-requested DevEx improvement has arrived! Client-defined @component fields can be used directly as React components!

For example, if we select a User.Avatar client-defined @component field in the User.UserProfile field, it can be rendered as <props.data.Avatar />!

export const UserProfile = iso`
  field User.UserProfile @component {
    full_name,
    Avatar,
  }
`(function UserProfile(props) {
  return (
    <>
      <h1>Hello {props.data.full_name}!</h1>
      <props.data.Avatar />
    </>
  );
});

Major thanks to Alec Aivazis for explaining how this is done in Houdini, and to Christoph Nakazawa for convincing me of the importance of this feature.

Commit.

Users do not have to provide types​

Another absolutely groundbreaking feature! Users no longer have to provide any type parameters to the iso function. Instead, those types generated by the compiler, and thus come automatically to the developer.

Major thanks to Terence Bezman for explaining how this can be done, and to Alec Aivazis for proving this out in Houdini. And a huge shoutout to Edmondo Porcu for hitting it out of the park with the implementation of this feature!

Commit

Installable via yarn​

Everything can be installed with yarn! Add Isograph to an existing project with:

yarn add --dev @isograph/compiler
yarn add --dev @isograph/babel-plugin
yarn add @isograph/react

Watch mode​

The compiler can now be run in watch mode with yarn iso --watch, and even provides pretty error messages:

Starting to compile.
Error when compiling.

Error when validating schema, resolvers and fetch declarations.

In the resolver `Actor.UserLink`, the field `Actor.foo` is selected, but that field does not exist on `Actor`
/Users/rbalicki/code/isograph/demos/github-demo/src/isograph-components/UserLink.tsx

  field Actor.UserLink @component {
    login,
    foo,
    ^^^
  }

Compilation took 139ms.

A brand-new isograph.dev​

You're looking at it now!

Babel plugin​

In another DevEx win, Isograph now comes with a Babel plugin that replaces calls to iso(`entrypoint Type.Field`) with require calls to the generated entrypoint artifact.

Entrypoints​

Goodbye @fetchable client-defined fields, hello entrypoints! The Isograph mental model has been substantially simplified.

When the Isograph compiler encounters an Isograph literal of the form iso(`entrypoint Query.field`), it will generate a query text for that field. This entrypoint can be passed to useLazyReference, which will make the network request during the initial render of a component.

Configurable magic mutation fields​

Magic mutation fields are fields that are added to certain types. When read out, these fields are functions that trigger mutations. For example, you might configure a User.set_name field to call the Mutation.set_name mutation.

These are now configurable in schema extensions via the @exposeField directive. See the documentation.

Commits: 1 and 2.

Integer literals​

Isograph now supports integer literals as parameters, in addition to variables.

Commit

Do not require a specific const export name​

The name of the export is now arbitrary, as it is understood by the compiler.

Commit

iso and isoFetch are combined​

In a win for DevEx and simplicity, isoFetch has been replaced by iso(`entrypoint ...`). Major thanks to Edmondo Porcu for working on this feature.

Commit

Full support for the GraphQL schema syntax​

The rest of GraphQL schema syntax is now supported. (Please let us know if we missed anything!)

Magic mutation fields on interface types​

A magic mutation field defined on an interface type (e.g. addLabelToLabelable, where a Labelable is an interface) will now show up on concrete types that implement that interface (e.g. repository { addLabelToLabelable } is valid).

Commit

Beautiful error messages​

The compiler now prints pretty error messages.

CI​

There is now a GitHub CI pipeline that:

• builds the compiler and demos
• runs unit tests
• ensures no changes occur after yarn format
• publishes the website
• publishes new versions of the site

Isograph environment is held in context​

The Isograph environment is held in context now, and there are associated changes to the API.

Commit Commit Commit

In this presentation, Robert Balicki covers:

Introduction and motivation​

• The many steps that one goes through when one extracts a child component
• Data masking, and why it is important
• The fundamental tension at the heart of GraphQL: it is a language for querying servers being used to provide isolation to front-end components
• The big idea: every fragment is associated with exactly one function

Isograph​

• The developer experience that Isograph aims to provide
• The other big idea: resolvers are GraphQL's missing primitive
• How in Isograph, everything is a resolver
• How in Isograph, even components can be resolvers
• How entrypoints work in Isograph

Why resolvers are the unit of abstraction​

• If we achieve data masking, we're already using resolvers
• Deferring data and code together is natural
• Resolver components let us reason about the on-screen-ness of data
• Imperatively loaded resolvers are entrypoints
• Server executed resolvers are regular ol' GraphQL resolvers
• Conditionally loaded resolvers are @match and Relay 3D
• Resolvers can lead to better DevTools and application-creation tools

A demonstration of Isograph: Robert's Pet List 3000™​

The roadmap​

Q&A​

• Is it worth writing your own Isograph language, instead of reusing GraphQL?
• What is the migration path from Relay to Isograph? Can it be automated?
• How does Isograph handle client resolver and server field name collisions?
• Is Isograph a bundler?
• How tied is Isograph to React, GraphQL and JavaScript?

I hope you check it out!

• magic mutation fields (though not called such in the article),
• deferred resolvers,
• entrypoints, and
• injected analytics code.

It also makes the case that Isograph will be well-suited for apps that prioritize correctness, because:

• type of every field is very informative (e.g. the type of a field might indicate whether the field was unfetched, errored, null or present), and
• precise control over how to handle each state (e.g. to suspend when reading the resolver if the field is unfetched).

Thank you!