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.

Features

The Gatsby 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 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 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:

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 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 storefront, start the storefront with the following command:

npm start

The storefront should run on localhost:8000.

Note About Development

It’s worth noting that the Gatsby starter makes use of the 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.

Conclusion

In this tutorial, you learned how to get a Gatsby 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.