React Quickstart

Get real-time Solana data streaming in your React app in 5 minutes.

What You’ll Build

A React app that displays live data from a Solana program using Hyperstack’s real-time streaming.

Prerequisites

• Node.js 18+
• A Hyperstack account (sign up here)
• An existing Hyperstack spec deployed (or use a public demo)

---

Step 1: Install the SDK

npm install hyperstack-react zustand react

Peer dependencies: react ^18.0.0, zustand ^4.0.0

---

Step 2: Set Up the Provider

Wrap your app with HyperstackProvider to enable WebSocket connections:

src/main.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import { HyperstackProvider } from 'hyperstack-react';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <HyperstackProvider
      websocketUrl="wss://your-spec.stack.hypertek.app"
      autoConnect={true}
    >
      <App />
    </HyperstackProvider>
  </React.StrictMode>
);

Replace your-spec with your deployed spec name, or use ws://localhost:8080 for local development.

---

Step 3: Define Your Stack

Create a stack definition that matches your spec’s entities:

src/stack.ts

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

// Define types matching your spec entities
interface Token {
  mint: string;
  name?: string;
  symbol?: string;
  price?: number;
  totalTrades?: number;
}

// Define the stack
export const TokenStack = defineStack({
  name: 'my-tokens',

  views: {
    tokens: {
      // List view: all entities as an array
      list: createListView<Token>('Token/list'),
      // State view: single entity by key
      state: createStateView<Token>('Token/state'),
    },
  },

  helpers: {
    formatPrice: (value: number) => `${value.toFixed(6)} SOL`,
  }
});

View path format: {EntityName}/{mode} where mode is list, state, or kv.

---

Step 4: Use Your Stack in Components

src/App.tsx

import { useHyperstack } from 'hyperstack-react';
import { TokenStack } from './stack';

function TokenList() {
  const stack = useHyperstack(TokenStack);

  // Subscribe to the token list - updates in real-time
  const { data: tokens, isLoading, error } = stack.views.tokens.list.use();

  if (isLoading) return <div>Connecting...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h1>Live Tokens ({tokens?.length || 0})</h1>
      {tokens?.map((token) => (
        <div key={token.mint}>
          <strong>{token.name || 'Unknown'}</strong> ({token.symbol})
          {token.price && <span> - {stack.helpers.formatPrice(token.price)}</span>}
        </div>
      ))}
    </div>
  );
}

function TokenDetail({ mint }: { mint: string }) {
  const stack = useHyperstack(TokenStack);

  // Subscribe to a single token by key
  const { data: token } = stack.views.tokens.state.use({ key: mint });

  if (!token) return <div>Loading token...</div>;

  return (
    <div>
      <h2>{token.name}</h2>
      <p>Total trades: {token.totalTrades}</p>
    </div>
  );
}

export default function App() {
  return <TokenList />;
}

---

Step 5: Run Your App

npm run dev

Your app now receives real-time updates whenever the on-chain data changes. No polling, no manual refreshes.

---

What’s Happening Under the Hood

1. HyperstackProvider establishes a WebSocket connection to your deployed spec
2. useHyperstack gives you access to your stack’s views and helpers
3. views.*.use() creates a subscription and returns reactive data
4. When on-chain data changes, Hyperstack pushes updates through the WebSocket
5. Your React components re-render automatically with the new data

---

Next Steps

• Creating Specs - Create custom data streams
• Stack API Reference - Full API documentation
• CLI Commands - Deploy and manage specs

---

Common Patterns

Transform Data on Receive

const TokenStack = defineStack({
  name: 'tokens',
  views: {
    tokens: {
      list: createListView<Token>('Token/list', {
        transform: (raw) => ({
          ...raw,
          price: raw.virtual_sol_reserves / raw.virtual_token_reserves,
        })
      }),
    },
  },
});

Filter List Results

const { data: recentTokens } = stack.views.tokens.list.use({
  where: { created_at: { gte: Date.now() - 86400000 } },
  limit: 10,
});

Handle Connection State

import { useConnectionState } from 'hyperstack-react';

function ConnectionStatus() {
  const state = useConnectionState();
  // state: 'disconnected' | 'connecting' | 'connected' | 'error' | 'reconnecting'
  return <div>Status: {state}</div>;
}

---

Troubleshooting

Issue	Solution
”WebSocket connection failed”	Check your websocketUrl is correct and the spec is deployed
Data not updating	Verify the view path matches your spec entity name
TypeScript errors	Ensure your interface matches the spec’s data shape