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.

A server has 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.