Settings model

Apps rarely ship with a single fixed configuration. A CRM might need different currency symbols per workspace, a ticketing app might hide certain actions for specific teams, and an integration app needs API credentials that must never reach the browser. Comindwork handles all of this through three settings levels - each targeting a different audience and taking effect at a different point in the app lifecycle.

Three settings levels

App system settings (compile-time)

System admins configure these settings for the entire platform. They apply to every workspace where the app is installed.

• Changing a system setting triggers redeployment (recompilation).
• Access in code via import - the value is preprocessed and baked in at compile time.
• System settings can update the app schema through the app-mutator (any aspect of the data model, actions, or layouts).

These are sometimes called deployment settings or system constants.

App workspace settings (runtime)

Workspace admins configure these settings for their own workspace. They take effect immediately - no redeployment required.

• Access in code via ComindView.getVars() (client-side) or ComindServer.getVars() (server-side), which returns the value for the current workspace at runtime.
• Each workspace can have a different value for the same setting.

warning

Do not use import to read workspace settings. An import resolves at compile time, so it returns the default value rather than the workspace-specific one. Always use ComindView.getVars() (client-side) or ComindServer.getVars() (server-side) for runtime settings. See Common mistakes for more pitfalls.

App personalization settings (runtime)

Individual end-users configure these settings for themselves. The scope can be per-user within a single workspace or per-user across all workspaces. Personalization settings control app-defined UI preferences and behavior customizations.

Settings types

Within each level, settings fall into three categories:

Type	Scope	Examples
Common settings	system-wide, every app	hide conversation/history in form, disable email notifications
App-specific variables	per-app, introduced by the developer	currency for a field, default assigned user, default record visibility
App-specific secrets	per-app, server-only (never sent to the browser)	auth tokens for external systems, passwords, API credentials

Customized settings are not part of the code. They cannot be pulled with npx comind pull. Changing a setting value does not change the app source - it only changes runtime behavior.

File structure

Settings files live inside the settings/ directory of your app package:

• settings/index.ts - exports AppSettings containing backlinks, mutations, and config.
• settings/app-mutator.ts - schema post-processing logic that runs based on system settings. Use this to add, remove, or modify fields, actions, or layouts at compile time.
• settings/secrets.ts - sensitive configuration using COMIND_SECRET_* environment variables. Secrets are resolved on the server only and are never included in client bundles.

All three files are optional. Add them as your app's configuration needs grow.

What you can customize

Data model

Settings can override field properties without modifying source code:

• Field caption, default value, prefix, mask, and help text
• Reference field target workspace and app
• User lookup restriction by group

Actions

Settings can override action properties:

• Action caption (the label on the button)
• Action visibility (show or hide per workspace)
• Help text displayed alongside the action
• Group names used in precondition checks

Operations and calculated fields

• Variables used in calculation expressions
• External service URLs
• Auth credentials for external service calls (via secrets)

Secrets

Secrets protect sensitive values such as API keys and passwords. Define them in settings/secrets.ts using environment variables prefixed with COMIND_SECRET_:

export const secrets = {
  apiKey: process.env.COMIND_SECRET_API_KEY,
  servicePassword: process.env.COMIND_SECRET_SVC_PASSWORD,
};

Secrets are resolved on the server and are never sent to the browser. Do not import secret values with a regular import in client-side code - that would embed the value in the browser bundle. See Common mistakes for details.

note

Secret values are currently stored as plain-text environment variables. Treat the server environment as a trusted boundary and restrict access to deployment configurations accordingly.

Key takeaways

• System settings change the compiled schema. Use import and the app-mutator.
• Workspace settings change runtime behavior per workspace. Use ComindView.getVars() or ComindServer.getVars().
• Personalization settings let end-users tweak their own experience.
• Secrets stay on the server. Use COMIND_SECRET_* env vars and settings/secrets.ts.
• Settings live outside the code - they are not version-controlled and cannot be pulled.