Getting started

Spin up a local Cal.diy instance for the first time. The README at the repo root has a longer installation walkthrough; this page is the engineering "five-minute" version.

Prerequisites

• Node.js ≥ 18 (the engines block in package.json enforces npm >= 7 and yarn >= 4.12.0)
• Yarn 4 — corepack enable + corepack prepare yarn@4.12.0 --activate
• PostgreSQL ≥ 13 (a Docker Compose file at docker-compose.yml boots one quickly)
• Optional: Redis (for caching/rate limiting), Stripe / SendGrid / Twilio API keys (for full integration coverage), Daily.co API key (for first-party video)

Clone, install, configure

git clone https://github.com/calcom/cal.com.git
cd cal.com
yarn
cp .env.example .env
cp .env.appStore.example .env.appStore

Generate the two required secrets:

echo "NEXTAUTH_SECRET=$(openssl rand -base64 32)" >> .env
echo "CALENDSO_ENCRYPTION_KEY=$(openssl rand -base64 24)" >> .env

CALENDSO_ENCRYPTION_KEY encrypts third-party credentials in the Credential.key column — never expose this column in API responses (AGENTS.md calls this out explicitly).

Database

docker compose up -d database  # if you don't already have Postgres
yarn workspace @calcom/prisma prisma migrate deploy
yarn workspace @calcom/prisma prisma generate
yarn db-seed

Seeding lives in packages/prisma/seed.ts and the scripts/seed-*.ts helpers. seed-app-store.ts populates the App table from the metadata generated by packages/app-store-cli.

Run the apps

# Just the web app
yarn dev

# Web + the local API v2 NestJS service
yarn dev:api

# Web + the marketing website
yarn dev:website

# Everything (web, website, console)
yarn dev:all

yarn dev resolves to turbo run dev --filter="@calcom/web" (see package.json). Turbo's turbo.json declares the dev / build / lint / test pipelines and their cache policy.

Test, lint, type-check

yarn test               # Vitest unit tests, runs in TZ=UTC
yarn type-check         # turbo run type-check across workspaces
yarn type-check:ci      # same but with the CI log prefix off
yarn lint               # turbo lint (Biome under the hood)
yarn lint:fix
yarn format             # biome format --write .
yarn e2e                # Playwright (requires DB + dev server)
yarn test-e2e           # yarn db-seed && yarn e2e

Important nuance from AGENTS.md:

Run yarn type-check:ci --force before concluding CI failures are unrelated to your changes.

App Store CLI

If you change anything under packages/app-store/<provider>, regenerate the registry:

yarn app-store-cli  # interactive
yarn app-store:build

The generated files (e.g., packages/app-store/apps.metadata.generated.ts) must not be edited by hand.

Environment files cheatsheet

File	Purpose
.env	Web app + database + auth secrets (mirror .env.example)
.env.appStore	Per-integration API keys (mirror .env.appStore.example)
apps/api/v2/.env	NestJS API config (mirror apps/api/v2/.env.example)

yarn env-check:common and yarn env-check:app-store validate that .env covers everything the schema requires.

Common gotchas

• Symlinked .env for Prisma. packages/prisma/.env is a symlink to ../../.env. On Windows, the README recommends replacing it with a real copy because Prisma chokes on the / character in symlink names.
• App-store generated files. If you see "Module not found" for @calcom/app-store/...generated, run yarn app-store:build.
• yarn prisma generate after every schema.prisma change. The Prisma client is committed-out (in .gitignore) under packages/prisma/generated/.
• TypeScript memory. Large refactors may need NODE_OPTIONS="--max_old_space_size=12288" (the changesets release script does this).

Next steps

• Skim how-to-contribute/ for the PR workflow and project conventions.
• Read apps/web for the structure of the main Next.js app.
• Look at features/bookings to understand the booking lifecycle.