Metaplex Umi Mobile Template

Forked from the original Solana Mobile Expo Template

⚠️ IMPORTANT: This template requires configuration before wallet connections will work!

This template will NOT work out-of-the-box. Wallet connections require:

• Your own domain with SSL certificate
• Hosted app association files (assetlinks.json / apple-app-site-association)
• App signing certificates that match the hosted files
• Updated configuration with your domain and credentials

See Deep Links Setup Guide for mandatory configuration steps.

Beta Notice: This template uses @tonyboyle/solana-wallet-universal-links-generator for wallet connections, which is currently in beta. While it's been performing reliably in testing, you may encounter occasional bugs with the connection flow. Rest assured, this doesn't impact the security of your transactions or signing operations - those are handled entirely within the wallet app's secure environment.

---

This template is a ready-to-go React Native dApp built with Expo that features:

Key Features

• Deep Link Wallet Adapter: New wallet connection system using universal links
• Dual Compatibility: Works with both web3.js and Umi libraries
• Global State Management: Zustand-powered authentication store
• React Navigation: Complete navigation setup with nested navigators
• Token Transfers: Built-in transfer functionality
• Responsive UI: Clean, mobile-optimized interface

Note for iOS Development: While this app works on both Android and iOS, iOS development requires testing on physical devices. iOS simulators cannot install wallet apps from the App Store, so wallet functionality can only be tested on actual iOS devices.

Tech Stack

Library	Category	Version	Description
React Native	Mobile Framework	v0.76	Cross-platform mobile framework
Expo	SDK	v52	Expo development platform
React	UI Framework	v18.3	UI framework
Metaplex Umi	SDK	Latest	Metaplex framework for Solana development
Solana web3.js	SDK	v1.78	General Solana library for transactions and RPCs
spl-token	SDK	v0.4	Library for building with Solana SPL tokens
React Navigation	Navigation	v6	Navigation framework
Zustand	State management	Latest	Global state management for authentication
TypeScript	Language	v5	Static typechecking
Deep Link Adapter	Wallet Connection	Beta	Universal links wallet connection system

Quick Start

Prerequisites

• A free Expo account
• An Android device/emulator to test your app
  • Install a wallet app that supports deep links (Phantom, Solflare, etc.)
• A domain you control with SSL certificate (required for wallet connections)
• App signing certificates (EAS can generate these)
• If using Expo's cloud service eas build, no further setup is required
• If building locally:
  • React Native and Android Environment setup

Setup

1. Clone this repository
2. Install dependencies: npm install or yarn install
3. MANDATORY: Configure deep links following SETUP_DEEPLINKS.md
4. Update your domain configuration in the app

Build and run the app

Create a custom development build:

npx expo install --fix
eas build --profile development --platform android

Then install and run the app on your device.

Troubleshooting

• Metro has encountered an error: While trying to resolve module @solana-mobile/mobile-wallet-adapter-protocol...

  • This is an on-going issue when using npm install to install the Expo template.
  • To mitigate, clean your project dependencies and reinstall with yarn install

• The package 'solana-mobile-wallet-adapter-protocol' doesn't seem to be linked. Make sure: ...

  • Ensure you are NOT using Expo Go to run your app.
  • You need to be using an Expo custom development build, rather than Expo Go.

• failed to connect to...

  • This is an Expo error that can occur when trying to connect to the dev server on certain Wifi networks.
  • To fix, try starting the dev server with the --tunnel command (npx expo start --dev-client --tunnel)

• Error: crypto.getRandomValues() not supported

  • This is a polyfill issue when trying to use certain functions from the @solana/web3.js in a React Native/Expo environment.
  • To fix, ensure your App properly imports and uses the polyfills like in this guide.

• error Failed to load configuration of your project.
  • Same as above, but for yarn. Uninstall and reinstall the CLI through yarn.

• Looks like your iOS environment is not properly set:
  • You can ignore this during template initialization and build the Android app as normal. This template is only compatible with Android.

• Usage Error: It seems you are trying to add a package using a https:... url; we now require package names to be explicitly specified.
  • This error happens on certain versions of yarn, and occurs if you try to initialize the template through the Github repo URL, rather than the npm package. To avoid this, use the @solana-mobile/solana-mobile-dapp-scaffold package as specified, or downgrade your yarn version to classic (1.22.x).

• error Couldn't find the ".../@solana-mobile/solana-mobile-dapp-scaffold/template.config.js file inside "@solana-mobile/solana-mobile-dapp-scaffold" template.
  • This is a known error that occurs with certain versions of yarn (>= 3.5.0). It is fixed by running the cli command with the --npm flag or downgrading your version of yarn.