# @react-terra/hooks

> React hooks for building professional-quality Terra dApps.

Latest version **0.0.868** (published 2021-10-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install @react-terra/hooks
pnpm add @react-terra/hooks
yarn add @react-terra/hooks
bun add @react-terra/hooks
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.868 |
| Published | 2021-10-31 |
| First published | 2021-10-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 11 |
| Unpacked size | 280.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 21 |
| Author | jkhaui |
| Maintainers | jkhaui |

## Links

- npm: https://www.npmjs.com/package/@react-terra/hooks
- Repository: https://github.com/jkhaui/react-terra
- Homepage: https://github.com/jkhaui/react-terra#readme
- Issues: https://github.com/jkhaui/react-terra/issues
- npm.io page: https://npm.io/package/@react-terra/hooks

## Dependencies (11)

- [immer](https://npm.io/package/immer.md) ^9.0.6
- [big.js](https://npm.io/package/big.js.md) ^6.1.1
- [flatted](https://npm.io/package/flatted.md) ^3.2.2
- [fast-equals](https://npm.io/package/fast-equals.md) ^2.0.3
- [rxjs-websockets](https://npm.io/package/rxjs-websockets.md) ^9.0.0
- [observable-hooks](https://npm.io/package/observable-hooks.md) ^4.0.5
- [@react-terra/ui-assets](https://npm.io/package/@react-terra/ui-assets.md) ^0.0.85
- [@use-it/event-listener](https://npm.io/package/@use-it/event-listener.md) ^0.1.6
- [@webreflection/json-map](https://npm.io/package/@webreflection/json-map.md) ^0.1.0
- [@internationalized/number](https://npm.io/package/@internationalized/number.md) ^3.0.3
- [@terra-money/ledger-terra-js](https://npm.io/package/@terra-money/ledger-terra-js.md) ^1.1.0

## Recent versions

- 0.0.868 (latest) — 2021-10-31
- 0.0.867 — 2021-10-28
- 0.0.866 — 2021-10-27
- 0.0.865 — 2021-10-24
- 0.0.864 — 2021-10-20
- 0.0.863 — 2021-10-20
- 0.0.862 — 2021-10-20
- 0.0.861 — 2021-10-20
- 0.0.86 — 2021-10-20
- 0.0.859 — 2021-10-20
- 0.0.858 — 2021-10-19
- 0.0.857 — 2021-10-19
- 0.0.856 — 2021-10-19
- 0.0.855 — 2021-10-19
- 0.0.854 — 2021-10-19
- … 5 more at https://npm.io/package/@react-terra/hooks/versions

## README

![img.png](logo-type.png)
![img.png](logo-illustration.png)

## Overview

Terra Hooks is an experimental wrapper over the Terra.js API.

The goal is to provide seamless integration out of the box between React apps
and real-time data from the Terra blockchain.

Terra Hooks is _headless_; that is, its only responsibility is providing
re-usable logic. It's up to the developer to decide how the client handles and
renders the resultant data. However, Terra Hooks is designed to work with its
constituent UI library—Terra Components
(coming soon).

## Installation

```shell
  yarn add @react-terra/hooks @terra-money/terra.js 
  @terra-money/wallet-provider rxjs
```

Follow the instructions from https://github.com/terra-money/wallet-provider 
to wrap your app in the wallet provider:

```jsx
import {
  NetworkInfo,
  WalletProvider,
  WalletStatus,
  getChainOptions,
} from '@terra-money/wallet-provider';
import React from 'react';
import ReactDOM from 'react-dom';

// getChainOptions(): Promise<{ defaultNetwork, walletConnectChainIds }>
getChainOptions().then((chainOptions) => {
  ReactDOM.render(
    <WalletProvider {...chainOptions}>
      <YOUR_APP />
    </WalletProvider>,
    document.getElementById('root'),
  );
});
```

## Example

```jsx
  import { useLiveBalances } from '@terra-hooks/use-live-balances';
```

## Benefits

- Declarative API with minimal surface area
- World-class UX is the first priority
- Conservation of resources is next (observables are lazily invoked)
- All functionality can be easily consumed by dApps—even if developers have no
  knowledge of RxJS

## Design Principles

Terra hooks relies heavily on RxJS. In this way, it follows best practices for
integrating React with RxJS (of which there aren't many resources) [1][2].

The basic idea is that there are "two worlds": the React world (i.e. the _UI
layer_) and the observable world (i.e. the _services layer_).

The React world consists of typical React components. They are light on logic
and do little more than subscribe to a data stream or communicate events back to
the observable world.

The observable world is where RxJS is used to handle complex async logic. This
logic exists as data streams composed of network requests to the Terra
blockchain & events from the browser. The `observable-hooks` library is used to
combine these worlds together.

We can use the example of rendering a user's wallet with stablecoin balances to
bring everything together. Ostensibly, this may seem like a straightforward
task. However:

- Currently, the Terra API doesn't appear to adequately support websockets.
- This leads to poor UX by default as the latest balance changes aren't
  reflected live.
- The only solution is to constantly poll the Terra endpoint for the latest
  data.
- But this creates a new issue of being wasteful with resources.
- Trying to solve all these issues within `useEffect` would lead to a huge mess,
  etc...

Here's how Terra Hooks solves it:

1. Once the user initialises their wallet, create an observable which polls the
   Terra blockchain every 6 seconds.
2. Ensure that any work done after the data has been fetched is _lazy_. That is,
   do not update any local state if the data fetched from the latest network
   request is identical to the previous request.
3. Additionally minimise resource usage by stopping polling if the browser
   window is hidden (and re-commence polling if the browser comes back into
   view).
4. Make this observable multi-case so any React component can subscribe to it
   and listen for balance state changes.

# References

[1]. https://observable-hooks.js.org/

[2]
. https://betterprogramming.pub/reactive-programming-with-react-and-rxjs-88d2789e408a

[3]
. https://redux.js.org/style-guide/style-guide/#do-not-put-non-serializable-values-in-state-or-actions

---
_Source: https://npm.io/package/@react-terra/hooks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._