Skip to content

Commit b89b2d5

Browse files
nikerzetic-aflabsnikerzetic-aflabs
authored
feat(docs): add new guides for React developers and update sidebar links (#1155)
2 parents d5d35f9 + 11dcfb3 commit b89b2d5

File tree

6 files changed

+385
-6
lines changed

6 files changed

+385
-6
lines changed

‎docs/authors.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,9 @@ nikerzetic:
3939
title: Dev Rel
4040
url: https://github.com/nikerzetic-aflabs
4141
image_url: https://github.com/nikerzetic-aflabs.png
42+
43+
fassko:
44+
name: Kristaps Grinbergs
45+
title: Dev Rel
46+
url: https://github.com/fassko
47+
image_url: https://github.com/fassko.png

‎docs/network/guides/flare-for-react-developers.mdx‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
---
2+
slug: flare-for-react-developers
3+
title: Flare for React Devs
4+
authors: [fassko]
5+
description: Learn how to interact with Flare using React and Wagmi.
6+
tags: [react, wagmi, javascript, quickstart]
7+
keywords:
8+
[
9+
react,
10+
wagmi,
11+
viem,
12+
javascript,
13+
typescript,
14+
quickstart,
15+
smart-contract,
16+
flare-network,
17+
]
18+
sidebar_position: 3
19+
---
20+
21+
This guide is for React developers who want to interact with Flare using [Wagmi](https://wagmi.sh/) and the [`@flarenetwork/flare-wagmi-periphery-package`](https://www.npmjs.com/package/@flarenetwork/flare-wagmi-periphery-package).
22+
23+
The package provides two ways to read and write Flare contracts:
24+
25+
- **Generic hooks:** use Wagmi's [`useReadContract`](https://wagmi.sh/react/hooks/useReadContract) with typed ABIs imported from the Flare Wagmi Periphery package.
26+
- **Contract-specific hooks:** use auto-generated hooks like `useReadIFlareContractRegistry` that already know the ABI.
27+
28+
In this guide, you will set up a React project, configure Wagmi for Flare, and query the [`WNat`](/network/solidity-reference/IWNat) contract address from the [`FlareContractRegistry`](/network/solidity-reference/IFlareContractRegistry) using both approaches.
29+
30+
## Prerequisites
31+
32+
- [Node.js](https://nodejs.org/) (v18 or later)
33+
- `npm` package manager
34+
35+
## Setting up the project
36+
37+
Scaffold a new React + TypeScript project using [Vite](https://vite.dev/):
38+
39+
```bash
40+
npm create vite@latest my-flare-app -- --template react-ts
41+
cd my-flare-app
42+
```
43+
44+
Install the Wagmi, Viem, TanStack Query, and the [Flare Wagmi periphery package](https://www.npmjs.com/package/@flarenetwork/flare-wagmi-periphery-package):
45+
46+
```bash
47+
npm install wagmi viem @tanstack/react-query @flarenetwork/flare-wagmi-periphery-package
48+
```
49+
50+
## Configure Wagmi for Flare
51+
52+
Create a `wagmi.config.ts` file in the `src` directory to define the Wagmi configuration with Flare networks:
53+
54+
```typescript title="wagmi.config.ts"
55+
import { createConfig, http } from "wagmi";
56+
import { flare, flareTestnet } from "viem/chains";
57+
import { injected } from "wagmi/connectors";
58+
59+
export const config = createConfig({
60+
chains: [flare, flareTestnet],
61+
connectors: [injected()],
62+
transports: {
63+
[flare.id]: http(),
64+
[flareTestnet.id]: http(),
65+
},
66+
});
67+
```
68+
69+
Wrap your application with the required providers in `src/main.tsx`:
70+
71+
```typescript title="src/main.tsx"
72+
import { StrictMode } from "react";
73+
import { createRoot } from "react-dom/client";
74+
import { WagmiProvider } from "wagmi";
75+
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
76+
import { config } from "./wagmi.config.ts";
77+
import App from "./App.tsx";
78+
79+
const queryClient = new QueryClient();
80+
81+
createRoot(document.getElementById("root")!).render(
82+
<StrictMode>
83+
<WagmiProvider config={config}>
84+
<QueryClientProvider client={queryClient}>
85+
<App />
86+
</QueryClientProvider>
87+
</WagmiProvider>
88+
</StrictMode>,
89+
);
90+
```
91+
92+
## Query contract data
93+
94+
The example below queries the [`FlareContractRegistry`](/network/solidity-reference/IFlareContractRegistry) to look up the [`WNat`](/network/solidity-reference/IWNat) contract address.
95+
96+
It demonstrates both approaches to query the contract data:
97+
98+
- **Generic hooks:** use Wagmi's [`useReadContract`](https://wagmi.sh/react/hooks/useReadContract) with typed ABIs imported from the Flare Wagmi Periphery package.
99+
- **Contract-specific hooks:** use auto-generated hooks like `useReadIFlareContractRegistry` that already know the ABI.
100+
101+
```typescript title="src/WNatQuery.tsx"
102+
import { useReadContract } from "wagmi";
103+
import {
104+
useReadIFlareContractRegistry,
105+
iFlareContractRegistryAbi,
106+
} from "@flarenetwork/flare-wagmi-periphery-package/contracts/flare";
107+
108+
// The Flare Contract Registry address
109+
const FLARE_CONTRACTS_REGISTRY =
110+
"0xaD67FE66660Fb8dFE9d6b1b4240d8650e30F6019" as const;
111+
112+
export function WNatQuery() {
113+
// Generic useReadContract with ABI
114+
const {
115+
data: wNatAddressGeneric,
116+
isLoading: isLoadingGeneric,
117+
error: errorGeneric,
118+
} = useReadContract({
119+
address: FLARE_CONTRACTS_REGISTRY,
120+
abi: iFlareContractRegistryAbi,
121+
functionName: "getContractAddressByName",
122+
args: ["WNat"],
123+
});
124+
125+
// Contract-specific hook
126+
const {
127+
data: wNatAddressSpecific,
128+
isLoading: isLoadingSpecific,
129+
error: errorSpecific,
130+
} = useReadIFlareContractRegistry({
131+
address: FLARE_CONTRACTS_REGISTRY,
132+
functionName: "getContractAddressByName",
133+
args: ["WNat"],
134+
});
135+
136+
return (
137+
<div>
138+
<h1>WNat Contract Query</h1>
139+
140+
<h2>Generic Hook with ABI</h2>
141+
<p>
142+
Uses Wagmi's generic <code>useReadContract</code> hook with{" "}
143+
<code>iFlareContractRegistryAbi</code> imported from the package.
144+
</p>
145+
{isLoadingGeneric && <p>Loading...</p>}
146+
{errorGeneric && <p>Error: {errorGeneric.message}</p>}
147+
{wNatAddressGeneric && <p>{wNatAddressGeneric as string}</p>}
148+
149+
<h2>Contract-Specific Hook</h2>
150+
<p>
151+
Uses <code>useReadIFlareContractRegistry</code>, a pre-typed hook
152+
generated for the contract. No ABI import needed.
153+
</p>
154+
{isLoadingSpecific && <p>Loading...</p>}
155+
{errorSpecific && <p>Error: {errorSpecific.message}</p>}
156+
{wNatAddressSpecific && <p>{wNatAddressSpecific as string}</p>}
157+
</div>
158+
);
159+
}
160+
```
161+
162+
## Run the app
163+
164+
Update `src/App.tsx` to render the `WNatQuery` component:
165+
166+
```typescript title="src/App.tsx"
167+
import "./App.css";
168+
import { WNatQuery } from "./WNatQuery";
169+
170+
function App() {
171+
return (
172+
<div>
173+
<WNatQuery />
174+
</div>
175+
);
176+
}
177+
178+
export default App;
179+
```
180+
181+
Start the development server:
182+
183+
```bash
184+
npm run dev
185+
```
186+
187+
Open the URL shown in the terminal.
188+
189+
The app will query the [`FlareContractRegistry`](/network/solidity-reference/IFlareContractRegistry) and display the [`WNat`](/network/solidity-reference/IWNat) contract address using both approaches.
190+
191+
### Generic hooks
192+
193+
The generic approach uses the [`useReadContract`](https://wagmi.sh/react/hooks/useReadContract) hook from Wagmi.
194+
You import the typed ABI (`iFlareContractRegistryAbi`) from the package and pass it as the `abi` prop.
195+
This gives you complete type safety for `functionName` and `args`.
196+
197+
```typescript
198+
import { useReadContract } from "wagmi";
199+
import { iFlareContractRegistryAbi } from "@flarenetwork/flare-wagmi-periphery-package/contracts/flare";
200+
201+
const { data } = useReadContract({
202+
address: FLARE_CONTRACTS_REGISTRY,
203+
abi: iFlareContractRegistryAbi,
204+
functionName: "getContractAddressByName",
205+
args: ["WNat"],
206+
});
207+
```
208+
209+
### Contract-specific hooks
210+
211+
The package also exports auto-generated hooks named after each contract.
212+
Instead of passing an `abi` prop, you call the contract-specific hook directly.
213+
The hook already knows the ABI, so you only need to provide `address`, `functionName`, and `args`.
214+
215+
```typescript
216+
import { useReadIFlareContractRegistry } from "@flarenetwork/flare-wagmi-periphery-package/contracts/flare";
217+
218+
const { data } = useReadIFlareContractRegistry({
219+
address: FLARE_CONTRACTS_REGISTRY,
220+
functionName: "getContractAddressByName",
221+
args: ["WNat"],
222+
});
223+
```
224+
225+
## Choosing an approach
226+
227+
| | Generic hooks | Contract-specific hooks |
228+
| --------------- | ---------------------------------------------------------------- | ------------------------------------------------- |
229+
| **Import** | `useReadContract` from Wagmi + ABI from package | `useReadIFlareContractRegistry` etc. from package |
230+
| **ABI prop** | Required — pass the imported ABI | Not needed — baked into the hook |
231+
| **Type safety** | Full, via ABI generic | Full, via generated hook signature |
232+
| **Best for** | Mixing contracts in one component, using ABIs with viem directly | Concise code when working with a single contract |
233+
234+
## Available exports
235+
236+
The package provides you with typed ABIs and contract-specific hooks for all Flare periphery contracts, organized by network.
237+
238+
To work with [Flare Time Series Oracle (FTSO)](/ftso/overview) contracts, you can import them using both approaches in the following ways:
239+
240+
```typescript
241+
// Generic: import ABIs for use with useReadContract / useWriteContract
242+
import { iFtsoAbi } from "@flarenetwork/flare-wagmi-periphery-package/contracts/<network>";
243+
244+
// Contract-specific: import auto-generated hooks
245+
import {
246+
useReadIFtso,
247+
useWriteIiFtso,
248+
} from "@flarenetwork/flare-wagmi-periphery-package/contracts/<network>";
249+
```
250+
251+
Where `<network>` is one of:
252+
253+
- `flare`
254+
- `songbird`
255+
- `coston`
256+
- `coston2`.
257+
258+
:::tip[What's next?]
259+
260+
- Explore the [Network Configuration](/network/overview#configuration) for RPC endpoints and chain details.
261+
- Learn how to use the [Hardhat & Foundry Starter Kit](/network/guides/hardhat-foundry-starter-kit) to deploy and interact with Flare contracts.
262+
263+
:::

‎docs/network/guides/overview.mdx‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: Network Guides
3+
description: Learn how to interact with Flare onchain and offchain.
4+
keywords:
5+
[flare-network, guides, quickstart, solidity, javascript, python, rust, go]
6+
---
7+
8+
import DocCardList from "@theme/DocCardList";
9+
10+
Explore guides for building on Flare.
11+
Whether you are just getting started or looking for advanced topics, these guides cover everything from language-specific quickstarts to on-chain interactions and protocol features.
12+
13+
## Getting Started
14+
15+
Get started building on Flare with your preferred language or framework.
16+
17+
<DocCardList
18+
items={[
19+
{
20+
type: "link",
21+
label: "Hardhat & Foundry Starter Kit",
22+
href: "/network/guides/hardhat-foundry-starter-kit",
23+
docId: "network/guides/hardhat-foundry-starter-kit",
24+
},
25+
{
26+
type: "link",
27+
label: "Flare for JavaScript Devs",
28+
href: "/network/guides/flare-for-javascript-developers",
29+
docId: "network/guides/flare-for-javascript-developers",
30+
},
31+
{
32+
type: "link",
33+
label: "Flare for React Devs",
34+
href: "/network/guides/flare-for-react-developers",
35+
docId: "network/guides/flare-for-react-developers",
36+
},
37+
{
38+
type: "link",
39+
label: "Flare for Python Devs",
40+
href: "/network/guides/flare-for-python-developers",
41+
docId: "network/guides/flare-for-python-developers",
42+
},
43+
{
44+
type: "link",
45+
label: "Flare for Rust Devs",
46+
href: "/network/guides/flare-for-rust-developers",
47+
docId: "network/guides/flare-for-rust-developers",
48+
},
49+
{
50+
type: "link",
51+
label: "Flare for Go Devs",
52+
href: "/network/guides/flare-for-go-developers",
53+
docId: "network/guides/flare-for-go-developers",
54+
},
55+
]}
56+
/>
57+
58+
## Onchain Guides
59+
60+
Learn how to interact with Flare smart contracts and onchain features.
61+
62+
<DocCardList
63+
items={[
64+
{
65+
type: "link",
66+
label: "Retrieving Contract Addresses",
67+
href: "/network/guides/flare-contracts-registry",
68+
docId: "network/guides/flare-contracts-registry",
69+
},
70+
{
71+
type: "link",
72+
label: "Secure Random Numbers",
73+
href: "/network/guides/secure-random-numbers",
74+
docId: "network/guides/secure-random-numbers",
75+
},
76+
{
77+
type: "link",
78+
label: "Wrapped Native Tokens",
79+
href: "/network/guides/wnat",
80+
docId: "network/guides/wnat",
81+
},
82+
]}
83+
/>
84+
85+
## Protocol Guides
86+
87+
Learn how to interact with Flare protocol features like FlareDrops, staking, and more.
88+
89+
<DocCardList
90+
items={[
91+
{
92+
type: "link",
93+
label: "Manage FlareDrops",
94+
href: "/network/guides/manage-flaredrops",
95+
docId: "network/guides/manage-flaredrops",
96+
},
97+
{
98+
type: "link",
99+
label: "Gasless USD₮0 Transfers",
100+
href: "/network/guides/gasless-usdt0-transfers",
101+
docId: "network/guides/gasless-usdt0-transfers",
102+
},
103+
{
104+
type: "link",
105+
label: "Using Flare Stake Tool",
106+
href: "/network/guides/using-flare-stake-tool",
107+
docId: "network/guides/using-flare-stake-tool",
108+
},
109+
]}
110+
/>

‎docs/tags.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@ flare-smart-accounts:
4444
label: flare-smart-accounts
4545
x402:
4646
label: x402
47+
react:
48+
label: react
49+
wagmi:
50+
label: wagmi
4751
security:
4852
label: security
4953
web2json:

0 commit comments

Comments
 (0)