Configuration

Application options

const backend = bunderstack({
  schema,
  env,
  database: { adapter: libsql(), migrations: './migrations' },
  access,
  auth,
  authResolver,
  session,
  storage,
  messaging,
  jobs: (j) => j.define({}),
  api,
  middleware: [instrumentation],
  background: { autoStart: true },
  rateLimit: { windowMs: 60_000, max: 100 },
  idempotency: { ttlMs: 86_400_000 },
  realtime: { bufferSize: 1_000, resumeSeconds: 300, redis },
  openapi: true,
})

const app = await backend.start()

schema and database.adapter are required. All validation slots accept Standard Schema. api takes your oRPC router — an object built from bases you declared with defineApi, or a callback receiving the framework builder. middleware applies oRPC middleware to every procedure in the graph, generated ones included; see Middleware. openapi serves the optional projection at /api/openapi.json. auth takes better-auth options directly, or a builder ({ db, env }) => BetterAuthConfig when database hooks need the app's own connection — see Auth.

Realtime transport

bufferSize and resumeSeconds configure Publisher retention. Heartbeats and exponential reconnect belong to the client transport and require no application setting.

When a standalone worker uses the memory publisher, app.runWorker() rejects startup unless allowProcessLocalRealtime: true is explicit. This prevents silently publishing events that cannot reach another process.

Database adapters

The adapter dialect must match the Drizzle schema. Import only the adapter you use so optional drivers stay outside the application dependency graph.

Messaging and storage adapters

messaging is a named record of channels. A channel without credentials captures to the message journal instead of sending; see Messaging.

import { resend } from 'bunderstack'
import { smtp } from 'bunderstack/email-smtp'

messaging: {
  email: resend({ apiKey: env.RESEND_API_KEY, from: 'My app <[email protected]>' }),
  ops: smtp({ url: env.SMTP_URL, from: '[email protected]' }),
}

Storage may use a local directory or S3-compatible infrastructure. Buckets carry their own upload, access, and image-transform rules; see Storage.

Declaration and lifecycle

await app.close() stops background work and closes application-owned database and Publisher resources. app.status, app.signal, and app.backgroundRunning expose lifecycle state.

bunderstack() is synchronous and side-effect-free. Deployment tooling imports the exported backend and calls backend.inspect({ env }), which resolves the declaration without opening database or Redis connections. backend.start({ env }) owns production runtime resources; backend.test() creates an isolated, lexically owned test fixture.

For test suites, declare reusable defaults and setup with backend.test.configure({ env, database, logs, setup }). A call to the returned factory may override its defaults; env and database are deep-merged. The value returned from setup is exposed as fixture.context, and fixture.defer(cleanup) attaches additional resources to the fixture lifecycle.

Common environment variables