What is this article about?
Medusa just released its new serverless Product Module. I’ve built a demo with Medusa and Next.js that showcases personalization using this new module running in a serverless Next.js function. In this post I will explain how the personalization logic is built, so you can start using the module to personalize your own storefronts.
In a nutshell, the Product Module connects to a product database and provides you with a service layer to communicate with the database directly within your Next.js project. This means there’s no need for a separate backend, and you get blazing fast response times. This makes it very suitable for use cases like real-time personalization.
What will you be building?
You'll learn how to build real-time personalization logic using Next.js API routes and the Medusa Product Module, as showcased in the demo I've built:
After completing this tutorial, you should be able to personalize your own Next.js storefront and apply the concepts to your own use case. I will not go into the frontend implementation in this article, if you'd like to know more about that, let me know.
Medusa: open-source SDK for commerce
Quick background: Medusa is an open-source SDK for ecommerce. It consists of modularized commerce logic like carts, products and order management. The modules are incredibly portable and can be tailored exactly to your specific needs.
The Product Module is part of the latest Medusa Recap. If you like this post, please help spread the word by liking the Recap announcement Tweet. 💜
Get started: install the module
The Product Module is installed from npm into the Next.js project and connects to a Medusa database when imported and initialized. Follow this guide to get it up and running in no time.
How to use the module
Create /api/products/route.ts and initialize the module:
import { initialize as initializeProductModule } from "@medusajs/product";
import { NextRequest, NextResponse } from "next/server";
export async function GET(req: NextRequest) {
// initialize the module
const productService = await initializeProductModule();
// list all products
const products = await productService.list();
// return the product list json in the response
return NextResponse.json({ products });
}
In this example we first import the Products Module, NextRequest, and NextResponse. Inside the GET function, we then initialize the module as productService. We then call the .list() method with an empty object as an argument to retrieve all products from the database. And finally, we return the full product list json in the response.
In your frontend component, you can now easily fetch the products from your created API route:
const response = await fetch('/api/products');
const data = await response.json();
// do stuff with data.products
Start personalizing
In the demo, I use two parameters to personalize the products shown on the homepage:
- User location
- Last clicked product category
The user location will decide which products are shown in the first section:
The last clicked product category will decide what product category is shown on top of the second section:
Let's dig into the first section:
Personalize on user location
Since the project is deployed on Vercel, we can use the built-in x-vercel-ip-country header to get the user's country code. I created a mapper object (isoAlpha2Countries) in lib/utils that maps the country code to its full country name and continent.
In our product database, I've added continent tags to all products. So there are products tagged with Europe, Africa, Asia and so on. We can use that tag to query products that are relevant to the user's location.
Let's add it to our route:
import { initialize as initializeProductModule } from "@medusajs/product";
import { NextRequest, NextResponse } from "next/server";
import { isoAlpha2Countries } from "@/lib/utils";
export async function GET(req: NextRequest) {
// initialize the module
const productService = await initializeProductModule();
// Get the user's country code from the header.
const countryCode = req.headers.get("x-vercel-ip-country");
// Get the user's continent from the mapper.
const { country, continent } = isoAlpha2Countries[countryCode];
// List 3 products with a tag that matches the user's continent.
const personalizedProducts = await productService.list(
{ tags: { value: [continent] } },
{ take: 3 }
);
// return the product list and country data in the response
return NextResponse.json({
personalized_section: {
products: personalizedProducts,
country,
continent,
}
});
}
We can now easily fetch 3 products personalized on the user's location from any frontend component. We can also use the continent and country variables to personalize the copy above the products.
const response = await fetch('/api/products');
const data = await response.json();
const { products, country, continent } = data.personalized_section;
// do stuff with products, country and continent
Personalize on user behavior
We're gonna personalize the second product section based on user behavior. We'll track what product a user has viewed last, and then show products from that category on top.
This will work as follows:
- When a user enters the site, we'll generate a unique user id using Next.js Middleware and store it in a cookie.
- When a user clicks a product, we'll store the products category name and id in a Vercel KV store.
- In
/api/products/route.ts, we'll use the user id to retrieve the last viewed category from the KV. - We then retrieve all products from the Products Module, sort the products with the last viewed category on top, and return the sorted list.
Set a user id
Let's start with handling the user id in src/middleware.ts:
import { v4 as uuidv4 } from "uuid";
import { NextResponse, NextRequest } from "next/server";
export async function middleware(request: NextRequest) {
// check if the userId cookie exists
// if not, generate a new userId using uuid
const userId = request.cookies.get("userId")?.value || uuidv4();
// initialize a new response
const response = NextResponse.next();
// set the userId cookie
response.cookies.set("userId", userId);
return response;
}
// by default, middleware will fire on every request
// use the matcher to match certain routes only
export const config = {
matcher: ["/", "/product/:handle/"],
};
Store user behavior in Vercel KV
We now have a userId cookie available to identify unique users. Let's create a new API route in /api/category-tracker/route.ts to handle the category tracking in the KV store:
import { kv } from "@vercel/kv";
import { NextRequest, NextResponse } from "next/server";
type UserData = {
categoryId: string;
categoryName: string;
};
export async function POST(request: NextRequest) {
// grab the category id and name from the request
const { categoryId, categoryName } = ((await request.json()) ??
{}) as UserData;
// return a null response when the category data is missing
if (!categoryId || !categoryName) {
return NextResponse.json(null);
}
// create the userData object
const userData = {
categoryId,
categoryName,
};
// grab the userId from the cookie we created with the middleware
const userId = request.cookies.get("userId")?.value!;
// set the userData object to the userId in the KV store
await kv.set(userId, userData);
// return an empty response
return new NextResponse();
}
On the frontend, we can now easily do a POST request to /api/category-tracker to store the user's last viewed category.
await fetch("/api/category-tracker", {
method: "POST",
body: JSON.stringify({
categoryId,
categoryName,
}),
});
For example, you can wrap it in a trackCategory() function and pass it as the onClick prop for your product card component.
Update /api/products/route.ts
We can now update the route to fetch the user data, get all products and sort the products based on the last viewed category:
import { kv } from "@vercel/kv";
import { initialize as initializeProductModule } from "@medusajs/product";
import { NextRequest, NextResponse } from "next/server";
import { isoAlpha2Countries } from "@/lib/utils";
type UserData = {
categoryId: string;
categoryName: string;
};
export async function GET(req: NextRequest) {
// initialize the module
const productService = await initializeProductModule();
// Get the user's country code from the header.
const countryCode = req.headers.get("x-vercel-ip-country");
// Get the user's continent from the mapper.
const { country, continent } = isoAlpha2Countries[countryCode];
// List 3 products with a tag that matches the user's continent.
const personalizedProducts = await productService.list(
{ tags: { value: [continent] } },
{ take: 3 }
);
// get the userId from the cookie
const userId = req.cookies.get("userId").value;
// get the user's last viewed category form the KV
const userData = await kv.get<UserData>(userId);
const {categoryId, categoryName} = userData ? userData : {} as UserData;
// get all products from the module
const allProducts = await productService.list();
// sort all products with the last viewed categoryId
// on top using a sorting function (not in this example)
const sortedProducts = sortProducts(allProducts, categoryId);
// return all personalization data in the response
return NextResponse.json({
personalized_section: {
products: personalizedProducts,
country,
continent,
},
all_products_section: {
category_name: categoryName,
products: sortedProducts
},
});
}
We now have easy access to all relevant personalized data in our frontend components!
const response = await fetch('/api/products');
const data = await response.json();
const { products: personalizedProducts, country, continent } = data.personalized_section;
const { products: orderedProducts, category_name: categoryName } = data.all_products_section;
// do stuff with products, country, continent and categoryName
Concluding
Now you know how to use the Medusa Product Module with Next.js to personalize your storefront! You can apply the same principles to other types of personalization that might be relevant to your business.
If you have any questions, let me know in the comments below!
If you want to dive deeper into the source code of the demo, you can check out the full repo here.
This module is part of Medusa's latest Recap. If you thought this was interesting, check out our other launches:
Top comments (2)
the pre-built starter templates need so much work to put in, there should be more robust templates with sort,search,filter,attributes,category features so that one can start right of the bat.
Hey, what template are you referring to? I've recently updated the Next.js starter to support the new App Router. It has search support built in. Would def be cool to add some of the features you mentioned to the starter, like sorting/filtering.