Settings

Add typed per-presence settings with boolean, input, select, and slider controls.

What Settings Are

Settings let users customize how a presence behaves without editing code.

Supported Setting Types

Nowly supports boolean, input, select, and slider settings.

Field	Type	Description	Default
`boolean`	boolean	Toggle for enabled/disabled options.	-
`input`	string	Free-form text value.	-
`select`	string	One value selected from predefined options.	-
`slider`	number	Numeric value with optional min, max, and step.	-

Defining Settings

With CLI 1.7.0 or later, define settings in a default-exported settings.ts beside presence.ts. It takes complete priority over legacy inline Presence.Settings({ ... }) definitions: the two sources are not merged. An invalid file fails the build instead of falling back. Without the file, legacy inline definitions still work.

import type { PresenceSetting } from "@nowly/sdk"

export default {
  showButtons: {
    type: "boolean",
    default: true,
    label: {
      "en-US": "Show buttons"
    }
  }
} satisfies Record<string, PresenceSetting>

const presence = new Presence()

The CLI discovers settings.ts and registers defaults automatically: no settings import or Presence.Settings call is needed. It still generates settings.json for the extension. Saved user values take priority over defaults. Keep the file declarative: use JSON-compatible definitions, not browser or Node APIs. Read ctx.settings directly, or use getSetting<boolean>("showButtons") for an explicitly typed value.

Reading Settings

Use getSetting at runtime. Values come from the user's saved settings, falling back to the defaults from Presence.Settings. Live changes from the side panel arrive as SETTINGS_UPDATED and update the same map.

You can also read the current map from ctx.settings in UpdateData:

presence.on("UpdateData", async (ctx) => {
  const showButtons = await presence.getSetting<boolean>("showButtons")
  // same value: ctx.settings.showButtons
})

Localized Labels

Setting labels and descriptions use the same locale keys used in metadata.

Defaults

Choose safe defaults. A presence should work immediately after installation without requiring configuration.

Edit on GitHub

Command Palette