Runtime configuration

NetScript splits configuration into two layers: a typed project config you author once in netscript.config.ts and load at startup (@netscript/config), and a hot-reloadable runtime override layer that operators roll out without redeploying (@netscript/runtime-config). Together they give you one validated, type-safe view of how the app is wired — defaults baked into the schema, values pulled from a config file and the environment, and last-mile operational overrides applied at runtime.

What it is

Project config is the static, schema-validated topology of a NetScript app. You author it with defineConfig (or defineConfigAsync when the shape depends on mode/command), NetScript validates it against a Zod schema, and loadConfig / initConfig resolve the authored file into a fully typed NetScriptConfig. Environment variables feed into this layer through resolveEnv / getEnv, which coerce and default typed values per call.

Runtime config is a separate, dynamic override layer. It lives under a runtime/ directory of versioned JSON files (jobs, sagas, triggers, features, tasks) selected by a current version pointer. loadRuntimeConfig reads it into a RuntimeConfig snapshot; watchRuntimeConfig reloads on change. Missing files produce empty defaults so startup never blocks on overrides that have not been rolled out yet. The two packages are deliberately distinct: @netscript/config owns the build-time contract, and @netscript/runtime-config owns the hot-reloadable operational layer.

Learn → / Do →

Minimal example

Author the project config once, then load and inspect it at startup. The runtimeConfig section of the project config controls where the generated runtime schema/output lives; the live overrides are read separately by @netscript/runtime-config.

// netscript.config.ts
import { defineConfig } from '@netscript/config';

export default defineConfig({
  name: 'orders',
  version: '1.0.0',
  databases: {
    active: 'postgres',
    config: [{ provider: 'postgres', schema: 'database/postgres/schema' }],
  },
  services: {
    api: { port: 3000 },
  },
  plugins: ['@netscript/plugin-workers'],
});

// src/bootstrap.ts — load project config + apply runtime overrides
import { initConfig, getConfig } from '@netscript/config';
import { isFeatureEnabled, loadRuntimeConfig } from '@netscript/runtime-config';

// 1. Project config: validated once, then read synchronously anywhere via getConfig().
await initConfig();
const config = getConfig();

// 2. Runtime overrides: hot-reloadable JSON the operator controls (empty if unset).
const runtime = await loadRuntimeConfig();
const rolloutOn = isFeatureEnabled(runtime, 'worker-rollout', false);

console.log(config.name, config.services?.api?.port, rolloutOn);

Key types first

The project config you author is NetScriptConfigInput; what loadConfig / initConfig return is the fully validated NetScriptConfig. These are the load-bearing fields.

The runtime override snapshot is a separate type — RuntimeConfig — returned by loadRuntimeConfig(). Each field is an array loaded from one topic directory.

Resolution & precedence

There is no single monolithic merge function — resolution happens across the two packages, each with its own precedence. The order below is the conceptual chain the diagram depicts.

Runtime override layout

The runtime override directory is resolved from the environment, then read through the current pointer that names the active version of each topic file.

// src/feature-gate.ts
import { isFeatureEnabled, loadRuntimeConfig } from '@netscript/runtime-config';

const runtime = await loadRuntimeConfig();

// Third arg is the fallback when the flag file/entry is absent.
if (isFeatureEnabled(runtime, 'worker-rollout', false)) {
  // run the gated path
}

// src/runtime-watch.ts
import { summarizeRuntimeConfig, watchRuntimeConfig } from '@netscript/runtime-config';

const controller = new AbortController();

watchRuntimeConfig(async (config) => {
  const summary = summarizeRuntimeConfig(config);
  // re-apply overrides; summary.messages is presentation-ready
  console.log(summary.messages.join('\n'));
}, { signal: controller.signal });

// src/env.ts
import { getEnv, resolveEnv } from '@netscript/config';

const port = getEnv('PORT', { type: 'number', default: 3000 });

const env = resolveEnv({
  DATABASE_URL: { env: 'DB_URL', required: true },
  DEBUG: { type: 'boolean', default: false },
});

Production notes

Reference →

This hub is intentionally thin — the full generated API surface for both packages lives in the reference.

runtime-config