Flowlib Docs

The configuration object is passed to createFlowlibRouter() (Express), FlowlibModule.forRoot() (NestJS), or createFlowlibHandler() (Next.js). It is also read directly by <Flowlib config={...} /> on the frontend for fields like apiPath, frontendPath, theme, and plugins. Use defineConfig() from @flowlib/core for type inference.

flowlib.config.ts

import { defineConfig } from '@flowlib/core';

export const flowlibConfig = defineConfig({
  database: { ... },
  apiPath: '/api/flowlib',   // backend mount path
  frontendPath: '/flowlib',  // where <Flowlib> is mounted in the frontend router
  theme: 'light',           // 'light' | 'dark' | 'system'
  logging: { ... },
  execution: { ... },
  triggers: { ... },
  plugins: [ ... ],
  defaultCredentials: [ ... ],
});

export default flowlibConfig;

`database` (required)

Field	Type	Default	Description
`connectionString`	`string`	—	Database URL. SQLite: `file:./dev.db`. PostgreSQL: `postgresql://user:pass@host:port/db`. MySQL: `mysql://user:pass@host:port/db`. Required for every driver except `d1`.
`type`	`'sqlite' \| 'postgresql' \| 'mysql'`	—	Database dialect.
`name`	`string`	—	Optional human-readable name.
`driver`	see below	auto-detected	Database driver.
`binding`	`D1Database`	—	Cloudflare D1 binding. Required (instead of `connectionString`) when `driver` is `d1`. Pass the `env.DB` your Worker received.

Supported drivers

Database	Drivers	Default
PostgreSQL	`postgres`, `pg`, `neon-serverless`	`postgres`
SQLite	`better-sqlite3`, `libsql`, `d1`	`better-sqlite3`
MySQL	`mysql2`	`mysql2`

d1 is a SQLite-dialect driver for Cloudflare Workers — pass a runtime binding instead of a connectionString:

database: {
  type: 'sqlite',
  driver: 'd1',
  binding: env.DB, // the D1Database from your Worker's env
},

`logging` (optional)

Field	Type	Default	Description
`level`	`'debug' \| 'info' \| 'warn' \| 'error' \| 'silent'`	`'silent'`	Global log level.
`scopes`	`Record<string, LogLevel>`	—	Per-scope overrides.

Available scopes: execution, validation, batch, database, node, graph, credentials, ai, template, renderer, flows, versions, http

logging: {
  level: 'info',
  scopes: {
    execution: 'debug',
    batch: 'silent',
    ai: 'debug',
  },
}

`execution` (optional)

Field	Type	Default	Description
`defaultTimeout`	`number`	`60000`	Node execution timeout (ms).
`maxConcurrentExecutions`	`number`	`10`	Maximum parallel flow runs.
`enableTracing`	`boolean`	`true`	Store node-level execution traces.
`flowTimeoutMs`	`number`	`600000`	Stale-run heartbeat threshold (10 min). A run is failed only if heartbeats stop, not on wall-clock.
`modelNodeTimeoutMs`	`number`	`300000`	Per-node timeout for `core.model` (5 min) unless the node sets its own `timeoutMs`.
`agentNodeTimeoutMs`	`number`	`900000`	Per-node timeout for the `core.agent` loop (15 min) unless the node sets its own `timeoutMs`.
`heartbeatIntervalMs`	`number`	`30000`	Heartbeat write interval during a run (ms).
`staleRunCheckIntervalMs`	`number`	`60000`	Stale-run detector poll interval (ms).
`sseHeartbeatIntervalMs`	`number`	`15000`	SSE keep-alive frame interval for the run event stream (ms). Lower it behind aggressive proxies.
`disableNativeEval`	`boolean`	`false`	Force-disable the `new Function` fast path in `DirectEvaluator` (edge-runtime hosts only).
`persistence`	`'per-node' \| 'per-run'`	`'per-node'`	Node-execution write strategy. `'per-run'` buffers in memory and flushes one blob on completion (~30× fewer writes) at the cost of in-flight node visibility.

`triggers` (optional)

Field	Type	Default	Description
`webhookBaseUrl`	`string`	—	Public URL prefix for webhook URLs.
`cronEnabled`	`boolean`	`true`	Enable/disable cron scheduler.

`plugins` (optional)

Array of plugin instances, initialised in order:

plugins: [
  auth({
    /* ... */
  }),
  rbac(),
  webhooks({ webhookBaseUrl: 'https://api.myapp.com/flowlib' }),
];

`defaultCredentials` (optional)

Array of credentials to seed on startup. Matched by name — existing credentials not overwritten.

Field	Type	Required	Description
`name`	`string`	Yes	Unique credential name.
`type`	`'llm' \| 'http-api' \| 'database'`	Yes	Credential category.
`provider`	`string`	For `llm`	Provider ID (`openai`, `anthropic`, `openrouter`).
`authType`	`string`	Yes	Auth method (`apiKey`, `oauth2`).
`config`	`Record<string, unknown>`	Yes	Provider-specific config.
`description`	`string`	No	Human-readable note.
`isShared`	`boolean`	No	Visible to all users.

Field	Type	Default	Description
`skipDatabaseInit`	`boolean`	`false`	Throw before connecting to the database — used by build steps. The Next.js adapter sets this automatically during a production build.
`skipStartupChecks`	`boolean`	`false`	Skip the per-startup connectivity probe and table/schema checks. Use only when the deploy pipeline already ran `generate` + `push`; saves ~4 DB round-trips per cold start.
`services`	`object`	—	Adapter overrides for cross-cutting infrastructure (`encryption`, `eventBus`, `chatSessionStore`, `cronScheduler`, `batchPoller`, `jobRunner`). Edge runtimes inject runtime-native implementations here.
`auth`	`object`	—	Authorization config for the RBAC layer (`customAuthorize` callback, etc.). Consumed by plugin `onAuthorize` hooks.

Full example

flowlib.config.ts

import { defineConfig } from '@flowlib/core';
import { auth } from '@flowlib/user-auth';
import { rbac } from '@flowlib/rbac';

export const flowlibConfig = defineConfig({
  database: {
    type: 'postgresql',
    connectionString: process.env.DATABASE_URL,
  },
  apiPath: '/api/flowlib',
  frontendPath: '/flowlib',
  theme: 'light',
  logging: {
    level: 'info',
    scopes: { execution: 'debug' },
  },
  execution: {
    defaultTimeout: 120000,
    maxConcurrentExecutions: 20,
    flowTimeoutMs: 600_000,
  },
  triggers: {
    webhookBaseUrl: process.env.WEBHOOK_BASE_URL,
    cronEnabled: true,
  },
  plugins: [
    auth({
      betterAuthOptions: { secret: process.env.BETTER_AUTH_SECRET },
      globalAdmins: [
        { email: process.env.ADMIN_EMAIL, pw: process.env.ADMIN_PASSWORD, name: 'Admin' },
      ],
    }),
    rbac(),
  ],
  defaultCredentials: [
    {
      name: 'OpenAI',
      type: 'llm',
      provider: 'openai',
      authType: 'apiKey',
      config: { apiKey: process.env.OPENAI_API_KEY },
      isShared: true,
    },
  ],
});

Configuration

`database` (required)

Supported drivers

`logging` (optional)

`execution` (optional)

`triggers` (optional)

`plugins` (optional)

`defaultCredentials` (optional)

`apiPath` (optional)

`frontendPath` (optional)

`theme` (optional)

`logger` (optional)

Edge / serverless options (optional)

Full example

On this page