Polygen

Polygen is a library for React Native that allows you to run WebAssembly modules in your apps, statically, without interpreting.

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. Downloading precompiled binaries from the releases page of wabt project.

2. 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

npm i -g @callstack/polygen

Usage

In your application folder run:

polygen init
polygen generate

Run polygen update 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 hello@callstack.com 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! 🔥