Work in progress, expect bugs and missing features.

A library to use Cloud Firestore inside Cloudflare Workers.

npm install fireworkers
# OR
yarn add fireworkers
# OR
pnpm add fireworkers

import * as Firestore from 'fireworkers';

const db = await Firestore.init({
  uid: 'user1234',
  project_id: 'my-project',
  client_email: '[email protected]',
  private_key: '-----BEGIN PRIVATE KEY-----...',
  private_key_id: 'OdxPtETQKf1o2YvMTTLBzsJ3OYdiPcx7NlFE2ZAk',
  claims: {
    premium_account: true,
  },
});

const todo = await Firestore.get(db, 'todos', 'aDyjLiTViX1G7HyF74Ax');

Returns a DB instance. Requires a service account.

Type: string

The unique identifier of the signed-in user, between 1-36 characters long.

Type: string

The project_id defined in the serviceAccountKey.json.

Type: string

The client_email defined in the serviceAccountKey.json.

Type: string

The private_key defined in the serviceAccountKey.json.

Type: string

The private_key_id defined in the serviceAccountKey.json.

Type: Record<string, string | number | boolean> | undefined

Optional custom claims to include in the Security Rules auth / request.auth variables.

const db = await Firestore.init({
  uid: 'user1234',
  project_id: 'my-project',
  client_email: '[email protected]',
  private_key: '-----BEGIN PRIVATE KEY-----...',
  private_key_id: 'OdxPtETQKf1o2YvMTTLBzsJ3OYdiPcx7NlFE2ZAk',
  claims: {
    premium_account: true,
  },
});

Gets a single document.

Type: DB

The DB instance.

Type: string

The document path, usually defined as {collection_id}/{document_id}.

Allows nested documents like {collection_id}/{document_id}/{nested_collection_id}/{nested_document_id}.

It can either be defined using a single string like:

const todo = await Firestore.get(db, 'todos/aDyjLiTViX1G7HyF74Ax');

Or multiple params like:

const todo = await Firestore.get(db, 'todos', 'aDyjLiTViX1G7HyF74Ax');

Creates a new document.

Type: DB

The DB instance.

Type: string

The collection path, usually defined as {collection_id}.

Allows nested collections like {collection_id}/{document_id}/{nested_collection_id}.

Nested collections can either be defined using a single string like todo/aDyjLiTViX1G7HyF74Ax/tasks or by passing multiple params like 'todo', 'aDyjLiTViX1G7HyF74Ax', 'tasks'.

Type: Record<string, any>

The document fields.

const newTodo = await Firestore.create(db, 'todos', {
  title: 'Win the lottery',
  completed: false,
});

Updates fields in a document. The update will fail if applied to a document that does not exist.

Implements the same functionality as Firestore's updateDoc.

Type: DB

The DB instance.

Type: string

The document path, defined like in get.

Type: Record<string, any>

The fields to update.

const updatedTodo = await Firestore.update(db, 'todos', 'aDyjLiTViX1G7HyF74Ax', {
  completed: false,
});

Writes to a document. If the document does not yet exist, it will be created. If you provide merge, the provided data can be merged into an existing document.

Implements the same functionality as Firestore's setDoc.

Type: DB

The DB instance.

Type: string

The document path, defined like in get.

Type: Record<string, any>

The fields to update.

Type: boolean

If set to true, the provided data will be merged into an existing document instead of overwriting.

const updatedTodo = await Firestore.set(
  db,
  'todos',
  'aDyjLiTViX1G7HyF74Ax',
  { completed: false },
  { merge: true }
);

Removes a document.

Type: DB

The DB instance.

Type: string

The document path, defined like in get.

const todo = await Firestore.remove(db, 'todos', 'aDyjLiTViX1G7HyF74Ax');

Runs a query.

Type: DB

The DB instance.

Type: StructuredQuery

A StructuredQuery object.

const todos = await Firestore.query(db, {
  from: [{ collectionId: 'todos' }],

  where: {
    fieldFilter: {
      field: {
        fieldPath: 'owner',
      },
      op: 'EQUAL',
      value: {
        stringValue: 'user1234',
      },
    },
  },
});

This library has first-class TypeScript support.

To define a document interface, you can pass a generic like so:

type Todo = {
  title: string;
  completed: boolean;
};

const todo = await Firestore.get<Todo>(db, 'todos', 'aDyjLiTViX1G7HyF74Ax');