Runtime settings

config reads runtime settings from the store you already use, checked against a JSON schema in your repo. A change reaches every running instance in seconds, with no deploy.

config.get() reads memory and never waits on the store, so the app answers at once. A bad value keeps the last good one, and every change the app sees is audited. Reach for it for values operators tune at run time, such as a cart limit or a support banner. App structure and drivers belong in main.yaml; feature switches per user belong in Feature flags.

config:
  driver: redis                  # memory | files | redis
  schema: ./config.schema.json
  refresh: 30s                   # poll interval without a change stream
  values: { checkout.currency: INR }
  files: { dir: config/ }        # files driver
  redis: { url: secret:REDIS_URL, prefix: "mainsdk:prj_01JC8Q…" }

import { config, log } from "mainsdk";

const maxItems = config.get("cart.maxItems");     // typed from the schema; synchronous, from memory
const stop = config.watch("cart.maxItems", (v) => log.info("changed", { v }));

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { MemoryConfigStore } from "mainsdk";

describe("cart settings", () => {
  it("applies a pushed value", async () => {
    const store = new MemoryConfigStore();
    const app = createTestApp({ yaml: "schema: 1\nproject: prj_test\nconfig:\n  driver: memory", configDriver: store });
    store.set("cart.maxItems", 20);
    await app.live.refresh();
    assert.equal(app.live.get("cart.maxItems"), 20);
  });
});

config:
  driver: files

Quick start

Point config at a store and a schema, then read keys by name. With the files driver, each file in config/ holds one prefix: config/cart.json with { "maxItems": 20 } sets cart.maxItems.

config:
  driver: files
  schema: ./config.schema.json

{
  "type": "object",
  "properties": {
    "cart": {
      "type": "object",
      "properties": { "maxItems": { "type": "integer" } }
    }
  }
}

import { config } from "mainsdk";

export function canAdd(count: number) {
  return count < (config.get("cart.maxItems") as number);   // synchronous; reads memory
}

use mainsdk::prelude::*;
let app = App::test();
let project = app.config().get("project").await?;
assert_eq!(project, Some("prj_test".into()));

config.get() returns unknown today, so cast the value as above. Generating TypeScript types from the schema, so that config.get("cart.maxItem") fails type checking, is planned. A pushed value that fails the schema is refused at run time with MAIN-CONFIG-0020.

Configuration

config:
  driver: redis                  # memory | files | redis (postgres planned)
  schema: ./config.schema.json   # JSON schema every value is checked against
  refresh: 30s                   # poll interval; the store can also send change hints
  values: { cart.maxItems: 20 }  # deployed defaults; overlays may change them
  files: { dir: config/ }        # files driver: config/*.json, merged in file-name order
  redis: { url: secret:REDIS_URL, prefix: "mainsdk:prj_01JC8Q…" }   # prefix defaults to mainsdk:<project>

Settings are not secrets. Keep credentials in Secrets and refer to them with secret:NAME.

Where a value comes from

From lowest to highest: the schema default, then config.values in main.yaml after its overlays, then the latest value the driver applied. A key that is in none of them returns undefined.

Overlays by environment

Use files in development and a shared store in production:

config:
  driver: files

config:
  driver: redis

What you get

Always:

• Reads never wait on the store, and a store outage serves the last good values.
• A value that fails the schema is refused and the last good one is kept.
• A push can only tighten what main.yaml allows.
• Every applied or refused change is audited by key and hash, never by value.

Examples

Read a setting in a Next.js route handler

import { auth, config } from "mainsdk";

export async function POST(req: Request) {
  await auth.require(req);
  const { items } = (await req.json()) as { items: unknown[] };
  const max = config.get("cart.maxItems") as number;
  if (items.length > max) {
    return Response.json({ error: `Keep the cart to ${max} items` }, { status: 422 });
  }
  return Response.json({ ok: true });
}

React to a change without a deploy

config.watch() calls you once for each change to the key, after the change is applied, and returns a function that stops it.

import { config, log } from "mainsdk";

let batchSize = config.get("worker.batchSize") as number;

const stop = config.watch("worker.batchSize", (value) => {
  batchSize = value as number;
  log.info("batch size changed", { batchSize });
});

process.on("SIGTERM", () => stop());

Watch a group of keys

A key ending in .* watches every key under that prefix. The callback gets the change's key.

import { config, log } from "mainsdk";

config.watch("checkout.*", (_value, change) => {
  log.info("checkout setting changed", { key: change.key });
});

A support banner from a fetch handler

Any server that speaks Request and Response, Hono included, can read a setting the same way.

import { config } from "mainsdk";

export default {
  fetch(req: Request) {
    if (new URL(req.url).pathname !== "/banner") return new Response("Not found", { status: 404 });
    return Response.json({ text: config.get("support.banner") });
  },
};

Pushing main.yaml values

The store can change a few main. settings at run time, such as a spend limit or an allowed host. A push can only tighten them. Each key is checked on its own, so a refused key keeps its last good value and the other keys in the same push still apply.

Exceptions in main.yaml do not apply to a push. Removing a pushed key brings back the main.yaml value. A pushed secret value is refused: put secrets in Secrets.

What happens when something goes wrong

If someone sets cart.maxItems to "twenty" in the store, the change is rejected with MAIN-CONFIG-0020, and config.get() keeps returning the last good value.

If the store goes down, the app keeps serving the last good values from memory and logs MAIN-CONFIG-0023 once for the outage. It does not wait and does not restart. The last applied snapshot is kept in .mainsdk/cache/config.json, so a restart during an outage serves it too.

Reference

Typed keys

config.get and config.watch are typed from config.schema. Write the declaration file once, and again when the schema changes; a typo in a key then fails type checking, and an integer key reads as number. A key with no default also reads as undefined.

import { readFileSync, writeFileSync } from "node:fs";
import { configTypes } from "mainsdk";

writeFileSync("mainsdk-config.d.ts", configTypes(JSON.parse(readFileSync("config.schema.json", "utf8"))));

Until a file is generated, keys are plain strings and values are unknown.

Errors and checks

Type errors for unknown keys show up in your editor and build, before mainsdk check runs. Run mainsdk explain MAIN-CONFIG-0020 for the cause and fix offline.

Swapping drivers

Change one line. Your schema, config.get() and config.watch() calls stay the same; copy the values into the new store.

config:
  driver: redis   # was files

When you need a provider-only feature, config.raw() returns the provider's client. Every use is logged and listed by mainsdk check.

Testing

The test app runs config on an in-memory MemoryConfigStore you can share and script. Change a value, call app.live.refresh(), and read it back.

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import { MemoryConfigStore } from "mainsdk";

describe("cart settings", () => {
  it("applies a pushed value", async () => {
    const store = new MemoryConfigStore();
    const app = createTestApp({ yaml: "schema: 1\nproject: prj_test\nconfig:\n  driver: memory", configDriver: store });
    store.set("cart.maxItems", 20);
    await app.live.refresh();
    assert.equal(app.live.get("cart.maxItems"), 20);
  });
});

See the Testing kit for fakes and the clock.

Security and privacy

• Every applied and refused change is written to the audit log with the key, hashes of the old and new values, and the source.
• No setting value appears in an audit record, a log line or an error. Only its key and hash do.
• Values are validated against your schema, so a bad value in the store cannot reach your code.
• A push can't loosen a rule in main.yaml, so a compromised store can only make the app stricter.
• Do not keep credentials or personal data in settings; use Secrets and Data and records.

FAQ

How is this different from main.yaml? main.yaml declares what your app is and which drivers it uses, and changes go through a pull request. config holds values that change at run time without a deploy.

How is this different from feature flags? Flags turn features on per user or market. Their definitions are kept in the same store, at flags.<name>, and pass the same checks. See Feature flags.

What if the store is down at startup? The app starts at once and does not wait for the store. It serves the last applied snapshot from .mainsdk/cache/config.json if there is one. With no cache, each key returns its config.values entry or schema default until the first load succeeds.

Refresh and ready

config.refresh() loads from the store now and applies it. It never rejects. config.ready() waits for the first load, or for its timeout. It never rejects either, so a slow store cannot stop start-up.

import { config } from "mainsdk";

await config.ready({ timeout: 2000 });   // first load applied, or 2 s passed
await config.refresh();                  // pull the latest values now

Next

• Feature flags: turn features on per user or market.
• Secrets: credentials, server only.
• Change config without a deploy: a walkthrough with rollouts and watchers.
• Logs, audit and telemetry: where config changes are audited.