shahednasser / commerce

Next.js x Medusa Commerce

Next.js Commerce x Medusa

Note: Looking for Next.js Commerce v1? View the code, demo, and release notes

A Next.js 13 and App Router-ready ecommerce template, built with Medusa, featuring:

• Next.js App Router
• Optimized for SEO using Next.js's Metadata
• React Server Components (RSCs) and Suspense
• Route Handlers for mutations
• Edge runtime
• New fetching and caching paradigms
• Dynamic OG images
• Styling with Tailwind CSS
• Automatic light/dark mode based on system settings

What is Medusa?

Medusa is a set of commerce modules and tools that allow you to build rich, reliable, and performant commerce applications without reinventing core commerce logic. The modules can be customized and used to build advanced ecommerce stores, marketplaces, or any product that needs foundational commerce primitives. All modules are open-source and freely available on npm.

Learn more about Medusa’s architecture and commerce modules in the Docs.

Running locally

You will need to use the environment variables defined in .env.example to run Next.js Commerce. It's recommended you use Vercel Environment Variables for this, but a .env file is all that is necessary.

Note: You should not commit your .env file or it will expose secrets.

1. Install Vercel CLI: npm i -g vercel
2. Link local instance with Vercel and GitHub accounts (creates .vercel directory): vercel link
3. Download your environment variables: vercel env pull

pnpm install
pnpm dev

Your app should now be running on localhost:3000.

How to configure your Medusa server for Next.js Commerce

Next.js Commerce x Medusa requires a running Medusa server.

Create a Medusa Backend​

It is recommended to use Yarn for the installation process as it's much faster than using NPM.

1. Install Medusa CLI​

yarn global add @medusajs/medusa-cli

If you run into any errors while installing the CLI tool, check out the troubleshooting guide.

2. Create a new Medusa project​

medusa new my-medusa-store --seed

3. Start your Medusa backend​

cd my-medusa-store medusa develop

4. Add Medusa backend domain to an environment variable

Copy the contents of .env.example to a .env file in the root of your Next.js Commerce project. Make sure the NEXT_PUBLIC_MEDUSA_BACKEND_API environment variable points to your Medusa backend domain (default: http://localhost:9000).

5. (Optional) Install Medusa Admin plugin and add product categories

Medusa comes with a few demo products, but they won't show up in the template by default. To showcase products in the store, we need to install the Medusa Admin and add a few product categories:

1. Install the Medusa Admin plugin
2. Enable the Product Categories feature flag
3. Log in to the admin dashboard and create the following product categories:

• hidden-homepage-carousel
• hidden-homepage-featured-items

4. Assign a few products to both categories and they should now show up on the homepage!