Getting Started

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

Want to try it first? Use the Learning App — real Firestore reads on a read-only demo project, no install required.

Installation

Choose one of these options:

Option 1: npm (recommended)

npm install -D readmeter
npx readmeter init --yes

One command wires the widget, Next.js loader (or Vite plugin), and Turbopack-safe import rewrites so tracking works without a second step.

Option 2: curl install

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

Non-interactive install + add in the current folder. Pass your license key as the first arg if needed: bash -s -- YOUR_KEY --yes.

Optional flags: --budget 50, --ci, --force-prod (ship widget to production; default is dev-only), --dry-run. Rollback: readmeter remove.

What ReadMeter measures

ReadMeter reports estimated document reads. It is not a full Firebase bill calculator.

Client: browser modular getDoc / getDocs / initial onSnapshot (corner widget)
Admin/server: after you wrap instrumentAdminFirestore(getFirestore()), Node .get() / getAll() in this process (dev: GET /api/readmeter-admin on Next.js)
Still not counted: Cloud Functions outside this Node process, other Firebase products, aggregation queries billed differently
Billing notes: missing docs still bill a getDoc (we count 1); empty queries bill 0 docs; client onSnapshot counts the initial snapshot only

If init detects an Admin SDK–heavy app, it vendors readmeter-admin-firestore and (on Next) a stats route. You still need one wrap around your Admin getFirestore() export.

Admin / server metering

For apps that read Firestore with firebase-admin (API routes, Server Components, scripts), init adds the Admin module. Wrap once:

import { getFirestore } from 'firebase-admin/firestore'
import { instrumentAdminFirestore } from '@/lib/readmeter-admin-firestore'

export const db = instrumentAdminFirestore(getFirestore())

After hitting server code that reads Firestore, open /api/readmeter-admin in development (or call getAdminReadStats()). Set READMETER_ADMIN_LOG=1 for console logs. The browser widget remains client-only.

Standalone: use in your app

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

Copy readmeter-widget.js into your project (e.g. public/ or static/).
In your HTML, add <script src="/readmeter-widget.js"></script> before your Firebase/Firestore script.
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.

Risk labels on the expanded panel are based on document reads for the current route in this dev session: Safe up to 30 reads, Scales with traffic between 31 and 100, and High risk above 100. Hover the badge for a short explanation. Costs shown are rough projections only — production caching, rules, and traffic differ.

Press Escape to leave History view or collapse the widget.

Modular SDK (v9+)

With the Firebase modular SDK (firebase/firestore), readmeter init --yes vendors a webpack loader into your Next.js config (no recursive resolve.alias), rewrites existing imports for Turbopack using your @/ alias when present, copies a .ts wrapper when tsconfig.json exists, and wires the widget dev-only by default. You should not need a second CLI command for the client happy path.

Already have a read tracker?

Bridge to ReadMeter from your tracker:

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

Recovery: fix-imports

If the widget shows 0 reads (unusual after a successful init), run readmeter fix-imports --yes. Prefer re-running readmeter init --yes first.

Advanced: published build plugins

Init vendors a local loader/plugin automatically. The npm packages below are optional if you prefer a dependency instead of vendored files.

Vite

npm install -D vite-plugin-readmeter

Next.js / Webpack

npm install -D readmeter-loader

Do not blanket-alias firebase/firestore to the wrapper — the wrapper imports that module and a resolve.alias would recurse. Use the loader/plugin (or the files init vendors).

CI integration (optional)

Add a budget during init: readmeter init --yes --budget 50 --ci, or run checks manually:

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

Requires Playwright. Use ?readmeter=1 to enable the widget in production builds.

Editor support

Install the ReadMeter VS Code extension for a code action to switch firebase/firestoreimports 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.