Medusa Next.js Starter Template

Combine Medusa's modules for your commerce backend with the newest Next.js 14 features for a performant storefront.

Prerequisites

To use the Next.js Starter Template, you should have a Medusa server running locally on port 9000. For a quick setup, run:

npx create-medusa-app@latest

Check out create-medusa-app docs for more details and troubleshooting.

Overview

The Medusa Next.js Starter is built with:

• Next.js
• Tailwind CSS
• Typescript
• Medusa

Features include:

• Full ecommerce support:
  • Product Detail Page
  • Product Overview Page
  • Search with Algolia / MeiliSearch
  • Product Collections
  • Cart
  • Checkout with PayPal and Stripe
  • User Accounts
  • Order Details
• Full Next.js 14 support:
  • App Router
  • Next fetching/caching
  • Server Components
  • Server Actions
  • Streaming
  • Static Pre-Rendering

Quickstart

Setting up the environment variables

Navigate into your projects directory and get your environment variables ready:

cd nextjs-starter-medusa/
mv .env.template .env.local

Install dependencies

Use Yarn to install all dependencies.

yarn

Start developing

You are now ready to start up your project.

yarn dev

Open the code and start customizing

Your site is now running at http://localhost:8000!

Payment integrations

By default this starter supports the following payment integrations

• Stripe
• Paypal

To enable the integrations you need to add the following to your .env.local file:

NEXT_PUBLIC_STRIPE_KEY=<your-stripe-public-key>
NEXT_PUBLIC_PAYPAL_CLIENT_ID=<your-paypal-client-id>

You will also need to setup the integrations in your Medusa server. See the Medusa documentation for more information on how to configure Stripe and PayPal in your Medusa project.

Search integration

This starter is configured to support using the medusa-search-meilisearch plugin out of the box. To enable search you will need to enable the feature flag in ./store.config.json, which you do by changing the config to this:

{
  "features": {
    // other features...
    "search": true
  }
}

Before you can search you will need to install the plugin in your Medusa server, for a written guide on how to do this – see our documentation.

The search components in this starter are developed with Algolia's react-instant-search-hooks-web library which should make it possible for you to seemlesly change your search provider to Algolia instead of MeiliSearch.

To do this you will need to add algoliasearch to the project, by running

yarn add algoliasearch

After this you will need to switch the current MeiliSearch SearchClient out with a Alogolia client. To do this update @lib/search-client.

import algoliasearch from "algoliasearch/lite"

const appId = process.env.NEXT_PUBLIC_SEARCH_APP_ID || "test_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, in src/app/(main)/search/actions.ts, remove the MeiliSearch code (line 10-16) and uncomment the Algolia code.

"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
}

After this you will need to set up Algolia with your Medusa server, and then you should be good to go. For a more thorough walkthrough of using Algolia with Medusa – see our documentation, and the documentation for using react-instantsearch-hooks-web.

Resources

Learn more about Medusa

• Website
• GitHub
• Documentation

Learn more about Next.js

• Website
• GitHub
• Documentation