@amboras-dev/storefront-core

The platform half of every Amboras storefront: cart, checkout logic, payments, auth, orders, subscriptions, catalogue data, analytics, consent, plugin slots, the edge proxy and the Next config. A store keeps only its design. Everything here used to be copied into each of the ~73k store repos at fork time, and drifted from there.

One versioned package means a fix ships as a version bump, rolled out in stages, instead of a file rewrite on every deploy.

This release (2026.11.0) moves logic only. Core's own UI (/ui, the Shopify-style checkout) comes in phase 3. Until then the store passes its own payment surfaces in (see paymentUi).

How a store uses it

1. Configure once: lib/amboras.ts

Next inlines process.env.NEXT_PUBLIC_* only in app source, so the store reads them and hands them to core:

import { configureCore } from '@amboras-dev/storefront-core/config'

configureCore({
  medusaUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL,
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
  storeId: process.env.NEXT_PUBLIC_STORE_ID,
  analyticsEndpoint: process.env.NEXT_PUBLIC_ANALYTICS_ENDPOINT,
  analyticsIngestUrl: process.env.NEXT_PUBLIC_ANALYTICS_INGEST_URL,
  analyticsKey: process.env.NEXT_PUBLIC_ANALYTICS_KEY,
  googleMapsApiKey: process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY,
})

Core reads the config lazily, at call time, so module order does not matter.

In production, a missing Medusa URL throws MissingMedusaUrlError on the first config read. Only development and tests fall back to http://localhost:9000.

2. Shims keep every import path

Each file core owns stays in the store as a one-line re-export, so existing design files (AI-restyled ones included) keep compiling unchanged:

// hooks/use-cart.ts
export * from '@amboras-dev/storefront-core/client/use-cart'

core-manifest.json lists every shim path and its target. The orchestrator builds the AI lock list from it and its version-floor check makes sure each shim exists.

3. The registry and payment UI are injected

Core never imports the store's generated app/_generated/plugin-registry or its checkout components.

// components/PluginSlot.tsx (server)
import { PLUGIN_REGISTRY } from '@/app/_generated/plugin-registry'
import { createPluginSlot } from '@amboras-dev/storefront-core/server/plugin-slot'
export const PluginSlot = createPluginSlot(PLUGIN_REGISTRY)
export default PluginSlot

// app/providers.tsx (client)
import { CoreProvider } from '@amboras-dev/storefront-core/client'
import { PLUGIN_REGISTRY } from '@/app/_generated/plugin-registry'
import { StripePaymentForm } from '@/components/checkout/stripe-payment-form'
// … SavedMethodSelector, SaveMethodConsent, PayPalSmartButtons
;<CoreProvider
  registry={PLUGIN_REGISTRY}
  pluginConfigs={pluginConfigs}
  paymentUi={{ StripePaymentForm, SavedMethodSelector, SaveMethodConsent, PayPalSmartButtons }}
>
  {children}
</CoreProvider>

Payment plugins add an adapter with registerPaymentProvider(config) from @amboras-dev/storefront-core/lib/payment-providers/registry.

Overriding a hook

A local export next to a shim's export * only changes the store's own imports. Core's hooks import each other directly, so to change a hook core itself calls, pass it to CoreProvider:

// app/providers.tsx. Module scope: overrides are read once.
const overrides: CoreHookOverrides = {
  useCart: (base) => {
    const cart = base()
    return { ...cart /* … */ }
  },
}

;<CoreProvider registry={PLUGIN_REGISTRY} overrides={overrides}>
  {children}
</CoreProvider>

Overridable: useCart, useRegion, useAuth, useListingParams, usePaymentProviders, usePaymentMethodsConfig, useStripeErrorCopy, useExpressCheckout. Every other hook is called only by store code, so its shim is already the override. /lib functions are not overridable. An override is a hook: call base on every render or on none. overrides is read once, on the first render: keep it stable (module scope), since adding or removing one later would change hook order.

4. Next config and Tailwind

// next.config.mjs
import { fileURLToPath } from 'node:url'
import { dirname } from 'node:path'
import { resolveAmborasImageHosts, withAmborasCore } from '@amboras-dev/storefront-core/next-config'

const __dirname = dirname(fileURLToPath(import.meta.url))
const imageHosts = await resolveAmborasImageHosts()

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* store options */
}

export default withAmborasCore(nextConfig, { root: __dirname, imageHosts })

Keep that shape. The orchestrator (e2b previews, check_build) and the Shopify cloner patch next.config.mjs by regex, and all of them anchor on the literal const nextConfig = {. That is where allowedDevOrigins (previews) and distDir: process.env.NEXT_DIST_DIR (check_build's isolated build) are injected. Keep the store's options in that literal object and apply core only on the export line. const nextConfig = withAmborasCore({...}) matches none of the patterns, so previews and check_build silently lose their patches. withAmborasCore spreads the object, so the injected keys survive. test/core/next-config-patchers.test.ts runs the orchestrator's and the cloner's real patterns against this snippet. Resolve the hosts with a top-level await; never export an async function.

withAmborasCore adds core to transpilePackages, pins turbopack.root, and builds images.remotePatterns from exact hosts only. The hosts are platform data, not code. resolveAmborasImageHosts() reads them once, at config load, from the first source that answers:

1. the platform: GET <platform>/api/v1/public/storefront/image-hosts?store=<NEXT_PUBLIC_STORE_ID>, with a 2s timeout. <platform> is AMBORAS_PLATFORM_API_URL, else derived from the Medusa host (api[-env].amboras.com becomes core[-env].amboras.com), else https://core.amboras.com;
2. AMBORAS_IMAGE_HOSTS: a JSON array or a comma list of exact host names;
3. the baked fallback AMBORAS_FALLBACK_IMAGE_HOSTS (the template's 13 hosts).

The exact host of NEXT_PUBLIC_MEDUSA_BACKEND_URL is always added, and the local-dev hosts are added when not on Vercel. It is the same algorithm as the template's amboras:image-hosts-reader block. Without imageHosts, withAmborasCore uses AMBORAS_IMAGE_HOSTS or the fallback list (it does not call the network). Any hostname containing * throws, whether it is ** or *.cloudfront.net, because a wildcard makes /_next/image an open proxy.

Release order: the orchestrator's image-hosts endpoint must be live in production before any production store adopts 2026.11.2. Without it a production build uses the fallback list. In a 1% production sample of product images, about 4% were on merchant hosts that the list does not include, so they would fail in /_next/image.

Add @source "../node_modules/@amboras-dev/storefront-core"; to app/globals.css (see presets/tailwind.md).

5. The proxy matcher

Next reads config from proxy.ts statically, so it cannot come from a package. The store keeps a literal copy of proxyConfig from @amboras-dev/storefront-core/edge:

export { proxy } from '@amboras-dev/storefront-core/edge'
export const config = {
  matcher: [
    /* copy of proxyConfig.matcher */
  ],
}

amboras-check proxy-matcher fails when the copy differs from the installed core's matcher.

6. Feature switches: unknown is not off

useStoreConfig() (client) and getStoreConfig() (server) read Medusa's GET /store/config. Each feature flag is true, false or null, and null means unknown. Everything is unknown while loading, on an older Medusa, on a 503 and on a network error, and a flag whose reader failed in Medusa is null too. Gate UI with isFeatureOff(feature), which is true only when Medusa said false. Never read features.x as a boolean, because null is falsy and would hide a feature nobody turned off. checkout_settings and brand are null when unknown. useCheckoutSettings then falls back to /store/checkout-settings.

7. Build gates

npx amboras-check            # plugin slots, store quirks, redirect boundaries, consent scroll, proxy matcher
npx amboras-check slots      # one gate

Entry points

dist/ is tsc output, file for file: every "use client" stays on the file that had it.

Versions

CalVer YYYY.M.N (npm run version:next). Plugins declare peerDependencies['@amboras-dev/storefront-core']: '>=2026.11.0'. Deprecated names stay exported for at least two minors. api/*.api.md is the public surface of /client, /server and /next-config; CI fails when it changes without the report being updated. api/shim-exports.json lists the export names behind /client/* and /lib/*; CI fails when one is removed or renamed.

See CONTRIBUTING.md for development and release.