Builder Pattern

The builder pattern is Telaio's primary composition mechanism. Instead of a single monolithic config object, you chain method calls to opt into features one by one. Each call narrows the TypeScript types so the final TelaioApp only exposes what you actually configured.

Starting a builder

import { createApp } from 'telaio';

const builder = createApp({ config });

createApp(options?) returns an AppBuilder<DefaultFeatures, unknown, TConfig>. The three type parameters track everything that matters across the chain:

You never write these explicitly. They are inferred as you chain methods.

Builder methods

Each method returns a new AppBuilder with the updated type parameters. Nothing is constructed until you call .build().

Standard wiring example

import { createApp } from 'telaio';
import { registry } from './queues/registry/index.js';
import { adapter } from './auth/adapter.js';
import config from './config.js';

const app = await createApp({ config })
  .withDatabase()
  .withCache()
  .withQueues(registry)
  .withAuth(adapter)
  .withSwagger({ info: { title: 'My API', version: '1.0.0' } })
  .withApiDocs()
  .build();

// All of these are fully typed:
app.fastify   // FastifyInstance
app.config    // TConfig
app.pool      // pg.Pool
app.db        // Kysely<DB>
app.cache     // Redis wrapper
app.queue     // pg-boss producer
app.logger    // Pino logger

await app.start({ port: 3000 });

The TelaioApp shape

Calling .build() resolves to a TelaioApp<F, TSession, TConfig>. Some properties are always present; others are conditional on the feature flags baked into F.

Always present:

Conditional (only present when the matching feature flag is true):

Accessing a conditional property without calling the corresponding with*() method is a compile-time error. See Phantom Types for how this works.

Build assembly order

.build() performs a fixed 12-step assembly. The order is not arbitrary -- Fastify's plugin model requires that hooks registered by a plugin only fire for routes registered after it.

1. Create FastifyInstance
2. Set up database -- pg pool, Kysely instance, CITEXT type parser
3. Set up queue producer (pg-boss)
4. Set up cache (Redis or disabled stub)
5. Register user plugins (skipAutoload: true -- routes are deferred)
6. Register Swagger plugin (must precede route autoload so the onRoute hook captures every route)
7. Register auth plugin (after Swagger, before schemas)
8. Register built-in TypeBox schemas
9. Register user schemas from the schemas directory
10. Register Scalar API docs UI
11. Register autoload (routes) -- runs after Swagger so all routes appear in the spec
12. Register lifecycle hooks (skipped when .asEphemeral() is used)

The auth chicken-and-egg problem

Some auth libraries (such as better-auth) require a database connection during their own initialization, before you call .build(). This creates a circular dependency: you need pool to configure auth, but pool is normally created inside .build().

Telaio provides standalone factory functions that mirror what .build() would create internally. You can pass the pre-built instances back into the builder so the same connections are reused rather than duplicated.

import { createPool, createDatabase } from 'telaio/db';
import { createBetterAuth } from 'better-auth';
import { createBetterAuthAdapter } from 'telaio/auth/better-auth';
import { createApp } from 'telaio';
import config from './config.js';

// Step 1: create the pool and db independently
const pool = await createPool(config);
const db = await createDatabase<DB>(pool);

// Step 2: pass the pool into the auth library
const auth = createBetterAuth({
  database: { provider: 'pg', db: pool },
});
const adapter = createBetterAuthAdapter({ auth });

// Step 3: hand the pre-built instances to the builder
const app = await createApp({ config })
  .withDatabase({ pool, db })  // reuse -- no second connection opened
  .withAuth(adapter)
  .build();