Overview

Configure the app itself — its identity, default permissions, and what runs at install time.

A Twenty app’s config layer is what describes the app to the platform — its identity, the permissions it holds, and the code that runs during install or upgrade. These declarations don’t add new data shapes or runtime behavior; they tell Twenty who the app is and how to set it up.

┌────────────────────────────────────────────────────────┐
│ Application — identity, default role, variables,       │
│               marketplace metadata                     │
│                                                        │
│   ┌──────────────────────────────────────────────────┐ │
│   │ Role — what the app's logic functions can read   │ │
│   │ and write (referenced by Application)            │ │
│   └──────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────┘
                          │
                          ▼  (at install / upgrade time)
       ┌──────────────────────────────────┐
       │ Pre-install hook                 │  before metadata migration
       └──────────────────────────────────┘
       ┌──────────────────────────────────┐
       │ Post-install hook                │  after metadata migration
       └──────────────────────────────────┘
                          │
                          ▼  (at uninstall time)
       ┌──────────────────────────────────┐
       │ Uninstall hook                   │  before app removal
       └──────────────────────────────────┘

In this section

Application Config

defineApplication — identity, default role, variables, marketplace metadata.

Roles & Permissions

defineRole — declare what your app’s logic functions can read and write.

Install Hooks

definePreInstallLogicFunction, definePostInstallLogicFunction, and defineUninstallLogicFunction — back up data, seed defaults, validate upgrades, clean up on removal.

How the pieces relate

• Application is the entry point. Every app has exactly one defineApplication() call, and it points at one Role as its default.
• The Role controls what the app’s logic functions and front components can read and write. Follow least-privilege: only grant the permissions your code actually needs.
• Install Hooks run during install or upgrade — pre-install before the metadata migration (so it can refuse a risky upgrade), post-install after the migration (so it can seed default data against the new schema). The uninstall hook runs right before the app is removed, so it can clean up external resources while the app’s data is still readable.

Install hooks share the logic function runtime — same handler signature, same environment variables, same typed API client — but they’re declared with their own define functions and live outside the regular trigger model (HTTP, cron, database events).