---
title: Başlarken
icon: rocket
description: İlk Twenty uygulamanızı dakikalar içinde oluşturun.
---

## Ön Gereksinimler

* **Node.js 24+** — [Buradan indirin](https://nodejs.org/)
* **Yarn 4** — Corepack aracılığıyla Node ile birlikte gelir. Etkinleştirin: `corepack enable`
* **Docker** — [Buradan indirin](https://www.docker.com/products/docker-desktop/). 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:

```bash filename="Terminal"
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** — Bağlanmak istediğiniz zaten bir Twenty sunucunuz varsa bunu seçin. Bunu daha sonra `yarn twenty remote add` ile bağlayabilirsiniz.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/start-instance.png" alt="Yerel örnek başlatılsın mı?" />
</div>

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:** `tim@apple.dev`
* **Parola:** `tim@apple.dev`

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/login.png" alt="Twenty oturum açma ekranı" />
</div>

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

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI yetkilendirme ekranı" />
</div>

Terminaliniz her şeyin kurulduğunu onaylayacaktır.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="Uygulama iskeleti başarıyla oluşturuldu" />
</div>

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

<Note>
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.
</Note>

---

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

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

```bash filename="Terminal"
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.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/dev.png" alt="Geliştirme modu terminal çıktısı" />
</div>

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

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Your Apps listesinde My twenty app gösteriliyor" />
</div>

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

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Uygulama kaydı ayrıntıları" />
</div>

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

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Yüklü uygulama" />
</div>

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

```bash filename="Terminal"
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.

<Warning>
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](/l/tr/developers/extend/apps/publishing).
</Warning>

---

## 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](/l/tr/developers/extend/apps/building).

## Proje yapısı

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

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

```bash filename="Terminal"
npx create-twenty-app@latest my-twenty-app --example postcard
```

Örnekler [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/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](/l/tr/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add).

---

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

```bash filename="Terminal"
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:

```bash filename="Terminal"
yarn add twenty-sdk twenty-client-sdk
```

`package.json` dosyasına betiği ekleyin:

```json filename="package.json"
{
  "scripts": {
    "twenty": "twenty"
  }
}
```

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

<Note>
`twenty-sdk`'yi global olarak kurmayın — her uygulama kendi sürümünü kullansın diye proje bazında sabitleyin.
</Note>

---

## 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](https://discord.com/channels/1130383047699738754/1130386664812982322) üzerinde yardım isteyin.
