Embed Snippet
Purpose and Scope
The embed snippet package is the small website-facing entry point for Cal.diy embeds. Its job is intentionally narrower than the full embed runtime: it is vanilla JavaScript that can be installed on an external page, then fetches the core embed library so a Cal Link can be displayed as an embed. That separation lets site owners add a compact loader while the reusable embed behavior stays in the core package. When you are deciding where to make a change, treat the snippet as bootstrap and delivery code, not as the place where the complete embed interaction model lives.
Sources: packages/embeds/embed-snippet/README.md, packages/embeds/README.md
The package belongs to the embeds family, where the repository distinguishes core and snippet responsibilities. The core library is described as vanilla JavaScript that manages the embed, while the snippet is the installable vanilla JavaScript code that can be placed on any website and automatically fetches core. This distinction matters for debugging: if the script tag is not loading, inspect snippet build and hosting first; if the embed loads but modal, inline, routing, or iframe behavior is wrong, the issue is more likely in the core runtime or its consumers.
Sources: packages/embeds/README.md
Relevant Source Files
- packages/embeds/embed-snippet/README.md - Defines the package purpose, development command, generated ES module output, and the two supported installation styles for website usage.
- packages/embeds/embed-snippet/package.json - Declares the package name, distribution entry points, type declarations, build scripts, publish-time environment wrapper, dependency on the core embed package, and package metadata.
- packages/embeds/README.md - Explains the embeds package family, the relationship between core and snippet, release workflow, skeleton loader support, and broader embed runtime concepts that the snippet loads into the page.
System-to-Code Mapping
At the source level, the public package is named @calcom/embed-snippet and is versioned independently as an embed package. Its package metadata points CommonJS-style consumers at the UMD build and modern bundlers at the ES module build, while the published package includes the dist directory and exposes generated type declarations. The dependency on @calcom/embed-core is a workspace dependency, which reflects the architectural contract: the snippet is shipped as a package, but its main value is to acquire and hand off to the core library that implements the actual embed behavior.
Sources: packages/embeds/embed-snippet/package.json
| Concern | Source-backed package surface | Practical meaning |
|---|---|---|
| Package identity | @calcom/embed-snippet | Use this package when you need the website snippet loader rather than the full core implementation. |
| UMD output | ./dist/snippet.umd.js | Supports script-style distribution for environments that expect a bundled browser artifact. |
| ES module output | ./dist/snippet.es.js | Supports module script usage and modern build pipelines. |
| Type declarations | ./dist/index.d.ts | Generated declarations are emitted during the build and published with dist. |
| Runtime dependency | @calcom/embed-core | The snippet relies on the core package for embed management after loading. |
The repository README for the embeds folder also documents runtime concepts that explain why the snippet exists. The embed system initializes by loading an embed script on the parent page, creating a global Cal object, setting up custom elements such as modal, floating button, and inline variants, and using a namespace-based action manager for event handling. The snippet is the practical path by which an arbitrary website reaches that runtime. In other words, snippet installation is the first step in a larger parent-page and iframe communication system.
Sources: packages/embeds/README.md
Development and Build Flow
For local development, the documented command is yarn build inside the snippet package context. That build generates dist/snippet.es.js, and the README specifically warns contributors to rebuild the snippet before testing React embeds so those tests use the latest generated snippet artifact. This is an important workflow detail because React embed testing can appear stale when the source has changed but the generated snippet bundle has not. If a local embed test behaves like an older implementation, rebuilding the snippet should be one of the first checks.
Sources: packages/embeds/embed-snippet/README.md
The package build script removes the previous dist directory, runs Vite, and then emits TypeScript declarations into dist. The same package also defines type checking, CI-oriented type checking, linting against the source directory, and cleaning of local build artifacts. Its sideEffects flag is false, which signals that package consumers and bundlers may treat unused imports as removable. Although most website users encounter the snippet as a script, the package is still maintained like a normal TypeScript and Vite workspace package with build, lint, and declaration outputs.
Sources: packages/embeds/embed-snippet/package.json
Installation Styles
The snippet README describes two installation styles. The generated ES module bundle can be loaded with a module script tag, which is appropriate when the site can reference a hosted snippet artifact. Alternatively, the relevant suggested portion of the code can be copied directly into a normal script tag. The first style centralizes delivery around the built artifact, while the second style gives a site owner a self-contained copy-paste embed bootstrap. Both approaches serve the same goal: get the small loader onto the page so it can fetch core and display a Cal Link.
Sources: packages/embeds/embed-snippet/README.md
Choose the module script approach when you want the page to load a maintained artifact and when your environment allows external script module loading. Choose the copied script approach when a CMS, tag manager, or constrained website editor works better with pasted JavaScript. In both cases, avoid treating the snippet as the complete embed application. If you need to understand behavior after the loader runs, such as modal reuse, prerendering, preloading, skeleton loader support, or iframe URL updates, continue into the core and broader embeds documentation.
Sources: packages/embeds/README.md
Publishing and Release Signals
Publishing is coordinated with the rest of the embed package family. The embeds README describes a changeset-based process: create a changeset, version the selected embed packages, merge the reviewed pull request, then run the embed publishing command from the repository root. The README notes that the repository does not use the normal changeset publish command for these packages because workspace dependency prefix removal is not supported in that path. This means snippet releases should be considered alongside core releases, especially when the loader and runtime contract change together.
Sources: packages/embeds/README.md
The snippet package adds one more release signal through its prepack script. Before packing, it runs linting filtered to the snippet package and builds with publish environment values for the embed library URL and web app URL. That publish-time wrapper sets public embed and web application locations so the generated browser artifact is suitable for the intended hosted Cal embed environment. For maintainers, this means a successful local build is useful, but the release path also validates linting and builds under the environment expected for published embeds.
Sources: packages/embeds/embed-snippet/package.json
Runtime Boundaries and Next Steps
When debugging a website embed, start with the boundary that the snippet owns: whether the script is present, whether the built artifact is current, whether the chosen installation style matches the host page, and whether the snippet can fetch the core library. After that boundary, use the broader embeds documentation to reason about the core runtime. The skeleton loader matrix, routing prerendering flow, preloading versus prerendering distinction, and modal reopening optimization are documented at the embeds package level because they are properties of the overall embed system rather than the snippet package alone.
Sources: packages/embeds/README.md
Next, read the Embed Core page when you need runtime internals, the React Embed page when the snippet is being exercised through React-facing components, and the Embed Publishing and Loaders page when you are preparing a package release or investigating loader behavior. For most contributors, the safest sequence is to rebuild the snippet, reproduce the page-level loading behavior, then move inward to core only after confirming the bootstrap script and published artifact are correct.