Skip to main content

@acromedia/gesso-shopware

Shopware 6 commerce plugin for Gesso. It implements the @acromedia/gesso-commerce hook surface (useCatalog, useProduct, useProductSearch, useFacet, useCart, useCustomer, useCheckout, useOrders, useAuth) on top of Shopware's REST Store API (/store-api).

Scaffold status. The read paths — useCatalog, useProduct, useProductSearch, useFacet — are implemented. The write paths (useCart, useCustomer, useCheckout, useOrders, useAuth) are present as typed stubs and land in follow-up tickets.

Installation​

pnpm add @acromedia/gesso-shopware

@acromedia/gesso-commerce is a peer dependency.

Configuration​

The plugin reads its connection settings from gesso.config.json (generated from .env by the plugin CLI). Two values are required:

Config keyEnv varNotes
shopwareStorefrontUrlNEXT_PUBLIC_SHOPWARE_STOREFRONT_URLBase host of the store, e.g. https://your-store.shopware.cloud.
shopwareAccessKeyNEXT_PUBLIC_SHOPWARE_ACCESS_KEYThe sales-channel sw-access-key. Sent on every Store API call.

Optional:

Config keyNotes
shopwareCurrencyCodeISO currency code used to label prices (Shopware returns amounts only). EUR.
shopwareLanguageIdSent as sw-language-id when set.
shopwareCurrencyIdSent as sw-currency-id when set.
shopwareRootCategoryIdCategory used by useFacet to derive global aggregations.

The Store API access key is public by design (it scopes requests to a sales channel) and is therefore exposed to the browser via the NEXT_PUBLIC_ prefix, the same way Shopify's storefront token is handled.

Running the plugin CLI (gesso-shopware config, or the host app's gesso config) reads the NEXT_PUBLIC_SHOPWARE_* env vars and writes the corresponding shopwareStorefrontUrl / shopwareAccessKey keys into gesso.config.json — the file the Store API client actually reads at runtime. .env stays the single source of truth.

Getting the sw-access-key​

In the Shopware Administration: Sales Channels → [your Headless channel] → API access → API access key.

Transport client​

This plugin talks to the Store API through the official @shopware/api-client SDK, pinned to an exact version (it has a fast release cadence), wrapped in a thin StoreApiClient (src/rest.ts). This mirrors how gesso-shopify wraps the official @shopify/graphql-client.

  • createAPIClient is configured with accessToken (sent as the sales-channel sw-access-key) and an initial contextToken seeded from the ContextTokenStore (see below).
  • Hooks call the SDK's fully-typed invoke('<operationId> <method> /path', { pathParams, body }), which returns { data, status } and throws ApiClientError on non-2xx responses.
  • The rotated sw-context-token is captured through the SDK's onContextChanged hook and written back to the store.
  • Store API request/response types come from the bundled @shopware/api-client/store-api-types, so generating pinned types with @shopware/api-gen is optional and not run in this scaffold.

Context token​

Stateful Store API endpoints (cart, customer, checkout) require an sw-context-token, which the Store API rotates on login/register. The SDK captures the token the server returns (via its onContextChanged hook) and replays it on the next request; where that token is stored is pluggable through a ContextTokenStore (src/Context):

  • Browser (default): the token lives in the gesso-sw-context cookie, mirroring how BigCommerce round-trips its cart cookie.
  • Server (default): a no-op store, so SSR/RSC reads are anonymous. A module-level token would leak one visitor's session into another's request, so server persistence is opt-in.
  • SSR with a session: inject a request-scoped store via config.contextTokenStore (e.g. backed by Next's cookies()) when constructing the client.

Development​

pnpm --filter @acromedia/gesso-shopware type-check
pnpm --filter @acromedia/gesso-shopware lint
pnpm --filter @acromedia/gesso-shopware build
pnpm --filter @acromedia/gesso-shopware test   # Vitest suite (Store API mocked with MSW)

The suite is Vitest + MSW. There is also an opt-in live check that hits GET /store-api/context against a real store — set LIVE_TESTS=true plus NEXT_PUBLIC_SHOPWARE_STOREFRONT_URL / NEXT_PUBLIC_SHOPWARE_ACCESS_KEY in your environment. It is skipped by default.

References​