Skip to main content

Next.js Quickstart

This document guides you to install and set up the Next.js Starter Template.

Next.js Starter Template Demo

Instant Deployment to Vercel​

Instead of manually following this guide to install then later deploy the Next.js Starter Template, you can deploy the Next.js Starter Template to Vercel with this button:

Deploy with Vercel

Prerequisites​

This document assumes you already have a Medusa backend installed. If you don’t, you can install the Medusa backend with the following command:

npx create-medusa-app@latest
Report Incorrect CodeCopy to Clipboard

Learn more about prerequisites of create-medusa-appCopy to Clipboard and troubleshooting in this guide.

You should also have Node.js with v16 or greater installed. You can check your Node.js version with the following command:

node -v
Copy to Clipboard

You can install Node from the official website.

Installation​

1. Create a new Next.js project using the Medusa starter template:

npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-medusa-storefront
Report Incorrect CodeCopy to Clipboard

2. Change to the newly created directory my-medusa-storefrontCopy to Clipboard and rename the template environment variable file to use environment variables in development:

cd my-medusa-storefront
mv .env.template .env.local
Report Incorrect CodeCopy to Clipboard

3. Make sure the Medusa backend is running, then run the local Next.js server:

yarn dev
Report Incorrect CodeCopy to Clipboard

Your Next.js Starter Template is now running at localhost:8000Copy to Clipboard

Did you set up the storefront successfully?

Troubleshooting Installation​

CORS Error

If you are experiencing connection issues when trying to access your Medusa backend from a storefront or the admin dashboard, it is most likely due to Cross-Origin Resource Sharing (CORS) issues.

You might see a log in your browser console, that looks like this:

CORS error log

In your medusa-config.jsCopy to Clipboard , you should ensure that you've configured your CORS settings correctly. By default, the Medusa starter runs on port 9000Copy to Clipboard, Medusa Admin runs on port 7000Copy to Clipboard, and the storefront starters run on port 8000Copy to Clipboard.

The default configuration uses the following CORS settings:

medusa-config.js
// CORS when consuming Medusa from admin
const ADMIN_CORS = process.env.ADMIN_CORS || 
  "http://localhost:7000,http://localhost:7001"

// CORS to avoid issues when consuming Medusa from a client
const STORE_CORS = 
  process.env.STORE_CORS || "http://localhost:8000"
Report Incorrect CodeCopy to Clipboard

If you wish to run your storefront or Medusa admin on other ports, you should update the above settings accordingly.

See Also​

Resolve "Cannot find module X" Errors

This error can occur while installing any of Medusa's projects (for example, Next.js Starter Template). There is no specific cause to this error.

One way to resolve it is by removing the node_modulesCopy to Clipboard directory in the project and re-installing the dependencies:

rm -rf node_modules
yarn install
Report Incorrect CodeCopy to Clipboard

Development Notes​

Changing Medusa Backend URL​

By default, the Medusa backend runs at http://localhost:9000Copy to Clipboard. This value is defined in your Next.js starter template under the environment variable NEXT_PUBLIC_MEDUSA_BACKEND_URLCopy to Clipboard.

If you need to change the URL of your Medusa backend because you changed the backend's default port or because you deployed your backend, change the value of NEXT_PUBLIC_MEDUSA_BACKEND_URLCopy to Clipboard (typically in .env.localCopy to Clipboard) to your backend URL. For example:

NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9001
Report Incorrect CodeCopy to Clipboard

Toggle Search Engine Feature​

The Next.js Starter Template by default is compatible with MeiliSearch.

To enable or disable the search engine, change the value of the feature in store.config.jsonCopy to Clipboard:

{
  "features": {
    "search": false
  }
}
Report Incorrect CodeCopy to Clipboard

Then, restart your Next.js backend. Depending on whether you enabled or disabled the search engine, the search bar will appear or disappear in the navigation bar accordingly.

MeiliSearch Integration​

If you have the search engine feature enabled, it is expected that you have installed the MeiliSearch plugin on your Medusa backend. If not, follow this guide to install it.

In your Next.js Starter Template, set the environment variables necessary for the MeiliSearch integration:

NEXT_PUBLIC_SEARCH_ENDPOINT=<YOUR_MEILISEARCH_URL>
NEXT_PUBLIC_SEARCH_API_KEY=<YOUR_API_KEY>
NEXT_PUBLIC_SEARCH_INDEX_NAME=products
Report Incorrect CodeCopy to Clipboard

<YOUR_MEILISEARCH_URL>Copy to Clipboard is the URL MeiliSearch is running on. The default is http://127.0.0.1:7700Copy to Clipboard.

NEXT_PUBLIC_SEARCH_INDEX_NAMECopy to Clipboard is the index name of the products in MeiliSearch. By default, it’s productsCopy to Clipboard.

<YOUR_API_KEY>Copy to Clipboard is the API key used to search through MeiliSearch indexes. To create a new API Key, make sure that the MeiliSearch service is running and send the following request:

curl \
  -X POST '<MEILISEARCH_URL>/keys' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <MEILISEARCH_MASTER_KEY>' \
  --data-binary '{
    "description": "Search products",
    "actions": ["search"],
    "indexes": ["products"],
    "expiresAt": "2024-01-01T00:00:00Z"
  }'
Report Incorrect CodeCopy to Clipboard

Make sure to replace <MEILISEARCH_URL>Copy to Clipboard with the URL MeiliSearch is running on and <MEILISEARCH_MASTER_KEY>Copy to Clipboard with your MeiliSearch master key.

Then, restart the Next.js backend. You’ll be able to search through available products by clicking the search icon in the navigation bar.

To make sure the Next.js Starter Template properly displays the products in the search result, include in the displayedAttributesCopy to Clipboard setting of the MeiliSearch plugin on the Medusa backend at least the fields titleCopy to Clipboard, handleCopy to Clipboard, descriptionCopy to Clipboard, and thumbnailCopy to Clipboard.

Search Result on Next.js Starter Template

Algolia Integration​

Instead of using the default MeiliSearch search engine, you can switch to using Algolia. Make sure you start by installing the Algolia plugin on your Medusa backend. You can do it by following this guide.

In your Next.js Starter Template, set the environment variables necessary for the Algolia integration:

NEXT_PUBLIC_SEARCH_APP_ID=<YOUR_APP_ID>
NEXT_PUBLIC_SEARCH_API_KEY=<YOUR_SEARCH_API_KEY>
NEXT_PUBLIC_SEARCH_INDEX_NAME=products
Report Incorrect CodeCopy to Clipboard

Where <YOUR_APP_ID>Copy to Clipboard and <YOUR_SEARCH_API_KEY>Copy to Clipboard are the Algolia App ID and Algolia Search API Key respectively. You can retrieve them from Algolia by going to API Keys in your account settings.

NEXT_PUBLIC_SEARCH_INDEX_NAMECopy to Clipboard is the index name of the products in Algolia. By default, it’s productsCopy to Clipboard.

Next, change the content of src/lib/search-client.tsCopy to Clipboard to the following:

import algoliasearch from "algoliasearch/lite"

const appId = process.env.NEXT_PUBLIC_SEARCH_APP_ID || "" // You should add this to your environment variables

const apiKey = process.env.NEXT_PUBLIC_SEARCH_API_KEY || "test_key"

export const searchClient = algoliasearch(appId, apiKey)

export const SEARCH_INDEX_NAME =
  process.env.NEXT_PUBLIC_INDEX_NAME || "products"
Report Incorrect CodeCopy to Clipboard

Then, restart the Next.js backend. You’ll be able to search through available products by clicking the search icon in the navigation bar.

Search Pop-up in Next.js Starter Template

Stripe Payment Integration​

Stripe integration is supported by default. Make sure you have Stripe installed and enabled on your Medusa backend first. You can follow this guide to learn how to install it.

Then, in your Next.js Starter Template, set the environment variable necessary for the Stripe integration:

NEXT_PUBLIC_STRIPE_KEY=<YOUR_PUBLISHABLE_KEY>
Report Incorrect CodeCopy to Clipboard

Make sure to replace <YOUR_PUBLISHABLE_KEY>Copy to Clipboard with your Stripe publishable key. It can be retrieved from your Stripe dashboard by going to Developers → API Keys.

If you restart your Next.js backend you should be able to pay with Stripe on checkout.

Pay with Stripe on Checkout

PayPal Payment Integration​

PayPal integration is supported by default. Make sure you have PayPal installed and enabled on your Medusa backend first. You can follow this guide to learn how to install it.

Then, in your Next.js Starter Template, set the environment variable necessary for the PayPal integration:

NEXT_PUBLIC_PAYPAL_CLIENT_ID=<YOUR_CLIENT_ID>
Report Incorrect CodeCopy to Clipboard

Make sure to replace <YOUR_CLIENT_ID>Copy to Clipboard with your PayPal client ID. You can retrieve it from the PayPal developer dashboard.

If you restart your Next.js backend you should be able to pay with PayPal on checkout.

Pay with PayPal on Checkout

Customization​

To customize the pages of the storefront, you can customize the files under the src/pagesCopy to Clipboard directory.

To customize the components used in the storefront, you can customize the files under the src/modulesCopy to Clipboard directory.

To customize the styles of the storefront, you can customize the src/stylesCopy to Clipboard directory.

Change Port​

By default, the Next.js Starter Template runs on port 8000Copy to Clipboard.

To change the port, change the developCopy to Clipboard command in package.jsonCopy to Clipboard to the following:

"scripts": {
    //other scripts
    "dev": "next dev -p <PORT>"
}
Report Incorrect CodeCopy to Clipboard

Make sure to replace <PORT>Copy to Clipboard with the port number you want the storefront to run on. For example, 3000Copy to Clipboard.

Then, on your backend, update the environment variable STORE_CORSCopy to Clipboard to the URL with the new port:

STORE_CORS=http://localhost:<PORT>
Report Incorrect CodeCopy to Clipboard

Development Resources​

You can learn more about development with Next.js through their documentation.

Storefront Features​

  • View all products and manage your cart.

All Products Page

  • Customer authentication and profiles.

Customer Profile

  • Full checkout workflow.

Checkout Page

See Also​

Was this page helpful?
© 2023 Medusa, Inc. All rights reserved.