Medusa offers bespoke commerce infrastructure and is the most popular open source commerce platform on GitHub. The solution allows developers to build scalable and custom ecommerce applications through a composable stack that allows you to easily integrate with your favorite tools for payments to search, CMS and more.
Medusa has three core parts: Medusa Server, Medusa Storefront, and Medusa Admin. Unlike traditional ecommerce platforms, every component of Medusa can be customized to fit your requirements, allowing you to avoid hacky workarounds and the build-up of an unmaintainable stack over time.
At the end of this guide, you will be able to spin up a new Medusa store, use the prebuilt Next.js commerce template and deploy it on Vercel.
What is Vercel Commerce?
Vercel is a leading platform where you can deploy frontend applications. There are several pros to using Vercel to deploy the Medusa storefront.
Sites deployed in Vercel can be loaded very fast compared to all other deployment services; this is very important for an ecommerce site because fast loading times lead to better rank in search engines.
This tutorial uses Next.js, a framework that does server-side rendering. Server-side rendering (SSR) means pre-rendering pages in the server beforehand and sending them to the client. This will contribute towards lower initial loading speed of the website.
What is Next.js Commerce
Using Next.js, you can build different types of websites, including ecommerce storefronts. By plugging into the ecommerce platform’s APIs, you can build ecommerce storefronts with unique designs and a focus on providing a good user experience.
As Next.js is built by Vercel, deploying websites built with Next.js on Vercel is an ideal solution.
Some of Next.js’s benefits include:
- Support for static-site generator, which allows pre-rendering pages on the server and serve them as HTML files.
- Built-in development server, making development with Next.js faster and a good experience.
Why use Medusa
Medusa offers benefits for both developers and businesses. Its extensibility and customization-capabilities facilitate a smooth developer experience. It also gives businesses the freedom in choosing the features they offer and bringing their vision to life.
Medusa provides many essential ecommerce features including order management, product management, sales channels, complete checkout and RMA flows, and more.
All these features and Medusa’s core features are built into Medusa as abstract layers, allowing developers to customize these functionalities and flows.
The Medusa server is a headless server that exposes REST APIs both for storefront and admin functionalities. So, it’s possible to create unique storefront and admin by connecting to the APIs.
Features of Medusa’s Next.js Storefront
Medusa provides a Next.js storefront that you can use instead of building your own storefront. This storefront offers many features including:
- Product listing and detail pages with a clear design.
- Customer authentication and profile functionalities, allowing customers to view their orders, edit their information, and more.
- Full checkout flow supporting shipping details and methods, and ready integration with payment gateways such as Stripe and PayPal.
- Search capabilities that are ready to integrate with best-in-breed solutions like Algolia and MeiliSearch.
To use Medusa, you need to have Node.js installed on your local computer. If you don’t have it already, you can download it from the official Node.js website. You would also need a GitHub and Vercel accounts.
Lastly, you should have the Medusa server deployed. You can follow this guide to do that.
Setup Medusa Server
In this section, you’ll install the Medusa server, get an overview of its structure, and learn about deployment options.
If you already have the Medusa server installed and deployed, you can skip to the next section.
Install Medusa Server
To install the Medusa server, start by installing Medusa’s CLI tool:
npm install @medusajs/medusa-cli -g
Then, run the following command to install a Medusa server in a new directory,
:Copy to clipboard
medusa new my-medusa-store --seed
Finally, to start the Medusa server, change to the
directory and run the necessary command:Copy to clipboard
cd my-medusa-storemedusa develop
Medusa Server Structure
The Medusa server has a structure similar to this:
├── data│ └── seed.json├── src│ ├── api│ ├── services│ └── subscribers├── .env├── develop.sh├── docker-compose.yml├── medusa-config.js├── package-lock.json├── package.json├── tsconfig.json├── yarn.lock├── Dockerfile└── README.md
Some important files and directories include:
: This is where you perform custom development in Medusa. For example, you can create new API routes in theCopy to clipboard
directory.Copy to clipboard
: This file includes all configurations related to Medusa such as plugins used, database connection URL, Redis configurations, and more.Copy to clipboard
: During development, you can use this file to add your environment variables. In production, however, it’s highly recommended to use the method provided in your hosting provider to store environment variables.Copy to clipboard
Before you can deploy the Next.js storefront, you must deploy the Medusa server, as the Next.js storefront will interact with the server’s APIs.
Medusa’s documentation provides guides for different choices to deploy your Medusa server, both free and paid:
Feel free to choose any of these hosting providers and follow the documentation to deploy the server. Alternatively, you can deploy to a different hosting provider.
Prepare Medusa Next.js Storefront
Now that you have the Medusa server ready and deployed, you can start preparing the storefront. You can start by building your own storefront using the Medusa storefront API, but this tutorial uses the official Next.js Starter provided by Medusa, which is a starter kit for high-performance ecommerce sites.
To install the storefront, go to your preferred directory and run:
npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa medusa-storefront
This will create a new Next.js project with the Medusa Next.js starter code. Change to the newly created directory and rename the
file toCopy to clipboard
:Copy to clipboard
cd medusa-storefrontmv .env.template .env.local
Deploy on Vercel Commerce
At the end of this section, you will know all about deploying your Medusa storefront on Vercel.
Push Storefront to GitHub
Before deploying your storefront to Vercel, you have to upload your code to GitHub. Go to GitHub and create a new repository with your preferred name.
Go back to the terminal and run the following commands inside the folder containing Medusa storefront:
git remote add origin <REPO_URL>git push -u origin main
Make sure to replace the
andCopy to clipboard
placeholders with your real values. After completing this step, your code should be uploaded to GitHub; you can confirm this by going to the GitHub repository page.Copy to clipboard
Now that everything else is ready, all you have to do is deploy the storefront on Vercel.
Once you’re inside the Vercel dashboard, click on the Add New button and choose Project from the menu.
This creates a Vercel project. Next, select Continue with GitHub to grant access to your GitHub account or the specific repository you want to deploy.
From the repository list, pick the repository you want to deploy and click on Import.
Environment Variable Configuration on Vercel
Before deploying, you have to set the environment variables in Vercel. In Vercel Configure Project page section, expand Environment Variables and you will see a page similar to the one below.
Now, add your environment variables one by one to these input boxes. To do that, open the
file inside your project folder and for each line of that file, input the part beforeCopy to clipboard
sign to the name and the part afterCopy to clipboard
to the value.Copy to clipboard
If you’re not using any payment processors or search services, you would only be required to enter one environment variable:
. This is where you should input the deployed Medusa server URL. Enter the corresponding information in the environment variable settings and click on Deploy.Copy to clipboard
Add Server Environment Variables
You need to copy your storefront’s URL that you will find under Domains on the Vercel project page and add it under the environment variable,
, of your Medusa server instance. This will make sure that no CORS errors will occur.Copy to clipboard
Visit the default store domain, you will see Medusa storefront working with all the products being displayed (which means the connection to backend is successful).
Testing Storefront After Deployment
After a few seconds, you will see that the deployment has been completed and the storefront is up and running.
Next Steps for your Vercel Ecommerce Store
This guide scratches the surface of what more you can do with Medusa. Here are some additional steps you can take to take your Vercel ecommerce store live and start selling:
- Install Medusa Admin to manage your store’s products, orders, customers, and more.
- Install Stripe or PayPal as payment gateways.
- For advanced search functionalities, install Algolia or MeiliSearch.
- Implement claim order flow in your storefront to allow guest customers to claim their orders after registering.
- Install a live-chat widget like Chatwoot on your storefront.
- Integrate Matomo with your storefront for advanced analytics.
Now, you should have a clear understanding of Vercel commerce. Once you have deployed the storefront, you can focus on making the storefront better.
- Read this guide to know more about the storefront template you used.
- Read this guide to learn how to integrate Stripe into your store
- Check out this documentation to learn all sorts of things you can do with Medusa.
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
You may also like
May 25, 2023
Good Chef & Webbers: Powering subscriptions with Medusa’s commerce modules
Shahed and Nicklas
On this page