Tutorial

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.Post thumbnail image

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:

  1. Node v14 or higher.
  2. Postgres with an empty database created.
  3. MeiliSearch for the search engine.
  4. A PayPal developer account.
  5. 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 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 comic-store directory to install the 3 plugins:

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

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

Make sure in package.json that the versions for @medusajs/medusa, medusa-interfaces and @medusajs/medusa-cli are greater than or equal to 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 .env variable.

Open the .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.

DATABASE_URL is the URL to connect to your PostgreSQL database schema. It should be of the format 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 PAYPAL_SANDBOX to true.

Configure Server

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

Server configurations are all in medusa-config.js. This includes database, plugins, and more configurations.

Open 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 .env file.

Next, in the 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 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 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 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 comic-store directory, run the following command:

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

Then, change to the newly created 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 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 comic-store and 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 comic-storefront.

Then, change to the comic-storefront directory and rename .env.template to .env.development:

mv .env.template .env.development

Add Environment Variables

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

In .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 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 src/pages/index.js. You should find in the returned JSX the component 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 src/images with the name hero.png.

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

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 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 instantMeiliSearch that is exported from the dependency @meilisearch/instant-meilisearch which you just installed.

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

The Search component then displays a search bar using components from react-instantsearch-dom.

When the user enters a query and there are results, each result is rendered using the 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 index.jsx and import the Search component at the beginning of the file:

import Search from "./search"

Then, in the returned JSX add the Search component before 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 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 @paypal/react-paypal-js which you just installed. You pass the component PayPalScriptProvider the PayPal client ID from the environment variables.
  • When the button is clicked, the method handlePayment is executed which initiates authorization with PayPal using the method 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 then is executed. If there are any errors in the authorization, an error message will be shown on your online store. Otherwise, the completeOrder method will be called.
  • In the 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 order-confirmed page on your online store where they can see a summary of their order details.

Next, in src/components/payment/index.jsx add an import for the 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 default case.

This renders PaypalPayment when the ID of the payment provider available for the customer on your online store is 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:

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

Person photo
Shahed NasserMay. 24, 202211 min.

Want to know more about Medusa

Find related blog posts below

Tutorial

Building with Nuxt.js for a Vue Ecommerce Platform Part 3: Ecommerce Checkout Flow with Stripe

In this guide, you will learn how to integrate and use Stripe as a payment provider in Medusa and Nuxt.js.

Tutorial

Online Marketplace Tutorial Part 3: Implement User Management and Permissions

This part of the tutorial focuses on user management within a store in a marketplace.

Article

Which Frontend Framework You Should Pick for Your Ecommerce Storefront?

This article introduces you to the most efficient frontend frameworks that you can use to build an ecommerce storefront

NEWSLETTER

Receive the most important updates around Medusa and our ecosystem