Server

Silgi gives you two ways to run your API: serve() for a quick Node.js server, and handler() for any runtime that supports the Fetch API (Bun, Deno, Cloudflare Workers, etc.).

serve()

The simplest way to get a server running. One call, and you have an HTTP server with automatic port selection, optional API docs, and WebSocket support:

import { silgi } from 'silgi'
import { z } from 'zod'

const s = silgi({
  context: (req) => ({ db: getDB() }),
})

const appRouter = s.router({
  health: s.$resolve(() => ({ status: 'ok' })),
})

s.serve(appRouter, {
  port: 3000,
})

Run it with npx tsx src/server.ts and you'll see:

Silgi server running at http://127.0.0.1:3000

All options

s.serve(appRouter, {
  port: 3000, // auto-finds next available if busy
  hostname: '0.0.0.0', // bind to all interfaces
  scalar: true, // API docs at /reference
  ws: true, // WebSocket RPC on the same port
  http2: {
    // HTTP/2 with TLS
    cert: './certs/cert.pem',
    key: './certs/key.pem',
  },
})

Automatic port selection

If your requested port is already in use, serve() finds the next available one in the 3000-3100 range. You never need to handle EADDRINUSE yourself.

handler()

For runtimes other than Node.js, or when you want to plug Silgi into an existing server, use handler(). It returns a standard Fetch API function: (Request) => Promise<Response>.

const handle = s.handler(appRouter)
// handle is: (request: Request) => Promise<Response>

This works everywhere the Web Fetch API exists:

const handle = s.handler(appRouter)

Bun.serve({
port: 3000,
fetch: handle,
})

const handle = s.handler(appRouter)

Deno.serve({ port: 3000 }, handle)

const handle = s.handler(appRouter)

export default {
fetch: handle,
}

Content negotiation

Both serve() and handler() inspect the Accept header and respond in the format the client prefers:

The server also checks Content-Type on incoming POST requests to decode the body correctly. No configuration needed on the server side — it all happens automatically.

Scalar API docs

Silgi can generate an OpenAPI 3.1.0 spec from your router and serve an interactive API reference powered by Scalar:

s.serve(appRouter, {
  port: 3000,
  scalar: true,
})

This gives you two extra routes:

• /reference — interactive API documentation UI
• /openapi.json — the raw OpenAPI specification

The spec is generated once at startup, so there is no per-request cost.

Customizing the docs

Pass an options object instead of true:

s.serve(appRouter, {
  scalar: {
    title: 'My API',
    description: 'Built with Silgi',
    version: '2.0.0',
    servers: [{ url: 'https://api.example.com' }],
    contact: { email: '[email protected]' },
    security: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
  },
})

Scalar UI source

By default, the Scalar UI JavaScript is loaded from a CDN. You can change this with the cdn option:

s.serve(appRouter, {
  scalar: {
    title: 'My API',
    cdn: 'local', // serve from node_modules (offline)
  },
})

Adding metadata to procedures

The generated docs pull information from your procedure definitions. Add route metadata to make the docs more useful:

const listUsers = k
  .$input(z.object({ limit: z.number().optional() }))
  .$route({
    summary: 'List all users',
    description: 'Returns a paginated list of users, ordered by creation date.',
    tags: ['users'],
  })
  .$resolve(({ input, ctx }) => ctx.db.users.findMany({ take: input.limit }))

The route field accepts:

Caching

Add a cache option to route to set Cache-Control headers on query responses. This enables HTTP-level caching by browsers, CDNs, and reverse proxies.

// Shorthand: cache for 60 seconds
const listUsers = s.$route({ cache: 60 }).$resolve(({ ctx }) => ctx.db.users.findMany())

// Full control: custom Cache-Control value
const getConfig = s.$route({ cache: 'public, max-age=300, stale-while-revalidate=60' }).$resolve(() => loadConfig())

The cache header is compiled once at startup and added to every response for that procedure — zero per-request overhead.

HTTP/2

For production deployments that benefit from multiplexing and header compression, pass TLS certificates:

s.serve(appRouter, {
  port: 443,
  http2: {
    cert: './certs/cert.pem',
    key: './certs/key.pem',
  },
})

Output:

Silgi server running at https://127.0.0.1:443
  HTTP/2 enabled (with HTTP/1.1 fallback)

HTTP/2 requires TLS. Older clients that don't support HTTP/2 automatically fall back to HTTP/1.1 on the same port.

WebSocket support

Enable bidirectional RPC alongside the HTTP server:

s.serve(appRouter, {
  port: 3000,
  ws: true,
})

Silgi server running at http://127.0.0.1:3000
  WebSocket RPC at ws://127.0.0.1:3000

HTTP and WebSocket share the same port. The server detects WebSocket upgrade requests and routes them accordingly. See the WebSocket protocol page for the message format and how to connect from the client.

Lifecycle hooks

Silgi fires hooks at key points during request processing. Register them in the hooks option when creating the instance:

const s = silgi({
  context: (req) => ({ db: getDB() }),
  hooks: {
    request: ({ path, input }) => {
      console.log(`--> ${path}`)
    },
    response: ({ path, output, durationMs }) => {
      console.log(`<-- ${path} (${durationMs.toFixed(1)}ms)`)
    },
    error: ({ path, error }) => {
      console.error(`ERR ${path}:`, error)
    },
    'serve:start': ({ url, port, hostname }) => {
      console.log(`Server ready at ${url}`)
    },
  },
})

You can also add or remove hooks after the instance is created:

// Add a hook
s.hook('error', ({ error }) => reportToSentry(error))

// Remove a hook
k.removeHook('error', myHookFn)

Raw Response and binary streaming

Procedures can return a Response or ReadableStream for full control over the HTTP response — useful for file downloads, PDF generation, image serving, and binary data.

Returning a Response

Return a standard Response object for complete control over status, headers, and body:

const downloadPdf = s.$input(z.object({ id: z.string() })).$resolve(async ({ input, ctx }) => {
  const pdf = await ctx.storage.getFile(input.id)
  return new Response(pdf, {
    headers: {
      'content-type': 'application/pdf',
      'content-disposition': `attachment; filename="${input.id}.pdf"`,
    },
  })
})

Returning a ReadableStream

Return a ReadableStream for binary streaming. Silgi sends it with application/octet-stream:

const exportCsv = s.$resolve(async ({ ctx }) => {
  return new ReadableStream({
    async start(controller) {
      controller.enqueue(new TextEncoder().encode('id,name\n'))
      for await (const user of ctx.db.users.cursor()) {
        controller.enqueue(new TextEncoder().encode(`${user.id},${user.name}\n`))
      }
      controller.close()
    },
  })
})

callable()

For server-side code where you need to call a procedure directly — without HTTP, serialization, or the client proxy. Useful in scripts, cron jobs, and seed files.

import { callable } from 'silgi'

const getUsers = k
  .$input(z.object({ limit: z.number().optional() }))
  .$resolve(({ input, ctx }) => ctx.db.users.findMany({ take: input.limit }))

const getUsersFn = callable(getUsers, {
  context: () => ({ db: getDB() }),
})

// Direct call — compiled pipeline, no HTTP
const users = await getUsersFn({ limit: 10 })

The compiled pipeline (guards, wraps, validation) runs exactly as it would through serve() or handler(). The only difference is there's no network involved.

What's next?

• Client — connect to your server from the browser or another service
• Middleware — guards and wraps that run inside your request pipeline
• Fastify integration — mount Silgi inside an existing Fastify app
• Plugins — add CORS, logging, rate limiting, and tracing
• Protocols — learn about JSON, MessagePack, devalue, and WebSocket