Front-Component Renderer

Relevant source files

The following files were used as context for generating this wiki page:

• packages/twenty-codex-plugin/references/develop-app/front-components.md
• packages/twenty-codex-plugin/references/develop-app/standalone-pages.md
• packages/twenty-codex-plugin/references/concepts/how-apps-work.md
• packages/twenty-codex-plugin/references/develop-app/layout.md
• packages/twenty-codex-plugin/references/design/front-component-ui.md
• packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js

The Front-Component Renderer is a specialized system within Twenty designed to render custom UI components defined by applications. It utilizes a Remote DOM model to bridge the gap between application-defined code and the host environment, allowing developers to extend the CRM's interface with custom widgets, record-page tabs, and standalone operational pages.

The renderer handles the mounting and lifecycle of components registered via the SDK, ensuring they have access to workspace data, UI primitives, and host-level actions like navigation and snackbars. By providing a unified rendering shell, it maintains a consistent "native" feel while executing decoupled application logic.

Sources: references/concepts/how-apps-work.md, references/develop-app/front-components.md:10-15

Architecture and Data Flow

The rendering architecture relies on a clear separation between the host (Twenty) and the remote (the App's Front Component). Components are registered using a universal identifier (UUID) and are served through the SDK's rendering pipeline.

Remote DOM Model

Front components do not interact with the browser's DOM directly. Instead, they use a Remote DOM abstraction. Developers are prohibited from calling react-dom/client directly; the SDK renderer manages the mounting process. This allows for a secure, sandboxed rendering environment where components can be updated and synced without requiring full system reloads.

Sources: references/concepts/how-apps-work.md, references/develop-app/front-components.md:17-19, references/develop-app/standalone-pages.md:195-200

Component Lifecycle Flow

The following diagram illustrates how a Front Component is resolved and rendered when a user navigates to a custom surface.

The sequence of events from registration to user interaction.
Sources: references/develop-app/standalone-pages.md:12-18, references/develop-app/front-components.md:10-15

Component Registration and Usage

Applications register their UI surfaces using the defineFrontComponent function. This registration includes a stable universalIdentifier, a name, and the React component itself.

Registration Field	Type	Description
universalIdentifier	UUID	The stable unique ID used to reference the component in layouts.
name	string	A human-readable identifier for the component.
description	string	A short summary of the component's purpose.
component	ReactComponent	The actual UI implementation.

Sources: references/develop-app/front-components.md:10-22

Placement and Widgets

Front components are typically rendered inside Widgets within a PAGE_LAYOUT. For standalone pages, a FRONT_COMPONENT widget type is used with PageLayoutTabLayoutMode.CANVAS to fill the available screen area.

The interaction between the host environment and the remote component during initialization.
Sources: references/develop-app/standalone-pages.md:12-18, references/develop-app/front-components.md:38-40

Runtime Environment and SDKs

The Front-Component Renderer provides a specific runtime environment with pre-configured SDKs.

SDK Packages

• twenty-sdk/front-component: Provides hooks for host interactions (navigation, snackbars, record context).
• twenty-client-sdk/core: Used for direct workspace data access (querying and mutating records).
• twenty-sdk/ui: A library of UI primitives (Button, Chip, Status, Tag) and theme tokens.

Sources: references/develop-app/front-components.md:26-32, references/concepts/how-apps-work.md

Theme and Styling

The renderer wraps components in a ThemeProvider that provides access to themeCssVariables. This ensures that custom components automatically inherit Twenty's visual language, including spacing, colors, and typography.

Sources: references/develop-app/front-components.md:32-35, references/design/front-component-ui.md:28-35

Surface Types

The renderer supports several distinct UI surfaces within the CRM.

Surface Type	Page Layout Type	Typical Use Case
Standalone Page	STANDALONE_PAGE	Operational consoles, maps, or planners not tied to a specific record.
Record Page	RECORD_PAGE	Custom tabs or widgets displayed on a specific object record (e.g., Company/Person).
Command/Side Panel	N/A	Focused forms or background actions triggered from the command menu.

Sources: references/develop-app/standalone-pages.md:21-27, references/develop-app/layout.md

Standalone Page Configuration

To render a full-page custom UI, the application must define a navigation item linked to a page layout.

// src/page-layouts/mission-control.page-layout.ts
export default definePageLayout({
  universalIdentifier: MISSION_CONTROL_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
  type: 'STANDALONE_PAGE',
  tabs: [{
    layoutMode: PageLayoutTabLayoutMode.CANVAS,
    widgets: [{
      type: 'FRONT_COMPONENT',
      gridPosition: { row: 0, column: 0, rowSpan: 12, columnSpan: 12 },
      configuration: {
        configurationType: 'FRONT_COMPONENT',
        frontComponentUniversalIdentifier: MISSION_CONTROL_FRONT_COMPONENT_UUID,
      },
    }],
  }],
});

Sources: references/develop-app/standalone-pages.md:65-88

Error Handling and Verification

The renderer includes built-in safeguards and state management. Components are expected to handle five key states: Loading, Empty, Error, Disabled, and Success.

Runtime Safety Checks

• FrontComponent error: Occurs if the component fails to mount or throws an unhandled exception.
• Hard Refresh Requirement: Some changes to component source or registration require a hard refresh to clear cached definitions.
• Validation Checklist: Before production sync, components should pass yarn twenty dev:typecheck and yarn lint.

Sources: scripts/validators/cross-doc-contracts.js:80-90, references/develop-app/front-components.md:73-80, references/design/front-component-ui.md:155-165

Summary

The Front-Component Renderer is the bridge between Twenty's core CRM and application-specific extensions. By leveraging the Remote DOM and a standardized set of SDKs, it allows for deep UI customization while maintaining the security and performance of the host system. It enables developers to create everything from simple data widgets to complex, full-screen operational tools that feel native to the Twenty platform.