MetaMask Mobile: building the Ethereum dapp browser from source

What MetaMask Mobile is, and who should clone it

The README describes MetaMask as a mobile wallet that provides access to websites that use the Ethereum blockchain. That single sentence covers two products in one binary: a key-holding wallet and a browser that injects an Ethereum provider into the pages you visit. The repository is the source of that app, written in TypeScript on React Native, with android/ and ios/ directories for the platform shells and app/ for the shared JavaScript. If you want a wallet, install it from an app store. If you need to change how the wallet behaves on a specific chain, reproduce a signing bug, or ship a branded build to a group of testers, this is the codebase you work in. The topic list (android, dapps-browser, ios, react-native, web3) matches that scope. Note that the repository is a client, not a service: nothing here gives you a backend, an indexer or a hosted wallet.

The Infura project ID is the first hard gate

Before any UI appears, the app needs a way to reach blockchain networks, and the README is explicit that this comes from an Infura project ID. External contributors create an account at developer.metamask.io, generate an API key, and place it in MM_INFURA_PROJECT_ID inside .js.env.example, which they then rename to .js.env. Internal contributors pull the same file from 1Password. The README carries a caution block stating that without an Infura project ID the app cannot connect to blockchain networks. This is the single most common reason a fresh clone looks broken: the bundler runs, the JavaScript loads, and every network call fails. Treat the key as a build-time input, not a runtime setting you can fix later in a menu.

Expo first: the fastest path to a running build

The README recommends Expo because it removes native compilation from the loop. You download a precompiled development build, run the JavaScript bundler, and the build connects to the bundler to load your code. Start by installing node, yarn v4 and watchman as described in the Expo environment document, then clone and install.

git clone [email protected]:MetaMask/metamask-mobile.git && \
cd metamask-mobile
yarn setup:expo

With dependencies installed, start the bundler. The README's command is yarn watch, which runs ./scripts/build.sh watcher.

yarn watch

The next step is the part that surprises people. The development builds are produced by the Expo Dev Build GitHub Actions workflow, which runs on every push to main but only compiles iOS or Android when the @expo/fingerprint hash of native code has changed since the previous build, plus a weekly Monday refresh. Most pushes reuse an existing artifact, so the build you install may be older than main HEAD, and the README says that is expected. You need the GitHub CLI authenticated with access to the repository. Then:

yarn install:ios:dev
yarn install:android:dev

Artifacts land under build/ as MetaMask.app on iOS and metamask-dev.apk on Android, and the workflow run id is written to build/expo-dev-build-run-id.txt. Re-runs skip the download when the artifact digest matches a local cache; add --force-download to bypass that, or --run RUN_ID to pin a specific workflow run. On a simulator, pick the bundler URL from the initial Expo screen or press a or i in the bundler terminal. On a physical device, scan the QR code the bundler prints. If you need to check the workflow manually, the README gives gh run list --repo MetaMask/metamask-mobile --workflow expo-dev-build.yml --branch main --status success --limit 5, and warns that a recent successful run may have no artifacts attached because the build job was skipped.

When the precompiled build stops being enough

The Expo shortcut has a clear boundary. The README states that if you develop or modify native code, or install any library that introduces or uses native code, you cannot use a precompiled development build and must compile the native side yourself, following the Native Development Environment Setup document. That means Xcode and CocoaPods on the iOS side (the repository ships a Gemfile, a .ruby-version and a pod:install script) and the Android toolchain on the other, with ccache.conf and .buckconfig present in the tree. The practical consequence is that the fingerprint mechanism which makes Expo fast is also the thing that hides your native changes: a precompiled artifact will not contain them. If your task is a JavaScript-only change, stay on Expo. If it touches a native module, budget the setup time before you start.

What the repository does not tell you

Several things a newcomer would reasonably look for are absent from the README. There is no documented rollback path for a development build: the install scripts cache artifacts under build/gh-expo-dev-build/ and the README only explains how to force a fresh download, not how to return to a previous one. The README also does not state which Node.js version is required, even though .nvmrc exists at the repository root, so read the file rather than guessing. The licence is listed as NOASSERTION on GitHub rather than a recognised identifier, and the README does not summarise the terms; the LICENSE file at the root is the only authority, and whether you can redistribute a modified build is a question for that file and, if it matters commercially, for a lawyer. Finally, the README does not describe the app's own privacy behaviour or what the bundled analytics do, so a team evaluating this code for a regulated deployment has research left to do outside this repository.

How it differs from wallet libraries and from the browser extension

MetaMask Mobile is often compared with two different things, and the differences are structural. Against a wallet library such as ethers or web3.js, the distinction is that this repository is a complete application: it owns the key storage, the UI, the transaction confirmation flow, the dapp browser and the release pipeline, and you cannot import it into another app the way you import a signing library. Against the MetaMask browser extension, the difference is the runtime. The extension lives in a desktop browser and relies on that browser's extension APIs; this project is a React Native application with its own android/ and ios/ projects, its own Expo fingerprinting, and its own native build requirements. A fix that lands in one does not automatically exist in the other, and the release cadence here is visible in the version tags (8.10.2, 8.11.0, 8.12.0 across September 2026) rather than in extension store updates. If your goal is to embed wallet functionality inside a product you already ship, neither of these is the right shape; you want a library, not an app.

Maintenance, release cadence and the cost of staying current

The repository is not archived, and the last push was on 2026-09-23, one day before this assessment, so it is being worked on continuously rather than maintained at a distance. Releases are frequent: 8.10.2 on 2026-09-09, 8.11.0 on 2026-09-15 and 8.12.0 on 2026-09-21, while package.json carries version 8.14.0, which tells you the tree moves faster than the tags. That cadence is the real upgrade cost. A fork that patches a single behaviour will need to rebase against a moving main branch, and the repository includes a CLA workflow, a changelog lint script and a messenger-action-types check in the lint pipeline, so contributions are expected to match the project's own conventions. The dependency surface is large (React Native, Expo, native toolchains, a Ruby Gemfile for iOS pods), and the Expo fingerprint mechanism means your local artifact can silently lag the code you just pulled. Plan for periodic clean installs rather than incremental ones.

Editorial conclusion

This repository is for engineers who need to read, patch or build the MetaMask mobile client itself, not for people who just want a wallet on their phone. Adopt the Expo path first: run yarn setup:expo, then yarn watch, then yarn install:ios:dev or yarn install:android:dev, and confirm your .js.env holds a working MM_INFURA_PROJECT_ID before blaming the bundler for a blank app. Anyone modifying native modules should skip the precompiled dev build entirely and read the Native Development Environment Setup document. Before committing time, check the LICENSE file at the repository root, since the GitHub listing reports NOASSERTION rather than a named licence, and that determines what you may do with a fork.

Frequently asked questions

Official sources

1. Issues
2. MetaMask/metamask-mobile on GitHub
3. Project website
4. README
5. Releases