Create a Gatsby Ecommerce Storefront with Medusa

Tutorial on creating a Gatsby ecommerce storefront with your Medusa server.Gatsby ecommerce

Medusa is an open source headless commerce platform that’s focused on providing a great developer experience while creating an ecommerce store.

Using Medusa’s headless architecture, you can create a storefront with any programming language or framework you prefer just by connecting it to the REST APIs. Your storefront will be able to display products and will have the full ecommerce checkout workflow.

In this tutorial, you’ll learn how to connect our Gatsby starter to your Medusa server to be able to create a Gatsby ecommerce frontend connected to the Medusa core.

gatsby ecommerce


The Gatsby ecommerce storefront comes with a lot of features out of the box, here are some of them:

  • View all products and manage your cart.
  • Customer authentication.
  • Full checkout workflow.
  • Request swaps and returns using a customer’s order ID and Email.


This article assumes you already have a Medusa server installed. If you don’t you can follow this quickstart guide to get you started in minutes.

You also need to have the Gatsby CLI tool installed as you’ll be using it to create the Gatsby ecommerce store. You can install it with the following command:

npm install -g gatsby-cli

Create Gatsby Storefront

In your terminal, run the following command to create the Medusa storefront with Gatsby:

gatsby new my-medusa-store https://github.com/medusajs/gatsby-starter-medusa

This creates a Gatsby website using the already-existing Medusa Gatsby starter.

Set Environment Variables

To connect to the backend, you need to set the URL that leads to the backend in the environment variables.

The Gatsby ecommerce starter comes with the file .env.template that you can use to add your environment variables. First, rename the file:

mv .env.template .env.development

This changes the name to .env.development. You can also rename it to .env.production for production use, or just rename it to .env.

This file includes 2 environment variables:


The first one is the URL to the Medusa server. By default, the Medusa server runs on localhost:9000. So, if you didn’t change that you can leave it as is.

The second one is your Stripe public key if you have Stripe set up. If you don’t, you can leave it as is.

Test it Out

Before you run your storefront make sure that your Medusa server is running.

Then, in your terminal in your Gatsby ecommerce storefront, start the storefront with the following command:

npm start

The storefront should run on localhost:8000.

gatsby ecommerce

Note About Development

It’s worth noting that the Gatsby starter makes use of the [gatsby-source-medusa](https://github.com/medusajs/medusa/tree/master/packages/gatsby-source-medusa) plugin to source data from your Medusa server. This data includes products, collections and regions, and as a result, you are able to query this data in the starter using GraphQL queries. You can also explore the data in your store on localhost:8000/___graphql.

As a result of this, you will need to rebuild the site every time you update any of this data for it to be reflected in your storefront. We will soon be releasing a new version of the plugin which adds incremental builds, which will improve build times, but more on that at a later time.


In this tutorial, you learned how to get a Gatsby ecommerce store up and running. Your storefront includes products listing, cart management, checkout workflow, an option for customers to request returns and exchanges for their previous orders, customer login, and customer order history.

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

Person photo
Kasper KristensenMar. 29, 20222 min.

Want to know more about Medusa

Find related blog posts below


How to Create Custom Endpoints in Medusa

In this tutorial, you’ll learn how to create custom endpoints on your Medusa server for both the storefront and admin.


How to Create a Comic Book Online Store with Medusa, Gatsby, PayPal, and MeiliSearch

In this tutorial, you’ll learn how to create a comic book store with Medusa and add important ecommerce features.


Medusa Open Source Marketplace Part 2: Make Orders Vendor Specific

In this part, you’ll learn how to link orders to their respective stores in a marketplace.


Receive the most important updates around Medusa and our ecosystem