Metro Hermes Compiler

0.73.10 verified Fri May 01 auth: no javascript

An experimental Node.js package providing a high-level API to interface with the Hermes bytecode compiler (HBC). Hermes is an open-source JavaScript engine optimized for React Native apps. This package integrates the compiler as a WebAssembly binary generated via Emscripten, enabling conversion of JavaScript/JSX into Hermes bytecode (.hbc) for improved startup performance on mobile. The current stable version is 0.73.10, with regular releases as part of Metro's release cadence (monthly minor updates). Unlike alternatives like Babel alone, this compiler is purpose-built for Hermes, producing optimized bytecode targeting React Native's Hermes runtime.

Common errors

error Error: Can't resolve 'metro-hermes-compiler' ↓

cause Package not installed or missing from node_modules.

fix

Run npm install metro-hermes-compiler or add it to package.json.

error TypeError: compile is not a function ↓

cause Incorrect import — using default export instead of named.

fix

Use import { compile } from 'metro-hermes-compiler' (not import ... from as default).

error Module not found: Can't resolve 'metro-hermes-compiler' in '/path/to/project' ↓

cause Webpack or bundler cannot locate the package; possibly not installed or incorrectly aliased.

fix

Ensure the package is installed and import path is correct (use 'metro-hermes-compiler' not a relative path).

Warnings

breaking The compile function now returns a Buffer instead of an object with a buffer property. ↓

fix Use compiled output directly as a Buffer instead of accessing .buffer.

deprecated The 'compileFromSource' function has been deprecated in favor of 'compile'. ↓

fix Replace compileFromSource calls with compile and adjust parameters if needed.

breaking Node.js versions below 14 are no longer supported. ↓

fix Upgrade Node.js to version 14 or later.

gotcha The WASM binary is large (~30MB) and may cause high memory usage during compilation. ↓

fix Ensure sufficient memory (at least 512MB heap) for the Node process.

breaking Options 'sourceMap' and 'optimize' were added as required; omitting them causes errors. ↓

fix Always include sourceMap and optimize boolean options in the config object.

Install

npm install metro-hermes-compiler

yarn add metro-hermes-compiler

pnpm add metro-hermes-compiler

Imports

compile
```
import { compile } from 'metro-hermes-compiler'
```
Default and named exports are both available; ESM is primary.

default

wrong

import metroHermesCompiler from 'metro-hermes-compiler'

correct

import { compile } from 'metro-hermes-compiler'

There is no default export; use named imports.

compileFromSource

wrong

const { compileFromSource } = require('metro-hermes-compiler')

correct

import { compileFromSource } from 'metro-hermes-compiler'

CJS require is deprecated; use ESM imports.

Quickstart

Compiles a JavaScript file to Hermes bytecode using the compile function, with source map and optimization enabled.

import { compile } from 'metro-hermes-compiler';
import { readFileSync, writeFileSync } from 'fs';

const source = readFileSync('input.js', 'utf8');
const bytecode = compile(source, {
  sourceURL: 'input.js',
  sourceMap: true,
  optimize: true
});
writeFileSync('output.hbc', bytecode);
console.log('Compiled to Hermes bytecode.');