메인 콘텐츠로 건너뛰기
Twenty 앱은 사용자 정의 객체, 로직, UI 컴포넌트 및 AI 기능으로 워크스페이스를 확장하는 TypeScript 패키지입니다. 앱은 Twenty 플랫폼에서 완전한 샌드박싱과 권한 제어 하에 실행됩니다.

​
앱 작동 방식

앱은 twenty-sdk 패키지의 defineEntity() 함수를 사용해 선언된 엔티티의 모음입니다. SDK는 빌드 시점에 AST 분석을 통해 이러한 선언을 감지하고, 앱이 워크스페이스에 추가하는 내용을 완전하게 설명한 매니페스트를 생성합니다. 이 함수들은 빌드 시점에 구성을 검증하고 IDE 자동 완성과 타입 안정성을 제공합니다. 
your-app/
├── src/
│   ├── application-config.ts    ← defineApplication (required, one per app)
│   ├── roles/                   ← defineRole
│   ├── objects/                 ← defineObject
│   ├── fields/                  ← defineField
│   ├── logic-functions/         ← defineLogicFunction
│   ├── front-components/        ← defineFrontComponent
│   ├── skills/                  ← defineSkill
│   ├── agents/                  ← defineAgent
│   ├── views/                   ← defineView
│   ├── navigation-menu-items/   ← defineNavigationMenuItem
│   └── page-layouts/            ← definePageLayout
├── public/                      ← Static assets (images, icons)
└── package.json
파일 구성은 사용자의 선택입니다. 엔티티 감지는 AST 기반이며 — 파일 위치와 관계없이 SDK가 export default defineEntity(...) 호출을 찾습니다. 위의 폴더 구조는 관례이며 필수 사항은 아닙니다.

​
엔티티 유형

엔티티목적문서
애플리케이션앱 식별, 기본 역할, 변수Application Config
역할객체와 필드에 대한 권한 세트Roles & Permissions
객체필드가 있는 사용자 정의 레코드 타입Objects
필드다른 앱의 객체에 필드를 추가Extending Objects
관계객체 간 양방향 링크Relations
로직 함수트리거가 있는 서버 측 TypeScript로직 함수
스킬재사용 가능한 AI 에이전트 지침스킬 및 에이전트
에이전트사용자 지정 프롬프트를 사용하는 AI 에이전트스킬 및 에이전트
연결 제공자서드파티 API용 OAuth 자격 증명Connections
뷰사전 구성된 레코드 목록 뷰Views
내비게이션 메뉴 항목사용자 정의 사이드바 항목Navigation Menu Items
페이지 레이아웃레코드 상세 페이지의 탭과 위젯Page Layouts
프런트 컴포넌트Twenty 내부의 샌드박스 React UI프런트 컴포넌트
명령 메뉴 항목빠른 작업 및 Cmd+K 항목Command Menu Items

​
샌드박싱

  • 로직 함수는 서버의 격리된 Node.js 프로세스에서 실행됩니다. 이들은 앱의 역할 권한 범위로 제한된 타입이 지정된 API 클라이언트를 통해서만 데이터에 접근합니다.
  • 프런트 컴포넌트는 Remote DOM을 사용하는 Web Worker에서 실행됩니다 — 메인 페이지와는 샌드박스로 격리되어 있지만 네이티브 DOM 요소를 렌더링합니다(iframe이 아님). 이들은 메시지 전달 호스트 API를 통해 Twenty와 통신합니다.
  • 권한은 API 수준에서 강제 적용됩니다. 런타임 토큰(TWENTY_APP_ACCESS_TOKEN)은 defineApplication()에 정의된 역할에서 파생됩니다.

​
앱 라이프사이클

┌─────────────────────────────────────────────────────────┐
│ Development                                             │
│   npx create-twenty-app → yarn twenty dev (live sync)   │
├─────────────────────────────────────────────────────────┤
│ Build & Deploy                                          │
│   yarn twenty dev:build → yarn twenty app:publish        │
├─────────────────────────────────────────────────────────┤
│ Install flow                                            │
│   upload → [pre-install] → metadata migration →         │
│   generate SDK → [post-install]                         │
├─────────────────────────────────────────────────────────┤
│ Publish                                                 │
│   npm publish → appears in Twenty marketplace           │
└─────────────────────────────────────────────────────────┘
  • yarn twenty dev — 소스 파일을 감시하고 연결된 Twenty 서버로 변경 사항을 실시간 동기화합니다. 스키마가 변경되면 타입이 지정된 API 클라이언트가 자동으로 재생성됩니다.
  • yarn twenty dev:build — TypeScript를 컴파일하고, 로직 함수와 프런트 컴포넌트를 esbuild로 번들링하며, 매니페스트를 생성합니다.
  • 사전/사후 설치 훅 — 설치 중에 실행되는 선택적 함수입니다. 자세한 내용은 Install Hooks를 참조하세요.

​
다음 단계

설정

애플리케이션 식별, 기본 역할, 설치 훅.

데이터

객체, 필드, 양방향 관계.

로직

로직 함수, 스킬, 에이전트, OAuth 연결.

레이아웃

뷰, 내비게이션, 페이지 레이아웃, 프런트 컴포넌트.

작업

CLI, 테스트, 리모트, CI, 앱 게시.