@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.

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 {
  NetworkGatewaysProvider,
  FastestPingRoutingStrategy,
} from '@ar.io/wayfinder-core'
import { ARIO } from '@ar.io/sdk'

function App() {
  return (
    <WayfinderProvider
      gatewaysProvider={new LocalStorageGatewaysProvider({
        gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() })
        ttlSeconds: 3600 * 4, // 4 hours
      })},
    >
      <YourApp />
    </WayfinderProvider>
  )
}

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.