How to build a Medusa Webshop with one command?

April 18, 2023, . open book5 minutes read


With the growth of the internet and the evolution of technologies, there is a need for businesses dealing in the ecommerce sector to remain competitive by keeping up with the latest trends in the area. Medusa is a popular open source headless ecommerce solution developed recently, scalable, and flexible making it one of the best choices for building an ecommerce website. It comes with two storefronts NextJs and Gatsby from which you can choose one or use a different stack for your storefront since Medusa has a composable architecture allowing you to use different technologies for your front and backend hence giving the possibility to fully customize your store and creating a store that will fit your needs. 

In this article, you will get started with Medusa by building your first headless store with a single command. 

Why Medusa?

Medusa is an open source user and developer-friendly platform for building incredible webshops. With over 17.8k stars on GitHub, its architecture allows you to build your online commerce shop with any framework of your choice that is developers have full control over their tech stack and the logic behind the commerce features. Besides that, it offers multi-regional support, advanced features for promotion and RMA flows, a user-friendly admin interface, and a community to support users.

How to Build a Medusa Webshop?

You will learn how to build your first webshop with just a single Medusa command. However make sure you have the following elements installed and working properly:

  • Node.js version 16 or latest. To check your Node.js version open your terminal or command line and run node -v. If you don’t have Node installed, then head to the official website, and follow the instructions to get it running on your OS 
  • Git
  • A package Manager(Yarn or Npm)
  • Medusa CLI

Now let’s get started. The first step will be to install the Medusa CLI. You can’t use Medusa without installing its command line. Run the following command to get it set up:

yarn global add @medusajs/medusa-cli


npm install @medusajs/medusa-cli -g

Upon installing the CLI, check the version by running the following command in your terminal

medusa -v 

If you ever encounter errors installing the CLI then visit this Medusa troubleshooting guide to get everything up.

Creating your Webshop with create-medusa-app

Medusa is divided into three main parts:

  • Backend  – It’s the commerce engine
  • Storefront – The actual webshop
  • Admin Dashboard – An application to manage your store(add/remove products, collections, payment methods, manage customers…)

Step 1: Install your Webshop with create-medusa-app

Open a terminal in your desired directory and run the following command:

npx create-medusa-app

NB: When you install your project with this command, it comes with Tailwind CSS

Step 2: Specify the project name

You need to specify the name of your webshop or leave the default value my-medusa-store. Here we will name the store my-headless-store.

? Where should you project be installed? . my-headless-store

Step 3: Choose a Backend starter

Once you have named your store, the next step is to choose a Medusa starter. Here we will be using medusa-starter-default

? Which Medusa starter would you like to install? …
❯ medusa-starter-default

This Medusa starter contains admin plugins, which will allow you to later access the admin dashboard. All the resources for the backend will be installed in the backend directory

Step 4: Choose a Storefront starter

The next consists of choosing the Medusa starter for your storefront. Here we will be using the NextJS starter 

? Which storefront starter would you like to install?
❯ Next.js Starter

Your storefront will be installed in the storefront directory.

Now you need to wait until your project sets up completely before testing your store. 

Step 5: Test your store

Upon installing all components of your project, you will see find three folders in your project directory.

  • Admin
  • Backend
  • Storefront

To start each component of your project navigate to each component root and run the commands as follows:

Your project is ready. The available commands are:

// Medusa API
cd my-headless-store/backend
yarn start

// Medusa Admin
cd my-headless-store/admin
yarn start

// Storefront
cd my-headless/storefront
yarn dev

To view your store and admin dashboard, open your favourite browser and type localhost:7000 and localhoat:8000 in the address bar respectively

Your store should look like the image below:

Medusa Storefront

And your dashboard:

How to build a Medusa Webshop with one command? - Medusa dashbaord

To access the dashboard, use

  • as email
  • supersecret as password

Well, if you have reached this stage that means you have successfully set up a basic webshop with Medusa however if you run into any trouble reach out on this website or reach out to the Medusa Discord channel for further assistance.


Hopefully, you have learnt how to build a basic store with Medusa, now you need to customize your store and add plugins and services like:

  • Payment methods with Klarna, Paypal, or Stripe
  • Notification services with SendGrid, Mailchimp or Twilio SMS
  • Search functionality with Algolia or MeiliSearch
  • File upload Services with S3, Space or MinIO
  • Shipping method.
  • Gift cards

Just head to the full Medusa Documentation to get the necessaire instructions to fulfil each task. Equally, feel free to sign up for our newsletter in order to get the latest ecommerce related content.

Share on

Author: Learndevtools

Like the article? Please share or subscribe to get more updates from Learndevtools