DEV Community: Victor Gerbrands

What we've learned from the transition to Next.js 14 with Server Components

Victor Gerbrands — Tue, 06 Feb 2024 10:23:55 +0000

We recently redesigned the Medusa Next.js Starter Template. The redesign also included a larger refactor to use Next.js 14 and the newer Next/React features like App Router, Server Components, and Server Actions. If you are considering migrating to Next.js 14 and Server Components here’s everything we learned.

The challenge

Medusa is an open-source backend commerce framework with APIs and tools to manage Products, Orders, Customers, and more. For everything beyond standard commerce functionality, we make it easy to introduce your own custom data models, business logic, API endpoints, etc. Medusa’s APIs can be used in storefronts that your customers interact with - an example of such a storefront is our Next.js starter.

On many websites, content changes relatively infrequently. And when it changes it’s often acceptable that there is some delay between content updates to visitors seeing it. For a blog post, for example, it’s acceptable that a few minutes pass between hitting publish and the post showing up on the site. When this is the case, statically generating and serving the webpages via a CDN greatly benefits visitors as the page loads quickly.

In e-commerce, however, dynamism is crucial. When a customer adds something to their cart, it should happen instantly. If a product sells out, it should be immediately clear to all customers. And with multi-currency and personalized prices, the customer should see the price they will be charged in real time. E-commerce websites, therefore, have to interact with a server that can deliver this information. Front-end frameworks like React all have mechanisms for this and in the past years, the common approach has been directing browsers to fetch data from servers that the framework would then render to HTML on the client.

This is also what Medusa’s Next.js starter did. When the customer visits the Cart page the starter would trigger an API call from the browser to fetch the customer’s cart data from Medusa and render it. To keep track of the user’s Cart and optimize the storefront experience, the previous version used client-side state and React Context to store Cart IDs, cache requests, and much more.

With Next.js 14, you can still make requests from the client; however, new tools like React Server Components and Server Actions are now available to simplify the developer experience for caching and state management when building highly dynamic websites. This new paradigm requires you to think differently about how you build your React applications, so there was a bit of a learning curve to migrating the starter to using the new tools. Below are the key differences I encountered and how I have understood React’s new tools.

Data fetching and state

Let’s tackle data fetching and state management first, taking the shopping cart as an example.

The Medusa server already keeps track of the contents of the current shopping cart. By retrieving this data, storing it in the Next cache, and then accessing that cached data from any component that might need it, we eliminate the need to manage the cart state in the client.

By revalidating the cart data whenever we modify it, we make sure the cache always holds an updated version of the cart, accessible throughout the app.

Let’s dig a bit deeper into how this works in Next.js:

Fetching and caching

Next.js has a caching mechanism built-in that automatically works with the native fetch API. This means that every fetch request is automatically cached until revalidated. As a result, you can safely fetch the same data from every component that needs it without worrying about doing 20 duplicate requests. This eliminates the need for keeping a global data state using Context or prop drilling.

At first, re-fetching the same data multiple times in a component tree seemed counterintuitive as you’d normally fetch data in one place, and pass it down via either Context or props. You must also remember to revalidate the relevant parts of the cache every time you mutate data on the server. These patterns take some getting used to.

My way of thinking about it is that in the previous model, a fetch meant going to the server and getting data back. With Next.js’s caching mechanism, a fetch is an abstraction for an intent to get some data and Next.js is then in charge of delivering it either from its cache or by going to the server for you. This creates super fast interactions, but it also forces you to be meticulous about revalidation which was not a concern previously.

Once figured out, the caching mechanics are very effective in practice. Fetching new data from the server is swift, and all subsequent requests load almost instantly from the cache. This leads to a responsive front-end performance when navigating through your app.

Data mutations with Server Actions

Now we know how to fetch and cache data. But how do we handle data mutations, like adding an item to the shopping cart? User interactions often trigger these mutations and require us to use a Client Component to render variant selectors and an "add to cart" button. But we aim to manage API interactions server-side. To accomplish this from a Client Component, we can use Server Actions.

Server Actions are asynchronous functions executed on the server. They can manage form submissions and data mutations in Client Components. Under the hood they trigger a POST request to the Next.js server. The actions can be used like any other function in your project, making them convenient to work with.

In the new Starter, we use the Medusa JS client through Server Actions to interact with the Medusa server. This replaces many client-side data mutation hooks from the medusa-react package used in previous versions.

Implementing “add to cart” - before and after

Let’s take the “add to cart” action and compare how to implement it in both the old and the new version.

First of all, we no longer have to wrap our root layout in Context Providers to give its children access to data and actions. In the new setup, we can keep the root layout simple and server-rendered.

Instead of defining the addToCart function in the ProductProvider, we’d now export it from an actions.ts file. There’s two significant differences here you should note:

The “use server” keyword at top of the file. This tells Next.js to execute this function on the server, even if its called from a client component.
The revalidateTag function call on line 15. This ensures that cart cache is revalidated and all components using cart data will fetch the latest data: the cart with the newly added item in it.

Now we can import and use the addToCart function like any other function in a client component. Notice the "use client" keyword on top of the file. This tells Next.js this should be a client component. The product variant is fetched in its parent Server Component, and passed down as a prop. All data fetching and mutating is handled by the server.

Server vs Client components

React Server Components allow you to build UIs that can be rendered on the server. Server components have a couple of benefits. Most notably, they have access to server-side data fetching. This can enhance performance by decreasing data fetching time and reducing the number of client requests. It also means you don’t have to expose API keys in the browser or worry about CORS. They can also be pre-rendered or cached on the server. This means the client gets served the rendered HTML and doesn’t need to download, parse and execute the JavaScript needed to render the page.

So when should you use a Server Component? As a rule of thumb, any component can be a Server Component, unless it needs client-side interactivity. If you need access to React hooks like useState or useEffect, or want to attach an onClick event handler to a button, you need to use a Client Component.

Client Components can be children of Server Components, meaning you can use a Server Component to fetch data server-side, and pass it down as a prop to the Client Component.

Let’s have a look at the product page to see the component structure:

All components marked in red, including the page itself, are Server Components. There are two exceptions: the product actions and the cart button/modal on the top right. These require client-side interactivity and event handlers. Since they are both rendered within Server Components, we can fetch cart and product data on the server and pass it down as a prop.

Static pre-rendering

Looking at the product page above, we can identify some parts of the page that use static data. The product title, description and images are all available when we build the app, and don’t change. They won’t change based on user behaviour and the general change frequency isn’t high. This means we can pre-render these parts of the page at build time as static HTML. This will improve page loading times.

The cool thing is that we can leave ‘holes’ in the static HTML for the server to stream dynamic data into. The server can quickly deliver the statically generated HTML with fallbacks. This is done by wrapping the components that require dynamic data within <Suspense> boundaries and providing a fallback. As the user views the page, the server streams in the dynamic data, replacing the static fallbacks.

Moving state to the URL

In the process of migrating to Next.js 14, one key shift in approach is the idea of moving state to the URL. This concept involves manipulating the URL to reflect and manage the application's state, providing a global state when using Server Side Rendering. Let's delve into how and why we implemented this strategy.

Medusa offers support for multi-region stores, allowing variation in pricing, inventory, and fulfillment options based on the user's region. The current region should be accessible by multiple components in the tree, on both the server and client sides. To facilitate this, we added a country code to the path, moving the region state to the URL. E.g. https://next.medusajs.com/gb or https://next.medusajs.com/nl.

There’s a couple of reasons we decided move the country code to the path:

It enables static pre-rendering.
It makes the country code globally available.
It allows search engines to index localized pages. This has a massive SEO benefit if you run a multi-region / multi-language store and want to rank well in all regions.

There’s a reason we didn’t go with URL search parameters to keep track of the region. I’ll explain why later.

Using search params

Another example of where we moved state to the URL is in the checkout flow. Since it's a one-page checkout, we must monitor the completed checkout steps and determine which parts of the checkout UI should be rendered.

In the previous version, we’d keep track of this checkout state using React Context. Since the high-level checkout components have been upgraded to Server Components and the checkout state needs to be accessible to all child components, we've relocated the state to a step= search parameter in the URL.

There’s a couple of caveats to moving state to the URL. First of all, accessing search params from Server Components is a hassle. On the server side, they’re only available from within page.tsx, where they will be passed as props. If you need the params in any other Server Component, you’ll need to pass it down as a prop from the main page.

From Client Components it’s easy to access the dynamic URL params with the useParams and useSearchParams React Hooks respectively.

Be aware that using the searchParams prop or the useSearchParams disables static rendering. As a result, the entire route will be dynamically rendered. If you only need to access the params from a Client Component, consider wrapping that component in <Suspense> boundaries. This allows dynamic rendering up to that Suspense boundary, while the rest of the page can still be statically rendered.

To the best of my understanding, this doesn't apply to params and useParams. That's why I decided to use them for the country code. As a dynamic path parameter it’s still globally accessible, but doesn’t disable static rendering.

Conclusion

In conclusion, the new patterns for fetching/caching that Next.js 14 introduces require some getting used to. Once you get the hang of it, It’s quite convenient to just be able to fetch the data where you need it, instead of having to set up client-side Context or endless prop drilling. The caching makes your UI feel very snappy and fun to use.

Same goes for working with Server Components and Server Actions. It requires you to plan out the structure of your app and forces you to think about what can be rendered on the server, and what has to be rendered in the client.

In my opinion, this method of work contributes to a cleaner, well-structured codebase. It clearly separates server and client code, logically groups Server Actions together, and the App Router enforces a clear project structure.

However, the approach is opinionated and involves a lot of 'magic' happening behind the scenes, such as with caching and Server Actions. Whether or not you're comfortable with this ultimately depends on personal preference.

Want to try out the Medusa Next.js Starter?

Like Medusa, the Next.js Starter is fully open source. Check out the live demo or get the code on GitHub.

Building an AI assistant for ecommerce with Medusa, Vercel AI SDK, and OpenAI

Victor Gerbrands — Thu, 12 Oct 2023 10:14:23 +0000

In today's fast-paced ecommerce landscape, efficiency and automation play a significant role in improving customer experience and operational efficiency. Store owners are continually exploring innovative ways to streamline their processes.

One noteworthy trend is the application of AI-powered assistants. I'd like to share a recent project, an AI assistant that simplifies the returns process in your ecommerce store:

// Detect dark theme var iframe = document.getElementById('tweet-1712381789069582550-632'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1712381789069582550&theme=dark" }

The tech stack

Before delving into the AI assistant's functionality, let's review the technology stack that powers it. Our project relies on the following key technologies:

Medusa: Medusa serves as the foundation for our AI assistant. It provides the necessary ecommerce logic required for the bot to function smoothly. With Medusa, we have the core commerce functionality ready to support our AI assistant.
Vercel AI SDK: The Vercel AI SDK is instrumental in handling various AI-related tasks, allowing seamless integration of our AI assistant into the ecommerce ecosystem, enabling interaction with the store's data and processes.
OpenAI: At the core of this project is OpenAI's powerful language model (gpt-3.5-turbo-0613). It's the engine behind the AI assistant's ability to understand and respond to natural language commands.

Exploring Function Calling

Building this AI assistant offered a valuable opportunity to explore GPT's function calling capabilities. GPT is known for text generation, but it can now also execute functions to retrieve data and perform action. This makes it a versatile tool for creating AI assistants.

Medusa's role in empowering AI assistants

Medusa, with its core commerce logic and flexible architecture, is an excellent choice for building AI assistants. Here's why Medusa is well-suited for the task:

Core Commerce Logic: Medusa provides essential commerce logic, granting the AI assistant access to vital ecommerce functionalities right from the start.
Custom Endpoints: Medusa's flexibility allows the creation of custom endpoints to connect with external services, such as the OpenAI API. This enables the AI assistant to integrate seamlessly with other services and perform tasks beyond standard ecommerce operations.
Custom UI Components: Medusa UI allows for the creation of a native-looking admin component that blends seamlessly into the existing admin interface, enhancing user experience and ease of management.

The power of natural language

A noteworthy feature of this AI assistant is its capacity to understand and respond to human language. By integrating the AI layer into Medusa, store owners can initiate complex custom workflows with simple, plain language instructions, making it user-friendly and accessible.

Imagine instructing the AI assistant to manage returns, update product listings, or handle customer interactions using everyday language. The possibilities are extensive, and the convenience is undeniable.

In summary, AI assistants like this one are contributing to the evolving landscape of ecommerce. They're becoming valuable tools for store owners looking to streamline operations and improve the customer experience. The project I've shared illustrates the potential of combining Medusa, Vercel AI SDK, and OpenAI to create practical AI assistants that cater to the needs of ecommerce businesses.

Next time you consider ways to enhance your ecommerce store, think about the possibilities AI can offer. The AI assistant I've built is just one example of how this technology can be used practically. It's a cool journey worth embarking upon. 🚀

I hope you found this article informative, providing a practical example of how this technology can be applied. If you have any questions or wish to explore this project further, please don't hesitate to reach out. Happy building!

Use AI to create great product descriptions with this free plugin

Victor Gerbrands — Fri, 06 Oct 2023 11:48:07 +0000

If you've ever dabbled in ecommerce, you probably know: writing great product descriptions can be tough.

I've created a Medusa Admin widget that lets you write and improve product descriptions with AI. This can save you a lot of time when adding new products or optimizing your current descriptions.

You can use this in various ways to make your ecomm life easier. Think content creation, automated workflows, recommendations, etc.

In this article I'll explain how to set up the plugin and how to extend it with your own prompts and buttons.

Medusa: open-source building blocks for commerce

Quick background on Medusa: we create open-source building blocks needed to build amazing ecommerce websites or enable commerce functionality in any product.

Prerequisites

This plugin requires an OpenAI API key and platform account. Go to https://platform.openai.com/account/api-keys to set this up.
You need a Medusa server with the Admin installed. The fastest way to set this up is by using create-medusa-app.

Getting Started

Note: if you want to use the hosted plugin as is, follow these steps. If you want to customize the prompts, skip to "Add your own prompts" below.

Install the package with yarn add medusa-product-ai-widget or npm i medusa-product-ai-widget.
In medusa-config.js, add the plugin to the plugins array with the following options:

const plugins = [
  // ... other plugins
  {
    resolve: `medusa-product-ai-widget`,
    options: {
      api_key: process.env.OPENAI_API_KEY,
      enableUI: true
    }
  }
]

In your .env file, add an OPENAI_API_KEY environment variable containing your API key:

OPENAI_API_KEY=<YOUR OPENAI API KEY>

Start your dev server and log into the admin. Open any product that has a product description and the widget will appear on the bottom of the page!

Add your own prompts

If you want to customize the plugin and add in your own prompts, it's better to grab the plugins source code and add it directly to your Medusa server.

To do so, head over to the plugin repo and grab the contents of /src/. Copy the contents of the folders to the corresponding folders in your Medusa server project. If you have other custom admin routes set-up, make sure you don't overwrite them in /src/api/routes/admin/index.ts and other index files.

To add in your own prompts, there's 3 files to edit:

1. src/types/product-ai-tools.ts
Add the name of your prompts to the PromptTypes type definition. Names can be anything, but I recommend to make them short and easily distinguishable.

export type PromptTypes =
  | "fix_writing"
  | "make_longer"
  | "make_shorter"
  | "improve_seo"
  | "your_custom_prompt"
  | "another_custom_prompt";

2. src/api/routes/admin/completion/product-descriptions.ts
Now add your newly created prompt name to the PROMPTS object. The key will be the actual prompt that is being sent to ChatGPT.

const PROMPTS: Prompts = {
  // ... other prompts
  your_custom_prompt: "Write a custom prompt that describes to ChatGPT what to do!",
  another_custom_prompt: "Write a another custom prompt that describes to ChatGPT what to do. Be specific!"
};

The key to high quality responses is to be specific. Look at the existing prompts for inspiration.

3. src/admin/widgets/product-ai-tools/product-ai-tools.tsx
As a final step, add a new button to the widget that will trigger your new prompt. Do this by adding your newly created prompt name to the prompts object. The key will be the text that's displayed on the button.

const prompts: Prompts = {
  fix_writing: "Fix writing",
  make_longer: "Make longer",
  make_shorter: "Make shorter",
  improve_seo: "Optimize for SEO",
  your_custom_prompt: "Custom button text",
  another_custom_prompt: "Another button text",
};

That's it! Now run medusa develop, log into the admin, browse to a product with description and try out your new prompts!

Liked this post? Show some love on the tweet below!

// Detect dark theme var iframe = document.getElementById('tweet-1709868185850126376-923'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1709868185850126376&theme=dark" }

Building a store for digital products with Next.js and Medusa

Victor Gerbrands — Tue, 26 Sep 2023 16:50:20 +0000

TL;DR

In this tutorial, you’ll learn how to build a store that sells digital products (like e-books) using Next.js and Medusa.

We’ll use the Medusa Next.js Starter Template and Digital Products Recipe to get up and running.
We’ll update the product pages to support digital products
- Add a media preview button
- Display relevant product information
We’ll simplify the checkout to match the digital products delivery process.
We’ll create Next.js API routes to validate product downloads and hide file paths.

Medusa: open-source building blocks for commerce

Quick background on Medusa: we create open-source building blocks needed to build amazing ecommerce websites or enable commerce functionality in any product.

Get started

Create a new Medusa app with the Next.js starter by running:



npx create-medusa-app@latest --with-nextjs-starter

Create a user and make sure you can log in to the admin.
Prepare the backend by following our Digital Products Recipe.
Create one or two example products in your Medusa admin. Make sure they have digital media files (both preview and main files) attached to them. Also add in some product metadata values. You can choose any key/value pairs that might be relevant to you product.

Add in type definitions

ℹ️ If you’re using regular JavaScript, you can skip this
step.

Before going any further, let’s add the required Typescript type definitions for our digital products to our Next.js storefront project.

Code example



// src/types/product-media.ts

import { Product } from "@medusajs/medusa"
import { ProductVariant } from "@medusajs/product"

export enum ProductMediaVariantType {
  PREVIEW = "preview",
  MAIN = "main",
}

export type ProductMedia = {
  id: string
  name?: string
  file?: string
  mime_type?: string
  created_at?: Date
  updated_at?: Date
  attachment_type?: ProductMediaVariantType
  variant_id?: string
  variants?: ProductMediaVariant[]
}

export type ProductMediaVariant = {
  id: string
  variant_id: string
  product_media_id: string
  type: string
  created_at: Date
  updated_at: Date
}

export type DigitalProduct = Omit<Product, "variants"> & {
  product_medias?: ProductMedia[]
  variants?: DigitalProductVariant[]
}

export type DigitalProductVariant = ProductVariant & {
  product_medias?: ProductMedia
}

Add a digital media preview to the product response

We’re gonna add previews of our e-books to the product detail page. To enable this, we need to fetch the product media preview that belong to the product variant that is currently being viewed. In src/lib/data/index.ts, we will add a function to get product media previews by variant.

Code example



// src/lib/data/index.ts

// ... other imports
import { DigitalProduct, ProductMedia } from "types/product-media"

// ... rest of the functions

export async function getProductMediaPreviewByVariant(
  variant: Variant
): Promise<ProductMedia> {
  const { product_medias } = await medusaRequest("GET", `/product-media`, {
    query: {
      variant_ids: variant.id,
      expand: ["variants"],
    },
  })
    .then((res) => res.body)
    .catch((err) => {
      throw err
    })

  return product_medias[0]
}

Add a preview download button

To give customers an idea of what the e-book is about, we’re giving away a preview PDF that contains the first few pages. First, we’re gonna create a Next API Route that handles the file downloads without showing the actual file location to the user. After that, we will create a “download free preview” button component that will call the new API Route. If a product variant has preview media available, we will render it inside the product-actions component.

ℹ️ You can use the newly created DigitalProduct and
DigitalProductVariant types to fix any TypeScript errors > that you may encounter.

Code example: preview download API route



// src/app/api/download/preview/route.ts

import { NextRequest, NextResponse } from "next/server"

export async function GET(req: NextRequest) {
  // Get the file info from the URL
  const { filepath, filename } = Object.fromEntries(req.nextUrl.searchParams)

  // Fetch the PDF file
  const pdfResponse = await fetch(filepath)

  // Handle the case where the PDF could not be fetched
  if (!pdfResponse.ok) return new NextResponse("PDF not found", { status: 404 })

  // Get the PDF content as a buffer
  const pdfBuffer = await pdfResponse.arrayBuffer()

  // Define response headers
  const headers = {
    "Content-Type": "application/pdf",
    "Content-Disposition": `attachment; filename="${filename}"`, // This sets the file name for the download
  }

  // Create a NextResponse with the PDF content and headers
  const response = new NextResponse(pdfBuffer, {
    status: 200,
    headers,
  })

  return response
}

Code example: download button component



// src/modules/products/components/product-media-preview/index.tsx

import Button from "@modules/common/components/button"
import { ProductMedia } from "types/product-media"

type Props = {
  media: ProductMedia
}

const ProductMediaPreview: React.FC<Props> = ({ media }) => {
  const downloadPreview = () => {
    window.location.href = `${process.env.NEXT_PUBLIC_BASE_URL}/api/download/preview?filepath=${media.file}&filename=${media.name}`
  }

  return (
    <div>
      <Button variant="secondary" onClick={downloadPreview}>
        Download free preview
      </Button>
    </div>
  )
}

export default ProductMediaPreview

Code example: render button in product-actions



// src/modules/products/components/product-actions/index.tsx

// ...other imports
import ProductMediaPreview from "../product-media-preview"
import { getProductMediaPreviewByVariant } from "@lib/data"

const ProductActions: React.FC<ProductActionsProps> = ({ product }) => {
    // ...other code

  const [productMedia, setProductMedia] = useState({} as ProductMedia)

  useEffect(() => {
    const getProductMedia = async () => {
      if (!variant) return
      await getProductMediaPreviewByVariant(variant).then((res) => {
        setProductMedia(res)
      })
    }
    getProductMedia()
  }, [variant])

  return (
            // ...other code

      {productMedia && <ProductMediaPreview media={productMedia} />}

      <Button onClick={addToCart}>
        {!inStock ? "Out of stock" : "Add to cart"}
      </Button>
    </div>
  )
}

export default ProductActions

Update product and shipping information

As the product and shipping information for digital product differs from physical products, we’re gonna update these sections on the product page.

Product information

I’ve added relevant product attributes to the e-book using the product’s metadata section in the Medusa admin. As we don’t want to use the standard attributes, we’re gonna refactor the ProductInfoTab component to display any metadata we add.

In the default response, metadata is structured as an object. We’re gonna map it to an array so we can easily loop through the key/value pairs to build our attribute list. In this example we’ll display 4 attributes from metadata, 2 in each column. Edit the values in the slice() if you want to display more or less attributes.

Code example



// src/modules/products/components/product-tabs/index.tsx

// ... other components 

const ProductInfoTab = ({ product }: ProductTabsProps) => {
  // map the metadata object to an array 
  const metadata = useMemo(() => {
    if (!product.metadata) return []
    return Object.keys(product.metadata).map((key) => {
      return [key, product.metadata?.[key]]
    })
  }, [product])

  return (
    <Tab.Panel className="text-small-regular py-8">
      <div className="grid grid-cols-2 gap-x-8">
        <div className="flex flex-col gap-y-4">
                {/* Map the metadata as product information */}
          {metadata &&
            metadata.slice(0, 2).map(([key, value], i) => (
              <div key={i}>
                <span className="font-semibold">{key}</span>
                <p>{value}</p>
              </div>
            ))}
        </div>
        <div className="flex flex-col gap-y-4">
          {metadata.length > 2 &&
            metadata.slice(2, 4).map(([key, value], i) => {
              return (
                <div key={i}>
                  <span className="font-semibold">{key}</span>
                  <p>{value}</p>
                </div>
              )
            })}
        </div>
      </div>
      {product.tags?.length ? (
        <div>
          <span className="font-semibold">Tags</span>
        </div>
      ) : null}
    </Tab.Panel>
  )
}

// ... other components

Shipping information

As the shipping information is not relevant for digital products, we’re gonna change the contents of the tab. This is handled in the ShippingInfoTab component within the same file. You can write anything that’s relevant for your store here.

Code example



// src/modules/products/components/product-tabs/index.tsx

// ... other components 

const ProductTabs = ({ product }: ProductTabsProps) => {
  const tabs = useMemo(() => {
    return [
      {
        label: "Product Information",
        component: <ProductInfoTab product={product} />,
      },
      {
        label: "E-book delivery",
        component: <ShippingInfoTab />,
      },
    ]
  }, [product])
    // ... rest of code
}

// ... other components 

const ShippingInfoTab = () => {
  return (
    <Tab.Panel className="text-small-regular py-8">
      <div className="grid grid-cols-1 gap-y-8">
        <div className="flex items-start gap-x-2">
          <FastDelivery />
          <div>
            <span className="font-semibold">Instant delivery</span>
            <p className="max-w-sm">
              Your e-book will be delivered instantly via email. You can also
              download it from your account anytime.
            </p>
          </div>
        </div>
        <div className="flex items-start gap-x-2">
          <Refresh />
          <div>
            <span className="font-semibold">Free previews</span>
            <p className="max-w-sm">
              Get a free preview of the e-book before you buy it. Just click the
              button above to download it.
            </p>
          </div>
        </div>
      </div>
    </Tab.Panel>
  )
}

// ... other components

Update checkout

Since we sell digital products, we don’t need the physical address of our customers. A name and email will suffice for delivering the e-book. This means we can simplify the checkout process by removing unnecessary input fields. In this example we’ll just keep first name, last name, country and email. We’ll completely get rid of the billing address. Note that your use case may require different input fields.

First, we’ll update the checkout types and context by removing any references to values we no longer need.

Code example - You can copy/paste this into src/lib/context/checkout-context.tsx



// src/lib/context/checkout-context.tsx

"use client"

import { medusaClient } from "@lib/config"
import useToggleState, { StateType } from "@lib/hooks/use-toggle-state"
import { Cart, Customer, StorePostCartsCartReq } from "@medusajs/medusa"
import Wrapper from "@modules/checkout/components/payment-wrapper"
import { isEqual } from "lodash"
import {
  formatAmount,
  useCart,
  useCartShippingOptions,
  useMeCustomer,
  useRegions,
  useSetPaymentSession,
  useUpdateCart,
} from "medusa-react"
import { useRouter } from "next/navigation"
import React, { createContext, useContext, useEffect, useMemo } from "react"
import { FormProvider, useForm, useFormContext } from "react-hook-form"
import { useStore } from "./store-context"

type AddressValues = {
  first_name: string
  last_name: string
  country_code: string
}

export type CheckoutFormValues = {
  shipping_address: AddressValues
  billing_address?: AddressValues
  email: string
}

interface CheckoutContext {
  cart?: Omit<Cart, "refundable_amount" | "refunded_total">
  shippingMethods: { label?: string; value?: string; price: string }[]
  isLoading: boolean
  readyToComplete: boolean
  sameAsBilling: StateType
  editAddresses: StateType
  initPayment: () => Promise<void>
  setAddresses: (addresses: CheckoutFormValues) => void
  setSavedAddress: (address: AddressValues) => void
  setShippingOption: (soId: string) => void
  setPaymentSession: (providerId: string) => void
  onPaymentCompleted: () => void
}

const CheckoutContext = createContext<CheckoutContext | null>(null)

interface CheckoutProviderProps {
  children?: React.ReactNode
}

const IDEMPOTENCY_KEY = "create_payment_session_key"

export const CheckoutProvider = ({ children }: CheckoutProviderProps) => {
  const {
    cart,
    setCart,
    addShippingMethod: {
      mutate: setShippingMethod,
      isLoading: addingShippingMethod,
    },
    completeCheckout: { mutate: complete, isLoading: completingCheckout },
  } = useCart()

  const { customer } = useMeCustomer()
  const { countryCode } = useStore()

  const methods = useForm<CheckoutFormValues>({
    defaultValues: mapFormValues(customer, cart, countryCode),
    reValidateMode: "onChange",
  })

  const {
    mutate: setPaymentSessionMutation,
    isLoading: settingPaymentSession,
  } = useSetPaymentSession(cart?.id!)

  const { mutate: updateCart, isLoading: updatingCart } = useUpdateCart(
    cart?.id!
  )

  const { shipping_options } = useCartShippingOptions(cart?.id!, {
    enabled: !!cart?.id,
  })

  const { regions } = useRegions()

  const { resetCart, setRegion } = useStore()
  const { push } = useRouter()

  const editAddresses = useToggleState()
  const sameAsBilling = useToggleState(
    cart?.billing_address && cart?.shipping_address
      ? isEqual(cart.billing_address, cart.shipping_address)
      : true
  )

  /**
   * Boolean that indicates if a part of the checkout is loading.
   */
  const isLoading = useMemo(() => {
    return (
      addingShippingMethod ||
      settingPaymentSession ||
      updatingCart ||
      completingCheckout
    )
  }, [
    addingShippingMethod,
    completingCheckout,
    settingPaymentSession,
    updatingCart,
  ])

  /**
   * Boolean that indicates if the checkout is ready to be completed. A checkout is ready to be completed if
   * the user has supplied a email, shipping address, billing address, shipping method, and a method of payment.
   */
  const readyToComplete = useMemo(() => {
    return (
      !!cart &&
      !!cart.email &&
      !!cart.shipping_address &&
      !!cart.billing_address &&
      !!cart.payment_session &&
      cart.shipping_methods?.length > 0
    )
  }, [cart])

  const shippingMethods = useMemo(() => {
    if (shipping_options && cart?.region) {
      return shipping_options?.map((option) => ({
        value: option.id,
        label: option.name,
        price: formatAmount({
          amount: option.amount || 0,
          region: cart.region,
        }),
      }))
    }

    return []
  }, [shipping_options, cart])

  /**
   * Resets the form when the cart changed.
   */
  useEffect(() => {
    if (cart?.id) {
      methods.reset(mapFormValues(customer, cart, countryCode))
    }
  }, [customer, cart, methods, countryCode])

  useEffect(() => {
    if (!cart) {
      editAddresses.open()
      return
    }

    if (cart?.shipping_address && cart?.billing_address) {
      editAddresses.close()
      return
    }

    editAddresses.open()
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [cart])

  /**
   * Method to set the selected shipping method for the cart. This is called when the user selects a shipping method, such as UPS, FedEx, etc.
   */
  const setShippingOption = (soId: string) => {
    if (cart) {
      setShippingMethod(
        { option_id: soId },
        {
          onSuccess: ({ cart }) => setCart(cart),
        }
      )
    }
  }

  /**
   * Method to create the payment sessions available for the cart. Uses a idempotency key to prevent duplicate requests.
   */
  const createPaymentSession = async (cartId: string) => {
    return medusaClient.carts
      .createPaymentSessions(cartId, {
        "Idempotency-Key": IDEMPOTENCY_KEY,
      })
      .then(({ cart }) => cart)
      .catch(() => null)
  }

  /**
   * Method that calls the createPaymentSession method and updates the cart with the payment session.
   */
  const initPayment = async () => {
    if (cart?.id && !cart.payment_sessions?.length && cart?.items?.length) {
      const paymentSession = await createPaymentSession(cart.id)

      if (!paymentSession) {
        setTimeout(initPayment, 500)
      } else {
        setCart(paymentSession)
        return
      }
    }
  }

  /**
   * Method to set the selected payment session for the cart. This is called when the user selects a payment provider, such as Stripe, PayPal, etc.
   */
  const setPaymentSession = (providerId: string) => {
    if (cart) {
      setPaymentSessionMutation(
        {
          provider_id: providerId,
        },
        {
          onSuccess: ({ cart }) => {
            setCart(cart)
          },
        }
      )
    }
  }

  const prepareFinalSteps = () => {
    initPayment()

    if (shippingMethods?.length && shippingMethods?.[0]?.value) {
      setShippingOption(shippingMethods[0].value)
    }
  }

  const setSavedAddress = (address: AddressValues) => {
    const setValue = methods.setValue

    setValue("shipping_address", {
      country_code: address.country_code || "",
      first_name: address.first_name || "",
      last_name: address.last_name || "",
    })
  }

  /**
   * Method that validates if the cart's region matches the shipping address's region. If not, it will update the cart region.
   */
  const validateRegion = (countryCode: string) => {
    if (regions && cart) {
      const region = regions.find((r) =>
        r.countries.map((c) => c.iso_2).includes(countryCode)
      )

      if (region && region.id !== cart.region.id) {
        setRegion(region.id, countryCode)
      }
    }
  }

  /**
   * Method that sets the addresses and email on the cart.
   */
  const setAddresses = (data: CheckoutFormValues) => {
    const { shipping_address, billing_address, email } = data

    const payload: StorePostCartsCartReq = {
      shipping_address,
      email,
    }

    if (isEqual(shipping_address, billing_address)) {
      sameAsBilling.open()
    }

    if (sameAsBilling.state) {
      payload.billing_address = shipping_address
    } else {
      payload.billing_address = billing_address
    }

    updateCart(payload, {
      onSuccess: ({ cart }) => {
        setCart(cart)
        prepareFinalSteps()
      },
    })
  }

  /**
   * Method to complete the checkout process. This is called when the user clicks the "Complete Checkout" button.
   */
  const onPaymentCompleted = () => {
    complete(undefined, {
      onSuccess: ({ data }) => {
        resetCart()
        push(`/order/confirmed/${data.id}`)
      },
    })
  }

  return (
    <FormProvider {...methods}>
      <CheckoutContext.Provider
        value={{
          cart,
          shippingMethods,
          isLoading,
          readyToComplete,
          sameAsBilling,
          editAddresses,
          initPayment,
          setAddresses,
          setSavedAddress,
          setShippingOption,
          setPaymentSession,
          onPaymentCompleted,
        }}
      >
        <Wrapper paymentSession={cart?.payment_session}>{children}</Wrapper>
      </CheckoutContext.Provider>
    </FormProvider>
  )
}

export const useCheckout = () => {
  const context = useContext(CheckoutContext)
  const form = useFormContext<CheckoutFormValues>()
  if (context === null) {
    throw new Error(
      "useProductActionContext must be used within a ProductActionProvider"
    )
  }
  return { ...context, ...form }
}

/**
 * Method to map the fields of a potential customer and the cart to the checkout form values. Information is assigned with the following priority:
 * 1. Cart information
 * 2. Customer information
 * 3. Default values - null
 */
const mapFormValues = (
  customer?: Omit<Customer, "password_hash">,
  cart?: Omit<Cart, "refundable_amount" | "refunded_total">,
  currentCountry?: string
): CheckoutFormValues => {
  const customerShippingAddress = customer?.shipping_addresses?.[0]
  const customerBillingAddress = customer?.billing_address

  return {
    shipping_address: {
      first_name:
        cart?.shipping_address?.first_name ||
        customerShippingAddress?.first_name ||
        "",
      last_name:
        cart?.shipping_address?.last_name ||
        customerShippingAddress?.last_name ||
        "",
      country_code:
        currentCountry ||
        cart?.shipping_address?.country_code ||
        customerShippingAddress?.country_code ||
        "",
    },
    billing_address: {
      first_name:
        cart?.billing_address?.first_name ||
        customerBillingAddress?.first_name ||
        "",
      last_name:
        cart?.billing_address?.last_name ||
        customerBillingAddress?.last_name ||
        "",
      country_code:
        cart?.shipping_address?.country_code ||
        customerBillingAddress?.country_code ||
        "",
    },
    email: cart?.email || customer?.email || "",
  }
}

Now that the context is updated, we’ll remove the redundant input fields from the checkout form.

Code example



// src/modules/checkout/components/addresses/index.tsx

import { useCheckout } from "@lib/context/checkout-context"
import Button from "@modules/common/components/button"
import Spinner from "@modules/common/icons/spinner"
import ShippingAddress from "../shipping-address"

const Addresses = () => {
  const {
    editAddresses: { state: isEdit, toggle: setEdit },
    setAddresses,
    handleSubmit,
    cart,
  } = useCheckout()
  return (
    <div className="bg-white">
      <div className="text-xl-semi flex items-center gap-x-4 px-8 pb-6 pt-8">
        <div className="bg-gray-900 w-8 h-8 rounded-full text-white flex justify-center items-center text-sm">
          1
        </div>
        <h2>Shipping address</h2>
      </div>
      {isEdit ? (
        <div className="px-8 pb-8">
          <ShippingAddress />
          <Button
            className="max-w-[200px] mt-6"
            onClick={handleSubmit(setAddresses)}
          >
            Continue to delivery
          </Button>
        </div>
      ) : (
        <div>
          <div className="bg-gray-50 px-8 py-6 text-small-regular">
            {cart && cart.shipping_address ? (
              <div className="flex items-start gap-x-8">
                <div className="bg-green-400 rounded-full min-w-[24px] h-6 flex items-center justify-center text-white text-small-regular">
                  ✓
                </div>
                <div className="flex items-start justify-between w-full">
                  <div className="flex flex-col">
                    <span>
                      {cart.shipping_address.first_name}{" "}
                      {cart.shipping_address.last_name}
                      {cart.shipping_address.country}
                    </span>
                    <div className="mt-4 flex flex-col">
                      <span>{cart.email}</span>
                    </div>
                  </div>
                  <div>
                    <button onClick={setEdit}>Edit</button>
                  </div>
                </div>
              </div>
            ) : (
              <div className="">
                <Spinner />
              </div>
            )}
          </div>
        </div>
      )}
    </div>
  )
}

export default Addresses

And finally, we’ll update the shipping-details component to show relevant values on order completion. In the example all redundant values are removed, and the email address of the buyer is added in.

Code example



// src/modules/order/components/shipping-details/index.tsx

import { Address, ShippingMethod } from "@medusajs/medusa"

type ShippingDetailsProps = {
  address: Address
  shippingMethods: ShippingMethod[]
  email: string
}

const ShippingDetails = ({
  address,
  shippingMethods,
  email,
}: ShippingDetailsProps) => {
  return (
    <div className="text-base-regular">
      <h2 className="text-base-semi">Delivery</h2>
      <div className="my-2">
        <h3 className="text-small-regular text-gray-700">Details</h3>
        <div className="flex flex-col">
          <span>{`${address.first_name} ${address.last_name}`}</span>
          <span>{email}</span>
        </div>
      </div>
      <div className="my-2">
        <h3 className="text-small-regular text-gray-700">Delivery method</h3>
        <div>
          {shippingMethods.map((sm) => {
            return <div key={sm.id}>{sm.shipping_option.name}</div>
          })}
        </div>
      </div>
    </div>
  )
}

export default ShippingDetails

Digital product delivery

There’s multiple ways to deliver digital products to a customer. We can deliver a download link via email, add a download button to the order confirmation page or give access to purchased items in the user account.

In all cases, we want to validate if the user that tries to access the product has actually purchased it. To do this, I’ve set up the backend to generate a unique token for every digital line item in an order. We can GET /store/:token to validate the token and return the associated file to the user. However, this will reveal the file url to the user, and we don’t want that for piracy reasons. We’re gonna set up a Next API route in src/app/api/download/main/[token]/route.ts to pass the token and proxy the file to the user, so they’ll get a direct download without seeing the exact file location.

Code example



// src/app/api/download/main/[token]/route.ts

import { NextRequest, NextResponse } from "next/server"

export async function GET(
  req: NextRequest,
  { params }: { params: Record<string, any> }
) {
  // Get the token from the URL
  const { token } = params

  // Define the URL to fetch the PDF file data from
  const pdfUrl = `${process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL}/store/product-media/${token}`

  // Fetch the PDF file data
  const { file, filename } = await fetch(pdfUrl).then((res) => res.json())

  // Handle the case where the token is invalid
  if (!file) return new NextResponse("Invalid token", { status: 401 })

  // Fetch the PDF file
  const pdfResponse = await fetch(file)

  // Handle the case where the PDF could not be fetched
  if (!pdfResponse.ok) return new NextResponse("PDF not found", { status: 404 })

  // Get the PDF content as a buffer
  const pdfBuffer = await pdfResponse.arrayBuffer()

  // Define response headers
  const headers = {
    "Content-Type": "application/pdf",
    "Content-Disposition": `attachment; filename="${filename}"`, // This sets the file name for the download
  }

  // Create a NextResponse with the PDF content and headers
  const response = new NextResponse(pdfBuffer, {
    status: 200,
    headers,
  })

  return response
}

We can now link to this API route from the delivery email like: {your_store_url}/api/download/main/{token}.

You can add your own logic to invalidate tokens after a certain time or X number of downloads.

Done!

You've made it to the end! If you have any questions or comments about this guide, let me know.

Check out our other Recipes for more Medusa use cases.

Serverless ecommerce with Next.js: Removing the server layer

Victor Gerbrands — Wed, 20 Sep 2023 15:01:01 +0000

When it comes to building ecommerce platforms, managing a dedicated server can be challenging, especially for those who choose to self-host. However, with the power of Next.js and serverless architecture, these challenges can be overcome.

Simplifying Headless Ecommerce

Traditionally, setting up an ecommerce platform in a headless architecture would involve managing a dedicated server. This approach brings along challenges like scalability, maintenance, and security.

But with serverless modules, these challenges can be overcome. By leveraging serverless functions, developers can achieve a more scalable and low-maintenance solution for their ecommerce needs.

Modules can work together or separately. E.g. our new Pricing Module is an obvious companion to our Product Module, but it's just as straightforward to incorporate a PIM to handle your product data.

Next.js and Serverless Ecommerce: A better DevEx

Using Medusa's serverless modules, backend logic can be seamlessly integrated within your Next.js project. This approach greatly enhances the developer experience by providing a unified development environment. You won't be switching between two projects when you need to modify an API response.

Going serverless also means that resources are scaled automatically as traffic increases. This means the server won't be overloaded in the case of an unexpected traffic peak, but you also won't be paying for resources you don't need in times of lower traffic.

When building with Next.js, deploying serverless functions to platforms like Vercel is straightforward. However, this approach is not limited to Vercel alone; it can be deployed on AWS, GCP, or any other serverless environment that supports Node.

Crafting Customized Responses

One key benefit of using serverless modules is the level of customizability you get, without the need to dive deep into the backend. This allows developers to tailor the response to contain only the data required for their frontend components.

If your product page requires an image, title, handle and price, you can easily query that data - and nothing else.

By doing so, unnecessary data transfer is eliminated, resulting in optimized performance.

The Future of Modular Commerce

As Medusa continues to release more modules, the possibilities for building scalable commerce setups expand.

The long-term vision is to transform the world of digital commerce with our modular approach. These modules will make it easier for developers to create highly customizable commerce applications, allowing them to work independently or together seamlessly.

The aim is to simplify and enhance communication between different parts of a commerce system, making it more efficient and adaptable. The goal is to empower businesses to build flexible and scalable commerce solutions that can evolve with their needs.

Stay tuned as we dive deeper into each of these subjects in future posts. We'll explore the technical details, best practices, and real-world implementation examples.

For now, check out the examples provided in our Next.js Starter repository here to get started with the Medusa Pricing Module.

Medusa Next.js Starter now has Product Module support

Victor Gerbrands — Mon, 04 Sep 2023 16:21:43 +0000

I've just updated the Medusa Next.js Starter Template with full support for the serverless Product Module.

Introducing the Product Module

With the Product Module, you can customize product logic quickly and easily from within your Next.js project, keeping backend logic close to the frontend. It runs in a Vercel Serverless Function, meaning it doesn't require a traditional server to interact with your product database. It comes with functional examples, making it a great entry point for those new to the concept of serverless functions. And if you ever want to opt in or out of using the module, all it takes is a simple feature toggle.

About Medusa's modules

Medusa's modules are essential building blocks for ecommerce applications, designed to increase extensibility and customization capabilities. The Product Module is the first serverless Medusa module, and we will continue to release all parts of our SDK as a serverless module over the coming period. The Starter Template is an example of how to use the Product Module in a Next.js application, but it runs in basically every serverless environment.

Benefits of serverless modules

But what are the benefits of using serverless modules like the Product Module? For one, it keeps packages small enough for easy deployment to serverless infrastructure. Plus, it makes it easier to integrate modules into an existing ecosystem of commerce services, without the need for a dedicated ecommerce server. And of course, it makes it easier to customize or extend core logic in Medusa.

About the Next.js Starter Template for Medusa

With the Next.js Starter Template for Medusa, you can effortlessly build fast ecommerce sites. Medusa handles essential ecommerce logic like carts, products, orders, and more, all of which are easily customizable to suit your unique use case. And with complete support for Next.js 13, including App Router, you're assured of all the latest Next features and benefits.

Integrations for PayPal, Stripe, Algolia, and Meilisearch are built-in, ensuring a quick setup process. In short, the Medusa Next.js Starter Template with Product Module support is the perfect solution for developers looking to build high-performing ecommerce stores with ease.

Get Started With the Next.js Starter Template for Medusa

Announcing Next.js Starter with App Router support

Victor Gerbrands — Thu, 13 Jul 2023 10:32:55 +0000

Unique commerce experiences begin at the frontend. We are therefore excited to announce our newly updated Next.js Starter Template with App Router support as an easy way for developers to get started building performant storefronts for Medusa.

The template combines Next.js 13, Tailwind, and Typescript for a modern stack and comes with key e-commerce features out-of-the-box. The template and Medusa’s commerce building blocks ensure developers can focus on building customer-facing features that create value instead of rewriting table-stakes logic.

Visit the hosted demo of the template. Or, learn how to set it up in our Docs.

About Medusa

Medusa is an SDK for commerce consisting of Node.js packages with core logic for carts, discounts, products, order management, and more. In combination, the packages provide a digital commerce API with default behavior similar to other platforms’ APIs. But, unlike other platforms, Medusa is easily extended and customized to create rich and differentiated customer experiences when needed.

Next.js 13 Support

The Medusa Next.js Starter Template has been fully updated to support Next.js 13 and App Router, which unlocks easy dynamic routing based on your data and improved SSR with React Server Components. Additionally, Next.js 13 introduces new features and improvements for font loading, serverless support, and efficient image optimization, making it a great foundation for performant e-commerce storefronts.

Template Features

Out of the box, our Next.js Starter Template comes with the following features:

Product Detail Pages

The Starter Template includes informative and visually appealing product detail pages. Display product descriptions, images, pricing, and other essential information.

Product Overview Page

Guide your customers through your product range with intuitive product overview pages. Our Starter Template enables you to showcase your products in an organized manner with collection filters automatically generated.

Product Search Integrations

The Medusa Next.js Starter Template supports popular instant-search providers Melliseach and Algolia out of the box. With these integrations, you can provide fast and accurate search results.

Product Collections

Create product collections to highlight specific themes, seasons, or promotions. With our Starter Template, collection pages are dynamically created, filterable, and added to the theme footer.

Cart

Our Starter Template provides robust cart functionality, allowing customers to conveniently add products, view their cart contents, and modify quantities. The cart is stored in the database and persistent over multiple user sessions.

Checkout with Payment Integrations

Ensure a secure and seamless checkout process with integrated payment gateways. The Medusa Next.js Starter Template seamlessly works with popular payment providers PayPal and Stripe, out of the box. Enable your customers to complete their purchases smoothly, using familiar payment methods.

User Accounts

Foster personalized experiences and customer loyalty by implementing user account functionality. With our Starter Template, customers can create accounts, manage their profiles, and access their order history.

Order Details

Keep your customers informed and satisfied with real-time order updates. The Medusa Next.js Starter Template enables you to provide order status, shipping information, and tracking details, ensuring transparency throughout the entire purchase journey.

More Medusa and Next.js

Clone the Medusa Next.js Starter Template from GitHub

Or check out our other Next-focused product launches, like our Product Module that allows you to access Products, Variants, Categories, and more through a standalone package that can be installed and run in Next.js functions. Read more about it in our latest announcement post, or check out how we used it to create a personalized storefront experience in our demo.

Building real-time personalization with Next.js and Medusa

Victor Gerbrands — Thu, 15 Jun 2023 13:02:44 +0000

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:

// Detect dark theme var iframe = document.getElementById('tweet-1671181706970255361-399'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1671181706970255361&theme=dark" }

DEV Community: Victor Gerbrands

What we've learned from the transition to Next.js 14 with Server Components

The challenge

Data fetching and state

Fetching and caching

Data mutations with Server Actions

Implementing “add to cart” - before and after

Server vs Client components

Static pre-rendering

Moving state to the URL

Using search params

Conclusion

Building an AI assistant for ecommerce with Medusa, Vercel AI SDK, and OpenAI

The tech stack

Exploring Function Calling

Medusa's role in empowering AI assistants

The power of natural language

Use AI to create great product descriptions with this free plugin

Medusa: open-source building blocks for commerce

Prerequisites

Getting Started

Add your own prompts

Building a store for digital products with Next.js and Medusa

TL;DR

Medusa: open-source building blocks for commerce

Get started

Add in type definitions

Add a digital media preview to the product response

Add a preview download button

Update product and shipping information

Product information

Shipping information

Update checkout

Digital product delivery

Done!

Serverless ecommerce with Next.js: Removing the server layer

Simplifying Headless Ecommerce

Next.js and Serverless Ecommerce: A better DevEx

Crafting Customized Responses

The Future of Modular Commerce

Medusa Next.js Starter now has Product Module support

Introducing the Product Module

About Medusa's modules

Benefits of serverless modules

About the Next.js Starter Template for Medusa

Announcing Next.js Starter with App Router support

About Medusa

Next.js 13 Support

Template Features

Product Detail Pages

Product Overview Page

Product Search Integrations

Product Collections

Cart

Checkout with Payment Integrations

User Accounts

Order Details

More Medusa and Next.js

Building real-time personalization with Next.js and Medusa

What is this article about?

What will you be building?

Medusa: open-source SDK for commerce

Get started: install the module

How to use the module

Start personalizing

Personalize on user location

Personalize on user behavior

Set a user id

Store user behavior in Vercel KV

Update /api/products/route.ts

Concluding

Update `/api/products/route.ts`