Server API Reference

The server module provides low-level registration functions used internally by the Telaio builder. You may call these directly when composing a Fastify application manually without the builder.

registerPlugins(server, pluginOptions, options)

Registers the set of optional Fastify plugins. Each plugin is guarded by a dynamic import(): if the peer dependency is not installed, the plugin is silently skipped.

import { registerPlugins } from 'telaio/server';

await registerPlugins(server, pluginOptions, {
  logger,
  baseDir: '/app',
  skipAutoload: false,
});

Signature

async function registerPlugins(
  server: FastifyInstance,
  pluginOptions: PluginOptions,
  options: {
    logger: Logger;
    baseDir: string;
    skipAutoload?: boolean;
  }
): Promise<void>

PluginOptions

Pass true to enable a plugin with all defaults, or an object to override specific fields. All keys are optional.

Plugins are registered in fixed order regardless of how they appear in the options object:

SSE -> Cookie -> WebSocket -> Compress -> CORS -> Helmet -> Multipart -> Autoload

CorsOptions

HelmetOptions

CookieOptions

CompressOptions

MultipartOptions

WebsocketOptions

AutoloadOptions

registerAutoload(server, pluginOptions, options)

Registers only the autoload plugin. Used internally when autoload needs to run after other setup has completed.

async function registerAutoload(
  server: FastifyInstance,
  pluginOptions: PluginOptions,
  options: {
    logger: Logger;
    baseDir: string;
  }
): Promise<void>

registerHooks(server, options)

Registers Fastify lifecycle hooks: request timing, auth session decoration, temp file management, and onReady/onClose callbacks.

import { registerHooks } from 'telaio/server';

await registerHooks(server, {
  logger,
  tempFiles: true,
  onReady: async () => {
    logger.info('Server ready');
  },
  onClose: async () => {
    await pool.end();
  },
});

Signature

async function registerHooks(
  server: FastifyInstance,
  options: {
    logger: Logger;
    tempFiles?: boolean;
    onReady?: () => Promise<void>;
    onClose?: () => Promise<void>;
  }
): Promise<void>

Options

Request decorators

registerHooks adds these decorators to every Fastify request. Auth decorators are added by buildAuthPlugin when an auth adapter is registered.

All temp files registered via req.addTempFile or req.getTempFile are deleted automatically after the response is sent, including on error paths.

registerSwagger(server, options)

Registers OpenAPI 3.1 spec generation via @fastify/swagger.

import { registerSwagger } from 'telaio/server';

await registerSwagger(server, {
  info: {
    title: 'My API',
    version: '1.0.0',
    description: 'REST API for the My App platform',
  },
});

Signature

async function registerSwagger(
  server: FastifyInstance,
  options: SwaggerOptions
): Promise<void>

SwaggerOptions

Additional standard OpenAPI fields can be passed alongside info and are forwarded to @fastify/swagger.

Schema $id values become $ref component names in the generated spec. A schema registered with $id: 'User' appears as #/components/schemas/User in every route that references it via AutoRef.

registerScalar(server, options?)

Mounts the Scalar interactive API reference UI. Requires registerSwagger to be called first.

import { registerScalar } from 'telaio/server';

registerScalar(server, {
  // Passthrough options for @scalar/fastify-api-reference
});

Signature

function registerScalar(
  server: FastifyInstance,
  options?: ScalarOptions
): void

URLs

ScalarOptions are passed through to @scalar/fastify-api-reference. Any valid Scalar configuration option can be provided.

registerSchemas and registerBuiltinSchemas

These functions are exported from telaio/schema, not telaio/server, but are part of the server setup pipeline.

See the Schema API Reference for full documentation on registerSchemas(fastify, schemasDir) and registerBuiltinSchemas(fastify).