👉 Visit the DatoCMS homepage or see What is DatoCMS?
A lightweight, TypeScript-ready package that offers utilities to work with DatoCMS Real-time Updates API inside a browser.
npm install datocms-listen
Import subscribeToQuery from datocms-listen and use it inside your components like this:
import { subscribeToQuery } from "datocms-listen";
const unsubscribe = await subscribeToQuery({
query: `
query BlogPosts($first: IntType!) {
allBlogPosts(first: $first) {
title
nonExistingField
}
}
`,
variables: { first: 10 },
token: "YOUR_TOKEN",
includeDrafts: true,
onUpdate: (update) => {
// response is the GraphQL response
console.log(update.response.data);
},
onStatusChange: (status) => {
// status can be "connected", "connecting" or "closed"
console.log(status);
},
onChannelError: (error) => {
// error will be something like:
// {
// code: "INVALID_QUERY",
// message: "The query returned an erroneous response. Please consult the response details to understand the cause.",
// response: {
// errors: [
// {
// fields: ["query", "allBlogPosts", "nonExistingField"],
// locations: [{ column: 67, line: 1 }],
// message: "Field 'nonExistingField' doesn't exist on type 'BlogPostRecord'",
// },
// ],
// },
// }
console.error(error);
},
onError: (error) => {
// error will be
// {
// message: "ERROR MESSAGE"
// }
console.log(error.message);
},
onEvent: (event) => {
// event will be
// {
// status: "connected|connected|closed",
// channelUrl: "...",
// message: "MESSAGE",
// }
},
});| prop | type | required | description | default |
|---|---|---|---|---|
| query | string | TypedDocumentNode |
✅ | The GraphQL query to subscribe | |
| token | string | ✅ | DatoCMS API token to use | |
| onUpdate | function | ✅ | Callback function to receive query update events | |
| onChannelError | function | ❌ | Callback function to receive channelError events | |
| onStatusChange | function | ❌ | Callback function to receive status change events | |
| onError | function | ❌ | Callback function to receive error events | |
| onEvent | function | ❌ | Callback function to receive other events | |
| variables | Object | ❌ | GraphQL variables for the query | |
| includeDrafts | boolean | ❌ | If true, draft records will be returned | |
| excludeInvalid | boolean | ❌ | If true, invalid records will be filtered out | |
| environment | string | ❌ | The name of the DatoCMS environment where to perform the query (defaults to primary environment) | |
| contentLink | 'vercel-1' or undefined |
❌ | If true, embed metadata that enable Content Link | |
| baseEditingUrl | string | ❌ | The base URL of the DatoCMS project | |
| cacheTags | boolean | ❌ | If true, receive the Cache Tags associated with the query | |
| reconnectionPeriod | number | ❌ | In case of network errors, the period (in ms) to wait to reconnect | 1000 |
| fetcher | a fetch-like function | ❌ | The fetch function to use to perform the registration query | window.fetch |
| eventSourceClass | an EventSource-like class | ❌ | The EventSource class to use to open up the SSE connection | window.EventSource |
| baseUrl | string | ❌ | The base URL to use to perform the query | https://graphql-listen.datocms.com |
This function will be called everytime the channel sends an updated query result. The updateData argument has the following properties:
| prop | type | description |
|---|---|---|
| response | Object | The GraphQL updated response |
The status argument represents the state of the server-sent events connection. It can be one of the following:
connecting: the subscription channel is trying to connectconnected: the channel is open, we're receiving live updatesclosed: the channel has been permanently closed due to a fatal error (ie. an invalid query)
The errorData argument has the following properties:
| prop | type | description |
|---|---|---|
| code | string | The code of the error (ie. INVALID_QUERY) |
| message | string | An human friendly message explaining the error |
| response | Object | The raw response returned by the endpoint, if available |
This function is called when connection errors occur.
The error argument has the following properties:
| prop | type | description |
|---|---|---|
| message | string | An human friendly message explaining the error |
This function is called then other events occur.
The event argument has the following properties:
| prop | type | description |
|---|---|---|
| status | string | The current connection status (see above) |
| channelUrl | string | The current channel URL |
| message | string | An human friendly message explaining the event |
The function returns a Promise<() => void>. You can call the function to gracefully close the SSE channel.
DatoCMS is the REST & GraphQL Headless CMS for the modern web.
Trusted by over 25,000 enterprise businesses, agencies, and individuals across the world, DatoCMS users create online content at scale from a central hub and distribute it via API. We ❤️ our developers, content editors and marketers!
Why DatoCMS?
- API-First Architecture: Built for both REST and GraphQL, enabling flexible content delivery
- Just Enough Features: We believe in keeping things simple, and giving you the right feature-set tools to get the job done
- Developer Experience: First-class TypeScript support with powerful developer tools
Getting Started:
- ⚡️ Create Free Account - Get started with DatoCMS in minutes
- 🔖 Documentation - Comprehensive guides and API references
- ⚙️ Community Support - Get help from our team and community
- 🆕 Changelog - Latest features and improvements
Official Libraries:
- Content Delivery Client - TypeScript GraphQL client for content fetching
- REST API Clients - Node.js/Browser clients for content management
- CLI Tools - Command-line utilities for schema migrations (includes Contentful and WordPress importers)
Official Framework Integrations
Helpers to manage SEO, images, video and Structured Text coming from your DatoCMS projects:
Additional Resources:
- Plugin Examples - Example plugins we've made that extend the editor/admin dashboard
- Starter Projects - Example website implementations for popular frameworks
- All Public Repositories