Solana Mobile projects
Set up and maintain Solana Mobile apps. The
CLI does the scaffolding,
environment checks, and emulator management — prefer it over hand-rolled setup.
Run it without installing:
bash
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
.
Android is the only platform with wallet support. iOS builds run, but no MWA.
First: work out which situation you are in
| Situation | Do this |
|---|
| No project yet | Create a new project |
| Existing Expo app, no Solana | Read references/add-to-existing-app.md |
| Project exists, build or toolchain broken | Check the environment |
| Project exists, needs wallet features | Use the skill |
Create a new project
bash
npx solana-mobile@latest create
Interactive by default. To skip the prompts, name the project and template:
bash
npx solana-mobile@latest create my-app --template expo-kit-wallet
Useful flags:
| Flag | Effect |
|---|
| Pick a template non-interactively |
| Package manager to use |
| Use the minimal template |
| Print the template catalog |
| Print template ids as a JSON array |
| Do not install dependencies |
| Do not initialise a git repo |
| Show what would happen, write nothing |
Choosing a template
Templates come in two families.
Pick an template. is the current
Solana client library, and these are the templates the CLI maintains most actively.
Reach for
only when the user is deliberately continuing an existing
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.
is the clearest reference for how the kit pieces fit together, and worth
reading even when building on a different template.
| Template | Stack | Use for |
|---|
| Kit + MWA + Uniwind | Best default. Wallet connect, sign, send already wired |
| Kit | Bare starting point, no UI kit |
| Kit + Uniwind | Tailwind-style styling, no wallet yet |
| Kit + Privy + Uniwind | Privy auth instead of, or alongside, MWA |
| web3.js + MWA | Legacy wallet app |
| web3.js + RN Paper | Legacy, Material UI |
| web3.js | Legacy bare starting point |
Template ids are also accepted in full
gh:solana-mobile/templates/mobile/<name>
form.
Re-run
rather than trusting this table if a template seems missing — the
catalog ships with the CLI, not with this skill.
After scaffolding
bash
cd my-app && npm run android
That runs
, 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:
bash
npx solana-mobile@latest doctor
It reports on the local Android and Node toolchain with recommendations for anything
missing.
gives a stable report worth parsing when you need to branch on a specific
check;
adds resolved paths and diagnostics.
Run
first whenever a build fails for reasons that are not obviously in app code.
Manage Android emulators
bash
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
is an alias for
. Subcommands:
,
,
,
,
,
,
. System images live under
(
,
,
).
Create a named emulator on a specific device profile:
bash
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
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
- — connecting wallets, signing, sending transactions
- — verifying Seeker device ownership
- — domain name resolution
For general non-mobile Solana work — Anchor or Pinocchio programs, Codama client generation,
testing, security review — use the Solana Foundation's
skill instead.
installs it into
.agents/skills/solana-dev/
, so a scaffolded project already has it.
Links