Building Custom Apps (Twenty SDK)
Relevant source files
The following files were used as context for generating this wiki page:
- packages/twenty-codex-plugin/references/concepts/how-apps-work.md
- packages/create-twenty-app/README.md
- packages/twenty-sdk/README.md
- packages/twenty-codex-plugin/references/develop-app/app-structure.md
- packages/twenty-codex-plugin/references/manage-app/cli-and-sync.md
- packages/twenty-codex-plugin/skills/develop-app/SKILL.md
- packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md
A Twenty app is a standalone npm package designed to extend a Twenty CRM instance. Unlike core modifications to the server, these apps live in their own source tree with a dedicated package.json and dependencies. They allow developers to introduce custom objects, fields, UI components, and automation logic into a workspace without altering the underlying CRM codebase.
Sources: packages/twenty-codex-plugin/references/concepts/how-apps-work.md:7-11
The development model utilizes a set of SDKs to define entities and interact with workspace data. Apps are built, published, and installed into running instances, where the instance loads app entities into its schema and renders front-end components within its isolated UI environment.
Sources: packages/twenty-codex-plugin/references/concepts/how-apps-work.md:13-15
Architecture and SDKs
The Twenty app architecture relies on two primary SDK packages that provide the registration functions and data access clients necessary for extension.
Core SDK Packages
| Package | Purpose | Primary Exports |
|---|---|---|
twenty-sdk | Defining entities and accessing runtime APIs | defineApplication, defineObject, defineField, defineFrontComponent, defineLogicFunction |
twenty-client-sdk | Querying and mutating workspace records | CoreApiClient (for records), Metadata (for definitions) |
Sources: packages/twenty-codex-plugin/references/concepts/how-apps-work.md:17-31
Data Flow and Rendering
Front components do not run as standalone React applications. Instead, they are rendered within a "Remote DOM" container inside the Twenty workspace UI. This isolation model restricts direct access to window or document globals. Components must use UI primitives provided by twenty-sdk/ui to ensure consistent styling and performance.
Sources: packages/twenty-codex-plugin/references/concepts/how-apps-work.md:75-85
The diagram above illustrates how definitions in an app's source code are synced and mounted into the corresponding engines within a Twenty instance.
Sources: packages/twenty-codex-plugin/references/concepts/how-apps-work.md:7-15
Development Lifecycle
The typical development loop follows a sequence of creation, development, synchronization, and validation.
1. Scaffolding
New projects are initialized using the create-twenty-app CLI. This tool sets up TypeScript, linting, and a preconfigured Twenty CLI. It also handles initial authentication against a local or remote Twenty instance.
Sources: packages/create-twenty-app/README.md:13-18
2. Entity Creation
Developers should use the twenty dev:add command to generate new entities. This ensures that file structures, SDK imports, and Universal Identifiers (UUIDs) are correctly boilerplate.
Sources: packages/twenty-codex-plugin/skills/develop-app/SKILL.md:68-73
3. Synchronization (Sync)
The yarn twenty dev --once command is the primary method for pushing changes to a remote instance. It builds the app and installs it on the active remote in a single step, updating the CRM schema and mounting UI components.
Sources: packages/twenty-codex-plugin/references/concepts/how-apps-work.md:58-62, packages/twenty-codex-plugin/references/manage-app/cli-and-sync.md:38-42
This sequence diagram shows the synchronization process where local code definitions are applied to a live CRM workspace.
Sources: packages/twenty-codex-plugin/references/manage-app/cli-and-sync.md:38-50
App Structure and Conventions
Twenty apps follow a strict directory structure and code organization rules to ensure maintainability and compatibility with the SDK's build process.
Directory Layout
src/application-config.ts: Entry point usingdefineApplication.src/objects/: Custom object definitions.src/fields/: Custom field definitions.src/logic-functions/: Backend-like automation logic.src/front-components/: UI components using React.src/constants/universal-identifiers.ts: Storage for stable UUIDs.public/: Static assets like logos and screenshots.
Sources: packages/twenty-codex-plugin/references/concepts/how-apps-work.md:87-105
Coding Rules
- One Export Per File: Every helper, type, and client file in
src/must export exactly one thing. If a type is shared, it must move tosrc/types/<name>.ts. - Naming: Filenames use
kebab-case. Conventional suffixes include.util.ts,.dto.ts,.service.ts, and.spec.ts. - Universal Identifiers: Stable UUIDs must be assigned to every entity. These must never change after the first sync as they are the primary key for entity identity across version bumps.
Sources: packages/twenty-codex-plugin/references/develop-app/app-structure.md:27-50, packages/twenty-codex-plugin/references/concepts/how-apps-work.md:108-111
CLI Reference
The twenty CLI manages the relationship between the local code and the CRM remotes.
| Command | Description |
|---|---|
twenty remote:add | Add a connection to a Twenty server |
twenty remote:list | Show all configured remotes |
twenty dev --once | One-shot build and synchronization |
twenty dev:add | Scaffold a new entity (object, view, component, etc.) |
twenty dev:build | Build the app package for release |
twenty app:publish | Publish to npm or a private registry |
Sources: packages/twenty-codex-plugin/references/manage-app/cli-and-sync.md:25-36, packages/twenty-sdk/README.md:25-35
Publishing and Metadata
Before publishing an app to the marketplace or npm, developers must configure marketplace metadata in defineApplication() and prepare visual assets.
Marketplace Metadata
Metadata fields include displayName, description, author, category, and links for support and terms. Visuals like logoUrl and screenshots must reference files residing in the app's public/ directory.
Sources: packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md:13-25
Visual Asset Requirements
- Logo: Legible at small sizes, simple geometry, stored in
public/. - Screenshots: Captured from real app surfaces after sync, using synthetic data only.
- Access: Files in
public/are served without authentication; sensitive data must never be placed here.
Sources: packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md:95-125
Summary
Building custom apps with the Twenty SDK enables developers to extend the CRM's core functionality through a version-controlled, modular approach. By defining entities as code and leveraging the isolated rendering model of front components, teams can build complex, workspace-specific features that are easily deployed and shared across different Twenty instances.
Sources: packages/twenty-codex-plugin/references/concepts/how-apps-work.md:7-15, packages/twenty-sdk/README.md:7-12