Uygulamalar nedir?
Uygulamalar, Twenty’yi özel nesneler, alanlar, mantıksal işlevler, ön uç bileşenleri, yapay zekâ yetenekleri ve daha fazlasıyla genişletmenizi sağlar — tümü kod olarak yönetilir. Her şeyi UI üzerinden yapılandırmak yerine, veri modelinizi ve mantığınızı TypeScript’te tanımlar ve bunu bir veya daha fazla çalışma alanına dağıtırsınız.
Ön Gereksinimler
Başlamadan önce, makinenizde aşağıdakilerin kurulu olduğundan emin olun:
- Node.js 24+ — Buradan indirin
- Yarn 4 — Corepack aracılığıyla Node.js ile birlikte gelir.
corepack enable komutunu çalıştırarak etkinleştirin
- Docker — Buradan indirin. Yerel bir Twenty örneğini çalıştırmak için gereklidir. Zaten çalışan bir Twenty sunucunuz varsa gerekmez.
İlk uygulamanızı oluşturun
Uygulamanızın iskeletini oluşturun
Bir terminal açın ve şunu çalıştırın:
npx create-twenty-app@latest my-twenty-app
my-twenty-app adlı, ihtiyacınız olan her şeyi içeren yeni bir klasör oluşturur.
Yerel bir Twenty örneği kurun
İskelet oluşturucu şunu soracaktır:
Yerel bir Twenty örneği kurmak ister misiniz?
yes yazın (önerilir) — Bu, twenty-app-dev Docker imajını çeker ve 2020 portunda yerel bir Twenty sunucusu başlatır. Devam etmeden önce Docker’ın çalıştığından emin olun.no yazın — Yerelde zaten çalışan bir Twenty sunucunuz varsa bunu seçin.
Çalışma alanınıza giriş yapın
Ardından, Twenty oturum açma sayfasıyla bir tarayıcı penceresi açılacaktır. Önceden eklenmiş demo hesabıyla oturum açın:
- E-posta:
tim@apple.dev
- Parola:
tim@apple.dev
Uygulamayı yetkilendirin
Oturum açtıktan sonra bir yetkilendirme ekranı göreceksiniz. Bu, uygulamanızın çalışma alanınızla etkileşim kurmasını sağlar.
Devam etmek için Authorize’a tıklayın.
Yetkilendirildikten sonra terminaliniz her şeyin kurulduğunu onaylayacaktır.
Geliştirmeye başlayın
Yeni uygulama klasörünüze gidin ve geliştirme sunucusunu başlatın:
cd my-twenty-app
yarn twenty dev
--verbose bayrağını kullanın:
yarn twenty dev --verbose
Geliştirme modu yalnızca geliştirme ortamında (NODE_ENV=development) çalışan Twenty örneklerinde kullanılabilir. Üretim örnekleri geliştirme eşitleme isteklerini reddeder. Üretim sunucularına dağıtmak için yarn twenty deploy komutunu kullanın — ayrıntılar için Uygulamaları Yayınlama bölümüne bakın. Tek seferlik eşitleme yarn twenty dev --once ile
Arka planda bir izleyicinin çalışmasını istemiyorsanız (örneğin bir CI ardışık düzeni içinde, bir git hook veya betik tabanlı bir iş akışı içinde), --once bayrağını belirtin. yarn twenty dev ile aynı ardışık düzeni çalıştırır — derleme manifestosunu oluşturur, dosyaları paketler, yükler, eşitler, tiplendirilmiş API istemcisini yeniden oluşturur — ancak eşitleme tamamlanır tamamlanmaz çıkış yapar:
| Komut | Davranış | Ne zaman kullanılmalı |
|---|
yarn twenty dev | Kaynak dosyalarınızı izler ve her değişiklikte yeniden eşitler. Siz durdurana kadar çalışmaya devam eder. | Etkileşimli yerel geliştirme — canlı durum paneli ve anlık geri bildirim döngüsü istersiniz. |
yarn twenty dev --once | Tek bir derleme + eşitleme gerçekleştirir, ardından başarı durumunda 0 veya başarısızlık durumunda 1 koduyla çıkar. | Betikler, CI, pre-commit hooks, AI ajanları ve etkileşimsiz herhangi bir iş akışı. |
Uygulamanızı Twenty’de görün
Tarayıcınızda http://localhost:2020/settings/applications#developer adresini açın. Settings > Apps bölümüne gidin ve Developer sekmesini seçin. Your Apps altında uygulamanızın listelendiğini görmelisiniz:
My twenty app üzerine tıklayarak uygulama kaydını açın. Kayıt, uygulamanızı tanımlayan sunucu düzeyinde bir kayıttır — adını, benzersiz tanımlayıcısını, OAuth kimlik bilgilerini ve kaynağını (yerel, npm veya tarball). Belirli bir çalışma alanının içinde değil, sunucuda bulunur. Bir uygulamayı bir çalışma alanına kurduğunuzda, Twenty bu kayda işaret eden, çalışma alanı kapsamında bir uygulama oluşturur. Tek bir kayıt, aynı sunucudaki birden çok çalışma alanına kurulabilir.
Yüklü uygulamayı görmek için View installed app’e tıklayın. About sekmesi, geçerli sürümü ve yönetim seçeneklerini gösterir:
Uygulamanızın sağladığı her şeyi — nesneler, alanlar, mantık işlevleri ve ajanlar — görmek için Content sekmesine geçin:
Her şey hazır! src/ içindeki herhangi bir dosyayı düzenleyin; değişiklikler otomatik olarak alınacaktır.
Oluşturabilecekleriniz
Uygulamalar varlıklardan oluşur — her biri tek bir export default içeren bir TypeScript dosyası olarak tanımlanır:
| Varlık | Ne yapar |
|---|
| Nesneler ve Alanlar | Tipli alanlarla özel veri modelleri (ör. Post Card, Invoice) tanımlayın |
| Mantıksal işlevler | HTTP rotaları, cron zamanlamaları veya veritabanı olayları tarafından tetiklenen sunucu tarafı TypeScript işlevleri |
| Ön uç bileşenleri | Twenty’nin arayüzünde görüntülenen React bileşenleri (yan panel, widget’lar, komut menüsü) |
| Beceriler ve Aracılar | Yapay zeka yetenekleri — yeniden kullanılabilir yönergeler ve otonom asistanlar |
| Görünümler ve Gezinme | Nesneleriniz için önceden yapılandırılmış liste görünümleri ve kenar çubuğu menü öğeleri |
| Sayfa düzenleri | Sekmeler ve widget’lar içeren özel kayıt ayrıntı sayfaları |
Proje yapısı
İskelet oluşturucu aşağıdaki dosya yapısını oluşturur:
my-twenty-app/
package.json
yarn.lock
.gitignore
.nvmrc
.yarnrc.yml
.oxlintrc.json
tsconfig.json
tsconfig.spec.json # TypeScript config for tests
vitest.config.ts # Vitest test runner configuration
LLMS.md
README.md
.github/
└── workflows/
└── ci.yml # GitHub Actions CI workflow
public/ # Public assets (images, fonts, etc.)
src/
├── application-config.ts # Required — main application configuration
├── default-role.ts # Default role for logic functions
├── constants/
│ └── universal-identifiers.ts # Auto-generated UUIDs and app metadata
└── __tests__/
├── setup-test.ts # Test setup (server health check, config)
└── app-install.integration-test.ts # Integration test
Bir örnekten başlayın
Özel nesneler, alanlar, mantık işlevleri, ön uç bileşenleri ve daha fazlasını içeren daha kapsamlı bir örnekten başlamak için --example bayrağını kullanın:
npx create-twenty-app@latest my-twenty-app --example postcard
yarn twenty add ile mevcut bir projeye tek tek varlıklar için iskelet oluşturabilirsiniz (bkz. Uygulama Oluşturma).
Temel dosyalar
| Dosya / Klasör | Amaç |
|---|
package.json | Uygulamanızın adını, sürümünü ve bağımlılıklarını bildirir. Tüm komutları görmek için yarn twenty help çalıştırabilmeniz amacıyla bir twenty betiği içerir. |
src/application-config.ts | Gerekli. Uygulamanızın ana yapılandırma dosyası. |
src/default-role.ts | Mantık işlevlerinizin neye erişebileceğini denetleyen varsayılan rol. |
src/constants/universal-identifiers.ts | Otomatik oluşturulan UUID’ler ve uygulama meta verileri (görünen ad, açıklama). |
src/__tests__/ | Entegrasyon testleri (kurulum + örnek test). |
public/ | Uygulamanızla birlikte sunulan statik varlıklar (görüntüler, yazı tipleri). |
Yerel geliştirme sunucusu
İskelet oluşturucu sizin için zaten yerel bir Twenty sunucusu başlattı. Daha sonra yönetmek için yarn twenty server komutunu kullanın:
| Komut | Açıklama |
|---|
yarn twenty server start | Yerel sunucuyu başlatır (gerekirse imajı çeker) |
yarn twenty server start --port 3030 | Özel bir portta başlatır |
yarn twenty server start --test | 2021 numaralı bağlantı noktasında ayrı bir test örneği başlatın |
yarn twenty server stop | Sunucuyu durdurur (verileri korur) |
yarn twenty server status | Sunucu durumunu, URL’yi ve kimlik bilgilerini gösterir |
yarn twenty server logs | Sunucu günlüklerini akış olarak iletir |
yarn twenty server logs --lines 100 | Son 100 günlük satırını gösterir |
yarn twenty server reset | Tüm verileri siler ve sıfırdan başlatır |
twenty-app-dev-data, dosyalar için twenty-app-dev-storage). Her şeyi silip baştan başlamak için reset kullanın.
Test örneği çalıştırma
server komutlarının herhangi birine --test parametresini vererek ikinci, tamamen yalıtılmış bir örneği yönetin — entegrasyon testlerini çalıştırmak veya ana geliştirme verilerinize dokunmadan denemeler yapmak için kullanışlıdır.
| Komut | Açıklama |
|---|
yarn twenty server start --test | Test örneğini başlatır (varsayılan bağlantı noktası 2021’dir) |
yarn twenty server stop --test | Test örneğini durdurur |
yarn twenty server status --test | Test örneğinin durumunu, URL’yi ve kimlik bilgilerini gösterir |
yarn twenty server logs --test | Test örneği günlüklerini akış olarak iletir |
yarn twenty server reset --test | Test verilerini siler ve sıfırdan başlatır |
twenty-app-dev-test), ayrılmış birimlerle (twenty-app-dev-test-data, twenty-app-dev-test-storage) ve yapılandırmayla çalışır; böylece ana örneğinizle çakışma olmadan paralel olarak çalışabilir. Varsayılan 2021’i geçersiz kılmak için --test ile --port’u birlikte kullanın.
Sunucunun çalışması için Docker’ın çalışıyor olması gerekir. “Docker not running” hatası görürseniz Docker Desktop’ın (veya Docker daemon’ının) başlatıldığından emin olun.
Manuel kurulum (iskelet oluşturucu olmadan)
create-twenty-app kullanmak yerine her şeyi kendiniz ayarlamayı tercih ederseniz, bunu iki adımda yapabilirsiniz.
1. twenty-sdk ve twenty-client-sdk paketlerini bağımlılık olarak ekleyin:
yarn add twenty-sdk twenty-client-sdk
package.json dosyanıza bir twenty betiği ekleyin:
{
"scripts": {
"twenty": "twenty"
}
}
yarn twenty dev, yarn twenty help ve diğer tüm komutları çalıştırabilirsiniz.
twenty-sdk’yi global olarak kurmayın. Her projenin kendi sürümünü sabitleyebilmesi için onu her zaman yerel bir proje bağımlılığı olarak kullanın.
Sorun Giderme
Sorunlarla karşılaşırsanız:
- Yerel bir örnekle scaffolder’ı başlatmadan önce Docker’ın çalıştığından emin olun.
- Node.js 24+ kullandığınızdan emin olun (kontrol etmek için
node -v).
- Yarn 4’ün kullanılabilir olması için Corepack’in etkinleştirildiğinden emin olun (
corepack enable).
- Bağımlılıklar bozuk görünüyorsa
node_modules dizinini silip yarn install komutunu yeniden çalıştırmayı deneyin.
Hâlâ takıldınız mı? Yardım için Twenty Discord üzerinden yardım isteyin.
