Getting Started

Installation

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

Optional flags: --budget 50, --ci, --force-prod (ship widget to production; default is dev-only), --no-agent-skill (skip the Claude Code / Cursor skill), --dry-run. Rollback: readmeter remove.

What ReadMeter measures

ReadMeter reports estimated document reads, and since 1.4 the writes and deletes next to them. It is not a full Firebase bill calculator.

• Client: browser modular getDoc / getDocs / initial onSnapshot reads, plus setDoc / addDoc / updateDoc / deleteDoc, writeBatch and runTransaction writes (corner widget)
• Admin/server: after you wrap instrumentAdminFirestore(getFirestore()), Node .get() / getAll() reads and set() / update() / delete(), batches, transactions and bulkWriter() writes 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 1 read (we count 1); client onSnapshot counts the initial snapshot only; writes and deletes are counted apart (Firestore prices them differently), one per document, once the write succeeds

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/:

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.

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 only the billed calls (getDoc / getDocs / onSnapshot and the other reads, plus the write functions) onto a thin wrap (Turbopack-safe — no export * of the Firestore barrel), 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.

import { getDoc, getDocs, onSnapshot } from '@/lib/readmeter-firestore'
import { collection, doc, query, where } from 'firebase/firestore'

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: build loaders

Init vendors a local Next.js/Webpack loader or Vite plugin into your project automatically, so there is nothing extra to install.

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).

Audit the whole app with your AI agent

With your dev server running, readmeter audit loads every route, ranks what to fix across all of them and writes .readmeter/FIX_PROMPT.md for your coding agent. After the fixes, readmeter audit --after measures again and writes .readmeter/COMPARE.md. It needs Playwright in your project (npm install -D playwright).

readmeter add also installs a ReadMeter skill for Claude Code (.claude/skills/readmeter-audit/SKILL.md) and Cursor (.cursor/rules/readmeter-audit.mdc). Ask your agent to "audit Firestore reads": it runs the audit, shows you a plan and waits for your OK, fixes, then measures again. Routes come from audit.routes in readmeter.config.js, or are found automatically in Next.js apps.

CI integration (optional)

Add a budget during init: readmeter add --yes --budget 50 --ci. This writes readmeter.config.js, a GitHub Actions workflow, and scripts/readmeter-check.cjs into your repo, so CI needs no license or download. Locally, with your dev server running:

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

Requires Playwright in the project (npm i -D playwright). The check counts the reads of one page load and fails above the budget. Add --max-writes N or --max-deletes N (or maxWrites / maxDeletes under check in readmeter.config.js) to fail when a page load writes too.

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

• Framework Guides — Next.js, Nuxt, Vite, React, Vanilla JS
• Best Practices
• API Reference
• Troubleshooting — Widget shows 0 reads, modular SDK
• Case Study