Config Patterns

Patterns & Best Practices

Config vs KV Store

While both use NATS JetStream under the hood, they solve different problems.

Feature	Config Management	KV Store
Model	JSON Documents (Objects).	Individual Keys (Raw).
Scoping	Automatic per Environment.	Manual per Bucket.
Updates	Full set or shallow patch.	put, create, or update.
Best For	Feature flags, App settings.	Caching, sessions, counters.

---

Pattern: Feature Flags

Store all your flags in a single JSON document. This allows your frontend or workers to load all active flags in a single network request.

TypeScript

import { createClient } from "@ironflow/node";

const ironflow = createClient({ apiKey: process.env.IRONFLOW_API_KEY });
const config = ironflow.config();

// 1. Define the flags
await config.set("flags", {
  "new-onboarding": true,
  "promo-banner": false,
  "max-items": 10
});

// 2. Patch one flag without affecting others
await config.patch("flags", { "promo-banner": true });

Go

// Patch a single flag
_, err := client.Config().Patch(ctx, "flags", map[string]any{
    "promo-banner": true,
})

---

Pattern: Application Settings

Centralize your server-side constants (timeouts, URLs, thresholds). Your workers can fetch these at startup or watch for changes to update their behavior without a restart.

const settings = await config.get("worker-settings");

if (settings.data.maintenanceMode) {
  process.exit(0); // Graceful pause
}

---

Pattern: Hot Reload via Watch

Subscribe to a document and react to every change without a restart. Watch is available in both the Node and Browser SDKs and is delivered over WebSocket.

const watcher = config.watch("worker-settings", {
  onUpdate: (event) => {
    applyRuntimeConfig(event.data);
  },
  onError: (err) => console.error("config watch error:", err),
});

// Later — stop watching during graceful shutdown
watcher.stop();

---

Pattern: Discovery & Cleanup

Use list() to enumerate every config document in the current environment, and delete() to remove a stale one.

const docs = await config.list();
for (const doc of docs) {
  console.log(doc.name);
}

await config.delete("legacy-flags");

---

Best Practices

1. Environment Scoping is Automatic: The server derives the environment from the API Key on the request. There is no environment header to pass — use a different API Key per environment to target dev / staging / production.
2. Shallow Merge: Prefer patch() over set() for runtime updates to prevent accidentally overwriting keys set by other team members or processes. patch() also creates the document if it does not yet exist.
3. Validation: Perform schema validation in your application logic after calling get(), as the Config Store accepts any valid JSON.