Medusa is an open source ecommerce platform that provides developers with customizability and extendability within all of its 3 components - the headless server, the admin, and the storefront.
Whether you want to add third-party integrations or custom functionalities, you have full freedom with how you implement them. Medusa is an open source ecommerce platform that comes packed with important ecommerce features out-of-the-box and ready-made plugins that you can install with a plug-and-play style.
In this tutorial, you’ll learn how to add product reviews to your Medusa server for your online store. You’ll also customize both the Medusa admin and Next.js storefront of your online store to show the reviews, and allow customers to add their reviews to products on the storefront of your online store.
You can find the code for this ecommerce tutorial in this GitHub repository.
Ecommerce Platform Prerequisites
Before you follow along with this tutorial, you must have the following requirements installed:
- Node.js v14 or greater
- PostgreSQL
Ecommerce Server Setup
To install the Medusa server, you need to install the CLI tool first:
Then, run the following command to install the Medusa server:
This installs your Medusa server into a newly-created directory
.Copy to clipboardmedusa-reviews
Configure PostgreSQL Database
Create an empty PostgreSQL database. Then, in
in the root of your Medusa server directory, add the following environment variable:Copy to clipboard.env
Where
is the URL to the database schema you just created in PostgreSQL. The URL should be of the formatCopy to clipboard<YOUR_DATABASE_URL>
. For example,Copy to clipboardpostgres://<USERNAME>:<PASSWORD>@<HOST>/<DB_NAME>
.Copy to clipboardpostgres://postgres:postgres@localhost/medusa-reviews
Then, change the database configuration in the exported object in
to use PostgreSQL instead of SQLite:Copy to clipboardmedusa-config.js
Seed and Migrate the Database
Finally, run the following command to migrate Medusa’s database schema and seed it with demo data:
Add Product Reviews
In this section, you’ll add the
model, its associated repository, the migration to create it in the database, and the service to facilitate accessing and manipulating product reviews in the database from endpoints.Copy to clipboardProductReview
Create the ProductReview model
Before you create the model, install the
library to add validation to some of the columns in the new model:Copy to clipboardclass-validator
Then, create the file
with the following content:Copy to clipboardsrc/models/product-review.ts
You create a new model
that extendsCopy to clipboardProductReview
.Copy to clipboardBaseEntity
adds 3 common columnsCopy to clipboardBaseEntity
,Copy to clipboardid
andCopy to clipboardcreated_at
.Copy to clipboardupdated_at
You additionally add the columns
,Copy to clipboardid
,Copy to clipboardproduct_id
,Copy to clipboardtitle
,Copy to clipboarduser_name
, andCopy to clipboardrating
.Copy to clipboardcontent
You also add a method to be run before inserting a new record in the database for this model which uses a utility function from Medusa. If the record doesn’t have an ID, a random and unique ID is generated for it.
Create the Repository
The next step is to create the Typeorm repository for this model. Typeorm repositories provide you an API to perform a variety of actions on tables in the database
Create the file
with the following content:Copy to clipboardsrc/repositories/product-review.ts
Create the Migration
Migrations are used to add or modify a database schema before running the server. It eliminates the need to do it manually on your RDBS each time you want to install your server.
Typeorm migration filenames are prefixed with a timestamp, so you have to create your own using this command:
This will create the migration
in the directoryCopy to clipboardProductReview
. You should find a file insideCopy to clipboardsrc/migrations
that has a file name of the formatCopy to clipboardsrc/migrations
.Copy to clipboard<TIMESTAMP>-ProductReview.ts
Inside the migration, there’s an
method and aCopy to clipboardup
method. TheCopy to clipboarddown
method is executed when you run the migration, and theCopy to clipboardup
method is executed when you revert the migration.Copy to clipboarddown
Replace the
method with the following:Copy to clipboardup
This creates the table with its columns, makes the column
the primary key, and adds a foreign key on the columnCopy to clipboardid
.Copy to clipboardproduct_id
Then, replace the
method with the following:Copy to clipboarddown
This drops the table
if you revert the migration.Copy to clipboardproduct_review
Before you can run migrations with Medusa, you need to run the
command to transpile the Typescript files into JavaScript files:Copy to clipboardbuild
Then, run the following command to run the migrations:
This runs the migration you created which creates a new table
in the database for your Medusa server.Copy to clipboardproduct_review
Create the Service
In this section, you’ll create the service that you’ll use in endpoints to access or add product reviews.
Create the file
with the following content:Copy to clipboardsrc/services/product-review.js
This creates the service
. This service has 2 methods.Copy to clipboardProductReviewService
gets all reviews for a product ID, andCopy to clipboardgetProductReviews
creates a new product review for a product ID using data passed to it as a second parameter.Copy to clipboardaddProductReview
Create Endpoints
Finally, you’ll create 3 new endpoints on your Medusa server:
- A
routeCopy to clipboardGET
to get reviews for a product on the storefront.Copy to clipboard/store/products/:id/reviews
- A
routeCopy to clipboardPOST
to add a new review for a product on the storefront.Copy to clipboard/store/products/:id/reviews
- A
routeCopy to clipboardGET
to get reviews on the Medusa admin.Copy to clipboard/admin/products/:id/reviews
Create the file
with the following content:Copy to clipboardsrc/api/index.js
Notice that you have to use the
middleware with the configuration imported fromCopy to clipboardcors
for each route. If you don’t use theCopy to clipboardmedusa-config.js
middleware for the routes then you will not be able to access them from the storefront or from the admin.Copy to clipboardcors
In the
routeCopy to clipboardGET
, you retrieve theCopy to clipboard/store/products/:id/reviews
that is registered in the scope by the Medusa server when you run it. You then use the service to retrieve the reviews using the methodCopy to clipboardproductReviewService
.Copy to clipboardgetProductReviews
The
routeCopy to clipboardGET
is similar to theCopy to clipboard/admin/products/:id/reviews
routeCopy to clipboardGET
, but it uses the cors options for admin requests.Copy to clipboard/store/products/:id/reviews
In the
routeCopy to clipboardPOST
, you retrieve theCopy to clipboard/store/products/:id/reviews
and use theCopy to clipboardproductReviewService
method to add a review for the product, then return the created product review.Copy to clipboardaddProductReview
Run the Server
To run the server, run the following command:
This runs the server on
. Make sure the server is running throughout the tutorial.Copy to clipboardlocalhost:9000
You can test out the endpoints you just added through a tool like Postman, but you’ll be testing them out throughout the rest of the tutorial.
Open Source Ecommerce Platform Admin Setup Admin Setup
The next step is to install and set up the Medusa Admin for your online store.
In your terminal and in a different directory than the Medusa server, run the following command to install the Medusa admin for your online store:
Then, change to the newly-created directory
and install the necessary dependencies:Copy to clipboardmedusa-reviews-admin
Create Reviews Component
You’ll show the reviews on the details page of each product.
So, create the file
with the following content:Copy to clipboardsrc/domain/products/product-form/sections/reviews.js
In this code snippet, you retrieve the reviews from the ecommerce server using the endpoint you created earlier, then you display the reviews if there are any.
Then, in
import theCopy to clipboardsrc/domain/products/product-form/index.tsx
component at the top of the file:Copy to clipboardReviews
And in the returned JSX in the component, add the following before the
wrappingCopy to clipboarddiv
:Copy to clipboardRawJSON
Test it Out
If you run your medusa admin with the following command:
You’ll first be asked to log in to the admin. You can use the demo email “admin@medusa-test.com” and password “supersecret”.
After you log in, go to the Products page from the sidebar, then choose one of the existing products on your ecommerce site.
Scroll down and you should find “Product Reviews” but there are currently no reviews to view on your ecommerce website.
You’ll come back to this page after adding the “Add Review” functionality on the storefront of your ecommerce website.
Setup Next.js Storefront for your Online Store
This section covers how to show product reviews on the Next.js storefront and allow users to add their reviews on your ecommerce website.
If you’re alternatively using the Gatsby storefront or your custom storefront for your ecommerce website, you can still follow along to see the general approach of how to implement it in the storefront of your ecommerce website.
In your terminal and in a different directory than the directories holding the Medusa server and Medusa admin, run the following command to install the Next.js storefront:
Then, change to the newly created directory
and rename theCopy to clipboardmedusa-reviews-storefront
file:Copy to clipboard.env
You need to install a few libraries that are useful for this tutorial:
Where
is used to show a star icon for the rating,Copy to clipboard@heroicons/react
is used to easily create a modal for the product review form, andCopy to clipboardreact-hyper-modal
is used for the form validation.Copy to clipboardyup
Implement Product Reviews
In this section, you’ll show the product reviews under the description on every product page. You’ll also show a button to add a new review. This button opens a modal with a form to add the review.
In
add the following imports at the beginning of the file:Copy to clipboardpages/product/[id].js
Then, at the beginning of the
component, add the following state variables:Copy to clipboardProduct
The
state variable is used to store the reviews retrieved from the server. TheCopy to clipboardreviews
state variable is used to control whether the modal holding the product review form is opened or closed.Copy to clipboardisModalOpen
Also, add a variable that uses Formik and Yup to easily create a form with validation functionalities:
This form has 4 fields:
,Copy to clipboardtitle
,Copy to clipboarduser_name
, andCopy to clipboardrating
. All fields are required, and the value of theCopy to clipboardcontent
field must be at least 1 and at most 5Copy to clipboardrating
On submit, a
request is sent to the endpoint you created earlier, and you pass the review data in the body. Then, the reviews are retrieved from the server using theCopy to clipboardPOST
function and the modal is closed.Copy to clipboardgetReviews
Next, add the
function and aCopy to clipboardgetReviews
that gets the reviews whenever theCopy to clipboarduseEffect
changes:Copy to clipboardproduct
This retrieves the reviews from the server using the endpoint you created earlier on the server.
Finally, add the following before the last 3 closing
elements in the returned JSX:Copy to clipboarddiv
You first create the modal using
. This modal is opened by the “Add Review” button. When it’s opened, a form with 3 input fields and a textarea is shown to add the review. When the form is submitted, the function passed toCopy to clipboardHyperModal
in the options object ofCopy to clipboardonSubmit
is executed.Copy to clipboarduseFormik
Then, if there are any reviews, you render them one by one.
Test it Out
To run the server for the storefront of your ecommerce website, run the following command:
This runs the storefront on
. Open it in your browser and choose one of the products. You can see that it has no reviews.Copy to clipboardlocalhost:8000
Click on Add Review to add a review. A modal opens with the form to add a product review.
Fill out the form and click Add. You should be able to see the reviews you add now. Add as many as you want.
Go back to the admin panel and open the page of the product you just added reviews to. You should see the same reviews now on the admin panel.
What’s Next
There’s still much more that you can do in your Medusa server to customize it with all the services and ecommerce features that you need:
- Use Stripe as a Payment Provider
- Integrate your server with Slack for automated notifications whenever a new order is placed.
- Deploy your server on Heroku and your Medusa admin 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
Try Medusa
Spin up your environment in a few minutes.
