Install

For a React app, install one package:

$ pnpm add @usewhisk/react

That is enough for most integrations. @usewhisk/react bundles the core engine as a regular dependency and re-exports the helpers and types you will actually touch (Chain, Token, Quote, FeeBearer, chainInfo, addressResolver, composeResolvers, and more), so every import in your app comes from @usewhisk/react. You never need to write @usewhisk/core in an import path.

The one required peer

@usewhisk/react uses wagmi internally, which needs @tanstack/react-query as a peer. If your app does not have it yet, add it:

$ pnpm add @tanstack/react-query

wagmi and viem themselves are bundled (regular dependencies of @usewhisk/react), so they are already in your node_modules after the first install. Add them to your own package.json only if you also call wagmi/viem APIs directly in your own code and want to pin a version.

Solana support (optional)

Add these only if your widget should accept sends from a Solana wallet (Phantom, Solflare, Backpack). EVM-only apps can skip this:

$ pnpm add @solana/wallet-adapter-react @solana/wallet-adapter-base

Going headless or framework-agnostic

There is exactly one situation that calls for installing @usewhisk/core on its own: you want to run the engine outside React, for example in a Node script, a Vue or Svelte app, or a server-side flow.

$ pnpm add @usewhisk/core

@usewhisk/core is framework-agnostic. It exposes createWhisk() plus the chain registry, fee logic, resolvers, error classes, and the state-machine reducer. No DOM, no React, no wallet imports.

Import the stylesheet once

Whisk's styles are scoped to a [data-whisk] attribute selector, so they never collide with the rest of your app. Import the stylesheet at the root of your tree and forget about it:

import "@usewhisk/react/styles.css";

If your bundler refuses CSS imports from node_modules (some older Webpack setups), reach for the explicit path:

import "@usewhisk/react/dist/styles.css";

Grab a WalletConnect project ID

EVM wallet connection runs through WalletConnect. Sign in to cloud.walletconnect.com, create a project, and copy the ID into your environment:

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your-project-id

Vite + Solana: polyfill Buffer

Skip this unless you're on Vite and using Solana. Next.js polyfills Node globals for you, so App Router and Pages Router apps need nothing here.

@solana/web3.js reaches for Node's Buffer global (base58 encoding, transaction serialization). The browser has no Buffer, and Vite doesn't shim it, so the first Solana operation — connecting a Solana wallet, or a CCTP bridge that crosses the Solana/EVM boundary — throws Buffer is not defined.

Add the polyfill once, at the very top of your entry file, before any other import so it's in place before wallet code loads:

import { Buffer } from "buffer";
if (typeof globalThis.Buffer === "undefined") {
  globalThis.Buffer = Buffer;
}

import React from "react";
import ReactDOM from "react-dom/client";
import "@usewhisk/react/styles.css";
import { App } from "./App";
// …

The buffer package ships as a transitive dependency of the Solana SDK, but some package managers won't surface it to your app's node_modules. If the import doesn't resolve, install it directly:

$ pnpm add buffer

Verify the install

Quick sanity check before you move on. Add this to any page in your app:

import { allChains } from "@usewhisk/react";

console.log(allChains().map((c) => c.id));

You should see a list of supported chains in the console. If the import fails or the array is empty, the install didn't land. Start again from the top.

Next

Mount the provider so the widget can read from the wallet stack.