Gear React-hooks
Hooks allow functional components to have access to programs running on Gear networks and significantly simplify the development of front-end applications.
For example, this article demonstrates the creation of a React application that connects to an NFT smart contract running on the blockchain.
Installation
npm install @gear-js/react-hooks
or
yarn add @gear-js/react-hooks
Getting started
Simple as it is, here's a quick example:
import { useReadFullState } from '@gear-js/react-hooks';
import { useMetadata } from './use-metadata'
import meta from 'assets/meta/meta.txt';
function State() {
const programId = '0x01';
const { metadata } = useMetadata(meta);
const { state } = useReadFullState(programId, meta);
return <div>{JSON.stringify(state)}</div>;
}
export { State };
Cookbook
In order for these hooks to work, the application must be wrapped in the appropriate Providers. As it is presented in the example. If you use create-gear-app
, then all the necessary environment has already been provided.
useApi
useApi
provides access to the Gear API connected to the selected RPC-node.
import { useApi } from '@gear-js/react-hooks';
const { api, isApiReady } = useApi();
useAccount
useAccount
provides interaction with Polkadot-js
extension API, allows to manage accounts from it (for example to sign transactions).
import { useAccount } from '@gear-js/react-hooks';
const { account, isAccountReady } = useAccount();
useAlert
useAlert
shows any alert in the application context.
import { useAlert } from '@gear-js/react-hooks';
const alert = useAlert();
// type?: 'info' | 'error' | 'loading' | 'success';
alert.success('success message')
useMetadata
This hook is auxiliary and it is not pre-installed in the react-hook library. useMetadata
allows converting the program's metadata (.txt
file) into the required format.
import { useEffect, useState } from 'react';
import {
getProgramMetadata,
ProgramMetadata
} from '@gear-js/api';
import { Buffer } from 'buffer';
export const useMetadata = (source: RequestInfo | URL) => {
const [data, setData] = useState<ProgramMetadata>();
useEffect(() => {
fetch(source)
.then((res) => res.text())
.then((raw) => getProgramMetadata(`0x${raw}`))
.then((meta) => setData(meta));
}, [source]);
return { metadata: data };
};
useWasmMetadata
This hook is auxiliary and it is not pre-installed in the react-hook library. useWasmMetadata
allows getting Buffer array from the program meta.wasm
. Buffer is required always when using custom functions to query specific parts of the program State.
import { useEffect, useState } from 'react';
import { Buffer } from 'buffer';
export const useWasmMetadata = (source: RequestInfo | URL) => {
const [data, setData] = useState<Buffer>();
useEffect(() => {
if (source) {
fetch(source)
.then((response) => response.arrayBuffer())
.then((array) => Buffer.from(array))
.then((buffer) => setData(buffer))
.catch(({ message }: Error) => console.error(`Fetch error: ${message}`));
}
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [source]);
return { buffer: data };
};