Troubleshooting

Widget visible but shows 0 reads

The widget appears in the corner but the read count stays at zero. This usually happens when your app uses the Firebase modular SDK (v9+) and does not load the compat Firestore API in the browser.

Why it happens

ReadMeter's widget patches the compat Firestore API (window.firebase.firestore). If your app uses only the modular SDK (import { getDoc, getDocs } from 'firebase/firestore'), the compat API is never loaded, so the patch never runs and ReadMeter.recordRead() is never called.

Solutions

1. Run fix-imports — From your project folder, run readmeter fix-imports to automatically switch your Firestore imports to the wrapper. Then reload your app.
2. Use the ReadMeter Firestore wrapper manually — Change your imports from firebase/firestore to the wrapper:

   // Before
   import { getDoc, getDocs, onSnapshot } from 'firebase/firestore'
   
   // After
   import { getDoc, getDocs, onSnapshot } from './lib/readmeter-firestore'

   The wrapper re-exports everything; only getDoc, getDocs, and onSnapshot are wrapped to call ReadMeter.recordRead().
3. Bridge from an existing tracker — If you already track reads (e.g. a custom firestoreReadTracker.track()), add a one-liner to feed ReadMeter:

   // In your track() function, after updating your own state:
   window.ReadMeter?.recordRead({ reads: readCount, collection, type: 'getDocs', caller: featureName })

recordRead parameter contract

When bridging from your own tracker or calling ReadMeter.recordRead() manually, use this shape:

{
  reads: number,      // required — number of document reads
  collection: string, // required — collection name
  type?: string,      // optional — e.g. 'getDoc', 'getDocs', 'onSnapshot'
  caller?: string     // optional — e.g. feature name or 'file.tsx:42'
}

Build tools (Next.js, Vite, Webpack)

To avoid changing imports in every file, you can alias firebase/firestore to the ReadMeter wrapper. Your existing import ... from 'firebase/firestore' will then resolve to the wrapper at build time.

Next.js (next.config.js):

const path = require('path')

module.exports = {
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      'firebase/firestore': path.resolve(__dirname, 'lib/readmeter-firestore.js'),
    }
    return config
  },
}

Vite (vite.config.js):

resolve: {
  alias: {
    'firebase/firestore': path.resolve(__dirname, 'lib/readmeter-firestore.js')
  }
}

Webpack:

resolve: {
  alias: {
    'firebase/firestore': path.resolve(__dirname, 'lib/readmeter-firestore.js')
  }
}

Server vs client reads

ReadMeter tracks client-side reads only. Server-side reads (SSR, SSG, API routes, server components) are not counted because the widget runs in the browser. If your Next.js app fetches Firestore data in Server Components or getServerSideProps, those reads will not appear in the widget.

Next steps

• Getting Started
• API Reference