solana-mobile

Solana Mobile projects

Set up and maintain Solana Mobile apps. The solana-mobile CLI does the scaffolding, environment checks, and emulator management — prefer it over hand-rolled setup.

Run it without installing:

npx solana-mobile@latest --help

pnpx solana-mobile@latest and bun x solana-mobile@latest work too. Match whichever package manager the project already uses.

Non-negotiable constraint

Mobile Wallet Adapter requires a development build. Expo Go will not work — MWA depends on native Android modules that Expo Go does not bundle. If someone reports wallet connection failing in Expo Go, that is the cause; there is no workaround, they need expo run:android.

Android is the only platform with wallet support. iOS builds run, but no MWA.

First: work out which situation you are in

Create a new project

npx solana-mobile@latest create

Interactive by default. To skip the prompts, name the project and template:

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

Useful flags:

Choosing a template

Templates come in two families. *Pick an `expo-kit- template.** @solana/kit` is the current Solana client library, and these are the templates the CLI maintains most actively.

Reach for expo-web3js-* only when the user is deliberately continuing an existing @solana/web3.js codebase, or asks for it by name. If they ask without a reason, say kit is the better starting point before going along with it — a new app on web3.js starts life needing a migration.

expo-kit-minimal is the clearest reference for how the kit pieces fit together, and worth reading even when building on a different template.

Template ids are also accepted in full gh:solana-mobile/templates/mobile/<name> form. Re-run --list-templates rather than trusting this table if a template seems missing — the catalog ships with the CLI, not with this skill.

After scaffolding

cd my-app && npm run android

That runs expo run:android, which builds and installs the development build. The first Android build is slow (Gradle cold start); later builds reuse the cache.

Check the environment

Before debugging a build failure, check the toolchain:

npx solana-mobile@latest doctor

It reports on the local Android and Node toolchain with recommendations for anything missing. --json gives a stable report worth parsing when you need to branch on a specific check; --verbose adds resolved paths and diagnostics.

Run doctor first whenever a build fails for reasons that are not obviously in app code.

Manage Android emulators

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 is an alias for emulator. Subcommands: create, delete, images, list, start, status, stop. System images live under emu images (install, list, delete).

Create a named emulator on a specific device profile:

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

Testing wallet flows on an emulator

A fresh emulator has no wallet app installed, so MWA has nothing to connect to. Install an MWA-compatible wallet APK into the emulator first, or test on a physical Android device. Anything gated on the Seeker Genesis Token needs a real Seeker device — see the seeker-genesis-token skill.

Reference material

• references/add-to-existing-app.md — wiring Solana

into an Expo app that already exists: crypto polyfill, providers, dependencies

• references/troubleshooting.md — build, polyfill, and

emulator failures with known causes

Related skills

• solana-mobile-wallet — connecting wallets, signing, sending transactions
• seeker-genesis-token — verifying Seeker device ownership
• seeker-domains — .skr domain name resolution

For general non-mobile Solana work — Anchor or Pinocchio programs, Codama client generation, testing, security review — use the Solana Foundation's solana-dev skill instead. create installs it into .agents/skills/solana-dev/, so a scaffolded project already has it.

Links

• CLI source: https://github.com/solana-mobile/solana-mobile-cli
• Templates: https://github.com/solana-mobile/templates
• Solana Mobile docs: https://docs.solanamobile.com