# Configuration (/docs/reference/configuration)



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.

```ts title="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) [#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 [#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`:

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

## `logging` (optional) [#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`

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

## `execution` (optional) [#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) [#triggers-optional]

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

## `plugins` (optional) [#plugins-optional]

Array of plugin instances, initialised in order:

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

## `defaultCredentials` (optional) [#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.                              |

## `apiPath` (optional) [#apipath-optional]

The URL path where the Flowlib API is mounted (e.g. `'/api/flowlib'` or `'http://localhost:3000/flowlib'`). Read by `<Flowlib>` on the frontend to know where to send API requests.

## `frontendPath` (optional) [#frontendpath-optional]

The URL path where `<Flowlib>` is mounted in the frontend router (e.g. `'/flowlib'`). Used for internal navigation and the OAuth callback route (`<frontendPath>/oauth/callback`).

## `theme` (optional) [#theme-optional]

`'light' | 'dark' | 'system'` — default `'dark'`. Controls the editor color scheme. Read by `<Flowlib>` on the frontend.

## `logger` (optional) [#logger-optional]

Custom logger instance. Must implement `info`, `debug`, `warn`, `error` methods.

## Edge / serverless options (optional) [#edge--serverless-options-optional]

These matter only on cold-start-per-request runtimes (Cloudflare Workers, Vercel, etc.). Self-hosted long-running servers can ignore them.

| 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 [#full-example]

```ts title="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,
    },
  ],
});
```