igniter-client-usage

Igniter.js Client Usage Guide

This rule provides comprehensive guidance on using the Igniter.js Client, which offers universal type-safe API communication across server and client environments with advanced features like real-time updates, caching, and React hooks integration.

1. Universal Client Architecture

1.1 Environment-Aware Client

The Igniter.js client automatically adapts to different execution environments:

// Generated client file: src/igniter.client.ts
export const api = createIgniterClient<AppRouterType>({
  baseURL: process.env.NEXT_PUBLIC_IGNITER_API_URL || 'http://localhost:3000',
  basePATH: process.env.NEXT_PUBLIC_IGNITER_API_BASE_PATH || '/api/v1',
  router: () => {
    if (typeof window === 'undefined') {
      // Server-side: Direct router access (zero HTTP overhead)
      return require('./igniter.router').AppRouter
    }
    // Client-side: HTTP-based client with hooks
    return require('./igniter.schema').AppRouterSchema
  },
})

1.2 Execution Environments

Server-Side Execution (RSC, API Routes, Middleware):

• Direct function calls via router.caller
• Zero HTTP overhead
• Full access to server context
• Synchronous execution model

Client-Side Execution (Browser, Client Components):

• HTTP requests via fetch API
• React hooks for state management
• Built-in caching and revalidation
• Real-time subscriptions via SSE

2. Server-Side Usage Patterns

2.1 React Server Components (RSC)

// app/users/page.tsx
import { api } from '@/igniter.client'

export default async function UsersPage() {
  // Direct function call - no HTTP request
  const users = await api.users.list.query()

  return (
    <div>
      <h1>Users</h1>
      {users.data.map(user => (
        <div key={user.id}>{user.name}</div>
      ))}
    </div>
  )
}

2.2 API Routes

// app/api/sync/route.ts
import { api } from '@/igniter.client'

export async function POST() {
  try {
    // Direct server-to-server calls
    const users = await api.users.list.query()
    const posts = await api.posts.list.query()

    // Perform sync logic
    return Response.json({ success: true })
  } catch (error) {
    return Response.json({ error: error.message }, { status: 500 })
  }
}