Combine Medusa's modules for your commerce backend with the newest Next.js 14 features for a performant storefront.
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@latestCheck out create-medusa-app docs for more details and troubleshooting.
The Medusa Next.js Starter is built with:
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
Navigate into your projects directory and get your environment variables ready:
cd nextjs-starter-medusa/
mv .env.template .env.localUse Yarn to install all dependencies.
yarnYou are now ready to start up your project.
yarn devYour site is now running at http://localhost:8000!
By default this starter supports the following payment integrations
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.
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 algoliasearchAfter 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.
For the new version, the main folder structure remains unchanged. The contents have changed quite a bit though.
.
└── src
├── app
├── lib
├── modules
├── styles
├── types
└── middleware.ts
The app folder contains all Next.js App Router pages and layouts, and takes care of the routing.
.
└── [countryCode]
├── (checkout)
└── checkout
└── (main)
├── account
│ ├── addresses
│ └── orders
│ └── details
│ └── [id]
├── cart
├── categories
│ └── [...category]
├── collections
│ └── [handle]
├── order
│ └── confirmed
│ └── [id]
├── products
│ └── [handle]
├── results
│ └── [query]
├── search
└── store
The app router folder structure represents the routes of the Starter. In this case, the structure is as follows:
- The root directory is represented by the
[countryCode]folder. This indicates a dynamic route based on the country code. The this will be populated by the countries you set up in your Medusa server. The param is then used to fetch region specific prices, languages, etc. - Within the root directory, there two Route Groups:
(checkout)and(main). This is done because the checkout flow uses a different layout. All other parts of the app share the same layout and are in subdirectories of the(main)group. Route Groups do not affect the url. - Each of these subdirectories may have further subdirectories. For instance, the
accountdirectory hasaddressesandorderssubdirectories. Theordersdirectory further has adetailssubdirectory, which itself has a dynamic[id]subdirectory. - This nested structure allows for specific routing to various pages within the application. For example, a URL like
/account/orders/details/123would correspond to theaccount > orders > details > [id]path in the router structure, with123being the dynamic[id].
This structure enables efficient routing and organization of different parts of the Starter.
The lib directory contains all utilities like the Medusa JS client functions, util functions, config and constants.
The most important file here is /lib/data/index.ts. This file defines various functions for interacting with the Medusa API, using the JS client. The functions cover a range of actions related to shopping carts, orders, shipping, authentication, customer management, regions, products, collections, and categories. It also includes utility functions for handling headers and errors, as well as some functions for sorting and transforming product data.
These functions are used in different Server Actions.
This is where all the components, templates and Server Actions are, grouped by section. Some subdirectories have an actions.ts file. These files contain all Server Actions relevant to that section of the app.
global.css imports Tailwind classes and defines a couple of global CSS classes. Tailwind and Medusa UI classes are used for styling throughout the app.
Contains global TypeScript type defintions.
Next.js Middleware, which is basically an Edge function that runs before (almost) every request. In our case it enforces a countryCode in the url. So when a user visits any url on your storefront without a countryCode param, it will redirect the user to the url for the most relevant region.
The region will be decided as follows:
- When deployed on Vercel and you’re active in the user’s current country, it will use the country code from the
x-vercel-ip-countryheader. - Else, if you have defined a
NEXT_PUBLIC_DEFAULT_REGIONenvironment variable, it will redirect to that. - Else, it will redirect the user to the first region it finds on your Medusa server.
If you want to use the countryCode param in your code, there’s two ways to do that:
-
On the server in any
page.tsx- thecountryCodeis in theparamsobject:export default async function Page({ params: { countryCode }, }: { params: { countryCode: string } }) { const region = await getRegion(countryCode) // rest of code
-
From client components, with the
useParamhook:import { useParams } from "next/navigation" const Component = () => { const { countryCode } = useParams() // rest of code
The middleware also sets a cookie based on the onboarding status of a user. This is related to the Medusa Admin onboarding flow, and may be safely removed in your production storefront.