# Metro: the JavaScript bundler that ships inside React Native > Metro is the bundler React Native projects already depend on, not a general-purpose web bundler you install on a whim. This is what it does, how to run it against a project, and where it stops being the right tool. **react/metro** — 🚇 The JavaScript bundler for React Native - Repository: https://github.com/react/metro - Website: https://metrobundler.dev - Stars: 5,642 · Forks: 698 - Language: JavaScript - License: MIT - Published: 2026-09-22 · Updated: 2026-09-22 · Language: en - Canonical page: https://hysenlabs.com/projects/react-metro ## The problem Metro solves, and who actually has that problem React Native applications are not served as static files from a web server. During development, a device or simulator has to fetch JavaScript from a local process, and that process has to resolve every require and import, transform JSX and Flow, and hand back something the runtime can execute. Metro is that process. The README describes it as "The JavaScript bundler for React Native" and lists three properties: sub-second reload cycles, working with thousands of modules in a single application, and support for every React Native project out of the box. The audience is therefore narrow and specific: people building React Native apps, and people maintaining tooling around them. If you are shipping a website, this is not the tool you are looking for, and the README makes no claim that it is. ## What the repository layout says about how Metro is built Metro is a monorepo. The top-level listing shows a packages/ directory alongside private/, scripts/, docs/ and website/, and the root package.json is named @metro/monorepo with "private": true and version 0.0.0. That is the standard shape for a project that publishes many packages from one repository rather than a single artifact. The root package.json also carries a build script that runs yarn run build-ts-defs before node ./scripts/build.js, and a build-ts-defs script that runs ./scripts/generateTypeScriptDefinitions.js through @babel/register. Two details stand out. First, the type definitions are generated rather than hand-written, which is a deliberate choice for a codebase that is otherwise Flow-typed (the repository has a .flowconfig and flow-bin in devDependencies). Second, the build pipeline is a script in this repository, not a wrapper around a generic bundler, which is consistent with Metro being its own bundler. The docs/ directory holds the documentation source; the README states that all available documentation lives on the Metro website. ## Installing Metro and running a first build The README is explicit that you do not normally install Metro yourself. It says Metro is included with React Native and points to the React Native documentation to get started. The README does not print an install command, and it does not print a start command either, so the two steps it describes are: create or open a React Native project following the React Native docs, then run the development server that project provides. For adding Metro to a project that is not a fresh React Native scaffold, the README sends you to the Getting Started guide on metrobundler.dev rather than describing the steps inline. That guide is the source for configuration keys, and the README separately links the configuration page for the full option list. Read both before editing anything, because the README itself documents no configuration keys at all. If you want to work on Metro itself rather than use it, the root package.json defines the build entry point as yarn run build, which first generates TypeScript definitions and then runs ./scripts/build.js. ## Where Metro is the wrong tool Metro is scoped to React Native. The README's third bullet is "Supports every React Native project out of the box", which is a statement about React Native projects specifically, not about JavaScript projects in general. If your target is a browser, the ecosystem's established bundlers assume a different module resolution model, a different set of platform targets, and a different set of output formats; Metro's design is oriented around a native runtime fetching a bundle from a dev server. The second limitation is documentation placement. The README contains no configuration reference, no list of CLI flags, and no troubleshooting section. Everything routes to metrobundler.dev. That is fine for a project this widely used, but it means this repository alone is not enough to answer an operational question, and anyone evaluating Metro from the README will come away knowing very little about how to configure it. A third constraint is version coupling: because Metro ships with React Native, the version you get is tied to your React Native version, and the release history shows several maintained lines at once, with v0.87.1, v0.84.6 and v0.84.5 all published within weeks of each other. Upgrading Metro independently of React Native is not the normal path. ## How Metro differs from Vite and webpack Vite and webpack both build for browsers and treat the dev server as a convenience around a production build. Metro's centre of gravity is the opposite: the development server is the primary artifact, and the bundle it produces is consumed by a native runtime. That difference shows up in the README's own priorities. "Fast" is defined there as sub-second reload cycles and fast startup, which are interactive-development metrics, not production-build metrics. "Scalable" is defined as working with thousands of modules in a single application, which is a statement about graph size during development. Neither bullet is about tree shaking, code splitting for the web, or output size optimisation. If your evaluation criteria are web bundle size and long-term caching, you are measuring Metro against a job it was not built for, and the comparison will mislead you. ## Maintenance, releases and what the MIT licence means here The repository is not archived, and its last push was on 2026-09-22, so it is being worked on. Release cadence is visible in the tags: v0.87.1 on 2026-09-13, v0.84.6 on 2026-09-02 and v0.84.5 on 2026-08-19. The presence of a 0.84 line receiving patches after 0.87 shipped indicates that older lines are maintained in parallel, which matters if you are pinned to an older React Native version. The repository also carries a CHANGELOG.md, so release notes are the place to check before upgrading. Metro is MIT licensed, as stated in the README and confirmed by the LICENSE file at the repository root. MIT is permissive: it allows use, modification and redistribution with the licence and copyright notice retained. That is a general description of the licence text, not advice about your situation; if your organisation has rules about dependency licences, run your own review. Note also that the README references a Meta Code of Conduct and a contributing guide, which govern contribution to the project rather than use of it. ## Contributing and where design decisions get made The README explains why Metro lives in its own repository: it was previously part of facebook/react-native, and the team moved it so it would be easier to respond to issues and pull requests, citing react-native#13976 for the original announcement. Contributions go through CONTRIBUTING.md, which the README links. Larger proposals do not happen in this repository at all. The README states that bigger discussions concerning React Native and Metro take place in the @react-native-community/discussions-and-proposals repository. That is worth knowing before you open an issue proposing a design change: the README is telling you the venue is elsewhere. ## Conclusion Adopt Metro if you are building a React Native application, because it is the bundler React Native projects use out of the box and the standalone repository now takes issues and pull requests directly. Do not adopt it as a general web bundler for a browser-only application; the README frames it around React Native, and nothing in the repository positions it as a replacement for a web build tool. Before committing, verify two things: that your project's React Native version pins a Metro release you are willing to run, and that the configuration options you need are documented on metrobundler.dev, since the README itself only points there rather than listing them. ## FAQ ### Is Metro the same thing as MetroPCS? No. MetroPCS is a mobile carrier, and this Metro is the JavaScript bundler for React Native, maintained under the react organisation on GitHub. The two share only a name. ### What does Metro mean in this project? In this repository, Metro is the name of the JavaScript bundler used by React Native. The README describes it as the bundler for React Native and notes that it was previously part of the react-native repository. ### How do I install Metro? You normally do not install it separately. The README states that Metro is included with React Native and directs you to the React Native documentation to get started; to add Metro to an existing project it points to the Getting Started guide on metrobundler.dev. ## Sources - [License: MIT](https://github.com/react/metro/blob/main/LICENSE) - [Project website](https://metrobundler.dev) - [react/metro on GitHub](https://github.com/react/metro) - [README](https://github.com/react/metro/blob/main/README.md) - [Releases](https://github.com/react/metro/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/react-metro