Modern Headless Next.js E-commerce Storefront – Nimara

Nimara is a modern, high-performance e-commerce storefront designed for multi-region, global brands. It runs on Saleor and uses Next.js with React Server Components, TypeScript, and Tailwind CSS.

This storefront uses a headless architecture, separating the frontend presentation layer from the backend business logic. You can connect it to any e-commerce platform that provides a GraphQL API, with pre-built integration for Saleor.

Features

Use Cases

• Global Retail Brands: Create distinct, localized shopping experiences for different international markets with a single storefront implementation.
• Direct-to-Consumer (DTC) Businesses: Build a unique brand identity with a fully customized storefront that is not constrained by traditional e-commerce templates.
• High-Volume Stores: Develop a scalable and performant online store capable of handling large product catalogs and high traffic.
• Legacy System Migration: Upgrade an existing, monolithic e-commerce site to a modern, flexible, and maintainable headless architecture.

How to Use It

1. Install pnpm globally using npm, as Nimara relies on pnpm for package management and workspace coordination.

npm install -g pnpm

2. Install Turborepo globally to manage the monorepo build system and development workflows.

pnpm install turbo --global

3. Clone the Nimara repository from GitHub to your local development environment.

git clone https://github.com/mirumee/nimara-ecommerce.git
cd nimara-ecommerce

4. Copy the environment configuration template and configure your specific variables. The .env.example file contains all required environment variables with example values.

cp .env.example .env

5. Edit the .env file to include your specific configuration values.

# -- REQUIRED ENVIRONMENT VARIABLES --

# Saleor
# A Saleor channel slug that will be used as a default channel on the storefront.
NEXT_PUBLIC_DEFAULT_CHANNEL=
NEXT_PUBLIC_SALEOR_API_URL=
SALEOR_APP_TOKEN=

# URL of the storefront, required for generating the absolute URLs in sitemap.xml, OpenGraph etc.
NEXT_PUBLIC_STOREFRONT_URL=

# Auth.js env - required
AUTH_SECRET="<SOME_RANDOME_STRING>"
# NextAuth env - required only when NOT deploying on Vercel
AUTH_URL=

# Stripe env - required
STRIPE_SECRET_KEY=
NEXT_PUBLIC_STRIPE_PUBLIC_KEY=
NEXT_PUBLIC_PAYMENT_APP_ID=

# Name of the environment used for sentry: PRODUCTION, STAGING, DEVELOPMENT, LOCAL, TEST
# See: https://docs.sentry.io/concepts/key-terms/environments/
NEXT_PUBLIC_ENVIRONMENT="LOCAL"

# -- OPTIONAL ENVIRONMENT VARIABLES --

# E2E tests - required for Playwright tests in apps/automated-tests, optional for local development of storefront
TEST_ENV_URL=https://localhost:3000
USER_EMAIL="<YOR_EMAIL>"
USER_PASSWORD="<YOUR_PASSWORD>"

# Logging - available levels: debug, info, warn, error, critical; default: debug
LOG_LEVEL=debug

# Sentry - optional, used for error tracking
SENTRY_DSN=
SENTRY_AUTH_TOKEN=
SENTRY_ORG="<YOUR_SENTRY_ORG>"
SENTRY_PROJECT="<YOUR_SENTRY_PROJECT>"
SENTRY_DEBUG=false

# Default image format for Saleor media files.
NEXT_PUBLIC_DEFAULT_IMAGE_FORMAT="AVIF"

# Search engine - available options: "SALEOR", "ALGOLIA"
NEXT_PUBLIC_SEARCH_SERVICE=

# CMS engine - available options: "SALEOR", "BUTTER_CMS"
NEXT_PUBLIC_CMS_SERVICE=

6. Install all project dependencies using pnpm.

pnpm i

7. Start the development server for the storefront application.

pnpm run dev:storefront

8. Generate TypeScript types from your GraphQL schema to ensure type safety across the application.

pnpm run codegen

9. Your development storefront will be available at http://localhost:3000. The development environment includes hot reloading, error boundaries, and debugging tools for efficient development workflows.

10. For production deployment, Nimara supports multiple deployment strategies. The simplest approach uses Vercel’s one-click deployment with pre-configured environment variables. Alternatively, you can deploy using Terraform for more complex infrastructure requirements or custom hosting providers.

11. Configure your payment processing by setting up Stripe webhooks and ensuring your Stripe keys match your environment. The storefront uses Stripe’s Payment Element for secure payment processing with support for multiple payment methods and currencies.

12. Customize the storefront appearance by modifying Tailwind CSS classes and Shadcn/ui components.

Related Resources

• Saleor – Open-source headless e-commerce platform that serves as Nimara’s recommended backend solution.
• Next.js – React framework providing the foundation for Nimara’s frontend architecture and performance optimizations.
• Shadcn UI – Component library used throughout Nimara for consistent and accessible user interface elements.
• Turborepo – Monorepo build system that manages Nimara’s workspace structure and development workflows.

FAQs

Q: What e-commerce backend does Nimara connect to?
A: Nimara is designed to work with Saleor, a headless e-commerce platform. You must provide your Saleor API endpoint in the environment variables.

Q: Is Nimara suitable for B2B e-commerce?
A: Nimara supports B2B features through its headless architecture, including customer-specific pricing, bulk ordering, and account management. Additional customization may be needed for complex B2B workflows like approval processes or custom catalogs.

Q: What are the hosting requirements?
A: Nimara is optimized for modern hosting platforms like Vercel, Netlify, or AWS. It requires Node.js runtime and supports serverless deployment models. The application can also be deployed on traditional servers with Docker containerization.