perf(front-component): fingerprint built-JS URLs by path for CDN caching (#22530)

**Stacked on #22523** — base is that branch, so the diff shows only this
commit. GitHub will retarget it to `main` automatically once #22523
merges.

Follows up on @FelixMalfait's question on #22523: move the
BuiltFrontComponent cache key from a query string into the path so it
plays well with Cloudflare cache rules.

## What

- URL: `/rest/front-components/:id?checksum=<c>` →
`/rest/front-components/:id/<c>.js` (`getFrontComponentUrl`).
- Route: the controller now accepts `[':frontComponentId',
':frontComponentId/:cacheKey']`. `:cacheKey` is a pure cache-buster the
server **ignores** — it still resolves by `:frontComponentId`, exactly
as the query param did.

## Why a path segment (not `:id-<checksum>.js`)

A path-based, extension-bearing URL is matched by Cloudflare's
**default** static-asset caching and by trivial `*.js` path cache rules,
and it's immune to any "ignore query string" cache setting that would
otherwise collapse `?checksum=` to one entry and serve stale JS.

I used a path **segment** (`/:id/:checksum.js`) rather than the literal
`:id-<checksum>.js` you sketched because the id is a **UUID — which
itself contains hyphens** — so a `-` separator is ambiguous to parse. A
segment is unambiguous and equally CDN-friendly (still ends in `.js`).

## Backward compatibility

The bare `:frontComponentId` route is kept, so URLs minted before this
deploys (query-string form, or in-flight pages) still resolve. It can be
dropped in a later release once no client mints the old form. No data
migration — the URL is computed at render time from `frontComponentId` +
`builtComponentChecksum`.

## ⚠️ Decision for you: this alone does not edge-cache — `private` vs
`public`

BFC is served behind `WorkspaceAuthGuard` and #22523 set its header to
**`private`**, max-age, immutable. `private` means shared caches
(Cloudflare) **won't** store it — so today this is browser-cache only,
and the path change just makes it *ready* for edge caching + clean cache
rules.

To actually get **edge** caching you'd additionally either flip BFC to
`public` or add a Cloudflare rule that overrides cache-control — which
means **accepting that the `id`+`checksum` URL becomes the access
capability** (a cache hit is served without re-checking origin auth).
The cache key is unique per component+build so there's no
cross-workspace mixup, but the built JS effectively becomes
public-by-URL (same posture PublicAsset already has). I've **left it
`private`** here; flipping to `public` is your call and can be a
one-line follow-up.

## Tests

- `getFrontComponentUrl` unit test: fingerprinted path when a checksum
is present, bare fallback otherwise.
- Integration test: the `/front-components/:id/:checksum.js` path serves
the built JS with `Content-Type: application/javascript` and
`Cache-Control: private, max-age=86400, immutable`. Existing bare-route
tests remain and still pass.

https://claude.ai/code/session_01AKwhTxYFDhWhCZ4b7sf35W

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

<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/22530?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. -->

packages/twenty-front/src/modules/front-components/utils/__tests__/getFrontComponentUrl.test.ts

@@ -0,0 +1,21 @@
+import { REST_API_BASE_URL } from '@/apollo/constant/rest-api-base-url';
+import { getFrontComponentUrl } from '@/front-components/utils/getFrontComponentUrl';
+
+describe('getFrontComponentUrl', () => {
+  it('builds a checksum-fingerprinted path URL when a checksum is provided', () => {
+    expect(
+      getFrontComponentUrl({
+        frontComponentId: 'front-component-id',
+        checksum: 'abc123',
+      }),
+    ).toBe(
+      `${REST_API_BASE_URL}/front-components/front-component-id/abc123.js`,
+    );
+  });
+
+  it('falls back to the bare id URL when no checksum is provided', () => {
+    expect(
+      getFrontComponentUrl({ frontComponentId: 'front-component-id' }),
+    ).toBe(`${REST_API_BASE_URL}/front-components/front-component-id`);
+  });
+});

packages/twenty-front/src/modules/front-components/utils/getFrontComponentUrl.ts

@@ -9,6 +9,6 @@ export const getFrontComponentUrl = ({
   checksum?: string;
 }): string => {
   return isDefined(checksum)
-    ? `${REST_API_BASE_URL}/front-components/${frontComponentId}?checksum=${checksum}`
+    ? `${REST_API_BASE_URL}/front-components/${frontComponentId}/${checksum}.js`
     : `${REST_API_BASE_URL}/front-components/${frontComponentId}`;
 };

packages/twenty-server/src/engine/metadata-modules/front-component/controllers/front-component.controller.ts

@@ -46,7 +46,7 @@ export class FrontComponentController {
 
   constructor(private readonly frontComponentService: FrontComponentService) {}
 
-  @Get(':frontComponentId')
+  @Get([':frontComponentId', ':frontComponentId/:cacheKey'])
   @UseGuards(NoPermissionGuard)
   async getBuiltJs(
     @Res() res: Response,

packages/twenty-server/test/integration/rest/suites/front-component-built-js.integration-spec.ts

@@ -55,6 +55,20 @@ describe('Front component built JS endpoint', () => {
       });
   });
 
+  it('should serve the built JS from the checksum-fingerprinted path with an immutable cache header', async () => {
+    await makeRestAPIRequest({
+      method: 'get',
+      path: `/front-components/${frontComponentId}/test-checksum-123.js`,
+      bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
+    })
+      .expect(200)
+      .expect('Content-Type', /application\/javascript/)
+      .expect('Cache-Control', 'private, max-age=86400, immutable')
+      .expect((res) => {
+        expect(res.text).toBe('dummy built component content');
+      });
+  });
+
   it('should return 404 for a non-existent front component ID', async () => {
     const nonExistentId = '00000000-0000-0000-0000-000000000000';