f9a24072b7
## Summary Restructures the apps Getting Started doc around the three things a developer actually has to do, so the mental model is visible upfront and discoverable when something goes wrong. **Why this matters:** the previous flow read as one continuous list of bash commands and prompts, which made it easy to miss that scaffolding, running a Twenty server, and live-syncing changes are three separate concepts. When the user hits a failure (Docker not running, server not up, auth not authorized), they have no mental map for which step they're in — so they end up retrying `yarn twenty dev`, which is the only command they remember. ## What changes **[getting-started.mdx](https://github.com/twentyhq/twenty/blob/docs/restructure-getting-started-three-phases/packages/twenty-docs/developers/extend/apps/getting-started.mdx):** - New summary table at the top showing the three-phase arc: | 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 server` | A running Twenty instance | | **3. Sync** | Live-sync your code to the server | `yarn twenty dev` | Your changes appear in the UI | - Three top-level sections, one per phase, each ending with **"After this phase: you have X"** so users can self-diagnose where they got stuck. - Phase 2 leads with the sentence that was missing before: *"Your app needs a Twenty server to sync into. The server is a full Twenty instance — UI, GraphQL API, PostgreSQL — running locally in Docker."* This is the concept new users were missing. - Removed the standalone *What are apps?* section — that's what the Core Concepts page is for. Don't duplicate. - Tightened wording throughout; same screenshots, same callouts, same content depth. **[core-concepts/apps.mdx](https://github.com/twentyhq/twenty/blob/docs/restructure-getting-started-three-phases/packages/twenty-docs/getting-started/core-concepts/apps.mdx):** - Removed the install snippet (`npx create-twenty-app`, `cd`, `yarn twenty dev`) — it duplicated Getting Started and the two examples used different directory names. - Updated the link card to reflect the new three-phase structure. ## Out of scope (mentioned for context, not done here) - The "Docker is not running" message rewrite: separate PR ([#20280](https://github.com/twentyhq/twenty/pull/20280)). - A `yarn twenty start` one-command bootstrap that auto-starts the server before `dev`. Worth doing — keeping it out of this docs PR. - Auto-offering to start the server when `yarn twenty dev` finds no running one. Same. - An "agent path" doc (single-page, imperative, for AI assistants) — separate effort. ## Test plan - [x] `npx nx lint twenty-docs` passes (no new warnings) - [x] All `<Note>`, `<Warning>`, `<Card>`, image refs preserved - [ ] Render and click through both pages once merged and previewed Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
43 lines
2.7 KiB
Plaintext
43 lines
2.7 KiB
Plaintext
---
|
|
title: Apps
|
|
icon: "cube"
|
|
description: Extend Twenty with code — custom objects, server-side logic, UI components, and AI agents, all as TypeScript packages.
|
|
---
|
|
|
|
|
|
Most CRMs give you a config panel. Twenty gives you a platform. Apps are how developers extend Twenty beyond what the UI offers — defining data models, server-side logic, UI components, and AI capabilities as code, then deploying them to one or more workspaces.
|
|
|
|
## Why apps exist
|
|
|
|
Workflows cover no-code automation. But some things need code: a custom pricing engine, a proprietary enrichment pipeline, a compliance check that runs on every record update, a custom UI panel that pulls data from an internal tool.
|
|
|
|
Apps let you build these as first-class extensions — not brittle scripts talking to an API from outside, but code that runs on the platform with full access to the type system, permission model, and UI.
|
|
|
|
## What an app can define
|
|
|
|
An app is a TypeScript package that declares **entities** using the `twenty-sdk`:
|
|
|
|
| Entity | What it does |
|
|
|--------|-------------|
|
|
| **Objects & Fields** | New data tables and fields on existing objects — same treatment as built-in ones |
|
|
| **Logic Functions** | Server-side TypeScript triggered by HTTP routes, cron schedules, or database events |
|
|
| **Front Components** | Sandboxed 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 |
|
|
|
|
Everything is detected via AST analysis at build time — no config files, no registration boilerplate. Put a `export default defineObject(...)` in any `.ts` file and the SDK picks it up.
|
|
|
|
## How they run
|
|
|
|
- **Logic functions** execute in isolated Node.js processes, sandboxed from the host. They access data through a typed API client scoped to the app's role permissions.
|
|
- **Front components** run in Web Workers using Remote DOM — sandboxed from the main page but rendering native DOM elements (not iframes).
|
|
- **Permissions** are enforced at the API level. An app only sees what its role allows.
|
|
|
|
## The developer experience
|
|
|
|
You write your app as a TypeScript project on your machine. The CLI watches your source files and live-syncs them to a running Twenty server — edit a file, see the change in the UI within a second. The typed API client regenerates automatically when the schema changes. When you're ready, `yarn twenty deploy` pushes to a production server, or `yarn twenty publish` lists your app on npm and the Twenty marketplace.
|
|
|
|
<Card title="Build your first app" icon="arrow-right" href="/developers/extend/apps/getting-started">
|
|
Three-phase walkthrough — scaffold, run a local server, sync your changes.
|
|
</Card>
|