sfnext-project-setup

用途

sfnext-project-setup 技能用于创建和配置 Storefront Next 项目。Storefront Next 是一种服务端渲染的 SPA，基于 React 19、React Router 7、Vite 和 Tailwind CSS v4 构建，运行在 Managed Runtime（MRT）上，所有 SCAPI 请求均在服务端执行。

主要能力

指导创建 Storefront Next 项目，包括通过 Business Manager 创建实例连接的店面，或通过 CLI 进行本地探索。
说明项目结构，涵盖配置文件、路由、组件、中间件、本地化文件等目录。
指导环境变量设置，包括必需变量示例。
提供开发命令（开发服务器、构建、测试、Storybook、包体积检查）。
列出必须遵守的规则与常见问题排查方法。

使用方式

通过 Business Manager 创建（实例连接的店面）

优先使用 storefront setup：它会创建 API 客户端、MRT 资源、初始配置和一次部署。应复用这些资源，不要将创建替代的 SLAS 客户端或 MRT 项目作为常规设置。可选择 GitHub 工作流或本地代码工作流。使用下载的 env.txt 作为项目的 .env；不要自行编造租户/站点 ID，也不要暴露其中的密钥。需要设置时引导用户完成 Business Manager 操作。

通过 CLI 创建（本地探索）

用于在不配置实例资源的情况下探索模板。若要连接到用户实例，请遵循上述 storefront setup 并使用其配置。

# 创建新的店面项目（交互式）
pnpm dlx @salesforce/storefront-next-dev create-storefront

# 或使用名称参数创建
pnpm dlx @salesforce/storefront-next-dev create-storefront --name my-storefront

# 进入项目目录
cd my-storefront

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

项目结构

my-storefront/
├── .env.default              # 默认环境变量（模板）
├── .env                      # 本地覆盖（git 忽略）
├── config.server.ts          # 带默认值的集中配置
├── vite.config.ts            # Vite 构建配置
├── package.json              # 依赖与脚本
├── src/
│   ├── app.css               # 全局样式与 Tailwind 主题
│   ├── root.tsx              # 根布局组件
│   ├── routes/               # 基于文件的路由（React Router 7）
│   │   ├── _app.tsx          # 应用布局（已认证外壳）
│   │   ├── _app._index.tsx   # 首页
│   │   └── _app.product.$productId.tsx
│   ├── components/           # 可复用 UI 组件
│   │   ├── ui/               # shadcn/ui 基础组件（可定制）
│   │   └── ...               # 自定义组件
│   ├── config/               # 配置 schema 与上下文
│   │   └── schema.ts         # 配置类型定义
│   ├── lib/                  # 工具与 API 客户端设置
│   │   ├── api-clients.ts    # createApiClients() 工厂
│   │   ├── utils.ts          # cn() 工具与辅助函数
│   │   └── registry.ts       # Page Designer 组件注册表
│   ├── locales/              # 翻译文件
│   │   └── en-US/
│   │       └── translations.json
│   ├── middlewares/          # 服务端中间件
│   │   ├── auth.server.ts    # 认证中间件
│   │   └── basket.server.ts  # 购物车中间件
│   ├── providers/            # React 上下文提供者
│   ├── hooks/                # 自定义 React hooks
│   ├── extensions/           # 扩展模块
│   └── test-utils/           # 共享测试工具
├── public/                   # 静态资源
└── cartridges/               # Page Designer cartridge 元数据

环境设置

对于 Business Manager 创建的店面，使用下载的配置。对于本地 CLI 探索，将 .env.default 复制为 .env：

cp .env.default .env

必需变量（使用所选店面的值；这是配置示例，不是要求配置新凭据）：

PUBLIC__app__commerce__api__clientId=your-client-id
PUBLIC__app__commerce__api__organizationId=your-org-id
PUBLIC__app__commerce__api__siteId=your-site-id
PUBLIC__app__commerce__api__shortCode=your-short-code
PUBLIC__app__defaultSiteId=your-site-id
PUBLIC__app__commerce__sites='[{"id":"your-site-id","defaultLocale":"en-US","defaultCurrency":"USD","supportedLocales":[{"id":"en-US","preferredCurrency":"USD"}],"supportedCurrencies":["USD"]}]'

开发命令

# 启动带热重载的开发服务器
pnpm dev

# 生产构建
pnpm build

# 运行测试
pnpm test

# 运行 Storybook
pnpm storybook

# 检查包体积
pnpm bundlesize:test

必须遵守的规则

仅使用 TypeScript —— .ts 和 .tsx 文件；JavaScript 文件会被 ESLint 阻止。
仅服务端数据加载 —— 使用 loader 函数；绝不使用客户端 loader。
同步 loader —— 返回 promise，不要使用 async/await（以启用流式传输）。
仅使用 Tailwind CSS 4 —— 不使用内联样式、CSS 模块或单独的 CSS 文件。
使用 createPage() HOC —— 通过 Suspense 标准化页面模式。

适用场景

创建新的 Storefront Next 店面。
理解项目结构。
设置环境变量。
排查 SCAPI 401 错误、JavaScript 文件错误、开发服务器无法启动、配置未加载等问题。

限制

资料未提供收费、价格、平台支持范围等具体信息。
资料未提供除上述命令与规则外的其他功能说明。

参考文档

Project Structure Reference —— 详细的目录与文件说明
Environment Variables Reference —— 完整变量列表与命名规则

技能介绍

用途