Skip to main content
This page documents the legacy settings API, which is deprecated. It keeps working for existing apps, but new apps should define settings in src/app/settings/ instead; see Workspace settings. To convert an existing app, use the folder structure migration guide.
The workspace settings schema defines the structure and types of the settings that users can configure for your app. This schema is used by useWorkspaceSettingsForm() to provide type-safe form components, ensuring that each component (like TextInput, NumberInput, or Toggle) can only reference fields with matching types in the schema (e.g., TextInput can only reference Settings.string() fields).

File Location

The settings schema must be defined in a file at src/app.settings.ts. This file location is required and cannot be changed.

Structure

app.settings.ts
All settings are workspace-level, meaning they apply to the entire workspace where your app is installed.

Available Setting Types

The Settings object provides the following types:

Settings.string()

Defines a string setting. Use this for text values like names, URLs, or identifiers.

Settings.boolean()

Defines a boolean setting. Use this for toggles, checkboxes, or on/off configurations.

Settings.number()

Defines a numeric setting. Use this for counts, durations, or other numerical values.

Complete Example

app.settings.ts

Using the Schema

Once you’ve defined your schema, you can use it in your workspace settings form:
workspace-settings.tsx