sealos-app-builder

Sealos App Builder

概要

このスキルを使うと、一般的なウェブアプリを Sealos Desktop 内で動作する Sealos アプリに変換したり、新しい Sealos アプリを一から作成したりできます。繰り返し使える部分に焦点を当てます。SDK の初期化、セッションへのアクセス、言語の同期、ビジネスデータの連携、Desktop テストアプリを使ったローカルデバッグ、公開に向けた準備です。

初心者にも理解しやすく、拡張しやすい、シンプルで学びやすい実装を優先します。

基本的なワークフロー

1. 出発点を特定する

依頼を次のいずれかのパスに分類します。

1. Sealos アプリを一から作成する。
2. 既存のウェブアプリを Sealos Desktop 内で動作するように適合させる。
3. すでに表示できているアプリに Sealos の ID とビジネスデータ連携を追加する。
4. コードを変更する代わりに、ドキュメントやチュートリアルを作成する。

リポジトリに Sealos 関連のコードがすでにある場合は、まずローカルのソースを調べます。特に、次の点を確認します。

1. packages/client-sdk または同等の SDK ソースを探します。
2. providers/ または同様のディレクトリにある既存のプロバイダーアプリを探します。
3. リポジトリですでに確立されているフレームワークとルーティングのパターンがある場合は、それを再利用します。

リポジトリに Sealos のローカルソースがない場合は、このスキルに含まれるリファレンスを基準として使用します。

2. Sealos アプリ SDK を統合する

Sealos Desktop との統合は、ルートレベルの関心事として扱います。

スターターテンプレートを使う前に、まず SDK をインストールします。

pnpm add @labring/sealos-desktop-sdk

プロジェクトで別のパッケージマネージャーを使用している場合は、npm install @labring/sealos-desktop-sdk または yarn add @labring/sealos-desktop-sdk を使います。

1. クライアント専用のルートコンポーネントで SDK を一度だけ初期化します。
2. 早い段階で getSession() と getLanguage() を取得します。
3. セッション、言語、読み込み状態、デスクトップの利用可否を共有コンテキストまたはストアに保存します。
4. アプリで実行時の言語同期が必要な場合は、EVENT_NAME.CHANGE_I18N を通じて言語変更を監視します。
5. Sealos Desktop の外部でアプリが開かれた場合に備えて、適切なフォールバックを追加します。

ルート統合を実装する前に、references/minimal-app-template.md を読んでください。 アプリで Next.js App Router を使用している場合は、references/nextjs-app-router.md も読んでください。

次のいずれかのスターターテンプレートを使用します。

1. React の場合は assets/templates/react/sealos-provider.tsx。
2. Vue の場合は assets/templates/vue/use-sealos.ts。

3. Sealos の ID をビジネスデータに連携する

多くのアプリでは、重要な連携は iframe 自体ではなく、ユーザーのマッピングです。

1. 安定したアプリレベルのユーザー識別子として session.user.id を使用します。
2. 必要に応じて、name、avatar、k8sUsername、nsid など、表示に適したフィールドを保存します。
3. ビジネスデータはアプリ独自のデータベースと API ルートに保持します。
4. Sealos のユーザー ID はビジネスロジックへの入力として扱い、バックエンド全体の代わりにしないでください。

スキーマや API に関するガイダンスが必要な場合は、references/data-integration-patterns.md を読んでください。

4. 実際のランタイムでのローカルデバッグを準備する

ブラウザーで正常に表示されても、Sealos との統合が動作しているとは限りません。

SDK の getSession() などの呼び出しを成功させるには、通常、Sealos Desktop からアプリを iframe 内で開く必要があります。ローカルデバッグがタスクに含まれる場合は、references/local-debug-and-test-app.md を読んでください。

次のルールに従います。

1. Sealos Desktop の外部でページを開いている場合は、そのことを明確に説明します。
2. エンドツーエンドの検証には、Sealos Desktop 内のテストアプリを優先します。
3. サーバーサイドでの SDK 呼び出しは避けます。

5. 公開に向けて準備する

ユーザーがデプロイや公開に向けた準備を希望する場合は、次の点を確認します。

1. 環境変数を確認します。
2. データベースへの接続とマイグレーションを確認します。
3. Sealos Desktop から起動したときにアプリが動作することを確認します。
4. アプリ間のナビゲーションやイベントの使用が有効であることを確認します。
5. 手動での登録やプラットフォーム設定で残っている手順をまとめます。

リリースチェックリストとして references/publish-checklist.md を使用します。

実装ルール

統合はシンプルに保つ

Sealos の統合は、実行可能な最小限の構成をデフォルトとします。

1. ルートのプロバイダーまたはストアを1つ用意します。
2. ビジネス上の ID をマッピングするパターンを1つ用意します。
3. Desktop 以外からアクセスする場合のフォールバック経路を1つ用意します。

複数のページやコンポーネントに SDK の初期化処理を分散させないでください。

リポジトリに実在する SDK の API を優先する

現在のワークスペースに Sealos SDK のソースコードや既存の Sealos アプリがある場合：

1. それらのソースコードを確認します。
2. 実際にエクスポートされている API と型に従います。
3. 汎用的な例とのリポジトリ固有の違いを明記します。

公式 SDK パッケージ名を使用する

生成する例やスターターコードでは、デフォルトで @labring/sealos-desktop-sdk を使用します。

対象のリポジトリですでにローカルのワークスペースエイリアスが確立されており、ユーザーからその維持を明示的に求められた場合に限り、別のものを使用します。

判断ガイド

ユーザーから「Sealos アプリの構築方法」を尋ねられた場合

以下を提示します。

1. ランタイムモデルの簡潔な説明。
2. SDK の最小限の統合例。
3. ビジネスデータのマッピング例。
4. Sealos Desktop のテストアプリを使ったローカルデバッグのガイダンス。

ユーザーから既存アプリの変更を求められた場合

次の順序で作業します。

1. 現在のアプリのエントリーポイントを確認します。
2. ルートの Sealos プロバイダーを1つ追加するか、リファクタリングします。
3. ビジネス API を session.user.id に接続します。
4. Desktop 以外でのフォールバック動作を確認します。

ユーザーからドキュメントやチュートリアルを求められた場合

以下の内容を軸に構成します。

1. Sealos アプリとは何か。
2. SDK の初期化方法。
3. セッションの取得方法と使用方法。
4. ビジネスデータの統合方法。
5. Desktop のテストアプリを使ったデバッグ方法。
6. 公開と検証の方法。

参考資料

タスクに必要なファイルのみを読みます。

1. 利用可能な SDK API とランタイムの動作については、references/sdk-capabilities.md を参照します。
2. 推奨されるルート統合パターンについては、references/minimal-app-template.md を参照します。
3. Next.js App Router での具体的な配置例については、references/nextjs-app-router.md を参照します。
4. ユーザーマッピング、データベーススキーマ、API の形式については、references/data-integration-patterns.md を参照します。
5. iframe を使ったデバッグと Desktop テストアプリの設定については、references/local-debug-and-test-app.md を参照します。
6. リリース準備の手順については、references/publish-checklist.md を参照します。