i18n - docs translations (#21789)
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
This commit is contained in:
github-actions[bot]
committed by
GitHub
GitHub
parent
22baf2c6c5
commit
2b3b2362db
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: 개념
|
||||
description: Twenty 앱이 작동하는 방식 — 엔티티 모델, 샌드박싱, 설치 라이프사이클.
|
||||
icon: sitemap
|
||||
---
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
<Note>
|
||||
**파일 구성은 사용자의 선택입니다.** 엔티티 감지는 AST 기반이며 — 파일 위치와 관계없이 SDK가 `export default defineEntity(...)` 호출을 찾습니다. 위의 폴더 구조는 관례이며 필수 사항은 아닙니다.
|
||||
</Note>
|
||||
|
||||
## 엔티티 유형
|
||||
|
||||
| 엔티티 | 목적 | 문서 |
|
||||
| --------------- | ------------------------- | ----------------------------------------------------------------------------- |
|
||||
| **애플리케이션** | 앱 식별, 기본 역할, 변수 | [Application Config](/l/ko/developers/extend/apps/config/application) |
|
||||
| **역할** | 객체와 필드에 대한 권한 세트 | [Roles & Permissions](/l/ko/developers/extend/apps/config/roles) |
|
||||
| **객체** | 필드가 있는 사용자 정의 레코드 타입 | [Objects](/l/ko/developers/extend/apps/data/objects) |
|
||||
| **필드** | 다른 앱의 객체에 필드를 추가 | [Extending Objects](/l/ko/developers/extend/apps/data/extending-objects) |
|
||||
| **관계** | 객체 간 양방향 링크 | [Relations](/l/ko/developers/extend/apps/data/relations) |
|
||||
| **로직 함수** | 트리거가 있는 서버 측 TypeScript | [로직 함수](/l/ko/developers/extend/apps/logic/logic-functions) |
|
||||
| **스킬** | 재사용 가능한 AI 에이전트 지침 | [스킬 및 에이전트](/l/ko/developers/extend/apps/logic/skills-and-agents) |
|
||||
| **에이전트** | 사용자 지정 프롬프트를 사용하는 AI 에이전트 | [스킬 및 에이전트](/l/ko/developers/extend/apps/logic/skills-and-agents) |
|
||||
| **연결 제공자** | 서드파티 API용 OAuth 자격 증명 | [Connections](/l/ko/developers/extend/apps/logic/connections) |
|
||||
| **뷰** | 사전 구성된 레코드 목록 뷰 | [Views](/l/ko/developers/extend/apps/layout/views) |
|
||||
| **내비게이션 메뉴 항목** | 사용자 정의 사이드바 항목 | [Navigation Menu Items](/l/ko/developers/extend/apps/layout/navigation-menu-items) |
|
||||
| **페이지 레이아웃** | 레코드 상세 페이지의 탭과 위젯 | [Page Layouts](/l/ko/developers/extend/apps/layout/page-layouts) |
|
||||
| **프런트 컴포넌트** | Twenty 내부의 샌드박스 React UI | [프런트 컴포넌트](/l/ko/developers/extend/apps/layout/front-components) |
|
||||
| **명령 메뉴 항목** | 빠른 작업 및 Cmd+K 항목 | [Command Menu Items](/l/ko/developers/extend/apps/layout/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](/l/ko/developers/extend/apps/config/install-hooks)를 참조하세요.
|
||||
|
||||
## 다음 단계
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="설정" icon="screwdriver-wrench" href="/l/ko/developers/extend/apps/config/overview">
|
||||
애플리케이션 식별, 기본 역할, 설치 훅.
|
||||
</Card>
|
||||
<Card title="데이터" icon="database" href="/l/ko/developers/extend/apps/data/overview">
|
||||
객체, 필드, 양방향 관계.
|
||||
</Card>
|
||||
<Card title="로직" icon="bolt" href="/l/ko/developers/extend/apps/logic/overview">
|
||||
로직 함수, 스킬, 에이전트, OAuth 연결.
|
||||
</Card>
|
||||
<Card title="레이아웃" icon="table-columns" href="/l/ko/developers/extend/apps/layout/overview">
|
||||
뷰, 내비게이션, 페이지 레이아웃, 프런트 컴포넌트.
|
||||
</Card>
|
||||
<Card title="작업" icon="rocket" href="/l/ko/developers/extend/apps/operations/overview">
|
||||
CLI, 테스트, 리모트, CI, 앱 게시.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: 로컬 서버
|
||||
description: 로컬 Twenty Docker 서버를 관리합니다. 시작, 중지, 업그레이드, 병렬 테스트 인스턴스 및 수동 SDK 설정을 수행할 수 있습니다.
|
||||
icon: server
|
||||
---
|
||||
|
||||
## 로컬 서버 관리
|
||||
|
||||
로컬 Twenty 컨테이너를 제어하려면 `yarn twenty docker:*`를 사용하세요:
|
||||
|
||||
| 명령 | 하는 일 |
|
||||
| -------------------------------------- | ----------------------------- |
|
||||
| `yarn twenty docker:start` | 서버 시작(필요하면 이미지를 가져옴) |
|
||||
| `yarn twenty docker:start 2.2.0` | 특정 서버 버전을 시작합니다 |
|
||||
| `yarn twenty docker:start --port 3030` | 사용자 지정 포트에서 시작 |
|
||||
| `yarn twenty docker:stop` | 서버 중지(데이터 보존) |
|
||||
| `yarn twenty docker:status` | URL, 버전 및 로그인 자격 증명 표시 |
|
||||
| `yarn twenty docker:logs` | 서버 로그 스트리밍 |
|
||||
| `yarn twenty docker:reset` | 데이터를 모두 삭제하고 새로 시작 |
|
||||
| `yarn twenty docker:upgrade` | `twenty-app-dev` 최신 이미지를 가져오기 |
|
||||
| `yarn twenty docker:upgrade 2.2.0` | 특정 버전으로 업그레이드합니다 |
|
||||
|
||||
데이터는 두 개의 Docker 볼륨에 저장되어 재시작 후에도 유지됩니다(PostgreSQL은 `twenty-app-dev-data`, 파일은 `twenty-app-dev-storage`). `reset`을 사용하여 모든 것을 삭제하세요.
|
||||
|
||||
## 서버 버전 고정하기
|
||||
|
||||
버전을 전달하지 않으면, `docker:start`는 `package.json`의 앱 `engines.twenty` 범위에서 버전을 결정합니다. 이 범위는 앱이 설치될 때 서버가 검증에 사용하는 범위와 같습니다. 이 명령은 해당 범위를 만족하는 가장 최근에 게시된 `twenty-app-dev` 이미지를 시작하며, 해당 필드가 없거나 게시된 버전이 범위와 일치하지 않으면 `latest`로 대체합니다:
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
"engines": {
|
||||
"twenty": ">=2.2.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
단일 실행에서만 범위를 재정의하려면 버전을 명시적으로 전달하세요: `yarn twenty docker:start 2.3.0`. 이미 다른 버전에서 컨테이너가 존재하는 경우, `docker:start`는 해당 컨테이너를 제자리에서 업그레이드합니다(데이터 볼륨을 유지하면서 컨테이너를 재생성).
|
||||
|
||||
## 서버 이미지 업그레이드
|
||||
|
||||
`yarn twenty docker:upgrade`는 최신 이미지를 가져와 다이제스트를 비교하고, 실제로 변경 사항이 있을 때만 컨테이너를 다시 생성합니다. 데이터 볼륨은 유지되며 — 컨테이너만 교체됩니다. 새 이미지를 가져왔고 컨테이너가 실행 중이었다면, 업그레이드는 자동으로 새 컨테이너를 시작합니다; 이후 `yarn twenty docker:start`를 실행하여 상태가 정상(healthy)이 될 때까지 기다리세요.
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty docker:upgrade # Latest
|
||||
yarn twenty docker:upgrade 2.2.0 # Specific version
|
||||
```
|
||||
|
||||
`yarn twenty docker:status`로 실행 중인 버전을 확인하세요(컨테이너에 포함된 `APP_VERSION`을 표시합니다).
|
||||
|
||||
## 병렬 테스트 인스턴스 실행
|
||||
|
||||
완전히 분리된 두 번째 인스턴스를 관리하려면 모든 `docker:*` 명령에 `--test`를 전달하세요 — 메인 개발 데이터를 건드리지 않고 통합 테스트를 실행하거나 실험할 때 유용합니다:
|
||||
|
||||
| 명령 | 하는 일 |
|
||||
| ----------------------------------- | ---------------------------- |
|
||||
| `yarn twenty docker:start --test` | 테스트 인스턴스를 시작합니다(기본 포트는 2021) |
|
||||
| `yarn twenty docker:stop --test` | 중지 |
|
||||
| `yarn twenty docker:status --test` | 상태 표시 |
|
||||
| `yarn twenty docker:logs --test` | 로그 스트리밍 |
|
||||
| `yarn twenty docker:reset --test` | 데이터 삭제 |
|
||||
| `yarn twenty docker:upgrade --test` | 이미지 업그레이드 |
|
||||
|
||||
테스트 인스턴스는 자체 컨테이너(`twenty-app-dev-test`), 전용 볼륨(`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`), 구성으로 실행되며, 메인 인스턴스와 충돌 없이 나란히 실행됩니다. `--test`를 `--port`와 함께 사용하여 2021을 재정의하세요.
|
||||
|
||||
## 수동 설정(스캐폴더 없이)
|
||||
|
||||
기존 프로젝트에 SDK를 추가하는 경우 스캐폴더 단계를 건너뜁니다:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn add twenty-sdk twenty-client-sdk
|
||||
```
|
||||
|
||||
`package.json`에 스크립트를 추가하세요:
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
"scripts": {
|
||||
"twenty": "twenty"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
이제 `yarn twenty dev`, `yarn twenty docker:start` 등을 실행할 수 있습니다.
|
||||
|
||||
<Note>
|
||||
`twenty-sdk`를 전역으로 설치하지 마세요 — 각 프로젝트에 고정하여 각 앱이 자체 버전을 사용하도록 하세요.
|
||||
</Note>
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: 프로젝트 구조
|
||||
description: 스캐폴딩된 Twenty 앱 안에 무엇이 들어 있는지 — 파일, 폴더, 그리고 각 요소의 역할을 설명합니다.
|
||||
icon: folder-tree
|
||||
---
|
||||
|
||||
`npx create-twenty-app`으로 생성한 새 앱은 다음과 같은 구조입니다:
|
||||
|
||||
```text filename="my-twenty-app/"
|
||||
my-twenty-app/
|
||||
package.json
|
||||
src/
|
||||
application-config.ts # Required — your app's entry point
|
||||
default-role.ts # Permissions for logic functions
|
||||
constants/
|
||||
universal-identifiers.ts # Auto-generated UUIDs and metadata
|
||||
__tests__/
|
||||
setup-test.ts
|
||||
app-install.integration-test.ts
|
||||
.github/workflows/ci.yml # GitHub Actions
|
||||
public/ # Static assets
|
||||
vitest.config.ts # Test runner config
|
||||
tsconfig.json, tsconfig.spec.json
|
||||
.nvmrc, .yarnrc.yml, .oxlintrc.json
|
||||
README.md, LLMS.md
|
||||
```
|
||||
|
||||
## 주요 파일
|
||||
|
||||
| 파일 / 폴더 | 목적 |
|
||||
| ---------------------------------------- | -------------------------------- |
|
||||
| `src/application-config.ts` | **필수.** 앱의 기본 구성 파일입니다. |
|
||||
| `src/default-role.ts` | 로직 함수가 접근할 수 있는 범위를 제어하는 기본 역할 |
|
||||
| `src/constants/universal-identifiers.ts` | 자동 생성된 UUID와 앱 메타데이터(표시 이름, 설명). |
|
||||
| `src/__tests__/` | 통합 테스트(설정 + 예제 테스트). |
|
||||
| `public/` | 앱과 함께 제공되는 정적 에셋(이미지, 폰트). |
|
||||
|
||||
<Note>
|
||||
**파일 구성은 사용자의 선택입니다.** 위 폴더들은 관례일 뿐이며, SDK는 파일 위치와 관계없이 `export default defineEntity(...)` 호출에 대한 AST 분석을 통해 엔티티를 감지합니다.
|
||||
</Note>
|
||||
|
||||
## 의존성
|
||||
|
||||
두 Twenty SDK 패키지는 `dependencies`가 아니라 `devDependencies` 아래에 속해야 합니다.
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
"dependencies": {},
|
||||
"devDependencies": {
|
||||
"twenty-client-sdk": "^2.13.0",
|
||||
"twenty-sdk": "^2.13.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* \*\*`twenty-sdk`\*\*는 `twenty` CLI와 빌드/스캐폴딩 도구를 제공합니다. 이 패키지는 개발 및 빌드 시점에만 실행되며, 배포된 앱의 런타임에서는 전혀 임포트되지 않습니다.
|
||||
* \*\*`twenty-client-sdk`\*\*는 앱 코드(`CoreApiClient`, `MetadataApiClient`, `RestApiClient`)에서 임포트되지만, 런타임에는 Twenty가 이를 제공합니다. 로직 함수는 생성된 SDK 레이어에서 이를 가져오고, 프런트엔드 컴포넌트는 서버에서 제공되는 모듈에서 이를 해석하여 가져옵니다. 설치된 사본은 타입 검사와 배포 시점 빌드에만 사용되므로, 배포된 번들에 포함되어 함께 제공될 필요가 없습니다.
|
||||
|
||||
어느 한 패키지라도 `dependencies` 아래에 두면, 설치된 앱의 런타임 번들에 포함되어 쓸모없는 부하가 됩니다. `twenty build`는 둘 중 하나라도 여전히 `dependencies` 아래에 나열되어 있으면 경고를 출력합니다.
|
||||
|
||||
앱의 실제 런타임 의존성(로직 함수가 런타임에 실제로 임포트하는 라이브러리)은 평소와 같이 `dependencies` 아래에 추가하세요.
|
||||
@@ -0,0 +1,176 @@
|
||||
---
|
||||
title: 빠른 시작
|
||||
icon: rocket
|
||||
description: 몇 분 만에 첫 번째 Twenty 앱을 만들어 보세요.
|
||||
---
|
||||
|
||||
## 사전 준비
|
||||
|
||||
* **Node.js 24+** — [여기에서 다운로드](https://nodejs.org/)
|
||||
* **Yarn 4** — Corepack을 통해 Node.js와 함께 제공됩니다. 활성화하려면: `corepack enable`
|
||||
* **Docker** — [여기에서 다운로드](https://www.docker.com/products/docker-desktop/). 로컬 Twenty 서버를 실행하려면 필요합니다. 이미 다른 곳에서 Twenty가 실행 중이라면 건너뛰세요.
|
||||
|
||||
Twenty 앱을 빌드하는 과정은 세 단계로 이루어집니다. 스캐폴더는 이를 단일 해피 패스 명령으로 합쳐 주지만, 각 단계는 별개의 개념입니다 — 문제가 발생했을 때 현재 단계가 어디인지 알면 무엇을 고쳐야 하는지 파악할 수 있습니다.
|
||||
|
||||
| 단계 | 하는 일 | 도구 | 결과 |
|
||||
| ------------ | ------------------------- | ----------------------------- | -------------------- |
|
||||
| **1. 스캐폴딩** | 앱의 소스 코드를 생성 | `npx create-twenty-app` | 디스크에 TypeScript 프로젝트 |
|
||||
| **2. 서버 실행** | 동기화 대상으로 사용할 Twenty 서버 시작 | Docker + `yarn twenty server` | 실행 중인 Twenty 인스턴스 |
|
||||
| **3. 동기화** | 코드를 서버와 실시간 동기화 | `yarn twenty dev` | 변경 사항이 UI에 표시됨 |
|
||||
|
||||
---
|
||||
|
||||
## 1단계 — 프로젝트 스캐폴딩
|
||||
|
||||
템플릿에서 새 앱을 생성합니다:
|
||||
|
||||
```bash filename="Terminal"
|
||||
npx create-twenty-app@latest my-twenty-app
|
||||
```
|
||||
|
||||
이름과 설명을 묻는 프롬프트가 표시됩니다 — 기본값을 사용하려면 **Enter**를 누르세요. 이 명령은 `my-twenty-app/`에 시작용 `application-config.ts`, 기본 역할, CI 워크플로, 통합 테스트가 포함된 TypeScript 프로젝트를 생성합니다.
|
||||
|
||||
**이 단계를 마치면:** 로컬 머신에 앱의 소스 코드가 준비됩니다. 아직 실행되지는 않았습니다 — 그건 2단계에서 진행합니다.
|
||||
|
||||
---
|
||||
|
||||
## 2단계 — 로컬 Twenty 서버 실행
|
||||
|
||||
앱은 동기화할 Twenty 서버가 필요합니다. 이 서버는 Docker에서 로컬로 실행되는 완전한 Twenty 인스턴스입니다 — UI, GraphQL API, PostgreSQL을 포함합니다. 로컬 코드가 해당 서버로 정의를 업로드하면 UI에 표시됩니다.
|
||||
|
||||
스캐폴더가 서버 시작 여부를 묻습니다:
|
||||
|
||||
> **로컬 Twenty 인스턴스를 설정하시겠습니까?**
|
||||
|
||||
* **Yes(권장)** — `twentycrm/twenty-app-dev` Docker 이미지를 가져와 포트 `2020`에서 시작합니다. 먼저 Docker가 실행 중인지 확인하세요.
|
||||
* **No** — 이미 연결하려는 Twenty 서버가 있는 경우 선택하세요. `yarn twenty remote:add`로 나중에 연결할 수 있습니다.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="로컬 인스턴스를 시작할까요?" />
|
||||
</div>
|
||||
|
||||
서버가 올라오면 로그인할 수 있도록 브라우저가 열립니다. 미리 준비된 데모 계정을 사용하세요:
|
||||
|
||||
* **이메일:** `tim@apple.dev`
|
||||
* **비밀번호:** `tim@apple.dev`
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/login.png" alt="Twenty 로그인 화면" />
|
||||
</div>
|
||||
|
||||
다음 화면에서 **Authorize**를 클릭하세요 — 그러면 CLI가 워크스페이스에 접근할 수 있게 됩니다.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI 권한 부여 화면" />
|
||||
</div>
|
||||
|
||||
권한 부여가 완료되면 터미널에 설정이 완료되었다는 메시지가 표시됩니다.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="앱 스캐폴딩 성공" />
|
||||
</div>
|
||||
|
||||
**이 단계를 마치면:** [http://localhost:2020](http://localhost:2020)에서 Twenty 서버가 실행 중이며, CLI가 해당 서버로 동기화하도록 권한이 부여됩니다.
|
||||
|
||||
<Note>
|
||||
Docker가 설치되어 있지 않거나 실행 중이 아니면, 스캐폴더가 OS에 맞는 올바른 시작 명령을 알려줍니다. Docker가 올라오면 `yarn twenty docker:start`로 이어서 진행할 수 있습니다 — 다시 스캐폴딩할 필요는 없습니다.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## 3단계 — 변경 사항 동기화
|
||||
|
||||
이 단계는 대부분의 시간을 보내게 될 내부 루프입니다.
|
||||
|
||||
```bash filename="Terminal"
|
||||
cd my-twenty-app
|
||||
yarn twenty dev
|
||||
```
|
||||
|
||||
`src/`를 감시하며 변경될 때마다 다시 빌드하고, 결과를 서버에 동기화합니다. 파일을 수정해 저장하면 몇 초 안에 서버에 변경 사항이 반영됩니다. 터미널에서 실시간 상태 패널을 확인할 수 있습니다.
|
||||
|
||||
더 자세한 출력(빌드 로그, 동기화 요청, 오류 트레이스)을 보려면 `--verbose`를 추가하세요.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/dev.png" alt="개발 모드 터미널 출력" />
|
||||
</div>
|
||||
|
||||
[http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer)를 엽니다. **Your Apps** 아래에 앱이 표시됩니다.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Your Apps 목록에 My twenty app이 표시됨" />
|
||||
</div>
|
||||
|
||||
**My twenty app**을 클릭하여 **애플리케이션 등록**을 확인하세요 — 앱을 설명하는 서버 수준의 레코드입니다(이름, 식별자, OAuth 자격 증명, 소스). 하나의 등록은 동일한 서버의 여러 워크스페이스에 설치할 수 있습니다.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="애플리케이션 등록 세부정보" />
|
||||
</div>
|
||||
|
||||
워크스페이스 설치를 확인하려면 **View installed app**을 클릭하세요. **About** 탭에는 버전과 관리 옵션이 표시됩니다.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="설치된 앱" />
|
||||
</div>
|
||||
|
||||
**이 단계를 마치면:** 라이브 개발 루프가 준비됩니다. `src/`의 파일을 수정하면 UI에 반영됩니다.
|
||||
|
||||
### CI 및 스크립트를 위한 1회성 동기화
|
||||
|
||||
`--once`를 전달하면 한 번만 빌드 + 동기화를 실행하고 종료합니다 — 파이프라인은 동일하고, 워처는 없습니다:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty dev --once
|
||||
```
|
||||
|
||||
| 명령 | 동작 | 사용 시점 |
|
||||
| ---------------------------------- | ------------------------------------------------ | -------------------------------------- |
|
||||
| `yarn twenty dev` | 소스 파일을 감시하고 변경될 때마다 다시 동기화합니다. 중지할 때까지 계속 실행됩니다. | 대화형 로컬 개발. |
|
||||
| `yarn twenty dev --once` | 한 번만 빌드 + 동기화를 수행하고, 성공 시 `0`, 실패 시 `1`로 종료합니다. | CI, pre-commit 훅, AI 에이전트, 스크립트형 워크플로. |
|
||||
| `yarn twenty dev --once --dry-run` | 메타데이터 변경 사항을 **실제로 적용하지 않고** 빌드하고 출력합니다. | 커밋하기 전에 동기화가 어떤 변경을 수행할지 살펴봅니다. |
|
||||
|
||||
두 모드 모두 인증된 리모트가 필요합니다. `--dry-run`에 대한 자세한 내용은 [동기화 및 복구](/l/ko/developers/extend/apps/operations/sync-and-recovery#previewing-changes-dry-run)를 참고하세요.
|
||||
|
||||
### 개발 모드 옵션
|
||||
|
||||
| 플래그 | 설명 |
|
||||
| ------------------------------------- | -------------------------------------------------------------------- |
|
||||
| `--once` | 한 번만 빌드하고 동기화한 다음 종료합니다. |
|
||||
| `--dry-run` | `--once`를 사용하면 메타데이터 변경 사항을 실제로 적용하지 않고 미리 볼 수 있습니다. 아무것도 기록하지 않습니다. |
|
||||
| `--debounceMs \<ms>` | 파일 변경 디바운스 지연 시간을 밀리초 단위로 설정합니다(기본값: `2000`). |
|
||||
| `--verbose` / `--debug` | 자세한 빌드 로그, 동기화 요청, 오류 추적을 표시합니다. |
|
||||
|
||||
## 만들 수 있는 것
|
||||
|
||||
앱은 **엔터티**로 구성됩니다 — 각 엔터티는 하나의 `export default`만 포함하는 TypeScript 파일로 정의됩니다:
|
||||
|
||||
| 엔터티 | 하는 일 |
|
||||
| ------------- | ---------------------------------------------------------- |
|
||||
| **객체 & 필드** | 사용자 정의 데이터 모델(Post Card, Invoice 등) 타입이 지정된 필드 포함 |
|
||||
| **로직 함수** | HTTP 라우트, cron 스케줄 또는 데이터베이스 이벤트로 트리거되는 서버 측 TypeScript 코드 |
|
||||
| **프론트 컴포넌트** | Twenty의 UI(사이드 패널, 위젯, 명령 메뉴) 안에 렌더링되는 React 컴포넌트 |
|
||||
| **스킬 & 에이전트** | AI 기능 — 재사용 가능한 지침과 자율형 어시스턴트 |
|
||||
| **뷰 & 내비게이션** | 사전 구성된 목록 뷰와 사이드바 메뉴 항목 |
|
||||
| **페이지 레이아웃** | 탭과 위젯이 있는 사용자 정의 레코드 상세 페이지 |
|
||||
|
||||
전체 참고 문서: [개념](/l/ko/developers/extend/apps/getting-started/concepts).
|
||||
|
||||
## 다음 단계
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="설정" icon="screwdriver-wrench" href="/l/ko/developers/extend/apps/config/overview">
|
||||
애플리케이션 ID, 기본 역할, 설치 훅, 공개 자산.
|
||||
</Card>
|
||||
<Card title="데이터" icon="database" href="/l/ko/developers/extend/apps/data/overview">
|
||||
객체, 필드, 그리고 양방향 관계.
|
||||
</Card>
|
||||
<Card title="로직" icon="bolt" href="/l/ko/developers/extend/apps/logic/overview">
|
||||
로직 함수, 스킬, 에이전트, OAuth 연결.
|
||||
</Card>
|
||||
<Card title="레이아웃" icon="table-columns" href="/l/ko/developers/extend/apps/layout/overview">
|
||||
뷰, 내비게이션, 페이지 레이아웃, 프론트 컴포넌트.
|
||||
</Card>
|
||||
<Card title="작업" icon="rocket" href="/l/ko/developers/extend/apps/operations/overview">
|
||||
CLI, 테스트, 리모트, CI, 그리고 앱 게시.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: 스캐폴딩
|
||||
description: "`yarn twenty dev:add`를 사용해 엔티티 파일을 대화형으로 생성하여 객체, 필드, 뷰, 로직 함수 등을 추가하세요."
|
||||
icon: wand-magic-sparkles
|
||||
---
|
||||
|
||||
엔티티 파일을 수동으로 만드는 대신, 대화형 스캐폴더를 사용하세요:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty dev:add
|
||||
```
|
||||
|
||||
이 도구는 엔티티 유형을 선택하도록 안내하고, 필요한 필드를 하나씩 진행한 다음, 안정적인 `universalIdentifier`와 올바른 `defineEntity()` 호출이 포함된 바로 사용할 수 있는 파일을 생성합니다.
|
||||
|
||||
첫 번째 프롬프트를 건너뛰려면 엔티티 타입을 직접 전달할 수도 있습니다:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty dev:add object
|
||||
yarn twenty dev:add logicFunction
|
||||
yarn twenty dev:add frontComponent
|
||||
```
|
||||
|
||||
## 사용 가능한 엔티티 타입
|
||||
|
||||
| 엔티티 유형 | 명령 | 생성된 파일 |
|
||||
| ----------- | ---------------------------------------- | ------------------------------------------------------- |
|
||||
| 객체 | `yarn twenty dev:add object` | `src/objects/\<name>.ts` |
|
||||
| 필드 | `yarn twenty dev:add field` | `src/fields/\<name>.ts` |
|
||||
| 로직 함수 | `yarn twenty dev:add logicFunction` | `src/logic-functions/\<name>.ts` |
|
||||
| 프런트 컴포넌트 | `yarn twenty dev:add frontComponent` | `src/front-components/\<name>.tsx` |
|
||||
| 역할 | `yarn twenty dev:add role` | `src/roles/\<name>.ts` |
|
||||
| 스킬 | `yarn twenty dev:add skill` | `src/skills/\<name>.ts` |
|
||||
| 에이전트 | `yarn twenty dev:add agent` | `src/agents/\<name>.ts` |
|
||||
| 뷰 | `yarn twenty dev:add view` | `src/views/\<name>.ts` |
|
||||
| 내비게이션 메뉴 항목 | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/\<name>.ts` |
|
||||
| 페이지 레이아웃 | `yarn twenty dev:add pageLayout` | `src/page-layouts/\<name>.ts` |
|
||||
|
||||
## 스캐폴더가 생성하는 것
|
||||
|
||||
각 엔티티 타입은 자체 템플릿을 가집니다. 예를 들어, `yarn twenty dev:add object`는 다음을 묻습니다:
|
||||
|
||||
1. **이름(단수)** — 예: `invoice`
|
||||
2. **이름(복수)** — 예: `invoices`
|
||||
3. **레이블(단수)** — 이름에서 자동으로 채워짐(예: `Invoice`)
|
||||
4. **레이블(복수)** — 자동으로 채워짐(예: `Invoices`)
|
||||
5. **뷰와 내비게이션 항목을 생성할까요?** — 예라고 답하면, 스캐폴더가 새 객체에 대한 일치하는 뷰와 사이드바 링크도 생성합니다.
|
||||
|
||||
다른 엔티티 타입은 더 단순한 프롬프트를 사용하며 — 대부분 이름만 묻습니다.
|
||||
|
||||
`field` 엔티티 타입은 더 자세합니다: 필드 이름, 레이블, 타입( `TEXT`, `NUMBER`, `SELECT`, `RELATION` 등 사용 가능한 모든 필드 타입 목록에서 선택), 그리고 대상 객체의 `universalIdentifier`를 묻습니다.
|
||||
|
||||
## 사용자 지정 출력 경로
|
||||
|
||||
`--path` 플래그를 사용해 생성된 파일을 사용자 지정 위치에 배치하세요:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty dev:add logicFunction --path src/custom-folder
|
||||
```
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: 문제 해결
|
||||
description: 일반적인 첫 실행 문제 — Docker, Node 버전, Yarn, 의존성.
|
||||
icon: wrench
|
||||
---
|
||||
|
||||
* **Docker 오류** — `yarn twenty docker:start`를 실행하기 전에 Docker Desktop(또는 데몬)이 실행 중인지 확인하세요. 오류 메시지에 OS에 맞는 올바른 시작 명령이 표시됩니다.
|
||||
* **Node 버전 오류** — 24 이상 필요. `node -v`로 확인하세요.
|
||||
* **Yarn 4 누락** — `corepack enable`을 실행하세요.
|
||||
* **의존성 문제** — `rm -rf node_modules && yarn install`.
|
||||
* **`twenty-sdk` v2.8.0으로 업그레이드한 후 오류 발생** — v2.8.0에서 `dependencies`에서 `devDependencies`로 이동했습니다. [프로젝트 구조 → Dependencies](/l/ko/developers/extend/apps/getting-started/project-structure#dependencies)를 참조하세요.
|
||||
* **`twenty build`는 `dependencies` 아래의 `twenty-client-sdk`에 대해 경고합니다** — 이는 실행 시 Twenty에서 제공되므로, `twenty-sdk`와 함께 `devDependencies`로 옮겨야 합니다. [프로젝트 구조 → Dependencies](/l/ko/developers/extend/apps/getting-started/project-structure#dependencies)를 참조하세요.
|
||||
|
||||
막히셨나요? [Twenty Discord](https://discord.com/channels/1130383047699738754/1130386664812982322)에서 문의하세요.
|
||||
Reference in New Issue
Block a user