npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@amboras-dev/storefront-core

v2026.11.10

Published

The platform half of every Amboras storefront: cart, checkout, payments, auth, orders, subscriptions, catalogue data, analytics, consent, plugin slots, edge proxy and the Next config. Stores keep only design; they import this. ESM, React 19, Next 16.

Readme

@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.

| Store path | Core import | | --------------------------------- | ------------------------------------------------------------------------- | | hooks/<name>.ts | @amboras-dev/storefront-core/client/<name> | | lib/<path>.ts | @amboras-dev/storefront-core/lib/<path> | | types/index.ts | @amboras-dev/storefront-core/types | | components/ClientPluginSlot.tsx | @amboras-dev/storefront-core/shell/client-plugin-slot | | components/PluginSlot.tsx | createPluginSlot from @amboras-dev/storefront-core/server/plugin-slot | | proxy.ts | proxy from @amboras-dev/storefront-core/edge |

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

| Entry | What | "use client" | | -------------------------- | --------------------------------------------------------------------------------------------- | -------------- | | /client | CoreProvider (registry, payment UI, hook overrides), ClientPluginSlot, config | yes | | /client/<hook> | one hook file, same exports as the template's | per file | | /server | createPluginSlot, PluginSlot, getPluginConfigs, medusaFetch, getStoreConfig, config | no | | /lib/<path> | logic modules (checkout, cart, payment providers, analytics, consent…) | per file | | /edge | proxy, proxyConfig | no | | /next-config | withAmborasCore, resolveAmborasImageHosts | no | | /config | configureCore, getCoreConfig | no | | /types, /types/plugins | shared types, slot types | no |

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.