---
title: Začínáme
description: Vytvořte svou první aplikaci Twenty během několika minut.
---

<Warning>
Aplikace jsou aktuálně v alfa fázi. Funkce funguje, ale stále se vyvíjí.
</Warning>

Aplikace vám umožňují rozšířit Twenty o vlastní objekty, pole, logické funkce, AI schopnosti a komponenty uživatelského rozhraní — vše je spravováno jako kód.

## Předpoklady

Než začnete, ujistěte se, že máte ve svém počítači nainstalováno následující:

* **Node.js 24+** — [Stáhnout zde](https://nodejs.org/)
* **Yarn 4** — Dodává se s Node.js prostřednictvím Corepacku. Povolte jej spuštěním `corepack enable`
* **Docker** — [Stáhnout zde](https://www.docker.com/products/docker-desktop/). Nutné pro spuštění lokální instance Twenty. Není potřeba, pokud už máte spuštěný server Twenty.

## Krok 1: Vytvořte kostru své aplikace

Otevřete terminál a spusťte:

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

Budete vyzváni k zadání názvu a popisu své aplikace. Stisknutím **Enter** přijmete výchozí hodnoty.

Tím se vytvoří nová složka s názvem `my-twenty-app` se vším potřebným.

<Note>
Generátor kostry podporuje tyto přepínače:

* `--minimal` — vygeneruje pouze nezbytné soubory, bez příkladů (výchozí)
* `--exhaustive` — vygeneruje všechny ukázkové entity
* `--name <name>` — nastaví název aplikace (přeskočí výzvu)
* `--display-name <displayName>` — nastaví zobrazovaný název (přeskočí výzvu)
* `--description <description>` — nastaví popis (přeskočí výzvu)
* `--skip-local-instance` — přeskočí výzvu k nastavení lokálního serveru
</Note>

## Krok 2: Nastavte lokální instanci Twenty

Generátor kostry se zeptá:

> **Chcete nastavit lokální instanci Twenty?**

* **Zadejte `yes`** (doporučeno) — Stáhne image Dockeru `twenty-app-dev` a spustí lokální server Twenty na portu `2020`. Než budete pokračovat, ujistěte se, že Docker běží.
* **Zadejte `no`** — Zvolte, pokud už máte lokálně spuštěný server Twenty.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/start-instance.png" alt="Spustit lokální instanci?" />
</div>

## Krok 3: Přihlaste se do svého pracovního prostoru

Poté se otevře okno prohlížeče se stránkou přihlášení do Twenty. Přihlaste se předpřipraveným demo účtem:

* **E-mail:** `tim@apple.dev`
* **Heslo:** `tim@apple.dev`

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/login.png" alt="Přihlašovací obrazovka Twenty" />
</div>

## Krok 4: Autorizujte aplikaci

Po přihlášení uvidíte autorizační obrazovku. Tím umožníte vaší aplikaci pracovat s vaším pracovním prostorem.

Pokračujte kliknutím na **Authorize**.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Autorizační obrazovka Twenty CLI" />
</div>

Po autorizaci váš terminál potvrdí, že je vše nastaveno.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="Aplikace byla úspěšně vygenerována" />
</div>

## Krok 5: Začněte vyvíjet

Přejděte do nové složky aplikace a spusťte vývojový server:

```bash filename="Terminal"
cd my-twenty-app
yarn twenty dev
```

Sleduje zdrojové soubory, při každé změně znovu sestaví a automaticky synchronizuje vaši aplikaci s lokálním serverem Twenty. V terminálu byste měli vidět panel se stavem v reálném čase.

Pro podrobnější výstup (protokoly sestavení, požadavky na synchronizaci, stopy chyb) použijte přepínač `--verbose`:

```bash filename="Terminal"
yarn twenty dev --verbose
```

<Warning>
Vývojový režim je k dispozici pouze na instancích Twenty běžících v režimu development (`NODE_ENV=development`). Produkční instance odmítají požadavky na vývojovou synchronizaci. Pro nasazení na produkční servery použijte `yarn twenty deploy` — podrobnosti viz [Publikování aplikací](/l/cs/developers/extend/apps/publishing).
</Warning>

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/dev.jpg" alt="Výstup terminálu ve vývojovém režimu" />
</div>

## Krok 6: Zobrazte svou aplikaci v Twenty

Otevřete ve svém prohlížeči [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Přejděte do **Settings > Apps** a vyberte kartu **Developer**. Vaše aplikace by měla být uvedena v části **Your Apps**:

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

Klikněte na **My twenty app** a otevřete její **registraci aplikace**. Registrace je záznam na úrovni serveru, který popisuje vaši aplikaci — její název, jedinečný identifikátor, přihlašovací údaje OAuth a zdroj (lokální, npm nebo tarball). Existuje na serveru, ne uvnitř žádného konkrétního pracovního prostoru. Když nainstalujete aplikaci do pracovního prostoru, Twenty vytvoří **aplikaci** v rozsahu pracovního prostoru, která odkazuje zpět na tuto registraci. Jedna registrace může být nainstalována ve více pracovních prostorech na stejném serveru.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Podrobnosti registrace aplikace" />
</div>

Klikněte na **View installed app**, abyste zobrazili nainstalovanou aplikaci. Karta **About** zobrazuje aktuální verzi a možnosti správy:

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Nainstalovaná aplikace — karta About" />
</div>

Přepněte na kartu **Content**, abyste viděli vše, co vaše aplikace poskytuje — objekty, pole, logické funkce a agenty:

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-4.png" alt="Nainstalovaná aplikace — karta Content" />
</div>

Vše je připraveno! Upravte libovolný soubor v `src/` a změny se automaticky projeví.

Přejděte na [Tvorba aplikací](/l/cs/developers/extend/apps/building) pro podrobný průvodce vytvářením objektů, logických funkcí, frontendových komponent, dovedností a dalšího.

---

## Struktura projektu

Generátor kostry vytvoří následující strukturu souborů (zobrazeno v režimu `--exhaustive`, který zahrnuje příklady pro každý typ entity):

```text filename="my-twenty-app/"
my-twenty-app/
  package.json
  yarn.lock
  .gitignore
  .nvmrc
  .yarnrc.yml
  .yarn/
    install-state.gz
  .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
  ├── __tests__/
  │   ├── setup-test.ts                   # Test setup (server health check, config)
  │   └── app-install.integration-test.ts # Example integration test
  ├── 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
  │   ├── create-hello-world-company.ts   # Example logic function using CoreApiClient
  │   ├── pre-install.ts                  # Runs before installation
  │   └── post-install.ts                 # Runs after installation
  ├── front-components/
  │   └── hello-world.tsx                 # Example front component
  ├── page-layouts/
  │   └── example-record-page-layout.ts   # Example page layout with 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
  └── agents/
      └── example-agent.ts                # Example AI agent definition
```

Ve výchozím nastavení (`--minimal`) se vytvoří pouze základní soubory: `application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts` a `logic-functions/post-install.ts`. Pro zahrnutí všech ukázkových souborů výše použijte `--exhaustive`.

### Klíčové soubory

| Soubor / Složka              | Účel                                                                                                                                            |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `package.json`               | Definuje název, verzi a závislosti vaší aplikace. Obsahuje skript `twenty`, takže můžete spustit `yarn twenty help` a zobrazit všechny příkazy. |
| `src/application-config.ts`  | **Povinné.** Hlavní konfigurační soubor vaší aplikace.                                                                                          |
| `src/roles/`                 | Definuje role, které určují, k čemu mají vaše logické funkce přístup.                                                                           |
| `src/logic-functions/`       | Serverové funkce spouštěné trasami, plánovačem cron nebo událostmi databáze.                                                                    |
| `src/front-components/`      | Komponenty Reactu, které se vykreslují uvnitř uživatelského rozhraní Twenty.                                                                    |
| `src/objects/`               | Vlastní definice objektů pro rozšíření vašeho datového modelu.                                                                                  |
| `src/fields/`                | Vlastní pole přidaná k existujícím objektům.                                                                                                    |
| `src/views/`                 | Konfigurace uložených zobrazení.                                                                                                                |
| `src/navigation-menu-items/` | Vlastní odkazy v postranní navigaci.                                                                                                            |
| `src/skills/`                | Dovednosti, které rozšiřují možnosti AI agentů Twenty.                                                                                          |
| `src/agents/`                | AI agenti s vlastními prompty.                                                                                                                  |
| `src/page-layouts/`          | Vlastní rozvržení stránek pro zobrazení záznamů.                                                                                                |
| `src/__tests__/`             | Integrační testy (nastavení + ukázkový test).                                                                                                   |
| `public/`                    | Statická aktiva (obrázky, písma) poskytovaná s vaší aplikací.                                                                                   |

## Správa vzdálených serverů

**Remote** je server Twenty, ke kterému se vaše aplikace připojuje. Během nastavení jej generátor kostry automaticky vytvoří. Můžete kdykoli přidat další vzdálené servery nebo mezi nimi přepínat.

```bash filename="Terminal"
# Add a new remote (opens a browser for OAuth login)
yarn twenty remote add

# Connect to a local Twenty server (auto-detects port 2020 or 3000)
yarn twenty remote add --local

# Add a remote non-interactively (useful for CI)
yarn twenty remote add --api-url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote

# List all configured remotes
yarn twenty remote list

# Switch the active remote
yarn twenty remote switch <name>
```

Vaše přihlašovací údaje jsou uloženy v `~/.twenty/config.json`.

## Lokální vývojový server (`yarn twenty server`)

CLI může spravovat lokální server Twenty běžící v Dockeru. Jde o stejný server, který se spustí automaticky při vytvoření kostry aplikace pomocí `create-twenty-app`, ale můžete jej spravovat i ručně.

### Spuštění serveru

```bash filename="Terminal"
yarn twenty server start
```

Stáhne image Dockeru `twentycrm/twenty-app-dev:latest` (pokud již není k dispozici), vytvoří kontejner s názvem `twenty-app-dev` a spustí jej na portu **2020**. CLI čeká, dokud server neprojde kontrolou stavu, než vrátí řízení.

Vytvoří se dva svazky Dockeru pro zachování dat mezi restartováními:

* `twenty-app-dev-data` — databáze PostgreSQL
* `twenty-app-dev-storage` — úložiště souborů

Pokud je port 2020 již používán, můžete spustit na jiném portu:

```bash filename="Terminal"
yarn twenty server start --port 3030
```

CLI automaticky nakonfiguruje interní `NODE_PORT` a `SERVER_URL` kontejneru tak, aby odpovídaly zvolenému portu, takže logické funkce, OAuth a veškerá ostatní vnitřní síťová komunikace fungují správně.

Po spuštění je server automaticky zaregistrován jako `local` remote ve vaší konfiguraci CLI.

### Kontrola stavu serveru

```bash filename="Terminal"
yarn twenty server status
```

Zobrazí, zda server běží, jeho URL a výchozí přihlašovací údaje (`tim@apple.dev` / `tim@apple.dev`).

### Zobrazení protokolů serveru

```bash filename="Terminal"
yarn twenty server logs
```

Streamuje protokoly kontejneru. Pomocí `--lines` ovládnete, kolik posledních řádků se má zobrazit:

```bash filename="Terminal"
yarn twenty server logs --lines 100
```

### Zastavení serveru

```bash filename="Terminal"
yarn twenty server stop
```

Zastaví kontejner. Vaše data jsou zachována ve svazcích Dockeru — další `start` naváže tam, kde jste skončili.

### Resetování serveru

```bash filename="Terminal"
yarn twenty server reset
```

Odstraní kontejner **a** smaže oba svazky Dockeru, čímž vymaže všechna data. Další `start` vytvoří čistou instanci.

<Note>
  Server vyžaduje, aby **Docker** běžel. Pokud vidíte chybu "Docker not running", ujistěte se, že je spuštěný Docker Desktop (nebo démon Dockeru).
</Note>

### Přehled příkazů

| Příkaz                                 | Popis                                                  |
| -------------------------------------- | ------------------------------------------------------ |
| `yarn twenty server start`             | Spustí lokální server (v případě potřeby stáhne image) |
| `yarn twenty server start --port 3030` | Spustí na vlastním portu                               |
| `yarn twenty server stop`              | Zastaví server (zachová data)                          |
| `yarn twenty server status`            | Zobrazí stav serveru, URL a přihlašovací údaje         |
| `yarn twenty server logs`              | Streamuje protokoly serveru                            |
| `yarn twenty server logs --lines 100`  | Zobrazí posledních 100 řádků logu                      |
| `yarn twenty server reset`             | Smaže všechna data a začne znovu                       |

## CI s GitHub Actions

Generátor kostry vytvoří připravený k použití workflow GitHub Actions v `.github/workflows/ci.yml`. Automaticky spouští integrační testy při každém pushi do `main` a u pull requestů.

Workflow:

1. Načte váš kód (checkout).
2. Spustí dočasný server Twenty pomocí akce `twentyhq/twenty/.github/actions/spawn-twenty-docker-image`
3. Nainstaluje závislosti pomocí `yarn install --immutable`
4. Spustí `yarn test` s proměnnými `TWENTY_API_URL` a `TWENTY_API_KEY` vloženými z výstupů akce

```yaml .github/workflows/ci.yml
name: CI

on:
  push:
    branches:
      - main
  pull_request: {}

env:
  TWENTY_VERSION: latest

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Spawn Twenty instance
        id: twenty
        uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main
        with:
          twenty-version: ${{ env.TWENTY_VERSION }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Enable Corepack
        run: corepack enable

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: '.nvmrc'
          cache: 'yarn'

      - name: Install dependencies
        run: yarn install --immutable

      - name: Run integration tests
        run: yarn test
        env:
          TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }}
          TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }}
```

Není potřeba konfigurovat žádné secrets — akce `spawn-twenty-docker-image` spustí efemérní server Twenty přímo v runneru a vypíše podrobnosti připojení. Secret `GITHUB_TOKEN` je poskytován GitHubem automaticky.

Chcete-li připnout konkrétní verzi Twenty místo `latest`, změňte proměnnou prostředí `TWENTY_VERSION` na začátku workflow.

## Ruční nastavení (bez scaffolderu)

Pokud dáváte přednost vlastnímu nastavení místo použití `create-twenty-app`, můžete to udělat ve dvou krocích.

**1. Přidejte `twenty-sdk` a `twenty-client-sdk` jako závislosti:**

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

**2. Přidejte skript `twenty` do svého `package.json`:**

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

Nyní můžete spouštět `yarn twenty dev`, `yarn twenty help` a všechny ostatní příkazy.

<Note>
Neinstalujte `twenty-sdk` globálně. Vždy jej používejte jako lokální závislost projektu, aby si každý projekt mohl připnout svou vlastní verzi.
</Note>

## Řešení potíží

Pokud narazíte na potíže:

* Před spuštěním generátoru kostry s lokální instancí se ujistěte, že **Docker běží**.
* Ujistěte se, že používáte **Node.js 24+** (ověříte příkazem `node -v`).
* Ujistěte se, že je **Corepack povolen** (`corepack enable`), aby byl k dispozici Yarn 4.
* Zkuste smazat `node_modules` a znovu spustit `yarn install`, pokud se zdají závislosti poškozené.

Pořád se nedaří? Požádejte o pomoc na [Discordu Twenty](https://discord.com/channels/1130383047699738754/1130386664812982322).
