Community

Ashiq Sultan

Full Stack Developer

In this article, you will learn how to use [MongoDB Change Streams](https://www.mongodb.com/docs/manual/changeStreams/) and [Socket.io](https://socket.io/) 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 Socket.io 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](https://github.com/mongodb-developer/location-tracking).

![preview of location updates in user app when driver simulator is updated](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/9_Fvq_VP_9_Imgur_05283ccda6.gif)


## Connect Express to MongoDB Atlas

Connecting Express.js to MongoDB requires the use of the [MongoDB driver](https://www.mongodb.com/docs/drivers/node/current/), which can be installed as an [npm package](https://www.npmjs.com/package/mongodb). For this project I have used MongoDB Atlas and utilized the [free tier to create a cluster](https://www.mongodb.com/docs/atlas/tutorial/deploy-free-tier-cluster/). You can create your own free cluster and generate the [connection string](https://www.mongodb.com/docs/guides/atlas/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.

```typescript
// dbClient.ts
import { MongoClient } from 'mongodb';
const uri = process.env.MONGODB_CONNECTION_STRING;
let db: MongoClient;
const dbConnect = async (): Promise<MongoClient> => {
    try {
        if (db) {
            return db;
        }
        console.log('Connecting to MongoDB...');
        const client = new MongoClient(uri);
        await client.connect();
        db = client;
        console.log('Connected to db');
        return db;
    } catch (error) {
        console.error('Error connecting to MongoDB', error);
        throw error;
    }
};
export default dbConnect;
```

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.

```typescript
// server.ts
import dbClient from './dbClient';
server.listen(5000, async () => {
    try {
        await dbClient();
    } catch (error) {
        console.error(error);
    }
});
```

We now have our Express server connected to MongoDB. With the basic setup in place, we can proceed to incorporating change streams and socket.io into our application.

## Change Streams

[MongoDB Change Streams](https://www.mongodb.com/docs/manual/changeStreams/) 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.

```typescript
const changeStream = collection.watch()
changeStream.on('change', (event) => {
// your logic
})
```

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.

```typescript
// socketHandler.ts
const socketHandler = (io: Server) => {
  io.on('connection', (socket: any) => {
    console.log('A user connected');
    socket.on('disconnect', () => {
      console.log('A user disconnected');
    });
  });
};
export default socketHandler;
```

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.

```typescript
// server.ts
import app from './app'; // Express app
import http from 'http';
import { Server } from 'socket.io';
const server = http.createServer(app);
const io = new Server(server);
server.listen(5000, async () => {
  try {
    socketHandler(io);
  } catch (error) {
    console.error(error);
  }
});
```

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](https://www.mongodb.com/docs/manual/reference/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](https://www.mongodb.com/docs/manual/reference/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.

```typescript
socket.on("UPDATE_DA_LOCATION", async (data) => {
  const { email, location } = data;
  await collection.findOneAndUpdate({ email }, { $set: { currentLocation: location } });
});
```

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](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/ha2g_Uz_S_6cf1e0687e.png)

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.

```typescript

const watcher = async (io: Server) => {\
  const collection = await DeliveryAssociateCollection();\
  const changeStream = collection.watch([], { fullDocument: 'updateLookup' });\
  changeStream.on('change', (event) => {\
    if (event.operationType === 'update') {\
        const fullDocument = event.fullDocument;\
        io.to(String(fullDocument._id)).emit("DA_LOCATION_CHANGED", fullDocument);\
}});};

```

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.

```typescript
// server.ts
import deliveryAssociateWatchers from './watchers/deliveryAssociates';
server.listen(5000, async () => {
  try {
    await dbClient();
    socketHandler(io);
    await deliveryAssociateWatchers(io);
  } catch (error) {
    console.error(error);
  }
});
```

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`](https://github.com/mongodb-developer/location-tracking/tree/main/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](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/X_Zrc_M1_G_Imgur_d1cd25b8c0.png)

### Driver simulator

Logging in as driver will let you simulate the driver's location. The code snippet provided demonstrates the use of `useState`and `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.

```jsx
// Driver Simulator
const [position, setPosition] = useState(initProps.position);
const gpsUpdate = (position) => {
  const data = {
    email,
    location: { type: 'Point', coordinates: [position.lng, position.lat] },
  };
  socket.emit("UPDATE_DA_LOCATION", data);
};
useEffect(() => {
gpsUpdate(position);
}, [position]);
return (
<MapContainer>
<DraggableMarker position={position}/>
</MapContainer>
)
```

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

```js
socket.on('SHIPMENT_UPDATED', (data) => {
  if (data.deliveryAssociateId) {
    const deliveryAssociateId = data.deliveryAssociateId;
    socket.emit('SUBSCRIBE_TO_DA', { deliveryAssociateId });
  }
});
```

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.

```jsx
const [driverPosition, setDriverPosition] = useState(initProps.position);
socket.on('DA_LOCATION_CHANGED', (data) => {
  const location = data.location;
  setDriverPosition(location);
});
return (
<MapContainer>
<Marker position={driverPosition}/>
</MapContainer>
)
```

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 <Marker> component and updated with the latest location data from the DA_LOCATION_CHANGED socket event.

## Summary

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](https://www.mongodb.com/developer/languages/javascript/nodejs-change-streams-triggers/), or the [video version](https://www.youtube.com/watch?v=9LA7_CSyZb8) 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.](https://www.mongodb.com/developer/products/mongodb/real-time-data-javascript/)

Learn how to use MongoDB Change Streams and Socket.io to build a real-time location-tracking application. We will build a local package delivery service.

Real-Time Location Tracking With Change Streams and Socket.io

Create an e-commerce semantic search utilizing MongoDB Vector Search and OpenAI models

Ashiq Sultan

Content by Ashiq Sultan

Real-Time Location Tracking With Change Streams and Socket.io

Build an E-commerce Search Using MongoDB Vector Search and OpenAI