Legacy Configuration Types

This page documents the legacy type form. It remains supported, and it can be mixed with schema-backed entries in the same module. For new runtime validation, native defaults, transforms, and structured values, use Schema-backed Configuration.

Every legacy entry has a type field. default, description, required, enum, and source are legacy entry metadata.

Type reference

type value	Injected TypeScript type	Notes
"string"	string	enum narrows TypeScript only; the legacy parser does not reject an out-of-enum runtime value
"number"	number	Parsed with Number; invalid input can become NaN
"boolean"	boolean	String input is true only for case-insensitive "true" and "y"
"string[]"	string[]	CSV strings are split on commas; a JSON array string is also accepted
"record"	Record<string, string>	Object values pass through; string values are parsed as JSON
"internal"	The declared value shape	Reserved for framework-managed or library-internal values

string

API_URL: {
  type: "string",
  required: true,
}

required: true is checked during finalization. If no value is available, bootstrap throws REQUIRED_CONFIGURATION_MISSING.

enum narrowing

enum narrows the TypeScript type:

ENVIRONMENT: {
  type: "string",
  enum: ["local", "staging", "production"] as const,
  default: "local",
}

The injected TypeScript type is "local" | "staging" | "production". The legacy runtime parser still treats the value as a string; it does not enforce membership in the enum list. Use a native schema union or enum when runtime rejection is required.

number

PORT: {
  type: "number",
  default: 3000,
}

Environment and CLI strings are passed to Number. A non-numeric value is not rejected by the legacy parser and may produce NaN.

boolean

DEBUG_MODE: {
  type: "boolean",
  default: false,
}

The legacy string conversion is intentionally narrow:

String input	Result
"true", "TRUE", "y", "Y"	true
"1", "yes", "false", "n", "0", or any other string	false

Native schemas have provider-specific boolean parsing and validation; do not infer schema behavior from this legacy table.

string[]

ALLOWED_ORIGINS: {
  type: "string[]",
  default: ["http://localhost:3000"],
}

A normal string is split as CSV:

MY_APP__ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com

The parser also accepts a string beginning with [ as JSON. Repeated CLI switches arrive as an array:

--my_app__ALLOWED_ORIGINS=https://app.example.com --my_app__ALLOWED_ORIGINS=https://admin.example.com

Schema arrays use native provider input; use JSON rather than relying on the legacy CSV convention.

record

FEATURE_FLAGS: {
  type: "record",
  default: {},
}

A string value is parsed as JSON, while an object value is retained. The default legacy value type is Record<string, string>; use a schema when the map needs runtime value validation.

internal

The internal type is a legacy escape hatch for framework-managed structured values. It is not intended for ordinary application configuration. Prefer a native object or record schema when the value has a user-facing contract.

source and required

source is an entry-level allow-list for loader channels such as env, argv, file, or a registered custom loader. required only applies to legacy entries. See Config Sourcing and Accessing Config.

Try it live

This editor intentionally shows the legacy form so its compatibility parsing is visible. For the schema-backed TypeBox example, open the typed configuration tutorial.

Loading...