react-native-eval-js

A React Native library for evaluating Hermes bytecode at runtime. This library allows you to load and execute pre-compiled JavaScript bytecode (.hbc files) in your React Native application.

Features

• 🚀 Execute Hermes bytecode files at runtime
• 📦 Load bytecode from app bundle or file system
• 🔒 Safe execution in the JSI runtime
• 📱 iOS and Android support
• ⚡️ Powered by Hermes engine

Installation

npm install react-native-eval-js

or

yarn add react-native-eval-js

iOS Setup

For iOS, you need to run pod install:

cd ios && pod install

Usage

1. Generate Hermes Bytecode

First, create a JavaScript file and compile it to Hermes bytecode:

// my-script.js
globalThis.myFunction = () => {
  console.log('Hello from bytecode!');
};

Use the included script to generate bytecode:

node node_modules/react-native-eval-js/scripts/generate-bytecode.js my-script.js

This will create my-script.hbc in the same directory.

2. Add Bytecode to Your App

iOS: Add the .hbc file to your Xcode project.

Android: Place the .hbc file in android/app/src/main/assets/.

3. Evaluate the Bytecode

import { evaluateByteCode } from 'react-native-eval-js';

// Load bytecode from app bundle
const success = evaluateByteCode('my-script.hbc');

if (success) {
  console.log('Bytecode loaded successfully!');
  // Now you can use functions/variables defined in the bytecode
  globalThis.myFunction();
}

API

evaluateByteCode(url: string): boolean

Evaluates Hermes bytecode from a file.

Parameters:

• url (string): The filename or path to the bytecode file. The library will first look in the app bundle, then try as a file path.

Returns:

• boolean: true if the bytecode was successfully evaluated, false otherwise.

Example:

import { evaluateByteCode } from 'react-native-eval-js';

// Load from bundle
evaluateByteCode('script.hbc');

// Load from file path (iOS)
evaluateByteCode('file:///path/to/script.hbc');

Generating Bytecode

The library includes a utility script for generating Hermes bytecode:

node node_modules/react-native-eval-js/scripts/generate-bytecode.js <input-file> [output-file]

Examples:

# Generate script.hbc from script.js
node node_modules/react-native-eval-js/scripts/generate-bytecode.js script.js

# Specify custom output file
node node_modules/react-native-eval-js/scripts/generate-bytecode.js script.js output.hbc

The script automatically finds the Hermes compiler from your React Native installation.

Use Cases

• Dynamic Features: Load optional features at runtime without increasing initial bundle size
• Hot Updates: Update app functionality without going through app store review
• A/B Testing: Load different implementations based on user segments
• Plugin Systems: Build extensible apps that can load plugins as bytecode
• Code Splitting: Split large apps into smaller chunks loaded on demand

Security Considerations

⚠️ Important: This library executes code in the JavaScript runtime. Only load bytecode from trusted sources. Do not load bytecode from user input or untrusted remote servers.

Limitations

• Only works with Hermes engine (enabled by default in React Native 0.70+)
• Bytecode must be compiled with the same Hermes version as your React Native version
• iOS and Android only (not for web)

Example

Check out the example app for a complete working implementation.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library