Get started with Medusa: the open-source Shopify alternative
Tags: javascript, webdev, opensource, tutorial
Published: 2021-11-02 15:53:36

_This is the first article in a longer series about how to get started with Medusa. Part 2 is live at [Get started with Medusa Part 2: Make the Server Your Own](https://dev.to/medusajs/get-started-with-medusa-part-2-make-the-server-your-own-gka)._

There are many popular ecommerce platforms that come to developers’ minds first, and one of these is Shopify. Shopify established itself as one of the go-to platforms to create an ecommerce store for any business. However, it has a lot of disadvantages including the fact that it is not free and it has minimal customizability. This is where Medusa comes in.

[Medusa](https://www.medusajs.com) is an open-source headless commerce engine that is fast and customizable. As Medusa is split into 3 core components - the headless commerce part that exposes the REST APIs for your store, the frontend of your store, and the admin panel - you are free to use the platform as a whole, or use the parts that you need for your ecommerce store.

In this tutorial series, you will learn how to create an ecommerce store with Medusa. This includes setting up your development environment, adding features and plugins to your backend, frontend, and admin panel each, and everything you might need to set up your ecommerce store with Medusa.

In this part of the tutorial series, you will learn how to install and run each part of the platform separately, and you will learn the structure of each part to understand where you need to do what. Then, you will learn how to set up all the different parts together with a single command.

## Why Medusa

### Customization Abilities

Shopify is a great choice if you are creating a basic store with no need for customization, or you are not a tech-savvy person. However, you should not use Shopify if you are looking to own your tech stack and make changes per your business requirements. When you choose Shopify, you are stuck with the features and architecture that the platform provides out of the box.

On the other hand, Medusa’s main feature is its flexibility and extendibility. You can use all of the 3 core components together, or take some of them and couple or integrate them with other technologies or systems.

You can still use it as a whole and you will get a great development and user experience. The backend is built on Node.js, Express, and by default SQLite when you first install the server with the option to use [PostgreSQL](https://www.postgresql.org/) and [Redis](https://redis.io).

For the frontend, you have the option to use a starter storefront built with either [Next.js](https://nextjs.org/) or [Gatsby](https://www.gatsbyjs.com). As with both options, you will end up with a static website that connects to the headless server, the speed of your website is almost guaranteed to be fast.

As for the backend, it is also built with Gatsby and connects to your server just like the frontend.

This sets Medusa apart from other ecommerce platforms that are tightly coupled, complex and slow. Medusa offers a lot of features out of the box and is built to allow you to customize it based on your needs. Compared to Shopify, which provides less ownership over your tech stack, it allows you to completely own your tech stack.

_Suggested Read: [Medusa: Create A Fast and Highly Customizable E-Commerce Store](https://blog.shahednasser.com/medusa-create-fast-and-highly-customizable-ecommerce-store/)_

### Pricing

Shopify’s pricing models can be a big disadvantage as there are a lot of other alternatives, including Medusa, that offer their ecommerce platform for free.

Not only do you have to pay to use and deploy the platform, but also it is hard to find plugins or themes for free. In addition, installing plugins is not easy due to the platform’s inflexibility.

This is where open-source shines. You are free to use and deploy Medusa free of charge. You also have an open-source community backing you up, providing free plugins for you to use. Due to Medusa’s flexibility, installing plugins is very easy.

### Business Use Cases

As mentioned earlier, Shopify is not flexible and is hard to customize. This means that a lot of business use cases, including B2B, market places, custom shopping experiences, and more are not available or possible with Shopify. 

If you are sure that your business will just sell products with the conventional ecommerce experience, that might not be a problem for you. However, if you are already planning for the growth of your business and need an ecommerce platform that can grow and extend as needed with your business use cases, then choosing Shopify will prove to be a hassle.

Medusa’s headless APIs and flexibility allow you to easily create plugins to customize the shopping experience to your use case or integrate Medusa with other services as needed.

## Prerequisites

Before we start, make sure you install [Node.js](https://nodejs.org/en/) if you have not. You will also need [NPM](https://www.npmjs.com) but it will install with Node.js when you install it.

To check if you have Node.js and NPM installed you can run these commands:

```bash
node -v
npm -v
```

If the output of each of the commands shows a number version, then you have them installed. Otherwise, you need to install them.

## Set Up Medusa

At its core, Medusa is the backend that exposes the REST APIs, which will allow your frontend or admin panel to retrieve or modify the data. You can replace the storefront or admin panel with a platform of your own that connects to the APIs, but you at least need this part of Medusa in your system.

### Install Medusa

Installing Medusa is easy. First, you need to install the CLI tool that allows you to set up the server:

```bash
npm install -g @medusajs/medusa-cli
```

Once this part is done, you can use the CLI to set up a new Medusa store on your machine:

```bash
medusa new my-store --seed
```

This will create a new Medusa installation in the directory my-store. You can change the name of the store or directory by changing my-store. By applying the --seed option, it will seed the database with basic data including a demo product.

### Run Medusa

Once this command is done, you are ready to run your server! First, change to the directory of the medusa store:

```bash
cd my-store
```

Then, run the `develop` command using the CLI tool to run the server:

```bash
medusa develop
```

This will run the server by default at `localhost:9000`. You can test it by going to `localhost:9000/store/products` in your browser and you should see a JSON array of products. It will include just one product as the seeder adds just one.

You can check the full list of [API endpoints in the documentation](https://docs.medusajs.com/api/store/auth). For the storefront, all endpoints are prefixed with `/store`, whereas for the admin panel, all endpoints are prefixed with `/admin`.

### Structure Overview

Let us take a look at the directory structure for the server. It should look something like this:

As you can see we have the following directories:

![Structure Overview](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5pf3w9kemzshbz74akdr.png)

1. `data`: This directory holds the data that will be used to seed the database. It has the file `seed.json` which includes the configuration for the basic store. These data are the data added to your store when you add the `--seed` option which we did.
2. `dist`: This directory will hold the build of your server when you run `npm run build`. When you deploy your server, you will run this command and the compiled files in the `dist` directory will be used.
3. `src`: Inside the `src` directory, you can add any of the plugins or changes you might need to make. Inside the `api` subdirectory, you can add new endpoints to your store. Inside the `services` subdirectory, you can add new services which you can use globally in different endpoints. Inside the `subscribers` subdirectory, you can add event listeners to different events e.g., when an order is placed.
4. `uploads`: will include any files to be uploaded like product images.

## Set Up the Storefront

Next, we'll install and set up the storefront. As mentioned earlier, you can use the [Gatsby](https://github.com/medusajs/gatsby-starter-medusa) starter or [Next.js](https://github.com/medusajs/nextjs-starter-medusa) starter. For this tutorial, we'll use the Next.js starter.

### Install the Storefront

To install the Next.js storefront just run the following command:

```bash
npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-storefront
```

This will create a Next.js storefront in the directory my-storefront. If you want to name it something else you can change the name in the command.

### Run the Storefront

Before running the storefront, make sure that the server is running first as the storefront will connect to the server to retrieve the data of the store. To run the server, you can follow the steps in the previous section.

To run the storefront, first change to the directory of the storefront:

```bash
cd my-storefront
```

Then, run the following command to run the storefront:

```bash
npm run dev
```

This will run the storefront at `localhost:8000` by default. If you open it, you should see a basic storefront with links to different documentations. You can also see the products and try out the full checkout experience.

![Medusa Storefront](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8q4ww6jvs6ei0jpgsnvf.png)

### Add Stripe Integration

To add the [Stripe](https://stripe.com) integration, first copy the `.env.template` to `.env.local`:

```bash
mv .env.template .env.local
```

Then, change the environment variable for Stripe's public key:

```bash
NEXT_PUBLIC_STRIPE_KEY=pk_test_something
```

### Structure Overview

The structure of the directory should look like this:

![Structure Overview](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/r7u0vyffglxyx22koc0e.png)

1. `components`: This directory includes different components in the storefront like the cart, checkout, navigation bar, and more. Here you can make changes to the components if needed.
2. `context`: This includes some easy to toggle or change settings for your store through the context. For example, you can toggle showing the full cart in `context/display-context.js` by changing the value of `cartView` in the `defaultDisplayContext` object.
3. `pages`: This includes the different pages in the storefront. By default, the storefront will have 3 pages: Checkout, Product page, and landing page. You can add more pages to your store here.
4. `public`: You can add the public assets like images here.
5. `styles`: This directory holds all the styles of the store and you can make changes here to change the styles of the storefront.
6. `utils`: This includes helper functions like getting Stripe's public key, helper functions, configurations, and more.

## Set Up the Admin Panel

Finally, we'll install and set up the admin panel. The admin panel is built with Gatsby. Through the admin panel, you can use the APIs exposed by the server to view or make changes to the data in the store. This includes viewing and adding products, orders, customers, and more.

### Install the Admin Panel

To set up the admin panel, first, clone [the repository of the admin panel](https://github.com/medusajs/admin):

```bash
git clone https://github.com/medusajs/admin my-admin
```

Then, change to the directory of the admin panel, which is my-admin. You can change that by changing it in the command above.

```bash
cd my-admin
```

After that, you need to install the dependencies with NPM:

```bash
npm install
```

### Run the Admin Panel

Once all the dependencies are installed, we are ready to run the admin panel:

```bash
npm start
```

This will open the admin panel at `localhost:7000` by default. When you first open it, you will be asked to log in. To log in you can use the email "admin@medusa-test.com" with the password "supersecret".

When you log in, you will see an admin panel with a sidebar that you can use to view orders, customers, products, and more.

![Medusa Admin](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/f63nku8x3selobtumzh6.png)

### Structure Overview

The structure of the directory should look something like this:

![Structure Overview](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/800zajsxaalkcoupi1cl.png)

1. `src`: Here you will find the main code for the admin panel. You can edit components, pages, context, and more. Any edits or additions to the admin panel can be done here.
2. `public`: This will include the build generated by Gatsby for the admin panel.
3. `static`: The public static assets you will need for the admin panel like images.

As mentioned, this admin panel is built with Gatsby. Although you do not necessarily need to learn Gatsby to set it up and run it, making changes to it would require some understanding of how Gatsby works, depending on the kind of change you will be making.

## Alternative Solution: Create Medusa App

As mentioned, Medusa decouples the three core components of the platform to give you the flexibility and ability to customize the platform as fitting for you. However, if you will use the three components, you can install them all at once.

Medusa introduces [create-medusa-app](https://docs.medusajs.com/how-to/create-medusa-app). If you've used [React](https://reactjs.org) before, before, you will notice that this is similar to [create-react-app](https://create-react-app.dev). by using this tool, you will be able to set up the 3 components of the platform all at once.

### Set Up Medusa App

In your terminal, you just need to run the following command:

```bash
npx create-medusa-app
```

You will then be asked some questions related to naming your store, what technologies you want to use for the different parts of the platform and more.

Once the installation is done, you will have 3 directories ready. One for the server which will be called `backend`, one for the storefront which will be called `storefront`, and one for the admin which will be called `admin`.

### Run the Medusa App

Similar to the instructions of each component in the first method, when we install them separately, you will have to run each component separately.

The Medusa server is required for both the storefront and the admin panel, so make sure that it is running before running either of them.

To run the Medusa server you need to change to the backend directory then run it:

```bash
cd backend
npm start
```

To run the Medusa storefront you need to change to the storefront directory then run it:

```bash
cd storefront
npm start
```

To run the Medusa admin you need to change to the admin directory then run it:

```bash
cd admin
npm start
```

## Conclusion

Although no one can deny Shopify’s popularity and many advantages, it is also good to recognize some of its disadvantages and what other options or alternatives you have. 

Its lack of extendibility and ownership are disadvantages that should not be taken lightly when choosing an ecommerce platform for your system.

Medusa is a great alternative when it comes to these cons. Medusa is an open-source platform that will provide you with an extensible and fast development experience, as you have probably seen from this tutorial. Its setup is quick, and you can easily make changes or additions to any part of its components.

In addition to all that, the team behind Medusa is always happy to assist you with any questions you might have regarding how to set up Medusa on [the Discord](https://discord.gg/F87eGuwkTp)!

In the next part of the series, you will see how to make changes to the server. This includes how to add API endpoints, services, and more. As we go through the tutorial series you will be able to master and understand each component of Medusa to help you build your ecommerce store.