### Vercel Project Setup

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.15.0/marketplace.mdx

Configure Vercel for deployment by setting the root directory, build command, and install command.

```bash
Root Directory: apps/marketplace
Build Command: turbo run build --filter=marketplace
Install Command: pnpm install
```

--------------------------------

### Copy Storefront Environment Example

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/README.md

Copies the example environment file for the storefront. This file should then be configured with your specific backend details.

```bash
cp apps/storefront/.env.example apps/storefront/.env
```

--------------------------------

### Install App from Manifest URL

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/stripe-integration.mdx

Link to install the app in Saleor by providing the manifest URL. Replace placeholders with your specific domains.

```text
https://<YOUR-SALEOR-CLOUD-DOMAIN>/dashboard/apps/install?manifestUrl=https://<YOUR-APP-DOMAIN>/api/saleor/manifest
```

--------------------------------

### Start Storefront Development Server

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/README.md

Starts the development server for the storefront application. The app will be accessible at http://localhost:3000.

```bash
pnpm run dev:storefront
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/README.md

Installs all project dependencies using pnpm. This command should be run after cloning the repository.

```bash
pnpm i
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/storefront.mdx

Install all necessary project dependencies using pnpm. This command should be run after cloning the repository.

```bash
pnpm install
```

--------------------------------

### Configure Vercel Build and Install Commands

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-2.0.x/storefront.mdx

Set the Install Command to 'pnpm install' and the Build Command to 'turbo run build --filter=storefront' in Vercel project settings.

```bash
turbo run build --filter=storefront
```

--------------------------------

### Start Storefront Development Server

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/add-new-channel.mdx

Run the storefront development server to test the new locale. This command starts the server with hot-reloading enabled.

```bash
pnpm run dev:storefront

```

--------------------------------

### Run the Storefront Development Server

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-2.0.x/onboarding.mdx

Start the storefront development server using pnpm. The storefront will be accessible at http://localhost:3000.

```bash
pnpm dev:storefront
```

--------------------------------

### Configure Vercel Build and Install Commands

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/storefront.mdx

Set the build and install commands for your Vercel deployment. This ensures the project is built and dependencies are installed correctly during deployment.

```bash
turbo run build --filter=storefront
```

```bash
pnpm install
```

--------------------------------

### Install Turborepo Globally

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/README.md

Installs the Turborepo build system globally. Turborepo is used for efficient monorepo builds.

```bash
pnpm install turbo --global
```

--------------------------------

### Copy Environment Variables

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/storefront.mdx

Copy the example environment variables to a new .env file. This sets up the initial configuration for your project.

```bash
cp .env.example .env
```

--------------------------------

### Example Usage of Actions

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/packages/features/src/product-detail-page/shared/actions/PROPOSAL.md

Shows how to import and pass actions through the component tree in the storefront.

```typescript
// In storefront app
import { addToBagAction } from "@/nimara/features/product-detail-page/actions/add-to-bag";

// In VariantSelectorWrapper (server component)
<VariantSelector
  addToBagAction={addToBagAction}
  // ... other props
/>

// In VariantSelector (client component)
<AddToBag
  addToBagAction={addToBagAction}
  // ... other props
/>
```

--------------------------------

### Run Marketplace Development Server

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.15.0/marketplace.mdx

Start the marketplace app development server. It runs on port 3001 by default.

```bash
pnpm dev:marketplace
```

--------------------------------

### Vercel Build and Install Commands

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-2.0.x/marketplace.mdx

Configure Vercel for deployment by setting the build and install commands. This ensures the correct build process for the marketplace app within the monorepo.

```bash
turbo run build --filter=marketplace
```

```bash
pnpm install
```

--------------------------------

### Install pnpm Globally

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/README.md

Installs the pnpm package manager globally on your system. This is a prerequisite for managing project dependencies.

```bash
npm install -g pnpm
```

--------------------------------

### App Manifest URL

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/stripe-integration.mdx

The manifest URL for your deployed app, used for installation in Saleor.

```text
https://<your-app-domain>/api/saleor/manifest
```

--------------------------------

### Run Local Docs Development

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/README.md

Starts the Docusaurus development server for the Nimara documentation site. Changes in versioned docs, src, and config files trigger hot reloads.

```bash
pnpm dev:docs
```

--------------------------------

### Reproduce CI Link Check Locally

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/README.md

Performs a local link check on the built documentation site using lychee. Requires lychee to be installed via Homebrew.

```bash
pnpm build:docs
lychee --config apps/docs/lychee.toml \
  --root-dir "$(pwd)/apps/docs/build" \
  --no-progress \
  'apps/docs/build/**/*.html'
```

--------------------------------

### Checkout and Pull Develop Branch

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-2.0.x/release-workflow.md

Ensure you are on the develop branch and have the latest changes before starting new work.

```bash
git checkout develop
git pull origin develop
```

--------------------------------

### Run Nimara Stripe Python App with Docker

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/stripe-integration.mdx

Quickly start the Nimara Stripe Python app for basic usage or testing using Docker. The app will be accessible at http://localhost:8080.

```bash
docker run -p 8080:8080 ghcr.io/mirumee/nimara-stripe:latest
```

--------------------------------

### Configure Terraform Variables for Nimara Stripe App

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/stripe-integration.mdx

Copy the example Terraform configuration file and fill in your specific variables for deploying the Nimara Stripe Python app on AWS.

```bash
cp terraform.tfvars.example terraform.tfvars
```

--------------------------------

### Storefront App i18n Configuration

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.15.0/i18n.md

Example of how the storefront app uses its identifier to create the i18n request configuration. This process loads and merges base English messages with locale-specific overrides.

```javascript
import { createRequestConfig } from "@nimara/i18n";

createRequestConfig({
  app: "storefront",
});
```

--------------------------------

### Conventional Commits Example

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/CONTRIBUTING.md

Example of a commit message following the Conventional Commits standard.

```git
docs: improve documentation about XXX
```

--------------------------------

### Set up Product Webhook

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.15.0/storefront.mdx

Configure a webhook in Saleor to receive product-related events.

```text
Target URL: https://<your-domain-url>/api/webhooks/saleor/products
Events: select all events related to the `Product` object, except `Export completed`.
```

--------------------------------

### Set Up Development Branch

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-2.0.x/onboarding.mdx

Create a new branch for your changes using Git. This is the first step before making any modifications.

```bash
git checkout -b contrib/my-first-change
```

--------------------------------

### UCP Get Cart Endpoint

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-2.0.x/ucp-integration.md

Use the GET /carts/{id} endpoint to retrieve a cart by its ID.

```http
GET /carts/{id}
```

--------------------------------

### Initialize Terraform Configuration

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/using-terraform.mdx

Navigate to the Terraform storefront directory and initialize Terraform to download necessary provider plugins.

```bash
cd nimara-ecommerce/terraform/storefront
terraform init
```

--------------------------------

### Set up Menu Webhook

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.15.0/storefront.mdx

Configure a webhook in Saleor to receive menu-related events.

```text
Target URL: https://<your-domain-url>/api/webhooks/saleor/menu
Events: select all events related to the `Menu` object.
```

--------------------------------

### Build Docs for Production

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/README.md

Builds the static output for the Nimara documentation site. The build process fails on broken internal or Markdown links, or anchors.

```bash
pnpm build:docs
```

--------------------------------

### Set up Page Webhook

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.15.0/storefront.mdx

Configure a webhook in Saleor to receive page-related events.

```text
Target URL: https://<your-domain-url>/api/webhooks/saleor/page
Events: select all events related to the `Page` object.
```

--------------------------------

### Cart to Checkout Conversion Request

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.15.0/ucp-integration.md

Example of converting a cart to a checkout session by including 'cart_id' in the create-checkout request.

```json
{
  "cart_id": "cart_abc123",
  "line_items": []
}
```

--------------------------------

### Navigate to Local Repository

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/CONTRIBUTING.md

Change your current directory to the cloned nimara-ecommerce repository.

```bash
cd nimara-ecommerce
```

--------------------------------

### Navigate to Terraform Storefront Directory

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-2.0.x/using-terraform.mdx

Navigate to the directory containing the Terraform configuration files for the storefront.

```bash
cd nimara-ecommerce/terraform/storefront
```

--------------------------------

### UCP Error Response Example

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.15.0/ucp-integration.md

Format for UCP error responses, including messages and optional continue URL for escalations.

```json
{
  "ucp": { "version": "2026-04-08", "status": "error", "capabilities": { "..." } },
  "messages": [
    {
      "type": "error",
      "code": "out_of_stock",
      "content": "Item is no longer available",
      "severity": "recoverable"
    }
  ],
  "status": "incomplete",
  "continue_url": "https://storefront.example.com/checkout"
}
```

--------------------------------

### Set up Collection Webhook

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.15.0/storefront.mdx

Configure a webhook in Saleor to receive collection-related events.

```text
Target URL: https://<your-domain-url>/api/webhooks/saleor/collections
Events: select `Deleted` and `Updated` events related to `Collection` object.
```

--------------------------------

### UCP Response Envelope Example

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.15.0/ucp-integration.md

Standard metadata envelope included in all UCP responses. 'ucp.status' is the primary success/error indicator.

```json
{
  "ucp": {
    "version": "2026-04-08",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [{ "version": "2026-04-08" }]
    },
    "payment_handlers": {}
  },
  "id": "...",
  "status": "incomplete",
  "..."
}
```

--------------------------------

### Implement Core and Server Action Pattern

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/DEVELOPER_REVIEW_REPORT.md

Demonstrates the separation of framework-agnostic business logic in core files from Next.js server action wrappers.

```typescript
// packages/features/src/checkout/shared/actions/update-delivery-method.core.ts
export const updateDeliveryMethodCore = async ({
  services,
  checkoutId,
  deliveryMethodId,
}: {
  services: ServiceRegistry;
  checkoutId: string;
  deliveryMethodId: string;
}) => {
  // Pure business logic
  return await services.checkout.checkoutDeliveryMethodUpdate({
    checkoutId,
    deliveryMethodId,
  });
};

// apps/storefront/src/app/.../actions.ts
("use server");
import { updateDeliveryMethodCore } from "@nimara/features/checkout/...";
import { revalidatePath } from "next/cache";

export async function updateDeliveryMethod(data: FormSchema) {
  const services = await getServiceRegistry();
  const checkoutId = await getCheckoutId();

  const result = await updateDeliveryMethodCore({
    services,
    checkoutId,
    deliveryMethodId: data.deliveryMethodId,
  });

  revalidatePath(paths.checkout.asPath());
  return result;
}
```

--------------------------------

### New Locale Translation Structure

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/add-new-channel.mdx

Example JSON structure for a new locale's translation file (`es-ES.json`). Translate all required messages to the target language.

```json
{
  "common": {
    "locale_name": "Español (España)",
    "cart": "Carrito",
    "checkout": "Pagar"
  },
  "errors": {
    "not_found": "No encontrado"
  }
}
```

--------------------------------

### Define Storefront-Specific Action

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/packages/features/src/product-detail-page/shared/actions/PROPOSAL.md

Initializes a server action file within the storefront directory.

```typescript
// apps/storefront/src/nimara/features/product-detail-page/actions/add-to-bag.ts
"use server";

// ... existing implementation (same as current add-to-bag.ts)
```

--------------------------------

### Implement Storefront Page Wrapper

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/DEVELOPER_REVIEW_REPORT.md

Shows how storefront pages act as thin wrappers that inject services and props into feature-specific view components.

```typescript
// apps/storefront/src/app/.../page.tsx
export default async function Page(props: PageProps) {
  const services = await getServiceRegistry();
  return (
    <StandardPDPView
      {...props}
      services={services}
      paths={...}
      checkoutId={...}
      addToBagAction={...}
    />
  );
}
```

--------------------------------

### Run Project Build and Test Commands

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-2.0.x/onboarding.mdx

Execute these commands to generate code if necessary, run tests, and format your code according to project standards. Ensure you only run codegen if .graphql files have changed.

```bash
pnpm codegen   # only if .graphql files changed
```

```bash
pnpm test
```

```bash
pnpm format
```

--------------------------------

### Verify Code Quality with Turbo and pnpm

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/CLAUDE.md

Run these commands to ensure code adheres to linting, formatting, testing, and code generation standards before committing.

```bash
turbo run lint:staged   # lint changed files
pnpm format:check       # Prettier (must stay clean)
pnpm test               # Vitest
pnpm codegen            # regenerate + check no diff after .graphql edits
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-2.0.x/onboarding.mdx

Common commands for running the development server, generating types, and running tests. Use `pnpm dev:storefront` for the storefront or `pnpm dev` for all services.

```bash
pnpm dev:storefront        # one app (also: dev:marketplace, dev:stripe, dev:docs)
pnpm dev                   # everything

pnpm codegen               # regenerate GraphQL types after editing .graphql files
pnpm test                  # unit tests (Vitest)
pnpm test:e2e              # end-to-end (Playwright)

pnpm format                # Prettier
pnpm format:check          # what CI checks
```

--------------------------------

### Configure Saleor API URL

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/storefront.mdx

Set the NEXT_PUBLIC_SALEOR_API_URL environment variable in your .env file. Use your Saleor Cloud domain or a local Saleor instance URL.

```properties
# Add backend address
NEXT_PUBLIC_SALEOR_API_URL=https://{your_domain}.saleor.cloud/graphql/

# Local example
# NEXT_PUBLIC_SALEOR_API_URL=http://localhost:8000/graphql/
```

--------------------------------

### Fork and Clone Nimara Repository

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-2.0.x/onboarding.mdx

Clone the Nimara e-commerce repository and set up the upstream remote for contributing. This is the first step in setting up your local development environment.

```bash
git clone https://github.com/{your_github_username}/nimara-ecommerce.git
cd nimara-ecommerce
git remote add upstream git@github.com:mirumee/nimara-ecommerce.git
```

--------------------------------

### Plan Terraform Deployment

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/using-terraform.mdx

Generates an execution plan for Terraform to show what actions will be taken to deploy the storefront. This command should be run before applying any changes.

```bash
terraform plan
```

--------------------------------

### Run Project Tests

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/CONTRIBUTING.md

Execute all project tests to ensure your changes do not introduce regressions.

```bash
pnpm run test
```

--------------------------------

### Clone Your Forked Repository

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/CONTRIBUTING.md

Clone your forked repository to your local machine after clicking the 'Fork' button.

```bash
git clone https://github.com/{YOUR_USERNAME}/nimara-ecommerce.git
```

--------------------------------

### Storefront Region Configuration

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/add-new-channel.mdx

Configure market and region-specific settings for the storefront, including channel mapping, language metadata, and market details. This file defines how locales correspond to Saleor channels and market configurations.

```typescript
import { LOCALES } from "@nimara/i18n/config";

import { clientEnvs } from "@/envs/client";

export const CHANNEL = clientEnvs.NEXT_PUBLIC_DEFAULT_CHANNEL;

export const LOCALE_CHANNEL_MAP = {
  "en-GB": "gb",
  "en-US": "us",
  "es-ES": "es", // Map the locale to the market ID
} as const;

export const SUPPORTED_CURRENCIES = ["USD", "GBP", "EUR"] as const;

export const SUPPORTED_CHANNELS = [
  "default-channel",
  "channel-us",
  "channel-uk",
  "channel-es",
] as const;

export const LANGUAGES = {
  GB: {
    id: "gb",
    name: "English (United Kingdom)",
    code: "EN_GB",
    locale: "en-GB",
  },
  US: {
    id: "us",
    name: "English (United States)",
    code: "EN_US",
    locale: "en-US",
  },
  ES: {
    id: "es",
    name: "Español (España)",
    code: "ES_ES",
    locale: "es-ES",
  },
} as const;

export const MARKETS = {
  GB: {
    id: "gb",
    name: "United Kingdom",
    channel: "channel-uk",
    currency: "GBP",
    continent: "Europe",
    countryCode: "GB",
    defaultLanguage: LANGUAGES.GB,
    supportedLanguages: [LANGUAGES.GB],
  },
  US: {
    id: "us",
    name: "United States of America",
    channel: "channel-us",
    currency: "USD",
    continent: "North America",
    countryCode: "US",
    defaultLanguage: LANGUAGES.US,
    supportedLanguages: [LANGUAGES.US],
  },
  ES: {
    id: "es",
    name: "España",
    channel: "channel-es",
    currency: "EUR",
    continent: "Europe",
    countryCode: "ES",
    defaultLanguage: LANGUAGES.ES,
    supportedLanguages: [LANGUAGES.ES],
  },
} as const;

export const REGIONS_CONFIG = {
  channel: CHANNEL,
  supportedLocales: LOCALES,
  languages: LANGUAGES,
  markets: MARKETS,
  localeToMarket: LOCALE_CHANNEL_MAP,
  supportedCurrencies: SUPPORTED_CURRENCIES,
} as const;

```

--------------------------------

### Environment Variable Configuration

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/add-new-channel.mdx

Set the default Saleor channel in your local environment variables. This ensures the storefront uses the correct channel when loading.

```bash
# Your default channel (should match a channel slug in Saleor)
NEXT_PUBLIC_DEFAULT_CHANNEL=channel-es

```

--------------------------------

### Apply Terraform Deployment

Source: https://github.com/mirumee/nimara-ecommerce/blob/main/apps/docs/versioned_docs/version-1.14.0/using-terraform.mdx

Applies the planned changes to deploy the storefront to Vercel. This command will prompt for confirmation before proceeding.

```bash
terraform apply
```