repository·master·Indexed 42 days ago
https://github.com/agilo/fashion-starterA modern, customizable e-commerce template for high-end fashion or furniture brands built with Medusa 2.0. It includes a Next.js storefront, dynamic product options, and Meilisearch integration. The starter provides guidance on creating custom API routes, Admin widgets, scheduled jobs, custom modules, and CLI scripts, and is compatible with @medusajs/medusa versions 1.8.0 and above.
The current E2E suite assumes a Postgres backend and relies on dropping/recreating databases. If you need to use a different database engine (such as SQLite or MySQL), you must implement a custom resetDatabase function.
Refer to seed/reset.ts for the existing implementation pattern and adapt it to your database type to ensure it can be called between test runs.
The storefront uses the Next.js App Router. The routing is organized as follows:
[countryCode]: The root directory is a dynamic route based on the country code (e.g., /us/products/...). This allows fetching region-specific prices and languages.(checkout) and (main) groups. These do not affect the URL but allow for different layouts (e.g., the checkout flow uses a different layout than the rest of the site)./account/orders/details/123 maps to src/app/[countryCode]/(main)/account/orders/details/[id].Accessing countryCode:
page.tsx): Access via the params object.useParams hook from next/navigation.// Server Component usage
export default async function Page({
params: { countryCode },
}: { params: { countryCode: string } }) {
const region = await getRegion(countryCode)
}
// Client Component usage
import { useParams } from "next/navigation"
const Component = () => {
const { countryCode } = useParams()
}The middleware.ts file acts as an Edge function that enforces a countryCode in the URL. If a user visits a URL without a countryCode, the middleware redirects them to the most relevant region based on this priority:
x-vercel-ip-country header.NEXT_PUBLIC_DEFAULT_REGION variable if defined.Note: The middleware also sets a cookie for Medusa Admin onboarding; this can be removed for production storefronts.
Medusa provides a set of open-source commerce modules and tools designed to build commerce applications (stores, marketplaces, etc.) without reinventing core logic. All modules are available on npm.
To understand how to build with these primitives, consult the Medusa Architecture overview and the Commerce Modules documentation.
Module Links allow you to form associations between data models belonging to different modules while preserving module isolation. You define these links using the defineLink utility from @medusajs/framework/utils.
To create a link, you pass the linkable entities from the respective modules to defineLink. For example, to associate a Product from the Medusa Product Module with a custom entity in your own module, you reference their .linkable properties.
import HelloModule from "../modules/hello"
import ProductModule from "@medusajs/medusa/product"
import { defineLink } from "@medusajs/framework/utils"
export default defineLink(
ProductModule.linkable.product,
HelloModule.linkable.myCustom
)The storefront is built with Next.js 15 and Tailwind CSS. After setting up the Medusa backend, follow these steps to run the storefront:
storefront directory..env.local file from the template.yarn.Important: You must paste the NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY (obtained from the Medusa admin at http://localhost:9000/app/settings/publishable-api-keys) into storefront/.env.local for the storefront to communicate with the backend.
The storefront will be available at http://localhost:8000.
cd storefront
# Create the .env.local file
cp .env.template .env.local
# Install dependencies
yarn
# Start the development server
yarn devTo get started with the storefront, ensure you have a Medusa server running locally on port 9000. Follow these steps to set up the local environment:
.env.local.yarn to install all required packages.http://localhost:8000.Prerequisites:
npx create-medusa-app@latest to create one quickly).# 1. Setup env
cd nextjs-starter-medusa/
mv .env.template .env.local
# 2. Install
yarn
# 3. Run
yarn devTo set up the Medusa 2.0 backend, follow these steps in order. This requires Docker and Docker Compose to be running for the database and Redis services.
medusa directory.yarn.After starting, access the admin at http://localhost:9000/app. You will need to retrieve a publishable key from the admin settings to connect the storefront.
cd medusa
# Create the .env file
cp .env.template .env
# Install dependencies
yarn
# Spin up the database and Redis
docker-compose up -d
# Build the project
yarn build
# Run the migrations
yarn medusa db:migrate
# Seed the database
yarn seed
# Create an user
yarn medusa user -e "admin@medusa.local" -p "supersecret"
# Start the development server
yarn devCustom CLI scripts allow you to execute custom Medusa tooling directly through the Medusa CLI.
To create a script:
.ts) or JavaScript (.js) file inside the src/scripts directory.default export of an async function.ExecArgs object as its parameter, which contains a container property. This container is an instance of the Medusa Container used to resolve application resources (e.g., module services).import {
ExecArgs,
IProductModuleService
} from "@medusajs/framework/types"
import { Modules } from "@medusajs/framework/utils"
export default async function myScript ({
container
}: ExecArgs) {
const productModuleService: IProductModuleService =
container.resolve(Modules.PRODUCT)
const [, count] = await productModuleService.listAndCount()
console.log(`You have ${count} product(s)`)
}To enable MeiliSearch, you must install the medusa-search-meilisearch plugin on your Medusa server and enable the feature flag in ./store.config.json:
{
"features": {
"search": true
}
}If you prefer Algolia, follow these steps:
yarn add algoliasearch.@lib/search-client to use the algoliasearch/lite client with your appId and apiKey (provided via environment variables).src/app/(main)/search/actions.ts to use the new searchClient instead of the MeiliSearch implementation.