mirror of
https://github.com/twentyhq/twenty.git
synced 2026-04-18 14:01:45 -04:00
287 lines
12 KiB
Plaintext
287 lines
12 KiB
Plaintext
---
|
|
title: Getting Started
|
|
icon: "rocket"
|
|
description: Create your first Twenty app in minutes.
|
|
---
|
|
|
|
<Warning>
|
|
Apps are currently in alpha. The feature works but is still evolving.
|
|
</Warning>
|
|
|
|
## What are apps?
|
|
|
|
Apps let you extend Twenty with custom objects, fields, logic functions, front components, AI skills, and more — all managed as code. Instead of configuring everything through the UI, you define your data model and logic in TypeScript and deploy it to one or more workspaces.
|
|
|
|
## Prerequisites
|
|
|
|
Before you begin, make sure the following is installed on your machine:
|
|
|
|
- **Node.js 24+** — [Download here](https://nodejs.org/)
|
|
- **Yarn 4** — Comes with Node.js via Corepack. Enable it by running `corepack enable`
|
|
- **Docker** — [Download here](https://www.docker.com/products/docker-desktop/). Required to run a local Twenty instance. Not needed if you already have a Twenty server running.
|
|
|
|
## Create your first app
|
|
|
|
### Scaffold your app
|
|
|
|
Open a terminal and run:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app
|
|
```
|
|
|
|
You will be prompted to enter a name and a description for your app. Press **Enter** to accept the defaults.
|
|
|
|
This creates a new folder called `my-twenty-app` with everything you need.
|
|
|
|
### Set up a local Twenty instance
|
|
|
|
The scaffolder will ask:
|
|
|
|
> **Would you like to set up a local Twenty instance?**
|
|
|
|
- **Type `yes`** (recommended) — This pulls the `twenty-app-dev` Docker image and starts a local Twenty server on port `2020`. Make sure Docker is running before you continue.
|
|
- **Type `no`** — Choose this if you already have a Twenty server running locally.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Should start local instance?" />
|
|
</div>
|
|
|
|
### Sign in to your workspace
|
|
|
|
Next, a browser window will open with the Twenty login page. Sign in with the pre-seeded demo account:
|
|
|
|
- **Email:** `tim@apple.dev`
|
|
- **Password:** `tim@apple.dev`
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/login.png" alt="Twenty login screen" />
|
|
</div>
|
|
|
|
### Authorize the app
|
|
|
|
After you sign in, you will see an authorization screen. This lets your app interact with your workspace.
|
|
|
|
Click **Authorize** to continue.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI authorization screen" />
|
|
</div>
|
|
|
|
Once authorized, your terminal will confirm that everything is set up.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App scaffolded successfully" />
|
|
</div>
|
|
|
|
### Start developing
|
|
|
|
Go into your new app folder and start the development server:
|
|
|
|
```bash filename="Terminal"
|
|
cd my-twenty-app
|
|
yarn twenty dev
|
|
```
|
|
|
|
This watches your source files, rebuilds on every change, and syncs your app to the local Twenty server automatically. You should see a live status panel in your terminal.
|
|
|
|
For more detailed output (build logs, sync requests, error traces), use the `--verbose` flag:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty dev --verbose
|
|
```
|
|
|
|
<Warning>
|
|
Dev mode is only available on Twenty instances running in development (`NODE_ENV=development`). Production instances reject dev sync requests. Use `yarn twenty deploy` to deploy to production servers — see [Publishing Apps](/developers/extend/apps/publishing) for details.
|
|
</Warning>
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/dev.jpg" alt="Dev mode terminal output" />
|
|
</div>
|
|
|
|
#### One-shot sync with `yarn twenty dev --once`
|
|
|
|
If you do not want a watcher running in the background (for example in a CI pipeline, a git hook, or a scripted workflow), pass the `--once` flag. It runs the same pipeline as `yarn twenty dev` — build manifest, bundle files, upload, sync, regenerate the typed API client — but **exits as soon as the sync completes**:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty dev --once
|
|
```
|
|
|
|
| Command | Behavior | When to use |
|
|
|---------|----------|-------------|
|
|
| `yarn twenty dev` | Watches your source files and re-syncs on every change. Keeps running until you stop it. | Interactive local development — you want the live status panel and instant feedback loop. |
|
|
| `yarn twenty dev --once` | Performs a single build + sync, then exits with code `0` on success or `1` on failure. | Scripts, CI, pre-commit hooks, AI agents, and any non-interactive workflow. |
|
|
|
|
Both modes require a Twenty server running in development mode and an authenticated remote — the same prerequisites apply.
|
|
|
|
### See your app in Twenty
|
|
|
|
Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) in your browser. Navigate to **Settings > Apps** and select the **Developer** tab. You should see your app listed 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 on **My twenty app** to open its **application registration**. A registration is a server-level record that describes your app — its name, unique identifier, OAuth credentials, and source (local, npm, or tarball). It lives on the server, not inside any specific workspace. When you install an app into a workspace, Twenty creates a workspace-scoped **application** that points back to this registration. 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 installed app. The **About** tab shows the current version and management options:
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Installed app — About tab" />
|
|
</div>
|
|
|
|
Switch to the **Content** tab to see everything your app provides — objects, fields, logic functions, and agents:
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-4.png" alt="Installed app — Content tab" />
|
|
</div>
|
|
|
|
You are all set! Edit any file in `src/` and the changes will be picked up automatically.
|
|
|
|
---
|
|
|
|
## 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** | Define custom data models (like Post Card, Invoice) with typed fields |
|
|
| **Logic functions** | Server-side TypeScript functions 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 for your objects |
|
|
| **Page layouts** | Custom record detail pages with tabs and widgets |
|
|
|
|
Head over to [Building Apps](/developers/extend/apps/building) for a detailed guide on each entity type.
|
|
|
|
---
|
|
|
|
## Project structure
|
|
|
|
The scaffolder generates the following file structure:
|
|
|
|
```text filename="my-twenty-app/"
|
|
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
|
|
```
|
|
|
|
### Starting from an example
|
|
|
|
To start from a more complete example with custom objects, fields, logic functions, front components, and more, use the `--example` flag:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app --example postcard
|
|
```
|
|
|
|
Examples are sourced from the [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) directory on GitHub. You can also scaffold individual entities into an existing project with `yarn twenty add` (see [Building Apps](/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add)).
|
|
|
|
### Key files
|
|
|
|
| File / Folder | Purpose |
|
|
|---|---|
|
|
| `package.json` | Declares your app name, version, and dependencies. Includes a `twenty` script so you can run `yarn twenty help` to see all commands. |
|
|
| `src/application-config.ts` | **Required.** The main configuration file for your app. |
|
|
| `src/default-role.ts` | Default role that controls what your logic functions can access. |
|
|
| `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and app metadata (display name, description). |
|
|
| `src/__tests__/` | Integration tests (setup + example test). |
|
|
| `public/` | Static assets (images, fonts) served with your app. |
|
|
|
|
## Local development server
|
|
|
|
The scaffolder already started a local Twenty server for you. To manage it later, use `yarn twenty server`:
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `yarn twenty server start` | Start the local server (pulls image if needed) |
|
|
| `yarn twenty server start --port 3030` | Start on a custom port |
|
|
| `yarn twenty server start --test` | Start a separate test instance on port 2021 |
|
|
| `yarn twenty server stop` | Stop the server (preserves data) |
|
|
| `yarn twenty server status` | Show server status, URL, and credentials |
|
|
| `yarn twenty server logs` | Stream server logs |
|
|
| `yarn twenty server logs --lines 100` | Show the last 100 log lines |
|
|
| `yarn twenty server reset` | Delete all data and start fresh |
|
|
|
|
Data is persisted across restarts in two Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-storage` for files). Use `reset` to wipe everything and start fresh.
|
|
|
|
### Running a test instance
|
|
|
|
Pass `--test` to any `server` command to manage a second, fully isolated instance — useful for running integration tests or experimenting without touching your main dev data.
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `yarn twenty server start --test` | Start the test instance (defaults to port 2021) |
|
|
| `yarn twenty server stop --test` | Stop the test instance |
|
|
| `yarn twenty server status --test` | Show test instance status, URL, and credentials |
|
|
| `yarn twenty server logs --test` | Stream test instance logs |
|
|
| `yarn twenty server reset --test` | Wipe test data and start fresh |
|
|
|
|
The test instance runs in its own Docker container (`twenty-app-dev-test`) with dedicated volumes (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) and config, so it can run in parallel with your main instance without conflicts. Combine `--test` with `--port` to override the default 2021.
|
|
|
|
<Note>
|
|
The server requires **Docker** to be running. If you see a "Docker not running" error, make sure Docker Desktop (or the Docker daemon) is started.
|
|
</Note>
|
|
|
|
## Manual setup (without the scaffolder)
|
|
|
|
If you prefer to set things up yourself instead of using `create-twenty-app`, you can do it in two steps.
|
|
|
|
**1. Add `twenty-sdk` and `twenty-client-sdk` as dependencies:**
|
|
|
|
```bash filename="Terminal"
|
|
yarn add twenty-sdk twenty-client-sdk
|
|
```
|
|
|
|
**2. Add a `twenty` script to your `package.json`:**
|
|
|
|
```json filename="package.json"
|
|
{
|
|
"scripts": {
|
|
"twenty": "twenty"
|
|
}
|
|
}
|
|
```
|
|
|
|
You can now run `yarn twenty dev`, `yarn twenty help`, and all other commands.
|
|
|
|
<Note>
|
|
Do not install `twenty-sdk` globally. Always use it as a local project dependency so that each project can pin its own version.
|
|
</Note>
|
|
|
|
## Troubleshooting
|
|
|
|
If you run into issues:
|
|
|
|
- Make sure **Docker is running** before starting the scaffolder with a local instance.
|
|
- Make sure you are using **Node.js 24+** (`node -v` to check).
|
|
- Make sure **Corepack is enabled** (`corepack enable`) so Yarn 4 is available.
|
|
- Try deleting `node_modules` and running `yarn install` again if dependencies seem broken.
|
|
|
|
Still stuck? Ask for help on the [Twenty Discord](https://discord.com/channels/1130383047699738754/1130386664812982322).
|