Why does my Firestore listener with offline persistence always read from the server?

Question

I am using Firebase JavaScript Modular Web Version 9 SDK with my Vue 3 / TypeScript app.

My understanding is that when using Firestore real-time listeners with offline persistence it should work like this:

1. When the listener is started the callback fires with data read from the local cache, and then immediately after it also tries to read from the server to make sure the local cache has up to date values. If the server data matches the local cache the callback listener should only fire once with data read from the local cache.
2. When data changes, the callback listener fires with data read from the server. It uses that data to update the local cache.
3. When data doesn't change, all subsequent calls to the listener trigger a callback with data read from the local cache.

But I have setup offline persistence, created a listener for my Firestore data, and monitored where the reads were coming from...

And in my app I see an initial read from the local cache (expected), and then a second immediate read from the server (unexpected). And after that all subsequent reads are coming from the server (also unexpected).

During this testing none of my data has changed. So I expected all reads from the callback listener to be coming from the local cache, not the server.

And actually the only time I see a read from the local cache is when the listener is first started, but this was to be expected.

What could be the problem?

PS To make those "subsequent calls" I am navigating to a different page of my SPA and then coming back to the page where my component lives to trigger it again.

src/composables/database.ts

export const useLoadWebsite = () => {
  const q = query(
    collection(db, 'websites'),
    where('userId', '==', 'NoLTI3rDlrZtzWCbsZpPVtPgzOE3')
  );
  const firestoreWebsite = ref<DocumentData>();
  onSnapshot(q, { includeMetadataChanges: true }, (querySnapshot) => {
    const source = querySnapshot.metadata.fromCache ? 'local cache' : 'server';
    console.log('Data came from ' + source);
    const colArray: DocumentData[] = [];
    querySnapshot.docs.forEach((doc) => {
      colArray.push({ ...doc.data(), id: doc.id });
    });
    firestoreWebsite.value = colArray[0];
  });
  return firestoreWebsite;
};

src/components/websiteUrl.vue

<template>
  <div v-if="website?.url">{{ website.url }}</div>
</template>

<script setup lang="ts">
import { useLoadWebsite } from '../composables/database';
const website = useLoadWebsite();
</script>

Answer 1

Nothing is wrong. What you're describing is working exactly the way I would expect.

Firestore local persistence is not meant to be a full replacement for the backend. By default, It's meant to be a temporary data source in the case that the backend is not available. If the backend is available, then the SDK will prefer to ensure that the client app is fully synchronized with it, and serve all updates from that backend as long as it's available.

If you want to force a query to use only the cache and not the backend, you can programmatically specify the cache as the source for that query .

If you don't want any updates at all from the server for whatever reason, then you can disable network access entirely.

See also:

• Firestore clients: To cache, or not to cache? (or both?)

Answer 2

I figured out why I was getting a result different than expected.

The culprit was { includeMetadataChanges: true } .

As explained here in the docs , that option will trigger a listener event for metadata changes.

So the listener callback was also triggering on each metadata change, instead of just data reads and writes, causing me to see strange results.

After removing that it started to work as expected, and I verified it by checking it against the Usage graphs in Firebase console which show the number of reads and snapshot listeners.

Here is the full code with that option removed:

export const useLoadWebsite = () => {
  const q = query(
    collection(db, 'websites'),
    where('userId', '==', 'NoLTI3rDlrZtzWCbsZpPVtPgzOE3')
  );
  const firestoreWebsite = ref<DocumentData>();
  onSnapshot(q, (querySnapshot) => {
    const source = querySnapshot.metadata.fromCache ? 'local cache' : 'server';
    console.log('Data came from ' + source);
    const colArray: DocumentData[] = [];
    querySnapshot.docs.forEach((doc) => {
      colArray.push({ ...doc.data(), id: doc.id });
    });
    firestoreWebsite.value = colArray[0];
  });
  return firestoreWebsite;
};