2.3

When a platform returned an occasional 503 or dropped a connection, whoever was mid-request got a failed cart or a failed checkout.

Integration API methods take a new retry config per integration in middleware.config.ts. Use retry: true for two retries with randomized exponential backoff, or set your own retries, retryCondition, and retryDelay. It fires on 502, 503, 504, 408, and 429 and on normalized network failures such as ETIMEDOUT and ECONNRESET. It's off by default.

When a call failed, the per-request error log reduced its cause to a name and a message, so you couldn't see what actually went wrong.

The GCP structured logger writes the whole cause chain of a normalized error. Logs also carry the data and cause fields of AppError subclasses such as ValidationError and HttpError. Redaction, circular-reference safety, and size bounds still apply, and what the error handler returns to API clients doesn't change.

The config switcher bootstraps each configured store as its own instance. Each store gets its own init() and extendApp(), and its configuration is merged correctly.

integrationConfigSchema accepts any object, not only {}. It no longer rejects the configuration the config switcher injects, so middleware bootstrap no longer breaks.

Custom fields on SfOrderListItem have correct types.

TypeScript resolves the InferAddCustomFields type faster.

The pako compression library is lazy-loaded. Clients that never use compression no longer bundle it.

When a circuit breaker was open, the request it blocked failed with TypeError: Cannot read properties of undefined (reading 'errorBoundary') instead of its real error. So every tripped breaker looked the same in your logs.

A request blocked by an open circuit breaker returns its proper error response. The error handler in @alokai/connect no longer throws while it builds that response.

A vulnerability in what the middleware could write to your logs has been identified and fixed.

The fix is inside the middleware and needs no change to your code.

A vulnerability in how the middleware sent error responses has been identified and fixed.

The middleware sends 404 and 405 responses, and errors thrown out of an endpoint, as text/plain with X-Content-Type-Options: nosniff instead of text/html. Status codes and bodies stay the same.

Only AppError subclasses had their cause chain serialized, so a plain Error that carried the real reason logged without it.

The GCP structured logger serializes the full cause chain of any error that carries one. The serialization itself doesn't change. It stays circular-safe, redacts secrets, and stays bounded in depth and size.

installConsoleBridge(logger, options?) from @alokai/connect/logger is an opt-in helper that routes raw console.error and console.warn output through the Alokai logger. Both storefront integrations use it. It renders nested errors with their stack, strips ANSI codes, and keeps non-error arguments as details metadata. Lines that are already structured pass straight through, and if the bridge fails, output falls back to the native console.

The metadata option is merged into every entry. The call returns a handle with uninstall(). The helper uses no Node built-ins, so the logger stays browser-safe.

createStorefrontLogger(options?) builds the standard GCP-structured logger that both storefront packages use, tagged alokai.context: "storefront". withStorefrontScope(logger, scope) wraps such a logger so every entry carries per-log detail under alokai.scope. The detail goes only there, because the rest of the reserved alokai namespace stays protected.

The logger in @alokai/connect skips empty and whitespace-only string messages, such as logger.info("") or logger.error(" "), instead of writing an entry with no message. This applies to every consumer: middleware, storefront, and SDK.

Every store carried its own copy of an image loader, and each copy had the same two bugs.

@vue-storefront/next adds a createImageOptimizer factory that returns the Next.js image loader and the proxy route's GET handler. @vue-storefront/nuxt does the same through an alokai.imageOptimizer.hosts config entry. URLs on a configured media host are rewritten so a CDN in front of the storefront can transform them. You can configure several hosts, use a sapcc URL variant, and override settings per host.

createStorefrontEvents from @vue-storefront/next/client builds a typed client-side pub/sub from your own event map. It returns bound emitStorefrontEvent, subscribeStorefrontEvent, useStorefrontEvent, and StorefrontEventEmitter helpers. An inline handler passed to useStorefrontEvent doesn't re-subscribe on every render. StorefrontEventEmitter emits once per mount, so it's safe under Strict Mode on server-rendered pages.

getCurrentPath from @vue-storefront/next/server returns the current request path, pathname, and search inside an App Router Server Component. It reads them from the headers that createAlokaiMiddleware sets. It has its own server entry because it imports next/headers, which client and Pages Router bundles can't use.

Each extension point is a file under config/. When no module is installed, it falls back to native behavior.

config/listing-data-source.ts defaults to the unified searchProducts. config/search-results-slot.tsx defaults to popular searches. The default submit in config/search-form.tsx navigates to the search page.

config/module-providers.tsx holds providers that modules contribute, and config/module-root-components.tsx holds their always-mounted root components. config/facet-type-config.tsx holds facet renderers. The storefront event bus and a client-hydration provider come with them.

The search modal renders a separate search-form above the search results slot. The form owns submit and reports the live query through onQueryChange. The Compass assistant overlays this form instead of the base search.tsx component.

env('NEXT_PUBLIC_*') returns the right value during the first client render and inside initial useEffect calls. Before, runtime env vars read undefined until shortly after hydration.

AlokaiInstrumentation captures the initial page view and any navigation during page load. Before, page-view tracking started after hydration, so the first page view and any router navigation before it were never reported.

The product card keys wantedQuantities by SKU instead of cart line item ID. Items missing from the updated cart after the add-line-items call are reported as errors, not successes.

The products hook guards against an undefined lineItems and shows unhandled mutateAsync rejections as error notifications. The local-storage hook resets to its initial value when the item is removed or storage is cleared, instead of keeping a stale value.

The module no longer ships cart-page-providers.tsx and order-details-page-providers.tsx, and no longer copies them into app/[locale]/(default)/my-account/my-orders/[id]/components/. A project generated on this release hands every translation namespace to NextIntlClientProvider in its root app/[locale]/layout.tsx, so page-scoped providers aren't needed.

A security issue in the image optimizer proxy route was found and fixed. The route no longer follows redirects from an upstream media host. It returns an upstream 3xx as a 502 instead.

@storefront-ui/react is now 4.0.1, @storefront-ui/vue is 3.1.2, and @storefront-ui/nuxt is 3.3.1.

Normalized CMS components carry their component type as a CSS class in the uniqueClass field. A new createComponentTypeClass utility builds the class.

Mock CMS images were relative paths that depended on a Cloudinary loader in the storefront, so the mock content worked with only that one image pipeline.

Mock CMS content references demo images as absolute URLs served by the image host. The consts.CLOUDINARY_FOLDER_NAME export is renamed to consts.CMS_MOCK_IMAGE_BASE_URL. It now holds a full base URL, not a folder name.

Next.js prints SSR and RSC errors as multi-line dumps that GCP, Datadog, and Elasticsearch can't parse.

@vue-storefront/next adds an @vue-storefront/next/instrumentation export with a ready-to-use register hook that routes the raw console.error/warn output of Next.js through the Alokai logger. store build in @alokai/cli wires the hook for you. It changes only the composed .out output, never your source.

Nitro printed raw server console output, so a Nuxt storefront's logs didn't match the Next.js and middleware format.

The Nuxt module registers a Nitro server plugin that routes Nitro's raw server console output through the Alokai logger, unhandled SSR errors included. Nested errors render with their stack, and ANSI color codes and blank spacing lines are removed.

Nuxt logged unexpected errors without a stack trace by default, unlike the middleware and Next.js.

The logger option includeStackTrace defaults to true instead of false. 4xx client errors still never carry a trace.

Coding agents didn't know about Alokai, so the code they wrote drifted toward generic Next.js patterns instead of what the framework enforces.

@alokai/ai-toolkit ships Alokai skills, agent-driven review workflows, and Alokai reference docs tagged for AI agents. alokai ai sync in @alokai/cli symlinks them into the agents installed on your machine and rewrites a managed block in your AGENTS.md. The toolkit is versioned independently of the release.

The packages use JSON ESM imports with with { type: "json" }. The previous floor accepted Node 20 releases that don't support them.

Every package published in this release declares engines.node as ^20.10.0 || >=22.14.0.

The pinned versions of defu, glob, h3, lodash-es, minimatch, path-to-regexp, rollup, and diff move to patched releases in the same major version. The patched releases fix known security vulnerabilities. The public API and runtime behavior don't change.

The updated sanitize-html mitigates CVE-2026-44990.

uuid moves to ^11.1.1, which patches CVE-2026-41907.

Every package that depends on axios asks for ^1.15.2.

@alokai/cli-plugin-review registers an ai review command. It reviews a pull request, a commit, a branch diff, the working tree, or a directory, with the code-reviewer skill from your repository.

The command posts a sticky summary comment and inline findings. It posts only findings that are new. Today it posts to GitHub.

The same plugin adds an ai fix command that applies fixes for the findings a review posted. It fixes one finding from a comment URL, every open finding on a thread, or, with --pr, every open finding on a pull request.

The command edits the files, commits, pushes to the head branch, and replies with what changed. With --dry-run, it stops at the working tree. On GitHub, the pull request author can trigger it by commenting /fix.

In a large diff, the files that look most important no longer crowd out findings in the rest. Directory reviews anchor inline findings to the correct line. The maintainability checks apply to a project of any structure, not only a monorepo packages/ layout. Inline comments render their fix snippets correctly on any git provider.

integration generate accepts an --answers flag. It takes a JSON object of the template's prompt answers, keyed by prompt name, and skips the interactive prompts.

The --skip-version-check flag lets generation continue when the project's Alokai version isn't in the compatibility matrix. The command prints the mismatch warning instead of aborting.

Integrations generated from the openapi and graphql templates build against the current Alokai version. Before, a freshly generated one failed to compile and needed manual fixes. The openapi template's fetch HTTP-client option also builds with no manual setup.

The graphql template reads the integration's baseUrl from an <INTEGRATION>_BASE_URL environment variable. It no longer uses a hardcoded placeholder.

The sdk-proxy template ships a working getSample endpoint that returns sample data. Before, it shipped a placeholder that didn't work.

When the Alokai version API is temporarily unavailable, the CLI version check prints a warning and skips. It no longer crashes.

The wrapWith JSX visitor no longer adds stray parentheses when it wraps an element inside a parenthesized return statement.

The generated workflow passed any of CLI_PROJECT_NAME, CLI_FRAMEWORK, or CLI_CLOUD_REGION you left undefined as an empty string. That empty string overrode alokai.config.json, so your deploys ran with a blank project name, framework, or region.

store deploy treats an empty CLI_PROJECT_NAME, CLI_FRAMEWORK, or CLI_CLOUD_REGION as unset, so alokai.config.json supplies the value.

Every generated project had @vsf-enterprise/algolia-api and @vsf-enterprise/magento-types in its middleware dependencies, even when it didn't use Algolia or Magento.

Project generation removes both packages from a project that doesn't use them.

If you built deployments with npm or pnpm, the image crashed on startup with Cannot find module 'react-dom/server.browser', because the production install removed react-dom from it. Yarn projects weren't affected.

The deploy prepare step writes a trimmed package.json with only the dependencies a standalone Next.js app needs at runtime. That list now includes react-dom alongside next and react.

outputSchema in a structured-output action accepts a dynamic definition { schema, cache? }, the same shape tools use. The schema resolves on each invocation from the request context and the workflow payload. When you supply cache.key, it's cached in Redis the same way tool schemas are. Static z.ZodType schemas work unchanged.

retryFailedToolCalls on an action config routes failed tool calls back to the LLM for a retry even when shouldReactToToolsResponses is off.

Tool callbacks can return { toolResponse, instructions }. The LLM gets instructions as a system message that tells it how to interpret the tool result.

The tool shipped with the module, so every installation carried it whether or not the assistant used it.

The module no longer ships the previewProducts tool file or the CATALOG toolkit entry that registered it.

Each action config carries a model and a legacyModel. model is the dated codename forwarded to the proxy in no-credentials mode. legacyModel is the concrete model used in credentials-manager mode.

The default Compass configuration sets model and legacyModel for every workflow action, one pair per tier.

A configuration that still passes a bare tier keeps working in credentials-manager mode. There, heavy, medium, and light each resolve to their configured model, and any other name falls back to the light one. In no-credentials mode, model goes to the proxy verbatim.

The model option on defineAction is typed as string, not a literal union. Its TSDoc links to the Available Models docs page.

ALOKAI_COMPASS_NO_CREDENTIALS_MANAGER=true turns off the credentials manager. Compass then reads ALOKAI_COMPASS_API_KEY and ALOKAI_COMPASS_API_URL straight from the environment and sends model requests to that URL, so you can point it at any OpenAI-compatible gateway, the Alokai one included. If you set the flag without ALOKAI_COMPASS_API_URL, the server stops at startup with a clear error.

Adding the Compass module now adds a commented ALOKAI_COMPASS_API_URL line to .env.example, set to the Alokai gateway.

appendToCompactHistory adds entries to the compact history stored in localStorage. getContextMessages extracts the context entries from stored chat messages. fetchConfiguration fetches a configuration document by ID, and can target a specific version.

chatId is now optional on the storage helpers and falls back to a default.

invoke saves the earlier conversation together with the new messages and the assistant's response. Before, it overwrote the stored history with only the latest turn. The workflow hook passes the earlier conversation as messageHistory, and invoke sends it to the server only when compact history is off.

Compact history now stores context messages correctly when it saves the conversation.

The product-visit context message from ProductMessage carries only { name, sku }, not the whole product object.

In development, a tracing UI at /compass/devTools records the spans of each run: LLM calls, tool calls, and workflow nodes. It shows their timeline and parent/child tree, token usage including cached tokens, and the messages exchanged with the model. It also shows each workflow's compiled graph.

CompassProvider no longer overrides the root translation provider. Before, it blocked every translation namespace except AddToCartButton and Compass.

The assistant no longer forces the cart page into a render loop that kept isLoading true.

The Compass module's Next.js dependencies now require @frsource/autoresize-textarea ^2.0.196. Versions 2.0.192 through 2.0.195 shipped without their declaration file, so tsc --noEmit failed.

If you never set SAPCC_MEDIA_HOST, the Compass MCP server silently used a hardcoded Cloudinary URL as your media host.

The Compass MCP server no longer falls back to a Cloudinary URL when SAPCC_MEDIA_HOST is unset. Media URLs then come back without a host prefix.

A new ping method checks Redis connectivity. It returns true on PONG and false otherwise. When the check fails, it logs the connection error.

A vulnerability in how SAP Commerce credentials were handled has been identified and fixed. This part of the fix changes what your own code receives.

createProxyApi returns only { status, statusText, data, headers } from upstream SAP Commerce calls. Before, every apiClient.api.* method returned a wider response envelope.

A vulnerability in how SAP Commerce credentials were handled has been identified and fixed. This is the second part of that fix.

getLanguages, getCountries, and getTitles no longer attach the application bearer token. They default to TokenModes.NONE.

The SAP Commerce integration supports SAP Customer Data Cloud (SAP CDC).

Authentication no longer fails when a global proxy agent (global.GLOBAL_AGENT) is configured.

Token refresh no longer crashes when its request fails at the network level.

The return type of createProxyApi now includes the middleware context parameter in each method signature.

Facet value matching handles prefixed values, such as color-black and size-10, in both the facet list and the selected facets. When a product has no base options, its variant options are used instead.

The image normalizer prefers the superZoom format for gallery and primary images. When superZoom is missing, it falls back to zoom, then to product.

Refreshing or revoking a customer token with a missing or expired token cookie returns 401 Unauthorized. It no longer crashes with an internal server error.

This applies when Magento expires the customer token while the vsf-customer cookie is still there. An explicit login now clears the stale token and logs in again, instead of failing with "Customer is already logged in". getCustomer and getCart fall back to a logged-out or guest state instead of surfacing authorization errors.

LivePreview types the livePreviewUrl parameter of its onLiveEdit callback as optional. The handler now type-checks against the published Contentstack SDK signature, and the parameter is no longer an implicit any.

A page that fell back to the storefront default looked different from a page with CMS content, because only the CMS branch rendered the layout.

connectCmsPage wraps each page it handles in the default layout: navbar, main content area, and footer. A fallback page now looks the same as a CMS-managed one.

When you set componentCache.ttl, resolved components are cached in Redis, with an in-memory fallback. This covers components resolved from the SAP Commerce API and from resolveUnknownComponents callbacks.

Page resolution collects the errors from all of its lookup steps and logs them once, after the last step runs.

A container component whose reference field contains its own UID no longer crashes page normalization with a stack overflow. SAP Commerce returns one, for example, for an empty tab-paragraph container. The self-reference is dropped, and the field becomes an empty array if no other UIDs remain.

When no path is given, the getPage error message includes searchParams. A 404 no longer writes a redundant log line.

The SmartEdit paragraph component has its heading hierarchy from h1 to h6, responsive typography, and list styles back.

The Coveo proxy forwards only accept, authorization, content-type, and a rewritten host. It no longer passes on every incoming header. The incoming content-length and transfer-encoding described the original body, not the payload sent upstream, so requests hung and eventually exhausted middleware memory.

The generated workflows use v5 of actions/checkout, actions/setup-node, and actions/cache. This clears the Node 20 deprecation warnings.

The generate-gtm action can append a suffix to hardcoded store IDs. The workflows it generates set environment: ${{ matrix.store_id }}, so each store can have its own GitHub environment with its own variables and secrets.

The workflow read the Console API URL from a secret with a hardcoded fallback, though the URL isn't secret and fits an ordinary repository variable.

The generated .github/workflows/continuous-delivery.yml reads CONSOLE_API_URL from the vars.CONSOLE_API_URL repository variable. It no longer reads a secret or falls back to a hardcoded URL.