@teliagen/react

React hooks and components for Teliagen applications.

Overview

@teliagen/react provides React integration for Teliagen applications:

• TeliagenProvider – Context provider for configuration
• useTeliagenAction – Hook for mutations (POST actions)
• useTeliagenQuery – Hook for queries (GET-like actions)
• React Query Integration – Built on @tanstack/react-query

Installation

npm install @teliagen/react @teliagen/client @tanstack/react-query
# or
pnpm add @teliagen/react @teliagen/client @tanstack/react-query

Quick Start

Setup Provider

// main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { TeliagenProvider } from '@teliagen/react';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <TeliagenProvider config={{ baseUrl: 'http://localhost:3000/api' }}>
    <App />
  </TeliagenProvider>
);

Use Hooks

import { useTeliagenAction, useTeliagenQuery } from '@teliagen/react';

// Query (for fetching data)
function UserList() {
  const { data, isLoading, error, refetch } = useTeliagenQuery<{}, User[]>(
    'listUsers',
    {},
    {}
  );

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

  return (
    <ul>
      {data?.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

// Mutation (for creating/updating data)
function CreateUserForm() {
  const { execute, isLoading, isSuccess, data, error } = useTeliagenAction<
    CreateUserInput,
    User
  >('createUser');

  const handleSubmit = (formData: CreateUserInput) => {
    execute(formData);
  };

  return (
    <form onSubmit={e => {
      e.preventDefault();
      handleSubmit({ email: '[email protected]', name: 'Test' });
    }}>
      {/* form fields */}
      <button disabled={isLoading}>
        {isLoading ? 'Creating...' : 'Create User'}
      </button>
      {isSuccess && <p>User created: {data?.name}</p>}
      {error && <p>Error: {error.message}</p>}
    </form>
  );
}

API Reference

TeliagenProvider

interface TeliagenClientConfig {
  baseUrl: string;
  token?: string;
  headers?: Record<string, string>;
}

interface TeliagenProviderProps {
  config: TeliagenClientConfig;
  children: React.ReactNode;
  queryClient?: QueryClient;  // Custom React Query client
}

<TeliagenProvider config={{ baseUrl: '/api' }}>
  {children}
</TeliagenProvider>

useTeliagenAction

For mutations (create, update, delete operations):

function useTeliagenAction<TInput, TOutput>(
  actionName: string,
  options?: {
    server?: string;
    module?: string;
    provider?: string;
  },
  defaultInput?: TInput
): {
  execute: (input: TInput) => void;
  executeAsync: (input: TInput) => Promise<TOutput>;
  data: TOutput | undefined;
  response: TOutput | undefined;
  isLoading: boolean;
  isSuccess: boolean;
  isError: boolean;
  error: Error | null;
  reset: () => void;
};

useTeliagenQuery

For queries (read operations):

function useTeliagenQuery<TInput, TOutput>(
  actionName: string,
  options: {
    server?: string;
    module?: string;
    provider?: string;
  },
  input: TInput
): {
  data: TOutput | undefined;
  response: TOutput | undefined;
  isLoading: boolean;
  isFetching: boolean;
  isSuccess: boolean;
  isError: boolean;
  error: Error | null;
  refetch: () => void;
};

useTeliagen

Access the transport directly:

import { useTeliagen } from '@teliagen/react';

function MyComponent() {
  const { transport, config } = useTeliagen();
  
  const handleAction = async () => {
    const result = await transport.execute('myAction', { data: 'value' });
  };
}

Usage Patterns

Form with Action

import { useTeliagenAction } from '@teliagen/react';
import { useState } from 'react';

interface LoginInput {
  email: string;
  password: string;
}

interface LoginOutput {
  user: User;
  token: string;
}

function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  
  const login = useTeliagenAction<LoginInput, LoginOutput>('login');

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    
    try {
      const result = await login.executeAsync({ email, password });
      localStorage.setItem('token', result.token);
      // Redirect...
    } catch (error) {
      // Error is also available in login.error
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="email"
        value={email}
        onChange={e => setEmail(e.target.value)}
        placeholder="Email"
      />
      <input
        type="password"
        value={password}
        onChange={e => setPassword(e.target.value)}
        placeholder="Password"
      />
      <button disabled={login.isLoading}>
        {login.isLoading ? 'Logging in...' : 'Login'}
      </button>
      {login.error && <p className="error">{login.error.message}</p>}
    </form>
  );
}

Data Table with Query

import { useTeliagenQuery } from '@teliagen/react';

interface ListUsersInput {
  page: number;
  limit: number;
}

interface ListUsersOutput {
  users: User[];
  total: number;
}

function UserTable() {
  const [page, setPage] = useState(1);
  
  const { data, isLoading, refetch } = useTeliagenQuery<
    ListUsersInput,
    ListUsersOutput
  >(
    'listUsers',
    { module: 'users' },
    { page, limit: 10 }
  );

  return (
    <div>
      <button onClick={() => refetch()}>Refresh</button>
      
      {isLoading ? (
        <p>Loading...</p>
      ) : (
        <table>
          <thead>
            <tr>
              <th>Name</th>
              <th>Email</th>
            </tr>
          </thead>
          <tbody>
            {data?.users.map(user => (
              <tr key={user.id}>
                <td>{user.name}</td>
                <td>{user.email}</td>
              </tr>
            ))}
          </tbody>
        </table>
      )}
      
      <div>
        Total: {data?.total}
        <button onClick={() => setPage(p => p - 1)} disabled={page === 1}>
          Previous
        </button>
        <button onClick={() => setPage(p => p + 1)}>
          Next
        </button>
      </div>
    </div>
  );
}

Cross-Service Call

function PaymentButton({ orderId }: { orderId: string }) {
  const processPayment = useTeliagenAction<PaymentInput, PaymentResult>(
    'processPayment',
    { server: 'payments' }  // Call payments service
  );

  return (
    <button
      onClick={() => processPayment.execute({ orderId })}
      disabled={processPayment.isLoading}
    >
      {processPayment.isLoading ? 'Processing...' : 'Pay Now'}
    </button>
  );
}

Custom Query Client

import { QueryClient } from '@tanstack/react-query';
import { TeliagenProvider } from '@teliagen/react';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000,  // 5 minutes
      retry: 3
    }
  }
});

function App() {
  return (
    <TeliagenProvider 
      config={{ baseUrl: '/api' }}
      queryClient={queryClient}
    >
      {/* ... */}
    </TeliagenProvider>
  );
}

With Generated Types

Use @teliagen/vite-plugin to generate typed hooks:

// Generated: .teliagen-client/main/hooks/useLogin.ts
import { useLogin } from '.teliagen-client/main';

function LoginPage() {
  const login = useLogin();
  
  // login.execute() is fully typed!
  login.execute({ email: '[email protected]', password: 'secret' });
}

Requirements

• React >= 18.0.0
• @tanstack/react-query >= 5.0.0

Related Packages

• @teliagen/client – Core HTTP transport
• @teliagen/vite-plugin – Vite plugin for code generation

Documentation

For full documentation, visit docs.teliagen.org.

License

Apache-2.0