Menu

Documentation

Menu
Guides

React SDK

Beautiful React components for displaying gamification data with pure rendering architecture.

Installation

Install the React package and SDK (for server-side use):

npm install @ludustack/react @ludustack/sdk

Getting Started

The React SDK provides pure rendering components that display pre-fetched data. All data fetching happens server-side:

// Server Component with Server-Side Data Fetching
import { LudustackSDK } from '@ludustack/sdk';
import { PlayerCard } from '@ludustack/react';

export default async function PlayerPage() {
  // Server-side SDK usage
  const sdk = new LudustackSDK({
    apiKey: process.env.LUDUSTACK_API_KEY!,
    gameId: process.env.LUDUSTACK_GAME_ID!,
  });

  // Fetch data server-side
  const player = await sdk.player.getById('player-123');
  const game = await sdk.game.getById('game-456');

  // Pure rendering component
  return (
    <div>
      <h1>Player Profile</h1>
      <PlayerCard 
        player={player} 
        game={game}
        onViewProfileClick={(player) => {
          // Handle navigation
          console.log('View profile for', player.displayName);
        }}
      />
    </div>
  );
}

Available Components

All components are designed for pure rendering - they only display data passed as props:

  • <PlayerCard /> - Comprehensive player information display
  • <PlayerBadge /> - Compact player badge
  • <LeaderboardTable /> - Ranked player table
  • <PointsDisplay /> - Points with animations

Server-Side Data Fetching

Next.js Server Components

Fetch data in server components and pass to React components:

// app/leaderboard/page.tsx
import { LudustackSDK } from '@ludustack/sdk';
import { LeaderboardTable } from '@ludustack/react';

export default async function LeaderboardPage() {
  const sdk = new LudustackSDK({
    apiKey: process.env.LUDUSTACK_API_KEY!,
    gameId: 'your-game-id',
  });

  // Server-side data fetching
  const players = await sdk.player.list({ 
    gameId: 'your-game-id',
    sortBy: 'points',
    order: 'desc',
    limit: 10
  });

  return (
    <div>
      <h1>Leaderboard</h1>
      <LeaderboardTable 
        players={players}
        title="Top 10 Players"
      />
    </div>
  );
}

Server Actions for Operations

Use server actions for operations like giving points:

// app/actions/gamification.ts
"use server";

import { LudustackSDK } from '@ludustack/sdk';
import { revalidatePath } from 'next/cache';

export async function givePointsAction(
  playerId: string,
  points: number,
  action: string
) {
  const sdk = new LudustackSDK({
    apiKey: process.env.LUDUSTACK_API_KEY!,
    gameId: process.env.LUDUSTACK_GAME_ID!,
  });

  const result = await sdk.operations.givePoints(playerId, points, action);
  
  // Revalidate pages that show player data
  revalidatePath('/player/[id]', 'page');
  
  return result;
}

// app/components/player-actions.tsx
"use client";

import { givePointsAction } from '../actions/gamification';

export function PlayerActions({ playerId }: { playerId: string }) {
  const handleGivePoints = async () => {
    await givePointsAction(playerId, 100, 'manual_award');
  };

  return (
    <button onClick={handleGivePoints}>
      Give 100 Points
    </button>
  );
}

API Routes

Create API endpoints for data fetching:

// app/api/players/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { LudustackSDK } from '@ludustack/sdk';

export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  const sdk = new LudustackSDK({
    apiKey: process.env.LUDUSTACK_API_KEY!,
    gameId: process.env.LUDUSTACK_GAME_ID!,
  });

  try {
    const player = await sdk.player.getById(params.id);
    return NextResponse.json(player);
  } catch (error) {
    return NextResponse.json(
      { error: 'Player not found' },
      { status: 404 }
    );
  }
}

Pure Rendering Examples

Display Player Information

Components only render data passed as props:

import { PlayerCard, PlayerBadge, PointsDisplay } from '@ludustack/react';

function PlayerProfile({ player, game }) {
  return (
    <div>
      {/* All data comes from props */}
      <PlayerCard
        player={player}
        game={game}
        onViewProfileClick={(player) => {
          // Handle navigation
          router.push(`/players/${player.id}`);
        }}
      />
      
      <PlayerBadge 
        player={player}
        onClick={() => console.log('Badge clicked')}
      />
      
      <PointsDisplay
        points={player.points}
        animateChanges={true}
      />
    </div>
  );
}

Display Leaderboard

Show rankings with server-fetched data:

import { LeaderboardTable } from '@ludustack/react';

function GameLeaderboard({ players, currentPlayerId }) {
  return (
    <div>
      <h2>Weekly Tournament</h2>
      <LeaderboardTable
        players={players}
        title="Top Performers"
        highlightedPlayerId={currentPlayerId}
      />
    </div>
  );
}

Benefits

  • ⚡ No Request Waterfalls: Server-side data fetching
  • 🚀 Faster Initial Loads: Server-rendered with data
  • 📦 Smaller Bundles: No SDK code in client bundle
  • 💰 Better Caching: Server-side data can be cached
  • 🔍 SEO Friendly: Data available at render time

For server-side data fetching, check out our JavaScript SDK documentation.

For full API reference, visit the API Reference section.