id | title |
---|---|
configuration |
Configuring Metro |
A Metro config can be created in these three ways (ordered by priority):
metro.config.js
metro.config.json
- The
metro
field inpackage.json
You can also give a custom file to the configuration by specifying --config <path/to/config>
when calling the CLI.
The configuration is based on our concepts, which means that for every module we have a separate config option. A common configuration structure in Metro looks like this:
module.exports = {
/* general options */
resolver: {
/* resolver options */
},
transformer: {
/* transformer options */
},
serializer: {
/* serializer options */
},
server: {
/* server options */
}
};
Type: Array<CacheStore<TransformResult<>>
List where we store our caches.
Type: string
Can be used to generate a key that will invalidate the whole metro cache.
Type: string
The root folder of your project.
Type: Array<string>
Specify any additional (to projectRoot) watch folders, this is used to know which files to watch.
(By default the file watching is disabled in CI environments. Also it can be manually disabled by setting the env variable CI=true
)
Type: string
The path to the transformer to use.
Type: {update: () => void}
Used to report the status of the bundler during the bundling process.
Type: boolean
Whether we should reset the cache when starting the build.
Type: boolean
Control whether the created workers should stick based on filename or not.
Type: number
The number of workers we should parallelize the transformer on.
Type: string
The path to the haste map cache directory, defaults to os.tmpdir()
.
Type: Array<string>
An array of asset extensions to include in the bundle. For example, if you would give ['ttf']
you would be able to include .ttf
files in the bundle.
Type: Array<string>
An array of source extensions to include in the bundle. For example, if you would give ['ts']
you would be able to include .ts
files in the bundle.
Type: Array<string>
Specify the fields in package.json files that will be used by the module resolver to do redirections when requiring certain packages. For example, using ['browser', 'main']
will use the browser
field if it exists and will default to main
if it doesn't.
Type: {[name:string]:string}
Which other node_modules
to include besides the ones relative to the project directory. This is keyed by dependency name.
Type: Array<string>
This option can be used to add additional node_modules
folders for Metro to locate third-party dependencies when resolving modules. This is useful if third-party dependencies are installed in a different location outside of the direct path of source files.
This option works similarly to how $NODE_PATHS works for Node.js based tooling.
Type: ?CustomResolver
An optional function used to resolve requests. Ignored when the request can be resolved through Haste. Particularly useful for cases where aliases are used. For example:
resolveRequest: (context, realModuleName, platform, moduleName) => {
// Resolve file path logic...
return {
filePath: "path/to/file",
type: 'sourceFile',
};
}
Type: boolean
If set to false
, it'll prevent Metro from using watchman (even if it's installed)
These options are only useful with React Native projects.
Type: RegExp
or Array<RegExp>
A RegEx defining which paths to ignore, however if a blocklisted file is required it will be brought into the dependency graph.
Type: string
The path to the haste resolver.
Type: Array<string>
Additional platforms to look out for, For example, if you want to add a "custom" platform, and use modules ending in .custom.js, you would return ['custom'] here.
Type: string
What module to use for handling async requires.
Type: string
Use a custom babel transformer (only relevant when using the default transformerPath). For example:
// in your babelTransformer file
module.exports = ({ filename, options, plugins, src }) => {
// transform file...
return { ast: AST };
}
Type: string
(throwAtRuntime
or reject
)
What should happen when a dynamic dependency is found.
Type: boolean
(default: true
)
Whether we should use the .babelrc
config file.
Type: boolean
(default: true
)
Whether the transformer should use the @babel/transform/runtime
plugin.
Type: GetTransformOptions
Get the transform options.
Type: PostMinifyProcess
What happens after minification.
Type: string
Path to the minifier that minifies the code after transformation.
Type: {[key: string]: mixed}
Configuration object that will be passed to the minifier (it should be serializable).
Type: number
Define a threshold (in bytes) to disable some expensive optimizations for big files.
Type: Array<string>
List of modules to call to modify Asset data
Type: string
Where to fetch the assets from.
Type: (number
| string) => string
Specify the format of the initial require statements that are appended at the end of the bundle. By default is __r(${moduleId});
.
Type: () => (path: string) => number
Used to generate the module id for require
statements.
Type: ({platform: ?string}) => $ReadOnlyArray<string>
An optional list of polyfills to include in the bundle. The list defaults to a set of common polyfills for Number, String, Array, Object...
Type: PostProcessBundleSourcemap
An optional function that can modify the code and source map of the bundle before it is written. Applied once for the entire bundle.
Type: (entryFilePath: string) => Array<string>
An array of modules to be required before the entry point. It should contain the absolute path of each module. Note that this will add the additional require statements only if the passed modules are already included as part of the bundle.
Type: (module: Array<Module>) => boolean
A filter function to discard specific modules from the output.
These options are used when Metro serves the content.
Type: number
Which port to listen on.
Type: boolean
Whether we should enable CMD+R hotkey for refreshing the bundle.
Type: (Middleware, Server) => Middleware
The possibility to add custom middleware to the server response chain.
Type: string => string
A function that will be called every time Metro processes a URL. Metro will use the return value of this function as if it were the original URL provided by the client. This applies to all incoming HTTP requests (after any custom middleware), as well as bundle URLs in /symbolicate
request payloads and within the hot reloading protocol.
Type: boolean
(default: true
)
Run Inspector Proxy server inside Metro to be able to inspect React Native code.
Using the metro-config
package it is possible to merge multiple configurations together.
Method | Description |
---|---|
mergeConfig(...configs): MergedConfig |
Returns the merged configuration of two or more configuration objects. |
Note: Arrays and function based config parameters do not deeply merge and will instead override any pre-existing config parameters. This allows overriding and removing default config parameters such as
platforms
orgetModulesRunBeforeMainModule
that may not be required in your environment.
// metro.config.js
const { mergeConfig } = require("metro-config");
const configA = {
/* general options */
resolver: {
/* resolver options */
},
transformer: {
/* transformer options */
},
serializer: {
/* serializer options */
},
server: {
/* server options */
}
};
const configB = {
/* general options */
resolver: {
/* resolver options */
},
transformer: {
/* transformer options */
},
serializer: {
/* serializer options */
},
server: {
/* server options */
}
};
module.exports = mergeConfig(configA, configB);