사전 준비
- Node.js 24.5+ — 여기에서 다운로드
- Yarn 4 — Corepack을 통해 Node.js와 함께 제공됩니다. 활성화하려면:
corepack enable - Docker — 여기에서 다운로드. 로컬 Twenty 서버를 실행하려면 필요합니다. 이미 다른 곳에서 Twenty가 실행 중이라면 건너뛰세요.
| 단계 | 하는 일 | 도구 | 결과 |
|---|---|---|---|
| 1. 스캐폴딩 | 앱의 소스 코드를 생성 | npx create-twenty-app | 디스크에 TypeScript 프로젝트 |
| 2. 서버 실행 | 동기화 대상으로 사용할 Twenty 서버 시작 | Docker + yarn twenty docker:start | 실행 중인 Twenty 인스턴스 |
| 3. 동기화 | 코드를 서버와 실시간 동기화 | yarn twenty dev | 변경 사항이 UI에 표시됨 |
1단계 — 프로젝트 스캐폴딩
템플릿에서 새 앱을 생성합니다:--display-name 및 --description을(를) 전달합니다(나중에 src/constants/universal-identifiers.ts에서 수정할 수도 있습니다). 이 명령은 my-twenty-app/에 시작용 application-config.ts, 기본 역할, CI/CD 워크플로, 통합 테스트가 포함된 TypeScript 프로젝트를 생성합니다.
이 단계를 마치면: 로컬 머신에 앱의 소스 코드가 준비됩니다. 아직 실행되지는 않았습니다 — 그건 2단계에서 진행합니다.
2단계 — 로컬 Twenty 서버 실행
앱은 동기화할 Twenty 서버가 필요합니다. 이 서버는 Docker에서 로컬로 실행되는 완전한 Twenty 인스턴스입니다 — UI, GraphQL API, PostgreSQL을 포함합니다. 로컬 코드가 해당 서버로 정의를 업로드하면 UI에 표시됩니다. Scaffolder가 이를 대신 시작합니다. Docker가 실행 중이면twentycrm/twenty-app-dev 이미지를 pull 하고, 포트 2020에서 시작한 다음, 미리 시드된 데모 워크스페이스(tim@apple.dev)에 대해 CLI를 인증합니다. 별도의 로그인은 필요하지 않습니다.
대신 기존 Twenty 서버에 연결하려면 --url \<your-server-url>을 전달하세요. 원격 서버는 OAuth로 인증합니다. 브라우저가 열리면 로그인한 뒤 Authorize를 클릭해 워크스페이스에 대한 CLI 액세스를 허용하면 됩니다. (로컬에서도 --authentication-method oauth로 OAuth를 선택할 수 있습니다. tim@apple.dev / tim@apple.dev로 로그인하세요.)
Docker가 설치되어 있지 않거나 실행 중이 아니면, 스캐폴더가 OS에 맞는 올바른 시작 명령을 알려줍니다. Docker가 올라오면
yarn twenty docker:start로 이어서 진행할 수 있습니다 — 다시 스캐폴딩할 필요는 없습니다.3단계 — 변경 사항 동기화
이 단계는 대부분의 시간을 보내게 될 내부 루프입니다.src/를 감시하며 변경될 때마다 다시 빌드하고, 결과를 서버에 동기화합니다. 파일을 수정해 저장하면 몇 초 안에 서버에 변경 사항이 반영됩니다. 터미널에서 실시간 상태 패널을 확인할 수 있습니다.
더 자세한 출력(빌드 로그, 동기화 요청, 오류 트레이스)을 보려면 --verbose를 추가하세요.
src/의 파일을 수정하면 UI에 반영됩니다.
CI 및 스크립트를 위한 1회성 동기화
워처 없이 동일한 파이프라인을 한 번만 실행하려면plan과 apply를 사용하세요:
| 명령 | 동작 | 사용 시점 |
|---|---|---|
yarn twenty dev | 소스 파일을 감시하고 변경될 때마다 다시 동기화합니다. 중지할 때까지 계속 실행됩니다. | 대화형 로컬 개발. |
yarn twenty apply | 한 번만 빌드 + 동기화를 수행하고, 성공 시 0, 실패 시 1로 종료합니다. 파괴적인 변경 사항에 대해 확인을 요청합니다(건너뛰려면 --force를 전달하세요). | CI, pre-commit 훅, AI 에이전트, 스크립트형 워크플로. |
yarn twenty plan | 메타데이터 변경 사항을 실제로 적용하지 않고 빌드하고 출력합니다. | 커밋하기 전에 동기화가 어떤 변경을 수행할지 살펴봅니다. |
plan에 대한 자세한 내용은 동기화 및 복구를 참고하세요.
yarn twenty dev --once 및 yarn twenty dev --once --dry-run은 yarn twenty apply 및 yarn twenty plan의 사용 중단된 별칭입니다.개발 모드 옵션
| 플래그 | 설명 |
|---|---|
--force | 확인 없이 파괴적인 변경 사항(삭제)을 적용합니다. |
--debounceMs \<ms> | 파일 변경 디바운스 지연 시간을 밀리초 단위로 설정합니다(기본값: 1000). |
--verbose / --debug | 자세한 빌드 로그, 동기화 요청, 오류 추적을 표시합니다. |
만들 수 있는 것
앱은 엔터티로 구성됩니다 — 각 엔터티는 하나의export default만 포함하는 TypeScript 파일로 정의됩니다:
| 엔터티 | 하는 일 |
|---|---|
| 객체 & 필드 | 사용자 정의 데이터 모델(Post Card, Invoice 등) 타입이 지정된 필드 포함 |
| 로직 함수 | HTTP 라우트, cron 스케줄 또는 데이터베이스 이벤트로 트리거되는 서버 측 TypeScript 코드 |
| 프론트 컴포넌트 | Twenty의 UI(사이드 패널, 위젯, 명령 메뉴) 안에 렌더링되는 React 컴포넌트 |
| 스킬 & 에이전트 | AI 기능 — 재사용 가능한 지침과 자율형 어시스턴트 |
| 뷰 & 내비게이션 | 사전 구성된 목록 뷰와 사이드바 메뉴 항목 |
| 페이지 레이아웃 | 탭과 위젯이 있는 사용자 정의 레코드 상세 페이지 |
다음 단계
설정
애플리케이션 ID, 기본 역할, 설치 훅, 공개 자산.
데이터
객체, 필드, 그리고 양방향 관계.
로직
로직 함수, 스킬, 에이전트, OAuth 연결.
레이아웃
뷰, 내비게이션, 페이지 레이아웃, 프론트 컴포넌트.
작업
CLI, 테스트, 리모트, CI, 그리고 앱 게시.