Introduction
Cal.com is structured as a monorepo using Turborepo. Cal.com is built on NextJS with Typescript, PostgreSQL database and the interactions with the database are carried out using Prisma. We use TRPC for end-to-end typesafe procedure calls to Prisma and utilize Zod for validation and type-safe parsing of API calls.Setting Up the Development Environment
Prerequisites
Here is what you need to be able to run Cal.com.- Node.js (Version: >=18.x)
- PostgreSQL
- Yarn (recommended)
Understanding the Project Structure
Cal.com makes use of Turborepo for a monorepo structure. This allows us to manage multiple code projects (like libraries, apps, services) and share code and resources effectively. You can look at turbo.json to see how we use it. In simple terms,- Each entry in the
pipeline
section corresponds to a different part of the project. Understanding these will help in navigating the codebase. - Knowing which tasks depend on others is crucial for understanding the build process.
- The
env
entries under each task highlight the need for specific configuration settings, which you will need to set up in your development environment. - You should focus on the tasks related to the area you are contributing to. For example, if working on the Prisma schema, look at tasks prefixed with
@calcom/prisma
- The various packages can be found in the /packages folder from the root.
- The various pages and components for the web can be found in the /apps/web folder from the root.
- The public API related codebase can be found in the /apps/api folder from the root.
- The Cal.ai related codebase can be found in the /apps/ai folder from the root
File Naming Conventions
To ensure consistency and make files easy to fuzzy-find, we follow the naming conventions below for services, repositories, and other class-based files.Repository Files
- Repository class files must include the
Repository
suffix. - If the repository is backed by a specific technology (e.g. Prisma), prefix the filename and class name with it.
- File name must match the exported class exactly (PascalCase).
<Entity>
Repository.ts
Examples:
Service Files
Service class files must include the Service suffix. File name should be in PascalCase, matching the exported class. Keep naming specific — avoid generic names like AppService.ts. Pattern:<Entity>
Service.ts
Examples:
New files must avoid dot-suffixes like .service.ts or .repository.ts; these will be migrated from the existing codebase progressively.
We still reserve suffixes such as .test.ts, .spec.ts, and .types.ts for their respective use cases.
We still reserve suffixes such as .test.ts, .spec.ts, and .types.ts for their respective use cases.
How we use TRPC at cal.com
Cal.com makes use of the TRPC calls for CRUD operations on the database by utilizing the useQuery() & useMutation() hooks. These are essentially wrappers around @tanstack/react-query and you can learn more about them here, respectively: queries, mutations. Here’s an example usage of useQuery at cal.com:create.handler.ts
in case of
list.handler.ts
in case of
The Cal.com API V1
Our API V1 uses zod validations to keep us typesafe and give us extensive parsing control and error handling. These validations reside in /apps/api/lib/validations. We also have helper and utility functions which are used primarily within our API endpoints. Here’s an example usage of our zod validation in action with the respective API endpoint:Building Apps for Cal.com
We’ve got an app store containing apps which complement the scheduling platform. From video conferencing apps such as Zoom, Google Meet, etc. to Calendar Apps such as Google Calendar, Apple Calendar, CalDAV, etc. and even payment, automation, analytics and other miscellaneous apps, it is an amazing space to improve the scheduling experience. We have a CLI script in place that makes building apps a breeze. You can learn more about it here.Running Tests
E2E-Testing
Be sure to set the environment variableNEXTAUTH_URL
to the correct value. If you are running locally, as the documentation within .env.example
mentions, the value should be http://localhost:3000
.
In a terminal just run:
Resolving issues
E2E test browsers not installed If you face the following error when runningyarn test-e2e
:
Executable doesn’t exist at /Users/alice/Library/Caches/ms-playwright/chromium-1048/chrome-mac/Chromium.app