DOCSEARCHbyAlgolia
Submit Docs

Metro Bundler Documentation

repository·main·Indexed 26 days ago

https://github.com/react/metro

A high-performance JavaScript bundler designed specifically for React Native, optimized for fast reload cycles and scalability. The documentation covers core API functions like runBuild and runServer, configuration via metro-config, resolution logic with metro-resolver, and various bundling formats including Plain, Indexed RAM, and File RAM bundles. It also details caching strategies using FileStore and HttpStore, as well as the experimental metro-file-map for file system crawling.

Tokens
30.4K
Snippets
53
Records
210
Agent score
90%

What's inside Metro

  2. Overview of [Experimental] Metro File Map

    main

    Metro File Map is an experimental package used for file system crawling, watching, and mapping within the Metro bundler ecosystem. It is originally a fork of jest-haste-map.

    Warning: This package is currently considered experimental. The API is treated as internal, meaning it is subject to change without semver-breaking guarantees. If you intend to use metro-file-map APIs directly in your own project, it is recommended to raise an issue to discuss your use case with the maintainers first.

  3. Overview of Metro bundler

    main
    Metro is the JavaScript bundler designed specifically for React Native. It is optimized for high performance with sub-second reload cycles, fast startup times, and quick bundling speeds. It is built to be scalable, supporting applications with thousands of modules, and provides out-of-the-box integration for React Native projects.

  4. Use ob1 for type-checked 0- and 1-based offsets

    main
    ob1 is a small library designed to handle 0-based and 1-based offsets using type-safe mechanisms. It helps prevent common off-by-one errors by distinguishing between these two indexing types at the type level.

  5. Understand Metro's Resolution Types

    main

    Metro's resolver can return one of three resolution types for a given module name and platform:

    1. Source file: The request is resolved to an absolute path representing a physical file on disk.
    2. Asset files: The request is resolved to one or more absolute paths representing physical files on disk (e.g., images).
    3. Empty module: The request is resolved to a built-in empty module, as specified by the resolver.emptyModulePath configuration.

  6. Understand Metro bundle formats

    main

    Metro supports three different bundling formats depending on the target environment. Note that in all formats, modules are assigned numeric IDs, which means dynamic require calls are not supported. Requires are transformed into references to these numeric IDs.

    Supported formats:

    1. Plain bundle: A standard JavaScript bundle where all files are wrapped in function calls and added to a global file. Ideal for environments expecting a pure JS bundle, such as a web browser. Triggering a build is typically done by requiring the entry point with the .bundle extension.
    2. Indexed RAM bundle: A binary format optimized for environments that load all code into memory at once (e.g., iOS). It uses an offset table for constant-time module loading.
    3. File RAM bundle: A format where each module is stored as an individual file. This is optimized for environments like Android where accessing specific files within a zipped package is faster than unzipping a large single binary.

  8. Understand Metro module resolution

    main
    Module resolution is the process Metro uses at build time to translate module names (e.g., import {View} from 'react-native') into specific file paths (e.g., node_modules/react-native/index.js). Metro uses a version of Node's module resolution algorithm but includes several specialized features for React Native environments.

  9. Understand the Metro bundling process

    main

    Metro is a JavaScript bundler that converts an entry file and its dependencies into a single JavaScript file. The bundling process consists of three distinct stages:

    1. Resolution: Metro builds a dependency graph starting from the entry point. It uses a resolver to locate required files.
    2. Transformation: Modules are transpiled into a format compatible with the target platform (e.g., React Native). This stage runs in parallel across available CPU cores.
    3. Serialization: Once transformed, a serializer combines the modules into one or more bundles (single JavaScript files).

  10. Use ES Modules syntax (`import` and `export`)

    main

    To use ES Modules (import and export) in Metro projects, it is recommended to use @babel/plugin-transform-modules-commonjs.

    Note: If you are using @react-native/babel-preset in a React Native project, import and export are supported automatically.

  11. Configure the Metro configuration structure

    main

    Metro configuration is organized into modules. A standard metro.config.mts file uses the MetroConfig type and contains top-level objects for resolver, transformer, serializer, server, and watcher.

    // metro.config.mts
import type {MetroConfig} from 'metro-config';

const config: MetroConfig = {
  /* general options */

  resolver: {
    /* resolver options */
  },
  transformer: {
    /* transformer options */
  },
  serializer: {
    /* serializer options */
  },
  server: {
    /* server options */
  },
  watcher: {
    /* watcher options */
    watchman: {
      /* Watchman-specific options */
    }
  }
};

export default config;