platform

Purpose

packages/platform/ is the Cal.com Platform SDK. It exists so that third-party SaaS products can embed Cal scheduling into their own products via well-typed React components ("atoms") talking to the REST API in apps/api/v2.

There are five workspaces under this umbrella:

• atoms — published as @calcom/atoms. React components (Booker, Availability, Connect, ...) that render Cal.diy UIs and call REST API v2.
• libraries — published as @calcom/platform-libraries. Re-exports shared logic from @calcom/features and @calcom/trpc so that apps/api/v2 can consume them. Documented in AGENTS.md as the canonical bridge.
• types — published as @calcom/platform-types. Shared Zod schemas + TypeScript types for the v2 API.
• enums — published as @calcom/platform-enums. Plain enums extracted from Prisma so SDK consumers don't pull in the entire Prisma client.
• constants — @calcom/platform-constants.
• utils — @calcom/platform-utils.
• examples/ — sample integrations consuming the SDK.

Directory layout

platform/
├── atoms/                 # The React SDK
│   ├── availability/
│   ├── booker/
│   ├── booker-embed/
│   ├── cal-provider/
│   ├── calendar-settings/
│   ├── calendar-view/
│   ├── connect/
│   ├── create-schedule/
│   ├── destination-calendar/
│   ├── event-types/
│   ├── hooks/
│   ├── lib/
│   ├── selected-calendars/
│   ├── timezone/
│   ├── troubleshooter/
│   ├── kysely-types/
│   ├── prisma-types/
│   ├── components.json
│   ├── globals.css, sources.css, styles.css
│   ├── postcss.config.js, vite.config.ts, tsconfig.json
│   ├── package.json
│   ├── README.md, STRIPE.md, CHANGELOG.md
│   └── src/, static/, scripts/
├── libraries/             # Re-exports for apps/api/v2 — DO NOT use directly from web
├── types/                 # Zod + TS for v2
├── enums/
├── constants/
├── utils/
└── examples/              # Sample apps using the SDK

Atoms

Each atom is a top-level directory under packages/platform/atoms/ (e.g., booker/, availability/, event-types/, calendar-settings/, ...). They render the Cal.diy UI for a specific domain and call REST endpoints via @calcom/platform-libraries.

A consumer's app would do:

import { Booker, CalProvider } from '@calcom/atoms';

<CalProvider
  clientId={clientId}
  accessToken={token}
  options={{ apiUrl: '...' }}
>
  <Booker eventSlug='30min' username='me' />
</CalProvider>;

libraries (the bridge)

packages/platform/libraries/index.ts re-exports symbols from @calcom/features, @calcom/trpc, and other internal packages. apps/api/v2's tsconfig.json does not have path mappings for those internal packages, so this indirection is mandatory for any code in apps/api/v2 that needs to reach into shared logic. AGENTS.md documents the rule:

When importing from @calcom/features or @calcom/trpc into apps/api/v2, do not import directly. Re-export from packages/platform/libraries/index.ts and import from @calcom/platform-libraries.

If you skip this you will see "module not found" errors in the API v2 build.

types

packages/platform/types/ holds Zod schemas that serve as the contract between API v2 controllers and SDK consumers. These same schemas are used to validate request bodies inside NestJS controllers and to type the SDK responses.

Versioned types follow the same <resource>_<YYYY_MM_DD> convention as the apps/api/v2/src/platform/ directories.

examples

packages/platform/examples/base/ is a minimal Next.js app that imports @calcom/atoms and renders a few atoms. It serves as a smoke test plus a quick-start template for SDK consumers.

Build and publish

yarn changesets-release — declared in the root package.json — builds the atoms package with an increased Node memory limit and publishes via Changesets:

"changesets-release": "NODE_OPTIONS='--max_old_space_size=12288' turbo run build-npm --filter=@calcom/atoms && yarn changeset publish"

The atoms build is run on every PR by .github/workflows/atoms-production-build.yml and the e2e suite by .github/workflows/e2e-atoms.yml.

How it fits together

graph LR
    SDKConsumer[Third-party Next.js app] -->|uses| Atoms[platform/atoms]
    Atoms -->|REST| APIv2[apps/api/v2]
    APIv2 -->|imports via| Libraries[platform/libraries]
    Libraries --> Features[packages/features]
    Libraries --> TRPC[packages/trpc]
    Atoms -->|types| Types[platform/types]
    APIv2 -->|validates| Types

Entry points for modification

• Add an atom: scaffold a new directory under packages/platform/atoms/, mirror the structure of an existing atom (e.g., availability/), wire it through index.ts. Add an example in packages/platform/examples/base/.
• Expose a feature to the API v2: re-export it from packages/platform/libraries/index.ts. Then import via @calcom/platform-libraries inside apps/api/v2.
• Add a v2 type: drop a Zod schema in packages/platform/types/, give it a versioned filename, and reference it from the corresponding controller in apps/api/v2/src/platform/.

Related pages

• API v2 — the REST surface atoms talk to
• embeds — the older iframe-based embed approach (still maintained)
• features — what platform/libraries re-exports