Application Config

Every app must have exactly one defineApplication call. It declares:

• Identity — universal identifier, display name, description.
• Permissions — which role its logic functions and front components run under.
• Variables (optional) — key–value pairs exposed to your code as environment variables.
• Pre-install / post-install hooks (optional) — see Logic Functions.

import { defineApplication } from 'twenty-sdk/define';

export default defineApplication({
  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
  displayName: 'My Twenty App',
  description: 'My first Twenty app',
  applicationVariables: {
    DEFAULT_RECIPIENT_NAME: {
      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
      description: 'Default recipient name for postcards',
      value: 'Jane Doe',
      isSecret: false,
    },
  },
});

Notes:

• universalIdentifier fields are deterministic IDs you own. Generate them once and keep them stable across syncs.
• applicationVariables become environment variables for your functions and front components (e.g., DEFAULT_RECIPIENT_NAME is available as process.env.DEFAULT_RECIPIENT_NAME).
• The default role is detected automatically from the role file marked with defineApplicationRole() — you do not need to reference it from defineApplication().
• Pre-install and post-install functions are detected automatically during the manifest build — you do not need to reference them in defineApplication().
• Passing defaultRoleUniversalIdentifier explicitly is still supported for backward compatibility, but is deprecated in favor of defineApplicationRole().

Default function role

The role declared with defineApplicationRole() controls what the app's logic functions and front components can access:

• The runtime token injected as TWENTY_APP_ACCESS_TOKEN is derived from this role.
• The typed API client is restricted to the permissions granted to that role.
• Follow least-privilege: declare only the permissions your functions need.

When you scaffold a new app, the CLI creates a starter role file at src/roles/default-role.ts. See Roles & Permissions for the full reference.

Marketplace metadata

If you plan to publish your app, these optional fields control how it appears in the marketplace: