Concepts

How apps work

An app is a collection of entities declared using defineEntity() functions from the twenty-sdk package. The CLI detects these declarations via AST analysis at build time and produces a manifest — a complete description of what your app adds to a workspace. These functions validate your configuration at build time and provide IDE autocompletion and type safety.

your-app/
├── src/
│   ├── application-config.ts    ← defineApplication (required, one per app)
│   ├── roles/                   ← defineRole
│   ├── objects/                 ← defineObject
│   ├── fields/                  ← defineField
│   ├── validation-rules/        ← defineValidationRule
│   ├── logic-functions/         ← defineLogicFunction
│   ├── front-components/        ← defineFrontComponent
│   ├── skills/                  ← defineSkill
│   ├── agents/                  ← defineAgent
│   ├── mcp-servers/             ← defineMcpServer
│   ├── views/                   ← defineView
│   ├── navigation-menu-items/   ← defineNavigationMenuItem
│   ├── settings-menu-items/     ← defineSettingsMenuItem
│   └── page-layouts/            ← definePageLayout
├── public/                      ← Static assets (images, icons)
└── package.json

File organization is up to you. Entity detection is AST-based — the SDK finds export default defineEntity(...) calls regardless of where the file lives. The folder structure above is a convention, not a requirement.

Entity types

Entity	Purpose	Docs
Application	App identity, default role, variables	Application Config
Role	Permission sets on objects and fields	Roles & Permissions
Object	Custom record types with fields	Objects
Field	Add fields to objects from other apps	Extending Objects
Relation	Bidirectional links between objects	Relations
Validation Rule	Conditions a record must meet before it can be saved	Validation Rules
Logic Function	Server-side TypeScript with triggers	Logic Functions
Skill	Reusable AI agent instructions	Skills & Agents
Agent	AI assistants with custom prompts	Skills & Agents
Workflow	Ready-made workflows with a trigger and steps	Workflows
Connection Provider	OAuth or custom sign-in for third-party accounts	Connections
Messaging Provider	Sends replies from an app’s message channels through a connection	Messaging Channels
MCP Server	External MCP server the workspace’s AI can call	Skills & Agents
View	Pre-configured record list views	Views
Navigation Menu Item	Custom sidebar entries	Navigation Menu Items
Page Layout	Tabs and widgets on a record’s detail page	Page Layouts
Front Component	Sandboxed React UI inside Twenty	Front Components
Shared Dependencies	Dependencies shared by the app’s front components, declared in package.json	Shared Dependencies
Command Menu Item	Quick actions and Cmd+K entries	Command Menu Items
Settings Menu Item	Entries in the app’s settings menu, each rendering a front component	Settings Menu Items

Sandboxing

Logic functions run in isolated Node.js processes on the server. They only access data through the typed API client, which acts either as the person who triggered the run or as the app itself. See Whose access a call uses.
Front components run in Web Workers using Remote DOM — sandboxed from the main page but rendering native DOM elements (not iframes). They communicate with Twenty via a message-passing host API.
Permissions are enforced at the API level. Two runtime tokens are injected, both derived from the role declared with defineApplicationRole(); the default one is narrowed further to what the triggering person can do whenever someone is behind the run.

App lifecycle

┌─────────────────────────────────────────────────────────┐
│ Development                                             │
│   twenty app init → twenty app dev (live sync)   │
├─────────────────────────────────────────────────────────┤
│ Build & Deploy                                          │
│   twenty app build → twenty app publish        │
├─────────────────────────────────────────────────────────┤
│ Install flow                                            │
│   upload → [pre-install] → metadata migration →         │
│   generate SDK → [post-install] → … → [uninstall]       │
├─────────────────────────────────────────────────────────┤
│ Publish                                                 │
│   npm publish → appears in Twenty marketplace           │
└─────────────────────────────────────────────────────────┘

twenty app dev — watches your source files and live-syncs changes to a connected Twenty server. After a successful sync, it regenerates the typed API client when the schema or installed generator package changed, or generated client files are missing or changed. To refresh types after changing the workspace in the UI, run twenty app generate-client.
twenty app build — compiles TypeScript, bundles logic functions and front components with esbuild, and produces a manifest.
Pre/post-install and uninstall hooks — optional functions that run during installation or right before removal. See Install Hooks for details.

Next steps

Config

Application identity, default role, and install and uninstall hooks.

Data

Objects, fields, and bidirectional relations.

Logic

Logic functions, skills, agents, connections, and messaging channels.

Layout

Views, navigation, page layouts, front components.

Operations

CLI, testing, remotes, CI, and publishing your app.

Developers

Apps

API

Self-Host

Contribute

UI Library

How apps work

Entity types

Sandboxing

App lifecycle

Next steps

​How apps work

​Entity types

​Sandboxing

​App lifecycle

​Next steps

How apps work

Entity types

Sandboxing

App lifecycle

Next steps