Skip to main content
ReadMeter

Getting Started

ReadMeter is a standalone product: add it to your app to see Firestore reads live during development.

Installation

Choose one of these options:

Option 1: npm (recommended)

npm install -D readmeter

Then run npx readmeter add in your project folder. No global install needed.

Option 2: curl install

curl -fsSL https://readmeter.dev/install | bash

When prompted, paste your license key from your intro email. One license is valid for one device only. Use readmeter deactivate before reinstalling if you see "License is already in use".

Standalone: use in your app

After install, the widget is in ~/.readmeter/standalone/:

  1. Copy readmeter-widget.js into your project (e.g. public/ or static/).
  2. In your HTML, add <script src="/readmeter-widget.js"></script> before your Firebase/Firestore script.
  3. Run your app on localhost. A floating "X reads" badge appears in the bottom-right; click to expand.

Works with any stack (React, Vue, plain JS). Only runs in development; safe to ship.

Modular SDK (v9+)

If you use the Firebase modular SDK (import { getDoc, getDocs } from 'firebase/firestore'), the widget cannot patch Firestore automatically. Use the wrapper instead. When you run readmeter add, the installer can automatically switch your imports to the wrapper — no manual changes needed in most cases.

  1. Copy readmeter-firestore.js into your project (e.g. lib/).
  2. Load readmeter-widget.js first (script tag).
  3. Change your imports from firebase/firestore to the wrapper (or let the installer do it automatically):
// Before
import { getDoc, getDocs, onSnapshot } from 'firebase/firestore'

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

The wrapper re-exports all Firestore APIs; only getDoc, getDocs, and onSnapshot are wrapped to count reads.

Already have a read tracker?

If you manually track Firestore reads (e.g. firestoreReadTracker.track(feature, collection, count)), bridge to ReadMeter: in your track() function, also call:

window.ReadMeter?.recordRead({ reads: readCount, collection, type: 'getDocs', caller: featureName })

Fix imports (if you see 0 reads)

If the widget shows 0 reads after adding ReadMeter, run readmeter fix-imports in your project folder to automatically switch Firestore imports to the wrapper. Use readmeter fix-imports --dry-run to preview changes first.

Build-time plugin (zero manual imports)

For Vite or Next.js/Webpack, use a build-time plugin to rewrite firebase/firestore imports automatically. No codemod step needed.

Vite

npm install -D vite-plugin-readmeter

// vite.config.ts
import readmeter from 'vite-plugin-readmeter'
export default defineConfig({
  plugins: [readmeter({ wrapperPath: '@/lib/readmeter-firestore' })],
})

Next.js / Webpack

npm install -D readmeter-loader

// next.config.js
const readmeterLoader = require('readmeter-loader')
module.exports = {
  webpack: (config) => {
    config.module.rules.push({
      test: /\.(ts|tsx|js|jsx|mjs|cjs)$/,
      enforce: 'pre',
      use: [{ loader: readmeterLoader, options: { wrapperPath: '@/lib/readmeter-firestore' } }],
    })
    return config
  },
}

CI integration

Fail CI when read count exceeds a threshold. Catch regressions before production. Install Playwright: npm install -D playwright && npx playwright install chromium

readmeter check --max-reads 50 --url http://localhost:3000

Ensure your app is running at the URL. For production builds, use ?readmeter=1 to enable the widget. Add to GitHub Actions or your CI pipeline.

Optional readmeter.config.js in project root:

module.exports = { check: { url: 'http://localhost:3000', maxReads: 50 } }

Editor support

Install the ReadMeter VS Code extension for a code action to switch firebase/firestore imports to the ReadMeter wrapper. Place your cursor on an import line and use the lightbulb (Quick Fix) or right-click → "Switch to ReadMeter wrapper".

Alert thresholds

Get a console warning and optional toast when reads exceed a threshold. Configure via:

  • Widget UI: Expand the panel and set "Alert threshold" (stored in localStorage)
  • URL: ?readmeter_alert=50
  • Config: window.ReadMeter.config = { alertThreshold: 50 }

Alerts are debounced (once per page load) to avoid spam.

Add to project (automated)

From your project folder, run:

readmeter add

This detects your framework (Next.js, Nuxt, Vite, React, etc.), copies the widget, and wires it up. For Firebase projects, it also copies the modular SDK wrapper and automatically rewrites Firestore imports to use the wrapper. Use readmeter add --no-codemod to skip automatic import changes.

Next steps