npm package: @qubic.ts/react
Description: React providers, hooks, typed contract helpers, and wallet connectors for Qubic apps.
Latest version: 1.6.2

# @qubic.ts/react

React providers, hooks, typed contract helpers, and wallet connectors for Qubic apps.

## See Also

- Workspace overview: [`../../README.md`](../../README.md)
- Core primitives: [`../core/README.md`](../core/README.md)
- Contracts metadata: [`../contracts/README.md`](../contracts/README.md)
- SDK helpers: [`../sdk/README.md`](../sdk/README.md)

## Install

```bash
bun add @qubic.ts/react @qubic.ts/sdk @tanstack/react-query react react-dom
# or
npm install @qubic.ts/react @qubic.ts/sdk @tanstack/react-query react react-dom
```

## Quickstart

```tsx
import { createSdk } from "@qubic.ts/sdk/browser";
import { QubicQueryProvider, SdkProvider, useTickInfo } from "@qubic.ts/react";

const sdk = createSdk({
  baseUrl: "https://rpc.qubic.org",
  txQueue: { enabled: false },
});

function TickView() {
  const tick = useTickInfo();
  if (!tick.data) return null;
  return <span>{tick.data.tick.toString()}</span>;
}

export function App() {
  return (
    <QubicQueryProvider>
      <SdkProvider sdk={sdk}>
        <TickView />
      </SdkProvider>
    </QubicQueryProvider>
  );
}
```

## Typed Contracts Example

```tsx
import { coreContractsRegistry } from "@qubic.ts/contracts/browser";
import { createSdkProvider } from "@qubic.ts/react";

const app = createSdkProvider();

function ContractsInfo() {
  const registry = coreContractsRegistry.contracts.map((contract) => contract.name);
  return <pre>{registry.join("\n")}</pre>;
}

export { ContractsInfo, app };
```

## Wallet and Vault Options

- `VaultConnector`
- `WalletConnectConnector`
- `MetaMaskSnapConnector`
- `QubicExtensionConnector`
- browser vault helpers from `@qubic.ts/react/browser`
- node vault helpers from `@qubic.ts/react/node`

### Connector Capability Matrix

| Connector | `connect` | `requestAccounts` | `signTransaction` | `signMessage` | `restore` |
| --- | --- | --- | --- | --- | --- |
| `VaultConnector` | ✅ | ✅ | ✅ (`kind: "vault"`) | ❌ | ❌ |
| `WalletConnectConnector` | ✅ (pending approval flow) | ✅ | ✅ (`kind: "walletconnect"`) | ❌ | ✅ |
| `MetaMaskSnapConnector` | ✅ | ✅ | ✅ (`kind: "snap"`) | ❌ | ❌ |
| `QubicExtensionConnector` | ✅ | ✅ | ✅ (`kind: "qubic-extension"`) | ✅ (`kind: "qubic-extension"`) | ✅ |

Notes:
- If `signMessage` is called on a connector without message capability, `WalletProvider` throws an error with code `METHOD_NOT_SUPPORTED`.
- `sendTransaction` is intentionally not exposed through `WalletProvider` in this batch.

## Qubic Extension Connector Quickstart

```tsx
import { QubicExtensionConnector, WalletProvider, useWallet } from "@qubic.ts/react";

const extensionConnector = new QubicExtensionConnector();

function DappActions() {
  const wallet = useWallet();

  const connectAndSign = async () => {
    await wallet.connect("qubic-extension");

    const signedMessage = await wallet.signMessage({
      kind: "qubic-extension",
      message: { message: "hello qubic" },
    });

    const signedTx = await wallet.signTransaction({
      kind: "qubic-extension",
      toIdentity: "DESTINATION_IDENTITY",
      amount: "1",
    });

    console.log(signedMessage.signatureHex, signedTx.signedTxBase64);
  };

  return <button onClick={() => void connectAndSign()}>Connect & Sign</button>;
}

export function App() {
  return (
    <WalletProvider connectors={[extensionConnector]}>
      <DappActions />
    </WalletProvider>
  );
}
```

Notes:
- `QubicExtensionConnector` wraps `window.qubic` from the browser extension.
- Current `@qubic.ts/react` wallet surface includes `signMessage` and `signTransaction` for this connector.
- `sendTransaction` is not exposed through `WalletProvider` in this batch.

## Browser Vault Quickstart

```ts
import { createBrowserVault, createMemoryVaultStore } from "@qubic.ts/react/browser";

const store = createMemoryVaultStore("demo");
const vault = await createBrowserVault({
  store,
  passphrase: "secret-passphrase",
});

console.log(await vault.listEntries());
```

## Node Vault Quickstart

```ts
import { openNodeVault } from "@qubic.ts/react/node";

const vault = await openNodeVault({
  path: "./vault.json",
  passphrase: "secret-passphrase",
  create: true,
});

console.log(await vault.listEntries());
```

## Runtime Notes

- Use `@qubic.ts/react/browser` only in browser/client runtime code.
- Use `@qubic.ts/react/node` only in Node/server code.
- Avoid importing node vault helpers from client bundles.