Init and Config

Baseline Recommendations

This table shows baseline recommendations for SDK initialization and configuration:

SDK is initialized once as a singleton early in the application's lifecycle

Applies to: All SDKs

Prevent duplicate connections, conserve resources, and ensure consistent caching/telemetry.

Implementation

• MUST Expose exactly one ldClient per process/tab via a shared module/DI container (root provider in React).
• SHOULD Make init idempotent: reuse the existing client if already created.
• SHOULD Close the client cleanly on shutdown. In serverless, create the client outside the handler for container reuse.
• NICE-TO-HAVE Emit a single startup log summarizing effective LD config (redacted).

Validation

• Pass if metrics/inspector show one stream connection per process/tab.
• Pass if event volume and resource usage do not scale with repeated imports/renders.

Application does not block indefinitely for initialization

Applies to: All SDKs

A LaunchDarkly SDK is initialized when it connects to the service and is ready to evaluate flags. If variation is called before initialization, the SDK returns the fallback value you provide. Do not block your app indefinitely while waiting for initialization. The SDK continues connecting in the background. Calls to variation always return the most recent flag value.

Implementation

• MUST Set an initialization timeout
  • Client-side: 100–500 ms.
  • Server-side: 1–5 s.
• SHOULD Race initialization against a timer if using an SDK that lacks a native timeout parameter.
• MAY Render/serve using bootstrapped or fallback values, then update when flags are ready.
• MAY Subscribe to change events to proactively respond to flag updates.
• MAY Configure a persistent data store to avoid fallback values in the event that the SDK is unable to connect to LaunchDarkly services.

Validation

• Pass if with endpoints blocked the app renders using fallbacks or bootstrapped values within the configured timeout.
• Pass if restoring connectivity updates values without a restart.

How to emulate:

• Point streaming/base/polling URIs to an invalid host
• Block the SDK domains in the container or host running the tests: stream.launchdarkly.com, sdk.launchdarkly.com, clientsdk.launchdarkly.com, app.launchdarkly.com
• In browsers, block clientstream.launchdarkly.com, clientsdk.launchdarkly.com, and/or app.launchdarkly.com in DevTools.

SDK configuration integrated with existing configuration/secrets management

Applies to: All SDKs

Use your existing configuration pipeline so LD settings are centrally managed and consistent across environments. Avoid requiring code changes setting common SDK options.

Implementation

• MUST Load SDK credentials from existing configuration/secrets management system.
• MUST NOT Expose the server-side SDK Key to client applications
• SHOULD Use configuration management system to set common SDK configuration options such as:
  • HTTP Proxy settings
  • Log verbosity
  • Enabling/disabling events in integration testing or load testing environments
  • Private attribute

Validation

• Pass if rotating the SDK key in the vault results in successful rollout and the old key is revoked.
• Pass if a repository scan finds no SDK keys or environment IDs committed.
• Pass if startup logs (redacted) show expected config per environment and egress connectivity succeeds with 200/OK or open stream.

Bootstrapping strategy defined and implemented

Applies to: JS Client-Side SDK in browsers, React SDK, Vue SDK

Prevent UI flicker by rendering with known values before the SDK connects and retrieves flags.

Implementation

• SHOULD Enable bootstrap: 'localStorage' for SPAs/PWAs to reuse cached values between sessions.
• SHOULD For SSR or static HTML, embed a server-generated flags JSON and pass to the client SDK at init.
• MUST Document which strategy each app uses and when caches expire.
• SHOULD Reconcile bootstrapped values with live updates and re-render when differences appear.

Validation

• Pass if under offline/slow network the first paint uses bootstrapped values with no visible flash of wrong content.
• Pass if clearing storage falls back to safe defaults and live updates correct the UI on reconnect.
• Pass if evaluations are recorded after successful initialization.