Rate limiting is applied per unique combination of flag key and evaluation context.

This behavior is built in and does not currently require configuration.

`flagsFallbackProvider` is a reliability feature that lets the SDK persist the latest successfully fetched raw flag definitions to fallback storage such as a local file, Redis, S3, GCS, or a custom backend.

Reflag servers remain the primary source of truth. On `initialize()`, the SDK always tries to fetch a live copy of the flag definitions first, and it continues refreshing those definitions from the Reflag servers over time.

If that initial live fetch fails, the SDK can call `flagsFallbackProvider.load()` and start with the last saved snapshot instead. This is mainly useful for cold starts in the exceedingly rare case that Reflag has an outage.

If Reflag becomes unavailable after the SDK has already initialized successfully, the SDK keeps using the last successfully fetched definitions it already has in memory. In other words, the fallback provider is mainly what helps future processes start, not what keeps an already running process alive.

After successfully fetching updated flag definitions, the SDK calls `flagsFallbackProvider.save()` to keep the stored snapshot up to date.

Typical reliability flow:

1. The SDK starts and tries to fetch live flag definitions from Reflag.

2. If that succeeds, those definitions are used immediately and the SDK continues operating normally.

3. After successfully fetching updated flag definitions, the SDK saves the latest snapshot through the fallback provider so a recent copy is available if needed later.

4. If a future process starts while Reflag is unavailable, it can load the last saved snapshot from the fallback provider and still initialize.

5. Once Reflag becomes available again, the SDK resumes using live data and refreshes the fallback snapshot.

Most deployments run multiple SDK processes, so more than one process may save identical flag definitions to the fallback storage at roughly the same time. This is expected and generally harmless for backends like a local file, Redis, S3, or GCS because the operation is cheap. In practice, this only becomes worth thinking about once you have many thousands of SDK processes writing to the same fallback storage.

You can access the built-in providers through the `fallbackProviders` namespace:

- `fallbackProviders.static(...)`

- `fallbackProviders.file(...)`

- `fallbackProviders.redis(...)`

- `fallbackProviders.s3(...)`

- `fallbackProviders.gcs(...)`

import { ReflagClient, fallbackProviders } from "@reflag/node-sdk";

const client = new ReflagClient({

secretKey: process.env.REFLAG_SECRET_KEY,

flagsFallbackProvider: fallbackProviders.file({

directory: ".reflag",

}),

});

await client.initialize();

The file provider stores one snapshot file per environment in the configured

`directory`.

If you just want a fixed fallback copy of simple enabled/disabled flags, you can provide a static map:

import { ReflagClient, fallbackProviders } from "@reflag/node-sdk";

const client = new ReflagClient({

secretKey: process.env.REFLAG_SECRET_KEY,

flagsFallbackProvider: fallbackProviders.static({

flags: {

huddle: true,

"smart-summaries": false,

},

}),

});

await client.initialize();

The built-in Redis provider creates a Redis client automatically when omitted and uses `REDIS_URL` from the environment. It stores snapshots under the configured `keyPrefix` and uses the first 16 characters of the secret key hash in the Redis key.

import { ReflagClient, fallbackProviders } from "@reflag/node-sdk";

const client = new ReflagClient({

secretKey: process.env.REFLAG_SECRET_KEY,

flagsFallbackProvider: fallbackProviders.redis(),

});

await client.initialize();

The built-in S3 provider works out of the box using the AWS SDK's default credential chain and region resolution. It stores the snapshot object under the configured `keyPrefix` and uses a hash of the secret key in the object name.

import { ReflagClient, fallbackProviders } from "@reflag/node-sdk";

const client = new ReflagClient({

secretKey: process.env.REFLAG_SECRET_KEY,

flagsFallbackProvider: fallbackProviders.s3({

bucket: process.env.REFLAG_SNAPSHOT_BUCKET!,

}),

});

await client.initialize();

The built-in GCS provider works out of the box using Google Cloud's default application credentials. It stores the snapshot object under the configured `keyPrefix` and uses a hash of the secret key in the object name.

import { ReflagClient, fallbackProviders } from "@reflag/node-sdk";

const client = new ReflagClient({

secretKey: process.env.REFLAG_SECRET_KEY,

flagsFallbackProvider: fallbackProviders.gcs({

bucket: process.env.REFLAG_SNAPSHOT_BUCKET!,

}),

});

await client.initialize();

To test fallback startup in your own app, first run it once with a working Reflag connection so a snapshot is saved. Then restart it with the same secret key and fallback provider configuration, but set `apiBaseUrl` to `http://127.0.0.1:65535`. That forces the live fetch to fail and lets you verify that the SDK initializes from the saved snapshot instead.

If you just want a fixed fallback copy of the flag definitions, a custom provider can be very small:

import type {

FlagsFallbackProvider,

FlagsFallbackSnapshot,

} from "@reflag/node-sdk";

const fallbackSnapshot: FlagsFallbackSnapshot = {

version: 1,

savedAt: "2026-03-10T00:00:00.000Z",

flags: [

{

key: "huddle",

description: "Fallback example",

targeting: {

version: 1,

rules: [],

},

},

],

};

export const staticFallbackProvider: FlagsFallbackProvider = {

async load() {

return fallbackSnapshot;

},

async save() {

// no-op

},

};

The `getFlagsForBootstrap()` method is useful whenever you need to pass flag data to another runtime or serialize it without wrapper functions. Server-side rendering (SSR) is a common example, but it is also useful for other bootstrapping and hydration flows.

// In offline mode, the SDK uses explicit local configuration only.

// It does not fetch from Reflag or use flagsFallbackProvider.

| Option | Type | Description | Env Var |

| ----------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |

| `secretKey` | string | The secret key used for authentication with Reflag's servers. | REFLAG_SECRET_KEY |

| `logLevel` | string | The log level for the SDK (e.g., `"DEBUG"`, `"INFO"`, `"WARN"`, `"ERROR"`). Default: `INFO` | REFLAG_LOG_LEVEL |

| `offline` | boolean | Operate in offline mode. Default: `false`, except in tests it will default to `true` based off of the `TEST` env. var. In offline mode the SDK does not fetch from Reflag and does not use `flagsFallbackProvider`. | REFLAG_OFFLINE |

| `apiBaseUrl` | string | The base API URL for the Reflag servers. | REFLAG_API_BASE_URL |

| `flagOverrides` | Record<string, boolean> | An object specifying flag overrides for testing or local development. See [examples/express/app.test.ts](https://github.com/reflagcom/javascript/tree/main/packages/node-sdk/examples/express/app.test.ts) for how to use `flagOverrides` in tests. | REFLAG_FLAGS_ENABLED, REFLAG_FLAGS_DISABLED |

| `flagsFallbackProvider` | `FlagsFallbackProvider` | Optional provider used to load and save raw flag definitions for fallback startup when the initial live fetch fails. Available only through the constructor. Ignored in offline mode. | - |

| `configFile` | string | Load this config file from disk. Default: `reflag.config.json` | REFLAG_CONFIG_FILE |

"@aws-sdk/client-s3": "^3.888.0",

"@google-cloud/storage": "^7.19.0",

"@redis/client": "^5.11.0",