MetaMask/metamask-extension: Building the Wallet Extension from Source

What the MetaMask extension repository is for

This is the source of the browser extension that injects an Ethereum provider into web pages and gives users a wallet UI. The README describes it as enabling browsing of Ethereum blockchain enabled websites, and lists Firefox, Google Chrome and Chromium-based browsers as supported, with a recommendation to use the latest browser version. The repository is public, the default branch is main, and the last push was on 2026-09-21, with releases v13.49.0, v13.48.0 and v13.47.1 in the days before that. It is not archived.

The audience is narrower than the user base. Someone who wants a wallet should install the published build from metamask.io; the README points users to the official website and to the user support site instead of to the source. The repository is for people who contribute to the extension itself, which the README routes through the Extension Docs under docs/, and for people who build MetaMask-compatible applications, which it routes to the separate developer docs. If you are in neither group, the source tree is a very large TypeScript codebase with no payoff for you.

How the extension is put together: app, ui, shared and the build pipeline

The top-level layout separates concerns in a way that is worth understanding before you touch anything. There is app/, which holds the extension-side code, ui/, which holds the interface, shared/, and types/. Configuration sits alongside them: jest.config.js and jest.integration.config.js for unit and integration tests, playwright.config.ts for browser tests, tailwind.config.js and stylelint.config.js for styling, and a set of eslintrc files split by target (base, babel, node, typescript-compat).

The build is where the repository shows its age and its discipline at the same time. package.json exposes a webpack entry point at development/webpack/launch.ts, and a parallel Lavamoat path: webpack:lavamoat runs the same build under a policy file at lavamoat/webpack/build/policy.json with an override at policy-override.json, and webpack:lavamoat:build runs it in production mode with no cache. Lavamoat is a dependency-sandboxing system, and its presence here means the shipped bundle is built against an explicit allowlist of what dependencies may do. Two build paths exist because the policy has to be regenerated when dependencies change, via webpack:lavamoat:policy:build. The manifest is also overridable: a .manifest-overrides.json file at the root, pointed at by MANIFEST_OVERRIDES in .metamaskrc, injects flags into the built manifest.json, and the README notes that editing _flags.remoteFeatureFlags in dist/browser/manifest.json works too but is overwritten on the next build.

Installing the MetaMask extension build on Chrome or Firefox locally

The documented local build needs Node.js version 24. The README recommends nvm, where `nvm use` picks the version from the repository, and the .nvmrc file in the root exists for exactly that. After that, Corepack supplies Yarn per project rather than a global install:

corepack enable
yarn install

Corepack reads the packageManager property in package.json. The README is explicit that modern Yarn releases are not meant to be installed globally or through npm, so skip the global install.

Before the build will produce a working extension you need a configuration file. The README says to duplicate .metamaskrc.dist and rename it to .metamaskrc, then replace INFURA_PROJECT_ID with a personal Infura API key:

cp .metamaskrc{.dist,}

An Infura account can be created for free, and the README links to the registration page. Two optional keys are documented: SEGMENT_WRITE_KEY if you are debugging MetaMetrics, and SENTRY_DSN if you are debugging unhandled exceptions. A PASSWORD value can be set to skip entering your development wallet password each time the app opens.

With that in place, the build command depends on the browser target:

yarn dist
yarn dist:mv2

The first is for Chromium-based browsers, the second for Firefox. The README describes `yarn start` and `yarn start:mv2` as development builds for the same two targets. Uncompressed output lands in /dist and compressed builds in /builds. Loading the result is a manual step: the README links to docs/add-to-chrome.md and docs/add-to-firefox.md rather than repeating the steps here, so those two files are what you follow next. If you develop on a fork, the README warns that the default Infura key is on the Free Plan with very limited requests per second, which is the single most likely reason a fork build appears to hang or fail.

Codespaces quickstart and what it costs you

The README offers a second path: GitHub Codespaces, which it claims gets a development environment running in under five minutes. The steps are a button, a remote VS Code window, a noVNC session inside a Simple Browser tab, a roughly twenty second wait on first launch for scripts to finish, then a right-click on the noVNC desktop to launch Chrome or Firefox with MetaMask pre-installed. Editing code and running `yarn start` rebuilds in a minute or two and the change appears in the noVNC desktop.

The cost is stated plainly and is the reason to think before defaulting to it. GitHub applies a limited free monthly quota, and after that it bills for both running time and storage. Codespaces pause after 30 minutes of inactivity and auto-delete after 30 days of inactivity, and the README warns that several idle Codespaces can exhaust a storage quota, suggesting you keep one or two long-term and switch branches on them rather than creating new ones. That last piece of advice is the practical one: reuse, do not accumulate.

Where the repository documentation stops

The README is a build guide, and it is thin on everything else. It does not document rollback, migration between extension versions, or what happens to a user's state when a build is replaced. It says nothing about how the extension handles key material beyond pointing at external documentation, and the repository's LICENSE file is present but the project is classified as NOASSERTION, meaning no standard licence identifier is asserted. Anyone who needs to know the terms before redistributing a build has to read LICENSE themselves; nothing in the README summarises it.

The build itself carries constraints that are easy to underestimate. Node 24 is pinned, not a range. Corepack is required. The Lavamoat policy means a dependency that does something outside the policy will fail the build rather than silently ship, which is the point, but it also means upgrading a dependency can require regenerating policy files through the policy scripts. And the default Infura key on a fork is rate-limited, so a build that compiles cleanly can still be unusable for browsing. The README does not document how to verify a build's integrity or how to compare a local build against the published one.

MetaMask extension versus building on a wallet library

The real alternative for most teams is not another extension. It is not building an extension at all. A team that wants a wallet inside a web page can use a wallet library directly and let users bring whatever wallet they already have, which is the approach the README points at when it sends developers to the MetaMask developer docs for building compatible applications. The difference in approach is structural: this repository is a full browser extension with a UI, a background process, a build pipeline, an extension manifest and a release cadence of roughly weekly version bumps, while a library integration is a dependency in your own application with none of that. If your goal is to let users connect a wallet, the extension repository is the wrong artifact to start from. If your goal is to change what the extension itself does, there is no alternative that gives you the same reach across Chrome, Firefox and Chromium browsers.

Contributing, the skills tooling and the release cadence

Contribution routes are separated in the README. General contribution guidance lives in the MetaMask contributor-docs repository, and contribution to this extension specifically lives in docs/ inside this repository. The repository also carries AGENTS.md and a .cursor/ directory, and the README documents an `yarn skills` command under which AI coding agents such as Cursor, Claude Code and Codex consume shared skills from the MetaMask/skills repository, with an optional private overlay configured through .skills.local.example. That is a real signal about how the project expects day-to-day work to happen, and it is unusual enough to be worth knowing before you open a pull request.

The release cadence is visible in the tag list: v13.49.0 on 2026-09-17, v13.48.0 on 2026-09-11, v13.47.1 on 2026-09-10, with package.json at version 13.51.0. That frequency cuts both ways. Fixes arrive quickly, and a fork drifts from upstream within days. If you patch the extension for internal use, budget for rebasing against main rather than treating your fork as a stable base.

Editorial conclusion

Adopt this repository if you need to read, patch or audit the wallet that ships to Chrome, Firefox and Chromium users, and you can commit to Node 24, Corepack and a personal Infura project ID. Do not adopt it as a way to get a wallet onto a phone, Safari or an Android browser: the README names only Firefox, Chrome and Chromium-based browsers, and no mobile build is documented. Before you spend a day on it, confirm that `yarn dist` produces a loadable `/dist` folder on your machine and that the Infura key you put in `.metamaskrc` is your own rather than the shared default.

Frequently asked questions

Official sources

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