From 2c5da39dc5beb38101ca335b5fea8b0cc4fdbe48 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Malfait?= <felix.malfait@gmail.com>
Date: Sat, 13 Jun 2026 17:53:09 +0200
Subject: [PATCH] perf(front): load Front chat during browser idle time
 (#21533)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Context

The Front support chat bundle
(`chat-assets.frontapp.com/v1/chat.bundle.js`, ~2.3s in a profiling
trace) was being injected only `500ms` after auth + client-config +
workspace-member resolved (`useInstantiateSupportChat.ts`). Because the
effect's gating conditions are themselves network-bound, that `500ms`
still lands the fetch + execute **inside the critical boot window**
(metadata load + first render), where the bundle competes for bandwidth
and main-thread time.

Two pre-existing issues:
- The `500ms` delay was too short to clear the critical window.
- The injected `<script>` already had `defer = true`, but `defer` is a
no-op on dynamically-inserted scripts (they're `async` by default), so
it contributed nothing.
- The `setTimeout` was never cleared, so an effect re-run within the
delay could schedule duplicate loads.

## Change

- Add a small `scheduleIdleCallback(callback, { timeout })` helper
(`src/utils/`) that runs work during a browser idle period via
`requestIdleCallback`, capped by `timeout`, and returns a canceller.
- Use it in `useInstantiateSupportChat` with a `2000ms` cap, and
**return the canceller from the effect** so a pending load is cancelled
on re-run/unmount.

### Why not gate on first interaction?
The launcher must appear proactively to surface an unread-reply badge,
so it has to load without user action. `requestIdleCallback` keeps it
proactive while yielding to the critical path.

### Safari / iOS
`requestIdleCallback` is disabled by default in all shipping Safari/iOS
versions (not Baseline). The helper falls back to a plain `setTimeout`
of the same duration there. Because `requestIdleCallback`'s `timeout` is
a *maximum* (it fires earlier at the first idle gap) while `setTimeout`
fires *at* that value, a single `2000ms` value gives:
- **Chrome/Firefox/Edge/Android**: loads at first idle, guaranteed
within 2s.
- **Safari/iOS**: loads at 2s (a fixed, longer delay — 4× the old
500ms).

Both paths are strictly better than the previous behavior.

## Testing

- `scheduleIdleCallback` unit tests (both the `requestIdleCallback` and
the fallback path, plus cancellation) — 4/4 pass.
- `npx nx typecheck twenty-front` — passes.
- `oxlint --type-aware` + `oxfmt` on changed files — clean.

https://claude.ai/code/session_013YXr5yNGFH1NYUe4ysmiEy

---
_Generated by [Claude
Code](https://claude.ai/code/session_013YXr5yNGFH1NYUe4ysmiEy)_

<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/21533?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->

---------

Co-authored-by: Claude <noreply@anthropic.com>
---
 .../hooks/useInstantiateSupportChat.ts        | 25 ++++--
 .../__tests__/scheduleIdleCallback.test.ts    | 86 +++++++++++++++++++
 .../src/utils/scheduleIdleCallback.ts         | 19 ++++
 3 files changed, 123 insertions(+), 7 deletions(-)
 create mode 100644 packages/twenty-front/src/utils/__tests__/scheduleIdleCallback.test.ts
 create mode 100644 packages/twenty-front/src/utils/scheduleIdleCallback.ts

diff --git a/packages/twenty-front/src/modules/support/hooks/useInstantiateSupportChat.ts b/packages/twenty-front/src/modules/support/hooks/useInstantiateSupportChat.ts
index a707bb4bec..b444842a44 100644
--- a/packages/twenty-front/src/modules/support/hooks/useInstantiateSupportChat.ts
+++ b/packages/twenty-front/src/modules/support/hooks/useInstantiateSupportChat.ts
@@ -6,6 +6,14 @@ import { isNonEmptyString } from '@sniptt/guards';
 import { useCallback, useEffect, useState } from 'react';
 import { isDefined } from 'twenty-shared/utils';
 import { type User, type WorkspaceMember } from '~/generated-metadata/graphql';
+import { scheduleIdleCallback } from '~/utils/scheduleIdleCallback';
+
+// Front chat is non-critical UI, so we load its ~2 s bundle during an idle
+// period rather than letting it compete with metadata loading and first
+// render during boot. The timeout caps the wait so the launcher (and any
+// unread-reply badge) still appears promptly, and it doubles as the plain
+// delay on browsers without requestIdleCallback (Safari/iOS).
+const FRONT_CHAT_IDLE_LOAD_TIMEOUT_MS = 2000;
 
 const insertScript = ({
   src,
@@ -77,13 +85,16 @@ export const useInstantiateSupportChat = () => {
       isDefined(currentWorkspaceMember) &&
       !isFrontChatLoaded
     ) {
-      setTimeout(() => {
-        configureFront(
-          supportChat.supportFrontChatId as string,
-          currentUser,
-          currentWorkspaceMember,
-        );
-      }, 500);
+      return scheduleIdleCallback(
+        () => {
+          configureFront(
+            supportChat.supportFrontChatId as string,
+            currentUser,
+            currentWorkspaceMember,
+          );
+        },
+        { timeout: FRONT_CHAT_IDLE_LOAD_TIMEOUT_MS },
+      );
     }
   }, [
     configureFront,
diff --git a/packages/twenty-front/src/utils/__tests__/scheduleIdleCallback.test.ts b/packages/twenty-front/src/utils/__tests__/scheduleIdleCallback.test.ts
new file mode 100644
index 0000000000..eac80678b5
--- /dev/null
+++ b/packages/twenty-front/src/utils/__tests__/scheduleIdleCallback.test.ts
@@ -0,0 +1,86 @@
+import { scheduleIdleCallback } from '~/utils/scheduleIdleCallback';
+
+type RequestIdleCallback = typeof window.requestIdleCallback;
+type CancelIdleCallback = typeof window.cancelIdleCallback;
+
+const setIdleCallbackApi = (
+  requestIdleCallback: RequestIdleCallback | undefined,
+  cancelIdleCallback: CancelIdleCallback | undefined,
+) => {
+  Object.defineProperty(window, 'requestIdleCallback', {
+    configurable: true,
+    writable: true,
+    value: requestIdleCallback,
+  });
+  Object.defineProperty(window, 'cancelIdleCallback', {
+    configurable: true,
+    writable: true,
+    value: cancelIdleCallback,
+  });
+};
+
+describe('scheduleIdleCallback', () => {
+  const originalRequestIdleCallback = window.requestIdleCallback;
+  const originalCancelIdleCallback = window.cancelIdleCallback;
+
+  afterEach(() => {
+    setIdleCallbackApi(originalRequestIdleCallback, originalCancelIdleCallback);
+    jest.useRealTimers();
+    jest.clearAllMocks();
+  });
+
+  describe('when requestIdleCallback is available', () => {
+    it('schedules the callback through requestIdleCallback with the timeout', () => {
+      const requestIdleCallbackMock = jest.fn(() => 42);
+      setIdleCallbackApi(requestIdleCallbackMock, jest.fn());
+
+      const callback = jest.fn();
+      scheduleIdleCallback(callback, { timeout: 2000 });
+
+      expect(requestIdleCallbackMock).toHaveBeenCalledWith(callback, {
+        timeout: 2000,
+      });
+    });
+
+    it('cancels the scheduled callback through cancelIdleCallback', () => {
+      const cancelIdleCallbackMock = jest.fn();
+      setIdleCallbackApi(
+        jest.fn(() => 42),
+        cancelIdleCallbackMock,
+      );
+
+      const cancel = scheduleIdleCallback(jest.fn(), { timeout: 2000 });
+      cancel();
+
+      expect(cancelIdleCallbackMock).toHaveBeenCalledWith(42);
+    });
+  });
+
+  describe('when requestIdleCallback is not available (e.g. Safari/iOS)', () => {
+    beforeEach(() => {
+      jest.useFakeTimers();
+      setIdleCallbackApi(undefined, undefined);
+    });
+
+    it('falls back to running the callback after the timeout', () => {
+      const callback = jest.fn();
+      scheduleIdleCallback(callback, { timeout: 2000 });
+
+      expect(callback).not.toHaveBeenCalled();
+
+      jest.advanceTimersByTime(2000);
+
+      expect(callback).toHaveBeenCalledTimes(1);
+    });
+
+    it('cancels the fallback timeout before it runs', () => {
+      const callback = jest.fn();
+      const cancel = scheduleIdleCallback(callback, { timeout: 2000 });
+
+      cancel();
+      jest.advanceTimersByTime(2000);
+
+      expect(callback).not.toHaveBeenCalled();
+    });
+  });
+});
diff --git a/packages/twenty-front/src/utils/scheduleIdleCallback.ts b/packages/twenty-front/src/utils/scheduleIdleCallback.ts
new file mode 100644
index 0000000000..93a9b924a0
--- /dev/null
+++ b/packages/twenty-front/src/utils/scheduleIdleCallback.ts
@@ -0,0 +1,19 @@
+import { isDefined } from 'twenty-shared/utils';
+
+export const scheduleIdleCallback = (
+  callback: () => void,
+  { timeout }: { timeout: number },
+): (() => void) => {
+  const requestIdleCallbackFn: typeof window.requestIdleCallback | undefined =
+    window.requestIdleCallback;
+
+  if (isDefined(requestIdleCallbackFn)) {
+    const handle = requestIdleCallbackFn(callback, { timeout });
+
+    return () => window.cancelIdleCallback(handle);
+  }
+
+  const handle = window.setTimeout(callback, timeout);
+
+  return () => window.clearTimeout(handle);
+};