GraphQL

Search…
GraphQL
Using Graphql with Overmind gives you the following benefits:
Query: The query for data is run with the rest of your application logic, unrelated to mounting components
Cache: You integrate the data from Graphql with your existing state, allowing you to control when new data is needed
Optimistic updates: With the data integrated with your Overmind state you can also optimistically update that state before running a mutation query
Get up and running
Install the separate package:
npm install overmind-graphql
Initial state
The Graphql package is an effect. Though since we are operating on state, let us prepare some:
overmind/index.js
overmind/state.js
import { state } from './state'
​
export const config = {
  state
}
​
export const state = {
  posts: []
}
The effect
Now let us introduce the effect:
overmind/index.js
overmind/onInitialize.js
overmind/effects/gql/index.js
overmind/effects/gql/queries.js
overmind/effects/gql/mutations.js
overmind/effects/gql/subscriptions.js
import { state } from './state'
import { onInitialize } from './onInitialize'
import { gql } from './effects/gql'
​
export const config = {
  onInitialize,
  state,
  effects: {
    gql
  }
}
export const onInitialize = ({ effects }) => {
  effects.gql.initialize({
    // query and mutation options
    endpoint: 'http://some-endpoint.dev',
  }, {
    // subscription options
    endpoint: 'ws://some-endpoint.dev',  
  })
}
import { graphql } from 'overmind-graphql'
import * as queries from './queries'
import * as mutations from './mutations'
import * as subscriptions from './subscriptions'
​
export const gql = graphql({
  queries,
  mutations,
  subscriptions
})
import { gql } from 'overmind-graphql'
​
export const posts = gql`
  query Posts {
    posts {
      id
      title
    }
  }
`;
import { gql } from 'overmind-graphql'
​
export const createPost = gql`
  mutation CreatePost($title: String!) {
    createPost(title: $title) {
      id
    }
  }
`
import { gql } from 'overmind-graphql'
​
export const onPostAdded = gql`
  subscription PostAdded() {
    postAdded() {
      id
      title
    }
  }
`
You define queries, mutations and subscriptions with the effect. That means you can have multiple effects holding different queries and even endpoints. The endpoints are defined when you initialize the effect. This allows you to dynamically create the endpoints based on state, and also pass state related to requests to the endpoints. The queries, mutations and subscriptions are converted into Overmind effects that you can call from your actions.
Query
To call a query you will typically use an action. Let us create an action that uses our posts query.
overmind/actions.js
export const getPosts = async ({ state, effects }) => {
  const { posts } = await effects.gql.queries.posts()
​
  state.posts = posts
}
Mutate
Mutation queries are basically the same as normal queries. You would typically also call these from an action.
overmind/actions.js
export const getPosts = async ({ state, effects }) => {
  const { posts } = await effects.gql.queries.posts()
​
  state.posts = posts
}
​
export const addPost = async ({ effects }, title) => {
  await effects.gql.mutations.createPost({ title })
}
Subscription
Subscriptions are also available via actions. You typically give them an action which triggers whenever the subscription triggers.
overmind/actions.js
export const getPosts = async ({ state, effects, actions }) => {
  const { posts } = await effects.gql.queries.posts()
​
  state.posts = posts
  
  effects.gql.subscriptions.onPostAdded(actions.onPostAdded)
}
​
export const addPost = async ({ effects }, title) => {
  await effects.gql.mutations.createPost({ title })
}
​
export const onPostAdded = ({ state }, post) => {
  state.posts.push(post)
}
Cache
Now that we have the data from our query in the state, we can decide ourselves when we want this data to update. It could be related to moving back to a certain page, maybe you want to update the data in the background or maybe it is enough to just grab it once. You do not really think about it any differently here than with any other data fetching solution.
Optimistic updates
Again, since our data is just part of our state we are in complete control of optimistically adding new data. Let us create an optimistic post.
overmind/actions.js
export const getPosts = async ({ state, effects }) => {
  const { posts } = await effects.queries.posts()
​
  state.posts = posts
}
​
export const addPost = async ({ state, effects }, title) => {
  const optimisticId = String(Date.now())
​
  state.posts.push({
    id: optimisticId,
    title
  })
​
  const { id } = await effects.mutations.createPost({ title })
  const optimisticPost = state.posts.find(post => post.id === optimisticId)
​
  optimisticPost.id = id
}
Options
There are two points of options in the Graphql factory. The headers and the options.
The headers option is a function that runs on every request, meaning you can dynamically change the headers based on the state of the application.
overmind/onInitialize.js
export const onInitialize = ({ state, effects }) => {
  effects.gql.initialize({
    endpoint: 'http://some-endpoint.dev',
    // This runs on every request
    headers: () => ({
      authorization: `Bearer ${state.auth.token}`
    }),
    // The options are the options passed to GRAPHQL-REQUEST
    options: {
      credentials: 'include',
      mode: 'cors',
    },
  }, {
    endpoint: 'ws://some-endpoint.dev',
    // This runs on every connect
    params: () => ({
      token: state.auth.token
    })
  })
}
Custom subscription socket
If you want to define your own socket for connecting to subscriptions, a function can be used instead:
overmind/onInitialize.js
export const onInitialize = ({ effects }) => {
  effects.gql.initialize(
    {
      endpoint: 'http://some-endpoint.dev',
    }, 
    () => new Websocket('ws://some-other-endpoint.dev')
  )
}
Disposing subscriptions
You can dispose any subscriptions in any action. There are two ways to dispose:
overmind/actions.js
export const disposeSubscriptions = async ({ state, effects }) => {
  // Disposes all subscriptions on "onPostAdded"
  effects.gql.subscriptions.onPostAdded.dispose()
  // If the subscription takes a payload, you can dispose specific
  // subscriptions
  effects.gql.subscriptions.onPostChange.disposeWhere(
    data => data.id === state.currentPostId
  )
}
Typescript
There is only a single type exposed by the library, Query. It is used for queries, mutations and subscriptions.
overmind/queries.ts
import { Query, gql } from 'overmind-graphql'
// You will understand this very soon
import { Posts } from './graphql-types'
​
export const posts: Query<Posts> = gql`
  query Posts {
    posts {
      id
      title
    }
  }
`;
The first Query argument is the result of the query. There is also a second query argument which is the payload to the query, as seen here.
overmind/mutations.ts
import { Query, gql } from 'overmind-graphql'
// You will understand this very soon
import { CreatePost, CreatePostVariables } from './graphql-types'
​
export const createPost: Query<CreatePost, CreatePostVariables> = gql`
  mutation CreatePost($title: String!) {
    createPost(title: $title) {
      id
    }
  }
`
Generate typings
It is possible to generate all the typings for the queries and mutations. This is done by using the APOLLO project CLI. Install it with:
npm install apollo --save-dev
Now you can create a script in your package.json file that looks something like:
{
  "scripts": {
    "schema": "apollo schema:download --header='X-Hasura-Admin-Secret: password' --endpoint=http://some-endpoint.dev graphql-schema.json && apollo codegen:generate --localSchemaFile=graphql-schema.json --target=typescript --includes=src/overmind/**/*.ts --tagName=gql --no-addTypename --globalTypesFile=src/overmind/graphql-global-types.ts graphql-types"
  }
}
To update your types, simply run:
npm run schema
Apollo will look for queries defined with the gql template tag and automatically produce the typings. That means whenever you add, remove or update a query in your code you should run this script to update the typings. It also produces what is called graphql-global-types. These are types related to fields on your queries, which can be used in your state definition and/or actions.
Note that initially you have to define your queries without types and after running the script you can start typing them to get typing in your app and ensure that your app does not break when you change the queries either in the client or on the server
Optimize query
It is possible to transpile the queries from strings into code. This reduces the size of your bundle, though only noticeably if you have a lot of queries. This can be done with the BABEL-PLUGIN-GRAPHQL-TAG.