Skip to content

CLAUDE.md

Latest commit

 

History

History
51 lines (39 loc) · 4.61 KB

CLAUDE.md

File metadata and controls

51 lines (39 loc) · 4.61 KB
Raw

CLAUDE.md

Twenty is an open-source CRM — an Nx / Yarn 4 monorepo. Main packages: twenty-front (React 18, Jotai, Linaria, Vite), twenty-server (NestJS, TypeORM, PostgreSQL, Redis, GraphQL), twenty-shared (isomorphic types/utils), twenty-ui, twenty-sdk (application SDK + CLI), twenty-e2e-testing (Playwright).

Match the surrounding code — the adjacent files in the directory you are editing beat any written rule, including for file naming, which varies by area.

House rules

Where this repo differs from your defaults:

  • Short-form // comments, never JSDoc blocks; comment only WHY (a constraint the code cannot express, still true for a reader who never saw your change), never WHAT.
  • Types over interfaces (except when extending third-party interfaces); string literals over enums (except GraphQL enums); no any; descriptive generics (TData, not T).
  • Named exports only. Functional components only.
  • Prefer event handlers over useEffect for state updates.
  • No abbreviations in names (fieldMetadata, not fm); constants in SCREAMING_SNAKE_CASE; component props types suffixed Props.
  • Use twenty-shared/utils guards (isDefined, isNonEmptyString, …) and other existing helpers before writing your own — reimplementing an existing util is the most common AI-authored defect here.
  • Lingui for user-facing strings; Linaria (zero-runtime, styled-components pattern) for twenty-front styling.
  • For Twenty product concepts, consult packages/twenty-ui/src/icon/icon-dictionary.md and use the canonical icon.
  • Import icons from twenty-ui/icon, never directly from @tabler/icons-react; action and status concepts should use their action or status icons.
  • Test behavior, not implementation: query by user-visible text/roles, @testing-library/user-event for interactions.

Longer-form guides remain in .cursor/rules/ (from the Cursor era).

Commands

bash packages/twenty-utils/setup-dev-env.sh   # Postgres/Redis + DB init; only for tasks needing a running app
yarn start                                    # front + server + worker

npx jest path/to/file.spec.ts --config=packages/<pkg>/jest.config.mjs   # single test file (preferred)
npx nx test twenty-server                     # package unit tests (same for twenty-front, ...)
npx nx run twenty-server:test:integration:with-db-reset
npx nx storybook:build twenty-front && npx nx storybook:test twenty-front

npx nx lint:diff-with-main twenty-server      # diff-based lint (fast; add --configuration=fix); run with typecheck after changes
npx nx fmt <pkg>                              # format
npx nx build twenty-shared                    # required before building/testing packages that depend on it
npx nx database:reset twenty-server
npx nx run twenty-front:graphql:generate      # after GraphQL schema changes (--configuration=metadata for metadata schema)

Gotchas

  • twenty-shared/dist is per-branch state nothing tracks. After switching branches or editing twenty-shared, run npx nx build twenty-shared --skip-nx-cache before trusting any typecheck or test failure in a dependent package.
  • Nx caching can serve a stale pass. To verify a fix, run npx tsgo -p tsconfig.json --noEmit in the package directly rather than nx typecheck.
  • Do not commit translation catalogs unless translations are the task. lingui extract/compile regenerate packages/twenty-server/src/engine/core-modules/i18n/locales/*.po and locales/generated/* with thousands of lines of churn as a side effect of touching any msg string. The i18n pipeline maintains them; leave them out of your commit.
  • Commit messages must not carry AI attribution. CI rejects commits containing @anthropic.com co-author trailers or "Generated with Claude Code" lines.
  • Upgrade commands (packages/twenty-server/src/database/commands/upgrade-version-command/): add or edit files only under the current TWENTY_CURRENT_VERSION directory, with a real epoch-ms timestamp strictly greater than every existing one in that directory — CI enforces both, and the upgrade cursor silently skips a command that sorts before an already-applied one. Include up and down; never rewrite committed command logic. See packages/twenty-server/docs/UPGRADE_COMMANDS.md.
  • Entity file changes need a generated instance command: npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow> (slow = adds a data-backfill step).
  • A read-only Postgres MCP server is configured in .mcp.json for inspecting workspace data, metadata, and migration results. Writes go through the CLI commands above.
  • E2E login: click "Continue with Email" and use the prefilled credentials.