Seald: documentation

English

Français

English

Français

Imports ​

All these methods expose a constructor with the same SealdSDK constructor function interface.

In general, importing the SDK and its plugins directly should work in most cases.

javascript
import SealdSDK from '@seald-io/sdk'
import SealdSDKPluginSSKSPassword from '@seald-io/sdk-plugin-ssks-password'
import SealdSDKPluginSSKS2MR from '@seald-io/sdk-plugin-ssks-2mr'

const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKSPassword(keyStorageURL), SealdSDKPluginSSKS2MR(keyStorageURL)] })

However, you may want more control over which version of the SDK is used, which polyfills are included, etc. This guide will explain all possible options and their differences.

WARNING

Whichever the platform or the way you import it, it is not recommended to use Hot-Reload, Hot-Restart, or any similar feature, when developing with the Seald SDK, in particular when using a persistant database.

These techniques start a second instance of the code, without properly terminating the first one, which can cause corruption problems with the local database.

Browser ​

There are 3 ways to use the Seald SDK in your browser, depending on your needs and your web app architecture.

Polyfilled library ​

javascript
import SealdSDK from '@seald-io/sdk' // if your bundler supports the "browser" field in package.json (supported by Webpack 5)

const seald = SealdSDK({ appId, apiURL })
javascript
import SealdSDK from '@seald-io/sdk/browser' // if your bundler supports custom entry-points (supported by Webpack 5)

const seald = SealdSDK({ appId, apiURL })
javascript
import SealdSDK from '@seald-io/sdk/browser/seald-sdk.polyfilled.js' // explicit import

const seald = SealdSDK({ appId, apiURL })

In the same way, you can import the following files for plugins:

javascript
// plugin-ssks-password
import SealdSDKPluginSSKSPassword from '@seald-io/sdk-plugin-ssks-password' // if your bundler supports the "browser" field in package.json (supported by Webpack 5)

// plugin-ssks-2mr
import SealdSDKPluginSSKS2MR from '@seald-io/sdk-plugin-ssks-2mr' // if your bundler supports the "browser" field in package.json (supported by Webpack 5)
javascript
// plugin-ssks-password
import SealdSDKPluginSSKSPassword from '@seald-io/sdk-plugin-ssks-password/browser' // if your bundler supports custom entry-points (supported by Webpack 5)

// plugin-ssks-2mr
import SealdSDKPluginSSKS2MR from '@seald-io/sdk-plugin-ssks-2mr/browser' // if your bundler supports custom entry-points (supported by Webpack 5)
javascript
// plugin-ssks-password
import SealdSDKPluginSSKSPassword from '@seald-io/sdk-plugin-ssks-password/browser/seald-sdk-plugin-ssks-password.polyfilled.js' // explicit import

// plugin-ssks-2mr
import SealdSDKPluginSSKS2MR from '@seald-io/sdk-plugin-ssks-2mr/browser/seald-sdk-plugin-ssks-2mr.polyfilled.js' // explicit import

This is a bundle, which already includes all necessary libraries, dependencies, and polyfills.

Use this method if you are using a bundler such as webpack, but you do not want to configure your bundler to include necessary polyfills.

Library ​

javascript
import SealdSDK from '@seald-io/sdk/browser-library' // if your bundler supports custom entry-points (supported by Webpack 5)

const seald = SealdSDK({ appId, apiURL })
javascript
import SealdSDK from '@seald-io/sdk/browser/seald-sdk.js' // explicit import

const seald = SealdSDK({ appId, apiURL })

This imports @seald-io/sdk/browser/seald-sdk.js, which is the wrapper for the browser.

In the same way, you can import the following files for plugins:

javascript
// plugin-ssks-password
import SealdSDKPluginSSKSPassword from '@seald-io/sdk-plugin-ssks-password/library' // if your bundler supports custom entry-points (supported by Webpack 5)

// plugin-ssks-2mr
import SealdSDKPluginSSKS2MR from '@seald-io/sdk-plugin-ssks-2mr/library' // if your bundler supports custom entry-points (supported by Webpack 5)
javascript
// plugin-ssks-password
import SealdSDKPluginSSKSPassword from '@seald-io/sdk-plugin-ssks-password/lib/main.js' // explicit import

// plugin-ssks-2mr
import SealdSDKPluginSSKS2MR from '@seald-io/sdk-plugin-ssks-2mr/lib/main.js' // explicit import

Use this method if you are using a bundler such as webpack. For this purpose, see the Custom bundling and transpilation section.

This method is recommended, as it reduces the duplication of dependencies and polyfills, so it minimizes the final size of your application.

Bundle ​

Copy the file @seald-io/sdk/browser/seald-sdk.browser.js into your project, then load it in a <script> tag.

In the same way, you can copy the following files for plugins:

  • @seald-io/sdk-plugin-ssks-password/browser/seald-sdk-plugin-ssks-password.browser.js
  • @seald-io/sdk-plugin-ssks-2mr/browser/seald-sdk-plugin-ssks-2mr.browser.js

For example, to import the SDK and the SSKS-Password plugin:

html
<html>
<head>
...
<script src="/libraries/seald-sdk.browser.js"></script>
<script src="/libraries/seald-sdk-plugin-ssks-password.browser.js"></script>
<script>
var seald = window.SealdSDK({ appId, apiURL, plugins: [ window.SealdSDKPluginSSKSPassword(keyStorageURL) ] })
</script>
...
</head>
</html>

This is a bundle, which already includes all necessary libraries, dependencies, and polyfills.

It exposes the Seald SDK constructor function in the global variable window.SealdSDK.

Plugins are exposed in the global variables:

  • window.SealdSDKPluginSSKSPassword
  • window.SealdSDKPluginSSKS2MR

Node.js / Electron ​

javascript
import SealdSDK from '@seald-io/sdk'

const seald = SealdSDK({ appId, apiURL })

This imports the Node wrapper for the Seald SDK.

You may want to use this on your NodeJS server, in an Electron desktop application, for your unit-tests ...

React-Native ​

Installation ​

The Seald SDK for react-native has peer dependencies that must be installed separately:

  • @react-native-async-storage/async-storage (for versions 0.11.X and earlier, it was the @react-native-community/async-storage package)
  • @seald-io/react-native-scrypt (for versions 0.23.X and earlier, it was the react-native-scrypt package)
  • react-native-quick-crypto
  • @craftzdog/react-native-buffer
  • react-native-quick-base64

You can install them with the command:

sh
npm i -S @react-native-async-storage/async-storage @seald-io/react-native-scrypt react-native-quick-crypto @craftzdog/react-native-buffer react-native-quick-base64

The use of react-native-quick-crypto and our SDK makes it necessary to define a specific Buffer polyfill in global. As early as possible in your application, add the following lines:

js
import { Buffer } from '@craftzdog/react-native-buffer'
global.Buffer = Buffer

Bundle ​

The library exposed by default is a bundle, which already includes all necessary libraries, dependencies, and polyfills.

javascript
import SealdSDK from '@seald-io/sdk' // if your bundler supports the "react-native" field in package.json (supported by Metro)

const seald = SealdSDK({ appId, apiURL })
javascript
import SealdSDK from '@seald-io/sdk/react-native' // if your bundler supports custom entry-points (not supported by Metro)

const seald = SealdSDK({ appId, apiURL })
javascript
import SealdSDK from '@seald-io/sdk/react-native/seald-sdk-react-native.bundle.js' // explicit import

const seald = SealdSDK({ appId, apiURL })

In the same way, you can import the following files for plugins:

javascript
// plugin-ssks-password
import SealdSDKPluginSSKSPassword from '@seald-io/sdk-plugin-ssks-password' // if your bundler supports the "react-native" field in package.json (supported by Metro)

// plugin-ssks-2mr
import SealdSDKPluginSSKS2MR from '@seald-io/sdk-plugin-ssks-2mr' // if your bundler supports the "react-native" field in package.json (supported by Metro)
javascript
// plugin-ssks-password
import SealdSDKPluginSSKSPassword from '@seald-io/sdk-plugin-ssks-password/react-native/seald-sdk-plugin-ssks-password.bundle.js' // explicit import

// plugin-ssks-2mr
import SealdSDKPluginSSKS2MR from '@seald-io/sdk-plugin-ssks-2mr/react-native' // if your bundler supports custom entry-points (not supported by Metro)
javascript
// plugin-ssks-password
import SealdSDKPluginSSKSPassword from '@seald-io/sdk-plugin-ssks-password/react-native/seald-sdk-plugin-ssks-password.bundle.js' // explicit import

// plugin-ssks-2mr
import SealdSDKPluginSSKS2MR from '@seald-io/sdk-plugin-ssks-2mr/react-native/seald-sdk-plugin-ssks-2mr.bundle.js' // explicit import

React-Native accelerator ​

When using the @seald-io/sdk package in a react-native application, we recommend using the @seald-io/react-native-accelerator utility. This utility improves the speed of encryption and decryption.

Library ​

If your application is itself transpiled, you can import the source library. This will allow you to optimise the size of your application.

javascript
import SealdSDK from '@seald-io/sdk/react-native-library' // if your bundler supports custom entry-points (not supported by Metro)

const seald = SealdSDK({ appId, apiURL })
javascript
import SealdSDK from '@seald-io/sdk/react-native/react-native/seald-sdk-react-native.js' // explicit import

const seald = SealdSDK({ appId, apiURL })

This library will need to be transpiled before it can be used. See the Custom bundling and transpilation section.

In the same way, you can import the following files for plugins:

javascript
// plugin-ssks-password
import SealdSDKPluginSSKSPassword from '@seald-io/sdk-plugin-ssks-password/library' // if your bundler supports custom entry-points (not supported by Metro)

// plugin-ssks-2mr
import SealdSDKPluginSSKS2MR from '@seald-io/sdk-plugin-ssks-2mr/library' // if your bundler supports custom entry-points (not supported by Metro)
javascript
// plugin-ssks-password
import SealdSDKPluginSSKSPassword from '@seald-io/sdk-plugin-ssks-password/lib/main.js' // explicit import

// plugin-ssks-2mr
import SealdSDKPluginSSKS2MR from '@seald-io/sdk-plugin-ssks-2mr/lib/main.js' // explicit import

Custom bundling and transpilation ​

To transpile the SDK, you may need to enable polyfilling of Node's internal modules.

Here is an example configuration for the Webpack 5 bundler :

javascript
module.exports = {
  // ... ,
  node: {
    global: true
  },
  resolve: {
    fallback: {
      assert: require.resolve('assert/'),
      fs: false,
      path: require.resolve('path-browserify'),
      events: require.resolve('events/'),
      constants: require.resolve('constants-browserify'),
      os: require.resolve('os-browserify/browser'),
      util: require.resolve('util/'),
      stream: require.resolve('readable-stream'),
      crypto: false
    }
  },
  plugins: [
    new webpack.ProvidePlugin({
      process: 'process/browser',
      Buffer: ['buffer', 'Buffer'],
      setImmediate: ['timers-browserify', 'setImmediate'],
      clearImmediate: ['timers-browserify', 'clearImmediate']
    })
  ]
  // ...
}

You may need to install as devDependencies the packages assert path-browserify events constants-browserify os-browserify util stream-browserify process buffer timers-browserify.

For more details, see the webpack documentation.

React-Native ​

Some SDK dependencies have specific implementations for React-Native declared as aliases in the "react-native" field of their package.json field. This field is automatically used by metro.

If you use an intermediate bundler before using metro (like webpack), you will need to specify it. You will also need to declare the native React-Native dependencies as external. With webpack, you need to add the following options:

js
module.exports = {
  externals: [
    '@craftzdog/react-native-buffer',
    'react-native-quick-crypto',
    'react-native-quick-base64',
    'buffer',
    'crypto',
    'react-native',
    '@seald-io/react-native-scrypt',
    '@react-native-async-storage/async-storage'
  ],
  resolve: {
    aliasFields: ['react-native', 'browser', 'main'],
    fallback: {
      assert: require.resolve('assert/'),
      buffer: '@craftzdog/react-native-buffer',
      fs: false,
      path: require.resolve('path-browserify'),
      events: require.resolve('events/'),
      constants: require.resolve('constants-browserify'),
      os: require.resolve('os-browserify/browser'),
      util: require.resolve('util/'),
      url: require.resolve('url/'),
      stream: require.resolve('stream-browserify')
    }
  }
}