Skip to content
Declarative WebAssembly instantiation for React
Branch: master
Clone or download
Latest commit b1c85e5 Mar 5, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github initial commit Jan 20, 2019
src useWasm hook Feb 27, 2019
test useWasm hook Feb 27, 2019
.babelrc initial commit Jan 20, 2019
.editorconfig initial commit Jan 20, 2019
.eslintignore initial commit Jan 20, 2019
.eslintrc useWasm hook Feb 27, 2019
.flowconfig initial commit Jan 20, 2019
.gitignore initial commit Jan 20, 2019
.travis.yml remove node 9 Feb 28, 2019
CHANGELOG.md initial commit Jan 20, 2019
CODE_OF_CONDUCT.md initial commit Jan 20, 2019
CONTRIBUTING.md initial commit Jan 20, 2019
LICENSE.md initial commit Jan 20, 2019
README.md readme API, update version Mar 5, 2019
package.json v1.0.1 Mar 5, 2019
webpack.config.js initial commit Jan 20, 2019
yarn.lock wip Jan 22, 2019

README.md

react-wasm

Build Status npm version npm downloads Coverage Status MIT Donate

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

Copyright and License

Copyright (c) 2019, Matteo Basso.

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

You can’t perform that action at this time.