feat: Prerender booking link and reuse with headless router #20720

hariombalhara · 2025-04-16T06:50:06Z

What does this PR do?

Fixes #20807

Video Demo (if applicable):

https://www.loom.com/share/448e7ee236684cf1842c0b9a914e1e99

PR Changes Summary

📝 Documentation:
+338 -1 (339 total)
🧪 Tests:
+1305 -14 (1319 total)
💻 Code:
+1278 -195 (1473 total)

Added router preloading to improve embed performance and reduce loading times. This feature preloads booking pages while routing form responses are being processed, creating a much faster user experience.

^Screenshot is from README

How to use

Just fire prerender instruction when you think is a good time. e.g. when user starts typing in the form(example in routing-playground.html)

Technical Details

Created a new API endpoint at /api/router for headless router.
- Not using API v2 one because that requires API Key and this one is public. This is similar to /router except that fact that it accepts POST data and returns JSON vs an HTML page which is /router
- This new endpoint is only used when prerender instruction is used. This will change soon and will always be used later.
Heavily improved "connect" flow to pass on existing data to the pre-rendered iframe and decide when to do a full page reload and when to do "connect" and when to just re-open the modal.
Enhanced booker state tracking with more granular states: initializing, slotsPending, slotsLoading, slotsLoaded.
Replaced direct Next.js router push with declarative URL parameter management that ensures better and consistent results - Fixes scenario where react what silently ignoring the router.push because a render was already in progress.
Updated embed lifecycle to better handle prerendering and loading states.
Updated/Fixed insights seed to be able to use the Routing Form in the playground
Update Playground to have dedicated page to test router prerendering at /routing-playground.html

Changes in App

getSchedule or getTeamSchedule requests would have an additional parameter embedConnectVersion(mapped from 'cal.embedConnectVersion' query param of the page)
- The param is set only in embed mode and only when the iframe is reused. This is to ensure that we can force refresh of availablity(e.g. after a stale time configured in embed)
getSchedule or getTeamSchedule requests will not be sent if cal.skipSlotsFetch=true param is set on the page.

Documentation Improvements

Heavily updated README.md and created LIFECYCLE.md to have a superficial diagram of the entire flow. It was a pain to revisit various lifecycle events without proper documentation and took the time to create it.

See LIFECYCLE.md for full view

Tests

Added Modal transition Unit tests as most of the changes are through that flow.

Mandatory Tasks (DO NOT REMOVE)

I have self-reviewed the code (A decent size PR without self-review might be rejected).
I have updated the developer docs in /docs if this PR makes changes that would require a documentation change. If N/A, write N/A here and check the checkbox.
I confirm automated tests are in place that prove my fix is effective or that my feature works.

How should this be tested?

First run from packages/prisma, yarn seed-insights. So that appropriate state of the DB is there to be able to test the scenario that is configured in routing-playground
Open the routing-playground.html page for testing as follows
- Go to packages/embed-core and run yarn dev. It will open up embed playground which you could use to test other cases e.g. for regression testing
- Open the page http://localhost:3100/embed/routing-playground.html after that to be able to test this newly added feature
The playground describes the usecase that is being tested there. You could tweak the code in playground.js and routing-playground.html to test other scenarios like what happens when you don't preload.

You could test with different network speed(throttled), like what happens if user opens the modal before pre-rendering is complete
What happens if the user closes the modal and re-open

Followup

A 404 page like http://acme.cal.remote:3000/team1/team1-dvent-1 doesn't correctly set CalcomPageStatus to 404. Infact it serems that notFoundClient.tsx is not being rendered. Thus, iframe isn't able to correctly fire linkFailed event and thus, the modal box(on clicked again) doesn't retry on 404 error.

## What does this PR do?  - Fixes #XXXX (GitHub issue number) - Fixes CAL-XXXX (Linear issue number - should be visible at the bottom of the GitHub issue description) ## Visual Demo (For contributors especially) A visual demonstration is strongly recommended, for both the original and new change **(video / image - any one)**. #### Video Demo (if applicable): - Show screen recordings of the issue or feature. - Demonstrate how to reproduce the issue, the behavior before and after the change. #### Image Demo (if applicable): - Add side-by-side screenshots of the original and updated change. - Highlight any significant change(s). ## Mandatory Tasks (DO NOT REMOVE) - [ ] I have self-reviewed the code (A decent size PR without self-review might be rejected). - [ ] I have updated the developer docs in /docs if this PR makes changes that would require a [documentation change](https://cal.com/docs). If N/A, write N/A here and check the checkbox. - [ ] I confirm automated tests are in place that prove my fix is effective or that my feature works. ## How should this be tested?  - Are there environment variables that should be set? - What are the minimal test data to have? - What is expected (happy path) to have (input and output)? - Any other important info that could help to test that PR ## Checklist  - I haven't read the [contributing guide](https://github.com/calcom/cal.com/blob/main/CONTRIBUTING.md) - My code doesn't follow the style guidelines of this project - I haven't commented my code, particularly in hard-to-understand areas - I haven't checked if my changes generate no new warnings

vercel · 2025-04-16T06:50:09Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

2 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
cal	⬜️ Ignored (Inspect)	Visit Preview		May 1, 2025 9:36am
calcom-web-canary	⬜️ Ignored (Inspect)	Visit Preview		May 1, 2025 9:36am

github-actions · 2025-04-16T06:50:18Z

Hey there and thank you for opening this pull request! 👋🏼

We require pull request titles to follow the Conventional Commits specification and it looks like your proposed title needs to be adjusted.

Details:

No release type found in pull request title "Router-preloading". Add a prefix to indicate what kind of release this pull request corresponds to. For reference, see https://www.conventionalcommits.org/

Available types:
 - feat: A new feature
 - fix: A bug fix
 - docs: Documentation only changes
 - style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
 - refactor: A code change that neither fixes a bug nor adds a feature
 - perf: A code change that improves performance
 - test: Adding missing tests or correcting existing tests
 - build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
 - ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
 - chore: Other changes that don't modify src or test files
 - revert: Reverts a previous commit

hariombalhara · 2025-04-28T14:08:04Z

packages/embeds/embed-core/src/embed-iframe.ts

@@ -340,16 +416,37 @@ export const useEmbedType = () => {
  return state;
 };

-function unhideBody() {
+function makeBodyVisible() {


Better named

hariombalhara · 2025-04-29T04:01:13Z

packages/embeds/embed-core/src/embed.ts

@@ -36,13 +42,13 @@ customElements.define("cal-inline", Inline);

 declare module "*.css";
 type Namespace = string;
-type InitConfig = {


Renamed InitConfig -> CalConfig as "init" is just how it is set. This was ambiguous with initialConfig

hariombalhara · 2025-04-29T04:02:28Z

packages/embeds/embed-core/src/embed.ts

@@ -280,7 +290,23 @@ export class Cal {
    iframe.className = "cal-embed";
    iframe.name = `cal-embed=${this.namespace}`;
    iframe.title = `Book a call`;
-    const embedConfig = this.getInitConfig();
+
+    this.loadInIframe({ calLink, config, calOrigin, iframe });


Abstracted it out from createIframe as it now used separately as well.

hariombalhara and others added 12 commits April 10, 2025 09:16

mvp done

939e3e6

wip

53a3014

fix ts errors and other code improvements

4ad57e5

fix ts errors

f3fca1f

ensure mobile layout support

c18532a

Make skeleton responsive on screen resize

967ec30

refactor

97b1986

Add test for EmbedElement

42e8b94

Merge branch 'main' into embed-loader

6a34235

make skeleton closer to pixel perfect

48c7a6e

Address PR feedback

2b6239e

keithwillcode added core area: core, team members only enterprise area: enterprise, audit log, organisation, SAML, SSO labels Apr 16, 2025

vercel bot had a problem deploying to Preview – dev April 16, 2025 06:57 Failure

vercel bot had a problem deploying to Preview – api April 16, 2025 06:57 Failure

Base automatically changed from embed-loader to main April 16, 2025 13:40

Merge remote-tracking branch 'origin/main' into router-preloading

dbc437e

vercel bot had a problem deploying to Preview – dev April 17, 2025 06:04 Failure

vercel bot had a problem deploying to Preview – api April 17, 2025 06:05 Failure

vercel bot had a problem deploying to Preview – dev April 17, 2025 11:21 Failure

vercel bot had a problem deploying to Preview – api April 17, 2025 11:59 Failure

wip\

5014dec

hariombalhara force-pushed the router-preloading branch from f2be740 to 5014dec Compare April 18, 2025 05:35

vercel bot had a problem deploying to Preview – dev April 18, 2025 05:43 Failure

vercel bot had a problem deploying to Preview – api April 18, 2025 05:54 Failure

Merge remote-tracking branch 'origin/main' into router-preloading

901a492

github-actions bot added the embed area: embed, widget, react embed label Apr 22, 2025

hariombalhara commented Apr 28, 2025

View reviewed changes

vercel bot deployed to Preview – dev April 28, 2025 15:08 View deployment

vercel bot deployed to Preview – api April 28, 2025 15:32 View deployment

hariombalhara commented Apr 29, 2025

View reviewed changes

hariombalhara added 3 commits April 29, 2025 09:47

self-review-3

4be639a

Merge remote-tracking branch 'origin/main' into router-preloading

08e7197

Handle soft connect\

4b272ff

hariombalhara force-pushed the router-preloading branch from 9f8ff71 to 4b272ff Compare April 29, 2025 08:37

vercel bot deployed to Preview – dev April 29, 2025 09:06 View deployment

vercel bot deployed to Preview – api April 29, 2025 09:19 View deployment

hariombalhara added 2 commits April 29, 2025 18:52

Merge remote-tracking branch 'origin/main' into router-preloading

d07b8b4

Merge remote-tracking branch 'origin/main' into router-preloading

e621bdf

vercel bot deployed to Preview – api April 30, 2025 06:10 View deployment

vercel bot deployed to Preview – dev April 30, 2025 06:24 View deployment

vercel bot deployed to Preview – api April 30, 2025 07:59 View deployment

vercel bot deployed to Preview – dev April 30, 2025 08:12 View deployment

vercel bot deployed to Preview – api April 30, 2025 09:09 View deployment

vercel bot deployed to Preview – dev April 30, 2025 09:20 View deployment

hariombalhara force-pushed the router-preloading branch from 6b40bda to e621bdf Compare April 30, 2025 10:01

Update README and fix a bug with query parmas

eb4f6d4

vercel bot deployed to Preview – api May 1, 2025 04:53 View deployment

vercel bot deployed to Preview – dev May 1, 2025 05:06 View deployment

Merge branch 'main' into router-preloading

69ad37f

hariombalhara changed the title ~~feat: Prerender booking link and reuse with headlesss router~~ feat: Prerender booking link and reuse with headless router May 1, 2025

vercel bot deployed to Preview – dev May 1, 2025 09:12 View deployment

Add one more case in routing-html playground

fbcc795

keithwillcode added the consumer label May 1, 2025

vercel bot had a problem deploying to Preview – api May 1, 2025 09:53 Failure

vercel bot deployed to Preview – dev May 1, 2025 09:56 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Prerender booking link and reuse with headless router #20720

feat: Prerender booking link and reuse with headless router #20720

hariombalhara commented Apr 16, 2025 •

edited

Loading

vercel bot commented Apr 16, 2025 •

edited

Loading

github-actions bot commented Apr 16, 2025 •

edited

Loading

hariombalhara Apr 28, 2025

hariombalhara Apr 29, 2025

hariombalhara Apr 29, 2025

feat: Prerender booking link and reuse with headless router #20720

Are you sure you want to change the base?

feat: Prerender booking link and reuse with headless router #20720

Conversation

hariombalhara commented Apr 16, 2025 • edited Loading

What does this PR do?

Video Demo (if applicable):

PR Changes Summary

How to use

Technical Details

Changes in App

Documentation Improvements

Tests

Mandatory Tasks (DO NOT REMOVE)

How should this be tested?

Followup

vercel bot commented Apr 16, 2025 • edited Loading

github-actions bot commented Apr 16, 2025 • edited Loading

hariombalhara Apr 28, 2025

Choose a reason for hiding this comment

hariombalhara Apr 29, 2025

Choose a reason for hiding this comment

hariombalhara Apr 29, 2025

Choose a reason for hiding this comment

hariombalhara commented Apr 16, 2025 •

edited

Loading

vercel bot commented Apr 16, 2025 •

edited

Loading

github-actions bot commented Apr 16, 2025 •

edited

Loading