🔥 MongoFire

Offline-first MongoDB sync — Local + Atlas feel like ONE database. Drop-in production setup, automatic connection management, zero boilerplate.

What is MongoFire?

MongoFire keeps a local MongoDB and MongoDB Atlas in sync — automatically, reliably, and with zero boilerplate. Your app reads and writes to a local MongoDB instance that is always fast and always available, even when offline. MongoFire handles the rest in the background.

⚡ MongoFire manages every MongoDB connection for you. You never call mongoose.connect(). You never call app.listen() directly. You import two functions — startApp and plugin — and everything else is automatic.

Features:

• Offline-first — your app never waits for the network
• Zero-config connection — local MongoDB connects automatically on import
• startApp(app, port) — replaces app.listen(), waits for DB, then opens the server
• Automatic sync — uploads local changes and downloads remote ones on a configurable interval
• Real-time mode — optional Atlas Change Streams for near-instant propagation
• Conflict resolution — deterministic last-writer-wins with version tracking
• Per-field merge — field-level LWW prevents data loss when devices edit different fields simultaneously
• Resumable bootstrap — first sync streams from Atlas in batches, survives crashes
• Self-healing — detects and recovers lost writes caused by crashes or local DB resets
• Auto-spawn mongod — if MongoDB is not running, MongoFire starts it automatically
• CLI tools — interactive commands for status, conflicts, reconciliation, and safe reset
• TypeScript — full type declarations included

Installation

npm install mongofire

Peer dependencies (install once in your project):

npm install mongodb mongoose dotenv

Quick Start (3 steps)

Step 1 — Run the setup wizard

npx mongofire init

This creates three files in your project root:

| File | Purpose | |---|---| | .env | MongoDB connection strings | | mongofire.config.js | Collections to sync, intervals, options | | mongofire.js | The MongoFire entry point — do not delete |

Step 2 — Fill in .env

ATLAS_URI=mongodb+srv://user:[email protected]/
LOCAL_URI=mongodb://127.0.0.1:27017
DB_NAME=myapp

ATLAS_URI is optional — omit it to run in local-only mode during development.

Step 3 — Use MongoFire in your project

server.js — your Express entry point:

// ESM
import express from 'express';
import cors from 'cors';
import cookieParser from 'cookie-parser';
import { startApp } from './mongofire.js';   // ← import from YOUR mongofire.js

import authRoutes    from './routes/auth.routes.js';
import studentRoutes from './routes/student.routes.js';

const app = express();
app.use(express.json());
app.use(cookieParser());
app.use(cors({ origin: process.env.FRONTEND_URL, credentials: true }));

app.use('/auth',     authRoutes);
app.use('/students', studentRoutes);

// ✅ Replaces app.listen() — waits for local DB then starts the server
startApp(app, process.env.PORT || 3000);

// CommonJS
const express = require('express');
const { startApp } = require('./mongofire');

const app = express();
app.use(express.json());

app.use('/auth', require('./routes/auth.routes'));

startApp(app, process.env.PORT || 3000);

models/User.js — attach the plugin to your Mongoose schemas:

// ESM — from a file inside models/
import mongoose from 'mongoose';
import { plugin } from '../mongofire.js';   // ← note: ../ because models/ is one level deep

const UserSchema = new mongoose.Schema({
  name:      String,
  email:     { type: String, unique: true },
  updatedAt: Date,
});

UserSchema.plugin(plugin('users'));  // collection name must match mongofire.config.js

export default mongoose.model('User', UserSchema);

// CommonJS — from a file inside models/
const mongoose = require('mongoose');
const { plugin } = require('../mongofire');   // ← note: ../ one level up

const StudentSchema = new mongoose.Schema({
  name:      String,
  grade:     Number,
  updatedAt: Date,
});

StudentSchema.plugin(plugin('students'));

module.exports = mongoose.model('Student', StudentSchema);

Critical: The import path is always a relative path to mongofire.js in your project root. It is never 'mongofire' (the npm package name). From server.js (root) → './mongofire.js' From models/User.js (one level deep) → '../mongofire.js'

Project folder structure

backend/
├── mongofire.js          ← Generated by init — the bridge between your app and MongoFire
├── mongofire.config.js   ← Your sync configuration
├── .env                  ← Connection strings (never commit this)
├── server.js             ← import { startApp } from './mongofire.js'
├── models/
│   ├── User.js           ← import { plugin } from '../mongofire.js'
│   └── Student.js        ← import { plugin } from '../mongofire.js'
└── routes/
    ├── auth.routes.js
    └── student.routes.js

What startApp() does

startApp(app, port) replaces app.listen(). It:

1. Waits for local MongoDB to be fully connected
2. Calls app.listen(port) only after the DB is ready
3. Logs 🚀 [MongoFire] Server ready on port <port> on success
4. If the local DB fails: logs a descriptive error and exits with code 1

Console output on startup:

✅ [MongoFire] Local MongoDB connected
🚀 [MongoFire] Server ready on port 3000
🌐 [MongoFire] Atlas connected — sync active
🔄 [MongoFire] Sync complete — ↑2 uploaded  ↓5 downloaded  🗑 0 deleted

Config Options (mongofire.config.js)

export default {
  localUri:  process.env.LOCAL_URI || 'mongodb://127.0.0.1:27017',
  atlasUri:  process.env.ATLAS_URI,
  dbName:    process.env.DB_NAME   || 'myapp',

  collections: ['users', 'students', 'orders'],  // every collection your app uses

  syncInterval: 30000,   // ms between sync cycles (minimum 500)
  batchSize:    200,
  syncOwner:    '*',     // '*' = sync all  |  'userId' = per-user isolation
  realtime:     false,   // true = Atlas Change Streams
  cleanDays:    7,

  onSync(result) {
    if (result.uploaded + result.downloaded + result.deleted > 0)
      console.log(`Synced: ↑${result.uploaded} ↓${result.downloaded}`);
  },
  onError(err) { console.error('Sync error:', err.message); },
};

| Option | Type | Default | Description | |---------------------|----------------|--------------------------------------|---------------------------------------------------------| | collections | string[] | required | Collection names to sync | | localUri | string | 'mongodb://127.0.0.1:27017' | Local MongoDB URI | | atlasUri | string | null | Atlas URI. Omit for local-only mode | | dbName | string | 'myapp' | Database name | | syncInterval | number | 30000 (5000 if realtime:true) | Polling interval in ms (minimum: 500) | | batchSize | number | 200 | Documents per batch (1–10 000) | | syncOwner | string\|fn | '*' | Owner filter — see Multi-Tenant section | | realtime | boolean | false | Enable Atlas Change Streams | | cleanDays | number | 7 | Auto-clean synced records older than N days | | onSync | function | null | Called after each sync cycle | | onError | function | null | Called when a sync cycle throws | | reconcileOnStart | boolean | true | Scan for lost writes at startup |

Common import mistakes

❌ Wrong — using the npm package name

import { plugin } from 'mongofire';       // ❌ ERR_MODULE_NOT_FOUND
const { plugin } = require('mongofire');  // ❌ wrong unless mongofire is installed globally

✅ Correct — relative path to your local mongofire.js

// server.js (same folder as mongofire.js)
import { startApp, plugin } from './mongofire.js';

// models/User.js (one folder deep)
import { plugin } from '../mongofire.js';

// routes/user.routes.js (one folder deep)
import { plugin } from '../mongofire.js';

Events

import { mongofire } from './mongofire.js';

mongofire.on('localReady', () => console.log('Local DB connected'));
mongofire.on('online',     () => console.log('Atlas connected'));
mongofire.on('offline',    () => console.log('Working offline'));
mongofire.on('sync',       (r) => console.log('Synced:', r));
mongofire.on('conflict',   (c) => console.warn('Conflict:', c));
mongofire.on('error',      (e) => console.error('Error:', e));
mongofire.on('stopped',    ()  => console.log('Shut down cleanly'));

| Event | Payload | When emitted | |--------------------|--------------------------------|----------------------------------------| | localReady | Db | Local MongoDB connected (before Atlas) | | ready | — | start() fully completed | | online | — | Atlas connected | | offline | — | Atlas becomes unreachable | | sync | SyncResult | After each sync cycle | | conflict | ConflictData | Local write conflicts with remote | | conflictResolved | { opId, resolution } | After retry or dismiss | | stopped | — | stop() finished | | error | Error | Unexpected sync error |

API Reference

startApp(app, port) → Promise<http.Server>

Replaces app.listen(). Waits for local DB, then opens the server port. Exits with code 1 on DB failure.

import { startApp } from './mongofire.js';
startApp(app, process.env.PORT || 3000);

plugin(collectionName, options?) → Mongoose plugin function

Attaches change-tracking to a schema. Apply before mongoose.model().

import { plugin } from '../mongofire.js';
UserSchema.plugin(plugin('users'));
UserSchema.plugin(plugin('users', { ownerField: 'userId' }));  // multi-tenant

localReady → Promise<Db>

Resolves as soon as local MongoDB is connected, before Atlas.

import { localReady } from './mongofire.js';
await localReady;  // DB is guaranteed ready after this

ready → Promise<MongoFire>

Resolves after Atlas connect and the first sync.

mongofire.sync(type?) → Promise<SyncResult>

Manually trigger a sync ('required' or 'all').

mongofire.status() → Promise<SyncStatus>

Returns { online, pending, creates, updates, deletes, realtime }.

mongofire.conflicts() / retryConflict(opId) / dismissConflict(opId)

View and resolve sync conflicts.

mongofire.reconcile(opts?) → Promise<ReconcileResult[]>

Scan for and recover writes lost in a crash.

mongofire.resetLocal() → Promise<{ dropped: number }>

Wipe the local DB. Next startup re-bootstraps from Atlas. Unsynced changes are lost.

mongofire.stop(timeoutMs?) → Promise<void>

Flush in-flight ops and close connections. Called automatically on SIGINT/SIGTERM.

Real-Time Sync

// mongofire.config.js
export default {
  atlasUri:     process.env.ATLAS_URI,
  collections:  ['orders'],
  realtime:     true,    // requires Atlas M10+ or a local replica set
  syncInterval: 5000,    // polling fallback
};

Falls back to polling if Change Streams are unavailable. Saves a resume token — restarts pick up exactly where they left off. Restarts use exponential backoff (2 s → 60 s).

Multi-Tenant

For apps where each user must only sync their own data:

// mongofire.config.js
export default {
  collections: ['notes'],
  syncOwner: () => currentUserId,  // returns the current user's ID
};

// model
NoteSchema.plugin(plugin('notes', { ownerField: 'userId' }));

// create — always set the owner field
await Note.create({ title: 'My note', userId: req.user._id });

CLI Reference

npx mongofire init                          # Setup wizard (creates mongofire.js, config, .env)
npx mongofire init --force                  # Overwrite existing files
npx mongofire init --esm                    # Force ESM output
npx mongofire init --cjs                    # Force CJS output
npx mongofire config                        # Update config interactively
npx mongofire status                        # Show pending sync counts
npx mongofire clean --days=7                # Delete records older than 7 days
npx mongofire conflicts                     # View and resolve conflicts
npx mongofire reconcile                     # Recover writes lost from crashes
npx mongofire reconcile --collection=users  # Single collection
npx mongofire reset-local                   # Wipe local DB and re-bootstrap

Set MONGOFIRE_DEBUG=1 for full error stack traces.

TypeScript

import { startApp, plugin, mongofire } from './mongofire.js';
import type { SyncResult, ConflictData } from 'mongofire';

UserSchema.plugin(plugin('users'));
startApp(app, 3000);

mongofire.on('sync', (result: SyncResult) => {
  console.log(`↑${result.uploaded} ↓${result.downloaded}`);
});

Environment Variables

| Variable | Default | Description | |------------------------------------|--------------------------|------------------------------------------------------| | ATLAS_URI | — | MongoDB Atlas connection string | | LOCAL_URI | mongodb://127.0.0.1:27017 | Local MongoDB URI | | DB_NAME | myapp | Database name | | MONGOFIRE_DEBUG | unset | Set to 1 for full stack traces | | MONGOFIRE_VERIFY_REMOTE | 0 | Set to 1 to checksum-verify each uploaded document | | MONGOFIRE_COLLECTION_CONCURRENCY | 4 | Collections synced in parallel (max 32) | | MONGOFIRE_DBPATH | ~/.mongofire/<dbName> | Data directory for auto-spawned mongod |

Troubleshooting

ERR_MODULE_NOT_FOUND: Cannot find package 'mongofire'

You are importing from 'mongofire' instead of from './mongofire.js'.

// ❌ Wrong
import { plugin } from 'mongofire';

// ✅ Correct (from project root)
import { plugin } from './mongofire.js';

// ✅ Correct (from models/ folder)
import { plugin } from '../mongofire.js';

mongoose.connect() should not be called

Remove any mongoose.connect() calls from your code. MongoFire manages the connection through localUri in mongofire.config.js.

Local MongoDB failed to connect

• MongoDB is not installed — download here
• mongod is not in your system PATH
• LOCAL_URI in .env is incorrect
• Port 27017 is blocked by a firewall

MongoFire tries to auto-spawn mongod. Set MONGOFIRE_DBPATH to a writable directory if the default fails.

Cannot find module './mongofire.config.js'

Run npx mongofire init to regenerate the config file.

License

MIT — see LICENSE