{"id":20213,"library":"metro-babel-transformer","title":"Metro Babel Transformer","description":"The base Babel transformer for Metro, the JavaScript bundler for React Native. Current stable version is 0.84.3, with frequent releases (~monthly). This package provides the default Babel transformation pipeline used by Metro to transpile JavaScript/TypeScript files. It handles caching, config merging, and integration with Metro's build system. Key differentiators: it is the official transformer maintained by Meta, tightly coupled with Metro's caching and dependency resolution; supports custom Babel configs; and ships TypeScript types natively since v0.83.5. Alternatives like @react-native/babel-transformer exist but this is the core package.","status":"active","version":"0.84.3","language":"javascript","source_language":"en","source_url":"https://github.com/facebook/metro","tags":["javascript","transformer","metro","typescript"],"install":[{"cmd":"npm install metro-babel-transformer","lang":"bash","label":"npm"},{"cmd":"yarn add metro-babel-transformer","lang":"bash","label":"yarn"},{"cmd":"pnpm add metro-babel-transformer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the Babel compiler used for transformation.","package":"@babel/core","optional":true},{"reason":"Core Metro package; required for transformer integration.","package":"metro","optional":false}],"imports":[{"note":"Package ships TypeScript types; ES module syntax recommended. CommonJS require works but may not have type checking.","wrong":"const { getTransformOptions } = require('metro-babel-transformer')","symbol":"getTransformOptions","correct":"import { getTransformOptions } from 'metro-babel-transformer'"},{"note":"Default export is the transformer function; namespace import will cause runtime errors.","wrong":"import * as MetroBabelTransformer from 'metro-babel-transformer'","symbol":"MetroBabelTransformer","correct":"import MetroBabelTransformer from 'metro-babel-transformer'"},{"note":"Available from v0.83.0; used to extend transform options.","wrong":null,"symbol":"customTransformOptions","correct":"import { customTransformOptions } from 'metro-babel-transformer'"}],"quickstart":{"code":"// Example of using metro-babel-transformer programmatically\nimport MetroBabelTransformer from 'metro-babel-transformer';\nimport path from 'path';\n\nconst transformer = MetroBabelTransformer({\n  // Required: root project directory\n  projectRoot: process.cwd(),\n  // Optional: custom Babel config path\n  babelConfigPath: path.join(process.cwd(), 'babel.config.js'),\n});\n\nconst result = transformer({\n  filename: path.resolve('src/index.js'),\n  sourceCode: 'const x = 1;',\n  options: {\n    dev: true,\n    hot: false,\n    platform: 'ios',\n    minify: false,\n    // Add custom transform options if needed\n    customTransformOptions: {},\n  },\n});\n\nconsole.log(result.code);\nconsole.log('Map:', result.map);","lang":"typescript","description":"Shows how to use the transformer function directly: instantiate with project root, then call with file contents."},"warnings":[{"fix":"Upgrade Node.js to ^20.19.4 || ^22.13.0 || ^24.3.0 || >=25.0.0","message":"Node.js versions earlier than 20.19.4 (including all v21, v23) are no longer supported in v0.84.0+.","severity":"breaking","affected_versions":">=0.84.0"},{"fix":"Use `customTransformOptions` instead of `getTransformOptions`.","message":"The function `getTransformOptions` is deprecated in favor of `customTransformOptions`.","severity":"deprecated","affected_versions":">=0.83.0"},{"fix":"Update to v0.83.6 or later, or manually add your Babel config path to the cache key.","message":"If you include a custom Babel config, make sure it is part of the transformer cache key to avoid stale caches. Metro includes it automatically since v0.83.6.","severity":"gotcha","affected_versions":"<0.83.6"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run `npm install metro-babel-transformer --save-dev` and ensure your code uses the correct import.","cause":"Package not installed or incorrect import path.","error":"Error: Cannot find module 'metro-babel-transformer'"},{"fix":"Use `import MetroBabelTransformer from 'metro-babel-transformer'` instead of `import * as...`.","cause":"Using a default export incorrectly (e.g., namespace import).","error":"TypeError: MetroBabelTransformer is not a function"},{"fix":"Install @babel/core: `npm install @babel/core --save-dev`","cause":"Missing peer dependency @babel/core.","error":"Error: Cannot find module '@babel/core'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}