Client

The Silgi client gives you a fully typed proxy that mirrors your server's router structure. You call procedures like local functions, and TypeScript knows every input and output type.

Setup

Setting up the client takes two steps: create a link (the transport layer) and then create the client (the typed proxy).

import { createLink } from 'silgi/client/ofetch'

const link = createLink({
  url: 'http://localhost:3000',
})

import { createLink } from 'silgi/client/ofetch'

const link = createLink({ url: '/api' })
// Calls resolve to /api/users/list, /api/health, etc.

import { createClient } from 'silgi/client'
import { createLink } from 'silgi/client/ofetch'
import type { AppRouter } from './server' // export type AppRouter = typeof appRouter

const link = createLink({ url: 'http://localhost:3000' })
const client = createClient<AppRouter>(link)

// Router structure: { users: { list, create }, health }

const users = await client.users.list({ limit: 10 })
const newUser = await client.users.create({ name: 'Alice' })
const status = await client.health()

Type inference

To get the router type on the client side, export it from your server file:

// server.ts
export const appRouter = s.router({
  users: {
    list: listUsers,
    create: createUser,
  },
})
export type AppRouter = typeof appRouter

Then use it when creating the client:

import type { AppRouter } from './server'

const client = createClient<AppRouter>(link)

You can also use the InferClient utility type, which extracts the client type from any router:

import type { InferClient } from 'silgi'

type Client = InferClient<typeof appRouter>
// Client.users.list: (input: { limit?: number }) => Promise<User[]>
// Client.users.create: (input: { name: string }) => Promise<User>

Link options

The createLink function accepts these options:

Authentication headers

The most common use for dynamic headers is passing an auth token:

const link = createLink({
  url: 'http://localhost:3000',
  headers: () => ({
    Authorization: `Bearer ${getToken()}`,
  }),
})

The header function runs on every request, so it always picks up the latest token. This is important for scenarios like token refresh — when the token changes, the next request automatically uses the new one.

Retry and timeout

const link = createLink({
  url: 'http://localhost:3000',
  retry: 3, // retry up to 3 times on failure
  retryDelay: 1000, // wait 1 second between retries
  timeout: 10_000, // 10 second timeout per request
})

For exponential backoff, pass a function:

const link = createLink({
  url: 'http://localhost:3000',
  retry: 3,
  retryDelay: (ctx) => Math.pow(2, ctx.options?.retryCount ?? 0) * 500,
  // 500ms, 1000ms, 2000ms
})

Binary mode

Set binary: true to use MessagePack instead of JSON. Payloads are smaller and encoding/decoding is faster:

const link = createLink({
  url: 'http://localhost:3000',
  binary: true,
})

The client encodes the request body as MessagePack, sets the Content-Type and Accept headers to application/x-msgpack, and the server responds in MessagePack too.

See the MessagePack protocol page for more details on what types are supported.

Interceptors

The link supports ofetch interceptors for fine-grained control over the request lifecycle:

const link = createLink({
  url: 'http://localhost:3000',
  onRequest({ request, options }) {
    // Runs before every request is sent
    console.log('Sending:', request)
  },
  onResponse({ response }) {
    // Runs after every successful response
    console.log('Received:', response.status)
  },
  onRequestError({ error }) {
    // Runs when the request fails (network error, DNS failure, etc.)
    console.error('Request failed:', error)
  },
  onResponseError({ response }) {
    // Runs when the server responds with an error status
    console.error('Server error:', response.status)
  },
})

Interceptors are useful for:

• Logging in development
• Token refresh — intercept 401 responses, refresh the token, and retry
• Metrics — measure request timing and success rates

Call options

Each procedure call can receive a second argument with per-call options:

const controller = new AbortController()

const users = await client.users.list({ limit: 10 }, { signal: controller.signal })

// Cancel the request at any time
controller.abort()

Available per-call options:

Error handling

Server errors are reconstructed as SilgiError instances on the client. You can catch them with try/catch:

import { SilgiError } from 'silgi'

try {
  await client.users.delete({ id: 1 })
} catch (error) {
  if (error instanceof SilgiError) {
    console.log(error.code) // "FORBIDDEN"
    console.log(error.status) // 403
    console.log(error.data) // { reason: "Not the owner" }
  }
}

Or use the safe() wrapper to avoid try/catch entirely:

import { safe } from 'silgi/client'

const { error, data, isError, isSuccess } = await safe(client.users.delete({ id: 1 }))

if (isError) {
  console.log(error.code) // "FORBIDDEN"
} else {
  console.log(data) // the deleted user
}

See the Typed Errors page for the complete error handling guide, including the defined flag for distinguishing business errors from unexpected failures.

Server-side client

For SSR, server components, or testing — use createServerClient to get the same typed client interface without any network overhead:

import { createServerClient } from 'silgi/client/server'

const client = createServerClient(appRouter, {
  context: () => ({ db: getDB() }),
})

// Same API as the HTTP client — but runs in-process
const users = await client.users.list({ limit: 10 })
const user = await client.users.create({ name: 'Alice' })

The server client compiles the router once and reuses the compiled handlers. Every call runs the full pipeline (guards, wraps, validation) — the only thing skipped is HTTP serialization.

This is especially useful for:

• SSR data fetching — call procedures during server rendering without a network round-trip
• Testing — write integration tests against the real pipeline without starting a server
• Server-to-server — call procedures from background jobs, cron tasks, or other services running in the same process

DynamicLink

A DynamicLink lets you route requests to different links at runtime. The factory function receives the procedure path, input, and call options, and returns the link to use:

import { createClient, DynamicLink } from 'silgi/client'

const link = new DynamicLink((path, input, options) => {
  if (path[0] === 'admin') return adminLink
  return defaultLink
})

const client = createClient<AppRouter>(link)

This is useful when different parts of your API live on different servers, or when you want to swap between real and mock links based on environment.

mergeClients

Combine multiple Silgi clients into a single object. Each client can point to a different server — the merged result keeps full type safety:

import { mergeClients } from 'silgi/client'

const client = mergeClients({
  users: usersClient,
  billing: billingClient,
})

// client.users.list(...)   → hits the users service
// client.billing.charges() → hits the billing service

withInterceptors

Wrap any link with lifecycle hooks. Unlike ofetch interceptors (which are HTTP-level), these run at the Silgi procedure level and receive the procedure path and input:

import { withInterceptors } from 'silgi/client'

const link = withInterceptors(baseLink, {
  onRequest({ path, input }) {
    console.log(`-> ${path.join('/')}`)
  },
  onResponse({ path, durationMs }) {
    console.log(`<- ${path.join('/')} (${durationMs}ms)`)
  },
  onError({ path, error }) {
    reportToSentry(error)
  },
})

All three hooks are optional. onError fires on any thrown error — the error still propagates to the caller after the hook runs.

What's next?

• Typed Errors — handle server errors on the client with full type safety
• Protocols — JSON, MessagePack, and devalue encoding
• TanStack Query — generate queryOptions and mutationOptions from the client
• Server — the server-side setup that the client connects to