solana-mobile

Solana Mobile プロジェクト

Solana Mobile アプリをセットアップして保守します。solana-mobile CLI は、スキャフォールディング、環境チェック、エミュレーター管理を行います。手作業でセットアップするよりも、こちらを優先してください。

インストールせずに実行します。

npx solana-mobile@latest --help

pnpm dlx solana-mobile@latest と bunx solana-mobile@latest も同等のコマンドです。プロジェクトですでに使われているパッケージマネージャーに合わせ、実行時に古いキャッシュ済みバージョンが再利用されないよう、@latest を付けてください。

コマンド	用途
create	新しいプロジェクトの作成
device	APK のインストール、URL の起動、デバイスの準備
doctor	ツールチェーンのチェック
emulator (emu)	エミュレーターの作成と実行
localnet	デバイスからアクセスできるローカルバリデーター
playground	アプリをビルドせずにウォレットをテスト
templates	テンプレートリポジトリの保守 — テンプレート作成者専用
webshell	既存のウェブアプリを Android WebView シェルでラップ

すべてのコマンドの全フラグについては、references/cli.md を参照してください。フラグを推測しないでください。CLI には独自のヘルプが用意されており、各コマンドの --help が正式な情報です。

譲れない制約

Mobile Wallet Adapter には開発ビルドが必要です。Expo Go は動作しません — MWA は Expo Go に含まれていないネイティブ Android モジュールに依存しています。Expo Go でウォレット接続に失敗するという報告があった場合、それが原因です。回避策はなく、expo run:android が必要です。

ウォレットをサポートしているのは Android のみです。iOS ビルドは実行できますが、MWA は利用できません。

まず、該当する状況を確認してください

状況	対応
まだプロジェクトがない	新しいプロジェクトを作成
Solana がまだ組み込まれていない既存の Expo アプリ	references/add-to-existing-app.md を読む
プロジェクトはあるが、ビルドまたはツールチェーンに問題がある	環境をチェック
プロジェクトはあり、ウォレット機能が必要	solana-mobile-wallet スキルを使用
ウォレット接続または署名をテストする必要がある	アプリなしでウォレットをテスト

新しいプロジェクトの作成

npx solana-mobile@latest create

デフォルトでは対話形式です。プロンプトを省略するには、プロジェクト名とテンプレートを指定してください。

npx solana-mobile@latest create my-app --template expo-kit-wallet

便利なフラグ：

フラグ	効果
-t, --template <id>	対話形式を使わずにテンプレートを選択
--pm <manager>	使用するパッケージマネージャー
--minimal	最小構成のテンプレートを使用
--list-templates	テンプレートカタログを表示
--list-template-ids	テンプレート ID を JSON 配列として表示
--skip-install	依存関係をインストールしない
--skip-git	git リポジトリを初期化しない
-d, --dry-run	実行内容を表示し、何も書き込まない

テンプレートの選択

テンプレートは2つの系統に分かれています。expo-kit-* テンプレートを選んでください。 @solana/kit は現在の Solana クライアントライブラリであり、CLI が最も積極的にメンテナンスしているテンプレートです。

既存の @solana/web3.js コードベースを意図的に引き継ぐ場合、または名前を指定して求められた場合に限り、expo-web3js-* を選んでください。理由を示さずに求められた場合は、そのまま応じる前に kit のほうがより適した出発点であることを伝えてください。web3.js を使った新しいアプリは、移行が必要な状態から始まるためです。

expo-kit-minimal は kit の各要素がどのように連携するかを示す最もわかりやすい参考例です。別のテンプレートを使って構築する場合も、一読する価値があります。

テンプレート	スタック	用途
expo-kit-wallet	Kit + MWA + Uniwind	最適なデフォルト。 ウォレット接続、署名、送信がすでに設定済み
expo-kit-minimal	Kit	UI キットなしの最小限の出発点
expo-kit-uniwind	Kit + Uniwind	Tailwind 風のスタイリング。ウォレットはまだなし
expo-kit-privy	Kit + Privy + Uniwind	MWA の代わり、または MWA と併用する Privy 認証
expo-web3js-wallet	web3.js + MWA	レガシーなウォレットアプリ
expo-web3js-paper	web3.js + RN Paper	レガシーな Material UI
expo-web3js-minimal	web3.js	レガシーな最小限の出発点

テンプレート ID は、完全な gh:solana-mobile/templates/mobile/<name> 形式でも指定できます。テンプレートが見つからないように見える場合は、この表をそのまま信頼するのではなく、--list-templates を再実行してください。カタログはこのスキルではなく、CLI に含まれています。

スキャフォールディング後

cd my-app && npm run android

これにより expo run:android が実行され、開発ビルドがビルドされてインストールされます。Android の初回ビルドは時間がかかります（Gradle のコールドスタート）。以降のビルドではキャッシュが再利用されます。

環境を確認する

ビルドの失敗をデバッグする前に、ツールチェーンを確認してください。

npx solana-mobile@latest doctor

不足しているものがあれば推奨事項とともに、ローカルの Android および Node のツールチェーンについて報告します。--json を指定すると安定した形式のレポートが出力されるため、特定のチェック結果に応じて処理を分岐する場合に解析できます。--verbose を指定すると、解決済みのパスと診断情報が追加されます。

ビルドの失敗がアプリのコードに明らかに起因するものでない場合は、まず doctor を実行してください。

Android エミュレーターを管理する

npx solana-mobile@latest emu list
npx solana-mobile@latest emu status
npx solana-mobile@latest emu create
npx solana-mobile@latest emu start my_phone
npx solana-mobile@latest emu stop my_phone

emu は emulator のエイリアスです。サブコマンドは create、delete、images、list、start、status、stop、tune です。システムイメージは emu images の下にあり（install、list、delete）、これらのコマンドで管理できます。

特定のデバイスプロファイルで名前付きエミュレーターを作成します。

npx solana-mobile@latest emu create local_phone --device pixel_9

新しいエミュレーターを準備する

新しく作成した AVD は、ウォレットを使う準備ができていません。起動しておらず、初回起動時のダイアログが表示される状態で、ウォレットアプリもインストールされていません。調整して起動してからウォレットアプリをインストールしてください。この順序にするのは、device install でインストールするにはデバイスが起動済みである必要があるためです。

npx solana-mobile@latest emu start local_phone --tune
npx solana-mobile@latest device install fakewallet

--tune を指定すると、新しい AVD でアプリに重なって表示されるアニメーション、初回起動時のダイアログ、ロック画面、通知が無効になります。調整はオプトインです。emu start と emu create --start で調整が適用されるのは、--tune を指定した場合のみです。また、この形式では対話的な操作が不要なため、スクリプトで使うのに最適です。作成時にこれらすべてを実行するには、emu create に --start --tune を指定します。

device install fakewallet は、Mobile Wallet Adapter のテスト用ウォレットを起動中のエミュレーターにインストールします。ウォレットアプリがないと、MWA は処理を引き渡す先がなく、接続を試みても何も起こりません。これは「エミュレーターで接続を試みても何も起きない」最も一般的な原因です。

Seeker Genesis Token が必要な機能には、引き続き実機の Seeker デバイスが必要です。エミュレーターにはトークンを保持できません。seeker-genesis-token スキルを参照してください。

接続済みデバイスを操作する

device は、エミュレーターと実機の両方で、adb 経由のすべての操作を扱います。

npx solana-mobile@latest device list                       # serials, states, names
npx solana-mobile@latest device install fakewallet         # catalog APK
npx solana-mobile@latest device install ./app-release.apk  # local file
npx solana-mobile@latest device open http://localhost:3000 # opens on the device
npx solana-mobile@latest device tune --all -y              # prepare for automation

device open は、ローカルホスト URL 用の adb reverse を自動で作成するため、このマシン上の開発サーバーに USB 接続したスマートフォンからアクセスできます。手動で adb reverse と am start を実行するよりも、こちらを使ってください。

device tune と emu tune は同じ調整を適用しますが、2 つの違いがあり、2 つ目はスクリプトで問題になります。device tune は実機を受け付け、--device <serial> または --all を指定できます。接続されているデバイスが 1 台だけの場合は、そのデバイスを使用します。emu tune はエミュレーター以外のシリアル番号を受け付けず、AVD 名またはシリアル番号を位置引数として指定します。引数がない場合は、エミュレーターが 1 台だけ実行中でも、また -y を指定して調整の確認を省略しても（エミュレーター選択の確認は省略されません）、選択画面が開きます。無人で実行する場合は、対象を指定してください。emu tune local_phone -y

ローカルバリデーターを実行する

npx solana-mobile@latest localnet start
npx solana-mobile@latest localnet check

localnet start は、ホスト上でバリデーターを起動し、接続中のすべてのデバイスにポートを転送するため、アプリからはバリデーターがデバイス上で動作しているかのように localhost:8899 にアクセスできます。すでに起動したローカルネットコンテナーを再利用し、すでにこれらのポートで応答しているバリデーター（Docker が不要なネイティブのものも含む）があれば接続し、どちらもない場合にのみコンテナーを起動します。 check は各デバイスからの到達性を確認します。マシン上では明らかに実行中のバリデーターをアプリから確認できない場合に、確認すべき項目です。

新しいデバイスを接続した後は localnet forward でポート転送を再適用できます。また、logs、status、stop はそれぞれの名前のとおりの動作をします。

アプリを使わずにウォレットをテストする

npx solana-mobile@latest playground

ウォレットのテストページを配信してデバイスで開き、すべての MWA 操作（接続、サインイン（SIWS）、メッセージへの署名、トランザクションへの署名、署名と送信）をターミナルに出力します。デフォルトでは devnet に対して実行されます。--cluster localnet を指定すると localnet バリデーターに接続し、mainnet では公開エンドポイントがブラウザー起点のリクエストを拒否するため、独自の --url が必要です。

これを使って、アプリの問題とセットアップの問題を切り分けてください。 プレイグラウンドでも署名できない場合、問題はデバッグ中のコードではなく、ウォレットまたはデバイスにあります。MWA ウォレットがインストールされている必要があります。インストールされていない場合は device install fakewallet を実行してください。

参考資料

• references/cli.md — templates と webshell を含む、solana-mobile のすべてのコマンドとフラグ
• references/add-to-existing-app.md — 既存の Expo アプリに Solana を組み込む方法：暗号ポリフィル、プロバイダー、依存関係
• references/troubleshooting.md — 既知の原因があるビルド、ポリフィル、エミュレーターの障害

関連スキル

• solana-mobile-wallet — ウォレットの接続、署名、トランザクションの送信
• solana-mobile-publishing — リリース APK に署名して dApp Store に公開
• seeker-genesis-token — Seeker デバイスの所有権を検証
• seeker-domains — .skr ドメイン名の解決

Anchor または Pinocchio プログラム、Codama クライアント生成、テスト、セキュリティレビューなど、モバイル以外の一般的な Solana 開発には、Solana Foundation の solana-dev スキルを使用してください。create はこれを .agents/skills/solana-dev/ にインストールするため、スキャフォールドしたプロジェクトにはすでに含まれています。

リンク

• CLI のソース：https://github.com/solana-mobile/solana-mobile-cli
• テンプレート：https://github.com/solana-mobile/templates
• Solana Mobile のドキュメント：https://docs.solanamobile.com