Polygen: WebAssembly Toolkit for React Native

Polygen allows you to run WebAssembly Modules in your React Native apps, with near native speed.
Report a Bug · Request Feature

Getting started

Warning

This library is still under active development. Feel free to hack around, but use at your own risk.

How it works?

Instead of interpreting the WebAssembly modules, or doing Just-in-Time compilation, Polygen instead leverages the Ahead-of-Time compilation. This solution can be used in iOS applications and other Apple devices, where JIT compilation is not allowed, without impacting performance.

It uses the wonderful wasm2c tool to generate C code from every WebAssembly module. Then, additional React Native/JSI glue native code is generated that allows to call the generated C code from JavaScript.

This gives us the ability to run WebAssembly modules in a statically compiled way, without the need for JIT compilation.

Features

Feature	Status
WebAssembly 2.0	🟩
- Exceptions	🟥
- Threads	🟥
- Garbage Collection	🟥
- Multiple Memories	🟨
- Mutable Globals	🟨
WebAPI	🟨
- Fetch	🟩
Native	🟨
- Metro	🟨
- Re.Pack	🟥

Requirements

• React Native 0.75+

Prerequisites

Because Polygen Codegen depends on wasm2c tool, you need to have it installed on your machine. You can install it by either:

1. Install using package manager:

   # macOS
   brew install wabt
   
   # linux
   sudo apt install wabt

2. Downloading precompiled binaries from the releases page of wabt project.

3. Building it from the source:

   $ git clone --recursive https://github.com/WebAssembly/wabt
   $ cd wabt
   $ git submodule update --init
   $ cmake -B build -S .
   $ cmake --build build

Then, you need to make binaries visible to polygen tool. You can do this in two ways:

• Set the WABT_PATH environment variable to the directory with binaries (wabt/build if you built it from source):

  # assumes build from source path
  $ export WABT_PATH=$(pwd)/build

• Append the PATH environment variable to the directory with binaries (wabt/build if you built it from source):

  # assumes build from source path
  $ export PATH="$PATH:$(pwd)/build"

Installation

In your React Native project run:

npx @callstack/polygen init
# or
yarn dlx @callstack/polygen init

Usage

In your application folder run:

## npm
npx polygen scan
# apply changes in config
npx polygen generate

## yarn
yarn polygen scan
# apply changes in config
yarn polygen generate

Run polygen scan to search for changes in found WebModules. All modules must be explictly listed in polygen.config.[mc]js Run polygen generate after any of the WebAssembly module changed.

To use WebAssembly API, import @callstack/polygen/polyfill in your application (before any other imports):

import '@callstack/polygen/polyfill';

Metro

Polygen has a Metro plugin that allows you to import WebAssembly modules in your application.

Warning

Currently, only modules from the current package are supported. This will be implemented in the next version.

Add @callstack/polygen-metro-config dependency to your project:

yarn add -D @callstack/polygen-metro-config

Then, in your metro.config.js file, add the following:

const { withPolygenConfig } = require('@callstack/polygen-metro-config');

And wrap your Metro configuration with withPolygenConfig call:

const config = {
  // ...
};

module.exports = withPolygenConfig(
  mergeConfig(getDefaultConfig(__dirname), config)
);

Then, you should be able to import module buffers in your application:

import example from '../table_test.wasm';

const instance = new WebAssembly.Instance(new WebAssembly.Module(example));

Using Fetch

You can also pass WebAssembly module binary loaded using fetch, or any other method:

await WebAssembly.compileStreaming(
  fetch('http://localhost:8000/example.wasm')
)

The downloaded module is not actually executed, but a native counterpart is searched based on the module checksum.

This does not require any additional setup, but it has the overhead of fetching the module on runtime, just for it to be discarded.

For it to work, you need:

• Place exactly the same WebAssembly Module in src directory of your application.
• The module binary checksums must match

Examples

See apps directory for usage examples.

Contributing

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

Made with ❤️ at Callstack

Polygen is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. Callstack is a group of React and React Native geeks, contact us at [email protected] if you need any help with these or just want to say hi!

Like the project? ⚛️ Join the team who does amazing stuff for clients and drives React Native Open Source! 🔥