Tutorial

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

May 24, 2022 by

Shahed Nasser

Create your own comic book online store with Medusa, open source ecommerce engine, Gatsby, PayPal, and MeiliSearch.

Medusa is an open source headless ecommerce platform targeted toward developers. It can be used to build fully-fledged ecommerce stores.

A fully-fledged ecommerce store is an ecommerce website that allows merchants to sell online. It also allows customers to browse through product pages and purchase products.

Medusa is an ecommerce platform that has a lot of essential ecommerce features including automated RMA flows, plug-and-play integrations, product and order management, and much more.

In this tutorial, you’ll learn how to create a comic book store with Medusa as the ecommerce platform.

You’ll also be adding important ecommerce features to your store including a search engine using MeiliSearch and a payment gateway using PayPal.

You can find the full code for this tutorial on this GitHub repository.

Architecture Overview

Before you create an online store with Medusa, here’s a short overview of Medusa’s ecommerce platform architecture in case you’re not familiar with it.

You can go ahead and skip to the next section if you are.

Medusa ecommerce platform is made up of 3 primary components:

Headless Server

The Headless Server is the core ecommerce platform of your online store.

It takes care of handling all logic, ecommerce features, and data.

All other components connect to the server using REST APIs.

Medusa Admin

The Medusa Admin is the user interface that store operators can use to view and manage their data (for example, products and orders).

Medusa provides an intuitive ready-made Admin panel that you can use.

Alternatively, you can build your own admin and connect to the server using the REST APIs.

Storefront

The Storefront is the ecommerce website where customers view products and make purchases.

Medusa provides two starter storefronts, one built with Next.js and one with Gatsby.

You can also build a storefront with any framework of your choice and connect to the server using REST APIs.

In this tutorial, you’ll learn about setting up each and how to use them to create a comic book store.

Prerequisites

Before you start building your own online store you’ll need the following requirements installed:

Node v14 or higher.
Postgres with an empty database created.
MeiliSearch for the search engine.
A PayPal developer account.
MinIO for file storage. You can alternatively use S3 or DigitalOcean Spaces.

Install Server of Ecommerce Store

To install the Medusa server, you need to first install the Medusa CLI:

npm install -g @medusajs/medusa-cli

Then, run the following command to install the Medusa server in a new directory

Copy to clipboard
comic-store

medusa new comic-store

Install Plugins

The next step is to install the plugins you’ll be using on your Medusa server. For this tutorial, you need the plugins for the PayPal, MeiliSearch, and MinIO integrations.

Run the following command inside the

Copy to clipboard
comic-store

directory to install the 3 plugins:

npm install medusa-file-minio medusa-plugin-meilisearch medusa-payment-paypal

Replace
Copy to clipboard
medusa-file-minio
with the file service you’re using if it’s not MinIO.

Make sure in

Copy to clipboard
package.json

that the versions for

Copy to clipboard
@medusajs/medusa

Copy to clipboard
medusa-interfaces

and

Copy to clipboard
@medusajs/medusa-cli

are greater than or equal to

Copy to clipboard
1.3.0

. If not, update them with the following command:

npm install @medusajs/medusa@latest medusa-interfaces@latest @medusajs/medusa-cli@latest

Add Environment Variables

Medusa gives you the freedom to handle your environment variables based on your server.

In this tutorial, you’ll be adding all environment variables in a

Copy to clipboard
.env

variable.

Open the

Copy to clipboard
.env

file. Add the following variables:

#PostgreSQL Database URL
DATABASE_URL=

#MinIO configurations
MINIO_ACCESS_KEY=
MINIO_SECRET_KEY=
MINIO_BUCKET=
MINIO_SERVER=

#PayPal Configurations
PAYPAL_SANDBOX=true
PAYPAL_CLIENT_ID=
PAYPAL_CLIENT_SECRET=
PAYPAL_AUTH_WEBHOOK_ID=

#MeiliSearch Configurations
MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_API_KEY=

These environment variables are important for configurations related to the database, MinIO, PayPal, and MeiliSearch.

Copy to clipboard
DATABASE_URL

is the URL to connect to your PostgreSQL database schema. It should be of the format

Copy to clipboard
postgres://<USERNAME>:<PASSWORD>@<HOST>/<DB_NAME>

You can refer to our documentation to learn how to retrieve the necessary variables for MinIO and MeiliSearch.

If you’re using a different file service than MinIO please refer to the documentation of your file service to learn what variables you need.

For PayPal, you can refer to PayPal’s documentation to retrieve the Client ID, Client Secret, and Webhook ID. You also turned sandbox mode on for testing by setting

Copy to clipboard
PAYPAL_SANDBOX

Copy to clipboard
true

Configure Server

You need to pass these environment variables to the server configurations.

Server configurations are all in

Copy to clipboard
medusa-config.js

. This includes database, plugins, and more configurations.

Open

Copy to clipboard
medusa-config.js

. Add the following to the beginning of the file:

const dotenv = require('dotenv');
let ENV_FILE_NAME = '';
switch (process.env.NODE_ENV) {
    case 'prod':
        ENV_FILE_NAME = '.env';
        break;
    case 'test':
        ENV_FILE_NAME = '.env.test';
        break;
    default:
        ENV_FILE_NAME = '.env';
        break;
}

dotenv.config({ path: process.cwd() + '/' + ENV_FILE_NAME });

This allows you to load environment variables from a

Copy to clipboard
.env

file.

Next, in the

Copy to clipboard
plugins

array, add the following 3 plugins at the end of the array:

const plugins = [
  //...
  {
    resolve: `medusa-payment-paypal`,
    options: {
      sandbox: process.env.PAYPAL_SANDBOX,
      client_id: process.env.PAYPAL_CLIENT_ID,
      client_secret: process.env.PAYPAL_CLIENT_SECRET,
      auth_webhook_id: process.env.PAYPAL_AUTH_WEBHOOK_ID
    }
  },
  {
    resolve: `medusa-file-minio`,
    options: {
        endpoint: process.env.MINIO_SERVER,
        bucket: process.env.MINIO_BUCKET,
        access_key_id: process.env.MINIO_ACCESS_KEY,
        secret_access_key: process.env.MINIO_SECRET_KEY,
    }
  },
  {
    resolve: `medusa-plugin-meilisearch`,
    options: {
      config: {
        host: process.env.MEILISEARCH_HOST,
        apiKey: process.env.MEILISEARCH_API_KEY
      },
      settings: {
        products: {
          searchableAttributes: ["title", "description", "variant_sku"],
          displayedAttributes: ["title", "description", "variant_sku"],
        },
      },
    },
  }
];

This loads the 3 plugins you installed earlier and passes the necessary options for each.

Finally, change the database configurations in

Copy to clipboard
projectConfig

in the exported function to use your PostgreSQL database instead of an SQLite database:

module.exports = {
  projectConfig: {
    //...
    database_url: DATABASE_URL,
    database_type: "postgres",
        //**comment out or remove these lines:**
    // database_database: "./medusa-db.sql",
    // database_type: "sqlite",
  },
    //...
};

Migrate and Seed Database

The final step before running your server is migrating and seeding your database.

Migration means adding the necessary tables into your database schema to make it work with Medusa.

Seeding means adding dummy data into your database to quickly get started.

Run the following command to migrate and seed your database:

npm run seed

This will connect to your database using the URL you passed to the environment variable

Copy to clipboard
DATABASE_URL

Make sure that you already created the database before running this command.

Run the Server

Make sure that the MeiliSearch and MinIO services are running. Then, run your server with the following command:

npm start

This will run your server on the port

Copy to clipboard
9000

You should keep the server running for the entire tutorial, as the Medusa admin and storefront depend on the server.

Setup Medusa Admin for the Ecommerce Website

In this section, you’ll install the Medusa Admin, add products to it, and enable PayPal as a payment gateway.

Install Admin

In your terminal and in a different directory than the

Copy to clipboard
comic-store

directory, run the following command:

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

Then, change to the newly created

Copy to clipboard
comic-admin

directory and install the necessary dependencies:

cd comic-admin
npm install

Make sure the Medusa server is still running.

Then, run the following command to start the admin:

npm start

This will start your Medusa admin on the port

Copy to clipboard
7000

by default.

Open it in your browser and you should see a login screen.

You can use the default email “admin@medusa-test.com” and password “supersecret” to log in.

Add Products

After you log in, choose from the sidebar “Products”.

You’ll see a few products that were added when you seeded your database.

Go ahead and delete those by clicking on the 3 dots for each one then Delete.

Next, add products to your comic book store by clicking the “New Product” button at the top right.

You need to fill out the fields related to the product info.

Add as many products as you want before moving on to the next step.

Enable PayPal

To enable PayPal as a payment gateway, click on Settings, then choose Regions.

For each region you want to add PayPal as a payment provider, click on the “Payment Providers” input and choose “paypal”, then click Save.

Setup the Storefront for Your Online Store

The last step is to set up the storefront.

This section covers installing the Gatsby storefront, making some customizations to it, adding MeiliSearch bar, and adding the UI for PayPal.

Install Storefront

In your terminal and in a different directory than the

Copy to clipboard
comic-store

and

Copy to clipboard
comic-admin

directories, run the following command:

gatsby new comic-storefront https://github.com/medusajs/gatsby-starter-medusa

This will install the Gatsby storefront in a new directory

Copy to clipboard
comic-storefront

Then, change to the

Copy to clipboard
comic-storefront

directory and rename

Copy to clipboard
.env.template

Copy to clipboard
.env.development

mv .env.template .env.development

Add Environment Variables

You need to add environment variables to use MeiliSearch and PayPal on your storefront.

Copy to clipboard
.env.development

add the following variables:

#MeiliSearch Configurations
GATSBY_MEILISEARCH_HOST=
GATSBY_MEILISEARCH_API_KEY=

#PayPal Configurations
GATSBY_PAYPAL_CLIENT_ID=

The values for these configurations are the same as those you used on your server.

Run Gatsby Storefront

Make sure that the Medusa server is running.

Then run the following command to start the Gatsby storefront:

npm start

This will run your storefront on

Copy to clipboard
localhost:8000

. Open it in your browser.

You should see a hero image and the products you added.

Customize Storefront

The hero banner is a static one that is added to the code.

You’ll now customize it to show something related to your comic book store.

Open

Copy to clipboard
src/pages/index.js

. You should find in the returned JSX the component

Copy to clipboard
StaticImage

followed by a div.

Change them to the following:

<StaticImage
  src="../images/hero.png"
  alt="A black Medusa hoodie and a white Medusa coffee mug"
  placeholder="tracedSVG"
  className="w-full lg:w-1/2 h-auto lg:my-5"
/>
<div className="lg:ml-7">
  <h1 className="text-4xl">The Best Comic Books</h1>
  <p className="mt-2 text-lg font-normal">
    Buy the best Marvel and DC Comic Books!
  </p>
</div>

This changes the text and image used.

You can download the new image from here. Place it at

Copy to clipboard
src/images

with the name

Copy to clipboard
hero.png

If you open your storefront now you should see the hero image updated.

Add Search Bar

In this section, you’ll add a search bar to search products using MeiliSearch.

In your terminal, run the following command to install some necessary dependencies:

npm install react-instantsearch-dom @meilisearch/instant-meilisearch

Then, create the file

Copy to clipboard
src/components/header/search.jsx

with the following content:

import {
  Highlight,
  Hits,
  InstantSearch,
  SearchBox,
  connectStateResults
} from "react-instantsearch-dom"

import React from "react"
import { instantMeiliSearch } from "@meilisearch/instant-meilisearch"

const searchClient = instantMeiliSearch(
  process.env.GATSBY_MEILISEARCH_HOST,
  process.env.GATSBY_MEILISEARCH_API_KEY
)

const Search = () => {
  const Results = connectStateResults(({ searchState, searchResults, children }) =>
    searchState && searchState.query && searchResults && searchResults.nbHits !== 0 ? (
      <div className="absolute top-full w-full p-2 bg-gray-200 shadow-md">
        {children}
      </div>
    ) : (
      <div></div>
    )
  );

  return (
    <div className="relative">
      <InstantSearch indexName="products" searchClient={searchClient}>
        <SearchBox submit={null} reset={null} />
        <Results>
          <Hits hitComponent={Hit} />
        </Results>
      </InstantSearch>
    </div>
  )
}

const Hit = ({ hit }) => {
  return (
    <div key={hit.id} className="relative">
      <div className="hit-name">
        <Highlight attribute="title" hit={hit} tagName="mark" />
      </div>
    </div>
  )
}

export default Search;

This creates a search client using the method

Copy to clipboard
instantMeiliSearch

that is exported from the dependency

Copy to clipboard
@meilisearch/instant-meilisearch

which you just installed.

You pass the method the environment variables you added earlier for the configurations.

The

Copy to clipboard
Search

component then displays a search bar using components from

Copy to clipboard
react-instantsearch-dom

When the user enters a query and there are results, each result is rendered using the

Copy to clipboard
Hit

component.

If you want to learn more about how you can customize the UI of the search bar and its options you can check out the documentation of React InstantSearch by Algolia.

Next, you’ll add the search bar to the navigation bar. To do that, open

Copy to clipboard
index.jsx

and import the

Copy to clipboard
Search

component at the beginning of the file:

import Search from "./search"

Then, in the returned JSX add the

Copy to clipboard
Search

component before

Copy to clipboard
RegionPopover

//...
<Search />
<RegionPopover regions={mockData.regions} />
//...

Save all changes and open the storefront now.

You should see a search bar in the navigation bar.

Try to enter the name of one of your products and you should see it in the result.

Add PayPal UI

In this section, you’ll add the UI necessary to use PayPal as a payment method.

In your terminal use the following command to install PayPal’s React library:

npm install @paypal/react-paypal-js

Then, create the file

Copy to clipboard
src/components/payment/paypal-payment/index.jsx

with the following content:

import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js";
import React, { useMemo, useState } from "react";

import { navigate } from "gatsby"
import { useCart } from "../../../hooks/use-cart"
import { useMedusa } from "../../../hooks/use-medusa";

const paypalClientId = process.env.GATSBY_PAYPAL_CLIENT_ID || ""
 const PaypalPayment = () => {
   const { 
     cart,
     actions: { completeCart, setPaymentSession },
   } = useCart()
   const [errorMessage, setErrorMessage] = useState(undefined)
   const [processing, setProcessing] = useState(false)
   const client = useMedusa()
   const paypalSession = useMemo(() => {
     if (cart.payment_sessions) {
       return cart.payment_sessions.find(s => s.provider_id === "paypal")
     }
     return null
   }, [cart.payment_sessions])
   if (!paypalSession) {
     return null
   }
   const completeOrder = async (authorizationOrder) => {
     const cart = await setPaymentSession("paypal")
     if (!cart) {
       setProcessing(false)
       return
     }
     await client.carts.updatePaymentSession(cart.id, "paypal", {
       data: {
         data: {
           ...authorizationOrder
         }
       }
     });
     const order = await completeCart(cart.id)
     if (!order || order.object !== "order") {
       setProcessing(false)
       return
     }
     setProcessing(false)
     navigate("/order-confirmed", { state: { order } })
   }
   const handlePayment = (data, actions) => {
     actions.order.authorize().then((authorization) => {
       if (authorization.status !== 'COMPLETED') {
         setErrorMessage(`An error occurred, status: ${authorization.status}`);
         setProcessing(false);
         return;
       }
       completeOrder(authorization)
     })
   }
   return (
     <PayPalScriptProvider options={{ 
       "client-id": paypalClientId,
       "currency": cart.region.currency_code.toUpperCase(),
       "intent": "authorize"
     }}>
         {errorMessage && (
           <span className="text-rose-500 mt-4">{errorMessage}</span>
         )}
         <PayPalButtons 
           style={{ layout: "horizontal" }}
           onApprove={handlePayment}
           disabled={processing}
         />
     </PayPalScriptProvider>
   )
 }
 export default PaypalPayment;

To briefly explain this code snippet:

You render a PayPal button that allows customers to pay with PayPal using components from
```
Copy to clipboard
@paypal/react-paypal-js
```
which you just installed. You pass the component
```
Copy to clipboard
PayPalScriptProvider
```
the PayPal client ID from the environment variables.
When the button is clicked, the method
```
Copy to clipboard
handlePayment
```
is executed which initiates authorization with PayPal using the method
```
Copy to clipboard
actions.order.authorize()
```
. This opens PayPal’s payment portal in a new window.
After the customer successfully completes payment, the fulfillment callback function passed to
```
Copy to clipboard
then
```
is executed. If there are any errors in the authorization, an error message will be shown on your online store. Otherwise, the
```
Copy to clipboard
completeOrder
```
method will be called.
In the
```
Copy to clipboard
completeOrder
```
method, PayPal is first set as the payment session of the current cart on your online store. Then, it is updated on the server with data that is received from PayPal after the customer authorized the payment.
Finally, the order is placed and the customer is redirected to the
```
Copy to clipboard
order-confirmed
```
page on your online store where they can see a summary of their order details.

Next, in

Copy to clipboard
src/components/payment/index.jsx

add an import for the

Copy to clipboard
PaypalPayment

component at the beginning of the file:

import PaypalPayment from "./paypal-payment"

Then, in the returned JSX you’ll find a switch statement that renders components on your online store based on the ID of the payment provider. Add a new case to the switch statement before the

Copy to clipboard
default

case.

This renders

Copy to clipboard
PaypalPayment

when the ID of the payment provider available for the customer on your online store is

Copy to clipboard
paypal

switch (ps.provider_id) {
  case "stripe":
    //...
  case "manual":
    //...
  case "paypal":
    return <PaypalPayment />
  default:
    return null
}

Save all changes before moving on to test the entire flow on your online store.

Test Checkout Flow: Start Selling Online

In this section, you’ll test placing an order on your online store on the storefront, then viewing the details on the admin and capturing payment.

Make sure that all 3 components (Medusa server, Medusa admin, and storefront) of your online store are running.

Then, on the storefront of your online store, choose a product and it to the cart.

Then, click on the cart icon and click on the “Checkout” button in the popup.

You’ll be taken to a one-page checkout on your online store where you have to enter your details and choose a shipping method.

Once you reach the last step of the checkout on your online store you should see the available payment methods in the current region including PayPal.

If you can’t see PayPal, make sure the correct region is selected at the top right of the navigation bar of your online store.

Try paying with PayPal by clicking on the first PayPal button on your online store.

A new page will open where you’re asked to log in to PayPal and authorize the payment.

Once you authorize the payment with a sandbox account, you’ll be taken back to the storefront of your online store.

If the authorization was successful, you’ll shortly be redirected to the Order Summary page on your online store.

On the Medusa admin of your online store, click on Orders in the sidebar.

You should see a new order on your online store.

Click on the order. You’ll see the order details including the items ordered and payment details.

To capture the payment on your online store, click on the “Capture payment” button.

What’s Next?

You just created a comic book online store using Medusa that has a search engine using MeiliSearch and PayPal as a payment provider.

Medusa is an open source ecommerce platform that has a lot of ecommerce features but also allows you to integrate other services into your ecommerce platform.

There’s much more that you can do with your online business:

Check more plugins that you can add to add more features to your ecommerce store, including using Strapi for CMS.
Customize your Medusa ecommerce platform by adding custom endpoints.
Deploy the server on Heroku and the Medusa Admin and Storefront of your online store on Netlify.

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