Custom Storefront with Next.js and Medusa.js: Build and Deploy Guide

Medusa.js is an open-source headless commerce platform built on Node.js and TypeScript. It handles all the backend commerce logic including products, carts, orders, payments, inventory, and taxes, and exposes everything through a clean REST API. Your storefront connects to this backend and fetches whatever data it needs.

Next.js is the frontend layer. It brings server-side rendering, static generation, the App Router, and a rich ecosystem of components and integrations. When combined with Medusa, you get a storefront that is fast, SEO-friendly, and fully customizable.

The pairing works well because both tools follow an API-first mindset. Medusa does not care how your frontend is built. You could use React, Vue, or a mobile app. But Next.js is the most popular choice because it handles SEO and performance in ways that a pure React single-page app cannot.

Before getting into setup, make sure your machine meets these requirements. You will need Node.js version 20 or higher installed, since Medusa will not run on older versions. You also need PostgreSQL running locally or accessible through a cloud service. Git should be installed for version control, and a basic understanding of React and REST APIs will help you move through the guide faster.

For deployment, you will need access to a cloud provider. This guide uses Vercel for the storefront and covers backend deployment to a VPS or cloud VM. If your team is already using AWS, refer to our previous guide in this series on deploying Medusa on AWS with production-ready architecture.

Start by creating a new Medusa project. The quickest way is using the create-medusa-app CLI command which scaffolds both the backend and, optionally, the Next.js storefront together.

Install and Scaffold the Project

Run the following command in your terminal to create a new project:

This command installs the Medusa application in a named project directory and the Next.js starter in a separate directory. The Medusa admin dashboard will open at localhost:9000/app once installation completes. The storefront runs at localhost:8000.

If you prefer to install the backend and frontend separately, you can clone the official Next.js starter from the Medusa GitHub repository and configure the backend URL through an environment variable.

Environment Configuration

In your Next.js storefront directory, create an .env.local file and set two required variables. MEDUSA_BACKEND_URL should point to your Medusa server, and NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY should contain the publishable API key generated in your Medusa admin settings under Publishable API Keys.

Every request from the storefront must pass this key in the request header. Without it, product and cart operations will be rejected.

The Next.js starter for Medusa is not just a template, it is a working storefront with components, routing, and API integration pre-built. You can use it as-is or treat it as a reference while building a fully custom storefront.

The storefront is structured around the App Router introduced in Next.js 13 and refined in Next.js 14 and 15. Each route maps to a page like product listing, product detail, cart, checkout, and account. These pages use React Server Components for data fetching, which improves performance and reduces client-side JavaScript.

Medusa exposes store APIs that the storefront calls to retrieve product catalogs, add items to a cart, apply discounts, and process payments. The starter includes a medusa client utility that wraps these API calls and keeps the code clean and reusable.

The real value of a custom Next.js storefront over a hosted SaaS solution is that you control every element. The header, the product cards, the checkout flow, the fonts, the color scheme, and the user experience are all yours to define.

Styling with TailwindCSS

The Medusa Next.js starter uses TailwindCSS for styling. You can modify the tailwind.config.js to update brand colors, typography, and spacing. For more significant redesigns, replace the component files inside the modules directory with your own implementations.

Tailwind works well here because it generates only the CSS classes that are actually used in your components, keeping the stylesheet small and fast. Combined with Next.js static generation, this gives you a storefront that scores well on Core Web Vitals.

Adding Custom Pages and Routes

Next.js App Router makes it straightforward to add pages beyond the standard ecommerce flow. If you need a landing page for a product launch, a brand story page, or a custom collection display, you create a new folder inside the app directory and add a page.tsx file.

These static pages can be combined with Medusa data. For example, a curated bundle page might fetch specific products from Medusa by their handles and display them in a custom layout that is not available in the standard product listing template.

Custom Checkout Experience

The checkout flow is often where custom storefronts justify the most effort. With a platform like Shopify, the checkout is largely fixed. With Medusa and Next.js, you can redesign every step of the process, add trust signals, offer express payment options, and handle region-specific flows.

Medusa supports Stripe as the default payment module. If you are building for the Indian market, the Razorpay integration covered in our earlier article in this series applies here as well. You add the payment session through the Medusa API and render the appropriate payment component in your checkout UI.

Medusa organizes functionality into modules. When you build a storefront, you are essentially consuming the output of these modules through the store API. Understanding what each module controls helps you build more intentional UI.

The product module gives you collections, variants, options, and metadata. When you build a product detail page, you pull from this module to render size selectors, color options, and availability. The pricing module determines what price a customer sees based on their region, currency, and any active promotions. If you are building a B2B storefront, this module also handles tiered pricing and account-level price lists.

The cart module manages the shopping session. Every interaction from adding a product to applying a discount code to updating quantities goes through cart API calls. Your storefront keeps the cart ID in a cookie and sends it with every relevant request.

Once your storefront is working locally and has been tested against a development instance of Medusa, the next step is production deployment. The storefront and backend are deployed independently, which gives you the flexibility to scale each layer based on its own traffic patterns.

Deploying the Storefront to Vercel

Vercel is the most straightforward deployment target for a Next.js application. Push your storefront code to a GitHub repository, connect the repository to Vercel, and set the environment variables. Vercel will detect the Next.js project automatically, build it, and deploy it to their global edge network.

In your Vercel project settings, add the following environment variables: set MEDUSA_BACKEND_URL to your deployed Medusa server URL, and set NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY to the publishable API key from your production Medusa instance.

Vercel also handles incremental static regeneration automatically. Product pages that are statically generated at build time can be revalidated on a schedule or on demand, meaning your storefront reflects catalog updates without requiring a full redeploy.

Deploying the Medusa Backend

The Medusa backend is a Node.js server with a PostgreSQL dependency. For production, you need a server with enough memory to handle concurrent requests and a managed PostgreSQL instance for reliability. Options include AWS RDS, Supabase, or Railway for the database, and a VPS, AWS EC2, or a container service for the Node.js process itself.

Point your deployed Medusa backend to your production PostgreSQL connection string, set a strong cookie secret, configure Redis for caching and sessions, and set the storefront URL in your CORS configuration to allow requests from your Next.js domain.

A production-ready Medusa storefront should pass through a structured test phase before going live. The most critical flows to test are the complete purchase journey from landing on a product page to order confirmation, cart behavior across page refreshes, payment processing with your actual payment credentials, and region and currency switching if your store serves multiple markets.

Next.js gives you the option to test server-rendered pages and static pages separately. Use browser developer tools to verify that the storefront makes the correct API calls, that responses contain accurate pricing, and that the publishable API key is passed in headers without being exposed in the page source.

For production testing patterns in headless commerce setups, the Medusa documentation covers testing recommendations for the Next.js starter storefront in detail. Teams at Askan Technologies follow a structured QA checklist before any storefront launch to ensure checkout, inventory sync, and payment flows work cleanly in production.

If your team needs support building or refining a Medusa storefront for the Indian market, explore our Medusa.js ecommerce development services where we walk through the custom builds we deliver for clients across verticals.

One underrated advantage of building with Next.js and Medusa is that both projects are actively maintained and follow semantic versioning. When Medusa releases a new version, the changes are documented and migration paths are provided. Your storefront upgrades are independent from your backend upgrades, which reduces the risk of a breaking change taking down the entire store.

Keep your component structure modular from the start. When product card designs need to change, a well-structured codebase lets you update the card component in one place and have the change reflected across every page that uses it. This kind of maintainability becomes critical as the store grows and more people contribute to the codebase.

Document your custom integrations and environment variable requirements. Medusa storefronts often involve multiple external services including payment gateways, search providers, and shipping APIs. A clear README with setup instructions keeps onboarding fast for new team members and reduces downtime when environment configurations need to change.