How to Use a Monorepo to Deploy Your Gatsby Ecommerce Storefront and Admin
Tags: javascript, opensource, webdev, hosting
Published: 2022-05-12 11:26:29

## Introduction

A [Monorepo](https://monorepo.tools) is a codebase that contains several projects, often using multiple and different frameworks but unified in a single repository.

[Medusa](https://www.medusajs.com/) 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](https://github.com/medusajs/medusa), 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](https://medusajs.com/blog/aws-elastic-beanstalk/) to get a server deployed on Amazon Web Services (AWS), and you can follow [this documentation to use S3](https://docs.medusajs.com/add-plugins/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](https://github.com/signup) account and a newly created repository to be the monorepo.
- A [Vercel](https://vercel.com/signup) account.
- Optionally you can install and use [Yarn](https://yarnpkg.com) 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:

```bash
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](https://docs.medusajs.com/admin/quickstart) 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:

```bash
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:

```bash
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:

```bash
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](https://docs.medusajs.com/troubleshooting/cors-issues) to resolve it.
> 

![Page to login on the admin app](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/t0uzk0lkl44w67ek580l.png)

### 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](https://docs.medusajs.com/starters/gatsby-medusa-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:

```bash
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:

```bash
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:

```bash
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](https://docs.medusajs.com/troubleshooting/cors-issues) to resolve it.
> 

![Storefront’s homepage](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kifo16f9a8tkvxrjbm18.png)

### 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.

![Add GitHub account](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vusy0r7e99xcgst9rr4n.png)

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

![Import monorepo repository](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/m66sdigtpr3rdai76kxn.png)

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.

![Select admin folder on the monorepo](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6bmxp5r0n4ia332fowne.png)
    
- Lastly, open **Environment Variables** and add an environment variable with the URL of your Medusa server:
    
```bash
GATSBY_MEDUSA_BACKEND_URL=<YOUR_MEDUSA_SERVER_URL>
``` 

Your configuration setup should look like this:

![Configuration for the admin app](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wk68ngviqaakvc90iy04.png)

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.

![Overview page on Vercel for the admin app](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/y7qhqv1cf3ondesxd4lw.png)

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:

```bash
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`.
> 

![Orders page on the admin app](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xy71cnoukexsv3wpygu2.png)

### 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)](https://www.gatsbyjs.com/docs/conceptual/rendering-options/#static-site-generation-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.

![Import monorepo for the storefront app](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/nirfgf7kcca5ziqcrhww.png)

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:

```bash
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:

![Config to create a vercel app for the storefront](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/sz2j0l1ndu70u9pdf8u9.png)

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.**

![Storefront’s congratulations page](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2s1momk342va17htqrh4.png)

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

![Storefront’s overview page](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7cyt0bpx1f7a49mvsl22.png)

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:

```bash
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

![Settings](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4awcgejhjgefd0tbx7gy.png)

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:

![Configuration to redeploy storefront app](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/eia6xv6dfl802lv0n9cu.png)

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

![deployments](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hyl7ndpa92ghlol0s3oo.png)

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

![Redeploy app from deployments page](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/q8bzrlwoiysm1rvgarg2.png)

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.

![Storefront’s overview page after deploying the app a second time](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yv4elp5nowfiv60zigjs.png)

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.

![Storefront’s homepage deployed on Vercel](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jfjnphzm6zbusczmkn03.png)

## Test Deployed Apps

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

![Info to sign up a new user](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/usgqdt4101fdwmco264x.png)

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

![User successfully registered and seen on the admin dashboard](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/61x16r5rmc441fhgsl8a.png)

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](https://docs.medusajs.com/add-plugins/stripe).
2. Add a product search engine to your storefront using the [Algolia plugin](https://docs.medusajs.com/add-plugins/algolia) to improve your customer’s experience.
3. Add an email notifications system using the [SendGrid plugin](https://docs.medusajs.com/add-plugins/sendgrid) 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](https://discord.gg/F87eGuwkTp).