docs: add AGENTS.md (#23426)
* add docs for agents * update * Update .agents/README.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
This commit is contained in:
Eunjae Lee
co-authored by
coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
parent
d125064430
commit
6b84dc09a7
@@ -0,0 +1,82 @@
|
||||
# Cal.com Development Guide for AI Agents
|
||||
|
||||
This directory contains comprehensive documentation for AI agents working on the Cal.com codebase.
|
||||
|
||||
## Quick Navigation
|
||||
|
||||
- **[Commands](commands.md)** - Build, test, and development commands
|
||||
- **[Knowledge Base](knowledge-base.md)** - Knowledge base & best practices
|
||||
- **[Architecture Overview](#architecture-overview)** - System structure and patterns
|
||||
|
||||
## Getting Started
|
||||
|
||||
Cal.com is a monorepo using Yarn workspaces and Turbo for build orchestration. The main application is in `apps/web/` with shared packages in `packages/`.
|
||||
|
||||
### Key Directories
|
||||
|
||||
- `apps/web/` - Main Next.js application
|
||||
- `packages/prisma/` - Database schema and migrations
|
||||
- `packages/trpc/` - API layer using tRPC
|
||||
- `packages/ui/` - Shared UI components
|
||||
- `packages/features/` - Feature-specific code
|
||||
- `packages/app-store/` - Third-party app integrations
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Database Layer
|
||||
|
||||
- **Prisma ORM** with PostgreSQL
|
||||
- Schema in `packages/prisma/schema.prisma`
|
||||
- Always use `select` instead of `include` for better performance
|
||||
- Never expose `credential.key` field in API responses
|
||||
|
||||
### API Layer
|
||||
|
||||
- **tRPC** for type-safe APIs
|
||||
- Routers in `packages/trpc/server/routers/`
|
||||
- Authentication handled via NextAuth.js
|
||||
|
||||
### Frontend
|
||||
|
||||
- **Next.js 13+** with App Router in some areas
|
||||
- **React 18** with TypeScript
|
||||
- **Tailwind CSS** for styling
|
||||
- Internationalization with `next-i18next`
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Error Handling
|
||||
|
||||
- Use early returns to reduce nesting
|
||||
- Throw descriptive errors with proper error codes
|
||||
- Prefer composition over prop drilling
|
||||
|
||||
### Performance
|
||||
|
||||
- Avoid O(n²) logic in backend code
|
||||
- Minimize Day.js usage in performance-critical paths
|
||||
- Use `select` queries to only fetch needed data
|
||||
- Consider using `.utc()` for Day.js operations
|
||||
|
||||
### Security
|
||||
|
||||
- Never commit secrets or API keys
|
||||
- Always validate input data
|
||||
- Use proper authentication checks
|
||||
- Never expose sensitive credential fields
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- **Unit tests** with Vitest
|
||||
- **Integration tests** for complex workflows
|
||||
- **E2E tests** with Playwright
|
||||
- Test files use `.test.ts` or `.spec.ts` extensions
|
||||
|
||||
## Pull Request Guidelines
|
||||
|
||||
For large PRs (>500 lines or >10 files):
|
||||
|
||||
- Split by feature boundaries
|
||||
- Separate database migrations, backend logic, frontend components
|
||||
- Create dependency chains that can be merged sequentially
|
||||
- Pattern: Database → Backend → Frontend → Tests
|
||||
@@ -0,0 +1,56 @@
|
||||
# Coding Standards & Best Practices
|
||||
|
||||
|
||||
|
||||
## Import Guidelines
|
||||
|
||||
### Type Imports
|
||||
|
||||
```typescript
|
||||
// ✅ Good - Use type imports for TypeScript types
|
||||
import type { User } from "@prisma/client";
|
||||
import type { NextApiRequest, NextApiResponse } from "next";
|
||||
|
||||
// ❌ Bad - Regular import for types
|
||||
import { User } from "@prisma/client";
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Code Structure
|
||||
|
||||
### Early Returns
|
||||
|
||||
- Prefer early returns to reduce nesting: `if (!booking) return null;`
|
||||
|
||||
### Composition Over Prop Drilling
|
||||
|
||||
- Use React children and context instead of passing props through multiple components
|
||||
|
||||
### Security Rules
|
||||
|
||||
```typescript
|
||||
// ❌ NEVER expose credential keys
|
||||
const user = await prisma.user.findFirst({
|
||||
select: {
|
||||
credentials: {
|
||||
select: {
|
||||
key: true, // ❌ NEVER do this
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// ✅ Good - Never select credential.key field
|
||||
const user = await prisma.user.findFirst({
|
||||
select: {
|
||||
credentials: {
|
||||
select: {
|
||||
id: true,
|
||||
type: true,
|
||||
// key field is excluded for security
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
@@ -0,0 +1,83 @@
|
||||
# Build, Test & Development Commands
|
||||
|
||||
## Development Commands
|
||||
|
||||
- `yarn dev` - Start development server for web app
|
||||
- `yarn dev:all` - Start web, website, and console apps
|
||||
- `yarn dev:api` - Start web app with API proxy and API
|
||||
- `yarn dev:console` - Start web app with console
|
||||
- `yarn dx` - Start development with database setup
|
||||
|
||||
## Build Commands
|
||||
|
||||
- `yarn build` - Build all packages and apps
|
||||
- `yarn build:ai` - Build AI package specifically
|
||||
- `yarn clean` - Remove build artifacts (node_modules, .next, .turbo, dist)
|
||||
|
||||
## Lint & Type Check
|
||||
|
||||
- `yarn lint` - Run ESLint on codebase
|
||||
- `yarn lint:fix` - Run ESLint and fix issues
|
||||
- `yarn lint:report` - Generate lint report
|
||||
- `yarn type-check` - Run TypeScript type checking
|
||||
- `yarn format` - Format code with Prettier
|
||||
|
||||
## Testing Commands
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- `yarn test` - Run unit tests (vitest)
|
||||
- `yarn test <filename>` - Run tests for specific file
|
||||
- `yarn test <filename> -- --integrationTestsOnly` - Run integration tests for specific file
|
||||
- `yarn test <filename> -t "<testName>" -- --integrationTestsOnly` - Run specific test by name
|
||||
- `yarn tdd` - Run tests in watch mode
|
||||
- `yarn test:ui` - Run tests with UI interface
|
||||
|
||||
### End-to-End Tests
|
||||
|
||||
- `yarn e2e` - Run end-to-end tests (Playwright)
|
||||
- `yarn e2e <filename>` - Run E2E tests for specific file
|
||||
- `yarn e2e <filename> --grep "<testName>"` - Run specific E2E test by name
|
||||
- `yarn e2e:app-store` - Run app store E2E tests
|
||||
- `yarn e2e:embed` - Run embed E2E tests
|
||||
- `yarn test-e2e` - Run database seed + E2E tests
|
||||
|
||||
## Database Commands
|
||||
|
||||
- `yarn prisma` - Run Prisma CLI commands
|
||||
- `yarn db-seed` - Seed database with test data
|
||||
- `yarn db-deploy` - Deploy database migrations
|
||||
- `yarn db-studio` - Open Prisma Studio
|
||||
- `psql "postgresql://postgres:@localhost:5432/calendso"` - Connect to local PostgreSQL database
|
||||
|
||||
## App Store Commands
|
||||
|
||||
- `yarn create-app` - Create new app store integration
|
||||
- `yarn edit-app` - Edit existing app
|
||||
- `yarn delete-app` - Delete app
|
||||
- `yarn app-store:build` - Build app store
|
||||
- `yarn app-store:watch` - Watch app store for changes
|
||||
|
||||
## Useful Development Patterns
|
||||
|
||||
### Running Single Tests
|
||||
|
||||
```bash
|
||||
# Unit test specific file
|
||||
yarn vitest run packages/lib/some-file.test.ts
|
||||
|
||||
# Integration test specific file
|
||||
yarn test routing-form-response-denormalized.integration-test.ts -- --integrationTestsOnly
|
||||
|
||||
# E2E test specific file
|
||||
yarn e2e tests/booking-flow.e2e.ts
|
||||
|
||||
# Run specific test by name
|
||||
yarn e2e tests/booking-flow.e2e.ts --grep "should create booking"
|
||||
```
|
||||
|
||||
### Environment Setup
|
||||
|
||||
- Copy `.env.example` to `.env` and configure
|
||||
- Copy `.env.appStore.example` to `.env.appStore` for app store development
|
||||
- Run `yarn dx` for initial development setup with database
|
||||
@@ -0,0 +1,320 @@
|
||||
# Knowledge Base - Product & Domain-Specific Information
|
||||
|
||||
## Repo note for calcom/cal.com
|
||||
|
||||
The whole thing is a monorepo. You need to be working in the apps/web folder.
|
||||
|
||||
Linting and Formatting
|
||||
- Run lint with report generation: `yarn lint:report`
|
||||
- Run type checking: `yarn type-check:ci --force`
|
||||
- Run auto-fix: `yarn lint -- --fix`
|
||||
|
||||
Development
|
||||
- Install dependencies: `yarn`
|
||||
- Set up environment:
|
||||
- Copy `.env.example` to `.env`
|
||||
- Generate keys with `openssl rand -base64 32` for both `NEXTAUTH_SECRET` and `CALENDSO_ENCRYPTION_KEY`
|
||||
- Configure Postgres database URL in `.env`
|
||||
- Set DATABASE_DIRECT_URL to the same value as DATABASE_URL
|
||||
|
||||
Database Setup
|
||||
- Development: `yarn workspace @calcom/prisma db-migrate`
|
||||
- Production: `yarn workspace @calcom/prisma db-deploy`
|
||||
|
||||
When setting up local development database, it'll create a bunch of users for you. The passwords are the same as the username. e.g. 'free:free' and 'pro:pro'
|
||||
|
||||
PR Requirements
|
||||
- PR title must follow Conventional Commits specification
|
||||
- For most PRs, you only need to run linting and type checking
|
||||
- E2E tests will only run if PR has "ready-for-e2e" label
|
||||
|
||||
Logging
|
||||
- Control logging verbosity by setting `NEXT_PUBLIC_LOGGER_LEVEL` in .env:
|
||||
- 0: silly
|
||||
- 1: trace
|
||||
- 2: debug
|
||||
- 3: info
|
||||
- 4: warn
|
||||
- 5: error
|
||||
- 6: fatal
|
||||
|
||||
## When addressing issues in the Cal.com repository
|
||||
|
||||
When working on the Cal.com repository, prioritize fixing type issues before addressing failing tests. Running `yarn type-check:ci --force` to identify and fix TypeScript errors should be done first, as these errors are often the root cause of test failures. Only after resolving type issues should you move on to fixing failing tests with `TZ=UTC yarn test`.
|
||||
|
||||
## When creating pull requests
|
||||
|
||||
Create pull requests in draft mode by default, so that actual human can mark it as ready for review only when it is.
|
||||
|
||||
## When developing Playwright tests in the Cal.com repository
|
||||
|
||||
Always ensure Playwright tests pass locally before pushing code. The user requires fast local e2e feedback loops instead of relying on CI, which is too slow for development iteration. Never push test code until those tests are passing locally first.
|
||||
|
||||
## When fixing failing tests in the Cal.com repository
|
||||
|
||||
When fixing failing tests in the Cal.com repository, take an incremental approach by addressing one file at a time rather than attempting to fix all issues simultaneously. This methodical approach makes it easier to identify and resolve specific issues without getting overwhelmed by the complexity of multiple failing tests across different files. Focus on getting each file's tests passing completely before moving on to the next file.
|
||||
|
||||
To identify and fix issues in the Cal.com codebase:
|
||||
|
||||
1. Run `yarn type-check:ci --force` to identify TypeScript type errors and get fresh results always, bypassing any caching issues
|
||||
2. Run `yarn test` to identify failing unit tests
|
||||
3. Address both type errors and failing tests before considering the task complete
|
||||
4. Type errors often need to be fixed first as they may be causing the test failures
|
||||
|
||||
## When implementing mock services in the Cal.com test files
|
||||
|
||||
When mocking calendar services in Cal.com test files, implement the Calendar interface rather than adding individual properties from each specific calendar service type (like FeishuCalendarService). Since all calendar services implement the Calendar interface and are stored in a map, the mock service should also implement this interface to ensure type compatibility. This approach is more maintainable than trying to add all properties from each specific calendar service implementation. For complex mocks that cause type compatibility issues with deep mocks, consider using simpler fake implementations that directly implement the required interfaces instead of trying to match all properties of the original service classes. When needed, you can modify other mock files to support your implementation rather than trying to force compatibility with existing mocks.
|
||||
|
||||
## When implementing mocks for Cal.com app-store integrations
|
||||
|
||||
When mocking app-store resources in Cal.com tests, prefer implementing simpler mock designs that directly implement the required interfaces rather than trying to match complex deep mock structures created with mockDeep. This approach is more maintainable and helps resolve type compatibility issues. The user encourages creative solutions and refactoring to better designs when the standard mocking approach causes persistent type errors.
|
||||
|
||||
## When implementing workflow triggers in the Cal.com repository
|
||||
|
||||
To trigger workflows in Cal.com, use the `scheduleWorkflowReminders` function. This is the standard approach used throughout the codebase for triggering any workflow. Before implementing new workflow triggers, examine existing implementations in the codebase to understand the pattern. The function filters workflows by trigger type and processes each workflow step. Key locations where this is used include booking handlers, confirmation processes, and other booking-related events.
|
||||
|
||||
## When making changes to Prisma schema in Cal.com
|
||||
|
||||
After making changes to the Prisma schema in Cal.com and creating migrations, you need to run `yarn prisma generate` to update the TypeScript types. This is especially important when switching Node.js versions, after adding new fields to models, or after pulling changes that include Prisma schema updates, as it ensures the TypeScript compiler recognizes the updated schema structure. If you encounter errors related to missing enum values (like CreationSource.WEBAPP), running `yarn prisma generate` will typically resolve these issues by regenerating the TypeScript types from the schema.
|
||||
|
||||
If you encounter enum generator errors during the Prisma generate step (like "Cannot find module './enum-generator.ts'"), run `yarn install` first before trying to generate. This ensures all dependencies are properly installed before the generation process.
|
||||
|
||||
Whenever you change the schema.prisma file, remember to always consolidate migrations by squashing them as declared in the Prisma docs: https://www.prisma.io/docs/orm/prisma-migrate/workflows/squashing-migrations. This helps maintain a clean migration history and prevents accumulation of multiple migration files.
|
||||
|
||||
## When reviewing PRs in the Cal.com repository
|
||||
|
||||
When asked to review a PR, focus on providing a clear summary of what the PR is doing and its core functionality. Avoid getting sidetracked by CI failures, testing issues, or technical implementation details unless specifically requested. The user prefers concise, focused reviews that prioritize understanding the main purpose and changes of the PR.
|
||||
|
||||
## When running Playwright tests in the Cal.com repository
|
||||
|
||||
Use the command format `PLAYWRIGHT_HEADLESS=1 yarn e2e [test-file.e2e.ts]` to run Playwright tests instead of the standard `yarn playwright test` command. This format includes the proper timezone setting, virtual display server, and uses the repository's e2e runner.
|
||||
|
||||
## When running tests in the Cal.com repository
|
||||
|
||||
When running tests in the Cal.com repository, use the TZ=UTC environment variable (e.g., `TZ=UTC yarn test`) to ensure consistent timezone handling. This prevents timezone-related test failures that might occur when tests are run in different environments or by different developers with varying local timezone settings.
|
||||
|
||||
## When working on calendar cache features in the Cal.com codebase
|
||||
|
||||
The calendar cache system follows specific patterns in `packages/features/calendar-cache-sql`. When implementing provider-specific calendar cache services (like for Outlook/Office365), the provider-specific code should be placed in the corresponding provider directory (e.g., `packages/app-store/office365calendar`).
|
||||
|
||||
## When working on PRs in the Cal.com repository
|
||||
|
||||
When making changes to the Cal.com codebase, always run type checks locally using `yarn type-check:ci` before concluding that CI failures are unrelated to your changes. Even if errors appear in files you haven't directly modified, your changes might still be causing type issues through dependencies or type inference. Compare type check results between the main branch and your feature branch to confirm whether you've introduced new type errors.
|
||||
|
||||
## When working on type issues in the Cal.com repository
|
||||
|
||||
Type casting with "as any" is strictly forbidden in the Cal.com codebase. When encountering Prisma type incompatibilities or other TypeScript type issues, proper type-safe solutions must be used instead, such as Prisma extensions system, type parameter constraints, repository pattern isolation, explicit type definitions, and extension composition patterns that are already established in the codebase.
|
||||
|
||||
## When working on UI layout changes in the Cal.com web application
|
||||
|
||||
The event types page UI components are located in `apps/web/modules/event-types/views/event-types-listing-view.tsx`. This file contains the layout implementation for the search bar and team tabs components on the event types listing page.
|
||||
|
||||
Changes to shared UI patterns (like tab layouts and button alignments) need to be checked across multiple views to maintain consistency:
|
||||
- Event types page layout: `apps/web/modules/event-types/views/event-types-listing-view.tsx`
|
||||
- Bookings page layout: `apps/web/modules/bookings/views/bookings-listing-view.tsx`
|
||||
- Common elements like tabs, search bars, and filter buttons should maintain consistent alignment across views
|
||||
|
||||
## When working on workflow triggers or similar enum-based features in the Cal.com codebase
|
||||
|
||||
To add new workflow triggers:
|
||||
|
||||
1. Check packages/prisma/schema.prisma for existing webhooks and workflow trigger enums as reference
|
||||
2. Add the same enums to workflows (only when asked by user specifically, or else focus on users requirement)
|
||||
3. Add enums to packages/features/ee/workflows/lib/constants.ts for UI display
|
||||
4. Add translations to en/locale.json using the format {enum}_trigger (all lowercase). Webhook triggers serve as the reference implementation pattern for workflow triggers.
|
||||
|
||||
## When working with app-store integrations in Cal.com
|
||||
|
||||
The Cal.com repository uses generated files (*.generated.ts) for app-store integrations. These files are created by the app-store-cli tool. When making structural changes to how integrations are imported or used, you need to update CLI code that generates these files. Typically manual changes to the *.generated.ts files are not made. That was only for PR 19771 for a proof-of-concept. Recent changes have moved from dynamic imports to static map-based imports for better performance. When working with browser components in the app-store, static imports should be used rather than dynamic imports (using Next.js' dynamic function) to maintain consistency with the performance improvements.
|
||||
|
||||
When modifying the app-store-cli build.ts file, you must ensure it correctly handles all types of generated files:
|
||||
1. Regular service files (calendar.services.generated.ts, crm.services.generated.ts, etc.) need default imports
|
||||
2. Browser component files (apps.browser-addon.generated.tsx, etc.) may require dynamic imports with Next.js
|
||||
3. After making changes to build.ts, always verify all generated files have the correct imports by checking each file type
|
||||
|
||||
The lazyImport parameter in getExportedObject() determines whether to use dynamic imports (for browser components) or static imports (for server-side services).
|
||||
|
||||
## When working with branches in the Cal.com repository
|
||||
|
||||
When asked to move changes to a different branch in the Cal.com repository, use git commands to commit existing changes to the specified branch rather than redoing the work. This is more efficient and prevents duplication of effort. The user prefers direct branch operations over reimplementing the same changes multiple times.
|
||||
|
||||
## When working with calendar events in the Cal.com codebase
|
||||
|
||||
Cal.com events in Google Calendar can be identified by checking if the iCalUID ends with "@Cal.com" (e.g., "2GBXSdEixretciJfKVmYN8@Cal.com"). This identifier is used to distinguish Cal.com bookings from other calendar events for data storage and privacy purposes.
|
||||
|
||||
## When working with CI/CD in the Cal.com repository
|
||||
|
||||
When reviewing CI check failures in Cal.com:
|
||||
1. E2E tests can be flaky and may fail intermittently
|
||||
2. Focus only on CI failures that are directly related to your code changes
|
||||
3. Infrastructure-related failures (like dependency installation issues) can be disregarded if all code-specific checks (type checking, linting, unit tests) are passing
|
||||
|
||||
## When working with database models in Cal.com
|
||||
|
||||
Database models in Cal.com are defined in `packages/prisma/schema.prisma`. When adding new fields to models:
|
||||
|
||||
1. For timestamp fields like `createdAt` and `updatedAt`:
|
||||
- Do not set default values if you want existing records to have null values
|
||||
- Only new records should get timestamps automatically
|
||||
- For `updatedAt` fields, ensure they're updated when records are modified
|
||||
|
||||
2. Create a migration using `npx prisma migrate dev --name migration_name` to update the database schema
|
||||
|
||||
3. When implementing cache-related features that require timestamp tracking, always update the database schema first before modifying application code that references those fields. The schema changes must be completed and migrated before the application can successfully query or use the new fields.
|
||||
|
||||
## When working with generated files in the Cal.com repository
|
||||
|
||||
When fixing imports in Cal.com's generated files (like packages/app-store/apps.browser-*.generated.tsx), always check the actual exports in the source files first. For EventTypeAppCardInterface components, they likely use named exports rather than default exports, requiring imports like `import * as ComponentName from "./path"` instead of `import ComponentName from "./path"`. This verification step is crucial when working with browser-addon, browser-appsettings, browser-eventtypesettings, and browser-install generated files. For these files, if you're seeing import errors, check whether the components are exported as default exports in their source files and adjust your import statements accordingly.
|
||||
|
||||
## When working with git and CI systems
|
||||
|
||||
Always push committed changes to the remote repository before waiting for or checking CI status. Waiting for CI checks on unpushed local commits is backwards - the CI runs on the remote repository state, not local commits. The proper sequence is: commit locally, run local checks, push to remote, then monitor CI status.
|
||||
|
||||
## When working with imports/exports in the Cal.com codebase
|
||||
|
||||
When working with imports in the Cal.com codebase, particularly in app-store integrations, pay attention to whether modules use named exports or default exports. Many services like VideoApiAdapter, CalendarService, and PaymentService are exported as named exports, but the actual export name may differ from the generic service type (e.g., `export class AppleCalendarService` instead of `export class CalendarService`). When importing these services, verify the actual export name in the source file and use the appropriate named import syntax (e.g., `import { AppleCalendarService } from "./applecalendar/lib/CalendarService"` or with renaming `import { AppleCalendarService as ApplecalendarCalendarService } from "./applecalendar/lib/CalendarService"`). Always check the actual export pattern and name in the source file to determine the correct import syntax.
|
||||
|
||||
## When working with tRPC components in the Cal.com repository
|
||||
|
||||
When making changes that affect tRPC components or after pulling updates that modify tRPC-related files, you need to follow a specific build order:
|
||||
1. First run `yarn prisma generate` to ensure all database types are up-to-date
|
||||
2. Then run `cd packages/trpc && yarn build` to rebuild the tRPC package
|
||||
This sequence ensures that type definitions are properly generated before building the tRPC components that depend on them, preventing type errors during compilation.
|
||||
|
||||
## When working with workflows or webhooks in the Cal.com repository
|
||||
|
||||
Workflows and webhooks are two completely separate features in Cal.com with different implementations and file structures. The workflow constants file is located at `packages/features/ee/workflows/lib/constants.ts`, not in the webhooks directory. When working on workflow triggers, do not reference or use webhook trigger implementations - they are distinct systems that should not be confused or mixed.
|
||||
|
||||
## When adding new feature flags to the Cal.com repository
|
||||
|
||||
To seed new feature flags in Cal.com, create a Prisma migration using the command `yarn prisma migrate dev --create-only --name seed_[feature_name]_feature`. The migration file should be placed in `packages/prisma/migrations/` with a timestamp prefix format like `20250724210733_seed_calendar_cache_sql_features/migration.sql`. Follow the pattern from existing feature seeding migrations like `packages/prisma/migrations/20241216000000_add_calendar_cache_serve/migration.sql` for the SQL structure. The migration should INSERT the new features into the `Feature` table with appropriate type (like `OPERATIONAL`) and default `enabled` status for manual team enablement.
|
||||
|
||||
## When adding new UI elements or text strings to Cal.com
|
||||
|
||||
All UI strings in Cal.com must be properly translated using the i18n system. This includes:
|
||||
- Labels for new UI elements (like dropdown labels, settings headers)
|
||||
- Option values that are displayed to users
|
||||
- Any text that appears in the interface
|
||||
|
||||
Even if some related strings are already translated (like "Bookings" and "Insights"), new strings must be explicitly added to the translation system.
|
||||
|
||||
## When creating a pull request
|
||||
|
||||
### Title
|
||||
|
||||
- Use conventional commits: `feat:`, `fix:`, `refactor:`
|
||||
- Be specific: `fix: handle timezone edge case in booking creation`
|
||||
- Not generic: `fix: booking bug`
|
||||
|
||||
### Size Limits
|
||||
|
||||
- **Large PRs** (>500 lines or >10 files) are not recommended.
|
||||
- Guide the user how to split large PRs into smaller ones.
|
||||
|
||||
## When handling errors
|
||||
|
||||
### Descriptive Errors
|
||||
|
||||
```typescript
|
||||
// ✅ Good - Descriptive error with context
|
||||
throw new Error(`Unable to create booking: User ${userId} has no available time slots for ${date}`);
|
||||
|
||||
// ❌ Bad - Generic error
|
||||
throw new Error("Booking failed");
|
||||
```
|
||||
|
||||
### Error Types
|
||||
|
||||
```typescript
|
||||
// ✅ Good - Use proper error classes
|
||||
import { TRPCError } from "@trpc/server";
|
||||
|
||||
throw new TRPCError({
|
||||
code: "BAD_REQUEST",
|
||||
message: "Invalid booking time slot",
|
||||
});
|
||||
```
|
||||
|
||||
## Basic Performance Guidelines
|
||||
|
||||
- Aim for O(n) or O(n log n) complexity, avoid O(n²)
|
||||
- Use database-level filtering instead of JavaScript filtering
|
||||
- Consider pagination for large datasets
|
||||
- Use database transactions for related operations
|
||||
|
||||
## When querying database
|
||||
|
||||
Prefer Select over Include:
|
||||
|
||||
```typescript
|
||||
// ✅ Good - Use select for performance and security
|
||||
const booking = await prisma.booking.findFirst({
|
||||
select: {
|
||||
id: true,
|
||||
title: true,
|
||||
user: {
|
||||
select: {
|
||||
id: true,
|
||||
name: true,
|
||||
email: true,
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// ❌ Bad - Include fetches all fields
|
||||
const booking = await prisma.booking.findFirst({
|
||||
include: {
|
||||
user: true, // This gets ALL user fields
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## Avoid barrel imports
|
||||
|
||||
```typescript
|
||||
// ❌ Bad - Avoid importing from index.ts barrel files
|
||||
import { BookingService, UserService } from "./services";
|
||||
|
||||
// ✅ Good - Import directly from source files
|
||||
import { BookingService } from "./services/BookingService";
|
||||
import { UserService } from "./services/UserService";
|
||||
|
||||
|
||||
// ❌ Bad
|
||||
import { Button } from "@calcom/ui";
|
||||
|
||||
// ✅ Good - Import directly from source files
|
||||
import { Button } from "@calcom/ui/components/button";
|
||||
```
|
||||
|
||||
## File Naming Conventions
|
||||
|
||||
### Repository Files
|
||||
|
||||
- **Must** include `Repository` suffix, PascalCase matching class: `PrismaBookingRepository.ts`
|
||||
|
||||
### Service Files
|
||||
|
||||
- **Must** include `Service` suffix, PascalCase matching class, avoid generic names: `MembershipService.ts`
|
||||
|
||||
### General Files
|
||||
|
||||
- **Components**: PascalCase (e.g., `BookingForm.tsx`)
|
||||
- **Utilities**: kebab-case (e.g., `date-utils.ts`)
|
||||
- **Types**: PascalCase with `.types.ts` suffix (e.g., `Booking.types.ts`)
|
||||
- **Tests**: Same as source file + `.test.ts` or `.spec.ts`
|
||||
- **Avoid**: Dot-suffixes like `.service.ts`, `.repository.ts` (except for tests, types, specs)
|
||||
|
||||
## When using Day.js
|
||||
|
||||
```typescript
|
||||
// ⚠️ Slow in performance-critical code (loops)
|
||||
dates.map((date) => dayjs(date).add(1, "day").format());
|
||||
|
||||
// ✅ Better - Use .utc() for performance
|
||||
dates.map((date) => dayjs.utc(date).add(1, "day").format());
|
||||
|
||||
// ✅ Best - Use native Date when possible
|
||||
dates.map((date) => new Date(date.valueOf() + 24 * 60 * 60 * 1000));
|
||||
```
|
||||
@@ -0,0 +1,20 @@
|
||||
# Cal.com Development Guide for AI Agents
|
||||
|
||||
**📖 Complete documentation is in the [.agents/](.agents/) directory.**
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Essential Commands
|
||||
|
||||
- `yarn dev` - Start development server
|
||||
- `yarn build` - Build all packages
|
||||
- `yarn lint:fix` - Lint and fix code
|
||||
- `yarn type-check` - TypeScript checking
|
||||
- `yarn test <filename> -- --integrationTestsOnly` - Run integration tests
|
||||
- `yarn e2e <filename> --grep "<testName>"` - Run specific E2E test
|
||||
|
||||
## 📚 Detailed Documentation
|
||||
|
||||
- **[.agents/README.md](.agents/README.md)** - Complete development guide
|
||||
- **[.agents/commands.md](.agents/commands.md)** - All build, test & dev commands
|
||||
- **[.agents/knowledge-base.md](.agents/knowledge-base.md)** - Knowledge base & best practices
|
||||
Reference in New Issue
Block a user