Client-side cache limits

Browser and mobile client SDKs can persist feature definitions keyed by evaluation context (identity, groups, and claims). Apps that switch users or contexts can accumulate many storage entries over time.

maxCacheKeys

Set optional maxCacheKeys to a positive integer to cap how many identity-scoped storage keys are retained. Omit it, or pass null, to keep unlimited retention (the default).

When the limit is exceeded, the SDK evicts the least recently accessed storage keys (true LRU). Each flags, variants, or (on Flutter) per-identity revision entry counts as one key. Global slots such as the current identity, JWKS, and web app-wide revision/ETag are not counted.

For a given evaluation context, sibling keys written together (flags + variants, and on Flutter the matching revision) are protected as a set during eviction so a refresh cannot leave only half of that context in storage.

Accesses that successfully read or write a tracked entry bump that key’s last-accessed time. Eviction runs after writes when a limit is configured.

Supported SDKs:

• JavaScript (@ops-ai/feature-flags-toggly)
• React, Vue, Svelte, Angular adapters
• React Native core
• Flutter (feature_flags_toggly + official cache providers)

Examples

JavaScript / React / Vue / Svelte / Angular

Toggly.init({
  appKey: '<YOUR_APP_KEY>',
  environment: '<YOUR_APP_ENVIRONMENT>',
  persistCache: true, // default
  maxCacheKeys: 20,   // keep at most 20 flags/variants storage keys
});

Framework adapters expose the same option on their provider / plugin / forRoot config.

React Native

<TogglyProvider
  appKey="your-app-key"
  environment="production"
  storage={storage}
  maxCacheKeys={20}
>
  <App />
</TogglyProvider>

Flutter

await Toggly.init(
  appKey: '<YOUR_APP_KEY>',
  environment: '<YOUR_APP_ENVIRONMENT>',
  identity: currentUserId,
  config: TogglyConfig(
    cacheProvider: SecureStorageCacheProvider(),
    maxCacheKeys: 20,
  ),
);

Flutter applies the limit through a wrapper around your cacheProvider. Custom providers must implement readCacheLruIndex / writeCacheLruIndex (official backends already do).

Notes

• Non-positive values are treated as unlimited.
• Eviction failures are reported via onError where applicable and do not fail feature evaluation.
• Clearing the current context’s cache also removes those keys from the LRU index.