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@latest
Check 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
- Product Collections
- Cart
- Checkout with PayPal and Stripe
- User Accounts
- Order Details
- Next.js 14
- Full App Router support with Dynamic Routes and Route Groups
- Product Module support (beta)
To get started, click the "Deploy with Vercel" button below.
Navigate into your projects directory and get your environment variables ready:
cd nextjs-starter-medusa/
mv .env.template .env.local
Use Yarn to install all dependencies.
yarn
You are now ready to start up your project.
yarn dev
Your site is now running at http://localhost:8000!
Edit /pages/index.tsx
to see your site update in real-time!
The Product Module is currently in beta. You can learn more about it here. In addition, the product module in the Next.js storefront can't be used without the Medusa backend running at the moment.
This starter has full support for our new 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. If you're running it locally, it should be http://localhost:8000.
Then, enable the productModule feature flag in ./store.config.json
:
{
"features": {
// other features...
"productModule": true
}
}
Make sure the Medusa backend is running, then start (or restart) your Next.js storefront.
Done! All product and collection data should now be coming from the module. The Product Module routes are all in src/app/api
for you to edit and play around with.
To opt out of using the product module, simply set the productModule
feature flag to false
and restart the server.
Deploying to Vercel? If you're not planning on using the serverless modules, you might encounter errors when deploying to Vercel. You can safely delete or exclude the src/app/api
folder before deploying. The API routes are only used by the serverless modules.
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 Algoli 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"
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
.