Skip to content
Get packs

Guide · Open source

How to use Hermes: build the CLI and run JavaScript

Updated · written with AI from the project's own documentation and checked against our catalogue data

Hermes is an open-source JavaScript engine, the software that runs JavaScript code, optimized for fast start-up of React Native apps. This guide explains how to build the Hermes command-line tools from source and run a small script with them. It is aimed at developers who want to work on or customize Hermes; if you only want Hermes inside a React Native app, the official React Native docs cover that without building from source.

Hermesmeta/hermes · ★ 11.4k · MIT

Quick start

  1. 1Check prerequisites. Make sure Git, cmake, Ninja and a C/C++ compiler for your OS are installed.
  2. 2Create a working directory. Run mkdir hermes_workingdir and move into it.
  3. 3Clone the repository. Clone facebook/hermes from GitHub into the working directory with git clone.
  4. 4Configure the build. Run the cmake configure command with -G Ninja and -DCMAKE_BUILD_TYPE=Debug on macOS or Linux.
  5. 5Build the CLI tools. Run cmake --build ./build to produce the Hermes CLI tools.
  6. 6Run a test script. Pipe a short JavaScript snippet into ./bin/hermes to confirm it runs.

Decide whether you need to build Hermes from source

Most people use Hermes by enabling the pre-built version in a React Native app. The project's README says that if you only want that, you do not need to follow its build guide or have direct access to the Hermes source. Use the React Native Hermes instructions instead.

Building from source makes sense if you want to build and hack on Hermes directly, or integrate a Hermes build from source into a React Native app.

  • Pre-built Hermes in an app: follow the official React Native docs on enabling Hermes.
  • Building the Hermes CLI, changing the engine, or contributing: continue with this guide.

Install the prerequisites

The README assumes you already have typical native development tools set up for your operating system, plus support for cmake and Ninja. The required tools are Git, cmake, Ninja, and a C/C++ compiler as part of your OS native development tools.

For full details on dependencies and build options, the README points to doc/BuildingAndRunning.md.

  • Git
  • cmake
  • Ninja
  • Native development tools for your OS (a C/C++ compiler)

Clone and build the Hermes CLI on macOS or Linux

Create a working directory, clone the repository into it, then configure and build a debug version of the Hermes CLI tools. The build output goes into a build directory.

mkdir hermes_workingdir cd hermes_workingdir git clone https://github.com/facebook/hermes.git cmake -S hermes -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug cmake --build ./build

Build on Windows

The README gives a separate set of steps for Windows, to be run in a Git Bash shell. It uses the Visual Studio 16 2019 generator instead of Ninja.

mkdir hermes_workingdir cd hermes_workingdir git -c core.autocrlf=false clone https://github.com/facebook/hermes.git cmake -S hermes -B build -G 'Visual Studio 16 2019' -A x64 cmake --build ./build

Run a JavaScript file with the Hermes CLI

After the build, you are in a directory containing the Hermes CLI tools. The README shows running a short piece of JavaScript by piping it into the hermes binary. The example prints a message through a strict-mode function.

The README's example is the only run command it gives, so use it as your first check that the build works.

echo "'use strict'; function hello() { print('Hello World'); } hello();" | ./bin/hermes

Avoid version mismatches with React Native

The README says each Hermes release is aimed at a specific React Native version. Its rule of thumb is to follow the Hermes releases page strictly. It warns that a version mismatch can, in the worst case, crash your app instantly.

If you integrate a custom Hermes build into a React Native app, track which Hermes release matches your React Native version. The README links to doc/ReactNativeIntegration.md for that process.

Contribute or read more

The README points to a contributing guide covering the development process, how to propose bugfixes, and how to build and test changes. It also links to a code of conduct and a Hermes blog with technical articles on internals.

The project is MIT licensed.

What people use it for

  • Building a local debug Hermes CLI to run JavaScript snippets.
  • Customizing or hacking on the Hermes engine itself.
  • Integrating a Hermes build from source into a React Native app.
  • Contributing bugfixes or improvements to Hermes internals.

Frequently asked questions

Is Hermes free to use?

Yes. Hermes is MIT licensed, as stated in its README and LICENSE file. You can read the license file in the repository for the full terms.

What do I need to install Hermes?

To build it from source you need Git, cmake, Ninja and native development tools for your OS, including a C/C++ compiler. The README assumes these are already set up. For full dependency details, see doc/BuildingAndRunning.md in the repository.

How do I enable Hermes in a React Native app?

The README says you do not need to build from source for this. Follow the official React Native documentation on enabling Hermes instead.

Why does my app crash after changing Hermes?

The README warns that each Hermes release targets a specific React Native version, and a mismatch can crash apps. Follow the Hermes releases page closely and keep the two versions aligned.

What are alternatives to Hermes?

Comparable JavaScript engines include JavaScriptCore, V8 and QuickJS. Hermes is specifically described as optimized for React Native start-up, so compare on that basis if you are choosing an engine for a React Native app.

Can I use Hermes outside React Native?

The README describes Hermes as optimized for React Native apps and does not describe other use cases. If you are not working with React Native, check whether another engine fits your project better.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Hermes suits React Native developers who want to build the engine from source, customize it, or contribute to its internals. If you only want faster start-up in an app, or you cannot track Hermes and React Native versions carefully, use the official React Native setup or consider another engine such as V8, JavaScriptCore or QuickJS.

Install options & downloads