Set Up An E-Commerce Backend With Medusa In Just A Few Minutes

Medusa is an open-source, customizable digital e-commerce platform designed to give you full control over your e-commerce backend. Unlike traditional platforms that provide a rigid, out-of-the-box solution, Medusa is built with flexibility in mind, allowing you to tailor every aspect of your store to suit your business needs.

Medusa comes with three main components:

1. Commerce Modules: A suite of core commerce functionalities like inventory tracking, cart totals, payment processing, order management, and more. These modules provide the essential tools to get your store up and running.

2. Customization Framework: Medusa is designed for customization. You can easily add custom API endpoints, integrate third-party services, introduce business logic, and build data models that fit your specific requirements. Additionally, you can create workflows and automations to streamline your operations.

3. Admin Dashboard: A fully customizable admin dashboard that empowers store owners and merchants to configure, manage, and operate their stores efficiently.

When you install Medusa, you’re not just getting an out-of-the-box e-commerce platform; you're getting a robust foundation that you can extend and modify to fit your business's vision.

This guide teaches you how to use Medusa to set up a standard full-stack E-commerce app in just a few minutes.

Let's get into it!

Who Should Use Medusa?

Medusa is ideal for businesses and teams that need a digital e-commerce platform that supports unique requirements not typically found in other out-of-the-box solutions. Whether you’re building a Direct-to-Consumer (D2C) brand, an Order Management System (OMS), a custom marketplace, or a global B2B platform, Medusa gives you the tools to bring your ideas to life.

Medusa works for businesses of all sizes, from startups to large enterprises. It’s also well-suited for development teams of all sizes, with a developer-friendly architecture that allows for easy management and deployment of projects.

Here are a few examples of how companies use Medusa:

• D2C (Direct-to-Consumer) platform
• OMS (Order Management System)
• Marketplace
• POS (Point of Sale)
• B2B platform

Medusa empowers businesses to scale and customize their digital commerce solutions without being restricted by traditional e-commerce platforms, providing the flexibility to create truly unique and innovative experiences.

Prerequisites

Before you begin, ensure you have the following tools and technologies set up:

• Node.js v20+: Medusa requires Node.js, so ensure you're using version 20 or higher. You can check your Node.js version with:

  node -v

If you need to install or update Node.js, visit the official website.

• Git: Git is required to clone repositories and manage your project versioning.
  Install Git from git-scm.com.

• PostgreSQL: Medusa uses PostgreSQL as its default database. Ensure PostgreSQL is installed and running on your computer.

How to Set Up an E-commerce Application with Medusa

Follow these simple steps to set up your Medusa backend application—complete with a working admin dashboard and NextJS frontend client.

Step 1: Create Your Database

Before you start setting up Medusa, you’ll need to create a PostgreSQL database for your project. The name of your database should match the name of your Medusa project to ensure proper configuration and smooth operation.

Create a PostgreSQL Database

1. Log into PostgreSQL: Open your terminal and log into PostgreSQL by running the following command:

   psql -U postgres

This will open the PostgreSQL interactive terminal. You may be prompted for your PostgreSQL password.

1. Create a New Database: Once logged in, run the following command to create your new database. Replace my-medusa-store with your desired database name (this should match the name of your Medusa project):
   

   CREATE DATABASE my_medusa_store;
   

   This will create a new PostgreSQL database. You may also create a new database via a GUI tool such as pgAdmin.

2. Exit PostgreSQL: After creating the database, you can exit PostgreSQL by typing:
   

   \q
   

   Now that you’ve created your database, you’re ready to proceed with installing Medusa and configuring it to connect to this database.

Step 2: Create a New Medusa Project

With the database set up, it's time to create your new project. Use the create-medusa-app command to set up the backend:

npx create-medusa-app@latest my-medusa-store

Here, my-medusa-store is the name of your project’s directory. During installation, you will be prompted to choose whether you want to install the Next.js storefront along with the Medusa backend. You can choose to install it now or skip and add it later.

We'll assume you chose to install now for the rest of this guide.

The installation process will:

• Set up a PostgreSQL database and connect it to your Medusa app.
• Install Medusa and related dependencies.
• Install a Next.js storefront if you chose to include it.

If successful, Medusa will run at http://localhost:9000, and the Medusa Admin dashboard will be available at http://localhost:9000/app.

The Next.js storefront will be available at http://localhost:8000.

Step 3: Run Medusa Application in Development

At this stage, your Medusa app should already be running so you may skip to the next step.

However, to start the Medusa application locally at any point, run the following command from your project directory:

npm run dev

This command starts both the backend at http://localhost:9000 and the Admin dashboard at http://localhost:9000/app.

Any changes made to the src directory will automatically restart the server, making development seamless.

Step 5: Set Up Medusa Admin User

You'll be prompted to set up an Admin User account the first time you run your Medusa app. Simply fill out the form to do so.

You may also do this using the Medusa CLI:

npx medusa user -e [e-mail] -p supersecret

Replace [e-mail] with your preferred email address and supersecret with a strong password.

This user will be able to log into the Admin dashboard at http://localhost:9000/app to manage products, orders, and customers.

Project Structure

Your Medusa project includes several important directories and files—here's a breakdown:

• src/: The core of your custom development, containing sub-directories like:
  • admin/: Custom UI widgets and routes for the Admin dashboard.
  • api/: Custom API routes that extend Medusa’s functionality.
  • modules/: Custom business logic for your store.
  • jobs/: Scheduled tasks and cron jobs.
  • scripts/: Custom scripts executed via the Medusa CLI.
  • workflows/: Automated flows executed from anywhere in your application.
• medusa-config.ts: The file where you define and configure the database and other settings for your Medusa backend.

Step 6 (Optional): Add a Product

Once your Medusa project is up and running, you can start adding products to your store. The Medusa Admin Dashboard provides a simple interface to manage your inventory, and adding a product is quick and easy.

Add a Product to Your Inventory

1. Access the Admin Dashboard: Open your browser and navigate to the Medusa Admin Dashboard at http://localhost:9000/app. Log in with the admin credentials you created during the setup process.

2. Navigate to the Inventory Section: On the left sidebar of the Admin Dashboard, click on Inventory. This will take you to the section where you can manage products.

3. Click the Create Button: In the Inventory section, click the Create button to add a new product to your store.

4. Fill in Product Details: A form will appear where you can input details for your new product. This includes:

   • Title: Enter the name of the product.
   • Description: Provide a description that gives customers more information about the product.
   • SKU: Optionally, add a SKU (Stock Keeping Unit) for inventory tracking.
   • Attributes: Various attributes describing the product.

5. Save the Product: Once you’ve filled out the product details, click Save to add the product to your inventory.

Your product is now part of your Medusa store, and you can view or edit it at any time from the Inventory section of the Admin Dashboard.

Step 7: Visit the Storefront

If you chose to install the NextJS storefront in the earlier step, you can visit http://localhost:8000/ to see it and interact with your e-commerce store.

If you didn't install earlier, follow these instructions if you'd like to now.

The storefront could serve as a great starting point for your custom e-commerce application.

Customize Your Medusa Store

Now that your Medusa application is up and running, you can start customizing it to fit your needs. Medusa is highly extendable, allowing you to:

• Add custom modules: Extend Medusa’s functionality with your own business logic.
• Create custom API endpoints: Add APIs to meet specific requirements for your store.
• Install third-party plugins: Integrate payment gateways, shipping providers, and more.
• Customize the admin dashboard: Modify the admin interface to meet your business needs.

Refer to the Official Medusa Documentation for instructions on how to do these.

Conclusion

Medusa is a powerful, open-source e-commerce platform designed to offer complete flexibility and control over your e-commerce store. Its modular architecture and customization capabilities make it an ideal solution for businesses seeking to go beyond traditional e-commerce setups.

With Medusa, you can easily manage inventory, orders, and customer data while customizing every aspect of your store to align with your unique business requirements. Whether you're building a Direct-to-Consumer platform, a marketplace, or a global B2B solution, Medusa equips you with the tools needed to innovate and scale.

By following this guide, you've set up a robust e-commerce application, added products to your inventory, accessed a highly-customizable storefront, and explored the various customization options available. Dive deeper into Medusa's features and continue to tailor your store to provide a truly unique shopping experience for your customers.