Settings kinds and environment
Look up supported setting kinds, defaults, validation, and environment behavior.
Every application setting has a dotted key, kind, and default.
The kind determines the TypeScript value, validation, and administration control.
Definition fields
| Field | Required | Contract |
|---|---|---|
kind |
Yes | Determines the value type and validation |
default |
Yes | Value used when no persisted value or valid environment fallback exists |
label |
No | Label in administration forms; Cloud derives one from the key when omitted |
description |
No | Explanation shown to operators |
placeholder |
No | Input hint for string-like, number, and list settings |
envFallback |
No | Server-side function that returns a fallback value |
envBootstrap |
No | Server-side function that can create the initial persisted value |
template also accepts templateVars. enum requires options, an array of
{ value, label }. number accepts min and max.
Environment resolvers run in the server process. Do not expose their source or secret values to browser code.
Setting kinds
| Kind | Value | Validation |
|---|---|---|
string |
string |
Text |
text |
string |
Multiline text |
email |
string |
Empty or email address |
url |
string |
Empty or absolute URL |
secret |
string |
Encrypted at rest; redacted from administration responses |
image |
string |
Empty or absolute URL |
boolean |
boolean |
Boolean |
number |
number |
Finite number with optional min and max |
enum |
string |
One declared option |
string_list |
string[] |
Trimmed, unique values |
number_list |
number[] |
Unique positive integers |
cron |
string |
Five-field cron expression |
timezone |
string |
Empty or valid IANA time zone |
template |
string |
Valid Liquid template |
List inputs accept arrays or comma- and newline-separated text.
Setting key ownership
Use <app-id>.<name> for application settings.
Platform settings are declared once in Cloud. Application settings belong in
that application's defineApp({ settings }).
Registering the same key with a different kind, default, minimum, or maximum is an error.
Resolve a value
Cloud resolves a setting in this order:
- a valid encrypted database value;
envFallback;- the code default.
The public setting entry reports custom, env, or default as its source.
At startup, envBootstrap writes a custom value only when no stored row exists.
Unreadable and invalid rows stay unchanged. It runs again after the row is
removed. Use it only to import an existing deployment value into Cloud.
While a stored row is unreadable or invalid, reads use envFallback or the
default, never envBootstrap. Declare both when the environment value should
apply in that case, as app.url and gotenberg.url do.
See Keep the encryption key stable
before changing APP_SECRET.
Read and write values
Inside a request, use the frozen c.get("settings") snapshot.
Outside a request, use the typed app.settings API:
const limit = await app.settings.get("inventory.export_limit");
await app.settings.set("inventory.export_limit", 500);
await app.settings.remove("inventory.export_limit");Removing a custom value reveals the environment fallback or default.
Writes validate, encrypt, store, and invalidate the shared Valkey cache.
Separate process environment
Infrastructure variables such as DATABASE_URL, REDIS_URL, APP_SECRET,
APP_ID are not settings. Built-in services use port 3000; PORT is no longer runtime configuration.
See Runtime configuration for their deployment contract and Settings for usage.