---
title: 'Get started with Next.js for e-commerce'
description: 'Learn how to get started with a Next.js storefront and Medusa. The Next.js Starter includes ready-integrations with plugins like Stripe and Algolia. It offers features like customer accounts, cart and checkout flows, and more.'
---

import Feedback from '@site/src/components/Feedback';
import QueryNote from '@site/src/components/QueryNote';
import Troubleshooting from '@site/src/components/Troubleshooting'
import ModuleXErrorSection from '../troubleshooting/common-installation-errors/_module-x-error.mdx'
import CorsErrorSection from '../troubleshooting/cors-issues.md'

# Next.js Quickstart

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

<!-- vale docs.We = NO  -->

<QueryNote
  query={{
    key: 'ref',
    value: 'gatsby-medusa-starter'
  }}
  admonition={{
    type: 'note'
  }}
>
  We've deprecated the Gatsby starter storefront and instead recommend using the Next.js Starter Storefront or [building your own custom storefront](../storefront/roadmap.mdx).
</QueryNote>

<!-- vale docs.We = YES  -->

![Next.js Starter Storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1692197728/Medusa%20Docs/Screenshots/b9c5cqpbzfusid0tar9d.jpg)

## Instant Deployment to Vercel

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

<a 
  href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fmedusajs%2Fnextjs-starter-medusa.git&env=NEXT_PUBLIC_MEDUSA_BACKEND_URL&envDescription=URL%20of%20your%20Medusa%20Backend" class="img-url no-zoom-img">
  <img src="https://vercel.com/button" alt="Deploy with Vercel" class="no-zoom-img"/>
</a>

---

## Prerequisites

Before following along with this guide, make sure you have v16 or greater of Node.js:

```bash noReport
node -v
```

You can install Node from the [official website](https://nodejs.org/en/).

---

## Option 1: Install a Full Ecommerce Store

The Next.js storefront requires a Medusa backend to be installed and running to work. The Medusa backend is a headless commerce engine, so storefronts connect to it using the Store REST APIs to provide commerce features to customers.

You can use the following command to install a full ecommerce store that includes the Medusa backend, Next.js storefront, and Medusa admin:

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

Refer to the [create-medusa-app](../create-medusa-app.mdx) documentation for more details on prerequisites, steps, and troubleshooting.

### Troubleshooting: Next.js Storefront Not Working

By default, the command above will start both the Medusa backend at `localhost:9000` and the Next.js storefront at `localhost:8000` once the installation finishes successfully. The Medusa admin will also open in your default browser.

If, while following along the setup process, you try to access the Next.js storefront and it's not working, try to run the storefront manually while the Medusa backend is still running.

To do that, first, change to the directory of the storefront. The directory name is `<PROJECT_NAME>-storefront`, where `<PROJECT_NAME>` is the name you chose for the project while running the `create-medusa-app` command. For example:

```bash
cd my-medusa-store-storefront
```

Then, run the following command to start the storefront:

```bash npm2yarn
npm run dev
```

The storefront should run on `localhost:8000` now.

---

## Option 2: Install Next.js Storefront Only

If you already have a Medusa backend installed, you can install the Next.js storefront separately.

To do that, follow these steps:

1\. Create a new Next.js project using the [Medusa starter Storefront](https://github.com/medusajs/nextjs-starter-medusa):

```bash
npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-medusa-storefront
```

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

```bash
cd my-medusa-storefront
mv .env.template .env.local
```

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

```bash npm2yarn
npm run dev
```

Your Next.js Starter Storefront is now running at `localhost:8000`

<Feedback 
   event="survey_nextjs_quickstart"
   question="Did you set up the storefront successfully?"
   positiveQuestion="Is there anything that should improved?"
   negativeQuestion="Please describe the issue you faced."
/>

---

## Troubleshooting Installation

<Troubleshooting
  sections={[
    {
      title: 'CORS Error',
      content: <CorsErrorSection />
    },
    {
      title: 'Resolve "Cannot find module X" Errors',
      content: <ModuleXErrorSection />
    },
  ]}
/>

---

## Development Notes

### Changing Medusa Backend URL

By default, the Medusa backend runs at `http://localhost:9000`. This value is defined in your Next.js starter Storefront under the environment variable `NEXT_PUBLIC_MEDUSA_BACKEND_URL`.

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_URL` (typically in `.env.local`) to your backend URL. For example:

```bash
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9001
```

### Using Product Module

:::note

The Product Module is currently in beta. You can learn more about it [here](../modules/products/serverless-module.md). In addition, the product module in the Next.js storefront can't be used without the Medusa backend at the moment.

:::

This starter has full support for the serverless Product Module for retrieving and manipulating product data directly from a serverless function. This keeps your product logic close to the frontend, making it easy to customize or extend Medusa's core functionality from within your Next.js project.

By default, this starter uses the standard Medusa API for product and collection retrieval.

To enable the Product Module, first, make sure to set the following environment variables:

- `PRODUCT_POSTGRES_URL`: the URL of your PostgreSQL databsae.
- `NEXT_PUBLIC_BASE_URL`: the URL of your storefront's base URL. For exmaple, if you're running it locally, it should be `http://localhost:8000`.

Then, enable the `productModule` feature flag in `store.config.json`:

```json title=store.config.json
{
  "features": {
    // other features...
    "productModule": true
  }
}

```

You can now test it out now. Make sure the Medusa backend is running, then start (or restart) your Next.js storefront:

```bash npm2yarn
npm run start
```

If you go to `localhost:8000`, all product and collection data should now be coming from the module. The Product Module routes are all in the `src/app/api` directory for you to customize to your use case.

To opt out of using the product module, simply set the `productModule` feature flag in `store.config.json` to `false` and restart the server.

### Toggle Search Engine Feature

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

To enable or disable the search engine, change the value of the feature in `store.config.json`:

```json
{
  "features": {
    "search": false
  }
}
```

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](../plugins/search/meilisearch.md).

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

```json
NEXT_PUBLIC_SEARCH_ENDPOINT=<YOUR_MEILISEARCH_URL>
NEXT_PUBLIC_SEARCH_API_KEY=<YOUR_API_KEY>
NEXT_PUBLIC_SEARCH_INDEX_NAME=products
```

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

`NEXT_PUBLIC_SEARCH_INDEX_NAME` is the index name of the products in MeiliSearch. By default, it’s `products`.

`<YOUR_API_KEY>` 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:

```bash
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"
  }'
```

Make sure to replace `<MEILISEARCH_URL>` with the URL MeiliSearch is running on and `<MEILISEARCH_MASTER_KEY>` with your MeiliSearch [master key](https://docs.meilisearch.com/learn/security/master_api_keys.html#protecting-a-meilisearch-instance).

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

:::note

To make sure the Next.js Starter Storefront properly displays the products in the search result, include in the `displayedAttributes` setting of the MeiliSearch plugin on the Medusa backend at least the fields `title`, `handle`, `description`, and `thumbnail`.

:::

![Search Result on Next.js Starter Storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003191/Medusa%20Docs/Screenshots/gQVWvH2_h1ljig.png)

### 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](../plugins/search/algolia.md).

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

```bash
NEXT_PUBLIC_SEARCH_APP_ID=<YOUR_APP_ID>
NEXT_PUBLIC_SEARCH_API_KEY=<YOUR_SEARCH_API_KEY>
NEXT_PUBLIC_SEARCH_INDEX_NAME=products
```

Where `<YOUR_APP_ID>` and `<YOUR_SEARCH_API_KEY>` are the Algolia App ID and Algolia Search API Key respectively. You can retrieve them from Algolia by going to [API Keys](https://www.algolia.com/account/api-keys/all) in your account settings.

`NEXT_PUBLIC_SEARCH_INDEX_NAME` is the index name of the products in Algolia. By default, it’s `products`.

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

```bash
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"
```

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 Storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003205/Medusa%20Docs/Screenshots/ZLgX5Ad_po6a4n.png)

### 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](../plugins/payment/stripe.mdx).

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

```bash
NEXT_PUBLIC_STRIPE_KEY=<YOUR_PUBLISHABLE_KEY>
```

Make sure to replace `<YOUR_PUBLISHABLE_KEY>` with your Stripe publishable key. It can be retrieved from your [Stripe dashboard](https://dashboard.stripe.com/) 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](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003250/Medusa%20Docs/Screenshots/h5mWdJT_yjogcq.png)

### 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](../plugins/payment/paypal.md).

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

```bash
NEXT_PUBLIC_PAYPAL_CLIENT_ID=<YOUR_CLIENT_ID>
```

Make sure to replace `<YOUR_CLIENT_ID>` with your PayPal client ID. You can retrieve it from the [PayPal developer dashboard](https://developer.paypal.com/developer/applications/).

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

![Pay with PayPal on Checkout](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003264/Medusa%20Docs/Screenshots/F8OvsOJ_mlx0le.png)

### Customization

To customize the pages of the storefront, you can customize the files under the `src/pages` directory.

To customize the components used in the storefront, you can customize the files under the `src/modules` directory.

To customize the styles of the storefront, you can customize the `src/styles` directory.

### Change Port

By default, the Next.js Starter Storefront runs on port `8000`.

To change the port, change the `develop` command in `package.json` to the following:

```json
"scripts": {
    //other scripts
    "dev": "next dev -p <PORT>"
}
```

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

Then, on your backend, update the environment variable `STORE_CORS` to the URL with the new port:

```bash
STORE_CORS=http://localhost:<PORT>
```

### Development Resources

You can learn more about development with Next.js through [their documentation](https://nextjs.org/docs/getting-started).

---

## Storefront Features

- View all products and manage your cart.

![All Products Page](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003278/Medusa%20Docs/Screenshots/1vLAYbH_sulxrr.png)

- Customer authentication and profiles.

![Customer Profile](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003287/Medusa%20Docs/Screenshots/etW3b3L_wccrez.png)

- Full checkout workflow.

![Checkout Page](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003296/Medusa%20Docs/Screenshots/VC8SYfb_eowjno.png)

---

## See Also

- [Storefront API reference](https://docs.medusajs.com/api/store)
- [Install Medusa Admin](../admin/quickstart.mdx).
- [Install Stripe as a payment processor](../plugins/payment/stripe.mdx#add-to-nextjs-storefront)
