Offline Support & Caching

Flagpool SDKs cache flag values locally and continue working even when the network is unavailable. Your application never blocks on a flag evaluation — regardless of connectivity.

How it works

After the initial fetch, the SDK maintains an in-memory cache of all flag configurations. If the network goes down, the SDK continues evaluating flags from this cache.

┌──────────────┐     Network OK      ┌──────────────┐
│    CDN       │ ──────────────────▶  │   SDK Cache  │
│  (Edge)      │                      │  (In-memory) │
└──────────────┘                      └──────┬───────┘
                                             │
                     Network DOWN            │  Local evaluation
                     ─────────────           │  continues working
                                             ▼
                                      ┌──────────────┐
                                      │  Your App    │
                                      │  (< 1ms)     │
                                      └──────────────┘

Cache lifecycle

Scenario	Behavior
First load, network OK	Fetch from CDN, cache locally
Subsequent load, network OK	Fetch from CDN, update cache
Network down, cache exists	Use cached values seamlessly
Network down, no cache	Use SDK default values (safe fallback)

Default values as safety net

Every flag evaluation in Flagpool accepts a default value. This is your safety net for the worst case — no network and no cache:

// The third argument is the default value
const showFeature = client.isEnabled('new-checkout', context, false)
// If the SDK has no data at all, returns false — your app keeps working

This pattern ensures your application always has a valid flag value, no matter what.

Polling and updates

SDKs periodically poll the CDN for updates. The polling interval is configurable:

const client = new FlagpoolClient({
  pollingInterval: 30000, // Check every 30 seconds (default)
})

Between polls, the SDK uses the cached values. If a poll fails (network error), the SDK logs the failure and retries on the next interval — the cache remains valid.

Stale-while-revalidate

The SDK uses a stale-while-revalidate strategy to ensure instant responses even during cache refresh:

0-60s:    Serve from cache (instant)
60-360s:  Serve stale value, fetch fresh in background
360s+:    Fetch fresh (wait for response)

This means:

• Users never wait for a flag fetch after the initial load
• Updates propagate within seconds of a CDN cache purge
• Graceful degradation if the origin is slow or unreachable

Real-time change detection

Subscribe to flag changes to react immediately when values update:

client.onChange((key, value) => {
  console.log(`Flag ${key} changed to:`, value)
})

This fires whenever a poll returns updated flag values, letting your application respond in real-time without page reloads.

Use cases

Scenario	How offline caching helps
Mobile apps	Users in subways, elevators, or poor coverage areas get uninterrupted feature flags
Edge computing	Serverless functions at the edge work even during origin outages
Microservices	Services continue operating during brief network partitions
Desktop apps	Offline-first desktop applications evaluate flags without connectivity

Next steps

• Architecture & Performance — CDN and caching layers in detail
• JavaScript SDK — SDK initialization and configuration
• Security Overview — what data is cached and how it's protected