wix-cli-app-validation

Wix アプリの検証

Wix CLI アプリを、パッケージのインストール、TypeScript のコンパイルチェック、ビルド、プレビューの4段階の順次ワークフローで検証します。

検証ワークフロー

以下の手順を順番に実行します。いずれかの手順で失敗した場合は、エラーを報告して停止してください。

手順 1：パッケージのインストール

ビルドに進む前に、すべての依存関係がインストールされていることを確認します。

パッケージマネージャーを検出します：

• package-lock.json を確認 → npm を使用
• yarn.lock を確認 → yarn を使用
• pnpm-lock.yaml を確認 → pnpm を使用
• ロックファイルが見つからない場合は、npm を使用

インストールコマンドを実行します：

# For npm
npm install

# For yarn
yarn install

# For pnpm
pnpm install

成功条件：

• 終了コードが 0
• すべての依存関係が正常にインストールされている
• 想定されるものを除き、ピア依存関係の不足に関する警告がない
• node_modules ディレクトリが存在し、必要なパッケージが含まれている

失敗した場合： インストールエラーを報告し、詳細な診断情報についてデバッグログを確認して、検証を停止してください。よくある問題：

• ネットワーク接続の問題
• ロックファイルの破損
• バージョンの競合
• Node.js またはパッケージマネージャーが見つからない

手順 2：TypeScript のコンパイルチェック

TypeScript コンパイラを実行して、型エラーを確認します。

プロジェクト全体のチェック：

npx tsc --noEmit

対象を絞ったチェック（特定のファイル／ディレクトリ）：

特定の拡張機能を実装した後に検証する場合は、該当するファイルのみを対象に TypeScript チェックを実行できます。

# 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/extensions/site/widgets/**/*.ts src/extensions/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/extensions/backend/**/*.ts

対象を絞ったチェックを使用する場合：

• 単一の拡張機能を実装した後（より速くフィードバックを得られます）
• 特定の領域の型エラーをデバッグするとき
• 反復的な開発中

プロジェクト全体のチェックを使用する場合：

• 最終検証の前
• 共有型に影響する変更を行ったとき
• ビルド／デプロイの前

成功条件：

• 終了コードが 0
• TypeScript のコンパイルエラーがない
• すべての型チェックに合格している

失敗した場合： 該当する TypeScript エラーを報告して、検証を停止してください。よくある問題：

• 期待される型と実際の型の不一致
• インポートしたモジュールの型宣言が見つからない
• ジェネリック型の型パラメーターが正しくない
• 宣言された型に存在しないプロパティ
• 互換性のない関数シグネチャ

手順 3：ビルドの検証

ビルドコマンドを実行し、コンパイルエラーがないか確認します。

npx wix build

成功条件：

• 終了コードが 0
• TypeScript エラーがない
• 依存関係の不足がない

失敗した場合： 該当するコンパイルエラーを報告し、詳細な診断情報についてデバッグログを確認して、検証を停止してください。

手順 4：プレビューのデプロイ

プレビューサーバーを起動します。

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 を抽出し、ユーザーが手動で確認できるように提示してください。

失敗した場合： プレビューの起動エラーを報告し、詳細な診断情報についてデバッグログを確認して、検証を停止してください。

検証レポート

すべての手順が完了したら、概要を提示してください。

合格：

• 依存関係：✓ すべてのパッケージが正常にインストールされました
• TypeScript：✓ コンパイルエラーはありません
• ビルド：✓ 正常にコンパイルされました
• プレビュー：✓ [URL] で実行中

不合格：

• 失敗した手順を特定する
• 具体的なエラーメッセージを提示する
• 解決手順を提案する

エラー発生時のデバッグログ

検証手順が失敗した場合（終了コードが 0 以外、エラー出力、または CLI のクラッシュ／ハング）、プロジェクトルートにある .wix/debug.log を確認し、エラーの詳細なトレースを取得します。このファイルを読むのはエラーが発生した場合に限ってください。手順が成功した場合や、ターミナル出力からエラーが明らかな場合（例：明確な TypeScript の型エラー）は確認しないでください。

.wix/ ディレクトリは Wix CLI によって自動的に作成され、内部設定ファイルとログファイルが含まれています。編集はしないでください。ただし、トラブルシューティングのために debug.log を読むことは想定されています。

Read: .wix/debug.log

# If the file is large, read the last 100 lines for the most recent errors
Read: .wix/debug.log (with offset to the end)

よくある問題

問題	原因	解決策
パッケージのインストールに失敗する	ロックファイルがない、ネットワークの問題、または node_modules が破損している	node_modules とロックファイルを削除してから、再インストールします
TypeScript のコンパイルに失敗する	型の不一致、宣言の不足、または型が正しくない	npx tsc --noEmit の出力に表示される TypeScript のエラーを修正します
ビルドに失敗する	TypeScript のエラー、依存関係の不足、または内部 CLI エラー	ソースコードの TypeScript エラーを修正します。原因が明確でない場合は、.wix/debug.log を確認します
プレビューの起動に失敗する	ポートの競合、設定の問題、または内部 CLI エラー	wix.config.json を確認します。不明な場合は、詳細を .wix/debug.log で確認します
プレビューでコンソールエラーが発生する	実行時例外	ブラウザーのコンソール出力を確認します
UI がレンダリングされない	コンポーネントのエラー	コンポーネントのコードとインポートを確認します
明確なメッセージがない CLI エラー	ターミナル出力が途中で切れている	完全なエラートレースとスタックの詳細を .wix/debug.log で確認します
設定変更後に原因不明の問題が発生する	CLI の状態が古い	.wix/debug.log で状況を確認してから、.wix/ を削除してビルドし直します