mbasso / react-wasm

Declarative WebAssembly instantiation for React

react-wasm

Declarative WebAssembly instantiation for React

Installation

You can install react-wasm using npm:

npm install --save react-wasm

If you aren't using npm in your project, you can include reactWasm using UMD build in the dist folder with <script> tag.

Usage

Render props

Once you have installed react-wasm, supposing a CommonJS environment, you can import and use it in this way:

import Wasm from "react-wasm";

// supposing an "add.wasm" module that exports a single function "add"
const ExampleComponent = () => (
  <Wasm url="/add.wasm">
    {({ loading, error, data }) => {
      if (loading) return "Loading...";
      if (error) return "An error has occurred";

      const { module, instance } = data;
      return <div>1 + 2 = {instance.exports.add(1, 2)}</div>;
    }}
  </Wasm>
);

Hooks

Since react-wasm uses the latest version of React, a useWasm hook is available:

import { useWasm } from "react-wasm";

// supposing an "add.wasm" module that exports a single function "add"
const ExampleComponent = () => {
  const {
    loading,
    error,
    data
  } = useWasm({
    url: '/add.wasm'
  });

  if (loading) return "Loading...";
  if (error) return "An error has occurred";

  const { module, instance } = data;
  return <div>1 + 2 = {instance.exports.add(1, 2)}</div>;
};

Higher Order Component

It's also possible to use the library using the HoC approach by importing the named withWasm function:

import { withWasm } from "react-wasm";

// supposing an "add.wasm" module that exports a single function "add"
const ExampleComponent = ({ loading, error, data }) => {
  if (loading) return "Loading...";
  if (error) return "An error has occurred";

  const { module, instance } = data;
  return <div>1 + 2 = {instance.exports.add(1, 2)}</div>;
};

// with a config object
const withAdd = withWasm({ url: "/add.wasm " });
const EnhancedExample = withAdd(ExampleComponent);

const App = () => <EnhancedExample />;

// with the "url" prop
const EnhancedExample = withWasm()(ExampleComponent);

const App = () => <EnhancedExample url="/add.wasm" />;

The second argument of the withWasm function is a props mapper. If you want to customize the information your child component will receive from the underlying Wasm component, you can do:

const mapToChild = ({ loading, error, data }) => ({
  hasLoaded: !loading,
  hasError: !!error,
  add: data && data.instance.add
});

const withAdd = withWasm({ url: "/add.wasm " }, mapToChild);
const EnhancedExample = withAdd(ExampleComponent);

const App = () => <EnhancedExample />;

API

type WasmConfig = {
  // you can instantiate modules using a URL
  // or directly a BufferSource (TypedArray or ArrayBuffer)
  url?: string,
  bufferSource?: BufferSource,
  // An optional object containing the values to be imported into the newly-created Instance
  // such as functions or WebAssembly.Memory objects.
  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/instantiate#Syntax
  importObject?: {},
};

type WasmResult = {
  loading: boolean,
  error: ?Error,
  data: ?{
    module: WebAssembly.Module,
    instance: WebAssembly.Instance
  }
};

type WasmProps = {
  ...$Exact<WasmConfig>,
  children: (renderProps: WasmResult) => React.Node
};

withWasm(
  config?: WasmConfig,
  mapProps?: ({ loading, error, data }: WasmResult) => Props
): (Component: React.ComponentType) => React.ComponentType

useWasm(config?: WasmConfig): WasmResult;

Browser support

react-wasm uses fetch and obviously WebAssembly APIs, they are broadly supported by major browser engines but you would like to polyfill them to support old versions.

if (!window.fetch || !window.WebAssembly) {
    ...
} else {
    ...
}

Change Log

This project adheres to Semantic Versioning.
Every release, along with the migration instructions, is documented on the Github Releases page.

Authors

Matteo Basso

• github/mbasso
• @teo_basso

Copyright and License

Copyright (c) 2019, Matteo Basso.

react-wasm source code is licensed under the MIT License.

react-wasm's Issues

Couldn't I just as easily handle this as actions of a flux application?

General Information

• Bug
• Improvement
• Feature
• [x ] Other: Chitchat

Description
I dig that you're sharing your interpretation and composition, is there any specific contextual reasoning that one wouldnt just stick their wasm in a projects flux actions, getting this as a composition agnostic abstraction?

(Add images if possible)

Expected 'application/wasm'

General Information

• Bug
• Improvement
• Feature
• [ X] Other

Description
TypeError: Failed to execute 'compile' on 'WebAssembly': Incorrect response MIME type. Expected 'application/wasm'.

It seems like I cannot instantiate webassemby streaming and I do not know how to add the mime type to the server.

Versions

• react:16.8.3
• react-wasm: 1.01
• browser: chrome Version 76.0.3809.132 (Official Build) (64-bit)
• expo: ^34.0.1

Reinstantiate wasm module on props change

The current implementation loads the module only on the initial mount of the component. We need to use a lifecycle method to detect props changes and reinstantiate it accordingly.

useWasm hook

The 4th of february [email protected] will be released, and it will contains hooks: facebook/react#14692.
This means that we can develop a useWasm hook, as said in #1, a new alternative to the render prop and HoC. Maybe something like:

const { loading, error, data } = useWasm({
  url: '/add.wasm'
});

@mfrachet let me know if you are interested in developing this 😄