Monorepo & Nx Workspace

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• nx.json
• package.json
• packages/twenty-docs/README.md
• .cursor/rules/nx-rules.mdc
• packages/twenty-codex-plugin/CHANGELOG.md

Twenty is an open-source CRM built using a monorepo structure managed by Nx and Yarn 4. This architecture allows multiple related packages—including the frontend, backend server, shared libraries, and documentation—to coexist in a single repository while sharing configuration, types, and build pipelines.

Sources: CLAUDE.md:7-9, package.json:173

Workspace Architecture

The workspace is organized into discrete packages located under the packages/ directory. Each package serves a specific role in the ecosystem, ranging from the core API to consumer-facing applications and developer tools.

Core Package Structure

Package	Description
twenty-front	React frontend application built with Vite and React 18.
twenty-server	NestJS backend API using TypeORM and PostgreSQL.
twenty-ui	Shared UI component library.
twenty-shared	Common types, utilities, and helper functions.
twenty-docs	Documentation website powered by Mintlify.
twenty-emails	Email templates built with React Email.
twenty-website	Next.js marketing website.
twenty-zapier	Integration package for the Zapier platform.
twenty-e2e-testing	End-to-end test suites using Playwright.

Sources: CLAUDE.md:83-93, packages/twenty-docs/README.md:1-5

Workspace Dependency Flow

The following diagram illustrates the build dependency flow where lower-level utility packages must be established before consumer applications.

The build order is critical; specifically, twenty-shared must be built before twenty-front or twenty-server.
Sources: CLAUDE.md:46-50, CLAUDE.md:86-87

Nx Configuration and Task Running

Nx is used to orchestrate tasks across the monorepo. It defines how targets like build, test, lint, and typecheck are executed and how results are cached.

Task Definitions

Tasks are configured in nx.json with specific target defaults. Many tasks utilize the ^ symbol to indicate that they depend on the same task being completed in the package's dependencies first.

Target	Cacheable	Dependencies
build	Yes	^build
test	Yes	^build
lint	Yes	None
typecheck	Yes	^build

Sources: nx.json:4-44

Common Commands

Nx allows developers to run commands globally or targeting specific packages using the npx nx <target> <project> syntax.

# General Package Development
npx nx start twenty-front     # Start frontend
npx nx start twenty-server    # Start backend

# Testing
npx nx test twenty-front      # Run frontend tests
npx nx test twenty-server     # Run backend tests

# Quality & Formatting
npx nx lint twenty-front      # Lint frontend
npx nx typecheck twenty-server # Typecheck backend
npx nx fmt twenty-front       # Format code

Sources: CLAUDE.md:14-25, CLAUDE.md:37-43

Development Workflow and Rules

The workspace enforces strict development standards to maintain code quality across all packages. These are codified in .cursor/rules/nx-rules.mdc and global configuration files.

Project Restrictions

• New Projects: Creating new projects or packages requires explicit user permission.
• Dependency Management: Direct modification of workspace.json or angular.json (if present) is prohibited; configuration should happen in project.json or nx.json.
• Code Generation: Developers are encouraged to use Nx generators for creating components, libraries, or applications to ensure consistency.

Sources: .cursor/rules/nx-rules.mdc:1-15

Multi-tenant Database Management

The workspace includes specialized Nx targets for managing a multi-tenant PostgreSQL database.

• database:reset: Wipes and resets the database.
• database:migrate:generate: Generates instance commands for schema changes.
• database:migrate:prod: Runs fast migrations in production environments.

Sources: CLAUDE.md:52-60

Documentation and Tooling

The documentation system itself is integrated into the monorepo as twenty-docs. It uses Nx to handle validation and local development.

Docs Management

• Local Dev: Run via npx nx run twenty-docs:dev.
• Validation: Documentation integrity is checked using npx nx run twenty-docs:validate.
• Translations: Uses a centralized navigation/base-structure.json as the source of truth for the site hierarchy, which is then used to generate translation templates for Crowdin.

Sources: packages/twenty-docs/README.md:15-38, packages/twenty-docs/README.md:73-75

Codex Plugin Integration

The twenty-codex-plugin is another specialized package within the monorepo that provides AI skills and agents to help developers manage the workspace. It includes Nx targets for validation (yarn workspace twenty-codex-plugin validate) and testing.
Sources: packages/twenty-codex-plugin/CHANGELOG.md:11-15

Conclusion

The Twenty monorepo leverages Nx to solve the complexities of a large-scale open-source project. By compartmentalizing logic into specific packages like twenty-shared and twenty-ui while using Nx for task orchestration, the project maintains a fast development cycle with robust caching and dependency management. This structure ensures that both the core CRM and its surrounding developer tools, such as the Codex plugin and documentation site, evolve in a synchronized manner.