Menu

Next.js Starter Storefront

Note: Since Medusa v2.14.0, the Next.js Starter storefront is installed in a monorepo with the MedusaGo application when using create-medusago-app. The standalone Next.js Starter Storefront is now deprecated.

The MedusaGo application is made up of a Node.js server and an admin dashboard. The storefront is hosted separately from the MedusaGo application. You have the flexibility to choose the frontend tech stack that you and your team are proficient in, and implement unique design systems and user experience.

The Next.js Starter Storefront is a good place to start building your storefront. It provides rich commerce features and a sleek design. Developers and businesses can use it as-is or build on top of it to tailor it for the business's unique use case, design, and customer experience.

Note: This guide helps technical users set up the Next.js Start storefront. If you're not a technical user, refer your technical team to this documentation instead.

Installation#

Approach 1: Install with MedusaGo Application#

Node.js v22.22.0+ LTS, less than v25↗Git CLI tool↗PostgreSQL↗

If you don't have a MedusaGo application installed, run the following command to install both the MedusaGo application and the Next.js Starter storefront:

Terminal
go run github.com/hitkey-io/medusago/packages/cli/create-medusago-app@latest my-medusa-store --with-nextjs-starter

You'll be asked for the project's name, then the installation will start.

The command will create a {project-name} directory that holds a monorepository. The MedusaGo backend will be installed in the apps/backend directory, and the Next.js Starter storefront will be installed in the apps/storefront directory.

Once the installation is done, the Medusa Admin dashboard will open in your default browser at http://localhost:9000/app, and the Next.js Starter storefront will be running at http://localhost:8000.

For other information related to the MedusaGo application's installation, refer to the Installation guide.

Approach 2: Install separately#

Node.js v22.22.0+ LTS, less than v25↗Git CLI tool↗An existing Medusa monorepo with the backend running.At least one region in the MedusaGo application.

If you already have a Medusa monorepo installed and want to add the Next.js Starter storefront to it, follow these steps.

  1. From the root of your monorepo, clone the DTC Starter into a temporary directory to extract the storefront:
Terminal
git clone https://github.com/medusajs/dtc-starter.git --depth=1 dtc-temp
  1. Copy the storefront into your project's apps directory, then remove the temporary clone:
Terminal
cp -r dtc-temp/apps/storefront apps/storefront
rm -rf dtc-temp
  1. Make sure your workspace configuration includes the apps/storefront directory. If your pnpm-workspace.yaml or the workspaces field in package.json already uses a glob like apps/*, no change is needed. Otherwise, add it explicitly:
pnpm-workspace.yaml
packages:
  - 'apps/*'
  1. From the monorepo root, install the dependencies:
  1. Create the storefront's environment file from its template:
Terminal
cp apps/storefront/.env.template apps/storefront/.env.local
  1. In apps/storefront/.env.local, set the URL of your MedusaGo backend and your publishable API key. You can retrieve the publishable API key from the Medusa Admin dashboard by going to Settings > Publishable API Keys:
apps/storefront/.env.local
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_123...
  1. While the MedusaGo application is running, start the Next.js Starter storefront from the apps/storefront directory:

Your Next.js Starter storefront is now running at http://localhost:8000.

Payment Providers#

Stripe Integration#

The Next.js Starter storefront is compatible with Medusa's Stripe Module Provider.

Stripe Module Provider installed in the MedusaGo application.↗

In your Next.js Starter project, set the following environment variables for the Stripe integration:

Terminal
NEXT_PUBLIC_STRIPE_KEY=<YOUR_PUBLISHABLE_KEY>

Where <YOUR_PUBLISHABLE_KEY> is your Stripe publishable key. You can retrieve it from your Stripe dashboard by going to Developers → API Keys.

Then, restart the Next.js Starter storefront. You can now use Stripe during checkout.

Tip: Refer to this guide to learn how to customize the Stripe integration and components.

Change MedusaGo Application URL#

By default, the MedusaGo application runs at http://localhost:9000. This value is defined in your Next.js Starter storefront under the environment variable MEDUSA_BACKEND_URL.

To change the URL of the MedusaGo application in the storefront, set the MEDUSA_BACKEND_URL environment variable:

Terminal
MEDUSA_BACKEND_URL=https://example.com

Change Medusa Publishable API Key#

All requests made from a storefront must pass a publishable API key in the request's header. This API key is created in the MedusaGo application. If you've installed the Next.js Starter storefront using create-medusago-app, the publishable API key is set in the environment variables automatically.

If you change your MedusaGo application or its database, or you lose the publishable API key you had before, make sure to change the NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY environment variable to the new publishable API key:

Terminal
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_123...