project-validator

プロジェクトバリデーター

Web プロジェクトと React Native プロジェクトの両方について、apps-in-toss プロジェクトの設定、構成、ポリシーを検証します。

対応するプロジェクトタイプ：

• @apps-in-toss/web-framework を使用する Web プロジェクト
• Metro bundler を使用する @apps-in-toss/granite の React Native プロジェクト
• Unity ゲームプロジェクト（@apps-in-toss/web-framework を使用する WebGL ビルド）

このスキルの使い方

apps-in-toss プロジェクトを検証するときは、次の手順に従います。

1. プロジェクトタイプを特定する（Web または React Native）
2. Read ツールを使用して、関連ファイルを読み取り、確認する
3. リファレンスドキュメントのスキーマと照合する
4. 具体的な問題点と解決策をユーザーに報告する

検証チェックリスト

プロジェクト構成

プロジェクトに以下があることを確認します。

• ✅ package.json が存在する
• ✅ granite.config.ts が存在する
• ⚠️ src/ ディレクトリが存在する（推奨）
• ⚠️ tsconfig.json が存在する（TypeScript プロジェクトでは推奨）

package.json の検証

以下を確認します。

• ✅ ファイルが有効な JSON である
• ✅ 依存関係または開発依存関係に @apps-in-toss/framework、@apps-in-toss/web-framework、または @granite-js/react-native が含まれている
• ⚠️ TDS（Toss Design System）パッケージが含まれている（一貫した Toss UX のため強く推奨）：
  • @apps-in-toss/framework < 1.0.0 を使用する React Native の場合：@toss-design-system/react-native
  • @apps-in-toss/framework >= 1.0.0 を使用する React Native の場合：@toss/tds-react-native
  • @apps-in-toss/web-framework < 1.0.0 を使用する Web の場合：@toss-design-system/mobile
  • @apps-in-toss/web-framework >= 1.0.0 を使用する Web の場合：@toss/tds-mobile
• ⚠️ name フィールドがある
• ⚠️ version フィールドがある
• ⚠️ 一般的なスクリプト（dev、build など）を含む scripts フィールドがある

granite.config.ts の検証

Web プロジェクトの場合

web-granite-config-schema.md に照らして確認します。

必須項目：

• ✅ ファイルが存在し、読み取り可能である
• ✅ @apps-in-toss/web-framework/config から defineConfig をインポートしている
• ✅ export default defineConfig ステートメントがある
• ✅ 必須フィールドが含まれている：
  • appName（文字列）
  • brand（displayName、primaryColor、icon を含むオブジェクト）
  • permissions（配列）
  • web.port（数値）
  • web.commands.dev（文字列）
  • web.commands.build（文字列）

任意の推奨フィールド：

• ⚠️ navigationBar（オブジェクト）
• ⚠️ webViewProps（オブジェクト）
• ⚠️ outdir（文字列）

React Native プロジェクトの場合

react-native-granite-config-schema.md に照らして確認します。

必須項目：

• ✅ ファイルが存在し、読み取り可能である
• ✅ @granite-js/react-native/config から defineConfig をインポートしている
• ✅ @apps-in-toss/framework/plugins から appsInToss をインポートしている
• ✅ export default defineConfig ステートメントがある
• ✅ 必須フィールドが含まれている：
  • scheme（文字列）
  • appName（文字列）
• ✅ plugins 配列に appsInToss プラグインが含まれ、以下を備えている：
  • brand（displayName、primaryColor、icon を含むオブジェクト）
  • permissions（配列）

任意の推奨フィールド：

• ⚠️ navigationBar（オブジェクト）
• ⚠️ entryFile（文字列）
• ⚠️ outdir（文字列）

検証ワークフロー

新しいプロジェクトを開始するとき

1. package.json を読み、プロジェクトタイプとフレームワークのバージョンを特定します
2. granite.config.ts を読み、アプリのタイプ（ゲームか非ゲームか）を判定します
3. 使用する設定スキーマを特定します：
   • Web アプリ（Unity ゲームを含む）：web-granite-config-schema.md
   • React Native アプリ：react-native-granite-config-schema.md
4. 非ゲームアプリの場合：TDS パッケージがインストールされているか確認します（UX の向上に推奨）
5. Unity ゲームアプリの場合：Unity SDK のインストールまたは WebGL ビルド成果物があるか確認します（unity-game-validation.md を参照）
6. 適切なスキーマに照らして、すべての必須フィールドを確認します
7. 不足している設定や誤った設定を報告します
8. スキーマのドキュメントに記載された具体的な解決策を提示します

設定の問題をデバッグする場合

1. どのような問題が発生しているか、ユーザーに確認します
2. 関連する設定ファイルを読みます
3. スキーマの要件と照合します
4. 根本原因を特定します
5. よくある問題と解決方法にある解決方法を提示します

プロジェクトのセットアップをレビューする場合

1. すべての検証項目を体系的に確認します
2. 重大なエラー（❌）を先に報告します
3. 次に警告（⚠️）を報告します
4. ベストプラクティスに基づいて改善案を提案します

検証結果の報告

検証結果をユーザーに報告する際は、次のようにします。

✅ 成功

すべての必須チェックに合格しました。プロジェクトの設定は有効です。

❌ 重大なエラー

必須の設定が不足しているか、無効です。プロジェクトが正しく動作しない可能性があります。

• 優先度を高くして報告します
• 具体的なファイルの場所を示します（例：granite.config.ts:15）
• スキーマのドキュメントに記載されている正確な修正方法を含めます

⚠️ 警告

重大ではない問題が検出されました。プロジェクトは動作する可能性がありますが、ベストプラクティスに従い、対処することをおすすめします。

• 重大なエラーの後に報告します
• この推奨事項が重要な理由を説明します
• 任意の改善案を提示します

よくある問題と解決方法

フレームワークの依存関係が不足している

問題： package.json に必要なフレームワークパッケージがありません

Web の解決方法：

npm install @apps-in-toss/web-framework

React Native の解決方法：

npm install @granite-js/react-native @apps-in-toss/framework

必須フィールド appName が不足している

問題： granite.config.ts に appName フィールドがありません

解決方法： granite.config.ts に appName を追加します。

export default defineConfig({
  appName: 'my-app',
  // ...
});

必須フィールド brand が不足している

問題： granite.config.ts に brand の設定がありません

解決方法： brand オブジェクトをすべて追加します。

export default defineConfig({
  brand: {
    displayName: 'My App',
    primaryColor: '#3182F6',
    icon: 'https://static.toss.im/icons/app-icon.png',
  },
  // ...
});

必須フィールド permissions が不足している

問題： granite.config.ts に permissions 配列がありません

解決方法： permissions 配列を追加します（空でもかまいません）。

export default defineConfig({
  permissions: [],
  // or with specific permissions:
  permissions: [
    { name: 'clipboard', access: 'read' },
    { name: 'camera', access: 'access' },
  ],
  // ...
});

appsInToss プラグインが不足している（React Native）

問題： React Native プロジェクトに appsInToss プラグインがありません

解決方法： プラグイン配列にプラグインを追加します。

import { appsInToss } from '@apps-in-toss/framework/plugins';

export default defineConfig({
  plugins: [
    appsInToss({
      brand: {
        displayName: 'My App',
        primaryColor: '#3182F6',
        icon: 'https://static.toss.im/icons/app-icon.png',
      },
      permissions: [],
    }),
  ],
});

インポートパスが正しくない

問題： defineConfig のインポートパスが間違っています

Web の解決方法：

import { defineConfig } from '@apps-in-toss/web-framework/config';

React Native の解決方法：

import { defineConfig } from '@granite-js/react-native/config';

必須ファイルが不足している：granite.config.ts

問題： プロジェクトに granite.config.ts ファイルがありません

解決方法： 適切なテンプレートを使用してファイルを作成します。

• Web プロジェクト：web-granite-config-schema.mdを参照してください
• React Native プロジェクト：react-native-granite-config-schema.mdを参照してください

エクスポート文が不足している

問題： granite.config.ts で設定がエクスポートされていません

解決方法： エクスポート文を追加します。

export default defineConfig({ /* config */ });

TDS（Toss Design System）パッケージが不足している

問題： ミニアプリの package.json に TDS パッケージがありません

重要： Toss UX の一貫性を保ち、レビューの承認を得やすくするため、TDS の導入を強くおすすめします。

React Native の解決方法：

package.json でフレームワークのバージョンを確認します。

@apps-in-toss/framework が 1.0.0 未満の場合：

npm install @toss-design-system/react-native

@apps-in-toss/framework が 1.0.0 以上の場合：

npm install @toss/tds-react-native

Web の解決方法：

package.json でフレームワークのバージョンを確認します。

@apps-in-toss/web-framework が 1.0.0 未満の場合：

npm install @toss-design-system/mobile

@apps-in-toss/web-framework が 1.0.0 以上の場合：

npm install @toss/tds-mobile

TDS のドキュメント：

• React Native：https://tossmini-docs.toss.im/tds-react-native
• Web：https://tossmini-docs.toss.im/tds-mobile

注： ゲームアプリ（appType: 'game'）は TDS の要件が免除される場合があります

リファレンスドキュメント

検証時は必ず以下のリファレンスを参照してください。

• web-granite-config-schema.md — Web の granite.config.ts の完全なスキーマと例
• react-native-granite-config-schema.md — React Native の granite.config.ts の完全なスキーマと例
• unity-game-validation.md — Unity WebGL ゲームプロジェクトの検証ガイド
• Apps-in-Toss Unity 公式ドキュメント（検証の要点）：
  • プラットフォームモデルと事前チェック（概要、runtime-structure、precheck）：WebGL/WASM と JS ブリッジを使用します。ネイティブプラグインは使用できません。モバイル／タッチ操作を対象とします。ファイル I/O とソケットには制限があります。AR/XR/Compute には制約があります。
  • エンジンのバージョン（recommend-engine）：Unity 2023.3 LTS を推奨します。2022.3 は安定版、2021.3 はレガシー版です。本番環境では 2024.2 beta を避けてください。
  • 移行フロー（migration-guide）：事前チェック → WebGL への変換 → Apps-in-Toss SDK の統合 → UX／パフォーマンスの最適化 → .ait のパッケージ化／モニタリング。
  • パフォーマンス目標（perf-optimization、perf-measure）：起動時間は 3 秒未満を目標（最大 5 秒未満）、モバイルでの平均 FPS は 30 以上、メモリは 200MB 未満（300MB 超は重大）、初回フレームは 5 秒未満、バッテリー消費はネイティブ版の約 90～110％です。
  • ランタイム／起動／読み込み（runtime/performance、startup-speed、loading）：フレームレートと品質を適応的に調整し、バッチ処理／インスタンシング／LOD／カリングや更新のプーリングを行います。初回フレームで負荷の高い処理を避けてください。アンロード手段とキャッシュ上限を設けた段階的／優先度付きの読み込みを行い、可能な場合はシーン遷移を約 2 秒に収めてください。
  • デバッグ（debug-exception）：ログを Web／Apps-in-Toss に集約し、復旧処理を備えたグローバル例外ハンドラーを用意します。WebGL 用にアプリ内プロファイラー／コンソールフックを設けてください。

検証のベストプラクティス

1. 具体的にする：問題を報告する際は、可能であれば正確なファイルパスと行番号を記載します
2. 背景を説明する：フィールドが必須または推奨される理由を説明します
3. 解決策を提示する：スキーマドキュメントにある正確なコード修正を必ず提示します
4. 優先順位を付ける：警告より先に重大なエラーを報告します
5. 徹底的に確認する：明らかな項目だけでなく、必須フィールドをすべて確認します
6. TDS の使用状況を確認する：TDS パッケージがインストールされているかを確認し、Toss の UX を一貫させるために推奨します
7. ドキュメントへのリンクを提示する：TDS を提案する際は、関連する TDS ドキュメントへのリンクを含めます

検証レポートの例

Validating apps-in-toss project...

✅ package.json found and valid
✅ granite.config.ts found

Project Type: Web (detected @apps-in-toss/web-framework v1.2.0)
App Type: general (non-game)

❌ Critical Errors:
1. Missing required field: brand
   Location: granite.config.ts
   Fix: Add brand configuration with displayName, primaryColor, and icon

2. Missing required field: permissions
   Location: granite.config.ts
   Fix: Add permissions array (can be empty: permissions: [])

⚠️ Warnings:
1. Missing recommended field: navigationBar
   Suggestion: Add navigationBar for better UX

2. TDS package not found
   Recommendation: Install @toss/tds-mobile (for @apps-in-toss/web-framework >= 1.0.0)
   Command: npm install @toss/tds-mobile
   Benefit: Provides consistent Toss UX and improves review approval chances
   Documentation: https://tossmini-docs.toss.im/tds-mobile

Consult: references/web-granite-config-schema.md for complete examples