NextJS

This guide uses the Next.js App Router pattern, which matches the maintained example in the widget repository. The widget must run on the client, so the widget component should be a client component and exported through dynamic(..., { ssr: false }).

To create a new app, you can run npx create-next-app@latest <your-app-name>. Then install the Kima Widget and its peer dependencies.

npm install @kimafinance/kima-transaction-widget redux react-redux pino-pretty

You'll need to add the following:

• A client-side widget component

• The <KimaProvider> component

• The <KimaTransactionWidget> component

• A link to the Kima Transaction Backend (or build your own)

• A Reown project id

If you don't have one already, you'll need to get a free Reown project ID from Reown Cloud and pass it to the projectId prop on <KimaProvider>.

Create a file at src/components/KimaWidget.tsx with the following code:

"use client";

import dynamic from "next/dynamic";
import React from "react";

import {
  KimaTransactionWidget,
  KimaProvider,
  ModeOptions,
  ColorModeOptions,
} from "@kimafinance/kima-transaction-widget";
import "@kimafinance/kima-transaction-widget/index.css";

const Widget = () => {
  return (
    <KimaProvider
      projectId="your-project-id"
      kimaBackendUrl="http://localhost:4000"
    >
      <KimaTransactionWidget
        theme={{ colorMode: ColorModeOptions.light }}
        mode={ModeOptions.bridge}
      />
    </KimaProvider>
  );
};

const KimaWidget = dynamic(() => Promise.resolve(Widget), {
  ssr: false,
});

export default KimaWidget;

Then render it from src/app/page.tsx:

"use client";

import KimaWidget from "@/components/KimaWidget";

export default function Home() {
  return <KimaWidget />;
}

If your project does not use the @/ alias, replace it with the relative import path to src/components/KimaWidget.

When you visit http://localhost:3000 you will see something like this:

The widget example maintained in this repo follows the same structure:

• src/components/KimaWidget.tsx for the client-side dynamic widget wrapper

• src/app/page.tsx for rendering the widget in the App Router

See the Configuration options section for more details on setting up the widget.

Pages Router

If your app still uses the older Pages Router, the same client-only requirement applies, but the maintained reference example in this repo is App Router first.

Troubleshooting

Turbopack (Development)

The widget is not currently compatible with the --turbopack flag. Please disable this flag when running the development server.