Module Resolution

Module resolution is the process of translating module names to module paths at build time. For example, if your project contains the code:

// src/App.js
import {View} from 'react-native';
// ...

Metro needs to know where in your project to load the react-native module from. This will typically resolve to something like node_modules/react-native/index.js.

Likewise, if your project contains the (similar) code:

// src/App.js
import Comp from './Component';
// ...

Metro needs to understand that you are referring to, say, src/Component.js, and not another file named Component that may also exist elsewhere.

Metro implements a version of Node's module resolution algorithm, augmented with additional Metro-specific features.

These Metro-specific features include:

• Haste: An opt-in mechanism for importing modules by their globally-unique name anywhere in the project, e.g. import Foo from 'Foo'.
• Platform extensions: Used by React Native to allow developers to write platform-specific versions of their JavaScript modules.
• Asset extensions and image resolutions: Used by React Native to automatically select the best version of an image asset based on the device's screen density at runtime.
• Custom resolvers: Metro integrators can provide their own resolver implementations to override almost everything about how modules are resolved.

Resolution algorithm

Given a resolution context context, a module name moduleName, and an optional platform identifier platform, Metro's resolver performs RESOLVE(context, moduleName, platform), which either returns one of the resolution types, or throws an error.

Resolution types

Source file

The request is resolved to some absolute path representing a physical file on disk.

Asset files

The request is resolved to one or more absolute paths representing physical files on disk.

Empty module

The request is resolved to a built-in empty module, namely the one specified in resolver.emptyModulePath.

Algorithm

note

These are the rules that Metro's default resolver follows. Refer to metro-resolver's source code for more details.

RESOLVE

Parameters: (context, moduleName, platform)

1. If a custom resolver is defined, then
   1. Return the result of the custom resolver.
2. If moduleName is an absolute path, or equal to '.' or '..', or begins './' or '../'
   1. Let absoluteModuleName be moduleName if it is absolute path, otherwise the result of prepending the current directory (i.e. parent of context.originModulePath) with moduleName.
   2. Return the result of RESOLVE_MODULE(context, absoluteModuleName, platform), or continue.
3. If moduleName begins '#'
   1. Throw an error. This will be replaced with subpath imports support in a non-breaking future release.
4. If moduleName parses as a URL, let scheme be the lowercased scheme (the prefix before ':'), then
   1. If context.schemeResolvers has a resolver registered for scheme, return the result of calling it with (context, moduleName, platform), where context.resolveRequest is set to the default resolver for chaining.
   2. Otherwise, continue to the following steps, but if none of them resolve moduleName, throw a scheme-specific error at step 11 rather than a generic resolution failure. (This fallback exists for backwards compatibility with projects using scheme-like specifiers via Haste or extraNodeModules, and is deprecated.)
5. Apply BROWSER_SPEC_REDIRECTION to moduleName. If this is false:
   1. Return the empty module.
6. If Haste resolutions are allowed, then
   1. Get the result of RESOLVE_HASTE(context, moduleName, platform).
   2. If resolved as a Haste package path, then
      1. Perform the algorithm for resolving a path (step 2 above). Throw an error if this resolution fails. For example, if the Haste package path for 'a/b' is foo/package.json, perform step 2 as if moduleName was foo/c.
7. If context.unstable_enablePackageExports is enabled, then
   1. Get the result of PACKAGE_SELF_RESOLVE(context, moduleName, platform).
   2. If resolved, return result.
8. If context.disableHierarchicalLookup is not true, then
   1. Try resolving moduleName under node_modules from the current directory (i.e. parent of context.originModulePath) up to the root directory.
   2. Perform RESOLVE_PACKAGE(context, modulePath, platform) for each candidate path.
9. For each element nodeModulesPath of context.nodeModulesPaths:
   1. Try resolving moduleName under nodeModulesPath as if the latter was another node_modules directory (similar to step 8 above).
   2. Perform RESOLVE_PACKAGE(context, modulePath, platform) for each candidate path.
10. If context.extraNodeModules is set:
    1. Split moduleName into a package name (including an optional scope) and relative path.
    2. Look up the package name in context.extraNodeModules. If found, then
       1. Construct a path modulePath by replacing the package name part of moduleName with the value found in context.extraNodeModules
       2. Return the result of RESOLVE_PACKAGE(context, modulePath, platform).
11. If no valid resolution has been found, throw a resolution failure error — a scheme-specific error if step 4.2 applied, otherwise a generic one.

RESOLVE_MODULE

Parameters: (context, moduleName, platform)

1. Let filePath be the result of applying BROWSER_SPEC_REDIRECTION to moduleName. This may locate a replacement subpath from a containing package.json file based on the browser field spec.
2. Return the result of RESOLVE_FILE(context, filePath, platform), or continue.
3. Otherwise, let dirPath be the directory path of filePath.
4. If a file dirPath + 'package.json' exists, resolve based on the browser field spec:
   1. Let mainModulePath be the result of reading the package's entry path using context.mainFields.
   2. Return the result of RESOLVE_FILE(context, mainModulePath, platform), or continue.
   3. Return the result of RESOLVE_FILE(context, mainModulePath + '/index', platform).
   4. Throw an error if no resolution could be found.

RESOLVE_PACKAGE

Parameters: (context, moduleName, platform)

1. If context.unstable_enablePackageExports is enabled, and a containing package.json file contains the field "exports", get result of RESOLVE_PACKAGE_EXPORTS(context, packagePath, filePath, exportsField, platform).
   1. If resolved path exists, return result.
   2. Else, log either a package configuration or package encapsulation warning.
2. Return the result of RESOLVE_MODULE(context, filePath, platform).

PACKAGE_SELF_RESOLVE

Parameters: (context, moduleName, platform)

1. Find the closest package to context.originModulePath. If no package is found, return no resolution.
2. If the package does not declare both a "name" field and an "exports" field, return no resolution.
3. Split moduleName into a package name (including an optional scope) and relative path.
4. If the package name does not match the current package's "name" field, return no resolution.
5. Get the result of RESOLVE_PACKAGE_EXPORTS(context, packagePath, filePath, exportsField, platform) against the current package's "exports" field.
   1. If resolved path exists, return result.
   2. Else, log either a package configuration or package encapsulation warning, then continue with normal resolution.

RESOLVE_PACKAGE_EXPORTS

Parameters: (context, packagePath, filePath, exportsField, platform)

Resolves a package subpath based on the Package Entry Points spec (the "exports" field), when resolver.unstable_enablePackageExports is enabled.

1. Let subpath be the relative path from packagePath to filePath, or '.'.
2. If exportsField contains an invalid configuration or values, raise an InvalidPackageConfigurationError.
3. If subpath is not defined by exportsField, raise a PackagePathNotExportedError.
4. Let target be the result of matching subpath in exportsField after applying any conditional exports and/or substituting a subpath pattern match.
   1. Condition names will be asserted from the union of 'default', 'import' OR 'require' according to context.isESMImport, context.unstable_conditionNames and context.unstable_conditionNamesByPlatform for platform, in the order defined by exportsField.
5. If target refers to an asset, then
   1. Return the result of RESOLVE_ASSET(context, target, platform).
6. Return target as a source file resolution without applying redirections or trying any platform or extension variants.

RESOLVE_FILE

Parameters: (context, filePath, platform)

1. If the path refers to an asset, then
   1. Return the result of RESOLVE_ASSET(context, filePath, platform).
2. Otherwise, if the path exists, then
   1. Try all platform and extension variants in sequence. Return a source file resolution for the first one that exists after applying BROWSER_SPEC_REDIRECTION. For example, if platform is android and context.sourceExts is ['js', 'jsx'], try this sequence of potential file names:
      1. moduleName + '.android.js'
      2. moduleName + '.native.js' (if context.preferNativePlatform is true)
      3. moduleName + '.js'
      4. moduleName + '.android.jsx'
      5. moduleName + '.native.jsx' (if context.preferNativePlatform is true)
      6. moduleName + '.jsx'

RESOLVE_ASSET

Parameters: (context, filePath, platform)

1. Use context.resolveAsset to collect all asset variants.
2. Return an asset resolution containing the collected asset paths.

RESOLVE_HASTE

Parameters: (context, moduleName, platform)

1. Try resolving moduleName as a Haste module. If found, then
   1. Return result as a source file resolution without applying redirections or trying any platform or extension variants.
2. Try resolving moduleName as a Haste (global) package, or a path relative to a Haste package. For example, if moduleName is 'a/b/c', try the following potential Haste package names:
   1. 'a/b/c', relative path ''
   2. 'a/b', relative path './c'
   3. 'a', with relative path './b/c'

BROWSER_SPEC_REDIRECTION

Parameters: (context, moduleName)

Based on defunctzombie/package-browser-field-spec, apply redirections to specifiers, based on the closest package.json to the origin or target module.

1. Find the closest package.json to moduleName, if moduleName is absolute, or to context.originModulePath otherwise, stopping at any node_modules. Let packageScope be its containing directory.
2. If none is found, return moduleName.
3. Define subpath:
   1. If moduleName begins '.', consider it relative to context.originModulePath and let subpath be the same path relative to packageScope, prefixed './'.
   2. Else if moduleName is absolute, let subpath be moduleName relative to packageScope, prefixed './'.
   3. Else let subpath be moduleName.
4. Taking each of context.mainFields as a key, let mainFieldValue be the value at that key within the package.json at packageScope.
   1. If mainFieldValue is an object, let expandedSubPath range over subpath, subpath + '.js' and subpath + '.json'.
      1. If mainFieldValue has the key expandedSubpath, let redirectedPath be its value, else continue.
      2. If moduleName is absolute or begins '.', and redirectedPath is a string:
         1. If redirectedPath is an absolute path, return redirectedPath.
         2. Return packageScope joined with redirectedPath.
      3. Return redirectedPath.
5. Return moduleName.

Resolution context

assetExts: $ReadOnlySet<string>

The set of file extensions used to identify asset files. Defaults to resolver.assetExts.

dev: boolean

true if the resolution is for a development bundle, or false otherwise.

doesFileExist: string => boolean

Deprecated

Returns true if the file with the given path exists, or false otherwise.

The default implementation wraps fileSystemLookup - prefer using that directly.

fileSystemLookup: string => {exists: true, type: 'f'|'d', realPath: string} | {exists: false}

Added in v0.81.0

Return information about the given absolute or project-relative path, following symlinks. A file "exists" if and only if it is watched, and a directory must be non-empty. The returned realPath is real and absolute.

By default, Metro implements this by consulting an in-memory map of the filesystem that has been prepared in advance. This approach avoids disk I/O during module resolution and performs realpath resolution at negligible additional cost.

nodeModulesPaths: $ReadOnlyArray<string>

A list of paths to check for modules after looking through all node_modules directories.

By default this is set to resolver.nodeModulesPaths

preferNativePlatform: boolean

If true, try .native.${ext} before .${ext} and after .${platform}.${ext} during resolution. Metro sets this to true.

redirectModulePath: string => string | false

Deprecated

The default implementation of this function is specified by BROWSER_SPEC_REDIRECTION.

Metro's default resolver does not call this function, instead using the BROWSER_SPEC_REDIRECTION implementation directly. It is exposed here for backwards-compatible use by custom resolvers, but is considered deprecated and will be removed in a future release.

resolveAsset: (dirPath: string, assetName: string, extension: string) => ?$ReadOnlyArray<string>

Given a directory path, the base asset name and an extension, returns a list of all the asset file names that match the given base name in that directory, or null if no such files are found. The default implementation considers each of resolver.assetResolutions and uses the ${assetName}@${resolution}${extension} format for asset variant file names.

See also Static Image Resources in the React Native docs.

sourceExts: $ReadOnlyArray<string>

The list of file extensions to try, in order, when resolving a module path that does not exist on disk. Defaults to resolver.sourceExts.

mainFields: $ReadOnlyArray<string>

The ordered list of fields in package.json that should be read to resolve a package's main entry point (and any subpath file replacements) per the "browser" field spec. Defaults to resolver.resolverMainFields.

getPackage: string => PackageJson

Given the path to a package.json file, returns the parsed file contents.

getPackageForModule: (absoluteModulePath: string) => ?PackageInfo

Deprecated

Given a candidate absolute module path that may exist under a package, locates and returns the closest package root (working upwards from the given path, stopping at the nearest node_modules), parsed package.json contents, and the package-relative path of the given path.

isESMImport?: boolean

Whether the dependency to be resolved was declared with an ESM import, ("import x from 'y'" or "await import('z')"), or a CommonJS "require". Corresponds to the criteria Node.js uses to assert an "import" resolution condition, vs "require".

Always equal to dependency.data.isESMImport where dependency is provided, but may be used for resolution.

resolveHasteModule: string => ?string

Resolves a Haste module name to an absolute path. Returns null if no such module exists.

The default implementation of this function uses metro-file-map's getModule method.

resolveHastePackage: string => ?string

Resolves a Haste (global) package name to an absolute package.json path. Returns null if no such package exists.

The default implementation of this function uses metro-file-map's getPackage method and can be turned on or off using resolver.enableGlobalPackages.

allowHaste: boolean

true if Haste resolutions are allowed in the current context, false otherwise.

disableHierarchicalLookup: boolean

If true, the resolver should not perform lookup in node_modules directories per the Node resolution algorithm. Defaults to resolver.disableHierarchicalLookup.

extraNodeModules: ?{[string]: string}

A mapping of package names to directories that is consulted after the standard lookup through node_modules as well as any nodeModulesPaths.

originModulePath: string

The path to the current module, e.g. the one containing the import we are currently resolving.

customResolverOptions: {[string]: mixed}

Any custom options passed to the resolver. By default, Metro populates this based on URL parameters in the bundle request, e.g. http://localhost:8081/index.bundle?resolver.key=value becomes {key: 'value'}.

resolveRequest: CustomResolver

A alternative resolver function to which the current request may be delegated. Defaults to resolver.resolveRequest.

Metro expects resolveRequest to have the following signature:

function resolveRequest(
  context: ResolutionContext,
  moduleName: string,
  platform: string | null,
): Resolution {
  // ...
}

type Resolution =
  | {type: 'empty'}
  | {type: 'sourceFile', filePath: string}
  | {type: 'assetFiles', filePaths: $ReadOnlyArray<string>};

Returned paths (filePath and filePaths) must be absolute and real, such as the realPath returned by fileSystemLookup.

When calling the default resolver with a non-null resolveRequest function, it represents a custom resolver and will always be called, fully replacing the default resolution logic.

Inside a custom resolver, resolveRequest is set to the default resolver function, for easy chaining and customization.

schemeResolvers: Readonly<{[scheme: string]: CustomResolver}>

An object of custom resolvers for import specifiers prefixed with a URI scheme, keyed by lowercased scheme name (the part before the first ':', without the colon). The scheme parsed from a specifier is lowercased before lookup, so keys must be lowercase (both Foo: and foo: match the 'foo' key). Defaults to resolver.schemeResolvers.

When the default resolver encounters a specifier whose scheme matches a key — for example my-scheme:foo matching 'my-scheme' — it invokes the corresponding resolver with the full specifier. The resolver is passed a context whose resolveRequest is the default resolver, so it can chain back into default resolution (e.g. to resolve a relative path).

Relative (./, ../) and subpath (#…) imports are handled before scheme dispatch and are never treated as schemes. See RESOLVE step 4 for how scheme dispatch fits into the algorithm, and resolver.schemeResolvers for precedence relative to resolveRequest.

dependency: ?Dependency

A dependency descriptor corresponding to the current resolution request. This is provided for diagnostic purposes only and may not be used for semantic purposes. See the Caching section for more information.

type Dependency = {
  // The literal name provided to a require or import call. For example 'foo' in
  // case of `require('foo')`.
  name: string,

  data: {
    // A locally unique key for this dependency within the origin module.
    key: string,

    // Source locations from the Babel AST, relative to the origin module, where
    // this dependency was encountered. This may be an empty array.
    locs: $ReadOnlyArray<BabelSourceLocation>,

    asyncType: 'async' | 'prefetch' | 'weak' | null,

    // Other properties are considered internal and may change in the future.
    ...
  },
};

Caching

Resolver results may be cached under the following conditions:

1. For given origin module paths A and B and target module name M, the resolution for M may be reused if all of the following conditions hold:
   1. A and B are in the same directory.
   2. The contents of dev and customResolverOptions are equivalent ( = serialize to JSON the same) in both calls to the resolver.
2. Any cache of resolutions must be invalidated if any file in the project has changed.

Custom resolvers must adhere to these assumptions, e.g. they may not return different resolutions for origin modules in the same directory under the same customResolverOptions.