使用 Blazity 构建您的 Next.js Shopify 店面

本指南将引导您设置 Shopify 商务的 Next.js 店面。我们将使用由 Blazity 开发的开源 企业电子商务 入门工具，该工具附带一个 CLI，可让您快速入门。

概述

下图概述了我们应用程序的架构。

应用程序堆栈由 4 个关键组件组成

• 数据源 — Shopify 管理员、个性化工具等。
• 搜索引擎 — Meilisearch
• 全栈应用程序 — Next.js 应用程序
• 第三方集成 — 分析、CRM 等。

在此架构中，Meilisearch 数据库聚合来自多个来源的数据，以便 Next.js 应用程序可以访问它。

我们的最终应用程序将如下所示：实时预览 ✨

先决条件

本指南需要

• Node.js ≥ 20.x
• Yarn ≥ 4.x
• Meilisearch ≥ 1.8
• 一个 Shopify 商店

设置

此设置阶段为您提供必要的凭据，以便您的应用程序与 Meilisearch 和您的 Shopify 商店进行交互。

这些凭据与安装阶段需要的环境变量匹配。为了清晰起见，本指南将使用“✅”表情符号指示每个变量。

创建 Shopify 商店

如果您还没有商店，请转到 Shopify 并创建一个新商店。Shopify 将一个唯一的 ID 与每个商店关联，该 ID 称为商店域。

要查找您的 Shopify 商店域，请转到设置 > 域。您的商店域如下所示：your-domain.myshopify.com。

✅ Shopify 商店域

安装 Shopify 无头

在 Shopify Marketplace 中，找到 无头应用程序 并安装它。安装后，单击创建店面。

然后，我们将更新 API 访问权限。在管理 API 访问权限部分中，单击店面 API 旁边的管理。

编辑店面 API 权限以添加以下内容

• unauthenticated_read_product_inventory
• unauthenticated_read_customer_tags

保存权限后，您可以复制私有访问令牌。

✅ Shopify 应用店面 API 令牌

创建 Shopify 应用

现在，我们将为我们的商店创建一个 Shopify 应用。Shopify 应用允许您为您的商店构建自定义集成。此应用将允许我们获取 API 密钥，以读取和管理我们 Shopify 商店中的数据。

要创建 Shopify 应用

• 导航到您商店的 Shopify 管理员仪表板
• 打开商店的设置并导航到应用和销售渠道选项卡
• 单击开发应用
• 如果需要，请按照步骤允许为您的商店开发自定义应用
• 创建一个应用并输入一个名称，例如，“Next.js 应用”

创建应用后，导航到 API 凭据选项卡以查找您的 Shopify 应用的 API 密钥（不是 API 密钥！）。

✅ Shopify 应用 API 密钥

配置 Shopify 管理员 API 密钥

Shopify 应用使用一组两个密钥

• 一个 管理员 API 密钥 — 用于管理 Shopify 管理员，例如编辑您的产品目录
• 一个 店面 API 密钥 — 用于读取产品目录、创建购物车等。

我们可以在 Shopify 应用的配置选项卡中配置这些 API 密钥的访问范围。在本节中，我们将为我们的管理员 API 密钥启用所需的范围。

要配置管理员 API 密钥的范围，请按照以下步骤操作

• 在管理员 API 集成部分中，单击配置
• 启用以下范围
  • write_product_listings
  • read_product_listings
  • read_products
  • write_products
• 在Webhook 订阅下，选择 2024-01 API 版本
• 保存 🙂

在定义了我们的令牌 API 范围后，我们可以返回到API 凭据选项卡并安装我们的应用。单击安装应用以生成您的 API 访问令牌。

安装 Shopify 应用后，您将可以访问您的管理员 API 访问令牌。出于安全原因，此令牌只会向您显示一次——请务必保存它。

✅ Shopify 应用管理员 API 令牌

创建您的 Meilisearch 数据库

Meilisearch 是一款开源搜索引擎，提供全文、向量和混合搜索功能。我们的 Shopify 产品数据将与 Meilisearch 同步，使前端应用程序能够为最终用户获得快速、相关的搜索结果。

如果您没有，请创建一个 Meilisearch 云帐户。如有必要，您可以首先了解如何 开始使用 Meilisearch 云。

首先，创建一个新的项目，例如，Shopify 商店。这将创建一个新的 Meilisearch 数据库，并且应该需要几秒钟才能完成。

然后，您可以导航到项目的“设置”页面以查找您的数据库 URL（您的主机）和默认管理员 API 密钥。

✅ Meilisearch 主机 URL

✅ Meilisearch API 令牌

配置您的 Meilisearch

创建数据库后，我们将创建索引。您可以为它们选择任何名称，但您必须相应地配置您的环境变量。让我们创建两个索引

• 我们的产品的索引，例如，products
• 我们的产品类别的索引，例如，categories

✅ Meilisearch 产品索引名称

✅ Meilisearch 类别索引名称

创建索引后，我们现在可以配置它们。Meilisearch 默认设置适用于大多数设置。对于每个索引，我们只配置可过滤属性和可排序属性。

产品索引 — 可过滤属性

[
	"collections",
	"collections.handle",
	"collections.id",
	"flatOptions",
	"handle",
	"minPrice",
	"tags",
	"variants.availableForSale",
	"vendor",
	"hierarchicalCategories",
	"hierarchicalCategories.lvl0",
	"hierarchicalCategories.lvl1",
	"hierarchicalCategories.lvl2",
	"avgRating"
]

产品索引 — 可排序属性

[
	"minPrice",
	"updatedAtTimestamp",
	"avgRating"
]

类别索引 — 可过滤属性

[
	"handle",
	"id"
]

您可以将所有其他属性设置保留为其默认值。

安装

有了所有凭据，我们就可以启动安装向导了。让我们使用 Blazity 的 commerce CLI 创建我们的项目。

# with NPM
npm create commerce

# with Yarn
yarn create commerce

第一个提示将要求您选择要启用的服务。对于本指南，我们将仅启用默认值：Shopify 和 Meilisearch。

然后，CLI 将会要求您提供一系列凭据。如果您已经按照“设置”部分进行了操作，那么您应该已经拥有所有必要的凭据。提供所有凭据后，CLI 将会在一个新文件夹中搭建您的项目。

创建完成后，导航到您的项目目录。您的 apps/web/.env.local 文件应该看起来像这样

# apps/web/.env.local

SHOPIFY_STOREFRONT_ACCESS_TOKEN=shpat_a-very-long-token
SHOPIFY_ADMIN_ACCESS_TOKEN=shpat_another-very-long-token
SHOPIFY_STORE_DOMAIN=your-domain.myshopify.com
SHOPIFY_APP_API_SECRET_KEY=a-32-characters-long-api-key
SHOPIFY_HIERARCHICAL_NAV_HANDLE=hierarchical-categories
MEILISEARCH_PRODUCTS_INDEX=products
MEILISEARCH_CATEGORIES_INDEX=categories
MEILISEARCH_ADMIN_KEY=your-meilisearch-admin-api-key
MEILISEARCH_HOST=https://edge.meilisearch.com
LIVE_URL=https://your-domain.myshopify.com
FLAGS_SECRET=randomly-generated-secret
CRON_SECRET=another-randomly-generated-secret

同步 Meilisearch 和 Shopify

Blazity 提供了一个 CLI 工具，用于同步您的 Shopify 和 Meilisearch 之间的数据。在本节中，我们将了解如何使用 commerce-cli 实现此目的。

要将您的 Shopify 数据与 Meilisearch 同步，请导航到您的项目文件夹并运行

npx commerce-cli@latest sync

此命令将从您的 Shopify 商店中提取所有必要的数据并将其同步到您的 Meilisearch 数据库中。

启动您的应用程序

在初始化您的应用程序并同步 Shopify 和 Meilisearch 之间的数据后，您就可以启动您的应用程序了。

要在开发模式下启动您的应用程序，请运行

# with NPM
npm run dev

# with Yarn
yarn dev

就是这样！您可以在 https://127.0.0.1:3000 访问您的应用程序 🎉

您还可以在此处查看实时示例：https://commerce.blazity.com/

进一步探索

本指南未涵盖 Blazity 模板中的所有可用功能。有关更高级的配置，您可以了解如何在 Blazity 文档中设置分层类别、实施高度可扩展的重定向等等。

此外，以下是一些资源可以帮助您将新的 Shopify 商店与 Meilisearch 和 Next.js 集成

• Meilisearch 文档
• Next.js 文档
• 将 Meilisearch Cloud 与 Vercel 集成

订阅我们的每月新闻通讯，及时了解 Meilisearch 的所有动态。要了解有关 Meilisearch 未来并帮助塑造它，请查看我们的 路线图 并参与我们的 产品讨论。

如有任何其他问题，请加入我们在 Discord 上的开发者社区。