📝 [DOCS] Add guide for client integration with Torii

[jimenezz22]

📝 Description

Create practical documentation showing how to consume Torii data from a React
client using GraphQL queries and custom hooks, based on the Dojo Game
Starter implementation.

📚 Context

Developers need to understand how to query Torii from their frontend
applications with real, working examples.

✅ Tasks

Client Integration Documentation

(pages/deployments/torii/client-integration.md)

• Prerequisites

  • Torii indexer running with your deployed world
  • React application with Starknet React hooks
  • Torii endpoint URL configured

• Configuration Setup

  // dojoConfig.js
  export const dojoConfig = {
    toriiUrl: process.env.VITE_TORII_URL || "http://localhost:8080",
    // other config...
  };

• GraphQL Query Structure

  • Explain query format for fetching models
  • Show how model names are generated (e.g., fullStarterReactPlayerModels)
  • Example query structure:
    query GetPlayer($playerOwner: ContractAddress!) {
    fullStarterReactPlayerModels(where: { owner: $playerOwner }) {
    edges {
    node {
    owner
    experience
    health
    coins
    }
    }
    }
    }

• Creating a Custom Hook

  • Break down the hook structure and explain each part:

// 1. Import dependencies
import { useEffect, useState } from "react";
import { useAccount } from "@starknet-react/core";

// 2. Define the GraphQL endpoint
const TORII_URL = dojoConfig.toriiUrl + "/graphql";

// 3. Create fetch function
const fetchPlayerData = async (playerOwner) => {
const response = await fetch(TORII_URL, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
query: PLAYER_QUERY,
variables: { playerOwner }
})
});

const result = await response.json();
return result.data?.fullStarterReactPlayerModels?.edges[0]?.node;

};

// 4. Build the hook
export const usePlayer = () => {
const [player, setPlayer] = useState(null);
const [isLoading, setIsLoading] = useState(true);
const { account } = useAccount();

// Fetch logic here...

return { player, isLoading, error, refetch };

};

• Data Type Conversion
  • Explain why hex values need conversion
  • Helper function for hex to number:
    const hexToNumber = (hexValue) => {
    if (typeof hexValue === 'string' && hexValue.startsWith('0x')) {
    return parseInt(hexValue, 16);
    }
    return hexValue;
    };
• Common Patterns
  • Auto-refetch on account change
  • Error handling
  • Loading states
  • Manual refetch functionality
  • Address padding with Starknet utilities
• Query Variations
  • Fetching multiple models
  • Using filters and pagination
  • Sorting results
    query GetTopPlayers {
    fullStarterReactPlayerModels(
    first: 10,
    orderBy: "experience",
    orderDirection: "desc"
    ) {
    edges {
    node {
    owner
    experience
    }
    }
    }
    }
• Best Practices
  • Cache query results
  • Handle network errors gracefully
  • Use loading states
  • Implement retry logic for failed requests
  • Use address padding for consistent queries
• Environment Variables

.env

VITE_TORII_URL=http://localhost:8080
VITE_WORLD_ADDRESS=0x123...

• Complete Example Reference
  • Link to full implementation in Dojo Game Starter
  • Explain how to adapt the example for different models

📋 Acceptance Criteria

• Complete working example of a custom hook
• Clear explanation of each part
• Common query patterns documented
• Error handling examples
• Best practices for production
• Reference to real implementation

🎯 Expected Outcome

Developers should be able to:

1. Create custom hooks to fetch Torii data
2. Handle hex value conversions
3. Implement proper error handling
4. Understand the complete data flow

💡 Additional Notes

• Keep examples practical and reusable
• Explain the "why" behind each pattern
• Reference the actual implementation from Dojo Game Starter
• Focus on common use cases

📚 References

• https://github.com/AkatsukiLabs/Dojo-Game-Starter/blob/main/client/src/dojo
  /hooks/usePlayer.tsx
• https://github.com/AkatsukiLabs/Dojo-Game-Starter

Contribution Guidelines

• Please ensure you read and follow the contribution guidelines in the project's README file

[respp]

Hello @jimenezz22 Can I take this issue?

I'm a developer with a solid background in Web3, working across both front-end and back-end. I've contributed to projects in ecosystems like StarkNet, Stellar, Optimism, and Worldcoin, with a focus on building scalable, secure, and efficient blockchain applications.

Currently, I'm a Fellow at OnlyDust and a maintainer at PayStell and StellarRent, where I lead the development of smart contracts and decentralized infrastructure.