@callstack/polygen

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 using your package manager:

# macOS
brew install wabt

# linux
sudo apt install wabt

Other installation options

If for some reason:

• you cannot use the package manager method,
• you are on Windows,
• or the version there is outdated,

you can still install wabt in a few other ways:

Option 1: Downloading prebuild binaries

Download precompiled binaries from the releases page of wabt project. Select correct version for your platform and extract it to the directory of your choice.

Option 2: Building from source

You can also build wabt from source. To do this, you need to have cmake and git installed on your machine.

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

Install binaries

You need to make binaries visible to Polygen. You can do this by adding the directory with the binaries to your system environment:

# Using WABT_PATH variable:
$ export WABT_PATH=/path/to/wabt/binaries

# or adding to PATH:
$ export PATH="$PATH:/path/to/wabt/binaries"

If you built WABT from source, the path should point to the build directory.

To make those changes persistent, add them to your .bashrc/.zshrc/.profile file.

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 [e-mail] 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! 🔥