# datocms-listen
Latest version **1.0.4** (published 2026-08-31) · MIT license · 0 weekly downloads
## Install
```sh
npm install datocms-listen
pnpm add datocms-listen
yarn add datocms-listen
bun add datocms-listen
```
## Health
**Score 70/100 (B)** — status: active.
Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.
Warnings: low downloads.
## Facts
| | |
|---|---|
| Version | 1.0.4 |
| Published | 2026-08-31 |
| First published | 2020-11-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 132.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 10 |
| Author | Stefano Verna |
| Maintainers | marcelofinamorvieira, stefanoverna, delphaber, mat_jack1, souljuse, sistrall_, datoroger |
## Links
- npm: https://www.npmjs.com/package/datocms-listen
- Repository: https://github.com/datocms/datocms-listen
- Issues: https://github.com/datocms/datocms-listen/issues
- npm.io page: https://npm.io/package/datocms-listen
## Dependencies (2)
- [@0no-co/graphql.web](https://npm.io/package/@0no-co/graphql.web.md) ^1.0.1
- [@datocms/cda-client](https://npm.io/package/@datocms/cda-client.md) ^0.3.1
## Recent versions
- 1.0.4 (latest) — 2026-08-31
- 1.0.3 — 2026-08-31
- 1.0.2 — 2025-01-17
- 1.0.1 — 2024-08-13
- 1.0.0 — 2024-07-25
- 0.1.15 — 2023-04-27
- 0.1.14 — 2022-11-09
- 0.1.13 — 2022-11-09
- 0.1.12 — 2022-11-09
- 0.1.10 — 2022-09-14
- 0.1.9 — 2022-06-10
- 0.1.8 — 2022-03-25
- 0.1.7 — 2021-12-27
- 0.1.6 — 2021-10-21
- 0.1.5 — 2021-10-21
- … 3 more at https://npm.io/package/datocms-listen/versions
## README
👉 [Visit the DatoCMS homepage](https://www.datocms.com) or see [What is DatoCMS?](#what-is-datocms)
---
# datocms-listen
  [](https://travis-ci.org/datocms/datocms-listen)
A lightweight, TypeScript-ready package that offers utilities to work with DatoCMS [Real-time Updates API](https://www.datocms.com/docs/real-time-updates-api) inside a browser.
## Installation
```
npm install datocms-listen
```
## Example
Import `subscribeToQuery` from `datocms-listen` and use it inside your components like this:
```js
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 is a MessageEvent, the actual error is in error.data
console.log(error.data);
},
onEvent: (event) => {
// event will be
// {
// status: "connecting|connected|closed",
// channelUrl: "...",
// message: "MESSAGE",
// response: Response
// }
},
});
```
## Initialization options
| prop | type | required | description | default |
| ------------------ | ------------------------------------------------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------ |
| query | string \| [`TypedDocumentNode`](https://github.com/dotansimha/graphql-typed-document-node) | :white_check_mark: | The GraphQL query to subscribe | |
| token | string | :white_check_mark: | DatoCMS API token to use | |
| onUpdate | function | :white_check_mark: | Callback function to receive query update events | |
| onChannelError | function | :x: | Callback function to receive channelError events | |
| onStatusChange | function | :x: | Callback function to receive status change events | |
| onError | function | :x: | Callback function to receive error events | |
| onEvent | function | :x: | Callback function to receive other events | |
| variables | Object | :x: | GraphQL variables for the query | |
| includeDrafts | boolean | :x: | If true, draft records will be returned | |
| excludeInvalid | boolean | :x: | If true, invalid records will be filtered out | |
| environment | string | :x: | The name of the DatoCMS environment where to perform the query (defaults to primary environment) | |
| contentLink | `'vercel-1'` or `undefined` | :x: | If true, embed metadata that enable Content Link | |
| baseEditingUrl | string | :x: | The base URL of the DatoCMS project | |
| cacheTags | boolean | :x: | If true, receive the Cache Tags associated with the query | |
| reconnectionPeriod | number | :x: | In case of network errors, the period (in ms) to wait to reconnect | 1000 |
| fetcher | a [fetch-like function](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) | :x: | The fetch function to use to perform the registration query | window.fetch |
| eventSourceClass | an [EventSource-like](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) class | :x: | The EventSource class to use to open up the SSE connection | window.EventSource |
| baseUrl | string | :x: | The base URL to use to perform the query | `https://graphql-listen.datocms.com` |
## Events
### `onUpdate(update: UpdateData)`
This function will be called every time the channel sends an updated query result. The `updateData` argument has the following properties:
| prop | type | description |
| -------- | ------ | ---------------------------- |
| response | Object | The GraphQL updated response |
### `onStatusChange(status: ConnectionStatus)`
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 connect
- `connected`: the channel is open, we're receiving live updates
- `closed`: the channel has been permanently closed due to a fatal error (i.e. an invalid query)
### `onChannelError(errorData: ChannelErrorData)`
The `errorData` argument has the following properties:
| prop | type | description |
| -------- | ------- | ------------------------------------------------------------------ |
| code | string | The code of the error (i.e. `INVALID_QUERY`) |
| message | string | A human-friendly message explaining the error |
| fatal | boolean | If true, the channel has been closed and will not reconnect |
| response | Object | The raw response returned by the endpoint, if available (optional) |
### `onError(error: MessageEvent)`
This function is called when connection errors occur (network errors, SSE errors).
The `error` argument is a standard [MessageEvent](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent). The actual error object is available in `error.data`.
### `onEvent(event: EventData)`
This function is called when 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 | A human-friendly message explaining the event |
| response | Response | The HTTP response from the registration request |
## Return value
The function returns a `Promise<() => void>`. You can call the function to gracefully close the SSE channel.
## Releasing (maintainers)
Every user-visible change needs a changeset: run `npx changeset` from the repo
root in the same PR, pick the bump level (`patch` is for bug fixes only, new API
surface is `minor`) and commit the file it writes under `.changeset/`. That is
where the changelog entry comes from, and it is where the bump level is decided
— not on release day. See [`.changeset/README.md`](.changeset/README.md).
To release, from an up-to-date, clean `main`, run `npm run release`. It
builds and tests, applies the pending changesets — bumping the version and
writing `CHANGELOG.md` — publishes to npm, and only then tags `vX.Y.Z`, pushes,
and creates a GitHub release whose notes come straight from that changelog
entry. An interrupted release is resumed by re-running it, never undone. Use
`npm run release:next` for a prerelease under the `next` dist-tag.
The script is
[`@datocms/release-toolchain`](https://github.com/datocms/release-toolchain),
shared with every other DatoCMS repository and pinned here by tag.
---
## Trying a change before it's released
Every push to a branch here publishes a preview of the package, which you can
install anywhere — no npm release, no `npm link`:
```
npm i https://pkg.pr.new/datocms/datocms-listen@
```
The exact URL shows up in the commit's check run on GitHub, and in a comment on
the pull request once there is one. This is the supported way to try a change
inside a site that lives in another repository, or to hand a fix to whoever
reported it before it is released.
Previews are throwaway: they are never published to npm, and the URL stops
resolving after a while. Never commit one to a `package.json` that ships.
# What is DatoCMS?
[DatoCMS](https://www.datocms.com/) is Headless CMS for the modern web. Trusted by 25,000+ businesses, agencies, and individuals, it gives your team one place to manage content and ship it to any website, app, or device via API.
**New here?** Start with [Create free account](https://dashboard.datocms.com/signup) and the [Documentation](https://www.datocms.com/docs). Stuck? Ask the [Community](https://community.datocms.com/). Curious what's new? [Product Updates](https://www.datocms.com/product-updates).
**Building with AI:** [Agent Skills](https://www.datocms.com/docs/agent-skills) turn coding assistants (Claude Code, Cursor) into expert DatoCMS developers, with full read/write via the auto-installed CLI. No local terminal? Use the [MCP Server](https://www.datocms.com/docs/mcp-server) instead.
**Talking to DatoCMS from code:**
- [Content Delivery API](https://www.datocms.com/docs/content-delivery-api) (CDA) — the fast, read-only GraphQL API your website/app uses to **fetch** published content.
- [Content Management API](https://www.datocms.com/docs/content-management-api) (CMA) — the REST API for **creating and updating** content, models, and project settings (think scripts, migrations, integrations).
- [CLI](https://www.datocms.com/docs/scripting-migrations/installing-the-cli) — terminal tool for schema migrations and importing from Contentful/WordPress.
**Framework guides:** end-to-end recipes for fetching content, rendering Structured Text, optimizing images/video, handling SEO, and setting up live preview with visual editing in [Next.js](https://www.datocms.com/docs/next-js), [Nuxt](https://www.datocms.com/docs/nuxt), [Svelte](https://www.datocms.com/docs/svelte), and [Astro](https://www.datocms.com/docs/astro).
**Want a head start?** Browse our [starter projects](https://www.datocms.com/marketplace/starters) — ready-to-deploy example sites for popular frameworks.
---
_Source: https://npm.io/package/datocms-listen · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._