@amboras-dev/ storefront-core (英语)

每个安博拉斯商店前台的一半:推车、退货逻辑、付款、代理、订单, 订阅、目录数据、分析、同意、插件插槽、边缘代理和下一个 相会. 一个商店只保留它的设计。 这里的每件东西都曾被复制到 ~73k 商店在分叉时间重置,然后从那里漂出.

一个版本包是指作为版本起伏的固定船,分期推出,而不是文件 重写每个部署.

此发行( 2026.11.0) 仅会移动逻辑 . 科雷自己的UI(/ui, shopify 式检查) 进入第三阶段。 在此之前,商店通过自己的支付方式(见 paymentUi) (中文(简体) ).

店里怎么用着的

1. 配置一次: lib/amboras.ts

下一条内线 process.env.NEXT_PUBLIC_* 只有应用源,所以商店读它们和手 改为核心:

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在呼叫时会读取相貌懒散,所以模块顺序并不重要.

在制作中,缺失的美杜莎URL抛出 MissingMedusaUrlError 在第一个配置读取. 只有开发和测试才回到 http://localhost:9000。 。 。 .

2. Shims保留每一个导入路径

每个文件核心作为一行再导出保留在商店中,所以现有的设计文件(AI-respected) 包括) 继续编译:

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

core-manifest.json 列出每一个shim路径及其目标。 管弦乐手构建 AI 锁列表 从它和它的版本地板检查 确保每个shim存在.

3. 登记和付款

核心从不进口商店产生的 app/_generated/plugin-registry 或它的取出组件.

// 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>

付款插件添加适配器 registerPaymentProvider(config) 从 @amboras-dev/storefront-core/lib/payment-providers/registry。 。 。 .

压住钩子

在 shim 旁边的本地导出 export * 只改变商店的进口。 核心的钩子 直接导入对方,从而改变钩芯本身的调用,将其传递给 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>

可超过 : useCart, (中文(简体) ), useRegion, (中文(简体) ), useAuth, (中文(简体) ), useListingParams, (中文(简体) ), usePaymentProviders, (中文(简体) ), usePaymentMethodsConfig, (中文(简体) ), useStripeErrorCopy, (中文(简体) ), useExpressCheckout。所有其他的钩子都叫 只能通过商店代码, 所以它的shim已经是覆盖. /lib 函数不能压倒一切。 一个 覆盖是钩: 呼叫 base 在每一个变形或没有. overrides 第一次读取 渲染:保持其稳定(模块范围),因为以后增加或去除一个会改变钩子顺序.

4. 下个配置和尾风

// 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 })

保持这个形状. 管弦乐器(e2b预览, check_build)和 Shopify 复制器补丁 next.config.mjs 以白银盟誓 const nextConfig = {这是 地点 allowedDevOrigins (审查)和 distDir: process.env.NEXT_DIST_DIR (单位:千美元)check_build是因为 被注入。 将商店的选项保存在该字面对象中, 只应用核心 在导出线上. const nextConfig = withAmborasCore({...}) 匹配所有模式, 所以 预览和 check_build 悄悄地失去了他们的补丁. withAmborasCore 扩展对象,所以 注入的键存活下来. test/core/next-config-patchers.test.ts 管理管弦乐团和 克隆人的真实模式 与这个片段相对应 用顶级解析主机 await从来没有 导出一个同步函数.

withAmborasCore 将核心添加到 transpilePackages针头 turbopack.root,并构建 images.remotePatterns 从确切的主机。 主机是平台数据,而不是代码. resolveAmborasImageHosts() 在配置负载时,从第一个答案源读取一次:

1. 平台: GET <platform>/api/v1/public/storefront/image-hosts?store=<NEXT_PUBLIC_STORE_ID>, (中文(简体) ), 与2s超时. <platform> 实值 AMBORAS_PLATFORM_API_URL,其他来源于美杜莎宿主 (单位:千美元)api[-env].amboras.com 变成 core[-env].amboras.com页:1 https://core.amboras.com· ;
2. AMBORAS_IMAGE_HOSTS: JSON 阵列或精确主机名的逗号列表;
3. 烤起的倒车 AMBORAS_FALLBACK_IMAGE_HOSTS (模板的13个主机).

确切的东道主是 NEXT_PUBLIC_MEDUSA_BACKEND_URL 总是添加,本地端的主机是 不在Vercel上时添加. 和模板的算法一样 amboras:image-hosts-reader 块。 无 imageHosts, (中文(简体) ), withAmborasCore 用途 AMBORAS_IMAGE_HOSTS 或倒置列表(它不调用网络). 包含任何主机名 * 抛出,不管它是 ** 或者说 *.cloudfront.net,因为通配符 /_next/image 打开 代理服务器.

释放命令 : 管弦乐团的影像主机端点必须先活在制作中,然后才能出现 生产店采用2026.11.2. 没有它,一个生产建筑 使用倒计时列表。 以1%计 产品图像生产样本,约4%在商家主机上显示清单没有 包括,这样他们就会失败 /_next/image。 。 。 .

添加 @source "../node_modules/@amboras-dev/storefront-core"; 改为 app/globals.css (见 presets/tailwind.md) (中文(简体) ).

5. 代理匹配者

下一个读 config 从 proxy.ts 静地,所以它不能来自一个包。 店里有个 文字副本 proxyConfig 从 @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 当复制件与安装的核心匹配器不同时失败 .

6. 特性开关:未知开关未关闭

useStoreConfig() (客户)和 getStoreConfig() (服务器)读作"美杜莎" GET /store/config每一个 特性旗为 true, (中文(简体) ), false 或者说 null,以及 null 意为未知. 一切不明时 在老美杜莎、503和网络出错上加载,在读取器失败的旗帜上加载 美杜莎就是个 null 我也一样。 门 UI 与 isFeatureOff(feature)美杜莎说 false。从未读取 features.x 作为布尔,因为 null 变幻无常,会隐藏一个特征 没有人关闭. checkout_settings 财务报告和审定财务报表 brand 为: null 当未知. useCheckoutSettings 然后掉头 /store/checkout-settings。 。 。 .

7. 建造大门

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

入境点

dist/ 实值 tsc 输出, 文件: 每 "use client" 留在档案里.

版本数

卡尔维尔 YYYY.M.N (单位:千美元)npm run version:next) (中文(简体) ). 插件声明 peerDependencies['@amboras-dev/storefront-core']: '>=2026.11.0'。过期名称暂出 至少两个未成年人. api/*.api.md 是一个公共表面 /client, (中文(简体) ), /server 财务报告和审定财务报表 /next-config; CI 不更新报告而更改时失败 . api/shim-exports.json 列出后面的导出名称 /client/* 财务报告和审定财务报表 /lib/*; CI 删除或重命名时失败 .

见 捐款额 发展与发行.