Add the Kima Transaction Widget to a React App

You can add the widget to your React project simply by running:

yarn add @kimafinance/kima-transaction-widget

There are several configuration options, which we will describe below.

Note that if you are using a later version of webpack (>= 5), you will need to polyfill node core modules using react-app-rewired.

You can resolve this by adding a file at the root of your project named config-overrides.js. Paste the following content into the file:

Copy

const { ProvidePlugin } = require('webpack')

module.exports = function override(config, env) {
  return {
    ...config,
    module: {
      ...config.module,
      rules: [
        ...config.module.rules,
        {
          test: /\.js$/,
          enforce: 'pre',
          use: ['source-map-loader']
        },
        {
          test: /\.cjs$/,
          type: 'javascript/auto'
        },
        {
          test: /\.wasm$/,
          type: 'webassembly/async'
        },
        {
          test: /\.m?js/,
          type: 'javascript/auto'
        },
        {
          test: /\.m?js/,
          resolve: {
            fullySpecified: false
          },
        },
        {
          test: /\.json$/,
          use: 'json-loader',
          type: 'javascript/auto' // This is important to prevent Webpack 5 from treating JSON as ESM
        }
      ]
    },
    plugins: [
      ...config.plugins,
      new ProvidePlugin({
        Buffer: ['buffer', 'Buffer'],
        process: 'process/browser'
      })
    ],
    resolve: {
      ...config.resolve,
      fallback: {
        assert: 'assert',
        buffer: 'buffer',
        console: 'console-browserify',
        constants: 'constants-browserify',
        crypto: 'crypto-browserify',
        domain: 'domain-browser',
        events: 'events',
        fs: false,
        http: 'stream-http',
        https: 'https-browserify',
        os: 'os-browserify/browser',
        path: 'path-browserify',
        punycode: 'punycode',
        process: 'process/browser',
        querystring: 'querystring-es3',
        stream: 'stream-browserify',
        _stream_duplex: 'readable-stream/duplex',
        _stream_passthrough: 'readable-stream/passthrough',
        _stream_readable: 'readable-stream/readable',
        _stream_transform: 'readable-stream/transform',
        _stream_writable: 'readable-stream/writable',
        string_decoder: 'string_decoder',
        sys: 'util',
        timers: 'timers-browserify',
        tty: 'tty-browserify',
        url: 'url',
        util: 'util',
        vm: 'vm-browserify',
        zlib: 'browserify-zlib'
      }
    },
    experiments: {
      asyncWebAssembly: true
    },
    ignoreWarnings: [/Failed to parse source map/]
  }
}

The easiest way to see the widget working, including the workaround above, is to check out the example in the widget repo.

If you are creating your application from scratch and assuming you are using TypeScript, create a file App.tsx and an Index.tsx.

Bridge scenario

Let's demonstrate the Kima bridging function first, which allows your users to transfer value between chains.

Into your App.tsx paste:

Copy

import React from 'react'

import {
  KimaTransactionWidget,
  KimaProvider,
  FontSizeOptions,
  ModeOptions,
  ColorModeOptions
} from '@kimafinance/kima-transaction-widget'
import '@kimafinance/kima-transaction-widget/dist/index.css'

const App = () => {
  return (
    <KimaProvider>
      <KimaTransactionWidget
        theme={{
          colorMode: ColorModeOptions.dark,
          fontSize: FontSizeOptions.medium
        }}
        mode={ModeOptions.bridge}
        kimaBackendUrl='http://localhost:3001'
        kimaNodeProviderQuery='https://api.demo.kima.finance'
        compliantOption={false}
        errorHandler={(e: any) => {
          console.log('error:', e)
        }}
        successHandler={() => {
          console.log('success')
        }}
        closeHandler={() => {
          console.log('closed')
        }}
      />
    </KimaProvider>
  )
}

export default App

Create a simple index.css with the following code:

Copy

body {
  margin: 0;
  padding: 0;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
    sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

code {
  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
    monospace;
}

#root {
  padding-top: 50px;
}

.container {
  max-width: 1440px;
  margin: 40px auto;
  display: flex;
  justify-content: center;
}

In your Index.tsx paste the following code:

Copy

import './index.css'

import React from 'react'
import ReactDOM from 'react-dom'
import App from './App'

ReactDOM.render(<App />, document.getElementById('root'))

Start your app with yarn start and you should see the Kima modal on localhost:3000.

It should look something like this:

The example above provides the most basic example of the bridge functionality, with generic styling and configuration.

Note that it makes the assumption that you also have the development server running on port 3001.

Payment scenario

Next, try the Kima Transaction Widget's payment scenario.

Replace the code in App.tsx with the following:

Copy

import React from 'react'

import {
  KimaTransactionWidget,
  KimaProvider,
  FontSizeOptions,
  ModeOptions,
  SupportNetworks,
  ColorModeOptions
} from '@kimafinance/kima-transaction-widget'
import '@kimafinance/kima-transaction-widget/dist/index.css'

const App = () => {
  return (
    <KimaProvider>
      <KimaTransactionWidget
        theme={{
          colorMode: ColorModeOptions.light,
          fontSize: FontSizeOptions.medium
        }}
        mode={ModeOptions.payment}
        kimaBackendUrl='https://demo.kima.finance/backend'
        kimaNodeProviderQuery='https://api.kima.finance'
        titleOption={{
          initialTitle: 'New Purchase'
        }}
        paymentTitleOption={{
          title:
            'Buy your custom product here',
          style: {
            fontSize: '1.2em',
            fontWeight: '500',
            color: '#DDDDDD'
          }
        }}
        compliantOption={false}
        errorHandler={(e: any) => {
          console.log('error:', e)
        }}
        successHandler={() => {
          console.log('success')
        }}
        closeHandler={() => {
          console.log('closed')
        }}
      />
    </KimaProvider>
  )
}

export default App

You should see a page that looks like this:

Configuration options

Note that in the above example, we have configured the title and payment title text, along with the colour. These are just some of the configuration options we describe below.

Configure the widget's look and feel

There are numerous ways to configure the modal for your own preferences and the look and feel of your dApp, which you can do via the following props:

Theme

The Theme prop allows you not only to switch between light and dark mode but also to specify your font colour and style and background colour:

Copy

  theme={{
    colorMode: ColorModeOptions.light,
    fontSize: FontSizeOptions.medium,
    fontFamily: 'Sans Serif',
    backgroundColorLight: '#CCCCCC', // background color of widget when light mode
    backgroundColorDark: '#FFDDFF' // background color of widget when dark mode
  }}

Title

The Title prop enables you to give the widget whatever title you want and can be configured for each step of the widget.

• Required: false

• Type: TitleOption:

Copy

titleOption={{
    initialTitle: 'New Purchase'
}}

Payment Title

The PaymentTitle prop allows you to optionally set the title that appears on the payment screen if you are using the Payment component.

• Required: false

• Type: PaymentTitleOption

Copy

 paymentTitleOption={{
   title:
     'You can now purchase our NFT on Polygon, using funds from other chains.',
   style: {
     fontSize: '1.2em',
     fontWeight: '500'
   }
 }}

HelpUrl

This is a string, which should be to your own help documentation or FAQ. If unset, the link will default to Kima's help documentation.

• Required: false

• Type: string

Configure the widget's functionality

Used to specify the scenario of kima-transaction-widget. Available modes are payment, bridget and status.

Required: true Type: ModeOptions Payment and bridge scenario for the purpose of widget, status mode is for tracking status of specific transaction of kima widget. To use status mode, txId prop should be determined export declare enum ModeOptions { payment = 'payment', bridge = 'bridge', status = 'status' }

TransactionOption

Within the payment scenario, you may optionally want to preset the chain and wallet address where the payment should go, as well as the payment amount.

• Required: false

• Type: TransactionOption

Copy

transactionOption={{
  targetChain: SupportNetworks.AVALANCHE, // target chain to receive payment
  targetAddress: '0x8222ADB2A2092c3774105a5F558987265D920C09', // target address to receive payment
  amount: 5 // USDK amount to receive payment
}}

kimaBackendUrl

This is one of the few props that is mandatory to set, because this specifies Kima's transaction back end URL. In the bridge example above, we have made the assumption that you have the back end server running locally on localhost:3001.

• Required: true

• Type: string

kimaNodeProviderQuery

Again, this is mandatory because this is used to specify the REST API URL for interactions with the Kima blockchain.

• Required: true

• Type: string

kimaExplorer

This is used to specify the URL of Kima's block explorer in the environment you are using. The widget needs this to provide updates to the status screen, as well as allowing users to link to their transactions to view progress.

It is not mandatory, but it is highly recommended.

Required: false Type: string Default: explorer.kima.finance

txID

Similarly, this is used to show users the progress of their transactions. It is not mandatory and is used only for status mode.

• Required: false

• Type: boolean

• Default: -1

useFIAT

Used to specify whether users should be given the option to transact with fiat currency.

• Required: false

• Type: boolean

• Default: false

autoConnect

This prop is optional and allows you to define whether connection of wallets such as MetaMask should be automatic or manual.

• Required: false

• Type: boolean

• Default: false

Configure Kima Provider

Used to provide the widget with wallet connection and chain switching functionality.

walletConnectProjectId

Used to specify the WalletConnect project id. A default value is provided, but you can specify your own. To create a project, visit Reown Cloud and sign up for a free account (WalletConnect is now called Reown).

• Required: false

• Type: string

networkOption

Used to specify the network type.

• Required: false

• Type: NetworkOptions

• Default: NetworkOptions.testnet