Introduction

A Monorepo is a codebase that contains several projects, often using multiple and different frameworks but unified in a single repository.

Medusa is an open source headless commerce that allows you to build an ecommerce platform through its API with just a few commands in a short amount of time. In addition to its core that holds all extensive ecommerce features, Medusa also has ready-made Gatsby storefront and admin websites that you can use to amplify your ecommerce business.

By default, the storefront, admin, and Medusa server are all distributed as separate projects. This separation gives developers the freedom to shape their ecommerce stack as they see fit to their use case. However, it’s easier to manage the different components that shape your ecommerce stack from one repository rather than different ones.

In this tutorial, you will learn how to set up and deploy the entirety of the frontend of your ecommerce stack in a monorepo with two projects, one for the admin panel and the other for the storefront.

Prerequisites

To follow along with this tutorial you need the following:

• A Medusa server with a working storage plugin. If not, you can follow this tutorial to get a server deployed on Amazon Web Services (AWS), and you can follow this documentation to use S3 for your storage.

The server needs to have its API ready to be consumed over HTTPS. This is because once you deploy your apps to Vercel, they will have by default a domain with an SSL certificate. If you try to make requests from them to a server without an SSL certificate, then you will get a mixed-content warning in your browser and you won’t be able to fetch data from the API.

• A GitHub account and a newly created repository to be the monorepo.
• A Vercel account.
• Optionally you can install and use Yarn to follow along with this tutorial. You’ll still be able to follow along with this tutorial if you prefer using NPM.

Set Up a Monorepo

The first step is to create the Monorepo that will hold the storefront and admin.

Open your terminal and run the following command:

mkdir medusa-monorepo && cd medusa-monorepo && git init

With this command you are doing three things:

1. Creating a new folder for the monorepo, which is called medusa-monorepo.
2. Change to the monorepo directory.
3. Initialize a git repository to have a control version system.

Add Admin Website to The Monorepo

The first project you’ll add to the monorepo is the admin. Medusa provides an intuitively designed admin panel that includes all features to manage your ecommerce store.

To add Medusa’s Admin to the monorepo, inside the medusa-monorepo folder run the following command:

git clone https://github.com/medusajs/admin admin

This will clone the admin’s GitHub repository inside your monorepo into a new directory called admin.

Make sure there is no .git folder inside medusa-monorepo/admin. If not, the admin project will be a sub-module of the monorepo rather than managed by the monorepo itself.

The next step is to install the dependencies for the admin app. Run the following command to change to the admin directory and install the dependencies:

cd admin
yarn install

Let’s test the admin app locally. For that, you need to have a local Medusa server installed and running. Then, run the following command inside the admin folder:

yarn develop 

You can view the admin in the browser by going to the URL http://localhost:7000.

If you get a CORS error, please check this guide to resolve it.

Add Storefront Website to the Monorepo

Medusa provides great flexibility in your choice of the storefront. You can use one of the ready-made starters, or you can create a storefront using a framework of your choice from scratch.

In this tutorial, you’ll be using Medusa’s Gatsby starter for your ecommerce storefront.

To add the Gatsby Storefront to the monorepo, clone the repository inside the medusa-monorepo directory with the following command:

git clone https://github.com/medusajs/gatsby-starter-medusa.git storefront

This will create a new directory storefront inside medusa-monorepo which will hold the code for your storefront.

As explained earlier, make sure there’s no .git folder inside the medusa-monorepo/storefront folder. If there is a .git folder then delete it.

The next step is to install the dependencies of the storefront app. Use the following command to change to the storefront directory and install the dependencies:

cd storefront
yarn install

Let’s test the storefront locally. You also need a Medusa server installed and running locally first.

Then, run the following command inside the storefront folder:

yarn develop 

You can check the storefront in your browser by going to localhost:8000.

If you get a CORS error, please check this guide to resolve it.

Push Changes to the Monorepo

Now that both the storefront and the admin are working locally, the last step before deploying them is pushing the changes to the monorepo you created on your GitHub account.

Deploy to Vercel

One of the advantages of using Vercel for deployment is that it allows you to deploy multiple apps separately from a monorepo. Additionally, you get out-of-the-box CI/CD. So, every time you push new commits to GitHub, Vercel will trigger a new deployment with those changes and your apps will be updated.

Log in with your Vercel account and go to your dashboard. Here you will create two projects, one for the admin app and another for the storefront app.

Deploy the Admin Website

First, you’ll create the admin project. Click on the New Project button and you will be redirected to the new project screen. Then, you need to import your repository from GitHub. If you don’t have your GitHub account already linked to Vercel, click on Add GitHub Account and give the necessary permissions to Vercel so it can read your repositories.

Once Vercel can access your monorepo you should be able to import it. Click on Import.

On the next page, you’ll be asked to configure the project:

• Give a name to your project. For example, medusa-admin.
• For the Framework Preset choose Gatsby.js.
• For the root directory, click on edit and a popup will be shown with the folder structure of the monorepo. Choose the admin folder and click on continue.

• Lastly, open Environment Variables and add an environment variable with the URL of your Medusa server:

GATSBY_MEDUSA_BACKEND_URL=<YOUR_MEDUSA_SERVER_URL>

Your configuration setup should look like this:

Once you’re done, click on Deploy. The deployment could take a while as Vercel will install all the dependencies, run the build command, and finally assign a new random domain for your app with an SSL certificate included.

Once your app is deployed you will be redirected to the overview page of the project you just created for your admin app. There, you can find the URL of your admin.

Copy the admin’s URL and go to your Medusa server. You need to add or change the CORS environment variable to allow your admin app to consume the API of your Medusa server:

ADMIN_CORS=<YOUR_ADMIN_URL>

Once the changes are saved and reflected on the Medusa server, you can go to the admin panel URL and you should see the login page.

Try to log in with your admin user credentials and you should be redirected to your admin dashboard.

If you seeded your server with dummy data on installation, you can use the email admin@medusa-test.com and password supersecret.

Deploy Storefront Website

The process to deploy the storefront app is a little different than the Admin. This is because the storefront is configured to render as a static site generator (SSG). To do that, the storefront needs to make some requests to the Medusa server during build time. As the domain name for the storefront is still not set up or added as an environment variable on the Medusa server at this point, a CORS error will be thrown during build time.

So, you’ll first create a project with general configurations and, when you obtain the URL of your storefront, update those configurations to something more specific and redeploy your app.

On your Vercel dashboard, click on the New Project button and you will be redirected to the new project screen. On that page, click on the Import button of the same medusa-monorepo repository.

For the project configurations:

• You need to give a name to the project, in this case, it will be medusa-storefront.
• For Framework preset choose Other. Later on, you will update this setting to Gatsby.js.
• Open Environment Variables and add the following environment variable with the URL of your Medusa server as its value:

GATSBY_MEDUSA_BACKEND_URL=<YOUR_MEDUSA_SERVER_URL>

At this point, you don’t have to choose any directory because you only need an app deployed on Vercel to get the storefront URL, as explained at the start of this section.

The configuration should be something like this:

Once you’re done, click on Deploy. Vercel will start a new deployment, but in this case, it will not install or build anything, and in the end, it will assign a random URL to the newly created app.

When the deployment is done, you will get a congratulations screen, click on Go to Dashboard.

On your project’s dashboard, you can see the info related to the deployment. Copy the URL of your storefront.

Then, go to your Medusa server again and change or add the environment variable STORE_CORS so the storefront can make requests to it without CORS errors:

STORE_CORS=<YOUR_STOREFRONT_URL>

Once you’ve saved the new environment variable and the change is reflected on your server, the next thing to do is update the configurations of the storefront project with configurations specific to it.

On your project’s dashboard, go to the Settings tab

In the Build & Development Settings section, change the Framework preset to Gatsby.js and click on Save.

In the Root directory section, change the value to storefront. This is the path of the storefront in the monorepo. Then, click on Save.

Your settings should look something like this:

The last step is to trigger a new deployment with the new configurations. Go to the Deployments tab

You should then see a previously finished deployment. Click on the 3 dots on the right side of that deployment and click on Redeploy.

A new deployment will start. This time Vercel will change to the storefront directory, install the dependencies, and build the app. Once the new deployment is completed, you will see the overview screen.

Now you can go to your app’s URL and you should see the newly deployed storefront app with the products and data from your Medusa server.

Test Deployed Apps

To test both apps, you can try to sign up as a new user on the storefront app:

Then, go to your admin dashboard and you should see your newly created user.

To test the CI/CD you can go back to your monorepo code and make some changes, then commit and push them to GitHub, Vercel will detect there is a new commit on your monorepo and it will start a new deployment for all your apps.

Conclusion

Medusa’s flexible architecture makes it easy to deploy different parts of your ecommerce stack separately or together.

By using a monorepo, you can utilize features from hosting platforms like Vercel such as out-of-the-box CI/CD and a secure domain to visit your apps.

Going forward, you can focus on developing or adding new functionalities for your ecommerce store including:

1. Set up Stripe as a payment method using the Stripe Plugin.
2. Add a product search engine to your storefront using the Algolia plugin to improve your customer’s experience.
3. Add an email notifications system using the SendGrid plugin to send emails to your customers and admin users.

If you have any issues or questions related to Medusa, feel free to reach out to the Medusa team via Discord.