> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-storefront.md).

# Emporix Storefront

Use the emporix-storefront skill to develop, run, and deploy the Emporix Journey Aware Storefront.

Use the **emporix-storefront** skill when you work in the Emporix storefront codebase: run it locally, change pages or components, or deploy it. The storefront is a Next.js and React foundation, not a finished shop. Customization is the expected path.

{% hint style="info" %}
This page explains when to use the skill and how to work with it. For the product overview, see [B2B Commerce Frontend](https://developer.emporix.io/frontend-guides/). Installation detail ships with the storefront package. Journey Aware Storefront, B2B Commerce Frontend, and `emporix-showcase` are names for the same product.
{% endhint %}

## Skill details

| Property     | Value                                              |
| ------------ | -------------------------------------------------- |
| Skill name   | `emporix-storefront`                               |
| Package path | `skills/emporix-storefront/` (contains `SKILL.md`) |

Install it once using [Installing skills](/agentic-commerce-intelligence/agentic-engineering/skill-library.md#installing-skills).

## When to use it

Use this skill when you need to:

* Run the storefront locally or check why `/api/ready` returns 503
* Decide which of the three layers a change belongs in
* Customize pages, routing, or design tokens
* Deploy to Vercel, Cloud Run, Kubernetes, or Azure
* Diagnose a blank page, a 401 on first load, a redirect loop, or CSS tokens that do not resolve

{% hint style="info" %}
API tokens and scopes belong to the [Emporix Auth](/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-auth.md) skill. Mixins belong to [Emporix Extensibility](/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-extensibility.md). Catalog import belongs to [Emporix Product Data](/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-product-data.md).
{% endhint %}

## How it works

Most storefront questions reduce to two checks: which layer owns the change, and which environment variable or infrastructure prerequisite is missing.

The codebase uses three layers. Pick the one that owns the change:

```mermaid
---
config:
  layout: fixed
  theme: base
  look: classic
  themeVariables:
    background: transparent
    lineColor: "#9CBBE3"
    arrowheadColor: "#9CBBE3"
    edgeLabelBackground: "#FFC128"
    edgeLabelTextColor: "#4C5359"
---
flowchart TD
  Start["Which layer owns<br>the change?"]
  Integration["Integration<br>external calls"]
  Service["Service<br>business logic"]
  Repository["Repository<br>data access"]

  Start --> Integration
  Start --> Service
  Start --> Repository

  style Start fill:#F2F6FA,stroke:#4C5359,color:#4C5359
  style Integration fill:#DDE6EE,stroke:#4C5359,color:#4C5359
  style Service fill:#9CBBE3,stroke:#4C5359,color:#4C5359
  style Repository fill:#3B73BB,stroke:#4C5359,color:#FFFFFF

  Start@{ shape: rounded}
  Integration@{ shape: rounded}
  Service@{ shape: rounded}
  Repository@{ shape: rounded}
```

Repository data access is wired with InversifyJS. Routes are grouped by `[site]` and `[locale]`. Styling uses a brand, alias, and mapped design-token stack. Trust file paths in the repository `docs/` over paths remembered from an older version. The skill was validated against the 1.x line.

The source repository `emporix-shared/emporix-frontend` is private. Request access through the Emporix Developer Portal or partner onboarding before you start.

## Prerequisites

Before you use this skill, make sure you have:

* The storefront repository checked out
* Node.js 20 or newer, and dependencies installed with `npm install`
* Two credential pairs: the public Storefront API client id, and the server-side Emporix credentials the app uses for anonymous tokens
* A copy of `.env.template` as `.env` – shared demo values work only while those keys are still valid

## How to use it

After install, work in your AI tool from the storefront repository. Examples:

> The storefront returns 401 on first load and `/api/ready` is 503. Which env vars are missing?

> Add a field to the product details page. Which layer owns that change?

> After deploy I get `ERR_TOO_MANY_REDIRECTS`. What should I check first?

## Usage notes

* If the log shows `Invalid ApiKey` on the anonymous-token call, the demo Storefront key was rotated. Point `NEXT_PUBLIC_EMPORIX_TENANT` and `NEXT_PUBLIC_EMPORIX_CLIENT_ID` at your own tenant.
* A blank first page is often a missing env var, not a routing bug. Check readiness before you edit middleware.
* Platform-layer edits may not hot-reload. Restart the dev server after those changes.
* Do not treat Management Dashboard extensions as storefront code. They are a different surface.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.emporix.io/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-storefront.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.