DEV Community: Jordan Smith

Building E-commerce AI Agents on MongoDB with CrewAI

Jordan Smith — Tue, 25 Aug 2026 17:04:18 +0000

AI-powered shopping agents are becoming a real differentiator for e-commerce teams. A 2026 Stord report on AI in e-commerce revealed a 34% year-over-year increase in the number of consumers who reported using generative AI for online shopping. The trend is even more pronounced among younger consumers: 37% of Gen Z and 29% of Millennials actively use AI to shop online. After seeing how the agentic commerce journey actually works, it's not hard to understand why.

This tutorial shows you exactly how to build one on MongoDB Atlas with CrewAI. You’ll create a chat-based shopping assistant that understands natural-language queries, retrieves relevant products with MongoDB Vector Search and MongoDB Search, and uses Change Streams, Atlas Triggers, and Atlas Stream Processing to keep inventory, checkout, and post-purchase experiences in sync with real-time data.

By the end, you’ll be able to:

Build a CrewAI shopping agent that calls MongoDB Vector Search tools with structured filters (price, availability).
Model an e-commerce catalog on MongoDB and generate high-quality product embeddings for semantic search.
Use MongoDB Change Streams to make checkout flows inventory-aware at the moment of purchase.
Trigger post-purchase workflows and customer notifications with MongoDB Atlas Triggers.
Detect emerging delivery issues with MongoDB Atlas Stream Processing so agents can respond proactively.

This GitHub repository wires up the code samples in this post. The code will help you build a CrewAI shopping agent and use MongoDB Vector Search on Atlas to understand the semantic meaning of customer queries, implement atomic inventory checkout with Change Streams, and (as deploy-ready artifacts) create an Atlas Trigger and an Atlas Stream Processing pipeline for post-purchase intelligence.

What is the agentic commerce journey?

Here is how a fully agentic shopping experience (a.k.a zero-click buying) works in practice:

A customer asks a question: Via voice or text, they describe what he/she needs. The agent interprets the intent behind the query, not just the keywords.
The agent finds and curates the best options: It surfaces a short list of products with detailed specifications, pricing, deals, quality ratings, and reviews.
The customer makes a purchase decision: With curated options in the chat interface, the customer asks follow-up questions and then decides to purchase. What used to take hours of browsing now takes minutes.
The agent completes the transaction: For products that support instant checkout, the agent handles the entire payment process end-to-end (provided the customer’s payment information is on file). If not, the agent can safely ask the customer to provide payment information, encrypt it, and securely store it in the database for future use.
The agent handles everything post-purchase: It tracks the order, surfaces proactive updates when status changes, and manages returns or follow-ups if something goes wrong.

Each step in this journey places real technical demands on the underlying platform. The agent needs to understand natural language, retrieve semantically relevant products, evaluate quality and price across thousands of options, confirm inventory accuracy at the moment of purchase, and stay aware of order events without waiting to be asked. That's a lot of moving parts. Most teams choose to build them on a collection of separate systems, each adding its own overhead, latency, and points of failure. But what if a single platform could support these capabilities without requiring teams to stitch together multiple specialized systems?

That is where MongoDB comes in. By combining operational data, semantic search, real-time updates, and transactional capabilities into a single platform, MongoDB can support the different stages of the agentic commerce journey.

How do MongoDB capabilities fit into each step of the agentic commerce journey?

Agent Journey Step	MongoDB Feature
Understand customer intent	Atlas Vector Search + LLM integration + Voyage AI embedding model
Produce relevant results	Atlas Vector Search + MongoDB Search
Answer follow-up questions	Atlas Vector Search + MongoDB Search
Confirm inventory at checkout	Change Streams
Proactive order status updates	Atlas Triggers
Detect delivery patterns before they escalate	Atlas Stream Processing

MongoDB is a strong candidate because it offers the native features required to power each step of the agentic commerce journey. Let's see how.

Step 1–3: How do MongoDB Vector Search on Atlas and MongoDB Search power agent discovery and decision-making?

When a customer types "lightweight running shoes under $100 with good arch support," they're describing an intent. The agent needs to understand the semantic meaning behind that query and match it to products that fit that intent. The agent needs to understand the user's intent, not just focus on keywords.

MongoDB Vector Search on Atlas handles this natively. Your product embeddings are stored alongside your product data in the same cluster. When a query comes in, the agent converts it to a vector using a best-in-class embedding model (Voyage AI), runs a search in your product catalog, and retrieves the most semantically relevant results, ranked by relevance rather than just keyword frequency. We can refer to this as a product-search tool. Let’s see exactly how to build it.

First, use the code below to create a Vector Search index that includes both the embedding field and the fields the agent will use as filters. For the query to work, the collection needs a Vector Search index that matches the fields used in the code. The embedding field is indexed as the vector field, with 2048 dimensions to match the Voyage AI embedding model. The price and in_stock fields are indexed as filter fields, which lets MongoDB apply those constraints before running the vector similarity search. That means the agent searches only for products under $100 and available to buy, rather than retrieving relevant products first and filtering them afterward.

function productToEmbeddingText(product) {
  return [
    `Name: ${product.name}`,
    `Brand: ${product.brand}`,
    `Category: ${product.category}`,
    `Description: ${product.description}`,
    `Features: ${(product.features || []).join(", ")}`,
    `Review summary: ${product.reviewSummary}`,
    `Price: ${product.price}`,
    `In stock: ${product.in_stock}`
  ].filter(Boolean).join("\n");
}

const embeddingText = productToEmbeddingText(product);
const embedding = await createEmbedding(embeddingText);

await db.collection("products").updateOne(
  { _id: product._id },
  {
    $set: {
      embedding,
      embedding_text: embeddingText
    }
  }
);

With that index in place, the agent can run a semantic search and apply price and inventory constraints before performing similarity ranking. Here is the code for that:

{
  "fields": [
    {
      "type": "vector",
      "path": "embedding",
      "numDimensions": 2048,
      "similarity": "cosine"
    },
    {
      "type": "filter",
      "path": "price"
    },
    {
      "type": "filter",
      "path": "in_stock"
    }
  ]
}

Next, use the code below to create the CrewAI shopping agent that uses the product search tool. The agent is given a role, a goal, and a backstory so it understands how to behave during the shopping experience. By attaching search_product_catalog (defined next) as a tool, we give the agent access to MongoDB Vector Search in Atlas and the live product catalog. When a customer asks for a recommendation, the agent can call that tool, retrieve relevant in-stock products, and use the results to provide a helpful, context-aware answer.

from crewai import Agent

shopping_agent = Agent(
    role="Shopping assistant",
    goal="Help customers find products that match their intent and constraints.",
    backstory=(
        "You help customers discover relevant products using MongoDB Atlas "
        "Vector Search and real-time product data."
    ),
    tools=[search_product_catalog],
    llm="gpt-4o",
)

The search_product_catalog function is the tool attached to the CrewAI shopping agent. When the agent needs to search the catalog, this tool connects to the product collection, uses Voyage AI to convert the customer’s request into a query embedding, and runs MongoDB Vector Search in Atlas against the embedding field using product_vector_index. The semantic part of the request, such as “lightweight running shoes with good arch support,” is handled by Vector Search, while the hard constraints, price <= 100 and in_stock: true, are applied as pre-filters. The result is a reusable CrewAI tool that returns products that are both semantically relevant and eligible for the customer to buy.

import os
from bson import json_util
from pymongo import MongoClient
from crewai.tools import tool

client = MongoClient(os.environ["MONGODB_URI"])
collection = client["ecommerce"]["products"]


@tool("Search product catalog")
def search_product_catalog(query: str) -> str:
    """Find in-stock products under $100 that semantically match the query.

    This version uses Atlas Vector Search auto-embedding. The application sends
    natural-language query text directly to MongoDB; Atlas generates the query
    embedding using the model configured in the Vector Search index.
    """

    pipeline = [
        {
            "$vectorSearch": {
                "index": "product_autoembed_index",
                "path": "search_text",
                "query": {
                    "text": query
                },
                "numCandidates": 100,
                "limit": 5,
                "filter": {
                    "$and": [
                        {"price": {"$lte": 100}},
                        {"in_stock": True}
                    ]
                }
            }
        },
        {
            "$project": {
                "_id": 0,
                "name": 1,
                "description": 1,
                "price": 1,
                "in_stock": 1,
                "score": {"$meta": "vectorSearchScore"}
            }
        }
    ]

    results = list(collection.aggregate(pipeline))
    return json_util.dumps(results, indent=2)

Alternative: Let Atlas generate embeddings automatically

The previous example shows manual embedding generation. If you want less application code, MongoDB Vector Search on Atlas can generate document and query embeddings automatically using an autoEmbed index. In that version, the app sends natural language query text directly to $vectorSearch. The code below explains how MongoDB Vector Search on Atlas generates document and query embeddings automatically.

{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "search_text",
      "model": "voyage-4"
    },
    {
      "type": "filter",
      "path": "price"
    },
    {
      "type": "filter",
      "path": "in_stock"
    }
  ]
}

For structured filtering, such as price ranges, brand filters, and in-stock flags, MongoDB Search layers on top of Vector Search. The agent can combine semantic similarity with exact filters in a single query, returning results that are both contextually relevant and within the customer's stated constraints.

Because your product catalog, inventory levels, reviews, and pricing (i.e., operational data) all reside in the same MongoDB database, the agent retrieves a complete, enriched product document in a single call.

Example output:

This is an example of the application's output in response to “Find in-stock products under $100 that semantically match the query.”

[
  {
    "name": "AeroFlex Runner 2",
    "description": "Lightweight daily running shoe with responsive foam and built-in arch support.",
    "price": 89.99,
    "in_stock": true,
    "score": 0.91
  },
  {
    "name": "CloudStep Support Knit",
    "description": "Breathable road running shoe designed for moderate overpronation and arch comfort.",
    "price": 94.5,
    "in_stock": true,
    "score": 0.88
  }
]

Optional: Connect your agent with the MongoDB MCP Server

The product-search tool above is one way to expose MongoDB to the agent. For more dynamic agent workflows, you can also connect the agent to MongoDB through the MongoDB MCP Server. MCP provides a standard tool interface that lets the agent discover MongoDB resources and issue structured database operations with the permissions you configure. In an e-commerce shopping flow, the agent could use MCP to look up product metadata, inspect inventory fields, retrieve customer order context, or run follow-up queries after Vector Search returns candidate products.

In the code below, the CrewAI agent is connected to MongoDB in two ways. The search_product_catalog tool handles the primary product discovery flow using Atlas Vector Search, while the MongoDB MCP Server provides the agent with a standard tool interface for follow-up database operations. The MCP server runs in read-only mode and exposes only selected tools, such as collection schema, find, and aggregate, so the agent can look up product details, inventory fields, or customer context without being given unrestricted database access.

import os
from crewai import Agent
from crewai.mcp import MCPServerStdio
from crewai.mcp.filters import create_static_tool_filter

mongo_mcp = MCPServerStdio(
    command="npx",
    args=[
        "-y",
        "mongodb-mcp-server@latest",
        "--readOnly",
    ],
    env={
        "MDB_MCP_CONNECTION_STRING": os.environ["MDB_MCP_CONNECTION_STRING"],
    },
    tool_filter=create_static_tool_filter(
        allowed_tool_names=[
            "list-databases",
            "list-collections",
            "collection-schema",
            "collection-indexes",
            "find",
            "aggregate",
        ]
    ),
    cache_tools_list=True,
)

shopping_agent = Agent(
    role="Shopping assistant",
    goal="Help customers find products that match their intent and constraints.",
    backstory=(
        "You help customers discover relevant products using MongoDB Atlas "
        "Vector Search, Atlas auto-embedding, live product data, and MongoDB MCP tools."
    ),
    tools=[search_product_catalog],
    mcps=[mongo_mcp],
    llm="gpt-4o",
)

Step 4: How do MongoDB Change Streams help with the checkout process?

This is where most teams don't anticipate the problem until they're already in production.

A customer has found the product, decided to buy it, and initiated checkout. At that exact moment, the agent needs to confirm that the item is still available.

During a high-traffic sale, inventory moves fast. The last unit of a limited-edition product can sell in the seconds between when a customer adds it to their cart and when the transaction is confirmed. If the agent is working with inventory data that doesn't reflect the final sale, the purchase goes through, the inventory system immediately rejects it, and the customer receives an "item not available" notification along with a refund. At scale, that failure pattern compounds quickly into frustrated customers, support overhead, and refund costs that add up fast.

MongoDB solves this in two parts: an atomic inventory update keeps checkout running smoothly, while Change Streams let the agent react immediately after inventory changes are committed. Change Streams is a cursor-based API that subscribes to document-level changes in a collection as soon as a write is committed to the database. There is no polling interval and therefore no sync gap. When inventory for a product drops to zero, the Change Stream fires instantly, and the agent receives the data instantly.

In the code below, checkout is protected by an atomic inventory update. The function looks for a product with the requested sku and enough remaining quantity, then decrements the quantity in the same database operation. If another customer has already purchased the last unit, the query no longer matches, and MongoDB returns None, so the checkout flow can stop before confirming the item is unavailable. Using ReturnDocument.AFTER returns the updated inventory document, giving the agent the freshest committed state after the reservation succeeds.

from pymongo import MongoClient, ReturnDocument

client = MongoClient(MONGODB_URI)
inventory = client["ecommerce"]["inventory"]


def reserve_inventory(sku: str, quantity: int = 1):
    """Atomically reserve inventory during checkout."""
    updated_product = inventory.find_one_and_update(
        {
            "sku": sku,
            "quantity": {"$gte": quantity},
        },
        {
            "$inc": {"quantity": -quantity},
        },
        return_document=ReturnDocument.AFTER,
    )

    if updated_product is None:
        raise ValueError(f"Product {sku} is no longer available.")

    return updated_product

In the code below, Change Streams detect when a product's inventory drops to zero. That event kicks off a CrewAI workflow: an inventory recovery agent finds active carts that still contain the sold-out SKU, suggests alternatives, and notifies affected customers. MongoDB handles the real-time event stream, while CrewAI handles the agent’s reasoning and tool orchestration.

from pymongo import MongoClient
from crewai import Agent, Task, Crew, Process
from crewai.tools import tool

client = MongoClient(MONGODB_URI)
inventory = client["ecommerce"]["inventory"]


@tool("Find active sessions with SKU")
def find_active_sessions_with_sku(sku: str) -> list[str]:
    """Find active shopping sessions that currently have this SKU in cart."""
    # Replace with a query against your sessions/carts collection.
    return []


@tool("Suggest alternative product")
def suggest_alternative(sku: str) -> str:
    """Suggest a similar in-stock product for the provided SKU."""
    # Replace with MongoDB Vector Search or product recommendation logic.
    return f"Suggested replacement for {sku}"


@tool("Notify customer")
def notify_customer(session_id: str, message: str) -> str:
    """Send a message to a customer shopping session."""
    # Replace with chat, email, SMS, or app notification logic.
    return f"Queued notification for {session_id}"


stock_recovery_agent = Agent(
    role="Inventory recovery specialist",
    goal=(
        "Recover active shopping sessions when a product sells out by finding "
        "affected carts, suggesting alternatives, and notifying customers."
    ),
    backstory=(
        "You support an e-commerce shopping agent. When inventory changes, "
        "you help customers continue checkout with the least possible friction."
    ),
    tools=[
        find_active_sessions_with_sku,
        suggest_alternative,
        notify_customer,
    ],
    llm="gpt-4o",
)

stock_recovery_task = Task(
    description=(
        "Product {sku} just sold out. Find active sessions that still have "
        "this item in cart, suggest suitable alternatives, and notify each "
        "affected customer clearly."
    ),
    expected_output=(
        "A summary of affected sessions, suggested alternatives, and customer "
        "notifications that were queued."
    ),
    agent=stock_recovery_agent,
)

stock_recovery_crew = Crew(
    agents=[stock_recovery_agent],
    tasks=[stock_recovery_task],
    process=Process.sequential,
)

pipeline = [
    {
        "$match": {
            "operationType": "update",
            "fullDocument.quantity": 0,
        }
    }
]

with inventory.watch(pipeline, full_document="updateLookup") as stream:
    for event in stream:
        product = event["fullDocument"]
        sku = product["sku"]

        stock_recovery_crew.kickoff(
            inputs={
                "sku": sku,
            }
        )

Step 5: How do Atlas Triggers and Atlas Stream Processing help with Post-purchase intelligence?

The post-purchase stage is where most shopping agents stop short. A customer who has paid expects to be kept informed without having to ask. That means the agent needs to respond when order data changes, especially when a shipment enters a state that matters to the customer.

Atlas Triggers: Reacting to individual order events

When an order’s status changes to "shipped", that update is a committed database event. Atlas Triggers are a fully managed way to react to that event: Atlas opens and maintains the underlying change stream, applies your trigger filter, and invokes a serverless function when a matching order update occurs.

In the code below, the Trigger is configured on the orders collection to run only when an order status changes to "shipped", with full-document lookup enabled for update events. The function receives the updated order document through changeEvent.fullDocument builds a JSON request body with API-friendly values, then sends it to the post-purchase agent endpoint.

From there, the agent can pull the customer’s order history, anticipate likely follow-up questions such as delivery window, return policy, and product setup, and prepare a personalized response so the next customer interaction feels informed and seamless.

// Atlas Trigger Function — fires when an order status changes to "shipped"
exports = async function(changeEvent) {
  const order = changeEvent.fullDocument;

  if (!order || order.status !== "shipped") {
    return { skipped: true };
  }

  const response = await context.http.post({
    url: "https://your-agent-endpoint.com/post-purchase",
    body: {
      customerId: order.customerId,
      orderId: order._id.toString(),
      product: order.product,
      estimatedDelivery: order.estimatedDelivery
    },
    encodeBodyAsJSON: true
  });

  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw new Error(
      `Post-purchase agent request failed with status ${response.statusCode}`
    );
  }

  return {
    ok: true,
    orderId: order._id.toString(),
    statusCode: response.statusCode
  };
};

Atlas Stream Processing: Detecting patterns before they become problems

Some post-purchase issues don't surface as a single event but emerge as a pattern. A carrier delay affecting multiple orders in the same region, such as due to an unexpected weather event, doesn't appear as a single document change. It shows up as a sustained pattern of delivery estimates shifting across an order cohort.

Atlas Stream Processing runs continuous aggregation pipelines over your order data and surfaces confirmed patterns before they reach customers. As illustrated in the code below, Atlas Stream Processing monitors delivery-estimate updates in the orders collection. Each update represents one order whose delivery date changed, but a single delayed order usually is not enough to involve an agent. The processor first filters for meaningful delays, such as orders whose estimated delivery time has moved by 30 minutes or more, then waits for a two-minute tumbling window to evaluate a batch of recent updates together.

Within each window, it groups delayed orders by carrier and shippingRegion. If at least 10 orders in the same carrier-region cohort are delayed, and the average delay across that group is at least 45 minutes, the processor writes one confirmed signal to agent_triggers.

A separate Change Stream can then watch that collection and invoke the demand-management agent. Then, the demand management agent can proactively draft customer communications, alert the logistics team, and flag the issue for resolution before customers start calling about missing orders. Imagine how many fewer calls your customer support team will receive if customers are proactively informed about shipping delays.

[
  {
    "$source": {
      "connectionName": "mongodb-atlas",
      "db": "ecommerce",
      "coll": "orders",
      "fullDocument": "updateLookup",
      "pipeline": [
        {
          "$match": {
            "operationType": "update",
            "updateDescription.updatedFields.estimatedDelivery": {
              "$exists": true
            }
          }
        }
      ]
    }
  },
  {
    "$replaceRoot": {
      "newRoot": "$fullDocument"
    }
  },
  {
    "$match": {
      "status": {
        "$in": ["shipped", "in_transit"]
      },
      "carrier": {
        "$exists": true
      },
      "shippingRegion": {
        "$exists": true
      },
      "originalEstimatedDelivery": {
        "$exists": true
      },
      "estimatedDelivery": {
        "$exists": true
      }
    }
  },
  {
    "$addFields": {
      "delayMinutes": {
        "$dateDiff": {
          "startDate": "$originalEstimatedDelivery",
          "endDate": "$estimatedDelivery",
          "unit": "minute"
        }
      }
    }
  },
  {
    "$match": {
      "delayMinutes": {
        "$gte": 30
      }
    }
  },
  {
    "$tumblingWindow": {
      "boundary": "processingTime",
      "interval": {
        "size": 2,
        "unit": "minute"
      },
      "pipeline": [
        {
          "$group": {
            "_id": {
              "carrier": "$carrier",
              "region": "$shippingRegion",
              "windowStart": {
                "$meta": "stream.window.start"
              }
            },
            "affectedOrderCount": {
              "$sum": 1
            },
            "averageDelayMinutes": {
              "$avg": "$delayMinutes"
            },
            "maxDelayMinutes": {
              "$max": "$delayMinutes"
            },
            "affectedOrders": {
              "$push": "$_id"
            }
          }
        }
      ]
    }
  },
  {
    "$match": {
      "affectedOrderCount": {
        "$gte": 10
      },
      "averageDelayMinutes": {
        "$gte": 45
      }
    }
  },
  {
    "$project": {
      "_id": {
        "$concat": [
          "delivery-delay:",
          "$_id.carrier",
          ":",
          "$_id.region",
          ":",
          {
            "$toString": "$_id.windowStart"
          }
        ]
      },
      "type": "delivery_delay_pattern",
      "severity": "warning",
      "carrier": "$_id.carrier",
      "region": "$_id.region",
      "windowStart": "$_id.windowStart",
      "affectedOrderCount": 1,
      "averageDelayMinutes": {
        "$round": ["$averageDelayMinutes", 0]
      },
      "maxDelayMinutes": 1,
      "affectedOrders": {
        "$slice": ["$affectedOrders", 25]
      },
      "agentAction": "draft_customer_delay_notice"
    }
  },
  {
    "$merge": {
      "into": {
        "connectionName": "mongodb-atlas",
        "db": "ecommerce",
        "coll": "agent_triggers"
      },
      "on": "_id",
      "whenMatched": "replace",
      "whenNotMatched": "insert"
    }
  }
]

Decision framework: How to choose the right event-driven service?

The decision framework below helps you choose the right event-driven service for your use case:

Figure 1. Choosing between Change Streams, Atlas Triggers, and Atlas Stream Processing based on your agent's use case.

Conclusion

Building a fully agentic shopping experience requires more than a good model and a well-tuned prompt. Every step of the journey, from product discovery to post-purchase follow-up, places real demands on the underlying data platform. The agent needs to retrieve semantically relevant products, confirm inventory at the moment of purchase, and react to order events without waiting to be asked.

Most teams solve this by assembling a stack of specialized systems: a search service, a vector database, a message broker, event processing infrastructure, and an operational database underneath it all. That architecture can work, but every handoff adds latency, synchronization headaches, operational overhead, and another point where data can drift from reality. For an agent that needs to reason and act in the moment, those gaps mean the agent fails to provide customers with valuable information when needed. Not because there is anything wrong with the agent, but because the data it relied on was outdated.

MongoDB consolidates these into a single platform. Vector Search, MongoDB Search, Change Streams, Atlas Triggers, and Atlas Stream Processing are all native features of the same cluster that holds your operational data. The agent works with data that reflects the world as it actually is, and the architecture stays simple enough to debug when something inevitably needs attention.

Build your first agent with MongoDB and CrewAI

If you want to put this into practice, MongoDB has an official integration with CrewAI. Use this GitHub repository to start building your E-commerce AI agents on MongoDB.

If you are already running on MongoDB Atlas, you have everything you need to get started. Sign up for MongoDB Atlas and follow the CrewAI integration tutorial to deploy your first e-commerce agent today.

Building a Vibe-Based Music Recommender with MongoDB and Voyage AI

Jordan Smith — Tue, 14 Jul 2026 14:08:37 +0000

Have you ever found yourself in the mood for a certain type of music but not any specific artists, songs, or genres in mind? Maybe you just had a long day and are looking for something with mellow and relaxing vibes. Or maybe it's a Friday afternoon, and you're ready for something to pump you up for the weekend. In times like these, traditional search experiences won't work. But today, we're going to build something that will.

In a traditional search experience, you would search for a term and get back a list of songs or artists that contain keywords from that search term somewhere in their name or description. But that's not what we want here. What we actually want is semantic search: a system that understands what you mean, not just what you typed. That's exactly what we're building. This music recommender takes a natural-language description of the music's “vibe” and finds songs that match that feel. And it's all powered by MongoDB Vector Search and Voyage AI.

In this tutorial, you’ll learn how to build a working web application where you can type something like "upbeat road trip with the windows down" and get back a ranked list of songs that fit that feeling. Let's get into it!

How It Actually Works

Before we write any code, let's go through a quick overview of how the search functionality in this app actually works.

The key to all of this is vector embeddings. A vector embedding is a way of representing text (or other data like images or audio) as an array of numbers, or vectors. Data with similar semantic meanings produces similar vectors, so you can compare all of your vectors mathematically to find data that's similar in meaning.

Here's how it actually works in this app:

Every song in our sample collection has an LLM-generated "vibe description". This is a 2-3 sentence description of what the song "feels" like to listen to. Vector embeddings were generated from these descriptions using Voyage AI and are stored with the songs.
When a user types a search query, it is converted into a vector using the same Voyage AI vector embedding model.
We use MongoDB Vector Search to find the songs in the collection whose vectors are closest to the query vector.
The results are returned to the user, ranked by how closely their vector matches the query vector.

Full Project Code

If you want to see the full project with all of the code already written, you can find it on GitHub. I'll explain all the elements throughout this tutorial, and you can clone the repository and follow along as well.

Prerequisites

Before getting started, you'll need a few things in place:

Node.js (v18 or later) installed on your machine
A MongoDB Atlas account with a free cluster
A Voyage AI API key - you can get one from the MongoDB Atlas UI

Project Setup

With that out of the way, let’s get going with the actual code.

Start by creating a new project directory and initializing it:

mkdir music-recommender
cd music-recommender
npm init -y

Then install the dependencies:

npm install express mongodb voyageai dotenv

Create a .env file in the root of your project with the following variables:

MONGODB_URI=<Your MongoDB Connection String>
MONGODB_DATABASE=song_vibe_search

VOYAGE_API_KEY=<Your Voyage AI API Key>

Next, you'll need to download the seed files. These files contain scripts that will initialize your database by using sample data. The scripts also contain code that you can use to generate your own descriptions and embeddings, but we won't get into that until the Deeper Dive: Generating Embeddings section at the end of the tutorial.

The sample data is a small sample of 500 songs from the Free Music Archive with pre-generated "vibe descriptions" and embeddings. You can download the seed files from the /seed directory in the GitHub repository for this tutorial.

After you have downloaded the seed folder, place it at the root of your project. Then run the following command to connect to your, insert the seed data, and create a vector search index:

npm run seed

This creates a new database called song_vibe_search and a new collection called songs. The song collection contains 500 documents, each representing a song with a "vibe description" and an embedding vector. It also creates a vector search index on the embedding field by running the following code:

await collection.createSearchIndex({
    name: VECTOR_INDEX_NAME,
    type: "vectorSearch",
    definition: {
    fields: [
        {
        type: "vector",
        path: "embedding",
        numDimensions: 512,
        similarity: "cosine",
        },
    ],
    },
});

This is what makes $vectorSearch possible. We need to tell MongoDB the shape of our embedding field so it can build the right index structure.

The index contains the type of index (in our case, vector), the path to the field, and the following parameters that tell MongoDB how to compare vectors:

numDimensions: 512 — This must match the output size of your embedding model. Voyage AI's voyage-3-lite\ model produces 512-dimensional vectors. If you're using a different model, you should be able to find the number of dimensions in the documentation for your model.
similarity: "cosine" — This is the distance metric used to compare vectors. Cosine similarity works well for text embeddings because it measures the angle between vectors rather than their raw distance, which makes it robust to differences in text length.

Now that we have our data and our vector search index, we are ready to build the main application.

Implementing Vector Search

In the root of your project, create a new directory called src and create a new file called server.ts in that directory. This is where we will implement the search logic that powers our recommendations.

First, we need to set our imports, our interfaces and constants, and establish our connection to MongoDB. Paste the following code into server.ts:

import "dotenv/config";
import { MongoClient } from "mongodb";
import { VoyageAIClient } from "voyageai";

const MONGODB_URI = process.env.MONGODB_URI;
const VOYAGE_API_KEY = process.env.VOYAGE_API_KEY;

if (!MONGODB_URI) {
  throw new Error(
    "Missing MONGODB_URI in environment. Ensure that you have created a .env file and added your connection string."
  );
}

if (!VOYAGE_API_KEY) {
  throw new Error(
    "Missing VOYAGE_API_KEY in environment. Ensure that you have created a .env file and added your Voyage AI key."
  );
}

export const client = new MongoClient(MONGODB_URI, {
  appName: "devrel-tutorial-javascript-music-recommender",
});

const voyage = new VoyageAIClient({ apiKey: VOYAGE_API_KEY });

const DB_NAME = process.env.MONGODB_DATABASE ?? "song_vibe_search";
const COLLECTION_NAME = "songs";
export const VECTOR_INDEX = "vibe_vector_index";
const EMBEDDING_MODEL = "voyage-3-lite";
export const NUM_RESULTS = 5;
export const NUM_CANDIDATES = 100;

export interface SearchResult {
  title: string;
  artist: string;
  genre_top: string;
  genres: string[];
  score: number;
}

export interface SearchResponse {
  results: SearchResult[];
  queryVector: number[];
}

If you're unfamiliar with vector search, some of the constants above may not make sense quite yet, but we'll explain them more as they're used.

Embedding the query

When a user submits a search, the first thing we need to do is embed that query by using the same Voyage AI model that was used to embed our song descriptions. Paste the following code into server.ts to create a search function and embed the query. Note the comment that shows where we will add the vector search query code in a later step.

export async function searchSongs(query: string): Promise<SearchResponse> {

  // Embed the user's query by using Voyage AI.
  const embedResponse = await voyage.embed({
    model: EMBEDDING_MODEL,
    input: [query],
    inputType: "query",
  });

  const queryVector = embedResponse.data![0].embedding!;

  // vector search query code here
}

This code specifies a few things. First, we specify the embedding model to use (in our case, we pass in the constant that we set earlier). We then pass the actual user query as an array to the input parameter. Finally, we specify the inputType as "query". Voyage AI distinguishes between the following two types of input:

"document" — used when embedding data that gets saved into your database (the song vibe descriptions, in our case)
"query" — used when embedding a search query at runtime

Using the right input type improves retrieval quality. It's a small but important thing to keep in mind when implementing vector search applications.

Now that we have our query embedded, it's time to use it to search for similar songs. Paste the following code to complete our search function. Ensure that this code is pasted inside the function that we defined in the previous code block.

  // ... previous embedding code here

  // vector search query code here 
  const collection = client.db(DB_NAME).collection(COLLECTION_NAME);

  const results = await collection
    .aggregate<SearchResult>([
      {
        $vectorSearch: {
          index: VECTOR_INDEX,
          path: "embedding",
          queryVector,
          numCandidates: NUM_CANDIDATES,
          limit: NUM_RESULTS,
        },
      },
      {
        $project: {
          _id: 0,
          title: 1,
          artist: 1,
          genre_top: 1,
          genres: 1,
          score: { $meta: "vectorSearchScore" },
        },
      },
    ])
    .toArray();

  return { results, queryVector };

To implement vector search, we use the $vectorSearch stage of the aggregation pipeline. The $vectorSearch stage takes the following parameters:

index — The name of the vector search index we created during seeding
path — The field in the document that holds the embedding (in this case, named "embedding").
queryVector — The vector we just generated from the user's query.
numCandidates — How many candidate documents to consider before ranking. A higher number means the search will be more thorough but slower.
limit — How many results to return.

After the search stage, a $project stage shapes our output, with { $meta: "vectorSearchScore" } pulling in the similarity score for each result — a number between 0 and 1, where higher means more similar.

And that's all we need for our search functionality! Next, we'll build out a simple server with an endpoint to call this function.

Building the Server

Create a new file called server.ts in the src directory. This is where we will create any endpoints we might need. In this tutorial, we will create a single endpoint to search for songs.

To start, paste the following code into server.ts, which specifies the imports and sets up an Express server:

import "dotenv/config";
import express from "express";
import path from "path";
import { client, searchSongs, VECTOR_INDEX, NUM_RESULTS, NUM_CANDIDATES } from "./search";

const app = express();
const PORT = process.env.PORT ?? 3000;

app.use(express.json());
app.use(express.static(path.join(__dirname, "../public")));

Now, we'll create our POST route that calls the searchSongs function we created earlier. Paste the following code into server.ts:

app.post("/api/search", async (req, res) => {
  const { query } = req.body;

  if (!query || typeof query !== "string" || query.trim() === "") {
    res.status(400).json({ error: "A search query is required." });
    return;
  }

  let results, queryVector;
  try {
    ({ results, queryVector } = await searchSongs(query.trim()));
  } catch (err) {
    console.error("Search failed:", err);
    res.status(500).json({ error: "Search failed. Please try again." });
    return;
  }

  res.json({
    results
  });
});

In the preceding code, it first checks that the query is valid. Then it sends the query to our searchSongs() function and returns the results. If there is an error, it returns an error message.

The last thing we need to do is write the code that actually starts the server and handles signals to close the client cleanly on shutdown. Paste the following code into server.ts:

async function startServer() {
  await client.connect();
  console.log("Connected to MongoDB Atlas.");

  app.listen(PORT, () => {
    console.log(`Server running at http://localhost:${PORT}`);
  });

  process.on("SIGINT", async () => {
    await client.close();
    process.exit(0);
  });

  process.on("SIGTERM", async () => {
    await client.close();
    process.exit(0);
  });
}

startServer();

Now that we have our server set up, let's create a simple front end to interact with it.

Building the Front End

Since the purpose of this tutorial is the search functionality itself, we'll keep the front end simple. Create a new directory called public in the root of your project (it's important to keep the name as public since our server is already set up to serve files from this directory). Then, create a new file called index.html in that folder.

Paste the following code into index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vibe Search</title>
    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
    <div class="container">
      <header>
        <h1>Vibe Search</h1>
        <p>Describe a mood or feeling and we'll find songs that match.</p>
      </header>

      <form id="search-form">
        <input
          id="query-input"
          type="text"
          placeholder="e.g. melancholy rainy afternoon, upbeat road trip..."
          autocomplete="off"
        />
        <button type="submit">Search</button>
      </form>
      <p class="token-note">Note: Each search generates a Voyage AI embedding and consumes tokens.</p>

      <div id="results"></div>
    </div>

    <script src="app.js"></script>
  </body>
</html>

This HTML creates a simple page with a header, an input box, and a section for results.

Now we need to create the style.css and app.js files. Create a new file called style.css in the public directory and paste the following code into it:

*, *::before, *::after {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
  background: #0f0f0f;
  color: #e8e8e8;
  min-height: 100vh;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  padding: 2rem 1rem;
}

.container {
  width: 100%;
  max-width: 720px;
}

header {
  text-align: center;
  margin-bottom: 2.5rem;
}

header h1 {
  font-size: 2.5rem;
  font-weight: 700;
  letter-spacing: -0.5px;
  margin-bottom: 0.5rem;
}

header p {
  color: #777;
  font-size: 1rem;
}

/* ── Search form ── */

#search-form {
  display: flex;
  gap: 0.5rem;
  margin-bottom: 2.5rem;
}

#query-input {
  flex: 1;
  padding: 0.75rem 1rem;
  font-size: 1rem;
  background: #1a1a1a;
  border: 1px solid #333;
  border-radius: 8px;
  color: #e8e8e8;
  outline: none;
}

#query-input:focus {
  border-color: #555;
}

#query-input::placeholder {
  color: #555;
}

#search-form button {
  padding: 0.75rem 1.5rem;
  font-size: 1rem;
  font-weight: 600;
  background: #00ed64;
  color: #000;
  border: none;
  border-radius: 8px;
  cursor: pointer;
}

#search-form button:hover {
  background: #00c853;
}

/* ── Token note ── */

.token-note {
  font-size: 1rem;
  color: #989898;
  text-align: center;
  margin-top: 0.6rem;
  margin-bottom: 0;
}

/* ── Spinner ── */

.spinner {
  width: 28px;
  height: 28px;
  border: 3px solid #2a2a2a;
  border-top-color: #00ed64;
  border-radius: 50%;
  margin: 2rem auto;
  animation: spin 0.7s linear infinite;
}

@keyframes spin {
  to { transform: rotate(360deg); }
}

/* ── Result cards ── */

#results {
  display: flex;
  flex-direction: column;
  gap: 1rem;
}

.card {
  background: #1a1a1a;
  border: 1px solid #2a2a2a;
  border-radius: 12px;
  overflow: hidden;
}

.card-color-bar {
  height: 6px;
}

.card-body {
  padding: 1.25rem 1.5rem;
}

.card-title {
  font-size: 1.1rem;
  font-weight: 600;
  margin-bottom: 0.2rem;
}

.card-artist {
  color: #777;
  font-size: 0.9rem;
  margin-bottom: 0.85rem;
}

.tags {
  display: flex;
  flex-wrap: wrap;
  gap: 0.35rem;
  margin-bottom: 1rem;
}

.tag {
  font-size: 0.75rem;
  padding: 0.2rem 0.65rem;
  border-radius: 999px;
  background: #252525;
  color: #999;
}

.card-footer {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.score {
  font-size: 0.8rem;
  color: #555;
}

.fma-link {
  font-size: 0.8rem;
  color: #00ed64;
  text-decoration: none;
}

.fma-link:hover {
  text-decoration: underline;
}

.message {
  text-align: center;
  color: #555;
  padding: 2rem 0;
  font-size: 0.95rem;
}

.message.error {
  color: #e05252;
}

The CSS added here is outside of the scope of this tutorial, but it just makes the app easier to look at and use.

The last file we need to create is app.js, which contains the front-end JavaScript code. Create a new file called app.js in the public directory and paste the following code into it:

const DEFAULT_GRADIENT = "linear-gradient(135deg, #434343, #1a1a1a)";

function renderResults(results) {
  const container = document.getElementById("results");

  if (results.length === 0) {
    container.innerHTML = '<p class="message">No results found. Try a different vibe.</p>';
    return;
  }

  container.innerHTML = results.map((result) => {
    const score = Math.round(result.score * 100);
    const tags = result.genres.map((g) => `<span class="tag">${g}</span>`).join("");

    return `
      <div class="card">
        <div class="card-color-bar" style="background: ${DEFAULT_GRADIENT}"></div>
        <div class="card-body">
          <div class="card-title">${result.title}</div>
          <div class="card-artist">${result.artist}</div>
          <div class="tags">${tags}</div>
          <div class="card-footer">
            <span class="score">Match: ${score}%</span>
            <a class="fma-link" href="https://www.youtube.com/results?search_query=${encodeURIComponent(result.title + ' ' + result.artist)}" target="_blank" rel="noopener">Find on YouTube →</a>
          </div>
        </div>
      </div>
    `;
  }).join("");
}

document.getElementById("search-form").addEventListener("submit", async (e) => {
  e.preventDefault();

  const query = document.getElementById("query-input").value.trim();
  if (!query) return;

  const container = document.getElementById("results");
  container.innerHTML = '<div class="spinner"></div>';

  const response = await fetch("/api/search", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query }),
  });

  if (!response.ok) {
    container.innerHTML = '<p class="message error">Something went wrong. Please try again.</p>';
    return;
  }

  const { results } = await response.json();
  renderResults(results);
});

This JavaScript code adds interactivity to the page. It sends the search query to the server and displays the search results.

Running the App

At this point, you should have everything set up. Make sure you have already run the npm run seed\ command from earlier in the tutorial.

Then, run the following command to start the server:

npm run dev

Open http://localhost:3000 and try a few searches, such as:

- "melancholy rainy afternoon"

- "high energy workout, aggressive beats"

- "peaceful background music for focusing"

You should see the results ranked by similarity score, with a link to YouTube so you can listen to the songs (if they're uploaded there). In a real application, you would want to serve the audio files or link directly to a streaming service, but for the sample data we're using here, searching YouTube is the only free option without license limitations. If you want to expand on this with different music, check out APIs for streaming services like Spotify.

Next Steps

And that's the basics! You've now built a working music recommender that uses MongoDB Vector Search and Voyage AI to find songs based on their "vibe". There are lots of ways you can expand on this as well. You could modify this to use music from different sources, expand the search functionality to include other metadata or filtering options, or even implement user profiles so that you can create personalized playlists and recommendations based on their likes, dislikes, and listening habits.

In the last section of this tutorial, we'll go through how the data for this tutorial was embedded. This can be useful if you're interested in adapting this tutorial to use your own data, or if you just want to learn more about working with vector embeddings.

Deeper Dive: Generating Embeddings {#deeper-dive:-generating-embeddings}

If you look at the GitHub repo, you'll notice that there are a few files in the seed directory that we didn't use in this tutorial. The fetchTracks.ts file contains code for downloading metadata about the songs that were downloaded from the Free Music Archive. This file will be specific to the Free Music Archive data, so we won't go into depth on it here.

The generateVibeDescriptions.ts and generateEmbeddings.ts files contain the code used to generate the "vibe descriptions" and embeddings for the sample data. The generateVibeDescriptions.ts file uses the Gemini API to generate a text description of the "vibe" of each song. The generateEmbeddings.ts file uses the Voyage AI API to generate an embedding for each description.

Generating Vibe Descriptions

Before generating embeddings from our data, we need some kind of description to embed. Raw metadata like title, artist, and genre isn't rich enough to embed meaningfully on its own, so we use Google Gemini to generate a 2-3 sentence vibe description for each track. Then, we save these descriptions in a new field in our documents called vibe_description.

To run the code to generate the descriptions, you'll need to get a Gemini API key. You can do this by going to the AI Studio and creating a new project. Then, add your API key to the .env file:

GEMINI_API_KEY=<Your Gemini API Key>

Then, create a file in the seed directory called generateVibeDescriptions.ts and paste the following code into it:

import "dotenv/config";
import { GoogleGenAI } from "@google/genai";
import type { RawTrack } from "./fetchTracks";

const GEMINI_API_KEY = process.env.GEMINI_API_KEY;
const GEMINI_MODEL = "gemini-3-flash-preview";
const BATCH_SIZE = 50;

export interface TrackWithVibe extends RawTrack {
  vibe_description: string;
}

function buildPrompt(tracks: RawTrack[]): string {
  const trackList = tracks
    .map(
      (t, i) =>
        `${i + 1}. Title: "${t.title}" | Artist: "${t.artist}" | Album: "${t.album}" | Genres: ${t.genres.join(", ")}`
    )
    .join("\n");

  return `For each track listed below, write a 2-3 sentence vibe description in third person. Focus on mood, energy, atmosphere, and ideal listening context. Avoid simply restating the genre — describe how it feels to listen to it. Return a JSON array of strings, one description per track, in the same order as the input. Return only the JSON array with no additional text. Tracks: ${trackList}`;
}

function parseResponse(text: string): string[] {
  // Extract the JSON array by finding the outermost [ ... ] bounds.
  // This handles cases where the model adds explanatory text before or after the JSON.
  const start = text.indexOf("[");
  const end = text.lastIndexOf("]");
  if (start === -1 || end === -1 || end < start) {
    throw new Error(`No JSON array found in model response:\n${text}`);
  }
  return JSON.parse(text.slice(start, end + 1));
}

export async function generateVibeDescriptions(
  tracks: RawTrack[]
): Promise<TrackWithVibe[]> {
  if (!GEMINI_API_KEY) {
    throw new Error(
      "GEMINI_API_KEY is not set. Add it to your .env file.\n" +
      "Get a free key at: https://aistudio.google.com/apikey"
    );
  }

  const ai = new GoogleGenAI({ apiKey: GEMINI_API_KEY });
  const results: TrackWithVibe[] = [];
  const totalBatches = Math.ceil(tracks.length / BATCH_SIZE);

  console.log(`\nGenerating vibe descriptions via Gemini (${totalBatches} batches)...`);

  for (let i = 0; i < tracks.length; i += BATCH_SIZE) {
    const batch = tracks.slice(i, i + BATCH_SIZE);
    const batchNum = Math.floor(i / BATCH_SIZE) + 1;

    console.log(`  Batch ${batchNum}/${totalBatches}`);

    const response = await ai.models.generateContent({
      model: GEMINI_MODEL,
      contents: buildPrompt(batch),
    });

    const descriptions = parseResponse(response.text ?? "");

    if (descriptions.length !== batch.length) {
      throw new Error(
        `Batch ${batchNum}: expected ${batch.length} descriptions, got ${descriptions.length}`
      );
    }

    for (let j = 0; j < batch.length; j++) {
      results.push({ ...batch[j], vibe_description: descriptions[j] });
    }

  }

  console.log(`  ${results.length} vibe descriptions generated.`);
  return results;
}

In this code, the first function creates the prompt that we send to Gemini. The prompt is a list of all the tracks we want to generate descriptions for, along with instructions for how we want the descriptions formatted.

Then, the generateVibeDescriptions function takes our tracks and sends them to Gemini along with that prompt. Gemini will respond with a JSON array of strings, each of which is a vibe description for a track. We parse the response (and strip any extraneous text that Gemini might have added) and return the tracks with their new descriptions.

Generating Embeddings

Now that we have our vibe descriptions, we can generate embeddings for them. To do this, we use the same Voyage AI model that we used to embed our search queries earlier in the tutorial. This process is very similar to the process that we use to embed our search queries.

Create a file in the seed directory called generateEmbeddings.ts and paste the following code into it:

import "dotenv/config";
import { VoyageAIClient } from "voyageai";
import type { TrackWithVibe } from "./generateVibeDescriptions";

const EMBEDDING_MODEL = "voyage-3-lite";

export interface TrackWithEmbedding extends TrackWithVibe {
  embedding: number[];
}

export async function generateEmbeddings(
  tracks: TrackWithVibe[]
): Promise<TrackWithEmbedding[]> {
  const VOYAGE_API_KEY = process.env.VOYAGE_API_KEY;
  if (!VOYAGE_API_KEY) {
    throw new Error("Missing VOYAGE_API_KEY in environment");
  }

  const voyage = new VoyageAIClient({ apiKey: VOYAGE_API_KEY });

  console.log(`\nGenerating embeddings for ${tracks.length} tracks...`);

  const response = await voyage.embed({
    model: EMBEDDING_MODEL,
    input: tracks.map((t) => t.vibe_description),
    inputType: "document",
  });

  const results: TrackWithEmbedding[] = [];

  for (let i = 0; i < tracks.length; i++) {
    const embeddingData = response.data?.[i];
    if (!embeddingData?.embedding) {
      console.warn(`  Warning: no embedding returned for "${tracks[i].title}" — skipping`);
      continue;
    }
    results.push({ ...tracks[i], embedding: embeddingData.embedding });
  }

  console.log(`  ${results.length} embeddings generated.`);
  return results;
}

The main difference in embedding this data is that we specify the input type as "document" rather than "query". This distinction is important when embedding data with Voyage AI, as it embeds the data slightly differently depending on the type you specify.

Putting It All Together

Now that we have the code to generate descriptions and embeddings, we need to run it when seeding our data. To do so, we just need to modify the index.ts file in the seed directory and call the functions before inserting the data into the database. It will look something like this:

const tracksWithVibes = await generateVibeDescriptions(rawTracks);

const tracksWithEmbeddings = await generateEmbeddings(tracksWithVibes);

const documents = tracksWithEmbeddings.map((track) => ({
...track,
seeded_at: new Date(),
}));

console.log(`\nInserting ${documents.length} documents into MongoDB...`);
await collection.insertMany(documents);

Note that you will likely have to modify the code you created earlier so that the flow of the seed script doesn't insert multiple times (since we originally set it up to use pre-built data).

Now, run the seed command again, and you should see the script generate descriptions and embeddings for the data before inserting it into the database. Then you can run the app again to try searching through the data.

Conclusion

You have now built a fully functional application that uses MongoDB Vector Search and Voyage AI to recommend music based on their general “vibes.” While this app is pretty simple and provides only basic functionality, you can easily use it as a baseline to build much more sophisticated applications.

Hopefully, this gives you some insight into just how powerful MongoDB Vector Search can be. If you want to learn more, check out our documentation or leave a comment letting me know how you’d like to see this expanded on!

How To Build A React App Using React Router v6 Without create-react-app

Jordan Smith — Tue, 14 Dec 2021 17:10:33 +0000

Recently I found myself in the position of needing to start a new React app from scratch, but due to anticipation for future needs of the app it was decided that we wouldn't be using create-react-app. But unfortunately, create-react-app is the only way I knew how to get a React project started. I also knew that we needed to use React Router in the app, and it just so happened that a new version was just released. So off to the internet I went, looking for a tutorial on getting started. I found some helpful links and articles, but I also found that I had to pull different steps from different areas in order to get a process that actually worked together with my setup and versioning. So in the interest of helping the next dev in my position, I decided to document the process I used. Hopefully this will make it much quicker and easier for whoever is reading this today.

To start off, create a new folder and give it a name (this will end up being the name of the app). Open up the folder and in a terminal type the following command:

npm init -y

You should see something similar to the following output

Next you'll create a "dist" folder at the root of your application. In that folder, create a file called index.html. This will be the initial starting HTML file for your application. Copy the following boilerplate into that file.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Sample React App</title>
</head>
<body>
    <div id="app"></div>
    <script src="bundle.js"></script>
</body>
</html>

You'll notice that inside the body tags there is a div with an id of "app." This is the div that you will eventually reference when telling React where to render everything. You can name it whatever you want, just make sure when you are referencing later on you use the same id the one you specify here.

Next, we'll install the React dependencies, Webpack and Babel. These are the core dependencies you'll need for a basic React app.

npm i react react dom
npm i --save-dev @babel/preset-env react-hot-loader webpack webpack-cli webpack-dev-server @babel/core @babel/preset-react babel-loader

Now we'll install React Router at version 6.

npm i react-router-dom@6

Now that everything is installed, we'll add a script allowing us to start the application from the terminal. In package.json, add the following code to the "scripts" section.

"start": "webpack serve --config ./webpack.config.js --mode development --port 3000"

Your package.json should now look like this:

{
  "name": "sample-react-app",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "webpack serve --config ./webpack.config.js --mode development --port 3000"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "dom": "^0.0.3",
    "react": "^17.0.2"
  },
  "devDependencies": {
    "@babel/core": "^7.16.0",
    "@babel/preset-env": "^7.16.4",
    "@babel/preset-react": "^7.16.0",
    "babel-loader": "^8.2.3",
    "react-hot-loader": "^4.13.0",
    "webpack": "^5.65.0",
    "webpack-cli": "^4.9.1",
    "webpack-dev-server": "^4.6.0"
  }
}

Next we need to set some Babel presets. In your root directory create a file called .babelrc and put in the following code:

{
    "presets": ["@babel/preset-env", "@babel/preset-react"]
}

Now we'll specify our Webpack presets. Create another file in the root directory called webpack.config.js and put in the following:

const webpack = require("webpack");
const path = require("path");

module.exports = {
  entry: path.resolve(__dirname, "./src/index.js"),
  module: {
    rules: [
      {
        test: /\.(js|jsx|ts|tsx)$/,
        exclude: /node_modules/,
        use: ["babel-loader"],
      },
    ],
  },
  resolve: {
    extensions: ["*", ".js", ".jsx", ".ts", ".tsx"],
  },
  output: {
    path: path.resolve(__dirname, "./dist"),
    filename: "bundle.js",
  },
  plugins: [new webpack.HotModuleReplacementPlugin()],
  devServer: {
    static: path.resolve(__dirname, "./dist"),
    hot: true,
    historyApiFallback: true,

  },
};

Note: if you are not using typescript in your app you can omit the all references to "ts" and "tsx" (found under resolve.extensions and module.rules.test).

Now we'll create our root React app file. Create a src folder at your root directory and inside make a new file called app.jsx. This will contain the following (I'll explain what all of this is below):

import React from "react";
import { BrowserRouter, Routes, Route, Outlet } from "react-router-dom";

const App = () => {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Layout />}>
          <Route index element={<Home />} />
          <Route path="about" element={<About />} />
          <Route path="contact" element={<Contact />} />
          <Route path="*" element={<h2>Page Not Found</h2>} />
        </Route>
      </Routes>
    </BrowserRouter>
  );
};

export default App;

const Layout = () => {
  return (
    <>
      <h1>Welcome to the app</h1>
      <Outlet />
    </>
  );
};

const Home = () => {
  return <h2>Home</h2>;
};

const About = () => {
  return <h2>About</h2>;
};

const Contact = () => {
  return <h2>Contact</h2>;
};

At first glance, it looks like I just threw a massive code block at you just now. But if you break it down, it's simply a component that holds a router with a couple dummy components to get started. You can see that the component is called App and in this component we return a <BrowserRouter>. This is the built in React Router component that will wrap around whatever routes you add to your app in the future.

Inside the <BrowserRouter> tag is where we will place all of our Routes. We start with a <Routes> (note the "s") tag, another React Router component, basically saying "Hey here's a bunch of different routes to look for." Then of course is the <Route> component, which is where you'll put the actual path and the component to be rendered when that path is hit. I won't go into anymore detail on how these React Router components work. Instead if you want to see a more in depth explanation on how they all work I'd recommend checking out their documentation here. Their docs are really clear and they explain things much better than I ever could.

Below that is just a couple simple dummy components, so that something will actually render when you hit each route. You'll notice that layout is the parent route, and it contains an <Outlet> that renders any children elements (again - see the official documentation for a much better explanation). These of course should be replaced once you start building out your application, and they should probably be split into their own separate files. But for ease of this tutorial I decided to put them all together so you can clearly see what's being rendered and when.

Finally you'll need to write your ReactDOM renderer component. In your src folder, create a file called index.js. Inside that you'll place the code below:

import React from "react";
import ReactDOM from "react-dom";
import App from "./app";

ReactDOM.render(<App />, document.getElementById("app"));

This code is what React uses to actually render your entire app. Notice in the document.getElementbyId, you are using the id "app" that you created in your index.html file at the beginning.

Now time to check everything out! Run the app using npm start and then in your browser navigate to localhost:3000. You should see the home screen rendered on the page. In the URL bar, add "/about" to the end of the current URL and you'll see the about page rendered. Switch that to "/contact" for the contact page. The header from layout should be shown for all routes.

And that's it! You now have a basic React app with React Router v6. This is of course only one way to do it, and I'm sure others have other methods, but this is what I've found to be simple and effective to get everything going.

I hope this helped, and saved you some time in the process! If you want to save even more time and not read through everything - although I do recommend going through the steps and typing everything yourself so you can have a good idea of what's going on - you can go to the GitHub repo here to get everything in one go.

Thanks for reading! If this article was helpful, or you have any questions or feedback, feel free to leave a comment!

6 Myths Keeping You From Becoming a Software Engineer

Jordan Smith — Wed, 08 Dec 2021 02:51:06 +0000

If you're thinking about trying to start a career as a software developer and done any kind of research into the tech industry, you've no doubt come across the countless horror stories and discouraging "facts" about how difficult it is to break into the world of software engineering.

As someone that started out my tech journey with a background in warehouses and manufacturing, with no extraordinary technical acumen, no connections to the tech community, and no college under my belt (except for a couple failed classes in the "running-start" program) - I'm here to tell you that much of what you hear is simply not true. Although it does take work, and you won't just get a coding job on a whim, there really aren't as many barriers separating you and your dream career as you might think. The world of technology is constantly evolving, and so are the requirements to working in it. While some of these myths may have been true at some point in the past, they aren't now. It's time to stop letting them get out into the world and start getting rid of this artificial barrier that's stopping so many people from even attempting to get the career they want.

Myth #1: You have to be a tech junkie to be a good developer

There is this idea that all developers are some kind of "tech nerds" that grew up taking apart computers and hacking video games. But as seems to always be the case, reality isn't quite like the stereotypes lead you to believe. You don't have to be a major technology enthusiast to be a software engineer. I was never all that into tech outside of being a general consumer. Sure I played video games and was excited when the new iPod or new phone came out, but the thought of actually finding out how these things worked was far from my mind.

All you really need is a general understanding and a willingness to learn about the technology relevant to the field you want to work in. If you are a tech junkie... great! You already know you'll enjoy the work! But don't be discouraged if you're not. There's a good chance you'll find yourself getting more into it as your career grows and as you start working on new and exciting things. If you're reading this article and you've gotten this far - you have more than enough interest to get started.

Myth #2: You have to be a genius to code

This one is similar to the first myth (and several more later on) in that it's just another stereotype. I can't tell you how many interactions I've had that went pretty much exactly like this:

Me after someone asks what I do: "I'm a software developer, so I make apps and websites and things like that."

Them: "Wow you must be really smart. I could never do something like that."

As much as that conversation is fine if you want to stroke your ego a bit, I always feel a little awkward afterwards. Because of course I'm not any smarter than the person I'm talking to. I just happened to learn a different set of skills.

Learning to code is sort of like learning another language. It takes dedication, incremental learning (start small and easy then slowly move to more difficult and complex), repetition, and of course practice. But the important thing to know is it doesn't require any inherit "smarts."

Myth #3: Programming involves too much complex math

This was something that I believed before getting started, and something that almost made me change my course entirely. But thankfully I kept going, and to my immense relief, learned that programming doesn't have to involve some crazy math skills.

Now to caveat this - I recognize that a lot of degree programs and universities do require higher level math, however not all of them do. And as I'll talk about a bit later, traditional college isn't your only option. I also have to acknowledge that some programming actually does involve a good amount of more complex math. If you are looking to get into something like game development or cryptography or some other more niche fields, then this one won't be as much of a myth.

But if you're someone like me who dreaded walking into math class, not all hope is lost! There are plenty of fields that you can get into that don't require some kind of advanced trigo-calcu-algebraic madness. Things like building websites, creating user interfaces, or even a lot of API and cloud work, are all perfectly valid and lucrative areas of focus for a programmer and require little to no high level math skills. Besides, unless you're in an interview (and sometimes not even then), no one is going to frown on you pulling up Google when the occasional need for math does arise.

Take it from me. I have been coding professionally for a little over 4 years, I make a comfortable 6-figure salary, and have no issues completing any tasks or growing in any of the companies I've worked for, and I can't remember a time I had to solve a complex math problem all on my own to get the job done.

Myth #4: You need to have an expensive college degree

This is one of those myths that started as a fact. Back in the day if you wanted to become a programmer the best option was to go get a degree at some university and inevitably go into a bunch of debt. Fortunately though this thought process is starting to disappear. With technology becoming such an integral part of every day life, and with so much easy access to self-learning materials, more and more paths are opening up to get into the tech world. It's starting to become more common to meet developers that are entirely self taught. Utilizing online resources such as LinkedIn Learning, Udemy, Codecademy, or even just through YouTube tutorials - you can learn everything you need to know to nail an interview and be a very proficient engineer.

But what if you want a little more guidance than that, but still don't want to go majorly in debt for a large university degree? Well, there's options for you too! Bootcamps are shorter programs that solely focus on getting someone the skills to become a software developer without all the fluff of a full scale degree. You won't be leaving these bootcamps with a Bachelor's degree, but you will be leaving with the skills you need to start doing the job.

There's also more programs that are coming up at smaller schools and community colleges that do end with a Bachelor's degree, but at a fraction of the cost of a large university. This is the route I took. My local community college offered a program in "Applied Computer Science" where we spent two years in small cohorts of students, creating real applications for real clients. All in the process of learning to code. The small and consistent class sizes along with having a core group of a few teachers allowed us to build strong relationships that in turn lead to greater learning. Building real apps for real clients, allowed us to really dive deep into the practical application of programming, rather than just getting taught a bunch of computer science theory. It was at this school that I also achieved my Certified Scrum Master certificate, and even worked in my first web development internship. And the best part is - my entire Bachelor's degree ended up costing less than a quarter of what it would have at my local large university.

Take a look into less traditional methods of learning. You may be surprised at what's out there today!

Myth #5: Coding is a young person's game

I want to preface this by saying that unfortunately agism does exist in the tech world today. It shouldn't exist and it's nothing but a detriment to the entire tech society. But that is another topic for another post. My point here is that even if you don't think of yourself as "young," you shouldn't count yourself out of becoming an engineer.

If I were to guess at what started this whole idea that the older generation can't become developers, I would attribute it to the early days of the big tech boom. When computers started to be commonplace, everyone started carrying tiny computers in their pockets, and the internet was just hitting its stride. At this time the people that were growing up alongside the technology were able to see it as a natural part of life, while at the same time the older generation saw the tech as something new and wildly different than what they were used to. But times have changed. Technology is so prevalent today that it's almost unavoidable to people of any age. This means more exposure, which consequently "levels the playing field" and makes it a lot easier for the older generation to quickly ramp up their skills in technology.

Nowadays, anyone of any age can get into software development and be just as successful as the 20-something year olds just out of college. I myself didn't even start learning until I had been out of High School for around 8 years and I didn't get my first internship until close to 30 years old - which admittedly isn't old, but it's definitely not the traditional path. I've also worked with plenty of engineers that are twice my age or more, and many of them make me look like someone who just wrote my first "Hello World" program.

Age is nothing but a number. Whether you're a fresh graduate not even out of teenage years, or you're looking to switch careers after 30+ years in another industry, you can become a software engineer if that's where you want to be.

Myth #6: Programmers are introverts that spend all day in the darkness staring at a screen

Okay. So this one definitely could be true for some. If you like to be in a dark room while you work and coding is your passion so you spend all day and night doing it, then you do you! But my point here is that this isn't the way it has to be. It's not like you get your first programming job and are suddenly teleported to a dungeon where you can never leave or talk to anyone else. I've actually found that this job can be quite social!

A lot (almost all) of software development in the professional world involves teamwork in some capacity. Whether it's virtual meetings or working together in person, you will be collaborating with others to get your work done. There's also a good chance you will be interacting with people who aren't developers. A lot of teams will also consist of designers, project managers, sales, and even sometimes clients or stakeholders, so you may be interacting with a lot of different groups of people. Additionally, if you're particularly extroverted, you may find yourself joining the many developers today that go to conferences, teach classes, host podcasts, or in general spend a lot of their time being around others.

There's also a lot of networking. Networking with others can become vital to a software engineer's career, especially in the early days. Whether that means just having a presence on LinkedIn, or going to meetups and workshops and exchanging information with the people you meet, networking can open up tons of new job opportunities. Think about it. If you're a hiring manager or a recruiter looking for a new Front End dev to join your team, and you recently had a great conversation with someone about how JavaScript really isn't all that bad, you're probably going to reach out to that person first to see if they are interested!

So you don't have to be secluded in a corner to be a developer. In fact, it helps if you can manage to have a little bit of a social side to you! That's not to say you can't be a developer as an introvert either. As a fellow shy-guy I can confirm that it's possible. But if you can manage to put yourself out there to meet and talk to people every once in a while, and if you can collaborate well with your team, you'll find a lot of success in this career.

Wrapping it up

This post ended up a lot longer than I originally intended, and if you've stuck around until now thank you! My goal with this long-winded list is to prove that anyone can start a career in software development if they really want to. We as a community in the tech world need to put a stop to the gatekeeping and bring down the intimidation factor so that more people can discover what a great career this can be. If you're considering jumping in, give it a shot. And if you have any other things stopping you from getting started that I haven't covered here, give me a shout. I'd be happy to give you some insight from the inside... and most likely end up telling you to try it anyway!