twenty/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx

---
title: Quick Start
icon: "rocket"
description: Create your first Twenty app in minutes.
---

## Prerequisites

- **Node.js 24.5+** — [Download](https://nodejs.org/)
- **Yarn 4** — bundled with Node via Corepack. Enable it: `corepack enable`
- **Docker** — [Download](https://www.docker.com/products/docker-desktop/). Needed to run a local Twenty server. Skip if you already have Twenty running elsewhere.

Building a Twenty app has three phases. The scaffolder collapses them into one happy-path command, but each phase is a separate concept — when something fails, knowing which phase you're in tells you what to fix.

| Phase | What you do | Tool | Result |
|---|---|---|---|
| **1. Scaffold** | Generate the app's source code | `npx create-twenty-app` | A TypeScript project on disk |
| **2. Run a server** | Start a Twenty server to sync into | Docker + `yarn twenty docker:start` | A running Twenty instance |
| **3. Sync** | Live-sync your code to the server | `yarn twenty dev` | Your changes appear in the UI |

---

## Phase 1 — Scaffold your project

Create a new app from the template:

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

The scaffolder is non-interactive: the directory name becomes the app name. Pass `--display-name` and `--description` to customize the generated metadata (you can also edit it later in `src/constants/universal-identifiers.ts`). This generates a TypeScript project in `my-twenty-app/` with a starter `application-config.ts`, a default role, CI/CD workflows, and an integration test.

**After this phase:** you have an app's source code on your machine. It isn't running yet — that's Phase 2.

---

## Phase 2 — Run a local Twenty server

Your app needs a Twenty server to sync into. The server is a full Twenty instance — UI, GraphQL API, PostgreSQL — running locally in Docker. Your local code uploads its definitions to that server, which makes them appear in the UI.

The scaffolder starts one for you: with Docker running, it pulls the `twentycrm/twenty-app-dev` image, starts it on port `2020`, and authenticates the CLI against the pre-seeded demo workspace (`tim@apple.dev`) — no sign-in required.

To connect to an existing Twenty server instead, pass `--url <your-server-url>`. Remote servers authenticate with OAuth: a browser opens so you can sign in and click **Authorize**, which gives the CLI access to your workspace. (You can also opt into OAuth locally with `--authentication-method oauth` — sign in with `tim@apple.dev` / `tim@apple.dev`.)

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/login.png" alt="Twenty login screen" />
</div>

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

Your terminal will confirm everything is set up.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App scaffolded successfully" />
</div>

**After this phase:** you have a running Twenty server at [http://localhost:2020](http://localhost:2020) with your CLI authorized to sync to it.

<Note>
If Docker isn't installed or running, the scaffolder will tell you the right start command for your OS. Once Docker is up, you can resume with `yarn twenty docker:start` — no need to re-scaffold.
</Note>

---

## Phase 3 — Sync your changes

This is the inner loop you'll spend most of your time in.

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

This watches `src/`, rebuilds on every change, and syncs the result to the server. Edit a file, save, and within a few seconds the server reflects the change. You'll see a live status panel in your terminal.

For more detailed output (build logs, sync requests, error traces), add `--verbose`.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/dev.png" alt="Dev mode terminal output" />
</div>

Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). You should see your app under **Your Apps**.

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

Click **My twenty app** to see its **application registration** — a server-level record describing your app (name, identifier, OAuth credentials, source). One registration can be installed across multiple workspaces on the same server.

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

Click **View installed app** to see the workspace install. The **About** tab shows version and management options.

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

**After this phase:** you have a live development loop. Edit any file in `src/` and it appears in the UI.

### One-shot sync for CI and scripts

Use `plan` and `apply` to run the same pipeline once, without a watcher:

```bash filename="Terminal"
yarn twenty plan   # preview the metadata changes without applying them
yarn twenty apply  # show the plan, then apply it
```

| Command | Behavior | When to use |
|---------|----------|-------------|
| `yarn twenty dev` | Watches and re-syncs on every change. Runs until you stop it. | Interactive local development. |
| `yarn twenty apply` | Single build + sync, exits `0` on success, `1` on failure. Asks for confirmation on destructive changes (pass `--force` to skip). | CI, pre-commit hooks, AI agents, scripted workflows. |
| `yarn twenty plan` | Builds and prints the metadata changes **without applying them**. | Inspecting what a sync would change before committing to it. |

All modes need an authenticated remote. See [Syncing & recovery](/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan) for more on `plan`.

<Note>
`yarn twenty dev --once` and `yarn twenty dev --once --dry-run` are deprecated aliases for `yarn twenty apply` and `yarn twenty plan`.
</Note>

### Dev mode options

| Flag | Description |
|------|-------------|
| `--force` | Apply destructive changes (deletes) without confirmation. |
| `--debounceMs <ms>` | Set the file-change debounce delay in milliseconds (default: `1000`). |
| `--verbose` / `--debug` | Show detailed build logs, sync requests, and error traces. |

## What you can build

Apps are composed of **entities** — each defined as a TypeScript file with a single `export default`:

| Entity | What it does |
|--------|-------------|
| **Objects & Fields** | Custom data models (Post Card, Invoice, etc.) with typed fields |
| **Logic functions** | Server-side TypeScript triggered by HTTP routes, cron schedules, or database events |
| **Front components** | React components that render inside Twenty's UI (side panel, widgets, command menu) |
| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |
| **Views & Navigation** | Pre-configured list views and sidebar menu items |
| **Page layouts** | Custom record detail pages with tabs and widgets |

Full reference: [Concepts](/developers/extend/apps/getting-started/concepts).

## Next steps

<CardGroup cols={2}>
  <Card title="Config" icon="screwdriver-wrench" href="/developers/extend/apps/config/overview">
    Application identity, default role, install and uninstall hooks, public assets.
  </Card>
  <Card title="Data" icon="database" href="/developers/extend/apps/data/overview">
    Objects, fields, and bidirectional relations.
  </Card>
  <Card title="Logic" icon="bolt" href="/developers/extend/apps/logic/overview">
    Logic functions, skills, agents, and OAuth connections.
  </Card>
  <Card title="Layout" icon="table-columns" href="/developers/extend/apps/layout/overview">
    Views, navigation, page layouts, front components.
  </Card>
  <Card title="Operations" icon="rocket" href="/developers/extend/apps/operations/overview">
    CLI, testing, remotes, CI, and publishing your app.
  </Card>
</CardGroup>