Frontend Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Twenty's frontend architecture is built as a modern, high-performance React application designed for extensibility and consistency. It serves as the primary interface for users to interact with CRM data, providing a native-feeling experience that supports both core product features and custom extensions through a modular "App" system.
The architecture emphasizes a clear separation between the core product app (twenty-front) and the extension ecosystem. Extensions, known as Twenty Apps, utilize a specialized "Front Component" system that allows for the injection of custom UI surfaces directly into the CRM, ranging from small record-page widgets to full-screen standalone tools.
Sources: CLAUDE.md, PRODUCT.md, packages/twenty-codex-plugin/references/concepts/how-apps-work.md
Core Tech Stack and State Management
The frontend is built with React 18 and TypeScript, enforcing strict types and functional components. It operates within an Nx monorepo workspace using Yarn 4 for package management.
Tech Stack Components
| Layer | Technology |
|---|---|
| Framework | React 18 |
| Language | TypeScript (Strict) |
| State Management | Jotai (Atoms), Apollo Client (GraphQL Cache) |
| Styling | Linaria (zero-runtime CSS-in-JS) |
| Internationalization | Lingui |
| Icons | @tabler/icons-react |
| Headless UI | @radix-ui/react-* |
Sources: CLAUDE.md, PRODUCT.md
State Management Patterns
The architecture utilizes Jotai for global state management through primitive atoms, derived selectors, and atom families for dynamic collections. Component-specific logic is handled via standard React hooks, while external data synchronization is managed by Apollo Client. The architecture follows a "props down, events up" unidirectional data flow.
Sources: CLAUDE.md
Front Component System
A critical part of the architecture is the Front Component system, which enables external extensions to render UI within the Twenty environment. These components are registered and served through a "Remote DOM" model.
Component Registration and Rendering
Front components are defined using the defineFrontComponent utility from the twenty-sdk/define package. They are characterized by a Universal Identifier (UUID) that ensures stable referencing across different environments.
The diagram shows how a Twenty App defines UI using the SDK to interact with the server and render within the main platform.
Sources: packages/twenty-codex-plugin/references/develop-app/front-components.md, packages/twenty-codex-plugin/references/concepts/how-apps-work.md
Data Access and Hooks
Front components interact with the platform using specialized SDKs:
twenty-sdk/front-component: Provides hooks for host navigation, snackbars, and application variables.twenty-client-sdk/core: Facilitates querying and mutating workspace records.twenty-client-sdk/metadata: Provides access to object and field definitions.
Sources: packages/twenty-codex-plugin/references/develop-app/front-components.md, packages/twenty-codex-plugin/references/develop-app/standalone-pages.md
Design System and UI Doctrine
The frontend follows an Editorial, Founder-led, and Considered design philosophy. It avoids common "SaaS" patterns like bento grids or heavy gradients, preferring typographic hierarchy and restrained palettes.
Visual Tokens
Styling is strictly governed by themeCssVariables, which include:
- Spacing: Grid-based tokens (e.g.,
themeCssVariables.spacing[2]). - Typography: Semantic tokens for weight and size (e.g.,
themeCssVariables.font.size.md). - Radius: Standardized tokens like
border.radius.smfor controls andborder.radius.mdfor panels. - Colors: Tinted neutrals based on OKLCH CSS variables.
Sources: PRODUCT.md, packages/twenty-codex-plugin/references/design/front-component-ui.md
Layout Patterns
Standardized layout constants ensure a native feel:
- Compact Controls: Height governed by
themeCssVariables.spacing[6]. - Dense Rows: Height governed by
themeCssVariables.spacing[8]. - Toolbars: Minimum height of
themeCssVariables.spacing[10].
Sources: packages/twenty-codex-plugin/references/design/front-component-ui.md
Custom Pages and Navigation
Custom UI can be integrated into the navigation through Standalone Pages and Page Layouts.
Standalone Page Assembly
A standalone page is rendered by connecting a FRONT_COMPONENT widget to a STANDALONE_PAGE layout, which is then linked to a NavigationMenuItem.
The sequence diagram illustrates the resolution of a sidebar navigation item to a custom standalone page experience.
Sources: packages/twenty-codex-plugin/references/develop-app/standalone-pages.md
Navigation Entity Types
| Entity | Description |
|---|---|
RECORD_PAGE | Layouts for specific object records (e.g., Company detail). |
STANDALONE_PAGE | Full-screen routes not tied to a single record. |
DASHBOARD | Metric composition surfaces. |
Sources: packages/twenty-codex-plugin/references/develop-app/standalone-pages.md, packages/twenty-codex-plugin/references/develop-app/layout.md
Development Principles
The architecture enforces strict coding standards to maintain maintainability:
- Functional Components: Class components are prohibited.
- Named Exports: Default exports are forbidden to improve refactoring and discovery.
- File Lengths: Components should remain under 300 lines; services under 500 lines.
- No Abbreviations: Variable names must be descriptive (e.g.,
fieldMetadatainstead offm). - Composition over Inheritance: React's composition model is used for UI reuse.
Sources: CLAUDE.md
Twenty's frontend architecture balances a robust, opinionated core with a flexible extension system. By strictly leveraging theme tokens, functional React patterns, and a specialized SDK for remote component rendering, the platform ensures that third-party extensions feel like native parts of the product while maintaining technical isolation and performance.