🚧 This page needs work

Note: Needs updating to reflect the new Workbench UX component structure — review imports, component names, and any API changes in the TypeScript libraries

Introduction to the TypeScript libraries

Description

Explore TrustGraph TypeScript libraries for building web applications

Difficulty

Intermediate

Duration

30 min

You will need
  • Basic TypeScript/JavaScript familiarity
Goal

Understand the TrustGraph TypeScript libraries and choose the right one for your application.

Overview

TrustGraph provides three TypeScript/JavaScript libraries for different use cases:

Library Description Use Case
trustgraph-client Pure TypeScript WebSocket client Backend services, CLI tools, non-React applications
trustgraph-react-provider React Context provider wrapper Basic React integration with direct client access
trustgraph-react-state React hooks with Tanstack Query Full-featured React applications with state management

Choosing the right library:

  • Building a React app? → Use trustgraph-react-state for the best developer experience
  • Need React Context integration? → Use trustgraph-react-provider for simpler needs
  • Building without React? → Use trustgraph-client for Node.js, CLIs, or vanilla JavaScript

trustgraph-client

The core TypeScript client for TrustGraph, built on WebSockets with minimal dependencies.

Links:

Key features:

  • Pure TypeScript with full type safety
  • WebSocket-based for streaming and non-streaming operations
  • Minimal dependencies (only websocket and promises)
  • No React dependency - works anywhere JavaScript runs
  • Suitable for backend services, CLI tools, and non-UI applications

Installation:

npm install trustgraph-client

Basic usage:

import { TrustGraphClient } from 'trustgraph-client';

// Create client
const client = new TrustGraphClient({
  url: 'http://localhost:8088',
  flowId: 'default'
});

// Query using Graph RAG (streaming)
const stream = client.graphRag({
  query: 'What is the scientific name for cats?',
  user: 'trustgraph',
  collection: 'default',
  streaming: true
});

for await (const chunk of stream) {
  process.stdout.write(chunk);
}

The client can be used in:

  • Node.js backend services
  • Command-line tools
  • Build scripts and automation
  • Browser applications without React
  • Electron apps

trustgraph-react-provider

A React Context provider that makes the TrustGraph client available throughout your component tree.

Links:

Key features:

  • Wraps trustgraph-client with React Context
  • Provides direct access to the client instance
  • Minimal abstraction - you control client interactions
  • Good for simple React integrations

Installation:

npm install trustgraph-react-provider trustgraph-client

Basic usage:

import { TrustGraphProvider, useTrustGraph } from 'trustgraph-react-provider';

// Wrap your app with the provider
function App() {
  return (
    <TrustGraphProvider
      url="http://localhost:8088"
      flowId="default"
    >
      <YourComponents />
    </TrustGraphProvider>
  );
}

// Access the client in components
function QueryComponent() {
  const client = useTrustGraph();

  const handleQuery = async () => {
    const stream = client.graphRag({
      query: 'What is the scientific name for cats?',
      user: 'trustgraph',
      collection: 'default',
      streaming: true
    });

    for await (const chunk of stream) {
      // Handle streaming chunks
    }
  };

  return <button onClick={handleQuery}>Query</button>;
}

Use this when:

  • You want direct control over client interactions
  • You’re comfortable managing your own state
  • You have simple integration needs

trustgraph-react-state

The most React-friendly library, providing hooks built on Tanstack Query for automatic state management and caching.

Links:

Key features:

  • React hooks for all TrustGraph operations
  • Built on Tanstack Query (React Query)
  • Automatic state management (loading, error, success states)
  • Intelligent caching and request deduplication
  • Optimistic updates and background refetching
  • Best developer experience for React applications

Installation:

npm install trustgraph-react-state @tanstack/react-query

Basic usage:

import { TrustGraphProvider } from 'trustgraph-react-state';
import { useGraphRag } from 'trustgraph-react-state/hooks';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

// Create QueryClient
const queryClient = new QueryClient();

// Wrap your app with providers
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <TrustGraphProvider
        url="http://localhost:8088"
        flowId="default"
      >
        <YourComponents />
      </TrustGraphProvider>
    </QueryClientProvider>
  );
}

// Use hooks in components
function QueryComponent() {
  const { data, isLoading, error } = useGraphRag({
    query: 'What is the scientific name for cats?',
    user: 'trustgraph',
    collection: 'default'
  });

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

  return <div>{data}</div>;
}

Available hooks:

  • useGraphRag - Graph RAG queries
  • useDocumentRag - Document RAG queries
  • useAgent - Agent queries
  • useTextCompletion - LLM text completion
  • useTriplesQuery - Knowledge graph triple queries
  • And more…

Each hook provides:

  • data - Query results
  • isLoading - Loading state
  • error - Error state
  • refetch - Manual refetch function
  • Automatic caching and deduplication

Use this when:

  • Building a full React application
  • You want automatic state management
  • You need caching and performance optimization
  • You want the best developer experience

Next Steps