MongoDB Developer
Sign in to follow topics
MongoDB Developer Centerchevron-right
Developer Topicschevron-right

Real-Time Location Tracking with Change Streams and

Ashiq Sultan8 min read • Published Feb 09, 2023 • Updated Feb 09, 2023
Node.jsMongoDBChange StreamsJavaScript
Facebook Icontwitter iconlinkedin icon
Rate this tutorial
In this article, you will learn how to use MongoDB Change Streams and to build a real-time location tracking application. To demonstrate this, we will build a local package delivery service.
Change streams are used to detect document updates, such as location and shipment status, and is used to broadcast these updates to the connected clients. An Express.js server will run in the background to create and maintain the websockets.
This article will highlight the important pieces of this demo project, but you can find the full code, along with setup instructions, on Github.
preview of location updates in user app when driver simulator is updated

Connect Express to MongoDB Atlas

Connecting Express.js to MongoDB requires the use of the MongoDB driver, which can be installed as an npm package. For this project I have used MongoDB Atlas and utilized the free tier to create a cluster. You can create your own free cluster and generate the connection string from the Atlas dashboard.
I have implemented a singleton pattern for connecting with MongoDB to maintain a single connection across the application.
The code defines a singleton db variable that stores the MongoClient instance after the first successful connection to the MongoDB database.The dbConnect() is an asynchronous function that returns the MongoClient instance. It first checks if the db variable has already been initialized and returns it if it has. Otherwise, it will create a new MongoClient instance and return it. dbConnect function is exported as the default export, allowing other modules to use it.
Now we can call the dbConnect function in the server.ts file or any other file that serves as the entry point for your application.
We now have our Express server connected to MongoDB. With the basic setup in place, we can proceed to incorporating change streams and into our application.

Change Streams

MongoDB Change Streams is a powerful feature that allows you to listen for changes in your MongoDB collections in real-time. Change streams provide a change notification-like mechanism that allows you to be notified of any changes to your data as they happen.
To use change streams, you need to use the watch() function from the MongoDB driver. Here is a simple example of how you would use change streams on a collection.
The callback function will run every time a document gets added, deleted, or updated in the watched collection.

Socket.IO and Socket.IO rooms

Socket.IO is a popular JavaScript library. It enables real-time communication between the server and client, making it ideal for applications that require live updates and data streaming. In our application, it is used to broadcast location and shipment status updates to the connected clients in real-time.
One of the key features of Socket.IO is the ability to create "rooms." Rooms are a way to segment connections and allow you to broadcast messages to specific groups of clients. In our application, rooms are used to ensure that location and shipment status updates are only broadcasted to the clients that are tracking that specific package or driver.
The code to include Socket.IO and its handlers can be found inside the files src/server.ts and src/socketHandler.ts
We are defining all the Socket.IO events inside the socketHandler.ts file so the socket-related code is separated from the rest of the application. Below is an example to implement the basic connect and disconnect Socket.IO events in Node.js.
We can now integrate the socketHandler function into our server.ts file (the starting point of our application) by importing it and calling it once the server begins listening.
We now have the Socket.IO setup with our Express app. In the next section, we will see how location data gets stored and updated.

Storing location data

MongoDB has built-in support for storing location data as GeoJSON, which allows for efficient querying and indexing of spatial data. In our application, the driver's location is stored in MongoDB as a GeoJSON point.
To simulate the driver movement, in the front end, there's an option to log in as driver and move the driver marker across the map, simulating the driver's location. (More on that covered in the front end section.)
When the driver moves, a socket event is triggered which sends the updated location to the server, which is then updated in the database.
The code above handles the "UPDATE_DA_LOCATION" socket event. It takes in the email and location data from the socket message and updates the corresponding driver's current location in the MongoDB database.
So far, we've covered how to set up an Express server and connect it to MongoDB. We also saw how to set up Socket.IO and listen for updates. In the next section, we will cover how to use change streams and emit a socket event from server to front end.

Using change streams to read updates

This is the center point of discussion in this article. When a new delivery is requested from the UI, a shipment entry is created in DB. The shipment will be in pending state until a driver accepts the shipment.
Once the driver accepts the shipment, a socket room is created with the driver id as the room name, and the user who created the shipment is subscribed to that room.
Here's a simple diagram to help you better visualize the flow.
Shipment creation flow diagram
With the user subscribed to the socket room, all we need to do is to listen to the changes in the driver's location. This is where the change stream comes into picture.
We have a change stream in place, which is listening to the Delivery Associate (Driver) collection. Whenever there is an update in the collection, this will be triggered. We will use this callback function to execute our business logic.
Note we are passing an option to the change stream watch function { fullDocument: 'updateLookup' }. It specifies that the complete updated document should be included in the change event, rather than just the delta or the changes made to the document.
In the above code, we are listening to all CRUD operations in the Delivery Associate (Driver) collection and we emit socket events only for update operations. Since the room names are just driver ids, we can get the driver id from the updated document.
This way, we are able to listen to changes in driver location using change streams and send it to the user. 
In the codebase, all the change stream code for the application will be inside the folder src/watchers/. You can specify the watchers wherever you desire but to keep code clean, I'm following this approach. The below code shows how the watcher function is executed in the entry point of the application --- i.e., server.ts file.
In this section, we saw how change streams are used to monitor updates in the Delivery Associate (Driver) collection. We also saw how the fullDocument option in the watcher function was used to retrieve the complete updated document, which then allowed us to send the updated location data to the subscribed user through sockets. The next section focuses on exploring the front-end codebase and how the emitted data is used to update the map in real time.

Front end

I won't go into much detail on the front end but just to give you an overview, it's built on React and uses Leaflet.js for Map.
I have included the entire front end as a sub app in the GitHub repo under the folder /frontend. The Readme contains the steps on how to install and start the app.
Starting the front end gives two options: 
1. Log in as user.2. Log in as a driver.
Use the "log in as driver" option to simulate the driver's location. This can be done by simply dragging the marker across the map.
frontend welcome screen

Driver simulator

Logging in as driver will let you simulate the driver's location. The code snippet provided demonstrates the use of useStateand useEffect hooks to simulate a driver's location updates. The <MapContainer> and <DraggableMarker> are Leaflet components. One is the actual map we see on the UI and other is, as the name suggests, a marker which is movable using our mouse.
The position state is initialized with the initial props. When the draggable marker is moved, the position gets updated. This triggers the gpsUpdate function inside its useEffect hook, which sends a socket event to update the driver's location.

User app

On the user app side, when a new shipment is created and a delivery associate is assigned, the SHIPMENT_UPDATED socket event is triggered. In response, the user app emits the SUBSCRIBE_TO_DA event to subscribe to the driver's socket room. (DA is short for Delivery Associate.)
Once subscribed, any changes to the driver's location will trigger the DA_LOCATION_CHANGED socket event. The driverPosition state represents the delivery driver's current position. This gets updated every time new data is received from the socket event.
The code demonstrates how the user app updates the driver's marker position on the map in real time using socket events. The state driverPosition is passed to the
component and updated with the latest location data from the DA_LOCATION_CHANGED socket event.


In this article, we saw how MongoDB Change Streams and Socket.IO can be used in a Node.js Express application to develop a real-time system.
We learned about how to monitor a MongoDB collection using the change stream watcher method. We also learned how Socket.IO rooms can be used to segment socket connections for broadcasting updates. We also saw a little front-end code on how props are manipulated with socket events.
If you wish to learn more about Change Streams, check out our tutorial on Change Streams and triggers with Node.js, or the video version of it. For a more in-depth tutorial on how to use Change Streams directly in your React application, you can also check out this tutorial on real-time data in a React JavaScript front end.

Facebook Icontwitter iconlinkedin icon
Rate this tutorial

Realm JavaScript v11: A Step Forward for React Native — Hermes Support, Realm React, Flipper, and Much More

Apr 02, 2024 | 6 min read

Using MongoDB Realm WebHooks with Amazon Kinesis Data Firehose

Jan 23, 2024 | 10 min read

Change Streams & Triggers with Node.js Tutorial

Aug 24, 2023 | 17 min read

Integrate MongoDB into Vercel Functions for the Serverless Experience

Feb 03, 2023 | 7 min read
Table of Contents