{"id":14619,"library":"hermes-compiler","title":"Hermes JavaScript Compiler CLI","description":"The `hermes-compiler` package provides the command-line interface (CLI) for the Hermes JavaScript engine, specifically optimized for React Native applications. Hermes focuses on delivering improved startup time, reduced memory usage, and smaller app sizes by leveraging ahead-of-time (AOT) compilation, which converts JavaScript source code into compact Hermes Bytecode (HBC) during the build process. The package's public versioning (e.g., v0.13.0 for RN 0.75.x) is tightly coupled with React Native releases, ensuring compatibility. While the npm registry shows an internal version like `250829098.0.2`, it's the `v0.x.x` versions that align with React Native support. Hermes is now the default JavaScript engine for React Native, requiring no additional configuration for most projects.","status":"active","version":"250829098.0.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/facebook/hermes","tags":["javascript"],"install":[{"cmd":"npm install hermes-compiler","lang":"bash","label":"npm"},{"cmd":"yarn add hermes-compiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add hermes-compiler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Hermes is primarily developed and optimized for use as the JavaScript engine within React Native applications. Its compiler is integrated into the React Native build pipeline.","package":"react-native","optional":false},{"reason":"The `hermes-compiler` is a command-line interface (CLI) tool that runs in a Node.js environment, typically invoked via `npx` or `npm scripts`.","package":"node","optional":false}],"imports":[{"note":"This package is a command-line interface tool and does not export JavaScript modules for direct import. Its primary interaction is via `npx` or npm scripts during the build process.","wrong":"import { hermesCompiler } from 'hermes-compiler';","symbol":"hermes-compiler CLI (npx)","correct":"npx hermes-compiler src/index.js -o dist/index.hbc"},{"note":"For environments where `npx` is not available or for direct scripting, the executable can be invoked from the local `node_modules/.bin` directory.","wrong":"const hermesCompiler = require('hermes-compiler');","symbol":"hermes-compiler CLI (direct binary)","correct":"./node_modules/.bin/hermes-compiler src/index.js -o dist/index.hbc"},{"note":"It is commonly integrated into `package.json` scripts to automate the bytecode compilation step within a project's build pipeline.","symbol":"package.json script","correct":"{ \"scripts\": { \"compile:hermes\": \"hermes-compiler src/entry.js -o build/app.hbc\" } }"}],"quickstart":{"code":"import { exec } from 'child_process';\nimport { promises as fs } from 'fs';\nimport * as path from 'path';\n\nconst sourceCode = `'use strict';\\n\\nfunction greet(name) {\\n  console.log('Hello, ' + name + '!');\\n}\\n\\ngreet('Hermes User');\\n`;\n\nconst inputFilePath = path.join(__dirname, 'temp.js');\nconst outputFilePath = path.join(__dirname, 'temp.hbc');\n\nasync function compileWithHermes() {\n  try {\n    await fs.writeFile(inputFilePath, sourceCode);\n    console.log(`Created temporary source file: ${inputFilePath}`);\n\n    const command = `npx hermes-compiler ${inputFilePath} -o ${outputFilePath}`;\n    console.log(`Executing command: ${command}`);\n\n    const { stdout, stderr } = await new Promise((resolve, reject) => {\n      exec(command, (error, stdout, stderr) => {\n        if (error) {\n          return reject(error);\n        }\n        resolve({ stdout, stderr });\n      });\n    });\n\n    console.log('Compilation successful!');\n    console.log('stdout:', stdout);\n    if (stderr) console.error('stderr:', stderr);\n    console.log(`Hermes bytecode saved to: ${outputFilePath}`);\n\n    // Clean up temporary files\n    await fs.unlink(inputFilePath);\n    await fs.unlink(outputFilePath);\n    console.log('Cleaned up temporary files.');\n\n  } catch (error) {\n    console.error('Hermes compilation failed:', error);\n    if (error.stderr) console.error('Compiler stderr:', error.stderr);\n  }\n}\n\ncompileWithHermes();","lang":"typescript","description":"Demonstrates how to programmatically invoke the `hermes-compiler` CLI using Node.js's `child_process.exec` to compile a simple JavaScript file into Hermes bytecode (.hbc)."},"warnings":[{"fix":"Migrate to alternative debugging methods, typically integrated within the React Native development server or IDEs, or use external tools.","message":"The command-line debugger was removed from `hermes-compiler` in v0.12.0, which may impact workflows relying on CLI-based debugging tools.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"Consult the official Hermes GitHub repository for updated instructions on building Hermes from source and integrating custom builds into a React Native project.","message":"As of v0.12.0, React Native now builds Hermes from source. This change simplifies integration for standard React Native users but requires a different approach for developers attempting to build or integrate custom Hermes versions from source.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"Always align your `hermes-compiler` version with the React Native version specified in the release notes or the `react-native-hermes` package.","message":"Prior to v0.12.0, specific `hermes-compiler` versions were often tied to particular React Native versions (e.g., v0.11.0 for RN 0.68.x). Mismatched versions could lead to runtime crashes or unexpected behavior.","severity":"gotcha","affected_versions":"<0.12.0"},{"fix":"Benchmark and profile applications on Hermes v0.8.0+ to understand performance impacts, particularly for CPU-intensive workloads. Consult Hermes documentation on Hades for details.","message":"The introduction of the 'Hades' concurrent garbage collector in v0.8.0 significantly altered GC pause times and performance characteristics. While generally an improvement, it could subtly affect applications with extreme performance sensitivities to GC.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Ensure the correct `hermes-compiler` or `hermes-engine` variant is used for your target platform and React Native version. Verify platform-specific installation notes carefully.","message":"Some Hermes versions have platform-specific releases or packaging changes (e.g., v0.5.3 for Darwin only, publishing `hermes-runtime-darwin` to CocoaPod instead of `hermes-engine-darwin` to NPM in v0.7.1), which can cause build failures on unsupported platforms or with incorrect dependency configurations.","severity":"gotcha","affected_versions":">=0.5.0"},{"fix":"Upgrade to `hermes-compiler` v0.12.0 or newer to use `WeakRef` and `BigInt`. For older versions, transpile down these features or avoid them.","message":"Support for ECMAScript features like `WeakRef` and `BigInt` was added in v0.12.0. Using these features with older `hermes-compiler` versions will result in compilation or runtime errors.","severity":"gotcha","affected_versions":"<0.12.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `npm` is correctly installed and `node_modules/.bin` is accessible, or use `npx hermes-compiler` or the full path `./node_modules/.bin/hermes-compiler` to invoke it. For npm scripts, define `\"scripts\": { \"compile\": \"hermes-compiler ...\" }`.","cause":"The `hermes-compiler` executable is not in the system's PATH, or `npx` cannot find it within `node_modules/.bin`.","error":"'hermes-compiler' is not recognized as an internal or external command, operable program or batch file."},{"fix":"Do not `import` or `require` `hermes-compiler`. Instead, execute it as a command-line tool using `npx hermes-compiler` or `child_process.exec`/`spawn` if invoked programmatically from Node.js.","cause":"Attempting to use `import` or `require` with `hermes-compiler` directly in JavaScript code. This package is a CLI tool, not a JavaScript module for programmatic import.","error":"Error: Cannot find module 'hermes-compiler'"},{"fix":"Review the indicated line and column for syntax errors. Ensure that the JavaScript features used are supported by your `hermes-compiler` version, or transpile down with Babel if necessary.","cause":"The JavaScript source code passed to the Hermes compiler contains syntax errors or uses unsupported language features for the targeted Hermes version.","error":"HermesVM: Compiling JS failed: ... SyntaxError: ..."},{"fix":"Check the `hermes-compiler` and React Native release notes for Windows compatibility. Ensure your environment matches the expected setup. In some cases, manual workarounds or specific package versions might be required.","cause":"The `hermes-compiler` package might not ship Windows binaries for all versions or specific React Native setups, leading to build failures.","error":"Release builds fail due to missing hermesc bin on Windows"},{"fix":"If using experimental 'Static Hermes' builds, ensure you are invoking the correct executable (e.g., `shermes` instead of `hermes`) and following its specific compilation flags and usage patterns. Refer to the 'Static Hermes' documentation or relevant GitHub discussions.","cause":"This error can occur when trying to use `hermes` with `Static Hermes` builds in a way that conflicts with its configuration, specifically when attempting to generate bytecode directly when it's disabled.","error":"LLVM ERROR: Generating HBC bytecode disabled in Static Hermes"}],"ecosystem":"npm"}