snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/developers/contribute/capabilities/backend-development/best-practices-server.mdx

@@ -0,0 +1,24 @@
+---
+title: Best Practices
+---
+
+
+This document outlines the best practices you should follow when working on the backend.
+
+## Follow a modular approach
+
+The backend follows a modular approach, which is a fundamental principle when working with NestJS. Make sure you break down your code into reusable modules to maintain a clean and organized codebase.
+Each module should encapsulate a particular feature or functionality and have a well-defined scope. This modular approach enables clear separation of concerns and removes unnecessary complexities.
+
+## Expose services to use in modules
+
+Always create services that have a clear and single responsibility, which enhances code readability and maintainability. Name the services descriptively and consistently.
+
+You should also expose services that you want to use in other modules. Exposing services to other modules is possible through NestJS's powerful dependency injection system, and promotes loose coupling between components.
+
+## Avoid using `any` type
+
+When you declare a variable as `any`, TypeScript's type checker doesn't perform any type checking, making it possible to assign any type of values to the variable. TypeScript uses type inference to determine the type of variable based on the value. By declaring it as `any`, TypeScript can no longer infer the type. This makes it hard to catch type-related errors during development, leading to runtime errors and makes the code less maintainable, less reliable, and harder to understand for others.
+
+This is why everything should have a type. So if you create a new object with a first name and last name, you should create an interface or type that contains a first name and last name that defines the shape of the object you are manipulating.
+

packages/twenty-docs/developers/contribute/capabilities/backend-development/custom-objects.mdx

@@ -0,0 +1,41 @@
+---
+title: Custom Objects
+---
+
+
+Objects are structures that allow you to store data (records, attributes, and values) specific to an organization. Twenty provides both standard and custom objects.
+
+Standard objects are in-built objects with a set of attributes available for all users. Examples of standard objects in Twenty include Company and Person. Standard objects have standard fields that are also available for all Twenty users, like Company.displayName.
+
+Custom objects are objects that you can create to store information that is unique to your organization. They are not built-in; members of your workspace can create and customize custom objects to hold information that standard objects aren't suitable for.
+
+
+## High-level schema
+
+<div style={{textAlign: 'center'}}>
+    <img src="/images/docs/server/custom-object-schema.png" alt="High level schema" />
+</div>
+
+<br/>
+
+## How it works
+
+Custom objects come from metadata tables that determine the shape, name, and type of the objects. All this information is present in the metadata schema database, consisting of tables:
+
+- **DataSource**: Details where the data is present.
+- **Object**: Describes the object and links to a DataSource.
+- **Field**: Outlines an Object's fields and connects to the Object.
+
+To add a custom object, the workspaceMember will query the /metadata API. This updates the metadata accordingly and computes a GraphQL schema based on the metadata, storing it in a GQL cache for later use.
+<div style={{textAlign: 'center'}}>
+    <img src="/images/docs/server/add-custom-objects.jpeg" alt="Query the /metadata API to add custom objects" />
+</div>
+
+<br/>
+
+To fetch data, the process involves making queries through the /graphql endpoint and passing them through the Query Resolver.
+<div style={{textAlign: 'center'}}>
+    <img src="/images/docs/server/custom-object-schema.png" alt="Query the /graphql endpoint to fetch data" />
+</div>
+
+

packages/twenty-docs/developers/contribute/capabilities/backend-development/feature-flags.mdx

@@ -0,0 +1,51 @@
+---
+title: Feature Flags
+---
+
+
+Feature flags are used to hide experimental features. For Twenty, they are set on workspace level and not on a user level.
+
+## Adding a new feature flag
+
+In `FeatureFlagKey.ts` add the feature flag:
+
+```ts
+type FeatureFlagKey =
+  | 'IS_FEATURENAME_ENABLED'
+  | ...;
+```
+
+Also add it to the enum in `feature-flag.entity.ts`:
+
+```ts
+enum FeatureFlagKeys {
+    IsFeatureNameEnabled = 'IS_FEATURENAME_ENABLED',
+    ...
+}
+```
+
+
+
+To apply a feature flag on a **backend** feature use:
+
+```ts
+@Gate({
+  featureFlag: 'IS_FEATURENAME_ENABLED',
+})
+```
+
+To apply a feature flag on a **frontend** feature use:
+
+```ts
+const isFeatureNameEnabled = useIsFeatureEnabled('IS_FEATURENAME_ENABLED');
+```
+
+
+## Configure feature flags for the deployment
+
+Change the corresponding record in the Table `core.featureFlag`:
+
+| id       | key                      | workspaceId   | value  |
+|----------|--------------------------|---------------|--------|
+|  Random  | `IS_FEATURENAME_ENABLED` |  WorkspaceID  | `true` |
+

packages/twenty-docs/developers/contribute/capabilities/backend-development/folder-architecture-server.mdx

@@ -0,0 +1,127 @@
+---
+title: Folder Architecture
+info: A detailed look into our server folder architecture
+---
+
+
+The backend directory structure is as follows:
+
+```
+server
+  └───ability
+  └───constants
+  └───core
+  └───database
+  └───decorators
+  └───filters
+  └───guards
+  └───health
+  └───integrations
+  └───metadata
+  └───workspace
+  └───utils
+```
+
+## Ability
+
+Defines permissions and includes handlers for each entity.
+
+## Decorators
+
+Defines custom decorators in NestJS for added functionality.
+
+See [custom decorators](https://docs.nestjs.com/custom-decorators) for more details.
+
+## Filters
+
+Includes exception filters to handle exceptions that might occur in GraphQL endpoints.
+
+## Guards
+
+See [guards](https://docs.nestjs.com/guards) for more details.
+
+## Health
+
+Includes a publicly available REST API (healthz) that returns a JSON to confirm whether the database is working as expected.
+
+## Metadata
+
+Defines custom objects and makes available a GraphQL API (graphql/metadata).
+
+## Workspace
+
+Generates and serves custom GraphQL schema based on the metadata.
+
+### Workspace Directory Structure
+
+```
+workspace
+
+  └───workspace-schema-builder
+    └───factories
+    └───graphql-types
+    └───database
+    └───interfaces
+    └───object-definitions
+    └───services
+    └───storage
+    └───utils
+  └───workspace-resolver-builder
+    └───factories
+    └───interfaces
+  └───workspace-query-builder
+    └───factories
+    └───interfaces
+  └───workspace-query-runner
+    └───interfaces
+    └───utils
+  └───workspace-datasource
+  └───workspace-manager
+  └───workspace-migration-runner
+  └───utils
+  └───workspace.module.ts
+  └───workspace.factory.spec.ts
+  └───workspace.factory.ts
+```
+
+
+The root of the workspace directory includes the `workspace.factory.ts`, a file containing the `createGraphQLSchema` function. This function generates workspace-specific schema by using the metadata to tailor a schema for individual workspaces. By separating the schema and resolver construction, we use the `makeExecutableSchema` function, which combines these discrete elements.
+
+This strategy is not just about organization, but also helps with optimization, such as caching generated type definitions to enhance performance and scalability.
+
+### Workspace Schema builder
+
+Generates the GraphQL schema, and includes:
+
+#### Factories:
+
+Specialised constructors to generate GraphQL-related constructs.
+- The type.factory translates field metadata into GraphQL types using `TypeMapperService`.
+- The type-definition.factory creates GraphQL input or output objects derived from `objectMetadata`.
+
+#### GraphQL Types
+
+Includes enumerations, inputs, objects, and scalars, and serves as the building blocks for the schema construction.
+
+#### Interfaces and Object Definitions
+
+Contains the blueprints for GraphQL entities, and includes both predefined and custom types like `MONEY` or `URL`.
+
+#### Services
+
+Contains the service responsible for associating FieldMetadataType with its appropriate GraphQL scalar or query modifiers.
+
+#### Storage
+
+Includes the `TypeDefinitionsStorage` class that contains reusable type definitions, preventing duplication of GraphQL types.
+
+### Workspace Resolver Builder
+
+Creates resolver functions for querying and mutating the GraphQL schema.
+
+Each factory in this directory is responsible for producing a distinct resolver type, such as the `FindManyResolverFactory`, designed for adaptable application across various tables.
+
+### Workspace Query Runner
+
+Runs the generated queries on the database and parses the result.
+

packages/twenty-docs/developers/contribute/capabilities/backend-development/queue.mdx

@@ -0,0 +1,43 @@
+---
+title: Message Queue
+---
+
+
+Queues facilitate async operations to be performed. They can be used for performing background tasks such as sending a welcome email on register.
+Each use case will have its own queue class extended from `MessageQueueServiceBase`.
+
+Currently, we only support `bull-mq`[bull-mq](https://bullmq.io/) as the queue driver.
+
+## Steps to create and use a new queue
+
+1. Add a queue name for your new queue under enum `MESSAGE_QUEUES`.
+2. Provide the factory implementation of the queue with the queue name as the dependency token.
+3. Inject the queue that you created in the required module/service with the queue name as the dependency token.
+4. Add worker class with token based injection just like producer.
+
+### Example usage
+```ts
+class Resolver {
+  constructor(@Inject(MESSAGE_QUEUES.custom) private queue: MessageQueueService) {}
+
+  async onSomeAction() {
+    //business logic
+    await this.queue.add(someData);
+  }
+}
+
+//async worker
+class CustomWorker {
+  constructor(@Inject(MESSAGE_QUEUES.custom) private queue: MessageQueueService) {
+    this.initWorker();
+  }
+
+  async initWorker() {
+    await this.queue.work(async ({ id, data }) => {
+      //worker logic
+    });
+  }
+}
+```
+
+

packages/twenty-docs/developers/contribute/capabilities/backend-development/server-commands.mdx

@@ -0,0 +1,84 @@
+---
+title: Backend Commands
+icon: "terminal"
+---
+
+
+## Useful commands
+
+These commands should be executed from packages/twenty-server folder.
+From any other folder you can run `npx nx {command} twenty-server` (or `npx nx run twenty-server:{command}`).
+
+### First time setup
+
+```
+npx nx database:reset twenty-server # setup the database with dev seeds
+```
+
+### Starting the server
+
+```
+npx nx run twenty-server:start
+```
+
+### Lint
+
+```
+npx nx run twenty-server:lint # pass --fix to fix lint errors
+```
+
+### Test
+
+```
+npx nx run twenty-server:test:unit          # run unit tests
+npx nx run twenty-server:test:integration   # run integration tests
+```
+Note: you can run `npx nx run twenty-server:test:integration:with-db-reset` in case you need to reset the database before running the integration tests.
+
+### Resetting the database
+
+If you want to reset and seed the database, you can run the following command:
+
+```bash
+npx nx run twenty-server:database:reset
+```
+
+### Migrations
+
+#### For objects in Core/Metadata schemas (TypeORM)
+
+```bash
+npx nx run twenty-server:database:migrate:generate
+```
+
+## Tech Stack
+
+Twenty primarily uses NestJS for the backend.
+
+Prisma was the first ORM we used. But in order to allow users to create custom fields and custom objects, a lower-level made more sense as we need to have fine-grained control. The project now uses TypeORM.
+
+Here's what the tech stack now looks like.
+
+
+**Core**
+- [NestJS](https://nestjs.com/)
+- [TypeORM](https://typeorm.io/)
+- [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server)
+
+**Database**
+- [Postgres](https://www.postgresql.org/)
+
+**Third-party integrations**
+- [Sentry](https://sentry.io/welcome/) for tracking bugs
+
+**Testing**
+- [Jest](https://jestjs.io/)
+
+**Tooling**
+- [Yarn](https://yarnpkg.com/)
+- [Oxlint](https://oxc.rs/docs/guide/usage/linter.html)
+
+**Development**
+- [AWS EKS](https://aws.amazon.com/eks/)
+
+

packages/twenty-docs/developers/contribute/capabilities/backend-development/zapier.mdx

@@ -0,0 +1,76 @@
+---
+title: Zapier App
+---
+
+
+Effortlessly sync Twenty with 3000+ apps using [Zapier](https://zapier.com/). Automate tasks, boost productivity, and supercharge your customer relationships!
+
+## About Zapier
+
+Zapier is a tool that allows you to automate workflows by connecting the apps that your team uses every day. The fundamental concept of Zapier is automation workflows, called Zaps, and include triggers and actions.
+
+You can learn more about how Zapier works [here](https://zapier.com/how-it-works).
+
+## Setup
+
+### Step 1: Install Zapier packages
+
+```bash
+cd packages/twenty-zapier
+
+yarn
+```
+
+### Step 2: Login with the CLI
+
+Use your Zapier credentials to log in using the CLI:
+
+```bash
+zapier login
+```
+
+### Step 3: Set environment variables
+
+From the `packages/twenty-zapier` folder, run:
+
+```bash
+cp .env.example .env
+```
+Run the application locally, go to [http://localhost:3000/settings/api-webhooks](http://localhost:3000/settings/api-webhooks), and generate an API key.
+
+Replace the **YOUR_API_KEY** value in the `.env` file with the API key you just generated.
+
+## Development
+
+<Warning>
+
+Make sure to run `yarn build` before any `zapier` command.
+
+</Warning>
+
+### Test
+```bash
+yarn test
+```
+### Lint
+```bash
+yarn format
+```
+### Watch and compile as you edit code
+```bash
+yarn watch
+```
+### Validate your Zapier app
+```bash
+yarn validate
+```
+### Deploy your Zapier app
+```bash
+yarn deploy
+```
+### List all Zapier CLI commands
+```bash
+zapier
+```
+
+

packages/twenty-docs/developers/contribute/capabilities/bug-and-requests.mdx

@@ -0,0 +1,77 @@
+---
+title: Bugs, Requests & Pull Requests
+icon: "bug"
+info: Report issues, request features, and contribute code
+---
+
+
+## Reporting Bugs
+
+To report a bug, please [create an issue on GitHub](https://github.com/twentyhq/twenty/issues/new).
+
+You can also ask for help on [Discord](https://discord.gg/cx5n4Jzs57).
+
+## Feature Requests
+
+If you're not sure if it's a bug, and you feel it's closer to a feature request, then you should probably [open a discussion instead](https://github.com/twentyhq/twenty/discussions/new).
+
+## Submit a Pull Request
+
+Contributing code to Twenty starts with a pull request (PR).
+
+### Before You Start
+
+1. Check [existing issues](https://github.com/twentyhq/twenty/issues) for related work
+2. For new features, open an issue first to discuss
+3. Review our [Code of Conduct](https://github.com/twentyhq/twenty/blob/main/.github/CODE_OF_CONDUCT.md)
+
+### Fork and Clone
+
+1. Fork the repository on GitHub
+2. Clone your fork:
+```bash
+git clone https://github.com/YOUR_USERNAME/twenty.git
+cd twenty
+```
+
+3. Add upstream remote:
+```bash
+git remote add upstream https://github.com/twentyhq/twenty.git
+```
+
+### Create a Branch
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+Use descriptive branch names:
+- `feature/add-export-button`
+- `fix/login-redirect-issue`
+- `docs/update-api-guide`
+
+### Make Your Changes
+
+1. Write clean, well-documented code
+2. Follow existing code style
+3. Add tests for new functionality
+4. Update documentation if needed
+
+### Submit Your PR
+
+1. Push your branch:
+```bash
+git push origin feature/your-feature-name
+```
+
+2. Open a PR on GitHub
+3. Fill in the PR template
+4. Link related issues
+
+### PR Checklist
+
+- [ ] Code follows project style guidelines
+- [ ] Tests pass locally
+- [ ] Documentation is updated
+- [ ] PR description explains the changes
+

packages/twenty-docs/developers/contribute/capabilities/frontend-development/best-practices-front.mdx

@@ -0,0 +1,331 @@
+---
+title: Best Practices
+icon: "star"
+---
+
+
+This document outlines the best practices you should follow when working on the frontend.
+
+## State management
+
+React and Jotai handle state management in the codebase.
+
+### Use Jotai atoms to store state
+
+It's good practice to create as many atoms as you need to store your state.
+
+<Warning>
+
+It's better to use extra atoms than trying to be too concise with props drilling.
+
+</Warning>
+
+```tsx
+import { createAtomState } from '@/ui/utilities/state/jotai/utils/createAtomState';
+import { useAtomState } from '@/ui/utilities/state/jotai/hooks/useAtomState';
+
+export const myAtomState = createAtomState<string>({
+  key: 'myAtomState',
+  defaultValue: 'default value',
+});
+
+export const MyComponent = () => {
+  const [myAtom, setMyAtom] = useAtomState(myAtomState);
+
+  return (
+    <div>
+      <input
+        value={myAtom}
+        onChange={(e) => setMyAtom(e.target.value)}
+      />
+    </div>
+  );
+}
+```
+
+### Do not use `useRef` to store state
+
+Avoid using `useRef` to store state.
+
+If you want to store state, you should use `useState` or Jotai atoms with `useAtomState`.
+
+See [how to manage re-renders](#managing-re-renders) if you feel like you need `useRef` to prevent some re-renders from happening.
+
+## Managing re-renders
+
+Re-renders can be hard to manage in React.
+
+Here are some rules to follow to avoid unnecessary re-renders.
+
+Keep in mind that you can **always** avoid re-renders by understanding their cause.
+
+### Work at the root level
+
+Avoiding re-renders in new features is now made easy by eliminating them at the root level.
+
+The `PageChangeEffect` sidecar component contains just one `useEffect` that holds all the logic to execute on a page change.
+
+That way you know that there's just one place that can trigger a re-render.
+
+### Always think twice before adding `useEffect` in your codebase
+
+Re-renders are often caused by unnecessary `useEffect`.
+
+You should think whether you need `useEffect`, or if you can move the logic in a event handler function.
+
+You'll find it generally easy to move the logic in a `handleClick` or `handleChange` function.
+
+You can also find them in libraries like Apollo: `onCompleted`, `onError`, etc.
+
+### Use a sibling component to extract `useEffect` or data fetching logic
+
+If you feel like you need to add a `useEffect` in your root component, you should consider extracting it in a sidecar component.
+
+You can apply the same for data fetching logic, with Apollo hooks.
+
+```tsx
+// ❌ Bad, will cause re-renders even if data is not changing,
+//    because useEffect needs to be re-evaluated
+export const PageComponent = () => {
+  const [data, setData] = useAtomState(dataState);
+  const [someDependency] = useAtomState(someDependencyState);
+
+  useEffect(() => {
+    if(someDependency !== data) {
+      setData(someDependency);
+    }
+  }, [someDependency]);
+
+  return <div>{data}</div>;
+};
+
+export const App = () => (
+  <PageComponent />
+);
+```
+
+```tsx
+// ✅ Good, will not cause re-renders if data is not changing,
+//   because useEffect is re-evaluated in another sibling component
+export const PageComponent = () => {
+  const [data, setData] = useAtomState(dataState);
+
+  return <div>{data}</div>;
+};
+
+export const PageData = () => {
+  const [data, setData] = useAtomState(dataState);
+  const [someDependency] = useAtomState(someDependencyState);
+
+  useEffect(() => {
+    if(someDependency !== data) {
+      setData(someDependency);
+    }
+  }, [someDependency]);
+
+  return <></>;
+};
+
+export const App = () => (
+  <>
+    <PageData />
+    <PageComponent />
+  </>
+);
+```
+
+### Use atom family states and selectors
+
+Atom family states and selectors are a great way to avoid re-renders.
+
+They are useful when you need to store a list of items.
+
+### You shouldn't use `React.memo(MyComponent)`
+
+Avoid using `React.memo()` because it does not solve the cause of the re-render, but instead breaks the re-render chain, which can lead to unexpected behavior and make the code very hard to refactor.
+
+### Limit `useCallback` or `useMemo` usage
+
+They are often not necessary and will make the code harder to read and maintain for a gain of performance that is unnoticeable.
+
+## Console.logs
+
+`console.log` statements are valuable during development, offering real-time insights into variable values and code flow. But, leaving them in production code can lead to several issues:
+
+1. **Performance**: Excessive logging can affect the runtime performance, especially on client-side applications.
+
+2. **Security**: Logging sensitive data can expose critical information to anyone who inspects the browser's console.
+
+3. **Cleanliness**: Filling up the console with logs can obscure important warnings or errors that developers or tools need to see.
+
+4. **Professionalism**: End users or clients checking the console and seeing a myriad of log statements might question the code's quality and polish.
+
+Make sure you remove all `console.logs` before pushing the code to production.
+
+## Naming
+
+### Variable Naming
+
+Variable names ought to precisely depict the purpose or function of the variable.
+
+#### The issue with generic names
+Generic names in programming are not ideal because they lack specificity, leading to ambiguity and reduced code readability. Such names fail to convey the variable or function's purpose, making it challenging for developers to understand the code's intent without deeper investigation. This can result in increased debugging time, higher susceptibility to errors, and difficulties in maintenance and collaboration. Meanwhile, descriptive naming makes the code self-explanatory and easier to navigate, enhancing code quality and developer productivity.
+
+```tsx
+// ❌ Bad, uses a generic name that doesn't communicate its
+//    purpose or content clearly
+const [value, setValue] = useState('');
+```
+
+```tsx
+// ✅ Good, uses a descriptive name
+const [email, setEmail] = useState('');
+```
+
+#### Some words to avoid in variable names
+
+ - dummy
+
+### Event handlers
+
+Event handler names should start with `handle`, while `on` is a prefix used to name events in components props.
+
+```tsx
+// ❌ Bad
+const onEmailChange = (val: string) => {
+  // ...
+};
+```
+
+```tsx
+// ✅ Good
+const handleEmailChange = (val: string) => {
+  // ...
+};
+```
+
+## Optional Props
+
+Avoid passing the default value for an optional prop.
+
+**EXAMPLE**
+
+Take the`EmailField` component defined below:
+
+```tsx
+type EmailFieldProps = {
+  value: string;
+  disabled?: boolean;
+};
+
+const EmailField = ({ value, disabled = false }: EmailFieldProps) => (
+  <TextInput value={value} disabled={disabled} fullWidth />
+);
+```
+
+**Usage**
+
+```tsx
+// ❌ Bad, passing in the same value as the default value adds no value
+const Form = () => <EmailField value="username@email.com" disabled={false} />;
+```
+
+```tsx
+// ✅ Good, assumes the default value
+const Form = () => <EmailField value="username@email.com" />;
+```
+
+## Component as props
+
+Try as much as possible to pass uninstantiated components as props, so children can decide on their own of what props they need to pass.
+
+The most common example for that is icon components:
+
+```tsx
+const SomeParentComponent = () => <MyComponent Icon={MyIcon} />;
+
+// In MyComponent
+const MyComponent = ({ MyIcon }: { MyIcon: IconComponent }) => {
+  const theme = useTheme();
+
+  return (
+    <div>
+      <MyIcon size={theme.icon.size.md}>
+    </div>
+  )
+};
+```
+
+For React to understand that the component is a component, you need to use PascalCase, to later instantiate it with `<MyIcon>`
+
+## Prop Drilling: Keep It Minimal
+
+Prop drilling, in the React context, refers to the practice of passing state variables and their setters through many component layers, even if intermediary components don't use them. While sometimes necessary, excessive prop drilling can lead to:
+
+1. **Decreased Readability**: Tracing where a prop originates or where it's utilized can become convoluted in a deeply nested component structure.
+
+2. **Maintenance Challenges**: Changes in one component's prop structure might require adjustments in several components, even if they don't directly use the prop.
+
+3. **Reduced Component Reusability**: A component receiving a lot of props solely for passing them down becomes less general-purpose and harder to reuse in different contexts.
+
+If you feel that you are using excessive prop drilling, see [state management best practices](#state-management).
+
+## Imports
+
+When importing, opt for the designated aliases rather than specifying complete or relative paths.
+
+**The Aliases**
+
+```js
+{
+  alias: {
+    "~": path.resolve(__dirname, "src"),
+    "@": path.resolve(__dirname, "src/modules"),
+    "@testing": path.resolve(__dirname, "src/testing"),
+  },
+}
+```
+
+**Usage**
+```tsx
+// ❌ Bad, specifies the entire relative path
+import {
+  CatalogDecorator
+} from '../../../../../testing/decorators/CatalogDecorator';
+import {
+  ComponentDecorator
+} from '../../../../../testing/decorators/ComponentDecorator';
+```
+
+```tsx
+// ✅ Good, utilises the designated aliases
+import { CatalogDecorator } from '~/testing/decorators/CatalogDecorator';
+import { ComponentDecorator } from 'twenty-ui/testing';
+```
+
+## Schema Validation
+
+[Zod](https://github.com/colinhacks/zod) is the schema validator for untyped objects:
+
+```js
+const validationSchema = z
+  .object({
+    exist: z.boolean(),
+    email: z
+      .string()
+      .email('Email must be a valid email'),
+    password: z
+      .string()
+      .regex(PASSWORD_REGEX, 'Password must contain at least 8 characters'),
+  })
+  .required();
+
+type Form = z.infer<typeof validationSchema>;
+```
+
+
+## Breaking Changes
+
+Always perform thorough manual testing before proceeding to guarantee that modifications haven’t caused disruptions elsewhere, given that tests have not yet been extensively integrated.
+
+

packages/twenty-docs/developers/contribute/capabilities/frontend-development/folder-architecture-front.mdx

@@ -0,0 +1,113 @@
+---
+title: Folder Architecture
+icon: "folder-tree"
+info: A detailed look into our folder architecture
+---
+
+
+In this guide, you will explore the details of the project directory structure and how it contributes to the organization and maintainability of Twenty.
+
+By following this folder architecture convention, it's easier to find the files related to specific features and ensure that the application is scalable and maintainable.
+
+```
+front
+└───modules
+│   └───module1
+│   │   └───submodule1
+│   └───module2
+│   └───ui
+│   │   └───display
+│   │   └───inputs
+│   │   │   └───buttons
+│   │   └───...
+└───pages
+└───...
+```
+
+## Pages
+
+Includes the top-level components defined by the application routes. They import more low-level components from the modules folder (more details below).
+
+## Modules
+
+Each module represents a feature or a group of feature, comprising its specific components, states, and operational logic.
+They should all follow the structure below. You can nest modules within modules (referred to as submodules) and the same rules will apply.
+
+```
+module1
+  └───components
+  │   └───component1
+  │   └───component2
+  └───constants
+  └───contexts
+  └───graphql
+  │   └───fragments
+  │   └───queries
+  │   └───mutations
+  └───hooks
+  │   └───internal
+  └───states
+  │   └───selectors
+  └───types
+  └───utils
+```
+
+### Contexts
+
+A context is a way to pass data through the component tree without having to pass props down manually at every level.
+
+See [React Context](https://react.dev/reference/react#context-hooks) for more details.
+
+### GraphQL
+
+Includes fragments, queries, and mutations.
+
+See [GraphQL](https://graphql.org/learn/) for more details.
+
+- Fragments
+
+A fragment is a reusable piece of a query, which you can use in different places. By using fragments, it's easier to avoid duplicating code.
+
+See [GraphQL Fragments](https://graphql.org/learn/queries/#fragments) for more details.
+
+- Queries
+
+See [GraphQL Queries](https://graphql.org/learn/queries/) for more details.
+
+- Mutations
+
+See [GraphQL Mutations](https://graphql.org/learn/queries/#mutations) for more details.
+
+### Hooks
+
+See [Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks) for more details.
+
+### States
+
+Contains the state management logic. [Jotai](https://jotai.org) handles this.
+
+- Selectors: Derived atoms (using `createAtomSelector`) compute values from other atoms and are automatically memoized.
+
+React's built-in state management still handles state within a component.
+
+### Utils
+
+Should just contain reusable pure functions. Otherwise, create custom hooks in the `hooks` folder.
+
+
+## UI
+
+Contains all the reusable UI components used in the application.
+
+This folder can contain sub-folders, like `data`, `display`, `feedback`, and `input` for specific types of components. Each component should be self-contained and reusable, so that you can use it in different parts of the application.
+
+By separating the UI components from the other components in the `modules` folder, it's easier to maintain a consistent design and to make changes to the UI without affecting other parts (business logic) of the codebase.
+
+## Interface and dependencies
+
+You can import other module code from any module except for the `ui` folder. This will keep its code easy to test.
+
+### Internal
+
+Each part (hooks, states, ...) of a module can have an `internal` folder, which contains parts that are just used within the module.
+

packages/twenty-docs/developers/contribute/capabilities/frontend-development/frontend-commands.mdx

@@ -0,0 +1,92 @@
+---
+title: Frontend Commands
+icon: "terminal"
+---
+
+
+## Useful commands
+
+### Starting the app
+
+```bash
+npx nx start twenty-front
+```
+
+### Regenerate graphql schema based on API graphql schema
+
+```bash
+npx nx run twenty-front:graphql:generate --configuration=metadata
+```
+OR
+```bash
+npx nx run twenty-front:graphql:generate
+```
+
+### Lint
+
+```bash
+npx nx run twenty-front:lint # pass --fix to fix lint errors
+```
+
+## Translations
+
+```bash
+npx nx run twenty-front:lingui:extract
+npx nx run twenty-front:lingui:compile
+```
+
+### Test
+
+```bash
+npx nx run twenty-front:test # run jest tests
+npx nx run twenty-front:storybook:serve:dev # run storybook
+npx nx run twenty-front:storybook:test # run tests # (needs yarn storybook:serve:dev to be running)
+npx nx run twenty-front:storybook:coverage # (needs yarn storybook:serve:dev to be running)
+```
+
+## Tech Stack
+
+The project has a clean and simple stack, with minimal boilerplate code.
+
+**App**
+
+- [React](https://react.dev/)
+- [Apollo](https://www.apollographql.com/docs/)
+- [GraphQL Codegen](https://the-guild.dev/graphql/codegen)
+- [Jotai](https://jotai.org/)
+- [TypeScript](https://www.typescriptlang.org/)
+
+**Testing**
+
+- [Jest](https://jestjs.io/)
+- [Storybook](https://storybook.js.org/)
+
+**Tooling**
+
+- [Yarn](https://yarnpkg.com/)
+- [Craco](https://craco.js.org/docs/)
+- [Oxlint](https://oxc.rs/docs/guide/usage/linter.html)
+
+## Architecture
+
+### Routing
+
+[React Router](https://reactrouter.com/) handles the routing.
+
+To avoid unnecessary [re-renders](/developers/contribute/capabilities/frontend-development/best-practices-front#managing-re-renders) all the routing logic is in a `useEffect` in `PageChangeEffect`.
+
+### State Management
+
+[Jotai](https://jotai.org/) handles state management.
+
+See [best practices](/developers/contribute/capabilities/frontend-development/best-practices-front#state-management) for more information on state management.
+
+## Testing
+
+[Jest](https://jestjs.io/) serves as the tool for unit testing while [Storybook](https://storybook.js.org/) is for component testing.
+
+Jest is mainly for testing utility functions, and not components themselves.
+
+Storybook is for testing the behavior of isolated components, as well as displaying the design system.
+
+

packages/twenty-docs/developers/contribute/capabilities/frontend-development/hotkeys.mdx

@@ -0,0 +1,177 @@
+---
+title: Hotkeys
+---
+
+
+## Introduction
+
+When you need to listen to a hotkey, you would normally use the `onKeyDown` event listener.
+
+In `twenty-front` however, you might have conflicts between same hotkeys that are used in different components, mounted at the same time.
+
+For example, if you have a page that listens for the Enter key, and a modal that listens for the Enter key, with a Select component inside that modal that listens for the Enter key, you might have a conflict when all are mounted at the same time.
+
+## The `useScopedHotkeys` hook
+
+To handle this problem, we have a custom hook that makes it possible to listen to hotkeys without any conflict.
+
+You place it in a component, and it will listen to the hotkeys only when the component is mounted AND when the specified **hotkey scope** is active.
+
+## How to listen for hotkeys in practice?
+
+There are two steps involved in setting up hotkey listening :
+1. Set the [hotkey scope](#what-is-a-hotkey-scope-) that will listen to hotkeys
+2. Use the `useScopedHotkeys` hook to listen to hotkeys
+
+Setting up hotkey scopes is required even in simple pages, because other UI elements like left menu or command menu might also listen to hotkeys.
+
+## Use cases for hotkeys
+
+In general, you'll have two use cases that require hotkeys :
+1. In a page or a component mounted in a page
+2. In a modal-type component that takes the focus due to a user action
+
+The second use case can happen recursively : a dropdown in a modal for example.
+
+### Listening to hotkeys in a page
+
+Example :
+
+```tsx
+const PageListeningEnter = () => {
+  const {
+    setHotkeyScopeAndMemorizePreviousScope,
+    goBackToPreviousHotkeyScope,
+  } = usePreviousHotkeyScope();
+
+  // 1. Set the hotkey scope in a useEffect
+  useEffect(() => {
+    setHotkeyScopeAndMemorizePreviousScope(
+      ExampleHotkeyScopes.ExampleEnterPage,
+    );
+
+    // Revert to the previous hotkey scope when the component is unmounted
+    return () => {
+      goBackToPreviousHotkeyScope();
+    };
+  }, [goBackToPreviousHotkeyScope, setHotkeyScopeAndMemorizePreviousScope]);
+
+  // 2. Use the useScopedHotkeys hook
+  useScopedHotkeys(
+    Key.Enter,
+    () => {
+      // Some logic executed on this page when the user presses Enter
+      // ...
+    },
+    ExampleHotkeyScopes.ExampleEnterPage,
+  );
+
+  return <div>My page that listens for Enter</div>;
+};
+```
+
+### Listening to hotkeys in a modal-type component
+
+For this example we'll use a modal component that listens for the Escape key to tell its parent to close it.
+
+Here the user interaction is changing the scope.
+
+```tsx
+const ExamplePageWithModal = () => {
+  const [showModal, setShowModal] = useState(false);
+
+  const {
+    setHotkeyScopeAndMemorizePreviousScope,
+    goBackToPreviousHotkeyScope,
+  } = usePreviousHotkeyScope();
+
+  const handleOpenModalClick = () => {
+    // 1. Set the hotkey scope when user opens the modal
+    setShowModal(true);
+    setHotkeyScopeAndMemorizePreviousScope(
+      ExampleHotkeyScopes.ExampleModal,
+    );
+  };
+
+  const handleModalClose = () => {
+    // 1. Revert to the previous hotkey scope when the modal is closed
+    setShowModal(false);
+    goBackToPreviousHotkeyScope();
+  };
+
+  return <div>
+    <h1>My page with a modal</h1>
+    <button onClick={handleOpenModalClick}>Open modal</button>
+    {showModal && <MyModalComponent onClose={handleModalClose} />}
+  </div>;
+};
+```
+
+Then in the modal component :
+
+```tsx
+const MyDropdownComponent = ({ onClose }: { onClose: () => void }) => {
+  // 2. Use the useScopedHotkeys hook to listen for Escape.
+  // Note that escape is a common hotkey that could be used by many other components
+  // So it's important to use a hotkey scope to avoid conflicts
+  useScopedHotkeys(
+    Key.Escape,
+    () => {
+      onClose()
+    },
+    ExampleHotkeyScopes.ExampleModal,
+  );
+
+  return <div>My modal component</div>;
+};
+```
+
+It's important to use this pattern when you're not sure that just using a useEffect with mount/unmount will be enough to avoid conflicts.
+
+Those conflicts can be hard to debug, and it might happen more often than not with useEffects.
+
+## What is a hotkey scope?
+
+A hotkey scope is a string that represents a context in which the hotkeys are active. It is generally encoded as an enum.
+
+When you change the hotkey scope, the hotkeys that are listening to this scope will be enabled and the hotkeys that are listening to other scopes will be disabled.
+
+You can set only one scope at a time.
+
+As an example, the hotkey scopes for each page are defined in the `PageHotkeyScope` enum:
+
+```tsx
+export enum PageHotkeyScope {
+  Settings = 'settings',
+  CreateWorkspace = 'create-workspace',
+  SignInUp = 'sign-in-up',
+  CreateProfile = 'create-profile',
+  PlanRequired = 'plan-required',
+  ShowPage = 'show-page',
+  PersonShowPage = 'person-show-page',
+  CompanyShowPage = 'company-show-page',
+  CompaniesPage = 'companies-page',
+  PeoplePage = 'people-page',
+  OpportunitiesPage = 'opportunities-page',
+  ProfilePage = 'profile-page',
+  WorkspaceMemberPage = 'workspace-member-page',
+  TaskPage = 'task-page',
+}
+```
+
+Internally, the currently selected scope is stored in a Jotai atom that is shared across the application :
+
+```tsx
+export const currentHotkeyScopeState = createState<HotkeyScope>({
+  key: 'currentHotkeyScopeState',
+  defaultValue: INITIAL_HOTKEYS_SCOPE,
+});
+```
+
+But this atom should never be handled manually ! We'll see how to use it in the next section.
+
+## How is it working internally?
+
+We made a thin wrapper on top of [react-hotkeys-hook](https://react-hotkeys-hook.vercel.app/docs/intro) that makes it more performant and avoids unnecessary re-renders.
+
+We also create a Jotai atom to handle the hotkey scope state and make it available everywhere in the application.

packages/twenty-docs/developers/contribute/capabilities/frontend-development/storybook.mdx

@@ -0,0 +1,9 @@
+---
+title: Storybook
+description: Browse Twenty's UI component library
+---
+
+View our complete component library and documentation in Storybook.
+
+[Open Storybook →](https://storybook.twenty.com)
+

packages/twenty-docs/developers/contribute/capabilities/frontend-development/style-guide.mdx

@@ -0,0 +1,291 @@
+---
+title: Style Guide
+icon: "paintbrush"
+---
+
+
+This document includes the rules to follow when writing code.
+
+The goal here is to have a consistent codebase, which is easy to read and easy to maintain.
+
+For this, it's better to be a bit more verbose than to be too concise.
+
+Always keep in mind that people read code more often than they write it, especially on an open source project, where anyone can contribute.
+
+There are a lot of rules that are not defined here, but that are automatically checked by linters.
+
+## React
+
+### Use functional components
+
+Always use TSX functional components.
+
+Do not use default `import` with `const`, because it's harder to read and harder to import with code completion.
+
+```tsx
+// ❌ Bad, harder to read, harder to import with code completion
+const MyComponent = () => {
+  return <div>Hello World</div>;
+};
+
+export default MyComponent;
+
+// ✅ Good, easy to read, easy to import with code completion
+export function MyComponent() {
+  return <div>Hello World</div>;
+};
+```
+
+### Props
+
+Create the type of the props and call it `(ComponentName)Props` if there's no need to export it.
+
+Use props destructuring.
+
+```tsx
+// ❌ Bad, no type
+export const MyComponent = (props) => <div>Hello {props.name}</div>;
+
+// ✅ Good, type
+type MyComponentProps = {
+  name: string;
+};
+
+export const MyComponent = ({ name }: MyComponentProps) => <div>Hello {name}</div>;
+```
+
+#### Refrain from using `React.FC` or `React.FunctionComponent` to define prop types
+
+```tsx
+/* ❌ - Bad, defines the component type annotations with `FC`
+ *    - With `React.FC`, the component implicitly accepts a `children` prop
+ *      even if it's not defined in the prop type. This might not always be
+ *      desirable, especially if the component doesn't intend to render
+ *      children.
+ */
+const EmailField: React.FC<{
+  value: string;
+}> = ({ value }) => <TextInput value={value} disabled fullWidth />;
+```
+
+```tsx
+/* ✅ - Good, a separate type (OwnProps) is explicitly defined for the
+ *      component's props
+ *    - This method doesn't automatically include the children prop. If
+ *      you want to include it, you have to specify it in OwnProps.
+ */
+type EmailFieldProps = {
+  value: string;
+};
+
+const EmailField = ({ value }: EmailFieldProps) => (
+  <TextInput value={value} disabled fullWidth />
+);
+```
+
+#### No Single Variable Prop Spreading in JSX Elements
+
+Avoid using single variable prop spreading in JSX elements, like `{...props}`. This practice often results in code that is less readable and harder to maintain because it's unclear which props the component is receiving.
+
+```tsx
+/* ❌ - Bad, spreads a single variable prop into the underlying component
+ */
+const MyComponent = (props: OwnProps) => {
+  return <OtherComponent {...props} />;
+}
+```
+
+```tsx
+/* ✅ - Good, Explicitly lists all props
+ *    - Enhances readability and maintainability
+ */
+const MyComponent = ({ prop1, prop2, prop3 }: MyComponentProps) => {
+  return <OtherComponent {...{ prop1, prop2, prop3 }} />;
+};
+```
+
+Rationale:
+- At a glance, it's clearer which props the code passes down, making it easier to understand and maintain.
+- It helps to prevent tight coupling between components via their props.
+- Linting tools make it easier to identify misspelled or unused props when you list props explicitly.
+
+## JavaScript
+
+### Use nullish-coalescing operator `??`
+
+```tsx
+// ❌ Bad, can return 'default' even if value is 0 or ''
+const value = process.env.MY_VALUE || 'default';
+
+// ✅ Good, will return 'default' only if value is null or undefined
+const value = process.env.MY_VALUE ?? 'default';
+```
+
+### Use optional chaining `?.`
+
+```tsx
+// ❌ Bad
+onClick && onClick();
+
+// ✅ Good
+onClick?.();
+```
+
+## TypeScript
+
+### Use `type` instead of `interface`
+
+Always use `type` instead of `interface`, because they almost always overlap, and `type` is more flexible.
+
+```tsx
+// ❌ Bad
+interface MyInterface {
+  name: string;
+}
+
+// ✅ Good
+type MyType = {
+  name: string;
+};
+```
+
+### Use string literals instead of enums
+
+[String literals](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) are the go-to way to handle enum-like values in TypeScript. They are easier to extend with Pick and Omit, and offer a better developer experience, especially with code completion.
+
+You can see why TypeScript recommends avoiding enums [here](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#enums).
+
+```tsx
+// ❌ Bad, utilizes an enum
+enum Color {
+  Red = "red",
+  Green = "green",
+  Blue = "blue",
+}
+
+let color = Color.Red;
+```
+
+```tsx
+// ✅ Good, utilizes a string literal
+
+let color: "red" | "green" | "blue" = "red";
+```
+
+#### GraphQL and internal libraries
+
+You should use enums that GraphQL codegen generates.
+
+It's also better to use an enum when using an internal library, so the internal library doesn't have to expose a string literal type that is not related to the internal API.
+
+Example:
+
+```TSX
+const {
+  setHotkeyScopeAndMemorizePreviousScope,
+  goBackToPreviousHotkeyScope,
+} = usePreviousHotkeyScope();
+
+setHotkeyScopeAndMemorizePreviousScope(
+  RelationPickerHotkeyScope.RelationPicker,
+);
+```
+
+## Styling
+
+### Use StyledComponents
+
+Style the components with [Linaria styled](https://github.com/callstack/linaria).
+
+```tsx
+// ❌ Bad
+<div className="my-class">Hello World</div>
+```
+
+```tsx
+// ✅ Good
+const StyledTitle = styled.div`
+  color: red;
+`;
+```
+
+Prefix styled components with "Styled" to differentiate them from "real" components.
+
+```tsx
+// ❌ Bad
+const Title = styled.div`
+  color: red;
+`;
+```
+
+```tsx
+// ✅ Good
+const StyledTitle = styled.div`
+  color: red;
+`;
+```
+
+### Theming
+
+Utilizing the theme for the majority of component styling is the preferred approach.
+
+#### Units of measurement
+
+Avoid using `px` or `rem` values directly within the styled components. The necessary values are generally already defined in the theme, so it’s recommended to make use of the theme for these purposes.
+
+#### Colors
+
+Refrain from introducing new colors; instead, use the existing palette from the theme. Should there be a situation where the palette does not align, please leave a comment so that the team can rectify it.
+
+
+```tsx
+// ❌ Bad, directly specifies style values without utilizing the theme
+const StyledButton = styled.button`
+  color: #333333;
+  font-size: 1rem;
+  font-weight: 400;
+  margin-left: 4px;
+  border-radius: 50px;
+`;
+```
+
+```tsx
+// ✅ Good, utilizes the theme
+const StyledButton = styled.button`
+  color: ${({ theme }) => theme.font.color.primary};
+  font-size: ${({ theme }) => theme.font.size.md};
+  font-weight: ${({ theme }) => theme.font.weight.regular};
+  margin-left: ${({ theme }) => theme.spacing(1)};
+  border-radius:  ${({ theme }) => theme.border.rounded};
+`;
+```
+## Enforcing No-Type Imports
+
+Avoid type imports. To enforce this standard, an Oxlint rule checks for and reports any type imports. This helps maintain consistency and readability in the TypeScript code.
+
+```tsx
+// ❌ Bad
+import { type Meta, type StoryObj } from '@storybook/react';
+
+// ❌ Bad
+import type { Meta, StoryObj } from '@storybook/react';
+
+// ✅ Good
+import { Meta, StoryObj } from '@storybook/react';
+```
+
+### Why No-Type Imports
+
+- **Consistency**: By avoiding type imports and using a single approach for both type and value imports, the codebase remains consistent in its module import style.
+
+- **Readability**: No-type imports improve code readability by making it clear when you're importing values or types. This reduces ambiguity and makes it easier to understand the purpose of imported symbols.
+
+- **Maintainability**: It enhances codebase maintainability because developers can identify and locate type-only imports when reviewing or modifying code.
+
+### Oxlint Rule
+
+An Oxlint rule, `typescript/consistent-type-imports`, enforces the no-type import standard. This rule will generate errors or warnings for any type import violations.
+
+Please note that this rule specifically addresses rare edge cases where unintentional type imports occur. TypeScript itself discourages this practice, as mentioned in the [TypeScript 3.8 release notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html). In most situations, you should not need to use type-only imports.
+
+To ensure your code complies with this rule, make sure to run Oxlint as part of your development workflow.

packages/twenty-docs/developers/contribute/capabilities/frontend-development/work-with-figma.mdx

@@ -0,0 +1,64 @@
+---
+title: Work with Figma
+info: Learn how you can collaborate with Twenty's Figma
+---
+
+
+Figma is a collaborative interface design tool that aids in bridging the communication barrier between designers and developers.
+This guide explains how you can collaborate with Figma.
+
+## Access
+
+1. **Access the shared link:** You can access the project's Figma file [here](https://www.figma.com/file/xt8O9mFeLl46C5InWwoMrN/Twenty).
+2. **Sign in:** If you're not already signed in, Figma will prompt you to do so.
+Key features are only available to logged-in users, such as the developer mode and the ability to select a dedicated frame.
+
+<Warning>
+
+You will not be able to collaborate effectively without an account.
+
+</Warning>
+
+
+## Figma structure
+
+On the left sidebar, you can access the different pages of Twenty's Figma. This is how they're organized:
+
+- **Components page:** This is the first page. The designer uses it to create and organize the reusable design elements used throughout the design file. For example, buttons, icons, symbols, or any other reusable components. It serves to maintain consistency across the design.
+- **Main page:** The second page is the main page, which shows the complete user interface of the project. You can press ***Play*** to use the full app prototype.
+- **Features pages:** The other pages are typically dedicated to features in progress. They contain the design of specific features or modules of the application or website. They are typically still in progress.
+
+## Useful Tips
+
+With read-only access, you can't edit the design, but you can access all features that will be useful to convert the designs into code.
+
+### Use the Dev mode
+
+Figma's Dev Mode enhances developers' productivity by providing easy design navigation, effective asset management, efficient communication tools, toolbox integrations, quick code snippets, and key layer information, bridging the gap between design and development. You can learn more about Dev Mode [here](https://www.figma.com/dev-mode/).
+
+Switch to the "Developer" mode in the right part of the toolbar to see design specs, copy CSS, and access assets.
+
+### Use the Prototype
+
+Click on any element on the canvas and press the “Play” button at the top right edge of the interface to access the prototype view. Prototype mode allows you to interact with the design as if it were the final product. It demonstrates the flow between screens and how interface elements like buttons, links, or menus behave when interacted with.
+
+1. **Understanding transitions and animations:** In the Prototype mode, you can view any transitions or animations added by a designer between screens or UI elements, providing clear visual instructions to developers on the intended behavior and style.
+2. **Implementation clarification:** A prototype can also help reduce ambiguities. Developers can interact with it to gain a better understanding of the functionality or appearance of particular elements.
+
+For more comprehensive details and guidance on learning the Figma platform, you can visit the official [Figma Documentation](https://help.figma.com/hc/en-us).
+
+### Measure distances
+
+Select an element, hold `Option` key (Mac) or `Alt` key (Windows), then hover over another element to see the distance between them.
+
+### Figma extension for VSCode (Recommended)
+
+[Figma for VS Code](https://marketplace.visualstudio.com/items?itemName=figma.figma-vscode-extension)
+lets you navigate and inspect design files, collaborate with designers, track changes, and speed up implementation - all without leaving your text editor.
+It's part of our recommended extensions.
+
+## Collaboration
+
+1. **Using Comments:** You are welcome to use the comment feature by clicking on the bubble icon in the left part of the toolbar.
+2. **Cursor chat:** A nice feature of Figma is the Cursor chat. Just press `;` on Mac and `/` on Windows to send a message if you see someone else using Figma as the same time as you.
+

packages/twenty-docs/developers/contribute/capabilities/local-setup.mdx

@@ -0,0 +1,314 @@
+---
+title: Local Setup
+icon: "laptop-code"
+description: "The guide for contributors (or curious developers) who want to run Twenty locally."
+---
+
+
+## Prerequisites
+
+<Tabs>
+<Tab title="Linux and macOS">
+
+Before you can install and use Twenty, make sure you install the following on your computer:
+- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+- [Node v24.5.0](https://nodejs.org/en/download)
+- [yarn v4](https://yarnpkg.com/getting-started/install)
+- [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md)
+
+<Warning>
+`npm` won't work, you should use `yarn` instead. Yarn is now shipped with Node.js, so you don't need to install it separately.
+You only have to run `corepack enable` to enable Yarn if you haven't done it yet.
+</Warning>
+
+</Tab>
+
+<Tab title="Windows (WSL)">
+
+1. Install WSL
+Open PowerShell as Administrator and run:
+```powershell
+wsl --install
+```
+You should now see a prompt to restart your computer. If not, restart it manually.
+
+Upon restart, a PowerShell window will open and install Ubuntu. This may take up some time.
+You'll see a prompt to create a username and password for your Ubuntu installation.
+
+2. Install and configure git
+
+```bash
+sudo apt-get install git
+
+git config --global user.name "Your Name"
+
+git config --global user.email "youremail@domain.com"
+```
+
+3. Install nvm, node.js and yarn
+
+<Warning>
+Use `nvm` to install the correct `node` version. The `.nvmrc` ensures all contributors use the same version.
+</Warning>
+
+```bash
+sudo apt-get install curl
+
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
+```
+Close and reopen your terminal to use nvm. Then run the following commands.
+
+```bash
+
+nvm install # installs recommended node version
+
+nvm use # use recommended node version
+
+corepack enable
+```
+
+</Tab>
+</Tabs>
+
+---
+
+## Step 1: Git Clone
+
+In your terminal, run the following command.
+
+<Tabs>
+<Tab title="SSH (Recommended)">
+If you haven't already set up SSH keys, you can learn how to do so [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh).
+```bash
+git clone git@github.com:twentyhq/twenty.git
+```
+</Tab>
+<Tab title="HTTPS">
+
+```bash
+git clone https://github.com/twentyhq/twenty.git
+```
+
+</Tab>
+</Tabs>
+
+## Step 2: Position yourself at the root
+
+```bash
+cd twenty
+```
+
+You should run all commands in the following steps from the root of the project.
+
+## Step 3: Set up a PostgreSQL Database
+
+<Tabs>
+  <Tab title="Linux">
+    **Option 1 (preferred):** To provision your database locally:
+    Use the following link to install PostgreSQL on your Linux machine: [PostgreSQL Installation](https://www.postgresql.org/download/linux/)
+    ```bash
+      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
+    ```
+    Note: You might need to add `sudo -u postgres` to the command before `psql` to avoid permission errors.
+
+    **Option 2:** If you have docker installed:
+    ```bash
+      make -C packages/twenty-docker postgres-on-docker
+    ```
+  </Tab>
+  <Tab title="Mac OS">
+    **Option 1 (preferred):** To provision your database locally with `brew`:
+
+    ```bash
+      brew install postgresql@16
+      export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"
+      brew services start postgresql@16
+      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
+    ```
+
+    You can verify if the PostgreSQL server is running by executing:
+    ```bash
+      brew services list
+    ```
+
+    The installer might not create the `postgres` user by default when installing
+    via Homebrew on macOS. Instead, it creates a PostgreSQL role that matches your macOS
+    username (e.g., "john").
+    To check and create the `postgres` user if necessary, follow these steps:
+    ```bash
+      # Connect to PostgreSQL
+      psql postgres
+      or
+      psql -U $(whoami) -d postgres
+    ```
+
+    Once at the psql prompt (postgres=#), run:
+     ```bash
+      # List existing PostgreSQL roles
+      \du
+    ```
+    You'll see output similar to:
+     ```bash
+      Role name | Attributes  | Member of
+      -----------+-------------+-----------
+      john      | Superuser   | {}
+    ```
+
+    If you do not see a `postgres` role listed, proceed to the next step.
+    Create the `postgres` role manually:
+     ```bash
+      CREATE ROLE postgres WITH SUPERUSER LOGIN;
+    ```
+    This creates a superuser role named `postgres` with login access.
+      ```bash
+      Role name | Attributes  | Member of
+      -----------+-------------+-----------
+      postgres  | Superuser   | {}
+      john      | Superuser   | {}
+    ```
+
+    **Option 2:** If you have docker installed:
+    ```bash
+      make -C packages/twenty-docker postgres-on-docker
+    ```
+  </Tab>
+  <Tab title="Windows (WSL)">
+    All the following steps are to be run in the WSL terminal (within your virtual machine)
+
+    **Option 1:** To provision your PostgreSQL locally:
+    Use the following link to install PostgreSQL on your Linux virtual machine: [PostgreSQL Installation](https://www.postgresql.org/download/linux/)
+    ```bash
+      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
+    ```
+    Note: You might need to add `sudo -u postgres` to the command before `psql` to avoid permission errors.
+
+    **Option 2:** If you have docker installed:
+    Running Docker on WSL adds an extra layer of complexity.
+    Only use this option if you are comfortable with the extra steps involved, including turning on [Docker Desktop WSL2](https://docs.docker.com/desktop/wsl).
+    ```bash
+      make -C packages/twenty-docker postgres-on-docker
+    ```
+  </Tab>
+</Tabs>
+
+You can now access the database at `localhost:5432`.
+
+If you used the Docker option above, the default credentials are user `postgres` and password `postgres`. For native PostgreSQL installations, use the credentials and roles configured on your machine.
+
+## Step 4: Set up a Redis Database (cache)
+Twenty requires a Redis cache to provide the best performance.
+
+<Tabs>
+  <Tab title="Linux">
+    **Option 1:** To provision your Redis locally:
+    Use the following link to install Redis on your Linux machine: [Redis Installation](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/install-redis-on-linux/)
+
+    **Option 2:** If you have docker installed:
+    ```bash
+      make -C packages/twenty-docker redis-on-docker
+    ```
+  </Tab>
+  <Tab title="Mac OS">
+    **Option 1 (preferred):** To provision your Redis locally with `brew`:
+    ```bash
+    brew install redis
+    ```
+    Start your Redis server:
+    ```bash
+    brew services start redis
+    ```
+
+    **Option 2:** If you have docker installed:
+    ```bash
+      make -C packages/twenty-docker redis-on-docker
+    ```
+  </Tab>
+  <Tab title="Windows (WSL)">
+    **Option 1:** To provision your Redis locally:
+    Use the following link to install Redis on your Linux virtual machine: [Redis Installation](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/install-redis-on-linux/)
+
+    **Option 2:** If you have docker installed:
+    ```bash
+      make -C packages/twenty-docker redis-on-docker
+    ```
+  </Tab>
+</Tabs>
+
+If you need a client GUI, we recommend [Redis Insight](https://redis.io/insight/) (free version available).
+
+## Step 5: Set up environment variables
+
+Use environment variables or `.env` files to configure your project. More info [here](/developers/self-host/capabilities/setup).
+
+Copy the `.env.example` files in `/front` and `/server`:
+```bash
+cp ./packages/twenty-front/.env.example ./packages/twenty-front/.env
+cp ./packages/twenty-server/.env.example ./packages/twenty-server/.env
+```
+
+<Info>
+**Multi-Workspace Mode:** By default, Twenty runs in single-workspace mode where only one workspace can be created. To enable multi-workspace support (useful for testing subdomain-based features), set `IS_MULTIWORKSPACE_ENABLED=true` in your server `.env` file. See [Multi-Workspace Mode](/developers/self-host/capabilities/setup#multi-workspace-mode) for details.
+</Info>
+
+## Step 6: Installing dependencies
+To build Twenty server and seed some data into your database, run the following command:
+```bash
+yarn
+```
+Note that `npm` or `pnpm` won't work
+
+## Step 7: Running the project
+
+<Tabs>
+  <Tab title="Linux">
+    Depending on your Linux distribution, Redis server might be started automatically.
+    If not, check the [Redis installation guide](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/) for your distro.
+  </Tab>
+  <Tab title="Mac OS">
+  Redis should already be running. If not, run:
+    ```bash
+    brew services start redis
+    ```
+  </Tab>
+  <Tab title="Windows (WSL)">
+    Depending on your Linux distribution, Redis server might be started automatically.
+    If not, check the [Redis installation guide](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/) for your distro.
+  </Tab>
+</Tabs>
+
+
+Set up your database with the following command:
+```bash
+npx nx database:reset twenty-server
+```
+
+Start the server, the worker and the frontend services:
+```bash
+npx nx start twenty-server
+npx nx worker twenty-server
+npx nx start twenty-front
+```
+
+Alternatively, you can start all services at once:
+```bash
+npx nx start
+```
+
+## Step 8: Use Twenty
+
+**Frontend**
+
+Twenty's frontend will be running at [http://localhost:3001](http://localhost:3001).
+You can log in using the default demo account: `tim@apple.dev` (password: `tim@apple.dev`)
+
+**Backend**
+
+- Twenty's server will be up and running at [http://localhost:3000](http://localhost:3000)
+- The GraphQL API can be accessed at [http://localhost:3000/graphql](http://localhost:3000/graphql)
+- The REST API can be reached at [http://localhost:3000/rest](http://localhost:3000/rest)
+
+
+
+## Troubleshooting
+
+If you encounter any problem, check [Troubleshooting](/developers/self-host/capabilities/troubleshooting) for solutions.