One valuable feature of Apollo Client is 

 fields.  These fields are redacted from an operation that is sent to the server by an application, and then computed and added to the server response to generate the final result.  The 

 clearly explain how to leverage this feature for local state management, but it's less clear on how to derive 

 local-only fields solely from other fields on the operation result.

Suppose we have an operation that queries for the current user.

const USER_QUERY = gql`
  query User {
    user {
      id
      firstName
      lastName
      department {
        id
        name
      }
    }
  }
`;

We use the result of this operation in some 

 component to render a display name in the format of 

As time goes on, we find ourselves using this same 

 format in numerous places throughout our application, duplicating the same logic each time.

We consider how best to reuse this formatted name across our application.  Our first thought might be a server-side resolver, but this isn't always feasible.  We might want to make use of client-side data - local time, for example - or maybe our calculation will use fields from a variety of subgraphs that are difficult to federate between.  Our next thought is a React component, but this won't work very well either.  We want a consistent 

 for our displayName, but usage or styling might vary considerably depending on context.  What about a hook, then? Maybe a 

 hook that encapsulates the query and display logic?  Better, but inelegant: we'll probably find ourselves invoking both the 

 hook in the same components, over and over.  What we'd really like is not logic 

 from the query result, but rather logic 

The first requirement for a local-only field is a corresponding field policy with a 

 function in our cache. (Technically, a field policy could be omitted in favor of reading to and writing from the cache, but we'll save that for another post.)

const cache = new InMemoryCache({
  typePolicies: {
    User: {
      fields: {
        displayName: {
          read(_) {
            return null;  // We'll implement this soon
          }
        }
      }
    }
  }
});

 function is the existing field value, which will be undefined for local-only fields since by definition they do not yet exist.

The other requirement for a local-only field is to add it to the operation with the 

 directive.  This directs Apollo Client to strip the field from the server request and then restore it to the result, with the value computed by the 

const USER_QUERY = gql`
  query User {
    user {
      id
      firstName
      lastName
      displayName @client
      department {
        id
        name
      }
    }
  }
`;

 hook, but of course, it always returns null right now.  Our desired format requires three fields from the server response: the user 

, a helper provided by the second "options" argument of the 

 function.  This helper will provide the requested value (if it exists) from the parent object of the field by default, or from another object if it's included as the second argument.  This helper will also resolve normalized references, allowing us to conveniently nest 

 invocations.  Note that we can't really force the operation to include the fields on which the local-only field is dependent, and thus 

 always has the potential to return a value of undefined (even if it's a non-nullable field).

Now, it's trivial to use this formatted display name anywhere in our application - it's just another field on our query data!

const BlogPost = () => {
  const { data } = useQuery(USER_QUERY);

  return (
    <div>
      <BlogTitle />
      <p>Written by {data.displayName}</p>
      <BlogContent />
    </div>
  );
}

Bonus: Local-only fields with GraphQL Code Generation

It's trivial to include local-only fields if you're using 

, too.). All you need to do is extend the type to which you're adding the local-only field in your client-side schema file.

const typeDefs = gql`
  extend type User {
    # Don't forget to return a default value
    # in the event a field dependency is undefined
    # if the local-only field is non-nullable
    displayName: String!
  }
`;

Computing Apollo Client local-only fields purely from other operation fields.

Computed local-only fields in Apollo Client

At EF Go Ahead Tours Engineering, we use a tool called 

 often. Since we use TypeScript and GraphQL, it saves us a lot of time since we can create TypeScript types from our GraphQL schema. Let's set up a basic GraphQL schema to show how it works:

const typeDefs = gql`
    type Query {
        cart(id: ID!): Cart
        carts: [Cart!]
    }
    
    type Cart {
        items: [Product!]
        grandTotal: Int!
    }

    type Product {
        sku: String!
        price: Int!
    }
`

Pretty simple, we have a two queries and a basic eCommerce model. This sets up our contract with our API. Let's generate our application types. We can do this by installing the needed packages and the plugins for typescript:

npm i @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-resolvers

All of these packages gives us the functionality to generate both types and a typed resolver, with a pretty minimal configuration, as specified in a YAML file. Let's set one up:

schema: "./src/typeDefs.ts"
generates:
  src/generated/types.ts
    plugins:
      - typescript
      - typescript-resolvers

This is an incredibly barebones configuration, only meant to show the TypeScript type generation, more details about configuration can be found 

All that's left is to run our generator and see what types we are able to use!

  "scripts": {
    "generate": "graphql-codegen"
  }  

at which point the command can be run with 

After this, we can see what types are generated in the 

 file! Having this tool is incredibly helpful for both back end and front end work, since our types can be generated from our GraphQL schema, which introduces coupling of the schema definition and the types that we can use within our apps. This makes GraphQL schemas 

, which means that the data and the types of that data is now available for us to use in TypeScript!

graphql-codegen works for both server and client side. Let's implement a basic resolver using our newly generated types:

import { Resolvers } from "./src/generated/types.ts"

export const resolvers: Resolvers => {
    Query: {
        cart(parent, args, context) {
            console.log(args)
            return null
        },
        carts(parent, args, context) {
            console.log(args)
            return []
        }
    }
}

 type from our generated schema, which gives us typechecking for all of our resolvers! This also includes typechecking for our parent type, our field arguments, and our context. Super easy! The package also splits out each individual resolver so one could do:

// ./src/cartResolvers.ts
import { CartResolvers } from "./src/generated/types.ts"

export const cartResolvers: CartResolvers => {
    cart(parent, args, context) {
            console.log(args)
            return null
        },
        carts(parent, args, context) {
            console.log(args)
            return []
        }
}

export const resolvers: Resolvers => {
    Query: {
        ...cartResolvers
    }
}

This makes creating typechecked resolvers with IntelliSense in VS Code very easy and guarantees static types from your schema. How can this tool also help us with the front end? After all, one of the benefits of using GraphQL is that we can query only the data we need. We can do this with a very minimal configuration update in our client side app, copying it from our GraphQL server configuration:

schema: "./src/typeDefs.ts"
generates:
  src/generated/types.ts
    plugins:
      - typescript
      - typescript-resolvers
+     - typescript-react-apollo
+     - typescript-operations
+     - fragment-matcher
+ documents: "src/graphql/**.{ts, tsx, graphql}"

This configuration will scrape all of our graphql, ts, and tsx files in our 

 file. We'll also need to install the extra plugins that this config requires:

npm i @graphql-codegen/typescript-operations @graphql-codegen/fragment-matcher @graphql-codegen/typescript-react-apollo

At EF Go Ahead Tours we use the first one quite a bit in most typical front-end applications, since we leverage a ton of GraphQL. A typical React component that fetches a cart by ID from our GraphQL server with a search parameter would look like:

// src/graphql/cart.graphql

query FindCart($id: ID!) {
    cart(id: $id) {
        items
        grandTotal
    }
}
        
// src/checkout/cart.tsx
import React from "react";
import { useFindCart } from "./src/generated/typedefs.ts";
import { Item } from "./Item";
import { Spinner } from "../shared/Spinner";

export const Cart: React.FC = () => {
    const cartId = new URLSearchParams(window.location.search).get("cartId");
    const { data, loading } = useFindCart({
        variables: {
            id: cartId ?? ""
        }
    });

   if (loading) {
        return <Spinner />
    }

    return (
        <>
            <h2>{data.grandTotal}</h2>
            {data?.items.map((item) => <Item item={item} />
        </>
    );
}

Where all of our queries and mutations, along with their variables are typechecked. This makes it very easy to build services alongside clients that consume those services, while maintaining type checking between the both of them. Graphql-codegen is an invaluable tool for us developers here at EF Go Ahead Tours. Without it we would never have been able to build services and front end applications with the speed of sharing types between client and server without the manual work of migrating types and the developer experience that using graphql-codegen affords us.

Untitled

GraphQL Codegen: What is it?

I presented this topic at Boston Code Camp

. At that time we were beginning our journey of using GraphQL at EF Go Ahead Tours. In this post I'll go over what our early steps looked like and what the outcome was for our teams.

Many industries depend on legacy systems that businesses are unwilling or unable to invest in improving or replacing. The risk and cost of replacing those systems can be prohibitive, especially in the short term. Yet, the existence of these systems pose a risk to growth by reducing engineering velocity and stifling innovation.

There are many reasons your legacy systems may no longer be sustainable:

The impact of overwhelming legacy and the tech debt often associated with the systems can loom large over your team. It can have a negative impact on team culture as people feel they're working on outdated systems that lack an end goal or an opportunity to innovate. This lack of innovation can lead to the following:

In a risk reward assessment you'll often find that replacing these systems all at once incurs too much cost or poses too much risk. As a result, you'll need a plan to retire your legacy over time. The goals, methods, and processes of doing so is worth an separate blog post but at EF Go Ahead Tours we were looking to do the following:

And of course, we are looking to create new opportunities that drive value for customers.

Contracts between systems are important. These contracts all serve the purpose of making inter-system communication predictable and trackable. In our architecture today contracts get represented by one of three things:

With contracts, you can separate the implementation detail from the functionality of a given service. This is an important tool in building an anti corruption layer as your first step is often to redefine your domain. It also allows systems to be modular and capable of change while having a predictable impact radius on its dependents.

GraphQL allows you to take disparate data sets and represent them as a cohesive set of models with defined relations. Consider the following example:

You have a CMS that contains content related to your products:

And an inventory service that stores pricing and inventory data:

And a review service that stores review information:

What your clients need is a way to look at a common set of models from multiple different entry points. So your remodeled object in your GraphQL SDL layer could look like the following:

type Query {
    product(id: Int!): Product
    review(id: Int!): ProductReview
}
type Product {
    id: Int!
    name: String
    description: String
    images: [ProductImage!]
    tags: [String!]
    collections: [String!]
    inventory: Int!
    available: Int!
    price: ProductPrice!
    discounts: [ProductDiscounts!]
    avgRating: Int!
    reviews: [ProductReview!]
}

type ProductImage {
    url: String!
    alt: String
}

type ProductPrice {
    USD: Int!
    CAD: Int!
}

type ProductDiscount {
    code: String!
    amount: ProductPrice!
}

type ProductReview {
    id: Int!
    productId: Int!
    userId: Int!
    title: String
    description: String
    rating: Int!
    product: Product
}

Your clients create their own queries to the graph depending on their use case without having to care about where the data is originating:

They want to query a product and get all its reviews.

query FindProduct($id: Int) {
    product(id: $id) {
        id
        name
        avgRating
        reviews {
            title
            description
            rating
        }
    }
}

Or it's a review detail screen and they want to show some associated product information:

query FindReview($id: Int) {
    review(id: $id) {
        id
        rating
        title
        description
        product {
            name
            description
            avgRating
            images {
                url
                alt
            }
        }
    }
}

In either scenario, the client is able to fetch the data it needs because the SDL acts as a contract that the GraphQL layer promises to fulfill.

In GraphQL the schema is enforced by resolvers — a function that handles resolving the value of that field. Every field is, including queries and mutations, represented by a resolver. A resolvers signature consists of the following:

Resolvers allow you to fulfill the SDL requirements of a type from many many sources. For example, the legacy CMS, inventory, and review services we outlined above.

export const resolvers: Resolvers = {
    Query: {
        review(_, args, context) {
            return context.reviewLoader.load(args.id);
        },
        product(_, args, context) {
            return context.productLoader.load(args.id);
        },
    },
    Product: {
        reviews(product, _, context) {
            return context.reviewLoader.loadByProduct(product.id);
        },
        avgRating(product, _, context) {
            return context.reviewLoader.loadAvgByProduct(product.id);
        },
        async inventory(product, _, context) {
            const result = await context.inventoryLoader.loadByProduct(product.id);
            return result.inventory;
        },
        async available(product, _, context) {
            const result = await context.inventoryLoader.loadByProduct(product.id);
            return result.available;
        },
        async price(product, _, context) {
            const result = await context.inventoryLoader.loadByProduct(product.id);
            return result.price;
        },
        async discounts(product, _, context) {
            const result = await context.inventoryLoader.loadByProduct(product.id);
            return result.discounts;
        }
    },
    Reviews: {
        product(review, _, context) {
            return context.productLoader.load(review.productId);
        }
    }
}

In the example code above you can imagine the loaders are ways to fetch data from the backing systems. These calls could be over any number of protocols such as gRPC, HTTP, SOAP, etc. The idea is to have your model fulfilled from many backing services. Picture how easy it would be to add new functionality relevant to our product models. You would need a new field to the schema and a new resolver that calls to your new datasource.

Getting started can be intimidating. Rome wasn't built in a day and neither should your graph. This is an opportunity to rethink your domain and establish a ubiquitous language. Start there. Work with product, senior engineers, and stakeholders to start building a dictionary. Define what your domain should look like. Then take a piece of it, represent it in your graph, and build from there.

If your team has the tendency to build BFFEs or works in isolation you'll need to get buy-in and collaborate. You want to avoid the graph becoming another place where the same objects get defined in many ways.

At EF Go Ahead Tours we have a staff engineer who elected as a graph champion. Part of their job is to help teams understand how they can benefit from the new system. They also help run trainings, provided architectural guidance, and general oversight of the graph.

 is a great resource from Apollo to guide you on best practices.

At EF Go Ahead Tours we used this method and were able to achieve the following:

Since taking this initial approach, new technology such as Apollo Federation has emerged. This helped us continue to break apart our legacy systems over the last 3 years while innovating. In a follow up blog post, I will go over how we expanded this approach using a series of GraphQL microservices.

GraphQL adoption at EF continues to increase. In the current phase of our journey, we are working on ways to integrate many businesses through the graph. This has posed unique challenges around performance, domain modeling, and more. We'll be writing blog posts on these topics as we go. So stay tuned!

GraphQL logo on a pink background

Legacy systems can stifle innovation and become costly. Learn how to use GraphQL to create an anti corruption layer that keeps your teams innovating.

Using GraphQL as an anti-corruption layer in front of legacy services

Offline mode is extremely important for most mobile apps in the market. Different companies with apps related to travel, weather, gaming, or finance, for example, find it vital to allow users to access certain data anytime, anywhere. With this blog post, we’re gonna explore how to create a seamless offline experience using React Native and Apollo.

In the past, we’ve explored different options, including maybe the most popular approach which is to use SQLite. This is a fine solution, but it can get pretty tedious in terms of extra configuration and needing to read and write manually directly from this database.

In this simple todo app example taken from 

, we need to manually read and write on initial render:

useEffect(() => {   
   db.transaction((tx) => {
      tx.executeSql("create table if not exists items (id integer primary key not null, done int, value text);");    
   }); 
}, []);

Here, we need to initialize our table if we haven’t done so yet.

Same goes for any other function that needs to write to the db. Let’s take a look at adding a todo below.

In this function, we are directly calling our database to insert our new todo items, as well as then read them.

While all of this effectively works, you can quickly see how this can become difficult to maintain for larger apps.

With our current architecture, we have over 40 federated GraphQL micro-services. So we share these API’s amongst all of our clients, including both web and mobile. We consume these API’s using Apollo Client. “Apollo Client is a comprehensive state management library for JavaScript that enables you to manage both local and remote data with GraphQL. Use it to fetch, cache, and modify application data, all while automatically updating your UI.” For the purposes of this blog post, I won’t get into the details of what Apollo accomplishes for us, but you can read more about it in their 

One of the main benefits from Apollo is its out of the box caching implementation. They store all of your query results in a local, normalized, in-memory cache. What this means for your mobile app is that if you navigate to a screen, fetch the data, and then return to that screen (all while your app is still open), you won’t need to re-fetch all of that data again from the network. Instead, Apollo is simply smart enough to get that data from the in-memory cache.

There’s a lot of different strategies in the way you should properly cache data using Apollo Client. You can configure how you want to balance fetching data from your cache through Apollo’s 

. It’s also very important to make sure your data is being cached properly. Apollo does this by generating a cache ID using a typename and an “id or _id” field on your data object. So it’s vital that you specify a unique identifier on each of your data models, otherwise, you can specify how you plan on merging those objects in your 

So now we should have our cache properly working, but we notice that once you close out the app, you’ll be forced to fetch from the network again, since Apollo Client simply provides an in-memory cache. Going back to earlier, this won’t work for certain industries. Travelers on the road need to be able to access their data offline, which means once they close out their app, they won’t be able to fetch data from the network and they also won’t have the cache available in memory. So what do we do?

! Apollo Cache Persist is a library which seamlessly saves and restores your Apollo cache from persistent storage.

The setup is extremely simple. First, we need to decide which configurations we want to add. For example, if we want to change the maxSize, which defaults to 1MB, we can set this here. You can reference the additional configuration 

. For our example, we’ll focus on just providing our storage provider, which will be AsyncStorage.

import { ApolloClient, InMemoryCache } from "@apollo/client";
import AsyncStorage from "@react-native-async-storage/async-storage";
import { AsyncStorageWrapper, CachePersistor } from "apollo3-cache-persist";
import { useEffect } from "react";

const cache = new InMemoryCache({
   // your cache configuration
});

const persistor = new CachePersistor({
   cache,
   storage: new AsyncStorageWrapper(AsyncStorage),
});

useEffect(() => {
   async function initializeCache() {
      await persistor.restore();
      const client = new ApolloClient({
         // your Apollo Client initialization
      });
      client.onClearStore(async () => {
         await persistor.purge();
      });
   }
   initializeCache();
}, []);

First, we set up our initialize our CachePersistor from apollo-cache-persist. We reference our cache by passing it in, and we determine our storage and initialize our AsyncStorageWrapper with AsyncStorage from 

@react-native-async-storage/async-storage

. Then, in our app initialization, we restore our cache using 

. This takes care of the hard work for us by checking against Async Storage and seeing if we have any data that we need to restore as part of our cache. Once we have this part setup, we can close our app and you’ll notice you have data available without needing to make network requests (Assuming you already fetched at least once before and have it in your cache). You can switch to airplane mode to properly test this out.

Since we have proper authentication, we still have one more step. We need to make sure this data is cleared from storage on logout because of security and to prevent any bugs with data from any other users logging in using the same device. In your app initialization, we can add 

client.onClearStore(async () => { await persistor.purge() });

 , which now allows us to purge our async storage whenever we clear our Apollo Client store. So now, when we sign our users out, we can simply clear the store.

<Button
   title="Sign out"
   onPress={async () => {
      await client.clearStore();
   }}
/>

That’s it! Now our users are happy on the road being able to access their data making the user experience that much better.

You can find a working demo here. It is made so you can see a working app with the examples we’ve outlined in this blog post.

https://github.com/nicobermudez/expo-offline-app-example

Photo by <a href="https://unsplash.com/@stenslens?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Sten Ritterfeld</a> on <a href="https://unsplash.com/s/photos/offline?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a>   

Optimizing React Native offline mode using Apollo Cache Persist

#graphql.

Computed local-only fields in Apollo Client

GraphQL Codegen: What is it?

Using GraphQL as an anti-corruption layer in front of legacy services

Optimizing React Native offline mode using Apollo Cache Persist