marketplace-scaffold

搭建新的 Sitecore Marketplace 应用

你将帮助用户使用官方 Sitecore Marketplace SDK（v0.4）搭建新的 Sitecore Marketplace 应用。

第 1 步：收集需求

向用户询问以下问题（跳过用户已经回答的问题）：

1. 应用名称 — 应用应该叫什么？（默认值：如果提供了 $ARGUMENTS，则使用其中的名称）
2. 架构 — 仅客户端，还是全栈？
   • 仅客户端：UI 完全在 iframe 中运行，并通过 SDK 客户端进行通信。更简单，无需服务器。
   • 全栈：包含 Next.js API 路由/服务器操作，以便在服务器端访问 SDK。Auth0、服务器端变更或代理外部 API 时需要此架构。
3. 身份验证 — 内置（默认）还是 Auth0？
   • 内置：零配置，SDK 会自动处理身份验证。足以满足大多数应用的需求。
   • Auth0：服务器端 API 访问、外部服务集成或自定义身份验证流程所需。需要设置 Auth0 租户。
4. 可选软件包 — 需要哪些其他 SDK 软件包？
   • XM Cloud（xmc）：访问 Sites、Pages、Authoring、Content Transfer、Search 和 Agent API
   • AI Skills（ai）：访问 Brand Review API，进行 AI 驱动的内容分析

第 2 步：运行搭建命令

根据用户的回答，构建并运行相应的命令：

# Client-side only (built-in auth)
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-client.json

# Client-side + XMC
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-client.json https://marketplace-sdk.sitecorecloud.io/r/xmc.json

# Client-side + AI
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-client.json https://marketplace-sdk.sitecorecloud.io/r/ai.json

# Client-side + XMC + AI
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-client.json https://marketplace-sdk.sitecorecloud.io/r/xmc.json https://marketplace-sdk.sitecorecloud.io/r/ai.json

# Full-stack (Auth0) — adds server-side SDK support
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-auth0.json

# Full-stack + XMC
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-auth0.json https://marketplace-sdk.sitecorecloud.io/r/xmc.json

# Full-stack + AI
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-auth0.json https://marketplace-sdk.sitecorecloud.io/r/ai.json

# Full-stack + XMC + AI
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/app-auth0.json https://marketplace-sdk.sitecorecloud.io/r/xmc.json https://marketplace-sdk.sitecorecloud.io/r/ai.json

重要提示：如果用户还没有 Next.js 项目，请先搭建一个：

npx create-next-app@latest <app-name> --typescript --tailwind --eslint --app --src-dir
cd <app-name>

第 3 步：搭建后的设置

搭建完成后：

1. 创建 .env.local — 模板请参阅 env-template.md。根据所选架构填写。

2. 配置 CSP 标头 — 在 next.config.ts 中添加 iframe 嵌入标头：

const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: "/(.*)",
        headers: [
          {
            key: "Content-Security-Policy",
            value: "frame-ancestors 'self' https://*.sitecorecloud.io",
          },
        ],
      },
    ];
  },
};

3. 安装 Blok 主题（如果尚未安装）：

npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/blok-theme.json

4. 验证设置 — 运行开发服务器并确认没有错误：

npm run dev

第 4 步：说明后续步骤

搭建成功后，建议用户：

• 使用 /marketplace-add-extension 添加扩展点路由（自定义字段、仪表板小组件等）
• 使用 /marketplace-sdk-reference 查阅 SDK API
• 使用 /marketplace-build-component，通过 Blok 设计系统构建 UI
• 准备部署时，使用 /marketplace-deploy

参考文件

• 架构指南 — 客户端与全栈架构的决策矩阵
• 环境模板 — 不同架构对应的 .env.local 模板