@ar.io/wayfinder-react

Overview

The @ar.io/wayfinder-react package provides React-specific components and hooks for integrating Wayfinder into React applications. It offers a provider pattern for configuration and convenient hooks for fetching data with built-in loading states and error handling.

Smart Defaults

Wayfinder React automatically configures optimal settings for web applications, including LocalStorageGatewaysProvider to avoid rate limits and performance optimizations in hooks to prevent unnecessary rerenders.

Installation

npm install @ar.io/wayfinder-react @ar.io/wayfinder-core
# or
yarn add @ar.io/wayfinder-react @ar.io/wayfinder-core

Quick Start

1. Add the Wayfinder Context Provider

import { WayfinderProvider } from '@ar.io/wayfinder-react'
import { ARIO } from '@ar.io/sdk'

function App() {
  return (
    <WayfinderProvider>
      <YourApp />
    </WayfinderProvider>
  )
}

Default Configuration

Wayfinder React automatically uses LocalStorageGatewaysProvider with NetworkGatewaysProvider to avoid rate limits and improve performance. You don't need to configure this manually unless you want custom settings.

2. Use Hooks in Your Components

import { useWayfinderRequest } from '@ar.io/wayfinder-react'

function MyComponent() {
  const request = useWayfinderRequest()

  const handleFetch = async () => {
    const response = await request('ar://transaction-id')
    const data = await response.text()
    console.log(data)
  }

  return <button onClick={handleFetch}>Fetch Data</button>
}

Advanced Configuration

import { WayfinderProvider } from '@ar.io/wayfinder-react'
import {
  NetworkGatewaysProvider,
  PreferredWithFallbackRoutingStrategy,
  FastestPingRoutingStrategy,
  HashVerificationStrategy,
  StaticGatewaysProvider,
} from '@ar.io/wayfinder-core'
import { ARIO } from '@ar.io/sdk'

function App() {
  return (
    <WayfinderProvider
      gatewaysProvider={new NetworkGatewaysProvider({ ario: ARIO.mainnet() })}
      routingSettings={{
        strategy: new PreferredWithFallbackRoutingStrategy({
          preferredGateway: 'https://my-gateway.com',
          fallbackStrategy: new FastestPingRoutingStrategy({ timeoutMs: 500 }),
        }),
        events: {
          onRoutingSucceeded: (event) =>
            console.log('Gateway selected:', event.selectedGateway),
          onRoutingFailed: (error) => console.error('Routing failed:', error),
        },
      }}
      verificationSettings={{
        enabled: true,
        strategy: new HashVerificationStrategy({
          trustedGateways: ['https://arweave.net'],
        }),
        strict: false,
        events: {
          onVerificationSucceeded: (event) =>
            console.log('Verified:', event.txId),
          onVerificationFailed: (error) =>
            console.error('Verification failed:', error),
        },
      }}
      telemetrySettings={{
        enabled: process.env.NODE_ENV === 'production',
        clientName: 'my-react-app',
        clientVersion: process.env.REACT_APP_VERSION || '1.0.0',
        sampleRate: 0.05,
        exporterUrl: process.env.REACT_APP_TELEMETRY_URL,
      }}
    >
      <YourApp />
    </WayfinderProvider>
  )
}

useWayfinder: Access the complete Wayfinder instance
useWayfinderRequest: Direct access to the request function
useWayfinderUrl: URL resolution with loading states

For more advanced configuration options, see the Core Documentation.