wix-cli-app-validation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wix App Validation

Wix 应用验证

Validates Wix CLI applications through a four-step sequential workflow: package installation, TypeScript compilation check, build, and preview.

通过四步顺序工作流验证Wix CLI应用：包安装、TypeScript编译检查、构建和预览。

Validation Workflow

验证工作流

Execute these steps sequentially. Stop and report errors if any step fails.

按顺序执行以下步骤。若任意步骤失败，立即停止并报告错误。

Step 1: Package Installation

步骤1：包安装

Ensure all dependencies are installed before proceeding with the build.

Detect package manager:

Check for
```
package-lock.json
```
→ use
```
npm
```
Check for
```
yarn.lock
```
→ use
```
yarn
```
Check for
```
pnpm-lock.yaml
```
→ use
```
pnpm
```
Default to
```
npm
```
if no lock file is found

Run installation command:

bash

undefined

在继续构建前，确保所有依赖已安装。

检测包管理器：

检查是否存在
```
package-lock.json
```
→ 使用
```
npm
```
检查是否存在
```
yarn.lock
```
→ 使用
```
yarn
```
检查是否存在
```
pnpm-lock.yaml
```
→ 使用
```
pnpm
```
若未找到锁文件，默认使用
```
npm
```

运行安装命令：

bash

undefined

For npm

npm install

For yarn

yarn install

For pnpm

pnpm install


**Success criteria:**
- Exit code 0
- All dependencies installed successfully
- No missing peer dependencies warnings (unless expected)
- `node_modules` directory exists and contains expected packages

**On failure:** Report the installation errors and stop validation. Common issues:
- Network connectivity problems
- Corrupted lock files
- Version conflicts
- Missing Node.js or package manager

pnpm install


**成功标准：**
- 退出码为0
- 所有依赖安装成功
- 无缺失peer依赖警告（除非是预期情况）
- `node_modules`目录存在且包含预期包

**失败处理：** 报告安装错误并停止验证。常见问题：
- 网络连接问题
- 锁文件损坏
- 版本冲突
- 缺少Node.js或包管理器

Step 2: TypeScript Compilation Check

步骤2：TypeScript编译检查

Run TypeScript compiler to check for type errors.

Full project check:

bash

npx tsc --noEmit

Targeted check (specific files/directories):

When validating after implementing a specific extension, you can run TypeScript checks on just those files:

bash

undefined

运行TypeScript编译器检查类型错误。

全项目检查：

bash

npx tsc --noEmit

定向检查（特定文件/目录）：

在实现特定扩展后进行验证时，可仅对这些文件运行TypeScript检查：

bash

undefined

Check specific directory

npx tsc --noEmit src/extensions/dashboard/pages/survey//*.ts src/extensions/dashboard/pages/survey//*.tsx

Check dashboard pages only

npx tsc --noEmit src/extensions/dashboard/pages//*.ts src/extensions/dashboard/pages//*.tsx

Check site widgets only

npx tsc --noEmit src/site/widgets//*.ts src/site/widgets//*.tsx

Check dashboard modals only

npx tsc --noEmit src/extensions/dashboard/modals//*.ts src/extensions/dashboard/modals//*.tsx

Check backend only

npx tsc --noEmit src/backend/**/*.ts


**When to use targeted checks:**
- After implementing a single extension (faster feedback)
- When debugging type errors in a specific area
- During iterative development

**When to use full project check:**
- Before final validation
- When changes affect shared types
- Before building/deploying

**Success criteria:**
- Exit code 0
- No TypeScript compilation errors
- All type checks pass

**On failure:** Report the specific TypeScript errors and stop validation. Common issues:
- Type mismatches between expected and actual types
- Missing type declarations for imported modules
- Incorrect generic type parameters
- Properties not existing on declared types
- Incompatible function signatures

npx tsc --noEmit src/backend/**/*.ts


**何时使用定向检查：**
- 实现单个扩展后（反馈更快）
- 调试特定区域的类型错误时
- 迭代开发期间

**何时使用全项目检查：**
- 最终验证前
- 变更影响共享类型时
- 构建/部署前

**成功标准：**
- 退出码为0
- 无TypeScript编译错误
- 所有类型检查通过

**失败处理：** 报告具体的TypeScript错误并停止验证。常见问题：
- 预期类型与实际类型不匹配
- 导入模块缺少类型声明
- 泛型类型参数不正确
- 声明类型上不存在对应属性
- 函数签名不兼容

Step 3: Build Validation

步骤3：构建验证

Run the build command and check for compilation errors:

bash

npx wix build

Success criteria:

Exit code 0
No TypeScript errors
No missing dependencies

On failure: Report the specific compilation errors and stop validation.

运行构建命令并检查编译错误：

bash

npx wix build

成功标准：

退出码为0
无TypeScript错误
无缺失依赖

失败处理： 报告具体的编译错误并停止验证。

Step 4: Preview Deployment

步骤4：预览部署

Start the preview server:

bash

npx wix preview

Success criteria:

Preview server starts successfully
Preview URLs are generated (both site and dashboard)

URL extraction: Parse the terminal output to find both preview URLs. Look for patterns like:

Site preview:

Site preview: https://...

Site URL: https://...

Dashboard preview:

Dashboard preview: https://...

Preview URL: https://...

Your app is available at: https://...

Extract both URLs and provide them to the user for manual verification.

On failure: Report the preview startup errors and stop validation.

启动预览服务器：

bash

npx wix preview

成功标准：

预览服务器成功启动
生成预览URL（站点和后台管理端均需生成）

URL提取： 解析终端输出以找到两个预览URL。查找如下格式的内容：

站点预览：

Site preview: https://...

或

Site URL: https://...

后台管理端预览：

Dashboard preview: https://...

或

Preview URL: https://...

或

Your app is available at: https://...

提取两个URL并提供给用户进行手动验证。

失败处理： 报告预览启动错误并停止验证。

Validation Report

验证报告

After completing all steps, provide a summary:

Pass:

Dependencies: ✓ All packages installed successfully
TypeScript: ✓ No compilation errors
Build: ✓ Compiled successfully
Preview: ✓ Running at [URL]

Fail:

Identify which step failed
Provide specific error messages
Suggest remediation steps

完成所有步骤后，提供总结：

通过：

依赖项：✓ 所有包安装成功
TypeScript：✓ 无编译错误
构建：✓ 编译成功
预览：✓ 运行于[URL]

失败：

明确标识失败的步骤
提供具体错误信息
建议修复步骤

Common Issues

常见问题

Issue	Cause	Solution
Package installation fails	Missing lock file, network issues, or corrupted node_modules	Delete `node_modules` and lock file, then reinstall
TypeScript compilation fails	Type mismatches, missing declarations, or incorrect types	Fix TypeScript errors shown in `npx tsc --noEmit` output
Build fails with TS errors	Type mismatches	Fix TypeScript errors in source
Preview fails to start	Port conflict or config issue	Check `wix.config.json`
Console errors in preview	Runtime exceptions	Check browser console output
UI not rendering	Component errors	Review component code and imports

问题	原因	解决方案
包安装失败	缺少锁文件、网络问题或node_modules损坏	删除 `node_modules` 和锁文件，重新安装
TypeScript编译失败	类型不匹配、缺少声明或类型错误	修复 `npx tsc --noEmit` 输出中显示的TypeScript错误
构建时出现TS错误	类型不匹配	修复源码中的TypeScript错误
预览无法启动	端口冲突或配置问题	检查 `wix.config.json`
预览中出现控制台错误	运行时异常	检查浏览器控制台输出
UI无法渲染	组件错误	检查组件代码和导入项