The Guild LogoThe Guild Monogram

Search docs

Search icon

Products by The Guild


Hive logoHive blurred logo


Schema Registry for your GraphQL Workflows

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