@hieco/react

@hieco/react brings the Hieco SDK into React with providers, TanStack Query integration, and hooks that feel native in modern app code.

If @hieco/sdk is the engine room, @hieco/react is the layer that lets your component tree use it with less ceremony and better caching.

Why This Package Exists

React apps need more than direct SDK calls. They need:

• a shared client lifecycle
• a clear place to provide a signer
• query keys and invalidation that match the data model
• hooks that fit loading, error, and success states cleanly

@hieco/react wraps @hieco/sdk in that experience.

When To Use It

Choose @hieco/react when you are building:

• React apps that read Hedera data
• React apps that submit transactions
• wallet-connected UIs that pass a signer into a shared client
• server-rendered or hydrated React apps that already use TanStack Query

If you only need a non-React client, use @hieco/sdk.

Installation

npm install @hieco/react @hieco/sdk @tanstack/react-query

pnpm add @hieco/react @hieco/sdk @tanstack/react-query

yarn add @hieco/react @hieco/sdk @tanstack/react-query

bun add @hieco/react @hieco/sdk @tanstack/react-query

Peer dependencies expected from the host app:

• react >= 18
• react-dom >= 18

Quick Start

import { HiecoProvider, useAccountInfo } from "@hieco/react";

function AccountCard() {
  const account = useAccountInfo({ accountId: "0.0.1001" });

  if (account.isPending) return <div>Loading...</div>;
  if (account.isError) return <div>{account.error.message}</div>;

  return <pre>{JSON.stringify(account.data, null, 2)}</pre>;
}

export function App() {
  return (
    <HiecoProvider config={{ network: "testnet" }}>
      <AccountCard />
    </HiecoProvider>
  );
}

The Usual Flow

Most apps follow this pattern:

1. Mount HiecoProvider.
2. Pass public client config with config.
3. Pass a signer when the app becomes wallet-connected.
4. Use Hieco hooks in components.

The provider can create its own QueryClient when needed, or reuse one from the host app.

Runtime Boundaries

The package is deliberately strict about runtime boundaries:

• config only accepts public client configuration
• operator credentials stay in server-only @hieco/sdk code
• signer is passed separately as session state

That split keeps React code focused on client state and queries instead of lower-level SDK configuration.

Common Workflows

Use a wallet signer

import { HiecoProvider } from "@hieco/react";
import { WalletProvider, useWallet } from "@hieco/wallet-react";

function HiecoRuntime({ children }: { children: React.ReactNode }) {
  const wallet = useWallet();

  return (
    <HiecoProvider config={{ network: "testnet" }} signer={wallet.session?.signer}>
      {children}
    </HiecoProvider>
  );
}

Reuse your own QueryClient

import { QueryClient } from "@tanstack/react-query";
import { HiecoProvider } from "@hieco/react";

const queryClient = new QueryClient();

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <HiecoProvider config={{ network: "testnet" }} queryClient={queryClient}>
      {children}
    </HiecoProvider>
  );
}

API At A Glance

Core exports:

• HiecoProvider
• generated query and mutation hooks
• createHiecoQueryKey
• createHiecoMutationKey

The package also re-exports the @hieco/sdk surface so shared types and helpers stay close at hand in React code.

There is also an optional AppKit subpath:

• @hieco/react/appkit

Use that only when you specifically need the AppKit bridge.

Packaging And Runtime Support

@hieco/react publishes:

• browser-friendly ESM output
• externalized dependencies in the published build
• explicit conditional exports for browser, worker, workerd, node, and default

That keeps the package easier to consume in modern React stacks without changing how the public API feels in app code.

Related Packages

• @hieco/sdk for the underlying fluent client
• @hieco/wallet-react for wallet connection in React
• @hieco/wallet for wallet runtime control outside React