# Config Reference

The complete CoframeConfig object — every field the install script can set

The `CoframeConfig` object is passed to the SDK via the `config` CFQ command
emitted by the install script. The SDK blocks at startup until this command
arrives, so every field listed here affects SDK behaviour from the moment
initialisation begins.


For a task-oriented guide and interactive install-script builder, see
[SDK Options](../docs/sdk-options.html). For details on the `config`
command itself and the other CFQ commands, see
[CFQ Commands](../docs/cfq-commands.html).

## Fields

Field | 
Type | 
Default | 
Description | 





`projectId` | 
`string` (required) | 
— | 
Coframe project/page identifier. Used to fetch project data from the edge and to tag the events the SDK sends. | 



`trackingOnly` | 
`boolean | undefined` | 
`undefined` (falsy) | 
When true, SDK only sends tracking events without activating variant modifications. | 



`enableAntiFlickering` **(unused)** | 
`boolean | undefined` | 
`—` | 
Declared on the config type but referenced nowhere in the SDK — it has no effect. Anti-flicker is applied by the install script, not this flag. See [Anti-Flicker](../docs/anti-flicker.html). | 



`waitForHydration` | 
`boolean | undefined` | 
`undefined` (falsy) | 
When true, SDK blocks variant selection until `{ pageHydrated: true }` arrives. Essential for SSR / React hydration workflows. | 



`waitForCookiesEnabled` | 
`boolean | undefined` | 
`undefined` (falsy) | 
When true, delays cookie writes and event sending until `{ cookiesEnabled: true }` is pushed. | 



`waitForFeatureFlag` | 
`boolean | undefined` | 
`undefined` (falsy) | 
When true, SDK waits for `{ featureFlagSet: boolean }`. A value of `false` causes a graceful exit (page revealed, no variants applied). | 



`waitForUserToken` | 
`boolean | undefined` | 
`undefined` (falsy) | 
When true, SDK waits for `{ setUserToken: string }` and skips its own cookie-based UUID generation. | 



`batchSize` | 
`number | undefined` | 
`32` | 
Controls how many events are batched per flush. | 



`startTime` | 
`number | undefined` | 
`undefined` | 
Client-side timestamp (ms since epoch) when the integration snippet was injected. Used to calculate `Coframe.status.elapsedFromInstallation` for performance monitoring. | 



`timeoutMs` | 
`number | undefined` | 
`5000` when omitted (capped at `TIMEOUT_MAX_MS = 5000`); the generated install script sets `1000` | 
Maximum milliseconds to wait for feature-flag, user-token, or hydration signals before graceful exit. The install script reuses this value for the [anti-flicker](../docs/anti-flicker.html) reveal, which is why it ships `1000`. | 



`timeoutBehavior` | 
`'exclude' | undefined` | 
`undefined` | 
The only defined value is `'exclude'`. Declared in the config type but not read by the current SDK; reserved for a future release. | 



`currentUrl` | 
`string | undefined` | 
— | 
The current page URL, forwarded to the edge as part of the JSON-encoded `config` query parameter so the edge worker can filter experiments and audiences by URL. | 



`userContext` | 
`Record<string, unknown> | undefined` | 
— | 
Opaque key/value context from the customer. Forwarded to the edge, where each top-level key is prefixed with `x-ctx-` and merged into the personalization headers (edge headers win on collision). Dropped silently if serialised JSON exceeds 4096 bytes. | 



`nonce` | 
`string | undefined` | 
— | 
CSP nonce applied to script elements that the SDK injects dynamically into the page. Required on sites with a strict `Content-Security-Policy: script-src 'nonce-...'` header. | 








`userContext`
`userContext` accepts an opaque `Record<string, unknown>` from the customer.
When the edge worker receives the config, each top-level key is prefixed with
`x-ctx-` (the constant `USER_CONTEXT_KEY_PREFIX`) and the resulting map is
merged with the edge-computed `PersonalizationHeaders`; edge headers win on key
collision. Values are stringified before merging (numbers and booleans become
strings; objects become JSON). If the JSON serialisation of `userContext`
exceeds 4096 bytes (`MAX_USER_CONTEXT_JSON_BYTES`), the entire field is
silently dropped and no `x-ctx-*` headers are forwarded.


Sources: `CONFIG.userContext`; `EDGE.user-context-headers`.


`timeoutBehavior`
`timeoutBehavior` accepts the string `'exclude'` or `undefined`. The field is
declared in the `CoframeConfig` type but is not read by the current SDK; it is
reserved for a future release and setting it has no effect today.


Source: `CONFIG.timeoutBehavior`.


`batchSize`
`batchSize` controls how many events are accumulated before a flush. The SDK
applies the value at initialisation as
`Coframe.batchSize = config.batchSize || 32`, so omitting the field or setting
it to a falsy value results in a batch size of `32`.


Source: `CONFIG.batchSize`.



See also:
[SDK Options](../docs/sdk-options.html) — task-oriented guide and
interactive install-script builder.
[CFQ Commands](../docs/cfq-commands.html) — the `config` command and
all other CFQ commands.