Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hypertekorg/hyperstack/llms.txt

Use this file to discover all available pages before exploring further.

The React SDK provides hooks-based integration for React applications. Built on top of hyperstack-typescript, it offers seamless state management with Zustand and idiomatic React patterns.

​
Installation

npm install hyperstack-react

​
Requirements

  • React 18.0+ or React 19.0+
  • Zustand 4.0+ or 5.0+
  • A generated stack definition from the Hyperstack CLI
Not using React? Use hyperstack-typescript directly for Vue, Svelte, Node.js, or vanilla JavaScript.

​
Quick Start

​
Setup Provider

Wrap your application with HyperstackProvider: 
import { HyperstackProvider } from 'hyperstack-react';

function App() {
  return (
    <HyperstackProvider 
      config={{ 
        url: 'wss://mainnet.hyperstack.xyz',
        autoConnect: true 
      }}
    >
      <GameDashboard />
    </HyperstackProvider>
  );
}

​
Use Hooks in Components

import { useHyperstack, defineStack } from 'hyperstack-react';
import { MY_STACK } from './generated/my-stack';

const myStack = defineStack(MY_STACK);

function GameDashboard() {
  const stack = useHyperstack(myStack);
  
  // Subscribe to all games (returns T[])
  const games = stack.views.games.use();
  
  // Subscribe to a specific game (returns T | undefined)
  const game = stack.views.games.useOne('game-123');
  
  return (
    <div>
      <h1>Active Games: {games.length}</h1>
      {game && <GameDetails game={game} />}
    </div>
  );
}

​
API Reference

​
Providers

​
HyperstackProvider

Root provider for Hyperstack configuration. 
<HyperstackProvider config={{
  url: 'wss://mainnet.hyperstack.xyz',
  autoConnect: true,
  reconnect: true,
}}>
  {children}
</HyperstackProvider>
​
config
HyperstackConfig
required
Configuration options:
  • url: WebSocket server URL
  • autoConnect: Auto-connect on mount (default: true)
  • reconnect: Auto-reconnect on disconnect (default: true)

​
Hooks

​
useHyperstack

Main hook for accessing stack functionality. 
const stack = useHyperstack(myStack);
​
stack
Stack
Stack instance with typed view accessors.

​
useHyperstackContext

Access the runtime context directly. 
const { connectionState, connect, disconnect } = useHyperstackContext();
​
connectionState
ConnectionState
Current connection state: 'connected' | 'connecting' | 'disconnected' | 'error'
​
connect
() => Promise<void>
Manually connect to the server.
​
disconnect
() => Promise<void>
Disconnect from the server.

​
View Methods

Each view provides hooks for subscribing to data.

​
use()

Subscribe to view data. Returns different types based on view type: 
// List view - returns T[]
const games = stack.views.games.use();

// State view - returns T | undefined
const player = stack.views.player.use('player-id');

// Single item query - returns T | undefined
const topGame = stack.views.games.use({ take: 1 });
​
options
object
Query options:
  • take: 1 - Fetch only the first item (enables type narrowing to T | undefined)

​
useOne()

Convenience method for single item queries. 
// Equivalent to .use({ take: 1 })
const topGame = stack.views.games.useOne();

​
Examples

​
Real-time Game List

import { useHyperstack, defineStack } from 'hyperstack-react';
import { GAME_STACK } from './generated/game-stack';

const gameStack = defineStack(GAME_STACK);

function GameList() {
  const stack = useHyperstack(gameStack);
  const games = stack.views.games.use();
  
  return (
    <div>
      <h2>Active Games ({games.length})</h2>
      <ul>
        {games.map(game => (
          <li key={game.id}>
            {game.name} - {game.players.length} players
          </li>
        ))}
      </ul>
    </div>
  );
}

​
Live Leaderboard

function Leaderboard() {
  const stack = useHyperstack(gameStack);
  const players = stack.views.players.use();
  
  // Sort by score (descending)
  const sorted = [...players].sort((a, b) => b.score - a.score);
  
  return (
    <div>
      <h2>Top Players</h2>
      <ol>
        {sorted.slice(0, 10).map((player, index) => (
          <li key={player.id}>
            #{index + 1} {player.name} - {player.score} points
          </li>
        ))}
      </ol>
    </div>
  );
}

​
Single Item Query

function GameDetails({ gameId }: { gameId: string }) {
  const stack = useHyperstack(gameStack);
  const game = stack.views.games.use(gameId);
  
  if (!game) {
    return <div>Game not found</div>;
  }
  
  return (
    <div>
      <h2>{game.name}</h2>
      <p>Status: {game.status}</p>
      <p>Players: {game.players.length}</p>
    </div>
  );
}

​
Top Item with Type Safety

function FeaturedGame() {
  const stack = useHyperstack(gameStack);
  
  // Type is narrowed to Game | undefined
  const topGame = stack.views.games.useOne();
  
  if (!topGame) {
    return <div>No games available</div>;
  }
  
  return (
    <div>
      <h2>Featured: {topGame.name}</h2>
      <p>{topGame.description}</p>
    </div>
  );
}

​
Connection Status

import { useHyperstackContext } from 'hyperstack-react';

function ConnectionIndicator() {
  const { connectionState } = useHyperstackContext();
  
  const getStatus = () => {
    switch (connectionState) {
      case 'connected': return { color: 'green', text: 'Connected' };
      case 'connecting': return { color: 'yellow', text: 'Connecting...' };
      case 'disconnected': return { color: 'red', text: 'Disconnected' };
      case 'error': return { color: 'red', text: 'Connection Error' };
    }
  };
  
  const status = getStatus();
  
  return (
    <div style={{ color: status.color }}>
      ● {status.text}
    </div>
  );
}

​
Manual Connection Control

function ConnectionControl() {
  const { connectionState, connect, disconnect } = useHyperstackContext();
  
  return (
    <div>
      <p>Status: {connectionState}</p>
      {connectionState === 'disconnected' ? (
        <button onClick={connect}>Connect</button>
      ) : (
        <button onClick={disconnect}>Disconnect</button>
      )}
    </div>
  );
}

​
Advanced Usage

​
Custom Stack Definition

import { defineStack, createListView, createStateView } from 'hyperstack-react';

const myStack = defineStack({
  views: {
    games: createListView<Game>({ name: 'games' }),
    player: createStateView<Player>({ name: 'player' }),
  },
});

function MyApp() {
  const stack = useHyperstack(myStack);
  // Fully typed views
}

​
Filtering and Derived State

function ActiveGames() {
  const stack = useHyperstack(gameStack);
  const allGames = stack.views.games.use();
  
  // Derive filtered state
  const activeGames = allGames.filter(game => game.status === 'active');
  const completedGames = allGames.filter(game => game.status === 'completed');
  
  return (
    <div>
      <h3>Active: {activeGames.length}</h3>
      <h3>Completed: {completedGames.length}</h3>
    </div>
  );
}

​
Using with Core SDK

Access low-level streaming APIs: 
import { HyperStack } from 'hyperstack-react';
// or from 'hyperstack-typescript'

const hs = await HyperStack.connect('wss://mainnet.hyperstack.xyz', {
  stack: MY_STACK,
});

for await (const update of hs.views.games.list.watch()) {
  console.log('Update:', update);
}

​
State Management

The React SDK uses Zustand internally for state management. Each view maintains its own store:
  • List views store entities as Record<string, T>
  • State views store single entities as T | undefined
  • Derived views store computed values
Updates are batched and optimized to minimize re-renders.

​
Performance Tips

​
Memoize Derived Values

import { useMemo } from 'react';

function LeaderboardOptimized() {
  const stack = useHyperstack(gameStack);
  const players = stack.views.players.use();
  
  // Memoize sorted array
  const sorted = useMemo(
    () => [...players].sort((a, b) => b.score - a.score),
    [players]
  );
  
  return <div>{/* render sorted */}</div>;
}

​
Selective Subscriptions

// Subscribe to specific entity only
function PlayerCard({ playerId }: { playerId: string }) {
  const stack = useHyperstack(gameStack);
  const player = stack.views.players.use(playerId);
  
  // Only re-renders when this specific player updates
  return <div>{player?.name}</div>;
}

​
Next Steps

TypeScript SDK

Learn about the core TypeScript SDK

Examples

Browse example applications

Stack API

Understand Stack API concepts

CLI Reference

Generate SDKs with the CLI

Build docs developers (and LLMs) love

Get started for freeTalk to us