982f0c4a4d
Created by Github action --------- Co-authored-by: github-actions <github-actions@twenty.com> Co-authored-by: Charles Bochet <charles@twenty.com>
234 lines
11 KiB
Plaintext
234 lines
11 KiB
Plaintext
---
|
||
title: Başlarken
|
||
description: İlk Twenty uygulamanızı dakikalar içinde oluşturun.
|
||
---
|
||
|
||
<Warning>
|
||
Uygulamalar şu anda alfa testinde. Özellik işlevsel ancak hâlâ gelişmekte.
|
||
</Warning>
|
||
|
||
Uygulamalar, Twenty'yi özel nesneler, alanlar, mantık işlevleri, Yapay Zeka yetenekleri ve UI bileşenleriyle genişletmenizi sağlar — tümü kod olarak yönetilir.
|
||
|
||
**Bugün Yapabilecekleriniz:**
|
||
|
||
* Özel nesneleri ve alanları kod olarak tanımlayın (yönetilen veri modeli)
|
||
* Özel tetikleyicilerle mantık işlevleri oluşturun (HTTP routes, cron, database events)
|
||
* Yapay zekâ ajanları için becerileri tanımlayın
|
||
* Twenty'nin UI'si içinde görüntülenen ön bileşenler oluşturun
|
||
* Aynı uygulamayı birden çok çalışma alanına dağıtın
|
||
|
||
## Ön Gereksinimler
|
||
|
||
* Node.js 24+ ve Yarn 4
|
||
* Bir Twenty çalışma alanı ve bir API anahtarı (https://app.twenty.com/settings/api-webhooks adresinde oluşturun)
|
||
|
||
## Başlarken
|
||
|
||
Resmi iskelet oluşturucu aracını kullanarak yeni bir uygulama oluşturun, ardından kimlik doğrulaması yapıp geliştirmeye başlayın:
|
||
|
||
```bash filename="Terminal"
|
||
# Scaffold a new app (includes all examples by default)
|
||
npx create-twenty-app@latest my-twenty-app
|
||
cd my-twenty-app
|
||
|
||
# Start dev mode: automatically syncs local changes to your workspace
|
||
yarn twenty app:dev
|
||
```
|
||
|
||
İskelet oluşturucu, hangi örnek dosyaların dahil edileceğini kontrol etmek için iki modu destekler:
|
||
|
||
```bash filename="Terminal"
|
||
# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill)
|
||
npx create-twenty-app@latest my-app
|
||
|
||
# Minimal: only core files (application-config.ts and default-role.ts)
|
||
npx create-twenty-app@latest my-app --minimal
|
||
```
|
||
|
||
Buradan şunları yapabilirsiniz:
|
||
|
||
```bash filename="Terminal"
|
||
# Add a new entity to your application (guided)
|
||
yarn twenty entity:add
|
||
|
||
# Watch your application's function logs
|
||
yarn twenty function:logs
|
||
|
||
# Execute a function by name
|
||
yarn twenty function:execute -n my-function -p '{"name": "test"}'
|
||
|
||
# Execute the pre-install function
|
||
yarn twenty function:execute --preInstall
|
||
|
||
# Execute the post-install function
|
||
yarn twenty function:execute --postInstall
|
||
|
||
# Uninstall the application from the current workspace
|
||
yarn twenty app:uninstall
|
||
|
||
# Display commands' help
|
||
yarn twenty help
|
||
```
|
||
|
||
Ayrıca bkz.: [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) ve [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk) için CLI başvuru sayfaları.
|
||
|
||
## Proje yapısı (şablondan oluşturulmuş)
|
||
|
||
`npx create-twenty-app@latest my-twenty-app` komutunu çalıştırdığınızda iskelet oluşturucu şunları yapar:
|
||
|
||
* Minimal bir temel uygulamayı `my-twenty-app/` içine kopyalar
|
||
* Yerel bir `twenty-sdk` bağımlılığı ve Yarn 4 yapılandırması ekler
|
||
* `twenty` CLI ile bağlantılı yapılandırma dosyaları ve betikler oluşturur
|
||
* İskelet oluşturma moduna bağlı olarak çekirdek dosyaları (uygulama yapılandırması, varsayılan işlev rolü, kurulum öncesi ve kurulum sonrası işlevler) ile örnek dosyaları üretir
|
||
|
||
Varsayılan `--exhaustive` moduyla yeni oluşturulmuş bir uygulama şu şekilde görünür:
|
||
|
||
```text filename="my-twenty-app/"
|
||
my-twenty-app/
|
||
package.json
|
||
yarn.lock
|
||
.gitignore
|
||
.nvmrc
|
||
.yarnrc.yml
|
||
.yarn/
|
||
install-state.gz
|
||
.oxlintrc.json
|
||
tsconfig.json
|
||
README.md
|
||
public/ # Public assets folder (images, fonts, etc.)
|
||
src/
|
||
├── application-config.ts # Required - main application configuration
|
||
├── roles/
|
||
│ └── default-role.ts # Default role for logic functions
|
||
├── objects/
|
||
│ └── example-object.ts # Example custom object definition
|
||
├── fields/
|
||
│ └── example-field.ts # Example standalone field definition
|
||
├── logic-functions/
|
||
│ ├── hello-world.ts # Example logic function
|
||
│ ├── pre-install.ts # Pre-install logic function
|
||
│ └── post-install.ts # Post-install logic function
|
||
├── front-components/
|
||
│ └── hello-world.tsx # Example front component
|
||
├── views/
|
||
│ └── example-view.ts # Example saved view definition
|
||
├── navigation-menu-items/
|
||
│ └── example-navigation-menu-item.ts # Example sidebar navigation link
|
||
└── skills/
|
||
└── example-skill.ts # Example AI agent skill definition
|
||
```
|
||
|
||
`--minimal` ile yalnızca çekirdek dosyalar oluşturulur (`application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts` ve `logic-functions/post-install.ts`).
|
||
|
||
Genel hatlarıyla:
|
||
|
||
* **package.json**: Uygulama adını, sürümünü, motorları (Node 24+, Yarn 4) bildirir ve `twenty-sdk` ile yerel `twenty` CLI'sine yetki devreden bir `twenty` betiği ekler. Tüm mevcut komutları listelemek için `yarn twenty help` komutunu çalıştırın.
|
||
* **.gitignore**: `node_modules`, `.yarn`, `generated/` (türlendirilmiş istemci), `dist/`, `build/`, kapsam klasörleri, günlük dosyaları ve `.env*` dosyaları gibi yaygın artifaktları yok sayar.
|
||
* **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Proje tarafından kullanılan Yarn 4 araç zincirini kilitler ve yapılandırır.
|
||
* **.nvmrc**: Projenin beklediği Node.js sürümünü sabitler.
|
||
* **.oxlintrc.json** ve **tsconfig.json**: Uygulamanızın TypeScript kaynakları için linting ve TypeScript yapılandırması sağlar.
|
||
* **README.md**: Uygulama kökünde temel talimatların yer aldığı kısa bir README.
|
||
* **public/**: Uygulamanızla birlikte sunulacak genel varlıkları (görseller, yazı tipleri, statik dosyalar) depolamak için bir klasör. Buraya yerleştirilen dosyalar senkronizasyon sırasında yüklenir ve çalışma zamanında erişilebilir olur.
|
||
* **src/**: Uygulamanızı kod olarak tanımladığınız ana yer
|
||
|
||
### Varlık algılama
|
||
|
||
SDK, TypeScript dosyalarınızı **`export default define<Entity>({...})`** çağrılarını arayarak ayrıştırıp varlıkları algılar. Her varlık türünün, `twenty-sdk` tarafından dışa aktarılan karşılık gelen bir yardımcı fonksiyonu vardır:
|
||
|
||
| Yardımcı fonksiyon | Varlık türü |
|
||
| -------------------------------- | -------------------------------------------------------- |
|
||
| `defineObject` | Özel nesne tanımları |
|
||
| `defineLogicFunction` | Mantık işlevi tanımları |
|
||
| `definePreInstallLogicFunction` | Kurulum öncesi mantık işlevi (kurulumdan önce çalışır) |
|
||
| `definePostInstallLogicFunction` | Kurulum sonrası mantık işlevi (kurulumdan sonra çalışır) |
|
||
| `defineFrontComponent` | Ön bileşen tanımları |
|
||
| `defineRole` | Rol tanımları |
|
||
| `defineField` | Mevcut nesneler için alan genişletmeleri |
|
||
| `defineView` | Kaydedilmiş görünüm tanımları |
|
||
| `defineNavigationMenuItem` | Gezinme menüsü öğesi tanımları |
|
||
| `defineSkill` | Yapay zekâ ajanı yetenek tanımları |
|
||
|
||
<Note>
|
||
**Dosya adlandırma esnektir.** Varlık algılama AST tabanlıdır — SDK, kaynak dosyalarınızı `export default define<Entity>({...})` desenini bulmak için tarar. Dosyalarınızı ve klasörlerinizi dilediğiniz gibi düzenleyebilirsiniz. Varlık türüne göre gruplama (örn. `logic-functions/`, `roles/`) bir gereklilik değil, yalnızca kod organizasyonu için bir gelenektir.
|
||
</Note>
|
||
|
||
Algılanan bir varlığa örnek:
|
||
|
||
```typescript
|
||
// This file can be named anything and placed anywhere in src/
|
||
import { defineObject, FieldType } from 'twenty-sdk';
|
||
|
||
export default defineObject({
|
||
universalIdentifier: '...',
|
||
nameSingular: 'postCard',
|
||
// ... rest of config
|
||
});
|
||
```
|
||
|
||
İlerideki komutlar daha fazla dosya ve klasör ekleyecektir:
|
||
|
||
* `yarn twenty app:dev`, `node_modules/twenty-sdk/generated` içinde iki tiplendirilmiş API istemcisini otomatik olarak oluşturur: `CoreApiClient` (`/graphql` üzerinden çalışma alanı verileri için) ve `MetadataApiClient` (çalışma alanı yapılandırması ve `/metadata` üzerinden dosya yüklemeleri için).
|
||
* `yarn twenty entity:add`, özel nesneleriniz, fonksiyonlarınız, ön bileşenleriniz, rolleriniz, yetenekleriniz ve daha fazlası için `src/` altında varlık tanım dosyaları ekler.
|
||
|
||
## Kimlik Doğrulama
|
||
|
||
`yarn twenty auth:login` komutunu ilk kez çalıştırdığınızda, sizden şunlar istenir:
|
||
|
||
* API URL’si (varsayılan: http://localhost:3000 veya mevcut çalışma alanı profiliniz)
|
||
* API anahtarı
|
||
|
||
Kimlik bilgileriniz kullanıcı başına `~/.twenty/config.json` içinde saklanır. Birden fazla profili yönetebilir ve aralarında geçiş yapabilirsiniz.
|
||
|
||
### Çalışma alanlarını yönetme
|
||
|
||
```bash filename="Terminal"
|
||
# Login interactively (recommended)
|
||
yarn twenty auth:login
|
||
|
||
# Login to a specific workspace profile
|
||
yarn twenty auth:login --workspace my-custom-workspace
|
||
|
||
# List all configured workspaces
|
||
yarn twenty auth:list
|
||
|
||
# Switch the default workspace (interactive)
|
||
yarn twenty auth:switch
|
||
|
||
# Switch to a specific workspace
|
||
yarn twenty auth:switch production
|
||
|
||
# Check current authentication status
|
||
yarn twenty auth:status
|
||
```
|
||
|
||
`yarn twenty auth:switch` ile çalışma alanlarını değiştirdikten sonra, sonraki tüm komutlar varsayılan olarak o çalışma alanını kullanacaktır. Yine de bunu geçici olarak `--workspace <name>` ile geçersiz kılabilirsiniz.
|
||
|
||
## Manuel kurulum (iskelet oluşturucu olmadan)
|
||
|
||
En iyi başlangıç deneyimi için `create-twenty-app` kullanmanızı önersek de, bir projeyi manuel olarak da kurabilirsiniz. CLI'yi global olarak kurmayın. Bunun yerine `twenty-sdk`'yi yerel bir bağımlılık olarak ekleyin ve package.json içinde tek bir betik tanımlayın:
|
||
|
||
```bash filename="Terminal"
|
||
yarn add -D twenty-sdk
|
||
```
|
||
|
||
Ardından bir `twenty` betiği ekleyin:
|
||
|
||
```json filename="package.json"
|
||
{
|
||
"scripts": {
|
||
"twenty": "twenty"
|
||
}
|
||
}
|
||
```
|
||
|
||
Artık tüm komutları `yarn twenty <command>` üzerinden çalıştırabilirsiniz; örn. `yarn twenty app:dev`, `yarn twenty help` vb.
|
||
|
||
## Sorun Giderme
|
||
|
||
* Kimlik doğrulama hataları: `yarn twenty auth:login` çalıştırın ve API anahtarınızın gerekli izinlere sahip olduğundan emin olun.
|
||
* Sunucuya bağlanılamıyor: API URL’sini ve Twenty sunucusunun erişilebilir olduğunu doğrulayın.
|
||
* Türler veya istemci eksik/eski: `yarn twenty app:dev` komutunu yeniden çalıştırın — tiplendirilmiş istemciyi otomatik olarak oluşturur.
|
||
* Geliştirme modu eşitlenmiyor: `yarn twenty app:dev`'in çalıştığından ve değişikliklerin ortamınız tarafından yok sayılmadığından emin olun.
|
||
|
||
Discord Yardım Kanalı: https://discord.com/channels/1130383047699738754/1130386664812982322
|