Platform Atoms Overview
Purpose and Scope
Platform atoms are the developer-facing UI building blocks for embedding Cal scheduling experiences inside another React or Next.js application. The atoms README describes the package as customizable UI components for integrating scheduling into services, which is the right mental model: these are not a separate scheduling backend, but a packaged interface layer that lets a host application present Cal-powered flows while relying on the surrounding Cal.diy platform and configuration. In a self-hosted Cal.diy deployment, use atoms when you want scheduling UI to live in your product surface rather than redirecting users to the full Cal web app.
Sources: packages/platform/atoms/README.md
This overview focuses on the public package surfaces visible from the requested entrypoints: provider setup, availability settings, and calendar settings. The exported names show a small but important contract. Provider exports establish context and OAuth support for atom consumers. Availability exports expose both a complete settings component and a platform wrapper, plus shared atom types. Calendar settings exposes its own platform wrapper. Together these files describe how the package is meant to be consumed: import stable atom entrypoints rather than reaching into internal component paths.
Sources: packages/platform/atoms/cal-provider/index.ts, packages/platform/atoms/availability/index.ts, packages/platform/atoms/calendar-settings/index.ts
Relevant Source Files
packages/platform/atoms/README.md- User and contributor guide for the atoms package, including supported React and Next.js versions, semantic versioning, changelog expectations, changesets release flow, and local testing notes.packages/platform/atoms/cal-provider/index.ts- Public provider entrypoint that re-exportsCalProviderandCalOAuthProviderfor applications embedding atom components.packages/platform/atoms/availability/index.ts- Public availability entrypoint that exportsAvailabilitySettingsPlatformWrapper,AvailabilitySettings, and the shared atom types namespace.packages/platform/atoms/calendar-settings/index.ts- Public calendar settings entrypoint that exportsCalendarSettingsPlatformWrapperfor embedded calendar configuration experiences.
Core Primitives
The first primitive is the provider layer. CalProvider is the general provider export, while CalOAuthProvider signals that atoms can participate in OAuth-backed platform flows. A host application should treat this layer as the boundary where shared configuration, identity state, and platform connection details are made available to descendant atom components. The entrypoint intentionally exports providers from a package-level path, which gives consumers a stable import target and allows the implementation files to evolve without requiring application code to import directly from nested internals.
Sources: packages/platform/atoms/cal-provider/index.ts
The second primitive is an embeddable settings surface. AvailabilitySettings is exported as a named component, and AvailabilitySettingsPlatformWrapper is exported beside it. That pairing suggests two levels of consumption: applications that need the raw availability settings UI can import the component, while platform-oriented integrations can import the wrapper that adapts the UI to the platform context expected by the package. The same availability entrypoint also re-exports from ../types, so consumers should prefer this namespace when they need atom-related TypeScript contracts associated with the availability flow.
Sources: packages/platform/atoms/availability/index.ts
The third primitive is the calendar settings wrapper. The calendar settings entrypoint exports CalendarSettingsPlatformWrapper, which mirrors the wrapper pattern used by availability. Calendar settings are a distinct part of the scheduling configuration experience: they deal with which calendars are connected or used for booking behavior, while availability settings describe when a user can be booked. Keeping these wrappers separate lets a host application compose only the settings experience it needs, while still using the same provider and platform context conventions.
Sources: packages/platform/atoms/calendar-settings/index.ts
Public API Components
| Entry point | Exported names | Consumer intent |
|---|---|---|
packages/platform/atoms/cal-provider/index.ts | CalProvider, CalOAuthProvider | Wrap atom usage with Cal platform context and OAuth-aware provider behavior. |
packages/platform/atoms/availability/index.ts | AvailabilitySettingsPlatformWrapper, AvailabilitySettings, export * from ../types | Embed or wrap availability configuration UI and consume shared atom types. |
packages/platform/atoms/calendar-settings/index.ts | CalendarSettingsPlatformWrapper | Embed calendar settings through the platform wrapper contract. |
These entrypoints form the safe import surface for the atom areas covered here. A consumer should import from the package-level feature directories instead of relying on implementation files such as ./wrappers/... or component internals. The index files exist to define what is public, and that public surface is intentionally concise. When adding a new atom or exposing additional behavior, contributors should update the relevant index file deliberately so downstream applications can depend on a documented export rather than an accidental internal path.
Sources: packages/platform/atoms/cal-provider/index.ts, packages/platform/atoms/availability/index.ts, packages/platform/atoms/calendar-settings/index.ts
Compatibility, Versioning, and Release Model
The atoms README states that the package currently supports React 18, React 19, Next 14, and Next 15. That compatibility statement matters for self-hosters and application developers because atoms are designed to be embedded into existing frontends, not only into one specific app shell. Before upgrading React, Next.js, or @calcom/atoms, validate that the host application stays inside those supported ranges. The README also points readers to the changelog and to versioning pull requests titled chore: version packages, which are the places to inspect upcoming or recently published atom changes.
Sources: packages/platform/atoms/README.md
Versioning follows semantic versioning according to the README: updates other than major versions should generally be safe, while breaking changes are marked in the changelog as ❗️Breaking change. The README also calls out suffixed versions such as 1.0.102-framer, which are intended for isolated use cases; most consumers should prefer unsuffixed versions such as 1.0.103. For a production-like embedded integration, do not treat every published tag as equivalent. Choose the normal version line unless you know you need a specialized suffix, and read the changelog before adopting a major update.
Sources: packages/platform/atoms/README.md
Contributor and Testing Signals
Contributors should use changesets for atom changes. The README explains that after finishing a development branch, a contributor runs yarn changesets-add from the monorepo root, selects @calcom/atoms, chooses a semantic version impact, writes a summary, and commits the generated file under .changeset. The contributor does not manually edit the package version for the feature branch; changesets later opens the versioning pull request, updates the changelog, updates package.json, and publishes to npm when the merged version is higher than the currently published package.
Sources: packages/platform/atoms/README.md
Testing guidance in the README ties atoms to the example platform app. To run atom e2e coverage locally, the documented flow starts in packages/platform/atoms, runs yarn dev-on, then runs yarn build to create a local atom build. The next step is to configure environment variables in packages/platform/examples/base/.env, including OAuth client and secret values such as NEXT_PUBLIC_X_CAL_ID, X_CAL_SECRET_KEY, VITE_BOOKER_EMBED_OAUTH_CLIENT_ID, and an ORGANIZATION_ID. This confirms that atom testing exercises realistic platform authentication and organization context rather than only isolated component rendering.
Sources: packages/platform/atoms/README.md
Implementation Guidance
When embedding atoms in an application, start by deciding which scheduling capability belongs in your product flow. If users need to manage their booking hours, use the availability entrypoint and decide whether the raw AvailabilitySettings component or AvailabilitySettingsPlatformWrapper is appropriate. If users need to manage calendar behavior, use CalendarSettingsPlatformWrapper. If the flow involves platform identity or OAuth state, wrap the UI with the provider exports from the cal-provider entrypoint. That sequence keeps application code aligned with the exported package contract.
Sources: packages/platform/atoms/cal-provider/index.ts, packages/platform/atoms/availability/index.ts, packages/platform/atoms/calendar-settings/index.ts
For maintainers, the practical rule is to preserve the public entrypoints. Internal files can be reorganized, but consumers are likely depending on the names exported by these index modules. When a change affects props, required provider context, OAuth assumptions, or supported framework versions, record it through changesets and ensure the changelog communicates whether the change is patch, minor, or major. For next steps, read the Booker atom page if you are embedding booking flows, the credential sync example page if you need a platform integration example, and the deployment pages if the embedded UI must talk to a self-hosted Cal.diy instance.