demo store

商务层演示商店

该演示商店是一个完全静态的电子商务解决方案（具有 SSR 功能），由 Commerce Layer 提供支持。该商店功能齐全、可全面运营，无需第三方服务。您可以轻松地通过不同级别的定制来定制您自己的产品。继续阅读以了解更多信息。

Demo Store 项目由两个存储库组成，这一个是 GitHub 模板。

什么是商务层？

Commerce Layer 是一个多市场商务 API 和订单管理系统，可让您轻松地将全球购物功能添加到任何网站、移动应用程序、聊天机器人、可穿戴设备、语音或物联网设备。使用您已经掌握和喜爱的最佳工具来构建您的堆栈。通过超快、企业级且安全的 API，让任何体验都可以随时随地购买。

目录

• 特征
• 它是如何运作的
• 入门
• 定制化
• 部署
• 需要帮助吗？
• 故障排除
• 执照

特征

我们决定构建演示商店，删除通常用于创建全面的电子商务网站体验的所有第三方服务（CMS、搜索、PIM 等）。

与内容相关的所有内容都存储为 JSON 文件。要构建您自己的演示商店，您需要手动或通过脚本创建这些文件。

演示商店附带：

• 内置搜索引擎，具有由 fusion.js 提供支持的分面搜索
• 具有分类法和分类单元的完整产品目录管理
• 单一产品变体管理
• 多语言功能使国际销售变得更容易
• Commerce Layer API 提供的一整套广泛的功能（多种货币价目表、支持多个库存地点和履行策略的库存模型、特定于市场的支付网关、交付选项和承运人帐户等）

与 Commerce Layer 的集成是通过利用我们的一些开源开发工具来实现的，具体来说：

• JS Auth 库
• JavaScript SDK
• React 组件
• 托管购物车
• 托管结帐

它是如何运作的

演示商店项目包含两个存储库，您可以根据需要添加的自定义量利用它们来构建自己的商店：

• demo-store

  这是一个GitHub 模板，使用下面提到的demo-store-core作为 git 子模块。如果您对 Commerce Layer 演示商店的功能和外观感到满意，我们建议您遵循此路径。您不必关心整个源代码，您可以自由地只关注您的数据和内容。最重要的是，您只需运行以下命令即可获得几乎没有风险的免费更新：

  git submodule update --remote
  npm install

• demo-store-core

  该存储库包含源代码。如果您需要完全自定义您的商店（行为、UI、UX 等），您只需分叉此存储库并创建您自己的商店。这也是贡献的方式。

  ️请注意，如果您遵循此路径并开始与原始源代码偏离太多，则存在丢失所有未来更新或无法复制它们的风险。

入门

如果您没有 Commerce Layer 的经验，您可以首先创建一个帐户（免费！）并按照入门教程进行操作。

重要的

请注意，要建立演示商店，您需要一个正确配置的组织，其中至少有几种产品和一个市场。

如果您喜欢从头开始，可以创建一个新组织并使用以下命令来配置 Commerce Layer 的类似演示商店的项目。

设置您的组织

创建组织后，您需要创建两个 API 客户端：销售渠道和集成。

如果尚未安装，请安装 Commerce Layer CLI 及其两个插件：播种器插件和导入插件：

npm install -g @commercelayer/cli

commercelayer plugins:install seeder
commercelayer plugins:install imports

现在您可以从 CLI 登录到集成 API 客户端：

commercelayer applications:login 
  --clientId Oy5F2TbPYhOZsxy1tQd9ZVZ... 
  --clientSecret 1ZHNJUgn_1lh1mel06gGDqa... 
  --organization my-awesome-organization 
  --alias cli-admin

建立你的商店

一旦您的组织建立完毕，要建立您的商店，您需要遵循一些简单的步骤......让我们开始吧！

1. 创建一个新的存储库

无论您选择哪种路径，首先，您需要为您的商店创建一个新的存储库：

• 如果您决定保留demo-store模板，您只需从 GitHub 上的存储库主页单击“使用此模板” ，然后运行：

  git clone < your-repository-url > my-new-project
  cd my-new-project
  git submodule update --init
  npm install
  
  cp ./demo-store-core/packages/website/.env.sample.submodule .env.local
  
  cp -r ./demo-store-core/packages/website/data/json ./data/json

• 如果您决定分叉demo-store-core存储库，您可以运行以下命令：

  git clone < your-repository-url > my-new-project
  cd my-new-project
  npm install
  
  cp ./packages/website/.env.sample ./packages/website/.env.local

2.设置环境变量

编辑.env.local并填写所有缺少的信息：

 # this is the 'sales channel' client id
NEXT_PUBLIC_CL_CLIENT_ID =er34TWFcd24RFI8KJ52Ws6q...

3. 播种数据

此步骤是可选的。如果您的 Commerce Layer 帐户已正确配置组织，则可以跳过它。

以下脚本将为您的组织填充使用 Commerce Layer 构建多市场电子商务所需的所有资源（我们用于演示商店的资源）。

npm run seeder:seed -ws --if-present

如果上面的命令执行时没有错误，请跳到步骤 4。否则，您仍然可以通过运行以下命令，使用 CLI 使用示例数据为您的组织播种：

commercelayer seeder:seed -b custom -n demo_store_full -u ./demo-store-core/packages/setup/

4. 选择您要销售的国家/地区

json/countries.json文件包含可用于电子商务的国家/地区列表。您可以使用您喜欢的编辑器更改它。只需确保将"market": xxx的所有结果替换为您组织的相关市场即可。您可以从 Commerce Layer 管理仪表板或运行以下命令获取市场列表：

npm run markets -ws --if-present

5. 看看实际情况

npm run dev

# http://localhost:3000/ 

管理更新

您始终可以在其main分支中找到demo-store-core的最新代码。

要将您的演示商店更新为最新更改，您只需运行：

git submodule update --remote
npm install

有时可能会发生新的主要版本包含重大更改的情况。在这种情况下，通过更新到最新版本，您的演示商店可能会停止工作，您需要按照发行说明手动解决所有问题。

如果您愿意，您可以在新版本发布后立即收到 GitHub 通知。

定制化

当您使用我们的演示商店模板时，您可以自定义三个主要元素：内容数据、区域设置和配置文件。

️我们将不断改进我们的演示商店以添加新功能并优化现有功能。当您更新到最新版本时，构建可能会失败。查看发行说明，了解如何通过更新自定义文件来修复它。

JSON 数据文件

如前所述，我们的演示商店是围绕一组存储为 JSON 文件的数据构建的，以将其与任何第三方服务解耦。要建立您的商店，您必须创建和管理这些文件。

JSON 文件位于data/json/ ，但您可以通过更改环境变量NEXT_PUBLIC_JSON_DATA_FOLDER来选择不同的位置。

类型定义文件位于packages/types/src/json/ 。我们使用 zod 进行模式验证。查看这些文件以了解您必须遵循的结构。

完成所有更改后，您可以通过运行以下命令检查一切是否正确：

 npm run test:data

区域设置数据文件

我们的演示商店是一个多语言网站。当您在上一步中构建数据时，您可能注意到某些字段已本地化。您可以添加新语言或更改现有翻译。

区域设置 JSON 文件位于data/locales/ ，但您可以通过更改环境变量NEXT_PUBLIC_LOCALES_DATA_FOLDER来选择不同的位置。

请执行以下操作以开始自定义区域设置：

cp -r ./demo-store-core/packages/website/data/locales ./data/locales

 # .env.local
NEXT_PUBLIC_LOCALES_DATA_FOLDER =../../../data/locales/

配置文件

配置文件位于config/ ，但您可以通过更改环境变量NEXT_PUBLIC_CONFIG_FOLDER来选择不同的位置。

您可以管理三个配置文件：

• general.config.js
  该文件包含一般配置。

• facets.config.js
  这是构面配置文件。您可以选择它们在过滤器面板中的显示顺序、外观及其值的排序规则。
  

• variants.config.js
  这是变体配置文件。您可以选择它们在产品详细信息页面上的显示顺序及其外观。
  

执行以下操作开始自定义配置：

cp -r ./demo-store-core/packages/website/config ./config

 # .env.local
NEXT_PUBLIC_CONFIG_FOLDER =../../../config/

附加环境变量

您可以使用一些环境变量来自定义您的商店。有关详尽的列表和描述，您可以查看additional-env.d.ts 文件。

部署

您可以将演示商店部署在您喜欢的任何地方。您只需要：

1. 根据您的需要，在系统中设置用于运行构建的所有环境变量。
2. 决定是否要使用静态站点生成或服务器端渲染。

演示商店首先设计为 SSG，但您可以立即切换到 SSR。我们测试了一些部署它的方法（例如使用 GitHub Workflow、Netlify、Vercel 等），您可以在此处找到有关它的更多信息。如果您采取了不同的做法或使用了其他服务，并且您想与社区分享这些步骤，请加入讨论，并提前致谢！

静态站点生成

要构建和部署演示商店：

1. 相应地设置以下环境变量：

    NEXT_PUBLIC_DATA_FETCHING =ssg

2. 运行npm run build来创建应用程序的静态优化生产版本。

3. 将文件夹demo-store-core/packages/website/out复制到您首选的静态托管。

服务端渲染

演示商店可以部署到任何支持 Node.js 的托管提供商。为此：

1. 相应地设置以下环境变量：

    NEXT_PUBLIC_DATA_FETCHING =ssr

2. 运行npm run build来创建应用程序的优化生产版本。

3. 运行npm start以在生产模式下启动 Node.js 服务器。

需要帮助吗？

• 加入 Commerce Layer 的 Discord 社区。
• 开启新的问答讨论
• 通过 Bluesky、X（以前称为 Twitter）或 LinkedIn 联系我们。
• 有错误吗？在此存储库上创建问题。

故障排除

1. 问：即使我更改了NEXT_PUBLIC_JSON_DATA_FOLDER 、 NEXT_PUBLIC_LOCALE_DATA_FOLDER或NEXT_PUBLIC_CONFIG_FOLDER ，网站仍然引用以前的文件。

   A.这些环境变量在 Webpack 中用作alias 。从 Webpack 5 开始，引入了缓存以加快构建速度。更改这些环境变量不会使 Webpack 缓存失效。您必须手动或通过运行以下命令删除.next文件夹：

    # update the path if needed
   rm -rf demo-store-core/packages/website/.next/

执照

该存储库是在 MIT 许可证下发布的。