Installing WasmThemis in ReactJS application #

This article is addressed application developers on React who want to use Themis to make cryptographic features in their products. The key step is configuring Webpack to use Themis.

Configure Webpack #

The second step is configuring Webpack. Webpack is the most useful tool for modern JavaScript applications, not only for React applications.

WasmThemis code is generated by Emscripten to be universal. It includes some references to Node.js modules for Node.js support, but they are not accessible in web browsers.

1. Create ReactJS application #

The easiest way to create a new application is to use the command

npx create-react-app my-app

or

yarn create react-app my-app --template typescript

Let us check that’s all correct.

cd my-app
yarn start

2. Use react-app-rewired #

Add react-app-rewired package to tweak create-react-app webpack config without eject.

yarn add react-app-rewired --dev

react-app-rewired gives all the benefits of create-react-app without the limitations of “no config”. You can add plugins and loaders whatever you need.

3. Install copy-webpack-plugin #

Install the webpack copy plugin that will copy libthemis.wasm to the output directory.

yarn add copy-webpack-plugin --dev

Be sure to add --dev option because you need to add the previous two packages to development dependencies.

4. Install Themis and Buffer #

Install WasmThemis if you haven’t previously, and Buffer (used for base64 conversions).

yarn add wasm-themis
yarn add buffer

5. Update package.json #

To use react-app-rewired, update package.json: replace start, build and test values in section “scripts” with the next values.

"scripts": {
   "start": "react-app-rewired start",
   "build": "react-app-rewired build",
   "test" : "react-app-rewired test",
    ... // don't change eject

Important: Do NOT flip the call for the eject script. That gets run only once for a project, after which you are given full control over the webpack configuration making react-app-rewired no longer required. There are no configuration options to rewire for the eject script.

6. Configure config-overrides.js #

Create (or configure already created) config-overrides.js (in the application folder):

const fs = require('fs');
const path = require('path');
const CopyWebpackPlugin = require('copy-webpack-plugin');
const CWD_PATH = fs.realpathSync(process.cwd());
const buildPath = process.env.BUILD_PATH || 'build';
const resolveApp = relativePath => path.resolve(CWD_PATH, relativePath);
const WASM_PATH = path.join(CWD_PATH, 'node_modules', 'wasm-themis/src/libthemis.wasm');
const SCRIPTS_PATH = path.join(resolveApp(buildPath), 'static/js/');
module.exports = function override(config, env) {
   if (!config.plugins) {
       config.plugins = [];
   }
   config.plugins.push(
       new CopyWebpackPlugin({ patterns: [{ from: WASM_PATH, to: SCRIPTS_PATH }] })
   );
   config['resolve']['fallback'] = {
       crypto: false,
       fs: false,
       http: false,
       https: false,
       net: false,
       path: false,
       stream: false,
       tls: false,
       util: false,
       url: false,
       zlib: false,
   }
   return config;
}

This config does two things: it copies libthemis.wasm file to the javascript build folder, and resolves unavailable modules, so WasmThemis can run in the browser.

7. Initialize Themis #

In your application code, initialize Themis and wait for it.

Important: WebAssembly code is loaded and compiled asynchronously so you have to wait for the initialize() promise to complete before using any Themis functions. If Themis is called too early, you will see an error message.

import { initialize } from 'wasm-themis';

function App() {
    useEffect(() => {
        initialize().then(() => {
            console.log("Themis initialized");
        }).catch( err => {
            // Themis initialization must be only once.
        })
    }, []);
}

We recommend to initialize Themis in useEffect() hook or componentDidMount() method.

Next steps #

You are good to go! Next browse code samples or read feature guides to learn how to use WasmThemis effectively.