Medusa Next.js Starter

Follow these steps to set up your local development environment for the Next.js starter:

1. Set up environment variables: Copy the template environment file to .env.local.
2. Install dependencies: Use yarn to install the required packages.
3. Start development server: Run the project locally.

The site will be available at http://localhost:8000.

# Set up environment variables
cd nextjs-starter-medusa/
mv .env.template .env.local

# Install dependencies
yarn

# Start developing
yarn dev

Before using this starter, you must have a Medusa server running locally on port 9000. You can set up a Medusa server quickly using the following command:

npx create-medusa-app@latest

The starter supports Stripe by default. To enable it, add your Stripe public key to your .env.local file. Additionally, you must configure the Stripe integration within your Medusa server as per the official Medusa documentation.

NEXT_PUBLIC_STRIPE_KEY=<your-stripe-public-key>

The Next.js middleware requires specific environment variables to fetch regions from your Medusa backend and handle routing. Ensure the following are set:

• MEDUSA_BACKEND_URL: The full URL of your Medusa server (e.g., https://your-medusa-url.com). Note: This is no longer named NEXT_PUBLIC_MEDUSA_BACKEND_URL.
• NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY: Your Medusa Publishable API Key used to authorize region requests.
• NEXT_PUBLIC_DEFAULT_REGION: (Optional) The fallback country code (e.g., us) if no other region can be determined. Defaults to us if not provided.

The SortProducts component provides a UI for users to select product sorting options via a radio group. It requires a sortBy value and a setQueryParams callback to update the application state (typically URL search parameters).

Props

• sortBy: The currently selected SortOptions value.
• setQueryParams: A function called when a new sort option is selected. It takes two arguments: the parameter name (always `

If the middleware fails to fetch regions, check the following:

1. Missing MEDUSA_BACKEND_URL: Ensure the environment variable is set correctly. The middleware will throw an error if this is missing.
2. No Regions Configured: If the backend returns successfully but contains no regions, the middleware will throw an error. Ensure you have created regions and assigned countries to them in your Medusa Admin.
3. API Key Issues: Ensure NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY is valid, as it is passed in the x-publishable-api-key header to the /store/regions endpoint.

Manage customer shipping and billing addresses using the following Server Actions:

• addCustomerAddress(currentState, formData): Creates a new address. Expects formData containing address fields (e.g., first_name, last_name, address_1, city, country_code, etc.). Returns { success: boolean, error: string | null }.
• updateCustomerAddress(currentState, formData): Updates an existing address. Requires an addressId which can be provided via currentState.addressId or formData.get("addressId").
• deleteCustomerAddress(addressId): Removes an address by its ID.