Ready for takeoff: the new Apollo blog

We’re leaving Medium for a Gatsby and WordPress powered site

Blogging is an important way we help developers build great apps at Apollo. It’s how we share GraphQL best practices, spread awareness about new Apollo features, and connect with our awesome community of developers.

In four years, our blog has grown from a small company blog into a valuable learning resource for thousands of developers worldwide. We’d like to give a big thank you to all the community contributors who made this possible by publishing articles on our blog. Sharing your knowledge is what has made this blog successful.

We’re excited to announce that the Apollo blog has a new home at apollographql.com/blog! 🚀 Rest assured, we’ve migrated all of our articles over to the new site, so you don’t have to worry about missing your favorites.

From Medium to Gatsby

When we first started the Apollo blog in 2016, publishing on Medium was a natural choice because it allowed us to reach developers that may have not otherwise heard of us. It worked! Over the years, we amassed an audience of over 26,000 subscribers who enjoy learning about Apollo.

While we want our articles to reach as many developers as possible, that goal shouldn’t come at the expense of our readers. In recent months, we’ve been disappointed with Medium’s pop-ups and paywall that distract from the reading experience and restrict developers from accessing our content.

Instead, we decided to move off Medium in favor of creating our own blog with Gatsby, WordPress, and Netlify. Gatsby enables us to use React for our site’s frontend while querying WordPress at build time, resulting in a blog that’s fast, consistent with other Apollo sites like the docs, and easy to publish.

Our blog is open source, so please file an issue if you have any feedback. Additionally, be on the lookout for a deep dive into how we built the Apollo blog from lead Developer Experience engineer Trevor Blades!

Contribute to our blog

We love community contributions to our blog, and we encourage you to submit a proposal if you have an idea you’d like to share.

Posting to the Apollo blog is an excellent way to get involved in the GraphQL community, gain exposure, and become a better technical writer. I know this from experience, since posting my first article to the Apollo blog eventually led to me joining the team. One thing that impressed me about my first experience contributing that still rings true today was how supportive the Apollo team was during the writing process.

Whether you’re new to technical blogging or an experienced writer, we’re here for you through every step of the way. Even if your idea isn’t fully formed, we’ll work with you to scope it down, shape it, and come up with an outline. Once you have a draft, we’ll help you edit it so it’s clear and concise. Finally, we’ll spotlight your post on our blog homepage and share it with thousands of developers on social media.

Blogging is one of the most effective ways to teach others while leveling up your own skills. What are you waiting for? Submit a proposal and let us know what you think about the new Apollo blog. Happy reading!

Ready for takeoff: The new Apollo blog was originally published in Apollo GraphQL on Medium, where people are continuing the conversation by highlighting and responding to this story.

As developers, we constantly interact with documentation. It’s what welcomes us to a project for the first time, it’s a trusted companion that guides us toward celebrating our first “Hello World,” and it’s the first place we turn when we’re frustrated with a bug or curious about a new feature.

Good documentation is at the heart of crafting an excellent developer experience, which is why we’re making a big investment in improving our docs at Apollo. Today, we’re excited to share the first big milestone on our journey: Apollo’s new docs site built with Gatsby! 🚀

From Hexo to Gatsby

Previously, our docs site was built with Hexo, a static site generator, and shared its theme with Meteor. Although we love our Meteor roots, the shared theme was becoming difficult for our team to maintain and evolve over time.

We wanted to migrate to React so we could share UI across all Apollo sites and add interactive elements to our docs. While I wouldn’t normally advocate for a rewrite, our team decided it was necessary in order to modernize our stack. Both our homepage and the GraphQL Summit site are built with Gatsby, so it was an easy choice for our new docs infrastructure.

Gatsby themes

With nearly 200 repositories in the Apollo organization on GitHub, it’s important that each project’s documentation lives alongside the code. When we first heard about Gatsby’s new themes feature, Apollo engineer Trevor Blades quickly built a proof-of-concept that confirmed it would be perfect for our needs.

Gatsby themes allow you to easily compose UI, configuration, and functionality across multiple sites. Themes are distributed as npm packages, and we use them for sharing versioning logic, constructing the left-hand navigation, common layout components, and more. Not only are Gatsby themes awesome for building docs sites, they’re also great for quickly spinning up derivative sites like Principled GraphQL, which was built by extending gatsby-theme-apollo.

We’ve been really happy with themes so far, and can’t wait to explore them further. Thank you to Christopher Biscardi and the rest of the Gatsby team for all their support along the way! 🤗

Focusing on discoverability

When designing our new UI, we wanted to focus on making our content more discoverable. Previously, our layout displayed too much information on the left sidebar, which made it difficult to find what you were looking for without scrolling. Apollo designer Jess Marina rose to the challenge and created a cleaner layout and navigation structure to solve this pain point.

Cleaner navigation 🗺

For our new docs site, we removed article details from the left sidebar and added a navigation panel to the right of the screen to show users all the topics that would be covered on a page. We also made each section on the left sidebar expand and contract so users could zero in on the pages that are relevant to them.

Prominent search 🕵️‍♀️

Since our docs site spans a large breadth of content, we wanted to improve the search experience. We moved the search bar to a more prominent location, redesigned the search menu, and added a keyboard command to trigger search.

Looking to the future

We’re happy with the progress we’ve made toward improving the Apollo docs experience, but our work isn’t done yet! Over the next few months, we will be working on a refactor of our information architecture in order to help developers find what they’re looking for faster. Before embarking on this project, we will conduct user testing and publicize a plan to the Apollo community for feedback. If you’re interested in contributing, check out our Docs channel on Spectrum to learn more.

With our new infrastructure, we’ll also be able to support MDX, which will allow us to render React components alongside markdown in the same file. We’re super excited about the creative possibilities MDX will enable, especially with integrating more interactive elements into our docs. Some ideas we’ve started to explore include: interactive code blocks that compile TypeScript to JavaScript, expansion panels with step-by-step instructions, and embedding GraphiQL for running queries.

We can’t wait to see what the future holds for Apollo docs, and we hope you enjoy exploring the new site! If you have any feature requests or feedback on the site, please let us know by filing an issue in the Gatsby theme repo.

A new Apollo docs experience was originally published in Apollo GraphQL on Medium, where people are continuing the conversation by highlighting and responding to this story.

Speak at the world’s largest GraphQL developer conference!

We’re excited to welcome the GraphQL community back to San Francisco, CA for this year’s GraphQL Summit at the Hyatt Regency on October 29–31, 2019. With over 1,200 developers expected to attend, this year’s edition will be bigger, better, and spookier than ever. 👻

At Summit, you’ll hear new ideas and learn best practices from GraphQL leaders, meet maintainers of open source GraphQL projects, and connect with passionate GraphQL developers from all around the world. For a taste of what to expect, check out last year’s conference YouTube playlist.

Speak at Summit

If you have ideas to share, we want to hear them! Our Call for Proposals is now open until May 24.

What we’re looking for

Developers come to Summit to get inspired and take back knowledge they can share with their teams. We love talks that have a unique point of view, teach the audience something new, and push the GraphQL community forward.

GraphQL Summit welcomes developers of all experience levels and backgrounds. It’s important to us that our speaker lineup reflects a diverse balance of races, genders, and backgrounds, and we encourage underrepresented groups in tech and first-time speakers to apply. If you would like feedback on your proposal, we’re available to help at speakers@graphql.com.

Themes

This year’s event will be larger than ever, so we’ve organized our content program into themes to help attendees discover what’s relevant to them. We’ve included suggested talk topics for each theme in the CFP, but please don’t limit yourselves to our list. Let your creativity shine through! ✨

• The GraphQL stack: How should today’s product teams think about integrating GraphQL into their stack? These talks should share practical knowledge that developers can use right away.
• Deep dives: Technical talks on GraphQL servers, clients, or the specification itself that appeal to an advanced/expert level audience.
• Spooky stories: Name a difficult challenge you faced and how you solved it. Did you take down your production GraphQL API and live to tell the tale? Let us know what you learned from that experience!
• GraphQL infrastructure: Talks for the architects, backend developers, and DevOps folks who keep our GraphQL APIs running smoothly.
• Creative uses of GraphQL: Have you used GraphQL in an unusual way? We want to hear about it!
• Community: This theme celebrates the GraphQL community and shows people how to get involved.

Join our featured speakers

At GraphQL Summit, you’ll learn best practices and hear new ideas from a diverse group of GraphQL leaders from around the world. We’re excited to announce our first round of featured speakers:

Brie Bunge

Brie is a Software Engineer at Airbnb. After an awesome talk at JSConf HI on adopting TypeScript at scale, we’re thrilled to have Brie share her TypeScript expertise at Summit this year!

Christian Nwamba

Christian is a Senior Developer Advocate at Microsoft. Through his excellent talks on GraphQL vs. REST and well-written fullstack tutorials, Christian has inspired developers worldwide to learn GraphQL. We’re honored to have him speak at Summit!

Lauren Tan

Lauren is an Engineering Manager at Netflix. Whether she’s teaching type systems at React Rally or exploring the strongly typed graph on her blog, Lauren’s content is always engaging, which is why we can’t wait to see her speak at Summit!

Simona Cotin

Simona is a Senior Developer Advocate at Microsoft. We’re eagerly anticipating her Summit talk, but in the meantime, check out her amazing talks on serverless GraphQL or her newly released GraphQL video series!

You could be next! If you’d like to join our featured speakers on stage, please submit a proposal to our CFP.

Early Bird tickets on sale

If you’re interested in attending GraphQL Summit, we recommend purchasing your ticket soon to lock in the best price! There are a limited number of Early Bird passes available, and we sold out of our previous tiers much faster than we anticipated.

We will reimburse your ticket cost if you’re selected to speak. We will also open up discounted Community passes for GraphQL open source contributors soon, in addition to a diversity scholarship program for underrepresented groups in tech at the end of May.

We hope to see you at GraphQL Summit 2019 and look forward to reading your talk proposals! 🎉 To connect with other developers attending the conference, check out our Spectrum channel.

GraphQL Summit 2019 Call for Proposals was originally published in Apollo GraphQL on Medium, where people are continuing the conversation by highlighting and responding to this story.

A new render prop API, improved docs, and more!

The wait is over! We’re super excited to announce React Apollo 2.1, a huge step forward in improving how you develop React applications with GraphQL. It features a new render prop API and much stronger TypeScript support, along with upgraded docs. It’s also 100% backwards compatible!

From the very beginning, React Apollo was designed to make building React apps with Apollo Client a delightful and intuitive experience. For a long time, this meant connecting data to your UI with higher order components. With React Apollo 2.1, using GraphQL data in your React app is now easier than ever thanks to our brand new components: Query, Mutation, and Subscription.

We’ve been working with these components exclusively for the past three months and have been amazed not only by how much they’ve improved our productivity, but also by how fun they are to build. Read on to learn more! 🚀

Data fetching with Query

Fetching data in a simple, declarative way is one of the core features of Apollo Client. We’re excited to improve upon that feature with our new Query component, which uses the render prop pattern to update your UI with your GraphQL data.

To create a Query component, just pass a GraphQL query to the query prop and provide a function as its child that returns the UI you want to render. This function, commonly referred to as a render prop function, is called with your GraphQL query’s loading and error state, in addition to your data when it arrives. For a full list of properties on the render prop function, check out our updated API overview.

The render prop API allows for much greater flexibility than our old graphql higher order component, unlocking features such as dynamically choosing a query based on props and easily composing multiple queries. While the higher order component API is still useful, we think the new API more accurately reflects how developers are building React apps today.

Updating data with Mutation

If you thought fetching data with the Query component was cool, just wait until you try updating data with the new Mutation component! Mutation also uses the render prop pattern to pass down a function to trigger a mutation from your UI, in addition to the state of your mutation and any results.

In this example, toggleTodo is our mutate function that tells Apollo Client to fire off the mutation. We also receive information about its loading and error state, as well as any data returned. This is a vast improvement over creating mutation containers with the graphql higher order component because you no longer have to manually track the state of your mutation. We’ve also provided onError and onCompleted props to the Mutation component if you’d like to register any callbacks.

Simplifying local state with ApolloConsumer

React Apollo 2.1 introduces a new component, the ApolloConsumer, that allows you to easily access your Apollo Client instance directly via the render prop function. You can think of the ApolloConsumer component as similar to the Consumer component from the new React context API.

One of the benefits of the ApolloConsumer component is that it drastically reduces the amount of code you need to write in order to perform simple local mutations with apollo-link-state. For one-off mutations like writing a string to the cache, there’s no need to set up a resolver or a GraphQL mutation! In your ApolloConsumer render prop function, just call writeData directly from your Apollo Client instance.

You can also use the ApolloConsumer component for firing queries manually in response to a user action, like a button click, or for prefetching data.

New docs & tutorials

With the React Apollo 2.1 release, we’re thrilled to finally share our revamped docs site, now with search and more tutorials! All of our docs improvements were specifically built with the community in mind, thanks to all the feedback you’ve shared with us on Twitter and Slack.

Not only did we refactor the code samples to Query and Mutation components, we also refactored the left-hand navigation to make core features like pagination and local state management more discoverable. In case you already know what you’re looking for, we reenabled search across all Apollo docs, thanks to Jesse Rosenberger.

For this release, we wanted to ensure that the getting started experience with Apollo Client was approachable and interactive, so we built a new essentials section from the ground up. The Apollo essentials section covers everything you need to start building your first Query and Mutation components quickly without overwhelming you with information. They feature tutorials on Apollo Boost, Query components, Mutation components, and Apollo Link State accompanied by interactive examples on CodeSandbox.

We know that many of you will be migrating to the new render props API incrementally, so we’ve made the old docs for the graphql higher order component available within the React Apollo API section.

Contributors

We’d like to thank Kevin Ross, Dirk-Jan Rutten, and Leonardo A Garcia C, who tirelessly worked to help write, test, and improve the new render props API. We’re really happy with how flexible the Query, Mutation, and Subscription components are, and we can’t wait to see what all of you build with them!

For the past two months, many of our community members were brave enough to test out the beta version of React Apollo 2.1. We’d like to give a shoutout to all our early testers, especially content creators such as Wes Bos and Sara Vieira, for your invaluable feedback on how to refine and teach the new components.

Finally, I’d like to give a special thanks to all of the Apollo team members who were involved in shipping this release, especially James Baxley III for his leadership over the project. It’s been awesome to see your vision for React Apollo evolve over the past two years.

What’s next 🚀

Our work isn’t done yet! We’re constantly looking to iterate upon the best way to build React apps with GraphQL. Here’s a sneak peek of some of the things on our mind that should be coming to React Apollo in the future:

• Today, you can manually fire queries either for prefetching or in response to a user action by creating an ApolloConsumer component, but you have to handle your own loading and error state. Soon, we’re looking to make manually firing queries a first-class feature in the Query component by adding a new delay prop and load action to the render prop function.
• We’re eagerly anticipating the release of React 16.3 and its awesome features like the new context API. Once it arrives, we will release a new major version of React Apollo that’s 100% compatible with async strict mode and all of the latest features.
• Beyond React 16.3, we can’t wait to start experimenting further with integrating React Suspense into React Apollo. We’ve already released a first proof of concept, and are curious to see where it goes!

As always, we would love to hear your feedback about React Apollo 2.1 and the direction of the project. We hope you love it as much as we do! ❤️

Introducing React Apollo 2.1 was originally published in Apollo GraphQL on Medium, where people are continuing the conversation by highlighting and responding to this story.

The suspense was killing us, so we built async React Apollo!

Like many members of the React community, the Apollo team eagerly woke up at 5:00 AM to catch Dan Abramov’s talk on the future of React at JSConf Iceland. With big mugs of coffee in hand, we glued ourselves to our laptops and watched as Dan explained how React async rendering would allow us to adapt our applications to our users’ many devices and networks.

Showcasing two outstanding demos, Dan illustrated some of async React’s new features such as time slicing and suspense. We couldn’t wait to get our hands dirty with these new features, so we started experimenting with what it would take to make Apollo Client async-ready. Thanks to James Baxley III, we shipped a prerelease of React Apollo 3.0 that’s 100% strict mode compliant, which is essential in order for your library to be async compatible.

Read on to learn how we made React Apollo async compatible and built an Andrew Clark inspired demo with GraphQL and Apollo! 🚀

The suspense was killing us

Optimizing fetching GraphQL data in your React app is something we’re constantly working on improving. That’s why we were thrilled to learn about React’s latest feature, suspense! Suspense lets you pause rendering a component while it’s loading async data. Here’s a step-by-step breakdown from Andrew about how it works:

Andrew Clark on Twitter

Here's how suspending works: - in the render method, read a value from the cache.

Let’s look at how Dan implemented data fetching with suspense in the I/O demo from his talk:

Under the hood, the createFetcher function uses React’s new cache implementation called simple-cache-provider in order to suspend the request from within the render method. With React Apollo, we can mimic this functionality by suspending the result of our GraphQL query.

To turn on this feature in our Query component, it’s as easy as passing a new asyncMode prop. No other changes necessary!

How did we implement asyncMode? The snippet below is from our getQueryResult function inside React Apollo, which is called in the Query component’s render method. If we’re in async mode and we’re loading, which means the request isn’t found in Apollo’s cache, we throw the promise that will eventually resolve to the result of our query.

Why are we throwing a promise here? 🤔 While this pattern might feel out of your comfort zone the first time you try it, it’s what allows React to suspend rendering until the promise is resolved. This unlocks the ability to handle loading state in a more thoughtful way by bubbling up the pending promise to a parent placeholder component. If the request time exceeds a threshold, the placeholder component can render a fallback UI until the request completes. This feature works similarly to error boundaries created with componentDidCatch.

Suspense is also what allows React to pause low-priority updates like data fetching while continuing to render high-priority updates like entering text into a search input. Once the promise eventually resolves with our GraphQL result, React will continue rendering where it left off. You can think of pausing and resuming rendering as creating a branch and rebasing that branch onto master, as Dan eloquently explained in his talk.

Tying it all together

Once we shipped a prerelease of async React Apollo, we couldn’t wait to give it a spin in an example app. Luckily, wrapping REST endpoints with a GraphQL server is our specialty, and with the power of GraphQL-specific caching built into Apollo Engine, the app is blazing fast!

If you’d like to skip to the code, you can check out our example below on CodeSandbox. Warning: the React API that powers deferred state updates is unstable, so proceed with caution!

Aside from setting the asyncMode flag on your Query component, you’ll notice not much has changed with how you build Apollo apps in an async React world vs. how you build them today. We want to help you take advantage of all the cool features async React has to offer without making you rewrite your entire application. Our goal is to bring you the best developer experience possible by empowering you to easily build performant, fluid applications with React and GraphQL.

What’s next 🚀

Our work isn’t done yet. We’re just scratching the surface of all the creative ways async rendering will enable us to build better user experiences with React and GraphQL.

One new feature we’re super excited to explore further is the simple-cache-provider. We think it will inspire new ways of thinking about the Apollo Client cache and future developments to help improve performance. We’re especially interested in testing out the simple-cache-provider low-level APIs that Dan mentioned in his talk. It’s possible that we could eventually hook into these APIs to normalize your GraphQL result before React’s commit phase.

If you’d like to give async React Apollo a spin, npm i react-apollo@canary and make sure to show us what you’ve built. The API is highly likely to change, especially as the React team starts to refine async APIs, so please don’t use it in production. That being said, we’d love to hear what you think and can’t wait to see how React Apollo 3.0 evolves.

A special thanks to the React team for their feedback on our post and for giving us early access to some of the new features! 👏 We look forward to collaborating further to ensure that all Apollo apps can fully benefit from all of async React’s exciting new features. If you are interested in helping us integrate Apollo with async React, come join us on Apollo Slack!

A first look at Async React + Apollo was originally published in Apollo GraphQL on Medium, where people are continuing the conversation by highlighting and responding to this story.

Meet apollo-boost, the easiest way to start using Apollo Client

Recently, there have been a lot of exciting developments happening in the GraphQL client space. Some of these new clients, such as urql and micro-graphql-react, were partially born from the idea that Apollo should be easier to get started with, especially for beginners. We’ve taken this constructive feedback to heart — that's why today, we’re announcing apollo-boost, an easy-to-use booster kit for Apollo Client with our recommended configuration. 🚀 We’re really hyped about making GraphQL easier to learn with Apollo Boost and can’t wait to hear what you all think!

As of today, here’s how simple it is to get started with Apollo Client:

import ApolloClient from 'apollo-boost';

const client = new ApolloClient();

The longer you work on an open source project, the tougher it is to put yourselves in the shoes of someone who’s discovering the project for the first time. As library authors, we want to work harder at this. Our main goal is to make GraphQL more approachable and powerful for everyone. For us, building Apollo Boost was an awesome chance for us to focus on empathy, and we’re really happy with the outcome. 🤗

I encourage all of you to take a step back and practice empathy building your software too. At the same time, continue to provide valuable feedback toward the open source projects you love.

Back to our roots

From the beginning, the Apollo team has always strived to design tools that were simple to get started with, so you could send your first query right away. While Apollo Client 2.0’s modular architecture unlocked new possibilities for experienced users to customize their cache and network stack, it also deviated somewhat from our original goal of simplicity. First impressions are everything, and it’s important to us that beginners feel comfortable working with GraphQL. That’s why we’re returning back to our roots with apollo-boost!

If you’ve been with us since the 1.0 days, you’ll notice that the ApolloClient exported from apollo-boost looks familiar. With Apollo Boost, you no longer have to manually connect your cache and network stack to the client. We’ve already set up InMemoryCache and HttpLink for you by default. No heavy lifting required. 💪

Get started

Creating a client with Apollo Boost requires zero config to get started. We’ve included some packages that we think are essential for building an Apollo app, like apollo-link-error and apollo-link-state. You can activate these features by specifying a few options on the ApolloClient constructor and we’ll set them up for you behind the scenes.

Let’s dive in! First, you’ll want to install the following packages. We’re going to install the new React Apollo 2.1 beta so we can take advantage of Query components.

npm i apollo-boost react-apollo@beta graphql -S

Next, create your client and hook it up to your app by passing it to the ApolloProvider exported from react-apollo.

Now that our app is up and running, let’s make our first query:

That’s it! If you need more customization, there are only six optional config properties you can pass to the Apollo Boost client:

• uri: Your GraphQL endpoint (defaults to /graphql)
• fetchOptions: Static fetch options for every request
• request: A function called every request that receives the operation. Here, you can implement authentication easily by dynamically setting headers on the context.
• onError: An error handler function (our default logs out errors for you)
• clientState: Your local state config for apollo-link-state
• cacheRedirects: Functions for redirecting queries to another entry in the cache (previously called cache resolvers)

Advanced migration

If you’re looking to integrate custom links into your Apollo Link stack that aren’t already included in Apollo Boost, migration is simple. Apollo Boost exports some of the building blocks of Apollo Client, like HttpLink and InMemoryCache, for you so you don’t have to reinstall all of the individual packages. In the future, we’d love to have an eject feature that writes your client setup for you automatically.

🔥 New 🔥

In addition to Apollo Boost, we’ve also made some improvements to the docs, along with a new example app on CodeSandbox.

• Pupstagram: Our new example app 🐶 (aka what I wish my Instagram feed was). It features Apollo Boost, local state management with apollo-link-state, and more! For the GraphQL server, check out our Launchpad.
• Quick Start: Go from zero to your first queries & mutations in less than 10 minutes with Apollo Boost.
• Why Apollo: Wondering why we normalize our cache? Need a document to convince your team to switch to Apollo Client? It’s all right here.

With the release of Apollo Boost, we’ve sunset the apollo-client-preset proof of concept which served as inspiration. For backwards compatibility, everything that was included in the old preset is included in apollo-boost. Simply change your import and you should be good to go! Thanks to everyone who helped test out apollo-client-preset.

Inspiration

Apollo Boost was largely inspired by the simplicity of urql, the newest GraphQL client on the block. We’d like to give a big thank you to Ken Wheeler and the team at Formidable Labs for challenging us to rethink how we could improve the developer experience for our users. We’re grateful for the opportunity to learn from your work.

It’s super exciting to see newcomers popping up in the GraphQL ecosystem because we all get to build upon each other’s successes. I firmly believe that competition is healthy for open source projects to keep innovating. As long as more developers are getting hyped about GraphQL and how it can improve their team’s productivity, we welcome anyone entering the space.

Finally, we’d also like to thank all of you! Our team loves hearing honest feedback from the community, whether it’s positive or constructive. If you have any ideas on how we can make your experience with Apollo better, just drop us a message on Twitter or Slack.

Zero-config GraphQL state management was originally published in Apollo GraphQL on Medium, where people are continuing the conversation by highlighting and responding to this story.

Managing your local data in Apollo Client with apollo-link-state

When an application grows in size, its state often grows in complexity. As developers, we’re not only tasked with juggling data from multiple remote servers, but also with handling local data resulting from UI interactions. To top it off, we have to store all of this data in a way that’s easily accessible from any component in our application.

Thousands of developers have told us that Apollo Client excels at managing remote data, which equates to roughly 80% of their data needs. But what about local data (like global flags and device API results) that make up the other 20% of the pie?

Historically, Apollo users managed that 20% in a separate Redux or MobX store. This was a doable solution for Apollo Client 1.0, but when Apollo Client 2.0 migrated away from Redux, syncing local and remote data between two stores became trickier. We often heard from our users that they wanted to encapsulate all of their application’s state inside Apollo Client and maintain one source of truth.

Building upon a solid foundation

We knew we had to solve this problem, so we asked ourselves: What would it look like to manage state in Apollo Client? First, we thought about what we liked about Redux — features like its dev tools and binding state to components via connect. We also thought about some of our pain points with Redux, like its boilerplate and its do-it-yourself approach to core features like asynchronous action creators, caching, and optimistic UI.

To create our ideal state management solution, we wanted to build upon what makes Redux great while addressing some criticisms of it. We also wanted to leverage the power of GraphQL to request data from multiple sources in one query.

Learn once, GraphQL anywhere

One common misconception about GraphQL is that it’s coupled to a specific server implementation. In fact, it’s much more flexible than that. It doesn’t matter if you’re requesting from a gRPC server, REST endpoint, or your client-side cache — GraphQL is a universal language for data that’s completely agnostic of its source.

This is why GraphQL queries and mutations are a perfect fit for describing what’s happening with our application’s state. Instead of dispatching actions, we use GraphQL mutations to express state changes. We can access our state by declaratively expressing our component’s data requirements with a GraphQL query.

One of the biggest advantages of GraphQL is that we can aggregate data from multiple sources, both local and remote, in one query by specifying GraphQL directives on our fields. 🎉 Let’s find out how!

State management with Apollo Client

Managing your local data in Apollo Client is made possible by Apollo Link, our modular network stack that allows you to hook into the GraphQL request cycle at any point. To request data from a GraphQL server, we use HttpLink, but to request local data from our cache we need to install a new link: apollo-link-state.

To create your state link, use the withClientState function and pass in an object with resolvers, defaults, and your Apollo cache. Then, concatenate your state link to your link chain. Your state link should come before your HttpLink so local queries and mutations are intercepted before they hit the network.

Defaults

Your defaults are an object representing the initial state that you would like to write to the cache upon creation of the state link. While not required, it’s important to pass in defaults to warm the cache so that any components querying that data don’t error out. The shape of your defaults object should mirror how you plan to query the cache in your application.

Resolvers

When we manage state with Apollo Client, our Apollo cache becomes our single source of truth for all the local and remote data in our application. How do we update and access the data in the cache? That’s where our resolvers come in. If you’ve worked with graphql-tools on the server, the type signature of resolvers on the client are identical:

fieldName: (obj, args, context, info) => result;

No worries if this is unfamiliar to you, the two most important things to note here are that your query or mutation variables are passed in as the second argument and the cache is automatically added to the context for you.

To write data to the root of the cache, we call cache.writeData and pass in our data. Sometimes what we’re writing to the cache depends on the data that was previously there, like in our mutation addTodo above. In that case, you can use cache.readQuery to read from the cache before you perform a write. If you would like to write a fragment to an existing object in the cache, you can optionally pass in an id, which corresponds to the object’s cache key. Since we’re using the InMemoryCache, the key is __typename:id.

apollo-link-state supports asynchronous resolver functions, which is useful for performing async side effects like accessing device APIs. However, we don’t recommend calling REST endpoints in your resolvers. Instead, use apollo-link-rest, which has its own @rest directive.

@client directive

When we trigger a mutation from our UI, Apollo’s network stack needs to know whether to update the data on the client or the server. apollo-link-state uses an @client directive to specify client-only fields. Then, apollo-link-state calls the resolvers for those fields.

Queries look very similar to mutations. If you are performing any asynchronous actions in your query, Apollo Client will track loading and error states for you. For React, you’ll find these states on this.props.data, along with numerous helper methods for refetching, pagination, and polling.

One exciting feature is that you can request from multiple data sources in one query! 😍 In this example, we’re requesting a user from our GraphQL server in addition to the visibilityFilter in the Apollo cache.

For more examples and tips for integrating apollo-link-state into your application, head on over to our updated docs page.

Roadmap to 1.0

Even though apollo-link-state is stable enough to use in your application today, there are some features we’d like to tackle soon:

• Client-side schema: Right now, we don’t have support for type validation against a client-side schema. This is because including the graphql-js modules for constructing and validating a schema at runtime would dramatically increase your bundle size. Instead, we hope to move schema construction to build time with support for introspection so you can still take advantage of all the cool features in GraphiQL.
• Helper components: Our goal is to make state management in Apollo as seamless as possible. We’d like to write some React components to reduce some of the verbosity for performing common tasks like passing a variable into a mutation while still implementing it as a mutation under the hood.

If these problems sound interesting to you, come join us on GitHub or the #local-state channel on Apollo Slack. We’d love to have you on board to help shape the next generation of state management! 🚀

The future of state management was originally published in Apollo GraphQL on Medium, where people are continuing the conversation by highlighting and responding to this story.

AWS AppSync, built with Apollo

A first look at Amazon’s newest GraphQL product

Yesterday at reInvent, Amazon launched AppSync, a new GraphQL service featuring real-time updates and built-in offline support. Managed in the AWS console, AppSync’s GraphQL layer aggregates data from other AWS products such as ElasticSearch and DynamoDB. In your application, you query your GraphQL API with the AppSync Client, available for web and native.

The AppSync announcement got a lot of love from the developer community, and it’s easy to see why people are excited about GraphQL! Architecting your application with GraphQL enables you to build complex features quickly by simply describing your data requirements and letting your GraphQL layer take care of the rest. Companies like the New York Times, Coursera, and Express have led the way by powering their most important applications with GraphQL.

Naturally, we were curious to learn more about AppSync. Once we dug into the open-source code, we were excited to see that the AppSync Client implementations are based on the same MIT-licensed Apollo technology you know and love: Apollo Client 2.0, Apollo iOS, and Apollo Codegen! Read on to learn how different components of these Apollo projects power some of the coolest features of the AppSync platform.

Leveraging Apollo Client’s extensibility

Last month, we officially released Apollo Client 2.0 at GraphQL Summit 2017. In addition to making it smaller and faster, one of our main goals was to also make it much more modular. You now have the ability to plug in your own cache and tailor your network stack to your application’s requirements with Apollo Link.

It turns out that Apollo Client 2.0’s modular architecture was a huge win for developers looking to customize their GraphQL client, because that’s exactly how the AWS team was able to build AppSync Client!

In only a few weeks, the AWS team was able to make complex features like offline support and authentication a reality by extending the Apollo InMemoryCache and using Apollo Link to customize their network interface. We think this is a testament to the extensibility of Apollo Client and hope their example inspires more teams to experiment with personalizing their GraphQL client. Let’s dive into how AWS accomplished this.

Apollo Link enables offline support

To achieve offline support, the AWS team created a custom Apollo Link that takes a Redux store augmented by redux-offline for persistence. This link also queues up any pending mutations and calls to refetch queries when the device is offline and stores them in a Redux subtree to be executed when the device goes back online. Since the AppSync Client is based on Apollo Client, you still get the benefit of optimistic UI responses even if the device is offline when the mutation is fired.

AWS re:Invent on Twitter

Using AWS SDK for Mobile development will give you Automatic offline support out of the box @saligramkarthik #reInvent

We’re also working on improving the offline experience to create easy persistence that isn’t dependent on Redux and advanced features such as applying a timeout to the offline mutation queue to avoid potential conflicts. If you’d like to learn more about these initiatives, come join the party on the apollo-cache-asyncstorage repo! 🎉 We’d love to hear your input and welcome any contributions.

Real-time data with GraphQL subscriptions

One AppSync feature that generated a lot of buzz is its emphasis on real-time data. Under the hood, AppSync’s real-time feature is powered by GraphQL subscriptions. While Apollo bases its subscriptions on WebSockets via subscriptions-transport-ws, subscriptions in GraphQL are actually flexible enough for you to base them on another messaging technology. Instead of WebSockets, AppSync’s subscriptions use MQTT as the transport layer.

The AWS team even wrote their own Apollo Link to execute subscriptions over MQTT, which we think is a really cool use case. If you’d like to integrate real-time features into your application in only a few lines of code with Apollo Link, please check out our example which serves queries & mutations over HTTP and subscriptions over WebSockets. We’d also like to hear from you on the subscriptions-transport-ws repo if you have any suggestions on how to improve our transport layer.

Native client with Apollo iOS & Apollo Codegen

Another cool feature of AWS AppSync is that it’s compatible with different platforms. It works with JavaScript and also with native platforms written in Swift. One of our main goals for Apollo is that you can use it with any type of architecture, which is why we collaborated with the community on Apollo iOS and Apollo Android. It’s exciting to see AppSync builds on that foundation to power their native client!

To generate Swift types from AppSync’s GraphQL layer, AWS uses a customized version of Apollo Codegen. Apollo Codegen is a build tool that uses your GraphQL schema and queries to output types for a variety of different language targets: Flow, TypeScript, Java, Scala, and Swift.

We’re constantly working with the community to continuously improve the language targets; for example, Lewis Chung from Coursera published a revision to the Flow & TypeScript targets just this week! If you’re interested in generating static types from GraphQL and would like to strengthen the generated code or support additional targets like Reason, please reach out! We’d love to welcome you on board.

A bright future 🚀

AWS AppSync is an excellent example of how teams can create innovative products quickly by using the Apollo family of tools. We’re so excited to see that Apollo works well as an extensible platform for developing customized GraphQL client tooling.

With our solid foundation in place, we can’t wait to see more people build upon the Apollo platform to push the GraphQL ecosystem forward! If you’re interested in collaborating with us to create the next generation of GraphQL tooling, learn more on our contributor site. We’d love to hear from you! 🤗

AWS AppSync, powered by Apollo was originally published in Apollo GraphQL on Medium, where people are continuing the conversation by highlighting and responding to this story.

Learn how to manage all your app data with Apollo in my talk from GraphQL Summit 2017

Apollo Client 1.0 was all about taking data from your GraphQL server and attaching it to your UI components. That’s a really important aspect of building an application that we’ve made faster, simpler, and more powerful in Apollo Client 2.0. But with the newly released version, you can actually use GraphQL to do much more than just load data from a server. You can use the same query language to manage your client-side data and even fetch from non-GraphQL APIs!

This is exactly what I explored in my talk at this year’s GraphQL Summit. Check out the video below, or if videos aren’t your jam, keep on reading to learn how Apollo Client 2.0 can simplify managing all of your application’s data, including local & REST data.

A solid foundation

Over the past year, Apollo Client has seen astounding growth, with over 2.5 million downloads on npm & nearly 5,000 stars on GitHub. I think a lot of this success can be attributed to the fact that Apollo removes a ton of front-end complexity for React, Angular, and Vue developers alike. All you have to do is describe exactly the data you want from your server with GraphQL, bind it to your component, and let Apollo Client take care of the rest.

The benefits of building your application with Apollo extend far beyond the ability to easily retrieve data from a GraphQL server. With Apollo Client, you no longer have to worry about fetching data, transforming the response, normalizing, and caching it. Features that normally require significant coding, such as optimistic UI updates, pagination, and prefetching data, become trivial to execute.

What’s new with Apollo Client 2.0

How did we improve upon an already solid foundation with Apollo Client 2.0? The newest version is 2–5x faster, 40% smaller, and most users can upgrade by changing only 5 lines of code. The main difference is our revamped modular architecture that paves the way for the future of GraphQL — things like streaming data, custom directives, and individualized caching.

Cache

We know caching is never one size fits all, so with Apollo Client 2.0 you can now easily swap out our default in-memory cache with your own implementation. We’ve already started to see community members build their own with great success, like the team at Convoy did with their graph-based cache Hermes. I’m super excited to see the community get creative with their Apollo Client caches in the upcoming weeks; for example, I’d love to see an integration for React Native AsyncStorage or MobX. If you have an idea, please don’t hesitate to get in touch by pinging me on Twitter @peggyrayzis!

Network stack

Our new interface for personalizing your network stack is called Apollo Link. Links are powerful because they allow you to hook into the request cycle at any point to manipulate how you process & retrieve your data. They’re backed by Observables, instead of promises, so you can return multiple results from one operation.

With only a few lines of code, you can create your own links and compose them together to fully manage your data flow from beginning to end. Here, we’re using the ApolloLink.split utility method to branch our request by serving subscriptions over WebSockets and queries & mutations over HTTP. The first argument to a link gives you full access to your query, which enables you to determine how to retrieve your data and what happens with the result.

If we can hook into the request cycle at any point with Apollo Link, then we can start to get really creative with how we process and retrieve our data. The last half of my talk dives into some experimental features that are now possible because of Apollo Link. Let’s get weird! 😜

Unlocking a universe of possibilities

Remember our diagram from earlier in the post where data was loaded from a GraphQL server? What if we could switch that GraphQL server out with something else? Since Apollo Link allows you to determine where you’re retrieving your data from based on a GraphQL operation, you can theoretically request data from anywhere. As long as the data coming back is JSON or an object, you should be able to query your source using GraphQL and get back whatever you want.

Apollo Link opens up the door to unlimited possibilities. What if we could query local data in your application and store it in Apollo Client? This includes things like network status, routing, or anything you currently use Redux or MobX for. By integrating your client-side data into Apollo Client, you get the same awesome features like built-in caching and ease of querying with GraphQL, without having to set up and maintain a second store.

Client-side state management

This is exactly what we’re proposing with Apollo Link State, our solution for managing client-side data entirely in Apollo Client. Thanks to James Baxley, Apollo Link State is already out, and although it’s in a very early stage, we’re excited about its potential! To set it up in your application, you will pass a resolver map to your state link that determines how you’ll read & write your local data to the cache. If you’ve worked with graphql-tools before, the API will look familiar. The main difference here is that the cache is added to the context so you can manipulate it directly like you would a database on the server.

What would our query requesting local data look like? By annotating a client-side field with the @client directive, the state link will be able to process the operation and tell it to resolve from the cache.

We can also query data from a REST endpoint in a similar way. By marking a field with the @rest directive, we can hit our REST endpoint and store exactly the data we request in Apollo Client side by side with our local and GraphQL server data. A contributor has already started working on a similar implementation and we hope to have an official version of Apollo Link REST out soon. Eventually, you’ll be able to combine all of these directives and request from multiple data sources in one query! 😍

Now that Apollo Link enables us to request data from anywhere, we can use Apollo Client to manage all of our application’s data. No more action creators, reducers, or maintaining a separate store! All you need to do is write queries with GraphQL and let Apollo Client take care of the rest.

Whether you’re requesting data from a REST endpoint, your application, or a GraphQL server, Apollo Client 2.0 is truly a universal data solution. The new modular architecture is flexible and extensible, so you can tailor your network stack and cache implementation to your application’s needs. Since Apollo Client is decoupled from the view layer, React, Angular, and Vue developers can all benefit from these advancements.

Get started 🚀

If you would like to test out Apollo Client 2.0, here are some example projects to get you started:

• React: https://codesandbox.io/s/jvlrl98xw3
• Angular: https://github.com/kamilkisiela/apollo-angular-ssr
• Vue: https://codesandbox.io/s/3vm8vq6kwq

We’d love to welcome you to our community and are eager to hear your feedback on the latest version of Apollo Client. Here’s how to get involved!

For more awesome GraphQL content, keep an eye on our YouTube channel to see more talks from GraphQL Summit 2017. Make sure to subscribe so you don’t miss a beat! 😊

Apollo Client 2.0: Beyond GraphQL APIs was originally published in Apollo GraphQL on Medium, where people are continuing the conversation by highlighting and responding to this story.

What would you do if conference organizers themselves committed a Code of Conduct violation against you?

This was the precise situation I found myself in recently the night before I was scheduled to speak at ReactiveConf, a React community conference hosted in Bratislava. I’d already travelled halfway across the world to attend, put weeks of work into a talk and slides I was excited to present, and was missing a company onsite for the team I’d just joined.

ReactiveConf’s Code of Conduct states that “harassment includes … sexual images in public spaces”, and makes a point to remind event sponsors “to not use sexualized images… or otherwise create a sexualized environment”. That is why it was a shock to receive my speaker gift just before the speakers’ dinner at the end of day one, only to see that the conference organizers had photoshopped my face onto a sexualized image of Wonder Woman without my consent, printed it out, and framed it. On top of that, this was the image they had intended to display on the big screen before my talk to 1000+ attendees, as they had already done for speakers earlier that day.

An uphill battle

As a woman in the tech industry, being taken seriously is already difficult enough. I’ve been sexually harassed at a conference, have received lewd comments on my published talk videos, and regularly have to field questions from men asking if I know how to code. That’s why it was so hurtful and alienating to receive this image from the very people who are tasked with creating a supportive and professional environment at the event.

By portraying me in a sexual way to attendees, this would have opened the door to additional harassment, and added yet another hurdle I’d have to overcome in order to be perceived as a competent professional. The fact that nowhere along the way did ReactiveConf organizers recognize how this gift could actually be harmful, to me, demonstrated a complete lack of empathy for women in tech. That’s not an organization I want to associate myself or my employer, Meteor Development Group (MDG), with.

Not only is the photo itself problematic, but also the fact that ReactiveConf never asked for my consent. I was never informed that ReactiveConf was planning on altering my photo for the event, nor did I see the superhero picture until after day one of the conference had ended. None of the organizers explicitly asked for my permission to display the picture on the big screen. Had I presented my talk on day 1, I would have been completely blindsided as I walked on stage, which is what happened to a colleague of mine who was also unhappy with his picture.

Speaking at a conference is already a monumental investment of mental, emotional, and physical effort, right up until the plane ride home. The will to continue investing any more energy into an event whose organizers had showed so little consideration for their speakers vanished as soon as I received the gift. After consulting with trusted members of my team, I decided to withdraw and leave the situation immediately.

Cancelling my talk was not a decision MDG and I took lightly. I know many of the attendees were disappointed by my withdrawal; however, I wasn’t willing to stay at ReactiveConf at the expense of my values and feeling additional discomfort.

The aftermath

Just when I thought the situation couldn’t get any worse, it did. To date, I still have not received a sincere apology, public or private, from the ReactiveConf team. They received a firm but considerate email from a teammate who was able to let them know I was withdrawing while I was in transit without cell service. Instead of respecting my decision or acknowledging the role their decisions played, they resorted to shaming me on Twitter:

On the conference Slack, ReactiveConf organizers have attempted to cover up what happened by claiming that we speakers gave them permission to release our images. This is completely false.

The facts are simple: the ReactiveConf team never asked the speakers for permission to photoshop our images. We did not see the pictures before they were printed, and many of us did not see them before they were tweeted and displayed on the big screen.

But the exact ordering of events aside, their response has continued to demonstrate disrespect and an inability to take any responsibility for their decision-making. They have implied that I should not have been offended because it was not their intent to offend, and that I owed them further explanation and discussion. Nowhere was there an understanding that I might not have been ready to go into more detail about how upsetting I found the situation, or that withdrawing came at great personal expense as well given the effort I’d already put into speaking.

Their response only confirmed that I had made the right call.

A silver lining

A big thank you goes out to all my colleagues and friends who have defended me publicly and offered to help over the past couple days. Your support means the world to me. ❤️

Throughout this situation, MDG has stood by my side every step of the way. From helping me find last-minute travel arrangements and navigate communication with the organizers, to welcoming me with open arms at GraphQL Summit, everyone on the team has been nothing short of amazing. I feel very fortunate to be a part of an organization who isn’t afraid to stand up for what’s right, even if it may be unpopular or controversial.

At MDG, we value transparency and think incidents like this one are a good opportunity to provide feedback. Hopefully, conference organizers can learn from what happened at ReactiveConf to make event experiences better for everyone.

Takeaways

In the future, I will be more selective with where I choose to devote my energy & time. There were several red flags leading into ReactiveConf, such as the lightning talk debacle and their refusal to book my travel arrangements in a timely manner, that should have clued me into how I would be treated when I arrived.

Speakers, trust your gut. If you get bad vibes early on, you should reconsider whether you want to invest in that event. Additionally, if you are harassed by the conference staff, please don’t feel guilty for standing up for yourself and withdrawing from the conference. We need to call out bad behavior when we see it in order to prevent incidents like these from becoming the norm.

Organizers, please remember that your speakers are vital to the success of your event. We devote countless hours of our free time, often without pay, in order to ensure that your attendees have a great experience. Please reciprocate our efforts by treating us with respect. Respect our image by asking for permission before altering and publishing a speaker’s photo. Respect our time by booking travel arrangements and reimbursing expenses promptly. If something goes wrong, apologize gracefully and respect the speaker’s decision if they no longer wish to participate in your event.

Attendees, research conferences before you decide to attend. If you care about the well-being of the people who travel to present there, then vote with your wallet and support events that work to create a respectful and professional atmosphere for attendees and speakers alike. If your company regularly sponsors conferences, make sure they are sponsoring events whose organization aligns with their corporate values.

It may not be easy, but let’s all work together to ensure a better conference experience for everyone.

If you would like to see the talk on Apollo Client 2.0 that I was scheduled to present at ReactiveConf, you’re in luck! Check out the video from GraphQL Summit 2017, the slides, and the accompanying blog post. 😊