The Guild LogoThe Guild Monogram
Envelop Logo


Get Started

Plugin Hub > useLiveQuery

yarn add @envelop/live-query


The easiest way of adding live queries to your GraphQL server!

Push new data to your clients automatically once the data selected by a GraphQL operation becomes stale by annotating your query operation with the @live directive.

query UserProfile @live { me { id login bio } }

The invalidation mechanism is based on GraphQL ID fields and schema coordinates. Once a query operation has been invalidated, the query is re-executed and the result is pushed to the client.


yarn add @envelop/live-query @n1ru4l/in-memory-live-query-store

Usage Example#

makeExecutableSchema from graphql-tools#

import { envelop, useSchema, useExtendContext } from '@envelop/core' import { useLiveQuery } from '@envelop/live-query' import { InMemoryLiveQueryStore } from '@n1ru4l/in-memory-live-query-store' import { makeExecutableSchema } from '@graphql-tools/schema' const schema = makeExecutableSchema({ typeDefs: [ /* GraphQL */ ` type Query { greetings: [String!] } `, GraphQLLiveDirectiveSDL ], resolvers: { Query: { greetings: (_, __, context) => context.greetings } } }) const liveQueryStore = new InMemoryLiveQueryStore() const greetings = ['Hello', 'Hi', 'Ay', 'Sup'] // Shuffle greetings and invalidate queries selecting Query.greetings every second. setInterval(() => { const firstElement = greetings.pop() greetings.unshift(firstElement) liveQueryStore.invalidate('Query.greetings') }, 1000) const getEnveloped = envelop({ plugins: [ useSchema(schema), useLiveQuery({ liveQueryStore }), useExtendContext(() => ({ greetings })) /* other plugins */ ] })

GraphQLSchema from graphql#

You need to pass the GraphQLLiveDirective to the list of directives:

import { GraphQLSchema } from 'graphql' import { GraphQLLiveDirective } from '@envelop/live-query' const schema = new GraphQLSchema({ directives: [...specifiedDirectives, GraphQLLiveDirective] })

Further information#

This plugin requires you to use a graphql transports that supports usage of the @defer and @stream directives, as it is built upon the same concepts (return an AsyncIterable from execute).

The following transports have been successfully tested:

@n1ru4l/socket-io-graphql-serverGraphQL over (WebSocket/HTTP Long Polling)npm versionnpm downloads
graphql-helixGraphQL over HTTP (IncrementalDelivery/SSE)npm versionnpm downloads
graphql-wsGraphQL over WebSocket (WebSocket)npm versionnpm downloads
graphql-sseGraphQL over Server-Sent Events (SSE)npm versionnpm downloads

For more details check out the live query repository or the introduction blog post.

There is also a full schema example available.

Plugin Details

Edit on GitHub