사전 준비
- Node.js 24.5+ — 여기에서 다운로드
- Yarn 4 — Corepack을 통해 Node.js와 함께 제공됩니다. 활성화하려면:
corepack enable - Docker — 여기에서 다운로드. 로컬 Twenty 서버를 실행하려면 필요합니다. 이미 다른 곳에서 Twenty가 실행 중이라면 건너뛰세요.
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를 사용하세요:
모든 모드에는 인증된 리모트가 필요합니다.
plan에 대한 자세한 내용은 동기화 및 복구를 참고하세요.
yarn twenty dev --once 및 yarn twenty dev --once --dry-run은 yarn twenty apply 및 yarn twenty plan의 사용 중단된 별칭입니다.개발 모드 옵션
만들 수 있는 것
앱은 엔터티로 구성됩니다 — 각 엔터티는 하나의export default만 포함하는 TypeScript 파일로 정의됩니다:
전체 참고 문서: 개념.
다음 단계
설정
애플리케이션 ID, 기본 역할, 설치 및 제거 훅, 공개 자산.
데이터
객체, 필드, 그리고 양방향 관계.
로직
로직 함수, 스킬, 에이전트, OAuth 연결.
레이아웃
뷰, 내비게이션, 페이지 레이아웃, 프론트 컴포넌트.
작업
CLI, 테스트, 리모트, CI, 그리고 앱 게시.