Başlarken

İlk Twenty uygulamanızı dakikalar içinde oluşturun.

Ön Gereksinimler

• Node.js 24+ — Buradan indirin
• Yarn 4 — Corepack aracılığıyla Node ile birlikte gelir. Etkinleştirin: corepack enable
• Docker — Buradan indirin. Yerel bir Twenty sunucusunu çalıştırmak için gereklidir. Zaten başka bir yerde Twenty çalıştırıyorsanız atlayın.

Bir Twenty uygulaması oluşturmanın üç aşaması vardır. İskelet oluşturucu bunları tek bir sorunsuz akış komutuna indirger, ancak her aşama ayrı bir kavramdır — bir şeyler başarısız olduğunda hangi aşamada olduğunuzu bilmek neyi düzeltmeniz gerektiğini söyler.

Aşama	Ne yaparsınız	Araç	Sonuç
1. İskelet Oluşturma	Uygulamanın kaynak kodunu oluşturun	npx create-twenty-app	Diskte bir TypeScript projesi
2. Bir sunucu çalıştırma	Eşitleme yapacağınız bir Twenty sunucusu başlatın	Docker + yarn twenty server	Çalışan bir Twenty örneği
3. Eşitleme	Kodunuzu sunucuya canlı olarak eşitleyin	yarn twenty dev	Değişiklikleriniz arayüzde görünür

---

Aşama 1 — Projenizin iskeletini oluşturun

Şablondan yeni bir uygulama oluşturun:

npx create-twenty-app@latest my-twenty-app

Sizden bir ad ve açıklama istenir — varsayılanlar için Enter tuşuna basın. Bu, my-twenty-app/ içinde bir başlangıç application-config.ts, varsayılan bir rol, bir CI iş akışı ve bir entegrasyon testi ile bir TypeScript projesi oluşturur.

Bu aşamadan sonra: makinenizde uygulamanın kaynak kodu bulunur. Henüz çalışmıyor — bu, 2. Aşama.

---

Aşama 2 — Yerel bir Twenty sunucusu çalıştırın

Uygulamanızın eşitleme yapacağı bir Twenty sunucusuna ihtiyacı vardır. Sunucu, Docker içinde yerel olarak çalışan tam bir Twenty örneğidir — UI, GraphQL API, PostgreSQL. Yerel kodunuz tanımlarını bu sunucuya yükler; bu da onların arayüzde görünmesini sağlar.

İskelet oluşturucu sizin için bir tane başlatmayı teklif eder:

Yerel bir Twenty örneği kurmak ister misiniz?

• Evet (önerilir) — twentycrm/twenty-app-dev Docker imajını çeker ve 2020 portunda başlatır. Önce Docker’ın çalıştığından emin olun.
• Hayır — Zaten bağlanmak istediğiniz bir Twenty sunucunuz varsa bunu seçin. Bunu daha sonra yarn twenty remote add ile bağlayabilirsiniz.

Sunucu çalışır duruma geldiğinde, oturum açmak için bir tarayıcı açılır. Önceden eklenmiş demo hesabını kullanın:

• E-posta: [e-mail]
• Parola: [e-mail]

Sonraki ekranda Authorize’a tıklayın — bu işlem CLI’nin çalışma alanınıza erişmesine izin verir.

Terminaliniz her şeyin kurulduğunu onaylayacaktır.

Bu aşamadan sonra: http://localhost:2020 adresinde çalışan bir Twenty sunucunuz ve ona eşitleme yapmak için yetkilendirilmiş bir CLI’ınız olur.

Docker yüklü değilse veya çalışmıyorsa, iskelet oluşturucu işletim sisteminiz için doğru başlatma komutunu söyleyecektir. Docker çalışır duruma geldiğinde, yarn twenty server start ile devam edebilirsiniz — yeniden iskelet oluşturmaya gerek yok.

---

Aşama 3 — Değişikliklerinizi eşitleyin

Zamanınızın çoğunu geçireceğiniz iç döngü budur.

cd my-twenty-app
yarn twenty dev

Bu, src/ dizinini izler, her değişiklikte yeniden oluşturur ve sonucu sunucuya eşitler. Bir dosyayı düzenleyin, kaydedin; bir saniye içinde sunucu değişikliği yansıtır. Terminalinizde canlı bir durum paneli göreceksiniz.

Daha ayrıntılı çıktı (derleme günlükleri, eşitleme istekleri, hata izleri) için --verbose ekleyin.

http://localhost:2020/settings/applications#developer adresini açın. Uygulamanızı Your Apps altında görmelisiniz.

My twenty app’e tıklayarak application registration’ı görüntüleyin — uygulamanızı tanımlayan (ad, tanımlayıcı, OAuth kimlik bilgileri, kaynak) sunucu düzeyinde bir kayıttır. Tek bir kayıt, aynı sunucudaki birden çok çalışma alanına kurulabilir.

Çalışma alanındaki kurulumu görmek için View installed app’e tıklayın. About sekmesi sürümü ve yönetim seçeneklerini gösterir.

Bu aşamadan sonra: canlı bir geliştirme döngünüz olur. src/ içindeki herhangi bir dosyayı düzenleyin; arayüzde görünür.

CI ve betikler için tek seferlik eşitleme

Tek bir derleme + eşitleme çalıştırıp çıkmak için --once parametresini geçin — aynı ardışık düzen, izleyici yok:

yarn twenty dev --once

Komut	Davranış	Ne zaman kullanılmalı
yarn twenty dev	Her değişiklikte izler ve yeniden eşitler. Siz durdurana kadar çalışır.	Etkileşimli yerel geliştirme.
yarn twenty dev --once	Tek derleme + eşitleme; başarıda 0, başarısızlıkta 1 ile çıkar.	CI, pre-commit kancaları, AI ajanları, betiklenmiş iş akışları.

Her iki mod da geliştirme modunda bir sunucuya ve kimliği doğrulanmış bir uzak uca ihtiyaç duyar.

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 kullanın. Bkz. Uygulamaları Yayımlama.

---

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	Özel veri modelleri (Post Card, Invoice vb.) tipli alanlarla
Mantıksal işlevler	HTTP rotaları, cron zamanlamaları veya veritabanı olayları tarafından tetiklenen sunucu tarafı TypeScript
Ö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	Ö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ı

Tam başvuru: Uygulama Oluşturma.

Proje yapısı

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

Dosya / Klasör	Amaç
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 meta veriler (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).

Bir örnekten başlayın

Daha kapsamlı bir projeyle başlamak için --example kullanın (özel nesneler, alanlar, mantık işlevleri, ön uç bileşenleri):

npx create-twenty-app@latest my-twenty-app --example postcard

Örnekler twenty-apps/examples dizininde yer alır. Ayrıca yarn twenty add ile mevcut bir projeye tek tek varlıklar için iskelet oluşturabilirsiniz — bkz. Uygulama Oluşturma.

---

Yerel sunucuyu yönetme

Yerel Twenty konteynerini kontrol etmek için yarn twenty server kullanın:

Komut	Ne yapar
yarn twenty server start	Sunucuyu başlatır (gerekirse imajı çeker)
yarn twenty server start --port 3030	Özel bir portta başlatır
yarn twenty server stop	Sunucuyu durdurur (verileri korur)
yarn twenty server status	URL’yi, sürümü ve oturum açma kimlik bilgilerini gösterir
yarn twenty server logs	Sunucu günlüklerini akış olarak iletir
yarn twenty server reset	Verileri siler ve sıfırdan başlatır
yarn twenty server upgrade	En güncel twenty-app-dev imajını çeker
yarn twenty server upgrade 2.2.0	Belirli bir sürüme yükseltin

Veriler, yeniden başlatmalar arasında iki Docker biriminde kalıcıdır (PostgreSQL için twenty-app-dev-data, dosyalar için twenty-app-dev-storage). Her şeyi silmek için reset kullanın.

Sunucu imajını yükseltme

yarn twenty server upgrade, en güncel imajı çeker, özetleri karşılaştırır ve yalnızca gerçekten bir şey değiştiyse konteyneri yeniden oluşturur. Birimler korunur — yalnızca konteyner değiştirilir. Yeni bir imaj çekildiyse ve konteyner çalışıyorsa, yükseltme otomatik olarak yeni bir konteyner başlatır; sağlıklı hale gelmesini beklemek için ardından yarn twenty server start çalıştırın.

yarn twenty server upgrade            # Latest
yarn twenty server upgrade 2.2.0      # Specific version

yarn twenty server status ile çalışan sürümü doğrulayabilirsiniz (konteynere gömülü APP_VERSION değerini gösterir).

Paralel bir 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	Ne yapar
yarn twenty server start --test	Test örneğini başlatır (varsayılan bağlantı noktası 2021’dir)
yarn twenty server stop --test	Durdurun
yarn twenty server status --test	Durumunu gösterin
yarn twenty server logs --test	Günlüklerini akış olarak izleyin
yarn twenty server reset --test	Verilerini silin
yarn twenty server upgrade --test	İmajını yükseltin

Test örneği, kendine ait bir Docker konteynerinde (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.

---

Manuel kurulum (iskelet oluşturucu olmadan)

SDK’yı mevcut bir projeye ekliyorsanız iskelet oluşturma adımını atlayın:

yarn add twenty-sdk twenty-client-sdk

package.json dosyasına betiği ekleyin:

{
  "scripts": {
    "twenty": "twenty"
  }
}

Artık yarn twenty dev, yarn twenty server start ve diğerlerini çalıştırabilirsiniz.

twenty-sdk’yi global olarak kurmayın — her uygulama kendi sürümünü kullansın diye proje bazında sabitleyin.

---

Sorun Giderme

• Docker hataları — yarn twenty server start öncesinde Docker Desktop’ın (veya daemon’ın) çalıştığından emin olun. Hata iletisi, işletim sisteminiz için doğru başlatma komutunu gösterecektir.
• Yanlış Node sürümü — 24+ gerekir. node -v ile kontrol edin.
• Yarn 4 eksik — corepack enable çalıştırın.
• Bağımlılıklar bozuk — rm -rf node_modules && yarn install.

Takıldınız mı? Twenty Discord üzerinde yardım isteyin.