medusa-store/www/apps/resources/app/nextjs-starter/page.mdx

import { DetailsList } from "docs-ui"
import CmaOptionTroubleshooting from "../troubleshooting/_sections/nextjs/cma-option.mdx"
import CorsErrorTroubleshooting from "../troubleshooting/_sections/other/cors-errors.mdx"
import ModuleXErrorTroubleshooting from "../troubleshooting/_sections/common-installation-errors/module-x-error.mdx"

export const metadata = {
  title: `Next.js Starter`,
}

# {metadata.title}

The Next.js Starter storefront provides rich commerce features and a sleek design. Developers and businesses can use it as-is or as a starting point to build a storefront for their Medusa application.

<Note type="check">

- [Node.js v18+](https://nodejs.org/en/download)

</Note>

## Installation

### Option 1: Medusa Application + Next.js Starter

The `create-medusa-app` CLI tool accepts the `--with-nextjs-starter` option that installs the Next.js storefront along with the Medusa application:

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

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

### Option 2: Next.js Starter Only

<Note type="check">

- At least one region in the Medusa application.

</Note>

1. Create a new Next.js project using the [Next.js Starter's GitHub repository](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 `my-medusa-storefront` directory and rename the template environment variable:

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

3. While the Medusa application is running, start the Next.js storefront:

```bash npm2yarn
npm run dev
```

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

---

## Troubleshooting

<DetailsList
  sections={[
    {
      title: "Next.js storefront not working using option 1",
      content: <CmaOptionTroubleshooting />
    },
    {
      title: "CORS Error",
      content: <CorsErrorTroubleshooting />
    },
    {
      title: `Resolve "Cannot find module X" Errors`,
      content: <ModuleXErrorTroubleshooting />
    }
  ]}
/>

## Payment Providers

The Next.js Starter storefront is compatible with Medusa's Stripe and PayPal plugins.

### Stripe Integration

<Note type="check">

- [Stripe plugin](../plugins/payment/stripe/page.mdx) installed in the Medusa application.

</Note>

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

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

Where `<YOUR_PUBLISHABLE_KEY>` is your Stripe publishable key. You can retrieve it from your [Stripe dashboard](https://dashboard.stripe.com/) by going to Developers → API Keys.

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

### PayPal Integration

<Note type="check">

- [PayPal plugin](../plugins/payment/paypal/page.mdx) installed in the Medusa application.

</Note>

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

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

Where `<YOUR_CLIENT_ID>` is your PayPal client ID. You can retrieve it from the [PayPal developer dashboard](https://developer.paypal.com/developer/applications/).

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

---

## Search Engine

The Next.js Starter storefront is compatible with Medusa's MeiliSearch and Algolia plugins.

### Enable Search Engine

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

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

Then, restart your Next.js storefront. You'll see a "Search" link in the navigation bar.

### Configure MeiliSearch

<Note type="check">

- [MeiliSearch plugin](../plugins/search/meilisearch/page.mdx) installed in the Medusa application.

</Note>

In your Next.js Starter storefront, set the following environment variables for the MeiliSearch integration:

```bash
NEXT_PUBLIC_SEARCH_ENDPOINT=<YOUR_MEILISEARCH_URL>
NEXT_PUBLIC_INDEX_NAME=products
NEXT_PUBLIC_SEARCH_API_KEY=<YOUR_API_KEY>
```

Where:

- `<YOUR_MEILISEARCH_URL>` is the URL MeiliSearch is running on. The default is `http://127.0.0.1:7700`.
- `NEXT_PUBLIC_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.

Then, restart the Next.js Starter storefront. You can search through available products by clicking the search icon in the navigation bar.

<Note title="Tip">

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 application at least the fields `title`, `handle`, `description`, and `thumbnail`.

</Note>

### Configure Algolia

<Note type="check">

- [Algolia plugin](../plugins/search/algolia/page.mdx) installed in the Medusa application.

</Note>

In your Next.js Starter's directory, install the `algoliasearch` package:

```bash npm2yarn
npm install algoliasearch
```

Then, set the following environment variables for the Algolia integration:

```bash
NEXT_PUBLIC_SEARCH_APP_ID=<YOUR_APP_ID>
NEXT_PUBLIC_SEARCH_API_KEY=<YOUR_SEARCH_API_KEY>
NEXT_PUBLIC_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 in your account settings](https://www.algolia.com/account/api-keys/all).
- `NEXT_PUBLIC_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:

```ts title="src/lib/search-client.ts"
import algoliasearch from "algoliasearch/lite"

const appId = process.env.NEXT_PUBLIC_SEARCH_APP_ID || ""

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

export const searchClient = algoliasearch(appId, apiKey)

export const SEARCH_INDEX_NAME =
  process.env.NEXT_PUBLIC_INDEX_NAME || "products"
```

And change the content of `src/app/(main)/search/actions.ts` to the following:

```ts title="src/app/(main)/search/actions.ts"
"use server"

import { 
  searchClient,
  SEARCH_INDEX_NAME,
} from "@lib/search-client"

/**
 * Uses MeiliSearch or Algolia to search for a query
 * @param {string} query - search query
 */
export async function search(query: string) {
  const index = searchClient.initIndex(SEARCH_INDEX_NAME)
  const { hits } = await index.search(query)

  return hits
}
```

Then, restart the Next.js Starter storefront. You can search through available products by clicking the search icon in the navigation bar.

<Note title="Tip">

To make sure the Next.js Starter storefront properly displays the products in the search result, include in the `attributesToRetrieve` setting of the Algolia plugin on the Medusa application at least the fields `title`, `handle`, `description`, and `thumbnail`.

</Note>

---

## Change Medusa Application URL

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

To change the URL of the Medusa application in the storefront, set the `NEXT_PUBLIC_MEDUSA_BACKEND_URL` environment variable:

```bash
NEXT_PUBLIC_MEDUSA_BACKEND_URL=https://example.com
```