Başlarken

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

Uygulamanız için bir ad ve açıklama girmeniz istenecektir. Varsayılanları kabul etmek için Enter tuşuna basın. Bu, 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

Bu, kaynak dosyalarınızı izler, her değişiklikte yeniden derler ve uygulamanızı yerel Twenty sunucusuyla otomatik olarak eşitler. Terminalinizde canlı bir durum paneli görmelisiniz. Daha ayrıntılı çıktı (derleme günlükleri, eşitleme istekleri, hata izleri) için --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:

yarn twenty dev --once

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ışı.

Her iki mod da geliştirme modunda çalışan bir Twenty sunucusu ve kimliği doğrulanmış bir uzak gerektirir — aynı önkoşullar geçerlidir.

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:

Your Apps listesinde My twenty app gösteriliyor

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ı

Her varlık türü hakkında ayrıntılı bir kılavuz için Uygulama Oluşturma bölümüne göz atın.

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

Örnekler GitHub’daki twenty-apps/examples dizininden alınır. Ayrıca 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

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 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

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.

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

2. package.json dosyanıza bir twenty betiği ekleyin:

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

Artık 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.

Genel Bakış

Uygulamalar

API

Kendi Kendine Barındırma

Katkıda Bulunun

Uygulamalar nedir?

Ön Gereksinimler

İlk uygulamanızı oluşturun

Uygulamanızın iskeletini oluşturun

Yerel bir Twenty örneği kurun

Çalışma alanınıza giriş yapın

Uygulamayı yetkilendirin

Geliştirmeye başlayın

Tek seferlik eşitleme `yarn twenty dev --once` ile

Uygulamanızı Twenty’de görün

Oluşturabilecekleriniz

Proje yapısı

Bir örnekten başlayın

Temel dosyalar

Yerel geliştirme sunucusu

Test örneği çalıştırma

Manuel kurulum (iskelet oluşturucu olmadan)

Sorun Giderme

​Uygulamalar nedir?

​Ön Gereksinimler

​İlk uygulamanızı oluşturun

​Uygulamanızın iskeletini oluşturun

​Yerel bir Twenty örneği kurun

​Çalışma alanınıza giriş yapın

​Uygulamayı yetkilendirin

​Geliştirmeye başlayın

​Tek seferlik eşitleme yarn twenty dev --once ile

​Uygulamanızı Twenty’de görün

​Oluşturabilecekleriniz

​Proje yapısı

​Bir örnekten başlayın

​Temel dosyalar

​Yerel geliştirme sunucusu

​Test örneği çalıştırma

​Manuel kurulum (iskelet oluşturucu olmadan)

​Sorun Giderme

Uygulamalar nedir?

Ön Gereksinimler

İlk uygulamanızı oluşturun

Uygulamanızın iskeletini oluşturun

Yerel bir Twenty örneği kurun

Çalışma alanınıza giriş yapın

Uygulamayı yetkilendirin

Geliştirmeye başlayın

Tek seferlik eşitleme `yarn twenty dev --once` ile

Uygulamanızı Twenty’de görün

Oluşturabilecekleriniz

Proje yapısı

Bir örnekten başlayın

Temel dosyalar

Yerel geliştirme sunucusu

Test örneği çalıştırma

Manuel kurulum (iskelet oluşturucu olmadan)

Sorun Giderme