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。

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. Q：即使我更改了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 許可證下發布的。