# graphql-firebase-subscriptions

> Broadcast graphql messages via firebase realtime database, optional local cache for performance

Latest version **3.2.0** (published 2025-12-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install graphql-firebase-subscriptions
pnpm add graphql-firebase-subscriptions
yarn add graphql-firebase-subscriptions
bun add graphql-firebase-subscriptions
```

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.2.0 |
| Published | 2025-12-09 |
| First published | 2022-01-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 27.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 7 |
| Author | Svante Bengtson |
| Maintainers | swantzter |
| Keywords | apollo, graphql, firebase |

## Links

- npm: https://www.npmjs.com/package/graphql-firebase-subscriptions
- Repository: https://github.com/swantzter/graphql-firebase-subscriptions
- Homepage: https://github.com/swantzter/graphql-firebase-subscriptions#readme
- Issues: https://github.com/swantzter/graphql-firebase-subscriptions/issues
- npm.io page: https://npm.io/package/graphql-firebase-subscriptions

## Dependencies (1)

- [lru-cache](https://npm.io/package/lru-cache.md) ^11.2.4

## Alternatives

- [apollo-link-http-common](https://npm.io/package/apollo-link-http-common.md) — 879.0K weekly downloads
- [react-relay](https://npm.io/package/react-relay.md) — 336.8K weekly downloads
- [relay-test-utils](https://npm.io/package/relay-test-utils.md) — 181.6K weekly downloads
- [@vendure/core](https://npm.io/package/@vendure/core.md) — 14.8K weekly downloads
- [@pnpm/deps.graph-sequencer](https://npm.io/package/@pnpm/deps.graph-sequencer.md) — 13.4K weekly downloads

## Recent versions

- 3.2.0 (latest) — 2025-12-09
- 3.1.1 — 2025-12-09
- 3.1.0 — 2025-12-09
- 3.0.0 — 2025-06-15
- 2.5.0 — 2024-03-17
- 2.4.0 — 2023-07-21
- 2.3.0 — 2022-11-23
- 2.2.0 — 2022-07-12
- 2.1.1 — 2022-03-22
- 2.1.0 — 2022-02-28
- 2.0.0 — 2022-01-26
- 1.0.0 — 2022-01-17

## README

# GraphQL Subscriptions through Firebase Realtime Database

[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
[![QA](https://github.com/swantzter/graphql-firebase-subscriptions/actions/workflows/qa.yml/badge.svg)](https://github.com/swantzter/graphql-firebase-subscriptions/actions/workflows/qa.yml)
[![Publish to NPM and GCR](https://github.com/swantzter/graphql-firebase-subscriptions/actions/workflows/publish.yml/badge.svg)](https://github.com/swantzter/graphql-firebase-subscriptions/actions/workflows/publish.yml)
[![codecov](https://codecov.io/gh/swantzter/graphql-firebase-subscriptions/branch/main/graph/badge.svg)](https://codecov.io/gh/swantzter/graphql-firebase-subscriptions)

This is a GraphQL Subscriptions implementation that uses Firebase Realtime
Database as a message broker.

## Comparison

Depending on your use-case this may or may not be the tool for you, this
implementation is *not* meant as a way to listen to state updates on persisted
data, for that you should probably look at
[graphql-firestore-subscriptions][graphql-firestore-subscriptions].
This implementation is closer to an alternative to [Google PubSub][pubsub].
Now you may wonder, "why not use PuSub then?" well, basically I had concerns
that the PubSub documentation stated the performance on low message volumes
might not be great on PubSub since the priority was low latency at high load,
some graphs I saw showed seconds of latency for the types of volumes I was
looking at, whereas I've experienced a more consistent performance from RTDB,
but it doesn't go lower with scale like PubSub does. For using PubSub, there's
[graphql-google-pubsub][graphql-google-pubsub].

Now Firebase RTDB isn't without latency, not at all! And to alleviate this,
this library also provides an optional "local cache", this is really useful
if you're running on something like Google Cloud Run where you have multiple
instances serving requests. Turning this on will make the library work on an
"at-least-once" delivery principle. If something happens (most likely a
mutation) on the same instance a subscriber is connected to it will use an
internal in-memory EventEmitter and "instantly" forward the message. It will
also publish the message to Firestore RTDB and keep the node ID in a
short-lived local cache, when the message later arrives, and assuming its ID
hasn't expired from the cache, it will simply be ignored and not re-emitted
to subscribers connected to the instance that originally received the message.

[graphql-firestore-subscriptions]: https://github.com/m19c/graphql-firestore-subscriptions
[graphql-google-pubsub]: https://github.com/axelspringer/graphql-google-pubsub
[pubsub]: https://cloud.google.com/pubsub

## Usage

By default, the ref `/graphql-firebase-subscriptions` in your database will be
used as the root for messages.

```typescript
import { PubSub } from 'graphql-firebase-subscriptions'

enum Topic {
  NEW_COMMENT = 'new-comment'
}

const pubSub = new PubSub()

const Resolvers = {
  Subscription: {
    newComment: {
      subscribe: () => pubSub.asyncIterator(Topic.NEW_COMMENT)
    }
  },
  Mutation: {
    async addComment (_, args, ctx) {
      const comment = await ctx.dataSources.comments.createOne(args.postId, args.comment)
      await pubSub.publish(Topic.NEW_COMMENT, { postId: args.postId, commentId: comment.id })

      return comment
    }
  }
}
```

### Local Cache

Enabling the local cache for speed up is as simple as a boolean

```typescript
import { PubSub } from 'graphql-firebase-subscriptions'

const pubSub = new PubSub({ localCache: true })
```

### Only New

This flag allows receiving only messages which were published after client
subscription to some topic. Default behaviour is to receive all messages which
were published and not deleted (see Cleanup section).

```typescript
import { PubSub } from 'graphql-firebase-subscriptions'

const pubSub = new PubSub({ onlyNew: true })
```

When creating an asyncIterator you can override this option

```typescript
import { PubSub } from 'graphql-firebase-subscriptions'

const pubSub = new PubSub({ onlyNew: false })

const iterator = pubSub.asyncIterator(['TOPIC'], { onlyNew: true })
```

### Alternative base ref

You can use an alternative base ref for the message brokerage, useful if you
want separate instances with the same topics.

```typescript
import { PubSub } from 'graphql-firebase-subscriptions'
import { getDatabase } from 'firebase-admin/database'

const pubSub = new PubSub({
  ref: getDatabase().ref('/path/to/base/ref')
})
```

## Cleanup

This library requires you to clean up old messages, else it will just keep
adding messages to the topics forever. This could slow down message delivery,
and it'll waste storage and cost.

To help with this task, the library provides a Firebase Function that
works on a Google Cloud Scheduler Trigger. Note that per Firebase's own
[documentation][cloud-fn-schedule] a cloud scheduler job costs about
USD 0.10 per month and requires you to be on the Blaze plan for firebase.

[cloud-fn-schedule]: https://firebase.google.com/docs/functions/schedule-functions

To use it, just generate a handler and re-export it

```typescript
import getDeletionRoutineFunction from 'graphql-firebase-subscriptions/firebase-functions'

enum Topics {
  NEW_COMMENT = 'new-comment'
}

export const pubSubDeletionRoutine = getDeletionRoutineFunction({
  topics: Topics,

  // -------OPTIONAL-------
  // You can overwrite the base ref, if you've done so when using the PubSub
  ref: getDatabase.ref('/graphql-firebase-subscriptions'),
  // you can override the schedule for the function, by default it runs every
  // 10 minutes
  schedule: 'every 10 minutes',
  // and you can override the maximum time a message should be stored,
  // the default is to delete messages older than 10 minutes
  maxAge: 600_000
})
```

---
_Source: https://npm.io/package/graphql-firebase-subscriptions · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._