Configs

For more information about Configurations, visit the Configurations Guide.

const gamebeastConfigs = gamebeast.configs;

PathsCopy Anchor Link

Values are addressed by path. The first segment is the configuration's ID, which you copy from its ⋯ menu in the dashboard with Copy ID:

• "game-settings.PlayerSpeed" reads the PlayerSpeed key of the game-settings configuration.
• "game-settings.UI.ButtonColor" reaches deeper, and "game-settings.Levels.0" indexes an array.
• "game-settings" on its own returns the whole configuration document.
• ["game-settings", "key.with.dots"] is the array form, for keys that contain a ..

Values are always deep copies, so changing a returned object never affects what the SDK holds.

FallbacksCopy Anchor Link

Every read accepts an optional fallback. With one, you get the fallback when the value is missing, null, not loaded yet, or a different JSON type than the fallback (a mismatch is logged once). That makes the fallback both a default and a type check:

const speed = gamebeastConfigs.get("game-settings.PlayerSpeed", 16); // number, always

Without a fallback, get returns undefined when there's no value. The type parameter (get<number>(…)) is not checked at runtime, so prefer a fallback where the type matters.

Client methodsCopy Anchor Link

In the browser, configurations are evaluated for the current user: if they're enrolled in an active experiment, the values already include their group's changes.

Configurations load on demand: the first read of a configuration fetches it. Listing it in the configurations option fetches it at startup instead and makes isReady / onReady wait for it. Values are cached in localStorage per user and app version, so on the next visit they're available immediately and then refreshed in the background.

While the page is visible, the SDK re-checks configurations every configRefreshIntervalSeconds (60 by default), and again when the tab becomes visible. An unchanged configuration costs one small round trip.

get(path, fallback?)Copy Anchor Link

→T | undefinedreturn type

Reads a value. Returns the fallback (or undefined without one) when the configuration hasn't loaded yet. Prefer observe when the value may still be loading.

UsageCopy Anchor Link

const speed = gamebeastConfigs.get("game-settings.PlayerSpeed", 16);
const color = gamebeastConfigs.get("game-settings.UI.ButtonColor", "blue");

// Whole document, typed by you
interface GameSettings {
  PlayerSpeed: number;
}
const settings = gamebeastConfigs.get<GameSettings>("game-settings");

observe(path, callback)Copy Anchor Link

→Unsubscribereturn type

Calls callback with the current value as soon as it's available, and again each time it changes. This is the best fit for values that may still be loading, and for UI that should follow live changes.

UsageCopy Anchor Link

const stop = gamebeastConfigs.observe("game-settings.PlayerSpeed", (speed) => {
  player.speed = typeof speed === "number" ? speed : 16;
});

onChanged(path, callback)Copy Anchor Link

→Unsubscribereturn type

Calls callback whenever the value at path changes. It does not fire for the initial load; use observe for that.

UsageCopy Anchor Link

gamebeastConfigs.onChanged("game-settings.MaintenanceMode", (on) => {
  if (on === true) showMaintenanceBanner();
});

isReadyCopy Anchor Link

→booleanreturn type

True once every configuration listed in the configurations option has loaded (from the cache or the network) or failed permanently, for example because it doesn't exist. Configurations fetched on demand don't affect it.

onReady(callback)Copy Anchor Link

→Unsubscribereturn type

Calls callback once isReady becomes true, or immediately if it already is.

UsageCopy Anchor Link

gamebeastConfigs.onReady(() => startGame());

ready(options?)Copy Anchor Link

→Promise<boolean>return type

Resolves true once ready, or false if timeoutMs passes first. It never rejects, so you can always await it before rendering without a try.

UsageCopy Anchor Link

if (!(await gamebeastConfigs.ready({ timeoutMs: 3_000 }))) {
  console.warn("Using default settings: configurations did not load in time.");
}

refresh()Copy Anchor Link

→Promise<void>return type

Re-fetches every known configuration now, in addition to the background refresh. Resolves once the requests have settled.

Server methodsCopy Anchor Link

On the server there's no current user, so configs come in two kinds:

• Base values (get, observe, onChanged, list): the configuration as written in the dashboard, with no experiment applied. Good for settings that are the same for everyone, such as maintenance mode or feature flags.
• Evaluated values (evaluate): the configuration for one user, with their experiment groups applied. Use this whenever the value depends on who's asking.

At startup the SDK loads every configuration and active experiment in one request. It then polls a lightweight status endpoint (every 30 seconds by default) and refetches documents only when one changes.

evaluate(options)Copy Anchor Link

→Promise<EvaluatedConfiguration>return type

Evaluates a configuration for one user (or server). The backend enrolls them in eligible experiments, records the assignment, and returns the document with their group's changes merged in.

Results are reused for evaluationCacheSeconds (30 by default). After that the SDK revalidates them, and an unchanged result costs one small round trip. Concurrent calls for the same user, configuration and properties share one request.

evaluate never rejects. If the backend can't be reached, it falls back to the user's last evaluated value, then to the base configuration. Check source when the difference matters.

TypesCopy Anchor Link

interface EvaluatedConfiguration {
  // Where the value came from (see the table below).
  source: "evaluated" | "stale" | "base" | "unavailable";
  configurationId: number | null;
  name: string | null;
  hash: string | null;
  // The whole document. undefined when source is "unavailable".
  value: JsonValue | undefined;
  // The experiment assignments that shaped this value.
  experiments: ExperimentAssignmentMetadata[];
  // Why evaluation failed, when source is not "evaluated".
  error: string | undefined;
  // Reads inside the document. The path is relative to the document root,
  // so it does not start with the configuration ID.
  get<T>(path?: ConfigPath, fallback?: T): T | undefined;
}

UsageCopy Anchor Link

const config = await gamebeastConfigs.evaluate({
  distinctId: user.id,
  configuration: "game-settings",
  properties: { plan: user.plan },
});

const speed = config.get("PlayerSpeed", 16); // relative to the document
const color = config.get("UI.ButtonColor", "blue");

get(path, fallback?)Copy Anchor Link

→T | undefinedreturn type

Reads a base value: the configuration as written, with no experiment applied. Returns the fallback until configurations have loaded, so await ready() at startup.

UsageCopy Anchor Link

await gamebeastConfigs.ready();
const maintenance = gamebeastConfigs.get("live-ops.MaintenanceMode", false);

observe(path, callback)Copy Anchor Link

→Unsubscribereturn type

Calls callback with the current base value as soon as it's available, and again each time it changes.

UsageCopy Anchor Link

gamebeastConfigs.observe("live-ops.MaintenanceMode", (on) => setMaintenance(on === true));

onChanged(path, callback)Copy Anchor Link

→Unsubscribereturn type

Calls callback whenever the base value at path changes. It does not fire for the initial load.

isReadyCopy Anchor Link

→booleanreturn type

True once the configuration snapshot has loaded.

ready(options?)Copy Anchor Link

→Promise<boolean>return type

Resolves true once configurations have loaded, or false on a permanent failure (for example, the key lacks access) or when timeoutMs passes. It never rejects.

list()Copy Anchor Link

→ConfigurationInfo[]return type

Every configuration in the environment. Empty until loaded.

interface ConfigurationInfo {
  id: number;
  name: string | null;
  alias: string | null; // The configuration ID used in paths.
  hash: string;
  isPrimary: boolean;
}

refresh()Copy Anchor Link

→Promise<void>return type

Checks for configuration and experiment changes now. With autoRefresh: false (for example in a serverless function), call it when you need current base values.