Firestore compatibility

This reference records the currently implemented Firebase / Firestore compatibility surface in Nimbus. It is intentionally narrower than a generic “Firestore-compatible” claim. Anything not listed as supported should be assumed unsupported.

Firestore routes are served by default on the main listener; opt out with --no-firestore.

Nimbus has three distinct Firebase-facing stories:

1. A tested first-party drop-in firebase package. It takes the stock npm name, so firebase/app and firebase/firestore imports work unchanged once the app’s firebase dependency points at the copy provisioned by the nimbus binary — nimbus dev wires that dependency automatically after its import scan confirms every Firebase import is covered, and nimbus packages provision firebase wires it directly.
2. A live Firestore server surface: REST, selected native gRPC, gRPC-Web, and WebSocket Listen.
3. Deferred wire compatibility with the registry-published Google firebase package, because upstream browsers still use WebChannel rather than gRPC-Web for the full Firestore client. Stock import paths are covered by the provisioned package; the upstream transport stack is not.

For the adoption path, see Use Firestore SDKs with Nimbus and Migrate from Firebase.

Status labels

Label	Meaning
supported	Covered by the shipped surface and exercised by tests.
supported with caveats	Usable now, but requires explicit settings or has a frozen boundary called out here.
server-capable, no SDK wrapper yet	The server implements the underlying Firestore RPCs, but the provisioned firebase package does not expose a helper yet.
not claimed	No compatibility promise yet, even if some lower-level RPCs exist.
deferred	Explicitly outside the current release target.

SDK and runtime matrix

Surface	Status	Transport(s)	Current claim
Provisioned firebase package in browsers	supported with caveats	REST unary by default, opt-in gRPC-Web unary, WebSocket Listen	Primary supported Firebase-style client for Nimbus; stock firebase/app + firebase/firestore imports resolve to it via the file: dependency. Covers refs, CRUD, queries, snapshots, listeners, write batches, transactions, supported FieldValue transforms, and bearer-token auth on the covered routes. No WebChannel, no offline persistence, no bundle/named-query APIs, no onSnapshotsInSync, no waitForPendingWrites, no long polling.
Provisioned firebase package in Node	supported with caveats	Same as browser; watch flows may need an explicit experimentalWebSocketFactory	Same API surface as the browser package, for tests and server-side JS callers. Not a drop-in replacement for firebase-admin or @google-cloud/firestore.
Registry-published Google firebase package	deferred	Upstream WebChannel stack	No wire-compatibility claim for Google’s npm package against Nimbus. Its WebChannel transport and browser persistence are not implemented; repoint the firebase dependency at the provisioned package instead — imports stay unchanged.
Stock firebase/firestore/lite	not claimed	Upstream browser REST stack	Overlapping unary semantics exist on the server, but no import-path or transport-stack compatibility promise.
Node Admin SDK (firebase-admin.firestore)	not claimed	Upstream Google Cloud client stack	Many underlying RPCs exist, but Admin SDK parity (BulkWriter, recursive delete, bundles, import/export, emulator control) is broader than the verified surface.
Go / Java / Python server SDKs	not claimed	Upstream Firestore gRPC/REST clients	Underlying protocol work exists; no supported-compatibility claim is published.
Android / Apple / C++ / Unity SDKs	not claimed	Native mobile transport stacks	No tested claim for auth, reconnect, persistence, or SDK-specific behavior.

Provisioned firebase package API coverage

Area	Status	Notes
App + Firestore bootstrap (initializeApp, getFirestore, initializeFirestore)	supported	App-scoped Firestore instances.
Emulator host switching (connectFirestoreEmulator)	supported with caveats	Redirects the SDK to a local Nimbus host; transport redirection, not Firebase Emulator Suite control-plane parity.
Termination (terminate)	supported
Collection / document / collection-group refs	supported	Canonical path validation, including nested refs and collection groups.
CRUD (getDoc, setDoc, updateDoc, deleteDoc, addDoc)	supported	Backed by live REST or gRPC-Web unary paths.
Query builder (query, where, orderBy, cursors, limit, documentId)	supported with caveats	Supported for the implemented Firestore subset, including collection-group queries and document-name ordering/cursors. Nested field-path helpers remain intentionally narrow.
Query execution (getDocs, QuerySnapshot, QueryDocumentSnapshot)	supported
Equality helpers (refEqual, queryEqual, snapshotEqual)	supported
Converters (withConverter, typed data())	supported	Converter-backed refs, queries, and snapshots.
Listeners (onSnapshot)	supported	Uses the binary-protobuf WebSocket Listen channel instead of WebChannel. Covers bootstrap, resume, retry budget, and auth upgrade.
writeBatch	supported	Atomic Firestore Commit semantics.
runTransaction	supported	Point reads, transactional query reads, staged writes, bounded retries, rollback.
FieldValue sentinels (deleteField, serverTimestamp, increment, arrayUnion, arrayRemove)	supported	Round-trip through REST and gRPC-Web.
Aggregation query helpers	server-capable, no SDK wrapper yet	The server implements RunAggregationQuery; no JS builders yet.
ListCollectionIds helpers	server-capable, no SDK wrapper yet
BatchWrite helpers	server-capable, no SDK wrapper yet

Frozen compatibility boundaries

These are intentional, documented boundaries rather than accidental gaps:

• Only the default Firestore database, (default), is supported end to end. The SDK can construct non-default database handles, but the server rejects named databases.
• Browser full-SDK compatibility means the Nimbus-provisioned firebase package. Stock import paths work because that package takes the stock npm name; the registry-published Google package itself is not wire-compatible.
• Unary transport defaults to REST. gRPC-Web is available only through the explicit experimentalUnaryTransport: "grpc-web" setting.
• Watch support uses the WebSocket Listen channel — not WebChannel and not gRPC-Web.
• Raw stock Firestore Write streaming compatibility is not part of the current public claim; upstream Node Firestore clients that open a Write stream are not covered.
• Firebase read surfaces only project Firestore-native typed scalars. Documents carrying foreign adapter typed scalars (for example MongoDB ObjectId, Decimal128, Binary, Regex) are rejected on Firebase REST/gRPC reads rather than lossy-projected into strings.
• Application auth on Firebase routes is enforced on the covered CRUD/query/transaction/Write/Listen paths within the contract in Firebase auth; breadth outside that contract is not a verified auth promise.
• experimentalForceLongPolling and experimentalAutoDetectLongPolling are accepted as settings-shape compatibility fields, but no long-polling transport is implemented behind them.

Known gaps relative to upstream SDK breadth

• Offline persistence and related browser APIs (enableIndexedDbPersistence, clearIndexedDbPersistence, cache-only reads, network toggles) are not implemented.
• Bundle and local query APIs (loadBundle, namedQuery) are not implemented.
• Client-coordination helpers (onSnapshotsInSync, waitForPendingWrites) are not implemented.
• Emulator control-plane compatibility is limited to host redirection via connectFirestoreEmulator; the Firebase Emulator Suite control/admin endpoint family is not implemented.
• Admin-library breadth (bulk writer, recursive delete, import/export) is not part of the current claim.