Tutorial

How to Build a Gatsby Ecommerce Storefront with Medusa

Mar 29, 2022 by

Kasper Kristensen

Discover how to build a high-performing ecommerce storefront with Gatsby and Medusa and take your ecommerce business to the next level.

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.

Features

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.

Prerequisites

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

Copy to clipboard
.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

Copy to clipboard
.env.development

. You can also rename it to

Copy to clipboard
.env.production

for production use, or just rename it to

Copy to clipboard
.env

This file includes 2 environment variables:

GATSBY_MEDUSA_BACKEND_URL=http://localhost:9000
GATSBY_STRIPE_KEY=pk_test_something

The first one is the URL to the Medusa server. By default, the Medusa server runs on

Copy to clipboard
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

Copy to clipboard
localhost:8000

Note About Development

It’s worth noting that the Gatsby starter makes use of the

Copy to clipboard
[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

Copy to clipboard
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.

Conclusion

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.

Share this post