Getting Started & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Twenty is an open-source CRM platform built as a monorepo Nx workspace. The project utilizes a modern tech stack including React, NestJS, PostgreSQL, Redis, and GraphQL. To ensure a consistent experience across various development environments—such as local machines, Cursor, or AI-assisted IDEs—the project provides a unified setup script and standard CLI commands for environment initialization and package management.
The setup process covers the configuration of core infrastructure services (Postgres and Redis), database schema initialization, and the starting of frontend, backend, and background worker services.
Sources: CLAUDE.md:5-9, CLAUDE.md:209-211
Automated Environment Setup
The primary method for initializing the development environment is the setup-dev-env.sh utility script. This script is idempotent and handles infrastructure detection, database creation, environment variable configuration, and schema migrations.
Setup Workflow
The setup script follows a specific logic to prepare the environment:
- Service Detection: Automatically detects if Postgres and Redis are running locally or if they need to be started via Docker.
- Configuration: Copies necessary
.envfiles into the appropriate package directories. - Database Preparation: Creates the required PostgreSQL databases.
- Initialization: Runs migrations to initialize the database schema on fresh installations.
The diagram shows the automated flow of the setup-dev-env.sh script to prepare the CRM for development.
Sources: packages/twenty-utils/setup-dev-env.sh, CLAUDE.md:209-218
Setup Script Flags
| Flag | Description |
|---|---|
--docker | Forces the use of Docker mode (using packages/twenty-docker/docker-compose.dev.yml). |
--down | Stops the running infrastructure services. |
--reset | Wipes existing data and restarts the environment from a fresh state. |
Sources: CLAUDE.md:218-221
Development Operations
Once the environment is initialized, developers use yarn and nx commands to manage the various components of the monorepo.
Core Services Management
The main development environment is started using a single command that launches the frontend, backend, and background workers simultaneously.
# Start full development environment
yarn start
For granular control, individual packages can be started independently:
- Frontend:
npx nx start twenty-front(React server) - Backend:
npx nx start twenty-server(NestJS API) - Worker:
npx nx run twenty-server:worker(BullMQ background processing)
Sources: CLAUDE.md:14-19, CLAUDE.md:162-164
Database Management
Beyond initial setup, several commands are used to manage the PostgreSQL database state and schema transitions.
| Command | Action |
|---|---|
npx nx database:reset twenty-server | Resets the database to a clean state. |
npx nx run twenty-server:database:migrate:prod | Runs migration commands on the production instance. |
| `npx nx run twenty-server:database:migrate:generate --name --type <fast | slow>` |
Sources: CLAUDE.md:65-71
Documentation Setup
The project documentation is a standalone package (twenty-docs) powered by Mintlify. It requires a specific setup to view or edit locally.
Documentation Commands
To run the documentation site locally:
# From the monorepo root
npx nx run twenty-docs:dev
The site becomes available at http://localhost:3000.
Sources: packages/twenty-docs/README.md:16-22
Documentation Architecture
The documentation system relies on a base structure JSON file to define navigation and MDX files for content.
The documentation generation flow ensures that translations are kept in sync with the base structural hierarchy.
Sources: packages/twenty-docs/README.md:46-52
App Development Setup
When developing "Twenty Apps" (modular extensions), specific checks and commands ensure the app is correctly integrated with the local server.
Application Verification
Before making changes to an app, developers must verify the application structure:
- Verify the presence of
package.jsonandsrc/application-config.ts. - Use
yarn twenty dev:addto scaffold new entities (objects, fields, functions). - Perform a "One-shot sync" using
yarn twenty dev --onceto synchronize local app changes with the server remote.
Sources: packages/twenty-codex-plugin/references/develop-app/app-structure.md:7-12, packages/twenty-codex-plugin/AGENTS.md:36-38
Summary
The local setup for Twenty is designed around an idempotent shell script that abstracts infrastructure complexity. By providing a unified path for environment initialization and a standard set of Nx-based commands for service management, the project maintains a strict boundary between infrastructure (handled by twenty-utils), documentation (handled by twenty-docs), and core CRM logic (handled by twenty-server and twenty-front). Developers can reliably transition from a fresh clone to a running environment by executing the setup script and then utilizing yarn start for active development.