개념 - Twenty Documentation

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] → … → [uninstall]       │
├─────────────────────────────────────────────────────────┤
│ Publish                                                 │
│   npm publish → appears in Twenty marketplace           │
└─────────────────────────────────────────────────────────┘

yarn twenty dev — 소스 파일을 감시하고 연결된 Twenty 서버로 변경 사항을 실시간 동기화합니다. 스키마가 변경되면 타입이 지정된 API 클라이언트가 자동으로 재생성됩니다.
yarn twenty dev:build — TypeScript를 컴파일하고, 로직 함수와 프런트 컴포넌트를 esbuild로 번들링하며, 매니페스트를 생성합니다.
사전/사후 설치 및 제거 훅 — 설치 중이거나 제거 직전에 실행되는 선택적 함수입니다. 자세한 내용은 Install Hooks를 참조하세요.

다음 단계

설정

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

데이터

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

로직

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

레이아웃

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

작업

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

개요

앱

API

셀프 호스팅

기여

개념

앱 작동 방식

엔티티 유형

샌드박싱

앱 라이프사이클

다음 단계

설정

데이터

로직

레이아웃

작업

​앱 작동 방식

​엔티티 유형

​샌드박싱

​앱 라이프사이클

​다음 단계

설정

데이터

로직

레이아웃

작업

앱 작동 방식

엔티티 유형

샌드박싱

앱 라이프사이클

다음 단계