configVar()

Creates a standard config variable object for code-native integrations.

The configVar() function defines a standard (non-connection, non-data-source) config variable. Standard config variables hold primitive values — strings, numbers, booleans, schedules, lists, and more — that customers supply when deploying an instance. They are placed in the elements record of a configPage().

Function signature

export const configVar = <T extends StandardConfigVar>(
  definition: T,
): T

Parameters

definition · StandardConfigVar · required

An object describing the config variable. The required fields depend on the dataType chosen.

Hide Common fields

stableKey · string · required

A unique, unchanging identifier for this config variable. Even if the variable’s key (its name in elements) changes, stableKey preserves the identity of the stored value in the platform.

dataType · ConfigVarDataType · required

The data type of this config variable. Determines the input control shown in the config wizard UI and the runtime value type.

Value	Runtime type	Notes
"string"	string	Plain text input
"date"	string	Date picker (ISO format)
"timestamp"	string	Date-time picker (ISO format)
"picklist"	string	Dropdown — requires pickList
"code"	string	Code editor — requires codeLanguage
"boolean"	boolean	Toggle switch
"number"	number	Numeric input
"schedule"	Schedule	Cron schedule — optionally set timeZone
"objectSelection"	ObjectSelection	Multi-object selector
"objectFieldMap"	ObjectFieldMap	Field mapping UI
"jsonForm"	unknown	JSON Form (requires schema)
"htmlElement"	string	Read-only HTML display element

description · string

Human-readable description shown to the user in the config wizard.

defaultValue · string | boolean | number | ...

Default value for this config variable. The accepted type matches the dataType. For "boolean" the value is a boolean; for "number" it is a number; for most others it is a string.

collectionType · 'valuelist' | 'keyvaluelist'

When set, the config variable becomes multi-value. Not available for schedule, objectSelection, objectFieldMap, and jsonForm data types.

• "valuelist" — An ordered list of values.
• "keyvaluelist" — A list of key-value pairs.

permissionAndVisibilityType · 'customer' | 'embedded' | 'organization' · default: "customer"

Controls who can view and edit this config variable in the config wizard.

• "customer" — Customers can view and edit the value.
• "embedded" — Customers cannot view or update; value is set programmatically.
• "organization" — Customers cannot view or update; always uses the default value or is set by the organization.

visibleToOrgDeployer · boolean · default: "true"

Whether this config variable is visible to an organization deployer.

Show Type-specific fields

pickList · string[]

Required when dataType is "picklist". The list of selectable string values.

codeLanguage · 'json' | 'xml' | 'html'

Required when dataType is "code". The syntax highlighting language for the code editor.

timeZone · string

Optional timezone for dataType: "schedule" config variables (e.g., "America/New_York").

validationMode · ValidationMode

Validation mode for dataType: "jsonForm" config variables.

Return type

configVar · T

The same config variable definition object passed in, unchanged. The function is used for type inference.

Examples

String and boolean

import { configVar } from "@prismatic-io/spectral";

const apiUrl = configVar({
  stableKey: "api-url",
  dataType: "string",
  description: "Base URL of the target API.",
  defaultValue: "https://api.example.com",
});

const debugMode = configVar({
  stableKey: "debug-mode",
  dataType: "boolean",
  description: "Enable verbose logging.",
  defaultValue: false,
});

Related

• configPage() — The page that contains this config variable.
• connectionConfigVar() — For connection-type config variables.
• dataSourceConfigVar() — For data source-backed config variables.